@ai-setting/roy-agent-core 1.0.0

package/src/env/llm/llm.ts

@@ -0,0 +1,568 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import { type LLMConfig, type LLMInvokeRequest, type LLMInvokeResult, type LLMMessage, type ModelLimits } from "./types";
+import { invoke, type InvokeConfig } from "./invoke";
+import type { ConfigComponent } from "../../config/config-component";
+import { createLogger } from "../log-trace/logger";
+import { TracedAs } from "../log-trace/decorator";
+import { toEnvKey, envKeyToConfigKey } from "../../config/env-key";
+import { ContextError, ErrorCodes } from "../errors";
+
+// 创建 llm 模块日志器
+const logger = createLogger("llm");
+
+/**
+ * LLM 调用上下文（共享数据）
+ */
+interface InvokeContext {
+  providerId: string;
+  model: string;
+  invokeConfig: InvokeConfig;
+  messages: LLMMessage[];
+  temperature: number;
+  maxTokens: number;
+  topP: number;
+  abortSignal: AbortSignal | undefined;
+}
+
+/**
+ * LLMComponent 配置（通过 options.config 传递）
+ * 
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ * 
+ * 环境变量转换规则：
+ * - 驼峰命名会被转换为下划线分隔的大写形式
+ * - 例如: "llm.defaultModel" + prefix "LLM" -> "LLM_LLM_DEFAULT_MODEL"
+ */
+export interface LLMComponentOptions {
+  /** ConfigComponent 实例（必填） */
+  configComponent: ConfigComponent;
+  
+  /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+  configPath?: string;
+  
+  /** 环境变量前缀（可选，默认 "LLM"） */
+  envPrefix?: string;
+  
+  /** 直接传入的配置对象（可选，优先级最高） */
+  config?: Partial<LLMConfig>;
+}
+
+/**
+ * LLMComponent
+ * 管理 LLM 调用，使用 AI SDK 进行实际调用
+ * 
+ * 配置通过 ConfigComponent 实时获取，支持配置热更新
+ * 
+ * @example
+ * // 通过 ConfigComponent 加载配置
+ * const configComponent = new ConfigComponent();
+ * configComponent.setXdgDataHome(__dirname);
+ * 
+ * const llmComponent = new LLMComponent();
+ * await llmComponent.init({
+ *   env,  // Environment 实例（必填）
+ *   options: {
+ *     configComponent,  // ConfigComponent 实例
+ *     configPath: "config.jsonc"  // 配置文件路径
+ *   }
+ * });
+ * 
+ * // 配置更新后，下次调用会自动获取最新配置
+ * configComponent.set("llm.temperature", 0.5);
+ */
+export class LLMComponent extends BaseComponent {
+  readonly name = "llm";
+  readonly version = "2.0.0";
+
+  private configComponent?: ConfigComponent;
+  
+  /** 配置变更 watcher 清理函数 */
+  private configWatcher?: () => void;
+
+  constructor() {
+    super();
+  }
+
+  /**
+   * 初始化组件
+   * 
+   * 配置加载优先级（从高到低）：
+   * 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 LLMComponentOptions | undefined;
+    if (!options?.configComponent) {
+      throw new Error("ConfigComponent is required for LLMComponent initialization");
+    }
+
+    this.configComponent = options.configComponent;
+    await this.registerConfig(options);
+
+    this.setStatus("running");
+  }
+
+  /**
+   * 注册配置到 ConfigComponent
+   * 
+   * 配置加载顺序（优先级从低到高）：
+   * 1. FileSource - 从配置文件加载（最低）
+   * 2. EnvSource - 从环境变量加载（中等）
+   * 3. MemorySource - 直接配置对象（最高）
+   */
+  private async registerConfig(options: LLMComponentOptions): Promise<void> {
+    const configComponent = options.configComponent;
+    if (!configComponent) return;
+
+    const { configPath, envPrefix, config } = options;
+    const prefix = envPrefix !== undefined ? envPrefix : "LLM";
+
+    // 获取所有已注册的 keys
+    const llmKeys = [
+      "llm.defaultModel",
+      "llm.defaultProvider",
+      "llm.temperature",
+      "llm.maxTokens",
+      "llm.topP",
+      "llm.stream",
+      "llm.providers",
+      "llm.limits",
+      "llm.capabilities",
+    ];
+
+    // 1. 注册并加载 FileSource（如果提供了 configPath）
+    let fileSource: any = null;
+    if (configPath) {
+      configComponent.registerSource({
+        type: "file",
+        relativePath: configPath,
+        optional: true,
+        watch: false
+      });
+      
+      // 确保 source 已创建
+      (configComponent as any).ensureSourcesCreated?.();
+      
+      // 获取 file source
+      const sources = configComponent.getSources?.() || [];
+      fileSource = sources.find((s: any) => s.name === "file");
+      
+      // 加载 file 配置到 memory
+      if (fileSource) {
+        for (const key of llmKeys) {
+          const value = fileSource.read?.(key);
+          if (value !== undefined) {
+            await configComponent.set(key, value);
+          }
+        }
+      }
+    }
+
+    // 2. 注册并加载 EnvSource
+    configComponent.registerSource({
+      type: "env",
+      envPrefix: prefix,
+      priority: 20,
+      watch: false
+    });
+    
+    // 确保 source 已创建
+    (configComponent as any).ensureSourcesCreated?.();
+    
+    // 获取 env source
+    const sourcesAfterEnv = configComponent.getSources?.() || [];
+    const envSource = sourcesAfterEnv.find((s: any) => s.name === "env");
+    
+    // 加载 env 配置到 memory（覆盖 file）
+    if (envSource) {
+      for (const key of llmKeys) {
+        const value = envSource.read?.(key);
+        if (value !== undefined) {
+          await configComponent.set(key, value);
+        }
+      }
+    }
+    
+    // 后备方案：直接读取环境变量
+    // 1. 先检查预定义的 llmKeys
+    for (const key of llmKeys) {
+      const envKey = toEnvKey(key, prefix);
+      const value = process.env[envKey];
+      if (value !== undefined) {
+        await configComponent.set(key, value);
+      }
+    }
+    
+    // 2. 自动发现并加载所有以 prefix 开头的 llm.* 环境变量
+    const loadedKeys = new Set(llmKeys); // 记录已加载的 keys，避免重复
+    for (const envKey of Object.keys(process.env)) {
+      const configKey = envKeyToConfigKey(envKey, prefix, "llm");
+      if (!configKey) continue;
+      
+      // 避免重复加载
+      if (loadedKeys.has(configKey)) continue;
+      loadedKeys.add(configKey);
+      
+      const value = process.env[envKey];
+      if (value !== undefined) {
+        await configComponent.set(configKey, value);
+      }
+    }
+
+    // 3. 如果有直接配置对象，覆盖到 MemorySource（优先级最高）
+    if (config) {
+      const flatConfig = this.flattenConfig(config);
+      for (const [key, value] of Object.entries(flatConfig)) {
+        await configComponent.set(key, value);
+      }
+    }
+
+    // 4. 注册配置热更新监听
+    this.registerConfigWatcher(configComponent);
+  }
+
+  /**
+   * 将配置对象展平为点号路径
+   * 
+   * @example
+   * flattenConfig({ providers: { openai: { apiKey: "xxx" } } })
+   * -> { "llm.providers.openai.apiKey": "xxx" }
+   */
+  private flattenConfig(
+    obj: Record<string, unknown>,
+    prefix = "llm"
+  ): 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 {
+    // 检查 watch 方法是否存在
+    if (typeof configComponent.watch !== "function") {
+      logger.debug("ConfigComponent does not support watch, hot reload disabled");
+      return;
+    }
+    
+    // 注册热更新监听
+    this.configWatcher = configComponent.watch("llm.*", (event) => {
+      this.onConfigChange(event);
+    });
+    
+    logger.debug("Config hot reload watcher registered for llm.*");
+  }
+  
+  /**
+   * 处理配置变更（支持热更新）
+   */
+  protected onConfigChange(event: { key: string; oldValue?: unknown; newValue?: unknown }): void {
+    logger.info(`LLM config changed: ${event.key}`);
+    
+    // 根据变更的 key 类型进行处理
+    if (event.key === "llm.providers" || event.key.startsWith("llm.providers.")) {
+      // Provider 配置变更，记录日志
+      // 注意：getProvider/getLLMConfig 会实时从 configComponent 读取，所以不需要显式重新加载
+      logger.info(`LLM provider config changed, will use new config on next call`);
+    } else if (event.key === "llm.defaultModel") {
+      logger.info(`LLM default model changed to: ${event.newValue}`);
+    } else if (event.key === "llm.defaultProvider") {
+      logger.info(`LLM default provider changed to: ${event.newValue}`);
+    } else {
+      logger.debug(`LLM config updated: ${event.key}`);
+    }
+  }
+
+  /**
+   * 启动组件
+   */
+  async onStart(): Promise<void> {
+    if (this._status === "stopped") {
+      this.setStatus("running");
+    }
+  }
+
+  /**
+   * 停止组件
+   */
+  async onStop(): Promise<void> {
+    // 清理配置热更新 watcher
+    this.configWatcher?.();
+    this.configWatcher = undefined;
+    
+    this.setStatus("stopped");
+  }
+
+  /**
+   * 从配置源获取配置值
+   * 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+   */
+  private getLLMConfig<T>(key: string, defaultValue?: T): T {
+    // 优先从 ConfigComponent 获取（实时）
+    if (this.configComponent) {
+      const value = this.configComponent.get(key);
+      if (value !== undefined) {
+        return value as T;
+      }
+    }
+    
+    return defaultValue!;
+  }
+
+  /**
+   * 解析请求，构建调用上下文（invoke 和 invokeStream 共享）
+   */
+  private resolveRequest(request: LLMInvokeRequest): InvokeContext {
+    // 实时获取配置
+    const defaultModel = this.getLLMConfig<string>("llm.defaultModel", "gpt-4o");
+    const defaultProvider = this.getLLMConfig<string>("llm.defaultProvider", "openai");
+    const defaultTemperature = this.getLLMConfig<number>("llm.temperature", 0.7);
+    const defaultMaxTokens = this.getLLMConfig<number>("llm.maxTokens", 4096);
+    const defaultTopP = this.getLLMConfig<number>("llm.topP", 1.0);
+
+    // 确定模型
+    const model = request.model || defaultModel;
+    const providerId = request.providerId || defaultProvider;
+
+    // 获取 API Key
+    const apiKey = this.getApiKey(providerId);
+    if (!apiKey) {
+      throw new Error(`API key not found for provider ${providerId}. Set providers.${providerId}.apiKey in config, or use \${env://...} protocol in config file.`);
+    }
+
+    // 构建消息
+    const messages: LLMMessage[] = request.messages.map((msg) => ({
+      role: msg.role,
+      content: msg.content,
+      name: msg.name,
+      toolCallId: (msg as any).toolCallId,  // 保留 toolCallId 字段
+      toolCalls: (msg as any).toolCalls,     // 保留 toolCalls 字段
+    }));
+
+    return {
+      providerId,
+      model,
+      invokeConfig: {
+        model: `${providerId}/${model}`,
+        apiKey,
+        baseURL: this.getProvider(providerId)?.baseURL,
+      },
+      messages,
+      temperature: request.temperature ?? defaultTemperature,
+      maxTokens: request.maxTokens ?? defaultMaxTokens,
+      topP: request.topP ?? defaultTopP,
+      abortSignal: request.abortSignal,
+    };
+  }
+
+  /**
+   * 调用 LLM
+   * 
+   * 流式事件通过 env.pushEnvEvent() 发布
+   */
+  @TracedAs("llm.component.invoke", { recordParams: true, recordResult: true, log: true })
+  async invoke(request: LLMInvokeRequest): Promise<LLMInvokeResult> {
+    const startTime = Date.now();
+
+    if (this._status !== "running") {
+      throw new Error("LLMComponent is not running");
+    }
+
+    const ctx = this.resolveRequest(request);
+
+    let output: { content: string; reasoning?: string; finishReason: "length" | "stop" | "content-filter" | "tool-calls" | "function-call"; toolCalls?: any[]; usage?: { promptTokens: number; completionTokens: number; totalTokens: number } } = {
+      content: "",
+      reasoning: undefined,
+      finishReason: "stop",
+    };
+    let finishUsage: { promptTokens: number; completionTokens: number; totalTokens: number } | undefined;
+
+    const result = await invoke(
+      ctx.invokeConfig,
+      {
+        messages: ctx.messages,
+        model: ctx.invokeConfig.model,
+        temperature: ctx.temperature,
+        maxTokens: ctx.maxTokens,
+        tools: request.tools,
+        env: this.env,
+        context: {
+          sessionId: request.context?.sessionId,
+          messageId: request.context?.messageId,
+        },
+      },
+      { abort: ctx.abortSignal }
+    );
+
+    if (result.isError) {
+      throw new Error(result.result);
+    }
+
+    // 解析 ToolResult
+    try {
+      const parsed = JSON.parse(result.result);
+      output.content = parsed.content || "";
+      output.reasoning = parsed.reasoning || undefined;  // 提取 reasoning 内容
+      output.finishReason = parsed.tool_calls?.length ? "tool-calls" : "stop";
+      output.toolCalls = parsed.tool_calls || [];
+      if (parsed.usage) {
+        finishUsage = {
+          promptTokens: parsed.usage.promptTokens ?? parsed.usage.inputTokens ?? 0,
+          completionTokens: parsed.usage.completionTokens ?? parsed.usage.outputTokens ?? 0,
+          totalTokens: parsed.usage.totalTokens ?? 0,
+        };
+      }
+      output.usage = finishUsage;
+    } catch {
+      output.content = result.result;
+      output.finishReason = "stop";
+    }
+
+    // 计算耗时
+    const latencyMs = Date.now() - startTime;
+
+    // 检测上下文阈值（除非 skipThresholdCheck 为 true）
+    if (!request.skipThresholdCheck) {
+      const sessionId = request.context?.sessionId;
+      const contextError = this.checkContextThreshold(
+        finishUsage,
+        ctx.providerId,
+        ctx.model,
+        sessionId
+      );
+      
+      if (contextError) {
+        throw contextError;
+      }
+    }
+
+    return {
+      output,
+      providerId: ctx.providerId,
+      model: ctx.model,
+      latencyMs,
+    };
+  }
+
+  /**
+   * 获取 Provider API Key
+   */
+  private getApiKey(providerId: string): string | undefined {
+    const providers = this.getLLMConfig<LLMConfig["providers"]>("llm.providers", {});
+    return providers?.[providerId]?.apiKey;
+  }
+
+  /**
+   * 获取 Provider
+   */
+  getProvider(id: string) {
+    const providers = this.getLLMConfig<LLMConfig["providers"]>("llm.providers", {});
+    return providers?.[id];
+  }
+
+  /**
+   * 列出所有 Provider
+   */
+  listProviders() {
+    const providers = this.getLLMConfig<LLMConfig["providers"]>("llm.providers", {});
+    return Object.keys(providers || {});
+  }
+
+  /**
+   * 获取模型的限制配置
+   * 
+   * @param providerId - Provider ID
+   * @param modelId - 模型 ID（可选，默认使用 provider 的 defaultModel）
+   * @returns 模型限制配置，如果没有配置则返回 undefined
+   */
+  getModelLimits(providerId: string, modelId?: string): ModelLimits | undefined {
+    const provider = this.getProvider(providerId);
+    if (!provider?.limits) return undefined;
+
+    // 如果没有指定 modelId，尝试获取 provider 的默认模型
+    const targetModel = modelId || provider.defaultModel;
+    if (!targetModel) return undefined;
+
+    return provider.limits[targetModel];
+  }
+
+  /**
+   * 获取上下文窗口阈值配置
+   * 
+   * @param providerId - Provider ID
+   * @param modelId - 模型 ID
+   * @returns 包含 contextWindow 和 thresholdRatio 的对象
+   */
+  getContextThresholdConfig(providerId: string, modelId?: string): { contextWindow: number; thresholdRatio: number } {
+    // 默认值
+    const defaults = {
+      contextWindow: 128000,  // 默认 128K 上下文窗口
+      thresholdRatio: 0.9,    // 默认 90% 时触发
+    };
+
+    const limits = this.getModelLimits(providerId, modelId);
+    if (!limits) return defaults;
+
+    return {
+      contextWindow: limits.contextWindow || defaults.contextWindow,
+      thresholdRatio: limits.compactionThreshold ?? defaults.thresholdRatio,
+    };
+  }
+
+  /**
+   * 检测上下文阈值是否超过
+   * 
+   * @param usage - LLM 使用量信息
+   * @param providerId - Provider ID
+   * @param modelId - 模型 ID
+   * @param sessionId - Session ID（用于错误信息）
+   * @returns 如果超过阈值，返回 ContextError；否则返回 undefined
+   */
+  checkContextThreshold(
+    usage: { totalTokens: number; promptTokens?: number; completionTokens?: number } | undefined,
+    providerId: string,
+    modelId: string | undefined,
+    sessionId?: string
+  ): ContextError | undefined {
+    if (!usage) return undefined;
+
+    const config = this.getContextThresholdConfig(providerId, modelId);
+    const threshold = config.contextWindow * config.thresholdRatio;
+
+    if (usage.totalTokens >= threshold) {
+      return new ContextError(
+        `Context threshold exceeded: ${usage.totalTokens}/${config.contextWindow} (${(usage.totalTokens / config.contextWindow * 100).toFixed(1)}%)`,
+        ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED,
+        sessionId,
+        {
+          promptTokens: usage.promptTokens ?? 0,
+          completionTokens: usage.completionTokens ?? 0,
+          totalTokens: usage.totalTokens,
+        },
+        config.contextWindow
+      );
+    }
+
+    return undefined;
+  }
+}