@ai-setting/roy-agent-core 1.0.0

package/src/env/hook/hook-manager.test.ts

@@ -0,0 +1,374 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { HookManager, type Hook, type HookContext } from "./hook-manager";
+import { createHook } from "./types";
+
+// 测试用的上下文类型
+interface TestData {
+  value: number;
+}
+
+// 创建测试 Hook 的辅助函数
+function makeHook(
+  name: string,
+  execute: (ctx: HookContext<TestData>) => void | Promise<void>,
+  priority?: number
+): Hook<TestData> {
+  return createHook({ name, priority }, execute);
+}
+
+describe("HookManager", () => {
+  let manager: HookManager<TestData>;
+
+  beforeEach(() => {
+    manager = new HookManager<TestData>();
+  });
+
+  // ========================================================================
+  // 基础功能测试
+  // ========================================================================
+
+  describe("register", () => {
+    test("should register a hook to a hook point", () => {
+      const hook = makeHook("test-hook", async () => {});
+      
+      manager.register("test.point", hook);
+      
+      expect(manager.count("test.point")).toBe(1);
+    });
+
+    test("should register multiple hooks to the same hook point", () => {
+      const hook1 = makeHook("hook-1", async () => {});
+      const hook2 = makeHook("hook-2", async () => {});
+      
+      manager.register("test.point", hook1);
+      manager.register("test.point", hook2);
+      
+      expect(manager.count("test.point")).toBe(2);
+    });
+
+    test("should register hooks to different hook points", () => {
+      const hook1 = makeHook("hook-1", async () => {});
+      const hook2 = makeHook("hook-2", async () => {});
+      
+      manager.register("point.1", hook1);
+      manager.register("point.2", hook2);
+      
+      expect(manager.count("point.1")).toBe(1);
+      expect(manager.count("point.2")).toBe(1);
+    });
+  });
+
+  describe("registerMany", () => {
+    test("should register multiple hooks at once", () => {
+      const hooks = [
+        makeHook("hook-1", async () => {}),
+        makeHook("hook-2", async () => {}),
+      ];
+      
+      manager.registerMany("test.point", hooks);
+      
+      expect(manager.count("test.point")).toBe(2);
+    });
+
+    test("should register empty array", () => {
+      manager.registerMany("test.point", []);
+      expect(manager.count("test.point")).toBe(0);
+    });
+  });
+
+  describe("unregister", () => {
+    test("should unregister a hook by name", () => {
+      const hook1 = makeHook("hook-1", async () => {});
+      const hook2 = makeHook("hook-2", async () => {});
+      
+      manager.register("test.point", hook1);
+      manager.register("test.point", hook2);
+      
+      const result = manager.unregister("test.point", "hook-1");
+      
+      expect(result).toBe(true);
+      expect(manager.count("test.point")).toBe(1);
+    });
+
+    test("should return false if hook not found", () => {
+      const result = manager.unregister("nonexistent", "hook");
+      expect(result).toBe(false);
+    });
+  });
+
+  describe("unregisterAll", () => {
+    test("should unregister all hooks at a hook point", () => {
+      manager.register("test.point", makeHook("hook-1", async () => {}));
+      manager.register("test.point", makeHook("hook-2", async () => {}));
+      
+      manager.unregisterAll("test.point");
+      
+      expect(manager.count("test.point")).toBe(0);
+    });
+  });
+
+  describe("count", () => {
+    test("should return 0 for non-existent hook point", () => {
+      expect(manager.count("nonexistent")).toBe(0);
+    });
+  });
+
+  describe("clear", () => {
+    test("should clear all hooks", () => {
+      manager.register("point.1", makeHook("hook-1", async () => {}));
+      manager.register("point.2", makeHook("hook-2", async () => {}));
+      
+      manager.clear();
+      
+      expect(manager.count("point.1")).toBe(0);
+      expect(manager.count("point.2")).toBe(0);
+    });
+  });
+
+  describe("getHookPoints", () => {
+    test("should return all registered hook points", () => {
+      manager.register("point.1", makeHook("hook-1", async () => {}));
+      manager.register("point.2", makeHook("hook-2", async () => {}));
+      manager.register("point.3", makeHook("hook-3", async () => {}));
+      
+      const points = manager.getHookPoints();
+      
+      expect(points).toContain("point.1");
+      expect(points).toContain("point.2");
+      expect(points).toContain("point.3");
+    });
+
+    test("should return empty array when no hooks registered", () => {
+      expect(manager.getHookPoints()).toEqual([]);
+    });
+  });
+
+  // ========================================================================
+  // 执行测试
+  // ========================================================================
+
+  describe("execute", () => {
+    test("should execute all hooks at a hook point", async () => {
+      const executionOrder: string[] = [];
+      
+      manager.register("test.point", makeHook("hook-1", async () => {
+        executionOrder.push("hook-1");
+      }));
+      manager.register("test.point", makeHook("hook-2", async () => {
+        executionOrder.push("hook-2");
+      }));
+      
+      await manager.execute("test.point", { value: 42 }, { meta: "test" });
+      
+      expect(executionOrder).toEqual(["hook-1", "hook-2"]);
+    });
+
+    test("should pass correct context to hooks", async () => {
+      let receivedCtx: HookContext<TestData> | null = null;
+      
+      manager.register("test.point", makeHook("test-hook", async (ctx) => {
+        receivedCtx = ctx;
+      }));
+      
+      const testData = { value: 123 };
+      const testMeta = { source: "unit-test" };
+      
+      await manager.execute("test.point", testData, testMeta);
+      
+      expect(receivedCtx).not.toBeNull();
+      expect(receivedCtx!.data).toEqual(testData);
+      expect(receivedCtx!.metadata).toEqual(testMeta);
+      expect(receivedCtx!.phase).toBe("before");
+      expect(receivedCtx!.hookPoint).toBe("test.point");
+    });
+
+    test("should do nothing for non-existent hook point", async () => {
+      const hook = makeHook("should-not-run", async () => {
+        throw new Error("This hook should not run");
+      });
+      
+      // 不注册，直接执行
+      await manager.execute("nonexistent", { value: 0 });
+      
+      // 没有错误即为通过
+      expect(true).toBe(true);
+    });
+  });
+
+  describe("executeAndCollect", () => {
+    test("should collect return values from hooks", async () => {
+      manager.register("test.point", makeHook("hook-1", async () => "result-1"));
+      manager.register("test.point", makeHook("hook-2", async () => "result-2"));
+      
+      const results = await manager.executeAndCollect<string>("test.point", { value: 0 });
+      
+      expect(results).toEqual(["result-1", "result-2"]);
+    });
+
+    test("should return empty array for non-existent hook point", async () => {
+      const results = await manager.executeAndCollect<string>("nonexistent", { value: 0 });
+      expect(results).toEqual([]);
+    });
+  });
+
+  // ========================================================================
+  // 优先级测试
+  // ========================================================================
+
+  describe("hook priority", () => {
+    test("should execute hooks in priority order (lower priority first)", async () => {
+      const executionOrder: string[] = [];
+      
+      manager.register("test.point", makeHook("low-priority", async () => {
+        executionOrder.push("low-priority");
+      }, 100));
+      
+      manager.register("test.point", makeHook("high-priority", async () => {
+        executionOrder.push("high-priority");
+      }, 1));
+      
+      manager.register("test.point", makeHook("medium-priority", async () => {
+        executionOrder.push("medium-priority");
+      }, 50));
+      
+      await manager.execute("test.point", { value: 0 });
+      
+      expect(executionOrder).toEqual([
+        "high-priority",
+        "medium-priority",
+        "low-priority"
+      ]);
+    });
+
+    test("should maintain registration order for same priority", async () => {
+      const executionOrder: string[] = [];
+      
+      manager.register("test.point", makeHook("first", async () => {
+        executionOrder.push("first");
+      }, 0));
+      
+      manager.register("test.point", makeHook("second", async () => {
+        executionOrder.push("second");
+      }, 0));
+      
+      await manager.execute("test.point", { value: 0 });
+      
+      expect(executionOrder).toEqual(["first", "second"]);
+    });
+
+    test("should use default priority 0 when not specified", async () => {
+      const executionOrder: string[] = [];
+      
+      manager.register("test.point", makeHook("with-priority", async () => {
+        executionOrder.push("with-priority");
+      }, 10));
+      
+      manager.register("test.point", makeHook("no-priority", async () => {
+        executionOrder.push("no-priority");
+      }));
+      
+      await manager.execute("test.point", { value: 0 });
+      
+      expect(executionOrder).toEqual(["no-priority", "with-priority"]);
+    });
+  });
+
+  // ========================================================================
+  // 错误隔离测试
+  // ========================================================================
+
+  describe("error isolation", () => {
+    test("should not throw if a hook throws", async () => {
+      manager.register("test.point", makeHook("failing-hook", async () => {
+        throw new Error("Hook failed");
+      }));
+      
+      manager.register("test.point", makeHook("good-hook", async () => {}));
+      
+      // 应该不抛出错误 - 直接调用而不是用 expect
+      let threw = false;
+      try {
+        await manager.execute("test.point", { value: 0 });
+      } catch {
+        threw = true;
+      }
+      expect(threw).toBe(false);
+    });
+
+    test("should continue executing other hooks if one fails", async () => {
+      const executionOrder: string[] = [];
+      
+      manager.register("test.point", makeHook("hook-1", async () => {
+        executionOrder.push("hook-1");
+      }));
+      
+      manager.register("test.point", makeHook("failing-hook", async () => {
+        throw new Error("Hook failed");
+      }));
+      
+      manager.register("test.point", makeHook("hook-2", async () => {
+        executionOrder.push("hook-2");
+      }));
+      
+      await manager.execute("test.point", { value: 0 });
+      
+      expect(executionOrder).toEqual(["hook-1", "hook-2"]);
+    });
+
+    test("should handle async hooks throwing", async () => {
+      const executionOrder: string[] = [];
+      
+      manager.register("test.point", makeHook("hook-1", async () => {
+        executionOrder.push("hook-1");
+      }));
+      
+      manager.register("test.point", makeHook("async-failing", async () => {
+        await Promise.resolve();
+        throw new Error("Async hook failed");
+      }));
+      
+      manager.register("test.point", makeHook("hook-2", async () => {
+        executionOrder.push("hook-2");
+      }));
+      
+      await manager.execute("test.point", { value: 0 });
+      
+      expect(executionOrder).toEqual(["hook-1", "hook-2"]);
+    });
+  });
+
+  // ========================================================================
+  // 生命周期测试
+  // ========================================================================
+
+  describe("hook lifecycle", () => {
+    test("should pass component info to hooks", async () => {
+      let receivedCtx: HookContext<TestData> | null = null;
+      const customManager = new HookManager<TestData>({
+        componentName: "TestComponent",
+        componentVersion: "2.0.0"
+      });
+      
+      customManager.register("test.point", makeHook("test-hook", async (ctx) => {
+        receivedCtx = ctx;
+      }));
+      
+      await customManager.execute("test.point", { value: 0 });
+      
+      expect(receivedCtx!.component.name).toBe("TestComponent");
+      expect(receivedCtx!.component.version).toBe("2.0.0");
+    });
+
+    test("should pass correct hookPoint to hooks", async () => {
+      let receivedHookPoint: string | null = null;
+      
+      manager.register("my.hook.point", makeHook("test-hook", async (ctx) => {
+        receivedHookPoint = ctx.hookPoint;
+      }));
+      
+      await manager.execute("my.hook.point", { value: 0 });
+      
+      expect(receivedHookPoint).toBe("my.hook.point");
+    });
+  });
+});

package/src/env/hook/hook-manager.ts

@@ -0,0 +1,309 @@
+/**
+ * @fileoverview Hook Manager - 统一管理 Component 的 Hook
+ * 
+ * 提供：
+ * - Hook 注册和管理
+ * - 按优先级排序执行
+ * - 错误隔离
+ * - 动态添加/移除
+ * - 干预机制（executeWithIntervention）
+ */
+
+import type { Hook, HookContext, HookPhase, HookResult } from "./types";
+
+/**
+ * HookManager 配置
+ */
+export interface HookManagerOptions {
+  /** 组件名称（用于上下文） */
+  componentName?: string;
+  /** 组件版本（用于上下文） */
+  componentVersion?: string;
+  /** 默认优先级 */
+  defaultPriority?: number;
+}
+
+/**
+ * HookManager
+ * 
+ * 统一管理 Component 的 Hook
+ * 
+ * @example
+ * ```typescript
+ * const manager = new HookManager<MyContext>();
+ * 
+ * // 注册 Hook
+ * manager.register("before-action", {
+ *   name: "my-hook",
+ *   priority: 10,
+ *   execute: async (ctx) => { /* ... *\/ }
+ * });
+ * 
+ * // 执行 Hooks
+ * await manager.execute("before-action", data);
+ * ```
+ */
+export class HookManager<T = unknown> {
+  private _hooks: Map<string, Hook<T>[]> = new Map();
+  private componentName: string;
+  private componentVersion: string;
+  private defaultPriority: number;
+
+  constructor(options: HookManagerOptions = {}) {
+    this.componentName = options.componentName ?? "unknown";
+    this.componentVersion = options.componentVersion ?? "0.0.0";
+    this.defaultPriority = options.defaultPriority ?? 0;
+  }
+
+  /**
+   * 注册 Hook 到指定 hook 点
+   */
+  register(hookPoint: string, hook: Hook<T>): void {
+    const hooks = this.getOrCreateHooks(hookPoint);
+    hooks.push(hook);
+  }
+
+  /**
+   * 注册多个 Hook
+   */
+  registerMany(hookPoint: string, hooks: Hook<T>[]): void {
+    const hookList = this.getOrCreateHooks(hookPoint);
+    hookList.push(...hooks);
+  }
+
+  /**
+   * 按名称取消注册 Hook
+   * @returns 是否成功取消注册
+   */
+  unregister(hookPoint: string, name: string): boolean {
+    const hooks = this._hooks.get(hookPoint);
+    if (!hooks) return false;
+
+    const index = hooks.findIndex((h) => h.name === name);
+    if (index === -1) return false;
+
+    hooks.splice(index, 1);
+    return true;
+  }
+
+  /**
+   * 取消注册所有指定 hook 点的 Hook
+   */
+  unregisterAll(hookPoint: string): void {
+    this._hooks.delete(hookPoint);
+  }
+
+  /**
+   * 执行指定 hook 点的所有 Hook
+   */
+  async execute(
+    hookPoint: string,
+    data: T,
+    metadata: Record<string, unknown> = {}
+  ): Promise<void> {
+    const hooks = this._hooks.get(hookPoint);
+    if (!hooks || hooks.length === 0) return;
+
+    const sortedHooks = this.sortHooks(hooks);
+    const ctx = this.createContext(hookPoint, data, metadata, "before");
+
+    for (const hook of sortedHooks) {
+      await this.safeExecute(hook, ctx);
+    }
+  }
+
+  /**
+   * 执行指定 hook 点的所有 Hook 并收集返回值
+   */
+  async executeAndCollect<R>(
+    hookPoint: string,
+    data: T,
+    metadata: Record<string, unknown> = {}
+  ): Promise<R[]> {
+    const hooks = this._hooks.get(hookPoint);
+    if (!hooks || hooks.length === 0) return [];
+
+    const sortedHooks = this.sortHooks(hooks);
+    const ctx = this.createContext(hookPoint, data, metadata, "before");
+    const results: R[] = [];
+
+    for (const hook of sortedHooks) {
+      const result = await this.safeExecuteAndReturn(hook, ctx);
+      if (result !== undefined) {
+        results.push(result as R);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * 获取指定 hook 点的 Hook 数量
+   */
+  count(hookPoint: string): number {
+    return this._hooks.get(hookPoint)?.length ?? 0;
+  }
+
+  /**
+   * 清空所有 Hook
+   */
+  clear(): void {
+    this._hooks.clear();
+  }
+
+  /**
+   * 获取所有已注册的 hook 点
+   */
+  getHookPoints(): string[] {
+    return Array.from(this._hooks.keys());
+  }
+
+  /**
+   * 检查 hook 点是否有任何 Hook
+   */
+  hasHooks(hookPoint: string): boolean {
+    return this.count(hookPoint) > 0;
+  }
+
+  /**
+   * 设置组件信息
+   */
+  setComponentInfo(name: string, version: string): void {
+    this.componentName = name;
+    this.componentVersion = version;
+  }
+
+  /**
+   * 获取所有注册的 hooks（只读副本）
+   */
+  get hooks(): ReadonlyMap<string, Hook<T>[]> {
+    return this._hooks;
+  }
+
+  // ========================================================================
+  // 干预机制
+  // ========================================================================
+
+  /**
+   * 执行 Hook 并支持干预机制
+   * 
+   * 如果任何一个 Hook 返回 { stop: true }，执行会停止
+   * Hook 可以通过返回 HookResult 来执行干预动作
+   * 
+   * @param hookPoint Hook 点
+   * @param data 数据
+   * @param metadata 元数据
+   * @returns 执行结果
+   */
+  async executeWithIntervention(
+    hookPoint: string,
+    data: T,
+    metadata: Record<string, unknown> = {}
+  ): Promise<HookResult> {
+    const hooks = this._hooks.get(hookPoint);
+    if (!hooks || hooks.length === 0) {
+      return { stopped: false, results: [] };
+    }
+
+    const sortedHooks = this.sortHooks(hooks);
+    const ctx = this.createContext(hookPoint, data, metadata, "before");
+    const results: unknown[] = [];
+    let stopped = false;
+    let action: HookResult["action"];
+
+    for (const hook of sortedHooks) {
+      if (stopped) break;
+
+      const result = await this.safeExecuteAndReturn(hook, ctx);
+      results.push(result);
+
+      // 检查是否需要干预
+      if (result && typeof result === "object" && "stopped" in result) {
+        const hookResult = result as HookResult;
+        if (hookResult.stopped) {
+          stopped = true;
+          action = hookResult.action;
+        }
+      }
+    }
+
+    return { stopped, action, results };
+  }
+
+  // ========================================================================
+  // 私有方法
+  // ========================================================================
+
+  /**
+   * 获取或创建 hook 列表
+   */
+  private getOrCreateHooks(hookPoint: string): Hook<T>[] {
+    let hooks = this._hooks.get(hookPoint);
+    if (!hooks) {
+      hooks = [];
+      this._hooks.set(hookPoint, hooks);
+    }
+    return hooks;
+  }
+
+  /**
+   * 按优先级排序 Hook
+   * 
+   * 优先级相同时保持原顺序（稳定排序）
+   */
+  private sortHooks(hooks: Hook<T>[]): Hook<T>[] {
+    return [...hooks].sort((a, b) => {
+      const priorityA = a.priority ?? this.defaultPriority;
+      const priorityB = b.priority ?? this.defaultPriority;
+      return priorityA - priorityB;
+    });
+  }
+
+  /**
+   * 创建 Hook 上下文
+   */
+  private createContext(
+    hookPoint: string,
+    data: T,
+    metadata: Record<string, unknown>,
+    phase: HookPhase
+  ): HookContext<T> {
+    return {
+      component: {
+        name: this.componentName,
+        version: this.componentVersion,
+      },
+      data,
+      metadata,
+      phase,
+      hookPoint,
+    };
+  }
+
+  /**
+   * 安全执行 Hook（错误隔离）
+   */
+  private async safeExecute(hook: Hook<T>, ctx: HookContext<T>): Promise<void> {
+    try {
+      await hook.execute(ctx);
+    } catch (error) {
+      // 记录错误但不中断执行
+      console.error(`Hook "${hook.name}" failed:`, error);
+    }
+  }
+
+  /**
+   * 安全执行 Hook 并返回结果
+   */
+  private async safeExecuteAndReturn<R>(
+    hook: Hook<T>,
+    ctx: HookContext<T>
+  ): Promise<R | undefined> {
+    try {
+      return await (hook.execute(ctx) as Promise<R>);
+    } catch (error) {
+      console.error(`Hook "${hook.name}" failed:`, error);
+      return undefined;
+    }
+  }
+}