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

package/dist/core/src/env/llm/llm.js

@@ -0,0 +1,461 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseComponent } from "../component.js";
+import { invoke } from "./invoke.js";
+import { createLogger } from "../log-trace/logger.js";
+import { TracedAs } from "../log-trace/decorator.js";
+import { toEnvKey, envKeyToConfigKey } from "../../config/env-key.js";
+import { ContextError, ErrorCodes } from "../errors.js";
+// 创建 llm 模块日志器
+const logger = createLogger("llm");
+/**
+ * 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 {
+    name = "llm";
+    version = "2.0.0";
+    configComponent;
+    /** 配置变更 watcher 清理函数 */
+    configWatcher;
+    constructor() {
+        super();
+    }
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    async init(config) {
+        // 调用基类 init，注入 env
+        await super.init(config);
+        // 从 options 获取 ConfigComponent
+        const options = config.options;
+        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 - 直接配置对象（最高）
+     */
+    async registerConfig(options) {
+        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 = null;
+        if (configPath) {
+            configComponent.registerSource({
+                type: "file",
+                relativePath: configPath,
+                optional: true,
+                watch: false
+            });
+            // 确保 source 已创建
+            configComponent.ensureSourcesCreated?.();
+            // 获取 file source
+            const sources = configComponent.getSources?.() || [];
+            fileSource = sources.find((s) => 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.ensureSourcesCreated?.();
+        // 获取 env source
+        const sourcesAfterEnv = configComponent.getSources?.() || [];
+        const envSource = sourcesAfterEnv.find((s) => 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" }
+     */
+    flattenConfig(obj, prefix = "llm") {
+        const result = {};
+        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, fullKey));
+            }
+            else {
+                result[fullKey] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * 注册配置热更新监听
+     */
+    registerConfigWatcher(configComponent) {
+        // 检查 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.*");
+    }
+    /**
+     * 处理配置变更（支持热更新）
+     */
+    onConfigChange(event) {
+        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() {
+        if (this._status === "stopped") {
+            this.setStatus("running");
+        }
+    }
+    /**
+     * 停止组件
+     */
+    async onStop() {
+        // 清理配置热更新 watcher
+        this.configWatcher?.();
+        this.configWatcher = undefined;
+        this.setStatus("stopped");
+    }
+    /**
+     * 从配置源获取配置值
+     * 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+     */
+    getLLMConfig(key, defaultValue) {
+        // 优先从 ConfigComponent 获取（实时）
+        if (this.configComponent) {
+            const value = this.configComponent.get(key);
+            if (value !== undefined) {
+                return value;
+            }
+        }
+        return defaultValue;
+    }
+    /**
+     * 解析请求，构建调用上下文（invoke 和 invokeStream 共享）
+     */
+    resolveRequest(request) {
+        // 实时获取配置
+        const defaultModel = this.getLLMConfig("llm.defaultModel", "gpt-4o");
+        const defaultProvider = this.getLLMConfig("llm.defaultProvider", "openai");
+        const defaultTemperature = this.getLLMConfig("llm.temperature", 0.7);
+        const defaultMaxTokens = this.getLLMConfig("llm.maxTokens", 4096);
+        const defaultTopP = this.getLLMConfig("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 = request.messages.map((msg) => ({
+            role: msg.role,
+            content: msg.content,
+            name: msg.name,
+            toolCallId: msg.toolCallId, // 保留 toolCallId 字段
+            toolCalls: msg.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() 发布
+     */
+    async invoke(request) {
+        const startTime = Date.now();
+        if (this._status !== "running") {
+            throw new Error("LLMComponent is not running");
+        }
+        const ctx = this.resolveRequest(request);
+        let output = {
+            content: "",
+            reasoning: undefined,
+            finishReason: "stop",
+        };
+        let finishUsage;
+        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
+     */
+    getApiKey(providerId) {
+        const providers = this.getLLMConfig("llm.providers", {});
+        return providers?.[providerId]?.apiKey;
+    }
+    /**
+     * 获取 Provider
+     */
+    getProvider(id) {
+        const providers = this.getLLMConfig("llm.providers", {});
+        return providers?.[id];
+    }
+    /**
+     * 列出所有 Provider
+     */
+    listProviders() {
+        const providers = this.getLLMConfig("llm.providers", {});
+        return Object.keys(providers || {});
+    }
+    /**
+     * 获取模型的限制配置
+     *
+     * @param providerId - Provider ID
+     * @param modelId - 模型 ID（可选，默认使用 provider 的 defaultModel）
+     * @returns 模型限制配置，如果没有配置则返回 undefined
+     */
+    getModelLimits(providerId, modelId) {
+        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, modelId) {
+        // 默认值
+        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, providerId, modelId, sessionId) {
+        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;
+    }
+}
+__decorate([
+    TracedAs("llm.component.invoke", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], LLMComponent.prototype, "invoke", null);
+//# sourceMappingURL=llm.js.map

package/dist/core/src/env/llm/llm.test.d.ts

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

package/dist/core/src/env/llm/llm.test.js

@@ -0,0 +1,197 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "bun:test";
+import { LLMComponent } from "./llm.js";
+import { ConfigComponent } from "../../config/config-component.js";
+describe("LLMComponent", () => {
+    let component;
+    let configComponent;
+    let mockEnv;
+    beforeEach(() => {
+        component = new LLMComponent();
+        configComponent = new ConfigComponent();
+        // Mock environment
+        mockEnv = {
+            getComponent: vi.fn((name) => {
+                if (name === "config")
+                    return configComponent;
+                return undefined;
+            }),
+            hasComponent: vi.fn((name) => name === "config"),
+            logger: vi.fn(),
+            trace: vi.fn(),
+        };
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe("constructor", () => {
+        test("should create instance with correct name and version", () => {
+            expect(component.name).toBe("llm");
+            expect(component.version).toBe("2.0.0");
+        });
+        test("should have hookManager", () => {
+            expect(component.hookManager).toBeDefined();
+        });
+    });
+    describe("init", () => {
+        test("should initialize with ConfigComponent", async () => {
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            expect(component.getStatus()).toBe("running");
+        });
+        test("should throw error without ConfigComponent", async () => {
+            await expect(component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+            })).rejects.toThrow("ConfigComponent is required");
+        });
+    });
+    describe("hooks", () => {
+        test("should add hook", async () => {
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            const beforeFn = async () => { };
+            const afterFn = async () => { };
+            component.addHook("llm.before-invoke", "test-before-hook", beforeFn);
+            component.addHook("llm.after-invoke", "test-after-hook", afterFn);
+            // 通过 hookManager 验证 hooks 已注册
+            expect(component.hookManager.count("llm.before-invoke")).toBe(1);
+            expect(component.hookManager.count("llm.after-invoke")).toBe(1);
+        });
+        test("should remove hook", async () => {
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            const hookFn = async () => { };
+            component.addHook("llm.before-invoke", "test-hook", hookFn);
+            expect(component.hookManager.count("llm.before-invoke")).toBe(1);
+            component.removeHook("llm.before-invoke", "test-hook");
+            expect(component.hookManager.count("llm.before-invoke")).toBe(0);
+        });
+    });
+    describe("lifecycle", () => {
+        test("should transition through lifecycle states", async () => {
+            expect(component.getStatus()).toBe("created");
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            expect(component.getStatus()).toBe("running");
+            await component.onStop();
+            expect(component.getStatus()).toBe("stopped");
+            await component.onStart();
+            expect(component.getStatus()).toBe("running");
+        });
+    });
+    describe("invoke", () => {
+        test("should throw error when component is not running", async () => {
+            await expect(component.invoke({
+                messages: [{ role: "user", content: "Hello" }]
+            })).rejects.toThrow("LLMComponent is not running");
+        });
+        test("should throw error when apiKey is missing", async () => {
+            // ConfigComponent is empty, no API key configured
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            await expect(component.invoke({
+                messages: [{ role: "user", content: "Hello" }]
+            })).rejects.toThrow(/API key not found for provider/);
+        });
+        test("should throw error when provider does not exist", async () => {
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            await expect(component.invoke({
+                messages: [{ role: "user", content: "Hello" }],
+                providerId: "non-existent-provider"
+            })).rejects.toThrow(/API key not found for provider/);
+        });
+    });
+    describe("config hot reload", () => {
+        test("should register config watcher on init", async () => {
+            const watchSpy = vi.spyOn(configComponent, "watch");
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            // Verify watch was called for llm.* patterns
+            expect(watchSpy).toHaveBeenCalled();
+        });
+        test("should cleanup watcher on stop", async () => {
+            const watchSpy = vi.spyOn(configComponent, "watch");
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            // Get the unwatch function returned by watch
+            const watchCall = watchSpy.mock.calls[0];
+            const callback = watchCall?.[1];
+            // Stop should be successful (watcher cleaned up)
+            await component.onStop();
+            expect(component.getStatus()).toBe("stopped");
+        });
+        test("should handle provider config reload", async () => {
+            // Set providers config before init
+            configComponent.set("llm.providers", {
+                openai: {
+                    apiKey: "test-key",
+                    baseURL: "https://api.openai.com/v1"
+                }
+            });
+            await component.init({
+                name: "llm",
+                version: "1.0.0",
+                enabled: true,
+                env: mockEnv,
+                options: { configComponent }
+            });
+            // Verify provider is loaded from config
+            const provider = component.getProvider("openai");
+            expect(provider).toBeDefined();
+            expect(provider?.apiKey).toBe("test-key");
+            // Simulate config change event
+            component.onConfigChange({
+                key: "llm.providers",
+                oldValue: { openai: { apiKey: "test-key" } },
+                newValue: { openai: { apiKey: "new-key" } }
+            });
+            // After config change event, onConfigChange should be called successfully
+            // (Verification is done by checking no error is thrown)
+            expect(true).toBe(true);
+        });
+    });
+});
+//# sourceMappingURL=llm.test.js.map