@ai-setting/roy-agent-core 1.0.0

package/src/env/task/hooks/contexts.ts

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Task Hook Contexts - Hook 上下文类型定义
+ */
+
+import type { CreateTaskOptions, UpdateTaskOptions, Task, TaskOperation, CreateOperationOptions } from "../types";
+import type { TagService } from "../tag-service";
+import type { DelegateToolResult } from "../delegate/delegate-tool";
+
+// ========================================================================
+// Task CRUD Contexts
+// ========================================================================
+
+/**
+ * Task Create Hook Context
+ * 
+ * 触发时机：createTask() 方法调用后，实际创建前
+ * 
+ * Plugin 可直接修改 options 来干预创建行为
+ */
+export interface TaskCreateContext {
+  /** 创建选项（Plugin 可直接修改） */
+  options: CreateTaskOptions;
+  /** Session ID */
+  sessionId: string;
+  /** Tag 服务引用 */
+  tagService: TagService;
+}
+
+/**
+ * Task Create Result Hook Context
+ * 
+ * 触发时机：Task 创建成功后
+ * 
+ * Plugin 可在此 Hook 中：
+ * - 同步 Tag 到数据库
+ * - 创建关联资源
+ * - 发送通知
+ */
+export interface TaskCreateResultContext {
+  /** 创建后的 Task（已包含生成 ID） */
+  task: Task;
+  /** Session ID */
+  sessionId: string;
+  /** Tag 服务引用 */
+  tagService: TagService;
+}
+
+/**
+ * Task Update Hook Context
+ * 
+ * 触发时机：updateTask() 方法调用后，实际更新前
+ * 
+ * Plugin 可直接修改 options 来干预更新行为
+ */
+export interface TaskUpdateContext {
+  /** Task ID */
+  id: number;
+  /** 更新选项（Plugin 可直接修改） */
+  options: UpdateTaskOptions;
+  /** Tag 服务引用 */
+  tagService: TagService;
+}
+
+/**
+ * Task Update Result Hook Context
+ * 
+ * 触发时机：Task 更新成功后
+ */
+export interface TaskUpdateResultContext {
+  /** 更新后的 Task */
+  task: Task;
+  /** 变更的字段 */
+  changes: Partial<UpdateTaskOptions>;
+  /** Tag 服务引用 */
+  tagService: TagService;
+}
+
+/**
+ * Task Delete Hook Context
+ * 
+ * 触发时机：deleteTask() 方法调用后，实际删除前
+ */
+export interface TaskDeleteContext {
+  /** Task ID */
+  id: number;
+}
+
+/**
+ * Task Delete Result Hook Context
+ * 
+ * 触发时机：Task 删除成功后
+ * 
+ * 注意：删除成功后无法获取 Task 的详细信息
+ */
+export interface TaskDeleteResultContext {
+  /** 被删除的 Task ID */
+  id: number;
+  /** 是否成功删除 */
+  deleted: boolean;
+}
+
+// ========================================================================
+// Delegate Contexts
+// ========================================================================
+
+/**
+ * Delegate Before Hook Context
+ * 
+ * 触发时机：delegate_task 工具执行前
+ * 
+ * Plugin 可直接修改 prompt 来注入上下文
+ */
+export interface TaskDelegateContext {
+  /** 关联的 Task ID */
+  taskId?: number;
+  /** 执行提示词（Plugin 可直接修改以注入上下文） */
+  prompt: string;
+  /** SubAgent 类型 */
+  subagentType: string;
+  /** 是否后台执行 */
+  background: boolean;
+  /** 超时时间 */
+  timeout?: number;
+  /** 清理策略 */
+  cleanup?: "delete" | "keep";
+  /** 执行原因 */
+  reason?: string;
+  /** Tag 服务引用 */
+  tagService: TagService;
+}
+
+/**
+ * Delegate After Hook Context
+ * 
+ * 触发时机：delegate_task 工具执行后
+ */
+export interface TaskDelegateResultContext {
+  /** 关联的 Task ID */
+  taskId?: number;
+  /** 执行结果 */
+  result: DelegateToolResult;
+  /** Tag 服务引用 */
+  tagService: TagService;
+}
+
+// ========================================================================
+// Operation Contexts
+// ========================================================================
+
+/**
+ * Operation Create Hook Context
+ * 
+ * 触发时机：createOperation() 方法调用后，实际创建前
+ * 
+ * Plugin 可直接修改 options 来干预操作记录创建
+ */
+export interface TaskOperationCreateContext {
+  /** 创建选项（Plugin 可直接修改） */
+  options: CreateOperationOptions;
+}
+
+/**
+ * Operation Create Result Hook Context
+ * 
+ * 触发时机：操作记录创建成功后
+ */
+export interface TaskOperationCreateResultContext {
+  /** 创建后的操作记录 */
+  operation: TaskOperation;
+}
+
+// ========================================================================
+// Context Map（用于泛型推导）
+// ========================================================================
+
+/**
+ * TaskHookContextMap - Hook 点与 Context 类型的映射
+ * 
+ * 用于 Hook 执行时类型安全的 Context 获取
+ */
+export interface TaskHookContextMap {
+  "task:before.create": TaskCreateContext;
+  "task:after.create": TaskCreateResultContext;
+  "task:before.update": TaskUpdateContext;
+  "task:after.update": TaskUpdateResultContext;
+  "task:before.delete": TaskDeleteContext;
+  "task:after.delete": TaskDeleteResultContext;
+  "task:delegate:before": TaskDelegateContext;
+  "task:delegate:after": TaskDelegateResultContext;
+  "task:operation:before.create": TaskOperationCreateContext;
+  "task:operation:after.create": TaskOperationCreateResultContext;
+}

package/src/env/task/hooks/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Task Hooks Module
+ * 
+ * 提供 Task Component 的 Hook 机制
+ */
+
+// Hook 点常量
+export { TaskHookPoints, type TaskHookPoint } from "./task-hook-points";
+
+// Context 类型
+export type {
+  TaskCreateContext,
+  TaskCreateResultContext,
+  TaskUpdateContext,
+  TaskUpdateResultContext,
+  TaskDeleteContext,
+  TaskDeleteResultContext,
+  TaskDelegateContext,
+  TaskDelegateResultContext,
+  TaskOperationCreateContext,
+  TaskOperationCreateResultContext,
+  TaskHookContextMap,
+} from "./contexts";

package/src/env/task/hooks/task-hook-points.test.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Task Hook Points Tests
+ */
+
+import { describe, test, expect } from "vitest";
+import { TaskHookPoints } from "./task-hook-points";
+
+describe("TaskHookPoints", () => {
+  test("should export all task CRUD hook points", () => {
+    expect(TaskHookPoints.BEFORE_CREATE).toBe("task:before.create");
+    expect(TaskHookPoints.AFTER_CREATE).toBe("task:after.create");
+    expect(TaskHookPoints.BEFORE_UPDATE).toBe("task:before.update");
+    expect(TaskHookPoints.AFTER_UPDATE).toBe("task:after.update");
+    expect(TaskHookPoints.BEFORE_DELETE).toBe("task:before.delete");
+    expect(TaskHookPoints.AFTER_DELETE).toBe("task:after.delete");
+  });
+
+  test("should export delegate hook points", () => {
+    expect(TaskHookPoints.DELEGATE_BEFORE).toBe("task:delegate:before");
+    expect(TaskHookPoints.DELEGATE_AFTER).toBe("task:delegate:after");
+  });
+
+  test("should export operation hook points", () => {
+    expect(TaskHookPoints.OPERATION_BEFORE_CREATE).toBe("task:operation:before.create");
+    expect(TaskHookPoints.OPERATION_AFTER_CREATE).toBe("task:operation:after.create");
+  });
+
+  test("should have 10 hook points total", () => {
+    const hookPoints = Object.values(TaskHookPoints);
+    expect(hookPoints).toHaveLength(10);
+  });
+});

package/src/env/task/hooks/task-hook-points.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Task Hook Points - Hook 点常量定义
+ * 
+ * 定义 Task Component 生命周期中的所有 Hook 点
+ */
+
+export const TaskHookPoints = {
+  // ========================================================================
+  // Task CRUD Hooks
+  // ========================================================================
+  
+  /** 创建 Task 前 - 可干预 options */
+  BEFORE_CREATE: "task:before.create",
+  
+  /** 创建 Task 后 - 观察或触发副作用 */
+  AFTER_CREATE: "task:after.create",
+  
+  /** 更新 Task 前 - 可干预 options */
+  BEFORE_UPDATE: "task:before.update",
+  
+  /** 更新 Task 后 - 观察变更 */
+  AFTER_UPDATE: "task:after.update",
+  
+  /** 删除 Task 前 - 观察 */
+  BEFORE_DELETE: "task:before.delete",
+  
+  /** 删除 Task 后 - 清理关联资源 */
+  AFTER_DELETE: "task:after.delete",
+  
+  // ========================================================================
+  // Delegate Hooks
+  // ========================================================================
+  
+  /** 委派任务前 - 可干预 prompt、参数 */
+  DELEGATE_BEFORE: "task:delegate:before",
+  
+  /** 委派任务后 - 观察结果 */
+  DELEGATE_AFTER: "task:delegate:after",
+  
+  // ========================================================================
+  // Operation Hooks
+  // ========================================================================
+  
+  /** 创建操作记录前 - 可干预 options */
+  OPERATION_BEFORE_CREATE: "task:operation:before.create",
+  
+  /** 创建操作记录后 - 观察或触发副作用 */
+  OPERATION_AFTER_CREATE: "task:operation:after.create",
+} as const;
+
+/**
+ * Task Hook 点类型
+ */
+export type TaskHookPoint = typeof TaskHookPoints[keyof typeof TaskHookPoints];

package/src/env/task/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Task Component Index
+ */
+
+export { TaskComponent, type TaskComponentOptions } from "./task-component";
+export * from "./types";
+export { SQLiteTaskStore, type TaskStore } from "./storage";

package/src/env/task/plugins/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Task Plugins Module
+ */
+
+export { TaskPlugin, type TaskPluginConfig, type TaskPluginHook } from "./task-plugin";
+export { TaskTagPlugin } from "./task-tag-plugin";
+export {
+  WORKFLOW_EXTRACTOR_PROMPT,
+  createWorkflowExtractorAgent,
+  formatExtractorInput,
+  formatExtractorInputFromDescription,
+  parseExtractorOutput,
+} from "./workflow-extractor-agent";

package/src/env/task/plugins/task-plugin.test.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview TaskPlugin Tests
+ */
+
+import { describe, test, expect } from "vitest";
+import { TaskPlugin, type TaskPluginConfig } from "./task-plugin";
+
+// Concrete implementation for testing
+class TestPlugin extends TaskPlugin {
+  readonly name = "TestPlugin";
+  readonly hooks = [
+    { point: "task:before.create", priority: 10 },
+    { point: "task:after.create", priority: 5 },
+  ];
+
+  execute() {
+    // No-op for testing
+  }
+}
+
+describe("TaskPlugin", () => {
+  test("should have name and hooks", () => {
+    const plugin = new TestPlugin();
+    
+    expect(plugin.name).toBe("TestPlugin");
+    expect(plugin.hooks).toHaveLength(2);
+    expect(plugin.hooks[0].point).toBe("task:before.create");
+    expect(plugin.hooks[0].priority).toBe(10);
+  });
+
+  test("should get hook points", () => {
+    const plugin = new TestPlugin();
+    const points = plugin.getHookPoints();
+    
+    expect(points).toContain("task:before.create");
+    expect(points).toContain("task:after.create");
+  });
+
+  test("should get priority for hook", () => {
+    const plugin = new TestPlugin();
+    
+    expect(plugin.getPriorityForHook("task:before.create")).toBe(10);
+    expect(plugin.getPriorityForHook("task:after.create")).toBe(5);
+    expect(plugin.getPriorityForHook("unknown")).toBe(0);
+  });
+
+  test("should be enabled by default", () => {
+    const plugin = new TestPlugin();
+    expect(plugin.isEnabled()).toBe(true);
+  });
+
+  test("should set enabled state", () => {
+    const plugin = new TestPlugin();
+    
+    plugin.setEnabled(false);
+    expect(plugin.isEnabled()).toBe(false);
+    
+    plugin.setEnabled(true);
+    expect(plugin.isEnabled()).toBe(true);
+  });
+
+  test("should use config priority when hook priority not set", () => {
+    class PluginWithConfig extends TaskPlugin {
+      readonly name = "ConfigPlugin";
+      readonly hooks = [
+        { point: "task:before.create" }, // No priority
+      ];
+      execute() {}
+    }
+    
+    const plugin = new PluginWithConfig({ priority: 20 });
+    expect(plugin.getPriorityForHook("task:before.create")).toBe(20);
+  });
+});

package/src/env/task/plugins/task-plugin.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview TaskPlugin 基类
+ * 
+ * 所有 Task Plugin 的基类，提供统一的接口和生命周期管理
+ */
+
+import type { HookContext } from "../../hook/types";
+import type { AgentInstanceConfig } from "../../agent/types";
+
+/**
+ * TaskPlugin 配置
+ */
+export interface TaskPluginConfig {
+  /** 是否启用 */
+  enabled?: boolean;
+  /** 优先级 */
+  priority?: number;
+}
+
+/**
+ * TaskPlugin Hook 定义
+ */
+export interface TaskPluginHook {
+  /** Hook 点 */
+  point: string;
+  /** 优先级（数字越大越先执行）*/
+  priority?: number;
+}
+
+/**
+ * TaskPlugin 基类
+ */
+export abstract class TaskPlugin {
+  abstract readonly name: string;
+  abstract readonly hooks: TaskPluginHook[];
+  protected config: TaskPluginConfig;
+  
+  constructor(config: TaskPluginConfig = {}) {
+    this.config = { enabled: true, priority: 0, ...config };
+  }
+  
+  /**
+   * 执行 Hook
+   * @param ctx Hook 上下文
+   */
+  abstract execute(ctx: HookContext): void | Promise<void>;
+  
+  /**
+   * 设置依赖组件（可选实现）
+   */
+  setComponents?(llmComponent: unknown, taskComponent: unknown): void;
+  
+  /**
+   * 获取 Hook 点列表
+   */
+  getHookPoints(): string[] {
+    return this.hooks.map(h => h.point);
+  }
+  
+  /**
+   * 获取指定 Hook 点的优先级
+   */
+  getPriorityForHook(hookPoint: string): number {
+    const hook = this.hooks.find(h => h.point === hookPoint);
+    return hook?.priority ?? this.config.priority ?? 0;
+  }
+  
+  /**
+   * 检查是否启用
+   */
+  isEnabled(): boolean {
+    return this.config.enabled ?? true;
+  }
+  
+  /**
+   * 设置启用状态
+   */
+  setEnabled(enabled: boolean): void {
+    this.config.enabled = enabled;
+  }
+  
+  /**
+   * 获取依赖的 Agent 配置列表（可选实现）
+   * 
+   * 子类可覆盖此方法声明依赖的 Agents
+   * TaskComponent.registerPlugin 时会自动注册这些 Agents
+   */
+  static getRequiredAgents?(): AgentInstanceConfig[];
+}