@ai-setting/roy-agent-core 1.0.0

package/src/env/llm/hooks.test.ts

@@ -0,0 +1,293 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { LLMHooks, type LLMBeforeInvokeHook, type LLMAfterInvokeHook, type LLMStreamHook, type LLMHookContext } from "./hooks";
+import { globalHookManager } from "../hook/global-hook-manager";
+import type { LLMInvokeRequest, LLMInvokeResult, LLMOutput, StreamEvent } from "./types";
+
+describe("LLMHooks", () => {
+  let hooks: LLMHooks;
+
+  beforeEach(() => {
+    hooks = new LLMHooks();
+    // 清理 globalHookManager 中的 hooks
+    globalHookManager.clear();
+  });
+
+  afterEach(() => {
+    // 清理 globalHookManager 中的 hooks
+    globalHookManager.clear();
+  });
+
+  describe("constructor", () => {
+    test("should create instance with empty hooks", () => {
+      expect(hooks.getHooks()).toEqual([]);
+    });
+  });
+
+  describe("register", () => {
+    test("should register before invoke hook", () => {
+      const hook: LLMBeforeInvokeHook = async (context) => {
+        // 可以在此处修改 context.request
+      };
+
+      hooks.register("before-invoke", hook);
+      expect(hooks.getHooks()).toHaveLength(1);
+      expect(hooks.getHooks()[0].type).toBe("before-invoke");
+    });
+
+    test("should register after invoke hook", () => {
+      const hook: LLMAfterInvokeHook = async (context) => {
+        // 可以在此处处理结果
+      };
+
+      hooks.register("after-invoke", hook);
+      expect(hooks.getHooks()).toHaveLength(1);
+    });
+
+    test("should register stream hook", () => {
+      const hook: LLMStreamHook = async (context, event) => {
+        // 可以在此处处理流事件
+      };
+
+      hooks.register("stream", hook);
+      expect(hooks.getHooks()).toHaveLength(1);
+    });
+
+    test("should register multiple hooks", () => {
+      hooks.register("before-invoke", async () => {});
+      hooks.register("after-invoke", async () => {});
+      hooks.register("stream", async () => {});
+
+      expect(hooks.getHooks()).toHaveLength(3);
+    });
+
+    test("should register named hooks", () => {
+      hooks.register("before-invoke", async () => {}, "custom-before-hook");
+      hooks.register("after-invoke", async () => {}, "custom-after-hook");
+
+      const allHooks = hooks.getHooks();
+      expect(allHooks[0].name).toBe("custom-before-hook");
+      expect(allHooks[1].name).toBe("custom-after-hook");
+    });
+  });
+
+  describe("unregister", () => {
+    test("should unregister hook by reference", () => {
+      const hook = async () => {};
+      hooks.register("before-invoke", hook);
+      hooks.register("before-invoke", async () => {});
+
+      expect(hooks.getHooks()).toHaveLength(2);
+
+      hooks.unregister(hook);
+      expect(hooks.getHooks()).toHaveLength(1);
+    });
+
+    test("should unregister hook by name", () => {
+      hooks.register("before-invoke", async () => {}, "hook1");
+      hooks.register("before-invoke", async () => {}, "hook2");
+
+      expect(hooks.getHooks()).toHaveLength(2);
+
+      hooks.unregisterByName("hook1");
+      expect(hooks.getHooks()).toHaveLength(1);
+      expect(hooks.getHooks()[0].name).toBe("hook2");
+    });
+
+    test("should unregister all hooks of a type", () => {
+      hooks.register("before-invoke", async () => {});
+      hooks.register("after-invoke", async () => {});
+      hooks.register("stream", async () => {});
+
+      hooks.unregisterByType("before-invoke");
+      expect(hooks.getHooks()).toHaveLength(2);
+    });
+  });
+
+  describe("clear", () => {
+    test("should clear all hooks", () => {
+      hooks.register("before-invoke", async () => {});
+      hooks.register("after-invoke", async () => {});
+
+      hooks.clear();
+      expect(hooks.getHooks()).toEqual([]);
+    });
+  });
+
+  describe("executeBeforeInvoke", () => {
+    test("should execute before-invoke hooks in order", async () => {
+      const executionOrder: string[] = [];
+
+      hooks.register("before-invoke", async () => {
+        executionOrder.push("hook1");
+      });
+      hooks.register("before-invoke", async () => {
+        executionOrder.push("hook2");
+      });
+
+      const context: LLMHookContext = {
+        request: { messages: [] },
+        providerId: "openai",
+        model: "gpt-4",
+      };
+
+      // 使用新的直接调用 globalHookManager 的方式
+      await globalHookManager.execute("llm:before.invoke", context);
+
+      expect(executionOrder).toEqual(["hook1", "hook2"]);
+    });
+
+    test("should allow hooks to modify context", async () => {
+      hooks.register("before-invoke", async (ctx) => {
+        ctx.request.messages = [
+          { role: "system", content: "You are helpful" },
+          ...ctx.request.messages,
+        ];
+      });
+
+      const context: LLMHookContext = {
+        request: { messages: [{ role: "user", content: "Hello" }] },
+        providerId: "openai",
+        model: "gpt-4",
+      };
+
+      await globalHookManager.execute("llm:before.invoke", context);
+
+      expect(context.request.messages).toHaveLength(2);
+      expect(context.request.messages[0].role).toBe("system");
+    });
+
+    test("should isolate errors and continue executing remaining hooks", async () => {
+      const executionOrder: string[] = [];
+
+      hooks.register("before-invoke", async () => {
+        executionOrder.push("hook1");
+      });
+      hooks.register("before-invoke", async () => {
+        throw new Error("Hook error");
+      });
+      hooks.register("before-invoke", async () => {
+        executionOrder.push("hook3");
+      });
+
+      const context: LLMHookContext = {
+        request: { messages: [] },
+        providerId: "openai",
+        model: "gpt-4",
+      };
+
+      // HookManager 会捕获错误并继续执行（错误隔离）
+      await globalHookManager.execute("llm:before.invoke", context);
+      // 错误被隔离，后续 hooks 继续执行
+      expect(executionOrder).toEqual(["hook1", "hook3"]);
+    });
+  });
+
+  describe("executeAfterInvoke", () => {
+    test("should execute after-invoke hooks in order", async () => {
+      const executionOrder: string[] = [];
+
+      hooks.register("after-invoke", async (ctx) => {
+        executionOrder.push("hook1");
+      });
+      hooks.register("after-invoke", async (ctx) => {
+        executionOrder.push("hook2");
+      });
+
+      const context: LLMHookContext = {
+        request: { messages: [] },
+        providerId: "openai",
+        model: "gpt-4",
+      };
+
+      const result: LLMInvokeResult = {
+        output: { content: "test", finishReason: "stop" },
+        providerId: "openai",
+        model: "gpt-4",
+        latencyMs: 100,
+      };
+
+      await globalHookManager.execute("llm:after.invoke", { ...context, result });
+
+      expect(executionOrder).toEqual(["hook1", "hook2"]);
+    });
+
+    test("should allow hooks to modify result", async () => {
+      hooks.register("after-invoke", async (ctx, result) => {
+        result.output.content = result.output.content + " [modified]";
+      });
+
+      const context: LLMHookContext = {
+        request: { messages: [] },
+        providerId: "openai",
+        model: "gpt-4",
+      };
+
+      const result: LLMInvokeResult = {
+        output: { content: "original", finishReason: "stop" },
+        providerId: "openai",
+        model: "gpt-4",
+        latencyMs: 100,
+      };
+
+      await globalHookManager.execute("llm:after.invoke", { ...context, result });
+
+      expect(result.output.content).toBe("original [modified]");
+    });
+  });
+
+  describe("executeStream", () => {
+    test("should execute stream hooks", async () => {
+      const events: StreamEvent[] = [];
+
+      hooks.register("stream", async (ctx, event) => {
+        events.push(event);
+      });
+
+      const context: LLMHookContext = {
+        request: { messages: [] },
+        providerId: "openai",
+        model: "gpt-4",
+      };
+
+      const event: StreamEvent = { type: "text", content: "Hello" };
+      await hooks.executeStream(context, event);
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual(event);
+    });
+
+    test("should allow hooks to modify stream event", async () => {
+      hooks.register("stream", async (ctx, event) => {
+        if (event.type === "text") {
+          event.content = event.content.toUpperCase();
+        }
+      });
+
+      const context: LLMHookContext = {
+        request: { messages: [] },
+        providerId: "openai",
+        model: "gpt-4",
+      };
+
+      const event: StreamEvent = { type: "text", content: "hello" };
+      await hooks.executeStream(context, event);
+
+      expect(event.content).toBe("HELLO");
+    });
+  });
+
+  describe("getHooksByType", () => {
+    test("should return hooks of specific type", () => {
+      hooks.register("before-invoke", async () => {});
+      hooks.register("after-invoke", async () => {});
+      hooks.register("before-invoke", async () => {});
+      hooks.register("stream", async () => {});
+
+      const beforeHooks = hooks.getHooksByType("before-invoke");
+      expect(beforeHooks).toHaveLength(2);
+
+      const afterHooks = hooks.getHooksByType("after-invoke");
+      expect(afterHooks).toHaveLength(1);
+    });
+  });
+});

package/src/env/llm/hooks.ts

@@ -0,0 +1,316 @@
+import type { LLMInvokeRequest, LLMInvokeResult, LLMOutput, StreamEvent } from "./types";
+import { globalHookManager, LLMHookPoints } from "../hook/global-hook-manager";
+
+/**
+ * LLM Hook 类型（兼容旧接口）
+ */
+export type LLMHookType = "before-invoke" | "after-invoke" | "stream";
+
+/**
+ * LLM Hook 上下文
+ */
+export interface LLMHookContext {
+  /** 请求 */
+  request: LLMInvokeRequest;
+  /** Provider ID */
+  providerId: string;
+  /** 模型名称 */
+  model: string;
+  /** 元数据 */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Before Invoke Hook
+ * 在 LLM 调用之前执行，可以修改请求
+ */
+export type LLMBeforeInvokeHook = (context: LLMHookContext) => Promise<void>;
+
+/**
+ * After Invoke Hook
+ * 在 LLM 调用之后执行，可以处理结果
+ */
+export type LLMAfterInvokeHook = (
+  context: LLMHookContext,
+  result: LLMInvokeResult
+) => Promise<void>;
+
+/**
+ * Stream Hook
+ * 在流式调用时处理每个事件
+ */
+export type LLMStreamHook = (
+  context: LLMHookContext,
+  event: StreamEvent
+) => Promise<void>;
+
+/**
+ * Hook 注册项
+ */
+export interface LLMHookRegistration {
+  /** Hook 类型 */
+  type: LLMHookType;
+  /** Hook 名称（可选，用于标识） */
+  name?: string;
+  /** Before Invoke Hook */
+  beforeInvoke?: LLMBeforeInvokeHook;
+  /** After Invoke Hook */
+  afterInvoke?: LLMAfterInvokeHook;
+  /** Stream Hook */
+  stream?: LLMStreamHook;
+}
+
+/**
+ * LLMHookManager
+ * 
+ * 代理到 globalHookManager 的 LLM Hook 管理器
+ * 
+ * @deprecated 请直接使用 globalHookManager.register() 注册 hooks
+ */
+export class LLMHookManager {
+  private registrations: LLMHookRegistration[] = [];
+
+  /**
+   * 注册 Hook
+   */
+  register(
+    type: LLMHookType,
+    handler: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook,
+    name?: string
+  ): void {
+    const registration: LLMHookRegistration = {
+      type,
+      name,
+    };
+
+    switch (type) {
+      case "before-invoke":
+        registration.beforeInvoke = handler as LLMBeforeInvokeHook;
+        break;
+      case "after-invoke":
+        registration.afterInvoke = handler as LLMAfterInvokeHook;
+        break;
+      case "stream":
+        registration.stream = handler as LLMStreamHook;
+        break;
+    }
+
+    this.registrations.push(registration);
+    
+    // 注册到 globalHookManager
+    this.registerToGlobal(registration);
+  }
+
+  /**
+   * 注册单个 registration 到 globalHookManager
+   */
+  private registerToGlobal(reg: LLMHookRegistration): void {
+    const hookName = `llm:${reg.name || `anon-${reg.type}-${this.registrations.indexOf(reg)}`}`;
+
+    if (reg.beforeInvoke) {
+      globalHookManager.register(LLMHookPoints.BEFORE_INVOKE, {
+        name: hookName,
+        priority: 0,
+        execute: async (ctx) => {
+          await reg.beforeInvoke!(ctx.data as LLMHookContext);
+        },
+      });
+    }
+
+    if (reg.afterInvoke) {
+      globalHookManager.register(LLMHookPoints.AFTER_INVOKE, {
+        name: hookName,
+        priority: 0,
+        execute: async (ctx) => {
+          const { request, providerId, model, metadata, result } = ctx.data as LLMHookContext & { result: LLMInvokeResult };
+          await reg.afterInvoke!({ request, providerId, model, metadata }, result);
+        },
+      });
+    }
+
+    if (reg.stream) {
+      globalHookManager.register(LLMHookPoints.ON_STREAM, {
+        name: hookName,
+        priority: 0,
+        execute: async (ctx) => {
+          const { request, providerId, model, metadata, event } = ctx.data as LLMHookContext & { event: StreamEvent };
+          await reg.stream!({ request, providerId, model, metadata }, event);
+        },
+      });
+    }
+  }
+
+  /**
+   * 取消注册 Hook
+   */
+  unregister(hook: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook): void {
+    const index = this.registrations.findIndex((h) => {
+      return h.beforeInvoke === hook || h.afterInvoke === hook || h.stream === hook;
+    });
+    
+    if (index !== -1) {
+      const reg = this.registrations[index];
+      this.unregisterFromGlobal(reg);
+      this.registrations.splice(index, 1);
+    }
+  }
+
+  /**
+   * 从 globalHookManager 取消注册
+   */
+  private unregisterFromGlobal(reg: LLMHookRegistration): void {
+    const hookName = `llm:${reg.name || `anon-${reg.type}`}`;
+    globalHookManager.unregister(LLMHookPoints.BEFORE_INVOKE, hookName);
+    globalHookManager.unregister(LLMHookPoints.AFTER_INVOKE, hookName);
+    globalHookManager.unregister(LLMHookPoints.ON_STREAM, hookName);
+  }
+
+  /**
+   * 按名称取消注册 Hook
+   */
+  unregisterByName(name: string): void {
+    const hookName = `llm:${name}`;
+    globalHookManager.unregister(LLMHookPoints.BEFORE_INVOKE, hookName);
+    globalHookManager.unregister(LLMHookPoints.AFTER_INVOKE, hookName);
+    globalHookManager.unregister(LLMHookPoints.ON_STREAM, hookName);
+    this.registrations = this.registrations.filter((h) => h.name !== name);
+  }
+
+  /**
+   * 按类型取消注册所有 Hook
+   */
+  unregisterByType(type: LLMHookType): void {
+    const filtered = this.registrations.filter((h) => h.type === type);
+    for (const reg of filtered) {
+      this.unregisterFromGlobal(reg);
+    }
+    this.registrations = this.registrations.filter((h) => h.type !== type);
+  }
+
+  /**
+   * 清空所有 Hook
+   */
+  clear(): void {
+    for (const reg of this.registrations) {
+      this.unregisterFromGlobal(reg);
+    }
+    this.registrations = [];
+  }
+
+  /**
+   * 获取所有 Hook
+   */
+  getHooks(): LLMHookRegistration[] {
+    return [...this.registrations];
+  }
+
+  /**
+   * 按类型获取 Hook
+   */
+  getHooksByType(type: LLMHookType): LLMHookRegistration[] {
+    return this.registrations.filter((h) => h.type === type);
+  }
+}
+
+/**
+ * LLMHooks
+ * 
+ * 兼容旧接口，内部委托给 globalHookManager
+ * 
+ * @deprecated 请直接使用 globalHookManager
+ */
+export class LLMHooks {
+  private hookManager = new LLMHookManager();
+
+  /**
+   * 注册 Hook
+   */
+  register(
+    type: LLMHookType,
+    handler: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook,
+    name?: string
+  ): void {
+    this.hookManager.register(type, handler, name);
+  }
+
+  /**
+   * 取消注册 Hook
+   */
+  unregister(hook: LLMBeforeInvokeHook | LLMAfterInvokeHook | LLMStreamHook): void {
+    this.hookManager.unregister(hook);
+  }
+
+  /**
+   * 按名称取消注册 Hook
+   */
+  unregisterByName(name: string): void {
+    this.hookManager.unregisterByName(name);
+  }
+
+  /**
+   * 按类型取消注册所有 Hook
+   */
+  unregisterByType(type: LLMHookType): void {
+    this.hookManager.unregisterByType(type);
+  }
+
+  /**
+   * 清空所有 Hook
+   */
+  clear(): void {
+    this.hookManager.clear();
+  }
+
+  /**
+   * 获取所有 Hook
+   */
+  getHooks(): LLMHookRegistration[] {
+    return this.hookManager.getHooks();
+  }
+
+  /**
+   * 按类型获取 Hook
+   */
+  getHooksByType(type: LLMHookType): LLMHookRegistration[] {
+    return this.hookManager.getHooksByType(type);
+  }
+
+  /**
+   * 执行 Before Invoke Hooks
+   * 
+   * @deprecated 请使用 globalHookManager.execute(LLMHookPoints.BEFORE_INVOKE, ...)
+   */
+  async executeBeforeInvoke(context: LLMHookContext): Promise<void> {
+    await globalHookManager.execute(LLMHookPoints.BEFORE_INVOKE, context);
+  }
+
+  /**
+   * 执行 After Invoke Hooks
+   * 
+   * @deprecated 请使用 globalHookManager.execute(LLMHookPoints.AFTER_INVOKE, ...)
+   */
+  async executeAfterInvoke(
+    context: LLMHookContext,
+    result: LLMInvokeResult
+  ): Promise<void> {
+    await globalHookManager.execute(
+      LLMHookPoints.AFTER_INVOKE,
+      { ...context, result }
+    );
+  }
+
+  /**
+   * 执行 Stream Hooks
+   * 
+   * @deprecated 请使用 globalHookManager.execute(LLMHookPoints.ON_STREAM, ...)
+   */
+  async executeStream(
+    context: LLMHookContext,
+    event: StreamEvent
+  ): Promise<void> {
+    await globalHookManager.execute(
+      LLMHookPoints.ON_STREAM,
+      { ...context, event }
+    );
+  }
+}

package/src/env/llm/index.ts

@@ -0,0 +1,61 @@
+/**
+ * LLM Component
+ * 提供 LLM 调用能力
+ */
+
+// Types
+export {
+  type LLMMessage,
+  type LLMOutput,
+  type UsageInfo,
+  type ToolCall,
+  type ToolResult,
+  type ToolInfo,
+  type LLMConfig,
+  type LLMProvider,
+  type ProviderConfig,
+  type ProviderType,
+  type LLMInvokeRequest,
+  type LLMInvokeResult,
+  type StreamEvent,
+} from "./types";
+
+export {
+  LLMConfigSchema,
+  ProviderConfigSchema,
+  ProviderCapabilitiesSchema,
+  ModelLimitsSchema,
+  LLMDefaultConfigSchema,
+} from "./types";
+
+// Provider
+export { ProviderManager } from "./provider";
+
+// Transform
+export { LLMTransform } from "./transform";
+
+// Invoke (AI SDK integration)
+export {
+  invoke,
+  invokeNonStream,
+  parseModelString,
+  createInvokeConfig,
+  type InvokeConfig,
+  type InvokeOptions,
+  type LLMToolContext,
+  type ConvertedUsageInfo,
+} from "./invoke";
+
+// Hooks
+export {
+  type LLMHookType,
+  type LLMHookContext,
+  type LLMBeforeInvokeHook,
+  type LLMAfterInvokeHook,
+  type LLMStreamHook,
+  type LLMHookRegistration,
+  LLMHooks,
+} from "./hooks";
+
+// Component
+export { LLMComponent, type LLMComponentOptions } from "./llm";