@ai-setting/roy-agent-core 1.0.0

package/src/env/task/task-component.ts

@@ -0,0 +1,658 @@
+/**
+ * @fileoverview Task Component
+ * 
+ * Component for managing task lifecycle including:
+ * - Task CRUD operations
+ * - Operation record management
+ * - Tool registration
+ */
+
+import { BaseComponent, type ComponentConfig } from "../component";
+import {
+  TaskConfigSchema,
+  type TaskConfig,
+  type Task,
+  type TaskOperation,
+  type CreateTaskOptions,
+  type UpdateTaskOptions,
+  type ListTasksOptions,
+  type CreateOperationOptions,
+  type ListOperationsOptions,
+} from "./types";
+import { SQLiteTaskStore, type TaskStore, getDefaultTaskDbPath } from "./storage";
+import { createLogger } from "../log-trace/logger";
+import type { ToolComponent } from "../tool";
+import type { Tool } from "../tool/types";
+import * as taskTools from "./tools";
+import * as operationTools from "./tools/operation";
+import { createDelegateTool, createStopTool, BackgroundTaskManager } from "./delegate";
+import { TASK_CONFIG_REGISTRATION, TASK_DEFAULTS } from "./task-config-registration";
+import type { ConfigComponent } from "../../config/config-component";
+import { envKeyToConfigKey } from "../../config/env-key";
+
+// Hook 机制
+import { globalHookManager } from "../hook/global-hook-manager";
+import { TaskHookPoints, type TaskHookPoint } from "./hooks";
+import type {
+  TaskCreateContext,
+  TaskCreateResultContext,
+  TaskUpdateContext,
+  TaskUpdateResultContext,
+  TaskDeleteContext,
+  TaskDeleteResultContext,
+  TaskOperationCreateContext,
+  TaskOperationCreateResultContext,
+} from "./hooks/contexts";
+
+// Tag 服务
+import { DefaultTagService, type TagService } from "./tag-service";
+
+// Plugin
+import { TaskPlugin } from "./plugins";
+
+const logger = createLogger("task");
+
+/**
+ * TaskComponent 配置选项（通过 options 传递）
+ * 
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface TaskComponentOptions {
+  /** ConfigComponent 实例（必填） */
+  configComponent: ConfigComponent;
+  
+  /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+  configPath?: string;
+  
+  /** 环境变量前缀（可选，默认 "TASK"） */
+  envPrefix?: string;
+  
+  /** 直接传入的配置对象（可选，优先级最高） */
+  config?: Partial<TaskConfig>;
+}
+
+export class TaskComponent extends BaseComponent {
+  name = "task";
+  version = "1.0.0";
+  
+  private store!: TaskStore;
+  private config?: TaskConfig;
+  private toolComponent?: ToolComponent;
+  private backgroundTaskManager?: BackgroundTaskManager;
+  private configComponent?: ConfigComponent;
+  private tagService!: TagService;
+  private plugins: Map<string, TaskPlugin> = new Map();
+
+  constructor() {
+    super();
+  }
+
+  /**
+   * Initialize the component
+   * 
+   * 配置加载优先级（从高到低）：
+   * 1. Object - 直接传入的 config 对象
+   * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+   * 3. File - 配置文件（通过 configPath 指定）
+   */
+  async init(config?: ComponentConfig): Promise<void> {
+    // 调用基类 init，注入 env
+    await super.init(config);
+
+    // 从 options 获取 ConfigComponent
+    const options = config?.options as unknown as TaskComponentOptions | undefined;
+    if (!options?.configComponent) {
+      throw new Error("ConfigComponent is required for TaskComponent initialization");
+    }
+
+    this.configComponent = options.configComponent;
+    await this.registerConfig(options);
+
+    this.setStatus("running");
+    logger.info("[TaskComponent] Initialized");
+  }
+
+  /**
+   * 注册配置到 ConfigComponent
+   * 
+   * 配置加载顺序（优先级从低到高）：
+   * 1. Defaults - 默认值（最低）
+   * 2. FileSource - 从配置文件加载
+   * 3. EnvSource - 从环境变量加载
+   * 4. config 对象 - 直接传入的配置（最高）
+   */
+  private async registerConfig(options: TaskComponentOptions): Promise<void> {
+    const configComponent = this.configComponent;
+    if (!configComponent) return;
+
+    const { configPath, envPrefix, config } = options;
+    const prefix = envPrefix ?? "TASK";
+
+    // 1. 使用 registerComponent 注册配置结构（keys 和 sources，不含 defaults）
+    configComponent.registerComponent(TASK_CONFIG_REGISTRATION);
+
+    // 2. 注册 FileSource（如果提供了 configPath）
+    if (configPath) {
+      configComponent.registerSource({
+        type: "file",
+        relativePath: configPath,
+        optional: true,
+        watch: false
+      });
+    }
+
+    // 3. 注册 EnvSource
+    configComponent.registerSource({
+      type: "env",
+      envPrefix: prefix,
+      priority: 20,
+      watch: false
+    });
+    
+    // 4. 从 sources 加载配置（FileSource 和 EnvSource）
+    await configComponent.load("task");
+    
+    // 5. 后备方案：直接读取环境变量（确保所有环境变量都被处理）
+    for (const envKey of Object.keys(process.env)) {
+      const configKey = envKeyToConfigKey(envKey, prefix, "task");
+      if (!configKey) continue;
+      const value = process.env[envKey];
+      if (value !== undefined) {
+        await configComponent.set(configKey, value);
+      }
+    }
+
+    // 6. 设置默认值（只有当配置不存在时）
+    for (const [key, value] of Object.entries(TASK_DEFAULTS)) {
+      if (configComponent.get(key) === undefined) {
+        await configComponent.set(key, value);
+      }
+    }
+
+    // 6.5 特殊处理 dbPath 动态默认值（只有当配置不存在时）
+    if (configComponent.get("task.storage.dbPath") === undefined) {
+      await configComponent.set("task.storage.dbPath", getDefaultTaskDbPath());
+    }
+
+    // 7. 直接配置对象（最高优先级）
+    if (config) {
+      const flatConfig = this.flattenConfig(config);
+      for (const [key, value] of Object.entries(flatConfig)) {
+        await configComponent.set(key, value);
+      }
+    }
+
+    // 8. 注册配置热更新监听
+    this.registerConfigWatcher(configComponent);
+
+    // 9. 解析最终配置并初始化 store
+    await this.initStore();
+
+    // 10. 初始化 TagService
+    this.tagService = new DefaultTagService(this.store);
+  }
+
+  /**
+   * 根据配置初始化 store
+   */
+  private async initStore(): Promise<void> {
+    const configComponent = this.configComponent;
+    if (!configComponent) return;
+
+    const storageType = configComponent.get("task.storage.type") ?? "sqlite";
+    const dbPath = configComponent.get("task.storage.dbPath") as string | undefined;
+
+    if (storageType === "sqlite") {
+      this.store = new SQLiteTaskStore(dbPath);
+      logger.info(`[TaskComponent] Using SQLite storage: ${dbPath || "default path"}`);
+    } else {
+      this.store = new SQLiteTaskStore();
+      logger.info("[TaskComponent] Using SQLite storage (default)");
+    }
+  }
+
+  /**
+   * 将配置对象展平为点号路径
+   */
+  private flattenConfig(
+    obj: Record<string, unknown>,
+    prefix = "task"
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = `${prefix}.${key}`;
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        Object.assign(
+          result,
+          this.flattenConfig(value as Record<string, unknown>, fullKey)
+        );
+      } else {
+        result[fullKey] = value;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 注册配置热更新监听
+   */
+  private registerConfigWatcher(configComponent: ConfigComponent): void {
+    if (typeof configComponent.watch !== "function") {
+      return;
+    }
+    
+    this.configWatcher = configComponent.watch("task.*", (event) => {
+      this.onConfigChange(event);
+    });
+  }
+
+  /**
+   * 处理配置变更
+   */
+  protected onConfigChange(event: { key: string; oldValue?: unknown; newValue?: unknown }): void {
+    logger.info(`[TaskComponent] Config changed: ${event.key}`, {
+      oldValue: event.oldValue,
+      newValue: event.newValue
+    });
+    // 如果 storage 配置变更，需要重新初始化 store
+    if (event.key === "task.storage.type" || event.key === "task.storage.dbPath") {
+      this.initStore();
+    }
+  }
+
+  /** 配置变更 watcher 清理函数 */
+  private configWatcher?: () => void;
+
+  /**
+   * Start the component - register tools
+   */
+  async start(): Promise<void> {
+    await super.start();
+    
+    // Create BackgroundTaskManager
+    this.backgroundTaskManager = new BackgroundTaskManager(this.env);
+    
+    // Get ToolComponent and register tools
+    this.toolComponent = this.env?.getComponent("tool");
+    if (this.toolComponent) {
+      await this.registerTools();
+    } else {
+      logger.warn("[TaskComponent] ToolComponent not found, skipping tool registration");
+    }
+  }
+
+  /**
+   * Stop the component
+   */
+  async stop(): Promise<void> {
+    // 清理配置 watcher
+    if (this.configWatcher) {
+      this.configWatcher();
+      this.configWatcher = undefined;
+    }
+
+    // Dispose BackgroundTaskManager to clean up timers and prevent process hanging
+    if (this.backgroundTaskManager) {
+      this.backgroundTaskManager.dispose();
+    }
+    if (this.store) {
+      await this.store.close();
+    }
+    await super.stop();
+  }
+
+  // ========================================================================
+  // Tool Registration
+  // ========================================================================
+  
+  /**
+   * Register task tools to ToolComponent
+   */
+  private async registerTools(): Promise<void> {
+    if (!this.toolComponent) return;
+
+    // Task tools
+    const taskToolsList: Tool[] = [
+      taskTools.createTaskTool(this),
+      taskTools.getTaskTool(this),
+      taskTools.listTasksTool(this),
+      taskTools.updateTaskTool(this),
+      taskTools.deleteTaskTool(this),
+      taskTools.completeTaskTool(this),
+    ];
+
+    // Operation tools
+    const operationToolsList: Tool[] = [
+      operationTools.createOperationTool(this),
+      operationTools.getOperationTool(this),
+      operationTools.listOperationsTool(this),
+      operationTools.updateOperationTool(this),
+      operationTools.deleteOperationTool(this),
+    ];
+
+    // Delegate tools (with background task manager)
+    const delegateTools: Tool[] = [
+      createDelegateTool(this),
+      createStopTool(this.backgroundTaskManager!),
+    ];
+
+    // Register all tools
+    for (const tool of [...taskToolsList, ...operationToolsList, ...delegateTools]) {
+      this.toolComponent.register(tool);
+      logger.info(`[TaskComponent] Registered tool: ${tool.name}`);
+    }
+  }
+
+  // ========================================================================
+  // Hook 执行
+  // ========================================================================
+
+  /**
+   * 执行 Hook
+   */
+  private async executeHook<P extends TaskHookPoint>(
+    hookPoint: P,
+    data: any,
+    metadata: Record<string, unknown> = {}
+  ): Promise<void> {
+    const ctx = {
+      component: { name: this.name, version: this.version },
+      data,
+      metadata,
+      phase: hookPoint.includes("before") ? "before" as const : "after" as const,
+      hookPoint,
+    };
+    
+    await globalHookManager.execute(hookPoint, ctx, metadata);
+  }
+
+  // ========================================================================
+  // Task CRUD
+  // ========================================================================
+  
+  /**
+   * Create a new task
+   */
+  async createTask(options: CreateTaskOptions): Promise<Task> {
+    const sessionId = options.sessionId;
+    
+    // 1. beforeCreate Hook
+    const createCtx: TaskCreateContext = {
+      options: { ...options },
+      sessionId,
+      tagService: this.tagService,
+    };
+    
+    await this.executeHook(TaskHookPoints.BEFORE_CREATE, createCtx);
+    
+    // 2. 实际创建
+    const task = await this.store.createTask(createCtx.options);
+    
+    // 3. Auto-create operation record for task creation
+    await this.store.createOperation({
+      taskId: task.id,
+      sessionId,
+      actionType: "create",
+      actionTitle: `Task created: ${task.title}`,
+      actionDescription: task.description || "",
+    });
+    
+    // 4. afterCreate Hook
+    const resultCtx: TaskCreateResultContext = {
+      task,
+      sessionId,
+      tagService: this.tagService,
+    };
+    await this.executeHook(TaskHookPoints.AFTER_CREATE, resultCtx);
+    
+    logger.info(`[TaskComponent] Task created: ${task.id} - ${task.title}`);
+    return task;
+  }
+  
+  /**
+   * Get task by ID
+   */
+  async getTask(id: number): Promise<Task | undefined> {
+    return this.store.getTask(id);
+  }
+  
+  /**
+   * Get task with operations
+   */
+  async getTaskWithOperations(id: number): Promise<{ task: Task; operations: TaskOperation[] } | undefined> {
+    const task = await this.store.getTask(id);
+    if (!task) return undefined;
+    
+    const operations = await this.store.listOperations({ taskId: id });
+    return { task, operations };
+  }
+  
+  /**
+   * Update task
+   */
+  async updateTask(id: number, options: UpdateTaskOptions): Promise<Task | undefined> {
+    // 1. beforeUpdate Hook
+    const updateCtx: TaskUpdateContext = {
+      id,
+      options: { ...options },
+      tagService: this.tagService,
+    };
+    await this.executeHook(TaskHookPoints.BEFORE_UPDATE, updateCtx);
+    
+    // 2. 实际更新
+    const task = await this.store.updateTask(id, updateCtx.options);
+    
+    if (task) {
+      // 3. afterUpdate Hook
+      const resultCtx: TaskUpdateResultContext = {
+        task,
+        changes: options,
+        tagService: this.tagService,
+      };
+      await this.executeHook(TaskHookPoints.AFTER_UPDATE, resultCtx);
+      logger.info(`[TaskComponent] Task updated: ${id}`);
+    }
+    return task;
+  }
+  
+  /**
+   * Delete task
+   */
+  async deleteTask(id: number): Promise<boolean> {
+    // 1. beforeDelete Hook
+    const deleteCtx: TaskDeleteContext = { id };
+    await this.executeHook(TaskHookPoints.BEFORE_DELETE, deleteCtx);
+    
+    // 2. 实际删除
+    const result = await this.store.deleteTask(id);
+    
+    // 3. afterDelete Hook
+    const resultCtx: TaskDeleteResultContext = { id, deleted: result };
+    await this.executeHook(TaskHookPoints.AFTER_DELETE, resultCtx);
+    
+    if (result) {
+      logger.info(`[TaskComponent] Task deleted: ${id}`);
+    }
+    return result;
+  }
+  
+  /**
+   * List tasks
+   */
+  async listTasks(options?: ListTasksOptions): Promise<Task[]> {
+    return this.store.listTasks(options);
+  }
+  
+  /**
+   * Complete task
+   */
+  async completeTask(id: number, sessionId: string): Promise<Task | undefined> {
+    const task = await this.store.updateTask(id, {
+      status: "completed",
+      progress: 100,
+    });
+    
+    if (task) {
+      // 调用 this.createOperation 以触发 OPERATION_AFTER_CREATE hook
+      await this.createOperation({
+        taskId: id,
+        sessionId,
+        actionType: "completed",
+        actionTitle: "Task completed",
+      });
+      logger.info(`[TaskComponent] Task completed: ${id}`);
+    }
+    
+    return task;
+  }
+
+  // ========================================================================
+  // Operation CRUD
+  // ========================================================================
+  
+  /**
+   * Create operation record
+   */
+  async createOperation(options: CreateOperationOptions): Promise<TaskOperation> {
+    // 1. beforeCreate Hook
+    const createCtx: TaskOperationCreateContext = {
+      options: { ...options },
+    };
+    await this.executeHook(TaskHookPoints.OPERATION_BEFORE_CREATE, createCtx);
+    
+    // 2. 实际创建
+    const op = await this.store.createOperation(createCtx.options);
+    
+    // 3. afterCreate Hook
+    const resultCtx: TaskOperationCreateResultContext = { operation: op };
+    await this.executeHook(TaskHookPoints.OPERATION_AFTER_CREATE, resultCtx);
+    
+    logger.info(`[TaskComponent] Operation created: ${op.id} for task ${op.taskId}`);
+    return op;
+  }
+  
+  /**
+   * Get operation by ID
+   */
+  async getOperation(id: number): Promise<TaskOperation | undefined> {
+    return this.store.getOperation(id);
+  }
+  
+  /**
+   * Update operation
+   */
+  async updateOperation(id: number, updates: { actionTitle?: string; actionDescription?: string }): Promise<TaskOperation | undefined> {
+    return this.store.updateOperation(id, updates);
+  }
+  
+  /**
+   * Delete operation
+   */
+  async deleteOperation(id: number): Promise<boolean> {
+    return this.store.deleteOperation(id);
+  }
+  
+  /**
+   * List operations for a task
+   */
+  async listOperations(options: ListOperationsOptions): Promise<TaskOperation[]> {
+    return this.store.listOperations(options);
+  }
+
+  // ========================================================================
+  // Plugin Management
+  // ========================================================================
+
+  /**
+   * 获取 TagService
+   */
+  getTagService(): TagService {
+    return this.tagService;
+  }
+
+  /**
+   * 注册 Plugin
+   */
+  registerPlugin(plugin: TaskPlugin): void {
+    this.plugins.set(plugin.name, plugin);
+    
+    // 注入组件引用
+    const llmComponent = this.env?.getComponent("llm");
+    
+    plugin.setComponents?.(llmComponent as any, this as any);
+    
+    // === 自动注册依赖的 Agents ===
+    const getRequiredAgents = (plugin.constructor as any).getRequiredAgents;
+    if (typeof getRequiredAgents === 'function') {
+      const agentComponent = this.env?.getComponent("agent");
+      if (agentComponent) {
+        try {
+          const agents = getRequiredAgents();
+          for (const agentConfig of agents) {
+            (agentComponent as any).registerAgent(agentConfig.name, agentConfig);
+          }
+        } catch (err) {
+          logger.warn(`Failed to auto-register agents for plugin ${plugin.name}: ${err}`);
+        }
+      }
+    }
+    // === 自动注册结束 ===
+    
+    // 注册 Hook 到 globalHookManager
+    for (const hook of plugin.hooks) {
+      const pluginConfig = (plugin as any).config;
+      const priority = hook.priority ?? pluginConfig?.priority ?? 0;
+      const hookName = `${this.name}:${plugin.name}:${hook.point}`;
+      
+      const pluginRef = plugin; // Capture plugin reference
+      globalHookManager.register(hook.point, {
+        name: hookName,
+        priority,
+        execute: async (ctx: any) => {
+          // 直接传递 ctx.data（这是 Component 传入的 TaskCreateContext 等）
+          // 同时注入 hookPoint 和 component 信息
+          const pluginCtx = {
+            component: ctx.component,
+            data: ctx.data,  // 直接传递 Component 的数据对象
+            metadata: ctx.metadata,
+            phase: ctx.phase,
+            hookPoint: hook.point,
+          };
+          
+          await pluginRef.execute(pluginCtx);
+        },
+      });
+    }
+    
+    logger.info(`[TaskComponent] Registered plugin: ${plugin.name}`, {
+      hooks: plugin.hooks.map(h => h.point)
+    });
+  }
+
+  /**
+   * 注销 Plugin
+   */
+  unregisterPlugin(name: string): boolean {
+    const plugin = this.plugins.get(name);
+    if (!plugin) return false;
+    
+    // 从 globalHookManager 移除
+    for (const hook of plugin.hooks) {
+      globalHookManager.unregister(hook.point, `${this.name}:${name}`);
+    }
+    
+    this.plugins.delete(name);
+    logger.info(`[TaskComponent] Unregistered plugin: ${name}`);
+    return true;
+  }
+
+  /**
+   * 获取所有注册的 Plugin
+   */
+  listPlugins(): TaskPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+}

package/src/env/task/task-config-registration.test.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Task Component 配置注册测试
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { ConfigComponent } from "../../config/config-component";
+import { TASK_CONFIG_REGISTRATION, TASK_DEFAULTS } from "./task-config-registration";
+
+describe("Task Config Registration", () => {
+  let configComponent: ConfigComponent;
+
+  beforeEach(() => {
+    configComponent = new ConfigComponent();
+  });
+
+  describe("TASK_CONFIG_REGISTRATION", () => {
+    it("应该包含正确的 name", () => {
+      expect(TASK_CONFIG_REGISTRATION.name).toBe("task");
+    });
+
+    it("应该包含 env source 配置", () => {
+      const envSource = TASK_CONFIG_REGISTRATION.sources.find(
+        (s) => s.type === "env"
+      );
+      expect(envSource).toBeDefined();
+      expect(envSource?.envPrefix).toBe("TASK");
+      expect(envSource?.priority).toBe(20);
+    });
+
+    it("应该包含所有配置 keys", () => {
+      const keys = TASK_CONFIG_REGISTRATION.keys;
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "task.storage.type" })
+      );
+      expect(keys).toContainEqual(
+        expect.objectContaining({ key: "task.storage.dbPath" })
+      );
+    });
+  });
+
+  describe("TASK_DEFAULTS", () => {
+    it("应该包含 storage.type 默认值（完整格式）", () => {
+      expect(TASK_DEFAULTS["task.storage.type"]).toBe("sqlite");
+    });
+
+    it("应该导出正确的默认值（完整格式）", () => {
+      expect("task.storage.type" in TASK_DEFAULTS).toBe(true);
+    });
+  });
+
+  describe("配置注册到 ConfigComponent", () => {
+    it("应该能够注册 TASK_CONFIG_REGISTRATION", () => {
+      configComponent.registerComponent(TASK_CONFIG_REGISTRATION);
+      expect(() => configComponent.registerComponent(TASK_CONFIG_REGISTRATION)).not.toThrow();
+    });
+  });
+});