@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/hook/hook-manager.js

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview Hook Manager - 统一管理 Component 的 Hook
+ *
+ * 提供：
+ * - Hook 注册和管理
+ * - 按优先级排序执行
+ * - 错误隔离
+ * - 动态添加/移除
+ * - 干预机制（executeWithIntervention）
+ */
+/**
+ * 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 {
+    _hooks = new Map();
+    componentName;
+    componentVersion;
+    defaultPriority;
+    constructor(options = {}) {
+        this.componentName = options.componentName ?? "unknown";
+        this.componentVersion = options.componentVersion ?? "0.0.0";
+        this.defaultPriority = options.defaultPriority ?? 0;
+    }
+    /**
+     * 注册 Hook 到指定 hook 点
+     */
+    register(hookPoint, hook) {
+        const hooks = this.getOrCreateHooks(hookPoint);
+        hooks.push(hook);
+    }
+    /**
+     * 注册多个 Hook
+     */
+    registerMany(hookPoint, hooks) {
+        const hookList = this.getOrCreateHooks(hookPoint);
+        hookList.push(...hooks);
+    }
+    /**
+     * 按名称取消注册 Hook
+     * @returns 是否成功取消注册
+     */
+    unregister(hookPoint, name) {
+        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) {
+        this._hooks.delete(hookPoint);
+    }
+    /**
+     * 执行指定 hook 点的所有 Hook
+     */
+    async execute(hookPoint, data, metadata = {}) {
+        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(hookPoint, data, metadata = {}) {
+        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 = [];
+        for (const hook of sortedHooks) {
+            const result = await this.safeExecuteAndReturn(hook, ctx);
+            if (result !== undefined) {
+                results.push(result);
+            }
+        }
+        return results;
+    }
+    /**
+     * 获取指定 hook 点的 Hook 数量
+     */
+    count(hookPoint) {
+        return this._hooks.get(hookPoint)?.length ?? 0;
+    }
+    /**
+     * 清空所有 Hook
+     */
+    clear() {
+        this._hooks.clear();
+    }
+    /**
+     * 获取所有已注册的 hook 点
+     */
+    getHookPoints() {
+        return Array.from(this._hooks.keys());
+    }
+    /**
+     * 检查 hook 点是否有任何 Hook
+     */
+    hasHooks(hookPoint) {
+        return this.count(hookPoint) > 0;
+    }
+    /**
+     * 设置组件信息
+     */
+    setComponentInfo(name, version) {
+        this.componentName = name;
+        this.componentVersion = version;
+    }
+    /**
+     * 获取所有注册的 hooks（只读副本）
+     */
+    get hooks() {
+        return this._hooks;
+    }
+    // ========================================================================
+    // 干预机制
+    // ========================================================================
+    /**
+     * 执行 Hook 并支持干预机制
+     *
+     * 如果任何一个 Hook 返回 { stop: true }，执行会停止
+     * Hook 可以通过返回 HookResult 来执行干预动作
+     *
+     * @param hookPoint Hook 点
+     * @param data 数据
+     * @param metadata 元数据
+     * @returns 执行结果
+     */
+    async executeWithIntervention(hookPoint, data, metadata = {}) {
+        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 = [];
+        let stopped = false;
+        let 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;
+                if (hookResult.stopped) {
+                    stopped = true;
+                    action = hookResult.action;
+                }
+            }
+        }
+        return { stopped, action, results };
+    }
+    // ========================================================================
+    // 私有方法
+    // ========================================================================
+    /**
+     * 获取或创建 hook 列表
+     */
+    getOrCreateHooks(hookPoint) {
+        let hooks = this._hooks.get(hookPoint);
+        if (!hooks) {
+            hooks = [];
+            this._hooks.set(hookPoint, hooks);
+        }
+        return hooks;
+    }
+    /**
+     * 按优先级排序 Hook
+     *
+     * 优先级相同时保持原顺序（稳定排序）
+     */
+    sortHooks(hooks) {
+        return [...hooks].sort((a, b) => {
+            const priorityA = a.priority ?? this.defaultPriority;
+            const priorityB = b.priority ?? this.defaultPriority;
+            return priorityA - priorityB;
+        });
+    }
+    /**
+     * 创建 Hook 上下文
+     */
+    createContext(hookPoint, data, metadata, phase) {
+        return {
+            component: {
+                name: this.componentName,
+                version: this.componentVersion,
+            },
+            data,
+            metadata,
+            phase,
+            hookPoint,
+        };
+    }
+    /**
+     * 安全执行 Hook（错误隔离）
+     */
+    async safeExecute(hook, ctx) {
+        try {
+            await hook.execute(ctx);
+        }
+        catch (error) {
+            // 记录错误但不中断执行
+            console.error(`Hook "${hook.name}" failed:`, error);
+        }
+    }
+    /**
+     * 安全执行 Hook 并返回结果
+     */
+    async safeExecuteAndReturn(hook, ctx) {
+        try {
+            return await hook.execute(ctx);
+        }
+        catch (error) {
+            console.error(`Hook "${hook.name}" failed:`, error);
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=hook-manager.js.map

package/dist/core/src/env/hook/hook-manager.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hook-manager.test.d.ts.map

package/dist/core/src/env/hook/hook-manager.test.js

@@ -0,0 +1,275 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { HookManager } from "./hook-manager.js";
+import { createHook } from "./types.js";
+// 创建测试 Hook 的辅助函数
+function makeHook(name, execute, priority) {
+    return createHook({ name, priority }, execute);
+}
+describe("HookManager", () => {
+    let manager;
+    beforeEach(() => {
+        manager = new HookManager();
+    });
+    // ========================================================================
+    // 基础功能测试
+    // ========================================================================
+    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 = [];
+            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 = 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("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("nonexistent", { value: 0 });
+            expect(results).toEqual([]);
+        });
+    });
+    // ========================================================================
+    // 优先级测试
+    // ========================================================================
+    describe("hook priority", () => {
+        test("should execute hooks in priority order (lower priority first)", async () => {
+            const executionOrder = [];
+            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 = [];
+            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 = [];
+            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 = [];
+            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 = [];
+            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 = null;
+            const customManager = new HookManager({
+                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 = 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");
+        });
+    });
+});
+//# sourceMappingURL=hook-manager.test.js.map

package/dist/core/src/env/hook/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Hook 系统统一导出
+ *
+ * 注意：HookContext 泛型版本从 ./types 导出
+ * Agent 特有的 HookContext 包含 iteration, maxIterations 等字段，在 ./agent/types.ts 中
+ */
+export { type HookPhase, type HookMeta, type HookContext, type Hook, type HookFn, type HookActionType, type HookAction, type HookResult, type HookContext as BaseHookContext, type Hook as BaseHook, type HookFn as BaseHookFn, createHook, createPriorityHook, } from "./types";
+export { HookManager, type HookManagerOptions } from "./hook-manager";
+export { globalHookManager, AgentHookPoints, LLMHookPoints, ToolHookPoints, executeAgentHook, executeAgentHookWithIntervention, executeLLMHook, executeToolHook, } from "./global-hook-manager";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/src/env/hook/index.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Hook 系统统一导出
+ *
+ * 注意：HookContext 泛型版本从 ./types 导出
+ * Agent 特有的 HookContext 包含 iteration, maxIterations 等字段，在 ./agent/types.ts 中
+ */
+export { createHook, createPriorityHook, } from "./types.js";
+// HookManager
+export { HookManager } from "./hook-manager.js";
+// GlobalHookManager
+export { globalHookManager, AgentHookPoints, LLMHookPoints, ToolHookPoints, executeAgentHook, executeAgentHookWithIntervention, executeLLMHook, executeToolHook, } from "./global-hook-manager.js";
+//# sourceMappingURL=index.js.map

package/dist/core/src/env/hook/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Hook 系统统一类型定义
+ *
+ * 提供所有 Component 使用的统一 Hook 接口
+ */
+/**
+ * Hook 执行阶段
+ */
+export type HookPhase = "before" | "after" | "error";
+/**
+ * Hook 元信息
+ */
+export interface HookMeta {
+    /** Hook 唯一名称 */
+    name: string;
+    /** 执行优先级，默认 0，数值越小越先执行 */
+    priority?: number;
+    /** 描述 */
+    description?: string;
+}
+/**
+ * 统一 Hook 上下文
+ *
+ * 泛型参数 T 表示该 Component 的上下文数据类型
+ */
+export interface HookContext<T = unknown> {
+    /** 当前组件信息 */
+    component: {
+        /** 组件名称 */
+        name: string;
+        /** 组件版本 */
+        version: string;
+    };
+    /** 上下文数据（Component 特定） */
+    data: T;
+    /** 元数据（可用于传递额外信息） */
+    metadata: Record<string, unknown>;
+    /** 执行阶段 */
+    phase: HookPhase;
+    /** 关联的 hook 点名称 */
+    hookPoint: string;
+}
+/**
+ * 统一 Hook 接口
+ *
+ * 所有 Component 的 Hook 都应实现此接口
+ */
+export interface Hook<T = unknown> extends HookMeta {
+    /** 执行 Hook
+     * @param ctx 上下文
+     */
+    execute(ctx: HookContext<T>): void | Promise<void>;
+}
+/**
+ * Hook 函数类型（便捷别名）
+ */
+export type HookFn<T = unknown> = (ctx: HookContext<T>) => void | Promise<void>;
+/**
+ * Hook 干预动作类型
+ */
+export type HookActionType = "stop" | "retry" | "compress" | "extract_memory" | "inject_message" | "skip_tool" | "custom";
+/**
+ * Hook 干预动作
+ */
+export interface HookAction {
+    /** 动作类型 */
+    type: HookActionType;
+    /** 动作参数 */
+    params?: Record<string, unknown>;
+    /** 动作描述 */
+    description?: string;
+}
+/**
+ * Hook 执行结果
+ */
+export interface HookResult {
+    /** 是否被停止 */
+    stopped?: boolean;
+    /** 干预动作（如果有） */
+    action?: HookAction;
+    /** 执行结果数据 */
+    results?: unknown[];
+}
+/**
+ * 创建 Hook 的工厂函数
+ *
+ * @param meta Hook 元信息
+ * @param fn 执行函数
+ * @returns Hook 实例
+ *
+ * @example
+ * ```typescript
+ * const hook = createHook(
+ *   { name: "my-hook", priority: 10 },
+ *   async (ctx) => { console.log(ctx.data); }
+ * );
+ * ```
+ */
+export declare function createHook<T = unknown>(meta: HookMeta, fn: HookFn<T>): Hook<T>;
+/**
+ * 创建带优先级的 Hook 的便捷函数
+ */
+export declare function createPriorityHook<T = unknown>(name: string, fn: HookFn<T>, priority: number): Hook<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/src/env/hook/types.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Hook 系统统一类型定义
+ *
+ * 提供所有 Component 使用的统一 Hook 接口
+ */
+/**
+ * 创建 Hook 的工厂函数
+ *
+ * @param meta Hook 元信息
+ * @param fn 执行函数
+ * @returns Hook 实例
+ *
+ * @example
+ * ```typescript
+ * const hook = createHook(
+ *   { name: "my-hook", priority: 10 },
+ *   async (ctx) => { console.log(ctx.data); }
+ * );
+ * ```
+ */
+export function createHook(meta, fn) {
+    return {
+        ...meta,
+        execute: fn,
+    };
+}
+/**
+ * 创建带优先级的 Hook 的便捷函数
+ */
+export function createPriorityHook(name, fn, priority) {
+    return createHook({ name, priority }, fn);
+}
+//# sourceMappingURL=types.js.map