@ai-setting/roy-agent-cli 1.0.0

package/src/plugin/registry.ts

@@ -0,0 +1,272 @@
+/**
+ * @fileoverview Plugin Registry
+ *
+ * 插件注册表，管理所有已注册的插件
+ */
+
+import type {
+  RoyCliPlugin,
+  PluginCommandDefinition,
+  PluginComponentDefinition,
+  ComponentPluginDefinition,
+  ComponentPluginInstance,
+} from "./types";
+
+// ============================================================================
+// Built-in Plugins
+// ============================================================================
+
+/**
+ * Task-Tag Plugin - 内置组件插件
+ */
+const taskTagPlugin: RoyCliPlugin = {
+  info: {
+    name: "task-tag",
+    version: "1.0.0",
+    description: "Intelligent tag suggestion and similar task experience injection",
+  },
+  getComponentPlugins() {
+    return [{
+      name: "task-tag",
+      targetComponent: "task",
+      factory: async () => {
+        // 动态导入避免循环依赖
+        const { TaskTagPlugin } = await import("@ai-setting/roy-agent-core");
+        return new TaskTagPlugin();
+      },
+    }];
+  },
+};
+
+/**
+ * 内置插件列表
+ */
+const BUILTIN_PLUGINS: RoyCliPlugin[] = [
+  taskTagPlugin,
+];
+
+// ============================================================================
+// Plugin Registry
+// ============================================================================
+
+/**
+ * 插件注册表
+ *
+ * 管理插件的注册、获取和遍历
+ */
+export class PluginRegistry {
+  private plugins = new Map<string, RoyCliPlugin>();
+
+  constructor() {
+    // 自动注册内置插件
+    for (const plugin of BUILTIN_PLUGINS) {
+      this.registerBuiltin(plugin);
+    }
+  }
+
+  /**
+   * 注册插件
+   *
+   * @param plugin - 要注册的插件
+   * @throws 如果插件名称已存在则抛出错误
+   */
+  register(plugin: RoyCliPlugin): void {
+    if (this.plugins.has(plugin.info.name)) {
+      throw new Error(
+        `Plugin "${plugin.info.name}" is already registered`
+      );
+    }
+    this.plugins.set(plugin.info.name, plugin);
+  }
+
+  /**
+   * 注册内置插件（不抛错）
+   */
+  private registerBuiltin(plugin: RoyCliPlugin): void {
+    if (!this.plugins.has(plugin.info.name)) {
+      this.plugins.set(plugin.info.name, plugin);
+    }
+  }
+
+  /**
+   * 注销插件
+   *
+   * @param name - 插件名称
+   */
+  unregister(name: string): void {
+    this.plugins.delete(name);
+  }
+
+  /**
+   * 获取插件
+   *
+   * @param name - 插件名称
+   * @returns 插件实例，如果不存在则返回 undefined
+   */
+  get(name: string): RoyCliPlugin | undefined {
+    return this.plugins.get(name);
+  }
+
+  /**
+   * 检查插件是否已注册
+   *
+   * @param name - 插件名称
+   */
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+
+  /**
+   * 获取所有已注册插件
+   *
+   * @returns 按优先级降序排列的插件数组
+   */
+  getAll(): RoyCliPlugin[] {
+    return Array.from(this.plugins.values()).sort(
+      (a, b) => (b.priority ?? 0) - (a.priority ?? 0)
+    );
+  }
+
+  /**
+   * 获取所有插件数量
+   */
+  get size(): number {
+    return this.plugins.size;
+  }
+
+  /**
+   * 获取所有插件提供的命令
+   *
+   * @returns 所有插件命令定义数组
+   */
+  getAllCommands(): PluginCommandDefinition[] {
+    const commands: PluginCommandDefinition[] = [];
+    for (const plugin of this.getAll()) {
+      commands.push(...(plugin.getCommands?.() ?? []));
+    }
+    return commands;
+  }
+
+  /**
+   * 获取所有插件提供的组件
+   *
+   * @returns 所有插件组件定义数组
+   */
+  getAllComponents(): PluginComponentDefinition[] {
+    const components: PluginComponentDefinition[] = [];
+    for (const plugin of this.getAll()) {
+      components.push(...(plugin.getComponents?.() ?? []));
+    }
+    return components;
+  }
+
+  /**
+   * 获取所有插件提供的组件插件
+   *
+   * @returns 所有组件插件定义数组
+   */
+  getAllComponentPlugins(): ComponentPluginDefinition[] {
+    const componentPlugins: ComponentPluginDefinition[] = [];
+    for (const plugin of this.getAll()) {
+      componentPlugins.push(...(plugin.getComponentPlugins?.() ?? []));
+    }
+    return componentPlugins;
+  }
+
+  /**
+   * 根据名称获取组件插件定义
+   *
+   * @param name - 组件插件名称
+   * @returns 组件插件定义，如果不存在则返回 undefined
+   */
+  getComponentPlugin(name: string): ComponentPluginDefinition | undefined {
+    for (const plugin of this.getAll()) {
+      const componentPlugins = plugin.getComponentPlugins?.() ?? [];
+      for (const cp of componentPlugins) {
+        if (cp.name === name) {
+          return cp;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * 遍历所有插件及其组件定义
+   *
+   * @yields 插件和其组件定义
+   */
+  *getPluginComponents(): Generator<{
+    plugin: RoyCliPlugin;
+    definition: PluginComponentDefinition;
+  }> {
+    for (const plugin of this.getAll()) {
+      for (const definition of plugin.getComponents?.() ?? []) {
+        yield { plugin, definition };
+      }
+    }
+  }
+
+  /**
+   * 清空所有已注册的插件（保留内置插件）
+   */
+  clear(): void {
+    // 先移除所有非内置插件
+    for (const name of this.plugins.keys()) {
+      const plugin = this.plugins.get(name)!;
+      if (!BUILTIN_PLUGINS.some(p => p.info.name === name)) {
+        this.plugins.delete(name);
+      }
+    }
+  }
+
+  /**
+   * 执行所有插件的生命周期钩子
+   *
+   * @param phase - 生命周期阶段
+   * @param env - Environment 实例
+   */
+  async executeLifecycleHooks(
+    phase: "beforeInit" | "afterInit",
+    env: import("@ai-setting/roy-agent-core").BaseEnvironment
+  ): Promise<void> {
+    const hookName =
+      phase === "beforeInit" ? "onBeforeInit" : "onAfterInit";
+
+    for (const plugin of this.getAll()) {
+      const hook = plugin[hookName];
+      if (hook) {
+        try {
+          await hook({ env });
+        } catch (err) {
+          console.warn(
+            `[roy] Plugin "${plugin.info.name}" ${hookName} failed:`,
+            err
+          );
+        }
+      }
+    }
+  }
+}
+
+/**
+ * 全局插件注册表实例
+ */
+export const globalPluginRegistry = new PluginRegistry();
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * 加载内置组件插件
+ */
+export async function loadBuiltinComponentPlugin(
+  name: string
+): Promise<ComponentPluginInstance | null> {
+  const definition = globalPluginRegistry.getComponentPlugin(name);
+  if (!definition) {
+    return null;
+  }
+  return definition.factory();
+}

package/src/plugin/types.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Roy CLI Plugin Types
+ *
+ * 定义插件协议，供插件开发者使用
+ */
+
+import type { CommandModule } from "yargs";
+import type { Component } from "@ai-setting/roy-agent-core";
+
+/**
+ * 插件元信息
+ */
+export interface PluginInfo {
+  /** 插件名称 */
+  name: string;
+
+  /** 插件版本 */
+  version: string;
+
+  /** 插件描述 */
+  description?: string;
+}
+
+/**
+ * 插件组件定义
+ */
+export interface PluginComponentDefinition {
+  /** 组件名称 */
+  name: string;
+
+  /** 组件类构造函数 */
+  component: new (...args: any[]) => Component;
+
+  /** 组件配置选项 */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * CLI 命令定义
+ */
+export interface PluginCommandDefinition {
+  /** yargs CommandModule */
+  command: CommandModule;
+
+  /** 是否为默认命令 */
+  default?: boolean;
+}
+
+/**
+ * 环境钩子上下文
+ */
+export interface PluginEnvironmentContext {
+  /** Environment 实例 */
+  env: import("@ai-setting/roy-agent-core").BaseEnvironment;
+}
+
+/**
+ * 组件插件实例
+ */
+export interface ComponentPluginInstance {
+  /** 插件名称 */
+  name: string;
+
+  /** Hook 定义 */
+  hooks: Array<{ point: string; priority?: number }>;
+
+  /** 执行 Hook */
+  execute(ctx: unknown): void | Promise<void>;
+
+  /** 设置依赖组件 */
+  setComponents?(...components: unknown[]): void;
+}
+
+/**
+ * 组件插件定义
+ */
+export interface ComponentPluginDefinition {
+  /** 插件名称 */
+  name: string;
+
+  /** 目标组件名称 (如 "task", "memory") */
+  targetComponent: string;
+
+  /** 插件实例工厂函数 */
+  factory: () => Promise<ComponentPluginInstance>;
+}
+
+/**
+ * Roy CLI 插件接口
+ *
+ * 用于扩展 roy-cli 的功能：
+ * - 注册 CLI 命令
+ * - 注册 Environment 组件
+ * - 注册组件插件（注入到现有组件）
+ * - 钩入 Environment 生命周期
+ *
+ * @example
+ * ```typescript
+ * export const myPlugin: RoyCliPlugin = {
+ *   info: {
+ *     name: "my-plugin",
+ *     version: "1.0.0",
+ *     description: "My custom plugin"
+ *   },
+ *
+ *   getCommands() {
+ *     return [{ command: MyCommand }];
+ *   },
+ *
+ *   getComponents() {
+ *     return [{ name: "my-component", component: MyComponent }];
+ *   },
+ *
+ *   getComponentPlugins() {
+ *     return [{
+ *       name: "my-component-plugin",
+ *       targetComponent: "task",
+ *       factory: async () => new MyComponentPlugin(),
+ *     }];
+ *   }
+ * };
+ * ```
+ */
+export interface RoyCliPlugin {
+  /** 插件元信息 */
+  readonly info: PluginInfo;
+
+  /**
+   * 获取插件提供的 CLI 命令
+   */
+  getCommands?(): PluginCommandDefinition[];
+
+  /**
+   * 获取插件提供的组件
+   */
+  getComponents?(): PluginComponentDefinition[];
+
+  /**
+   * 获取插件提供的组件插件
+   *
+   * 组件插件是注入到现有组件（如 TaskComponent）中的插件，
+   * 通过 Hook 机制扩展组件功能
+   */
+  getComponentPlugins?(): ComponentPluginDefinition[];
+
+  /**
+   * Environment 初始化前调用
+   *
+   * @param ctx - 环境上下文
+   */
+  onBeforeInit?(ctx: PluginEnvironmentContext): void | Promise<void>;
+
+  /**
+   * Environment 初始化后调用
+   *
+   * @param ctx - 环境上下文
+   */
+  onAfterInit?(ctx: PluginEnvironmentContext): void | Promise<void>;
+
+  /**
+   * 优先级，数字越大越先加载
+   * 默认值为 0
+   */
+  priority?: number;
+}