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

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

@@ -0,0 +1,607 @@
+/**
+ * @fileoverview BaseEnvironment Implementation
+ *
+ * Environment 的基础实现类（非抽象），提供：
+ * - 组件注册与管理
+ * - 核心调度方法（handle_query, handle_action）
+ * - EnvEvent 事件机制
+ *
+ * 设计原则：
+ * 1. Environment 只做两件事：
+ *    - 组件管理：持有、注册、获取组件
+ *    - 核心调度：handle_query / handle_action / EnvEvent
+ * 2. 其他能力归属到对应 Component
+ *
+ * 子类可覆盖：
+ * - registerDefaultComponents(): 注册默认组件
+ * - handle_query(): 查询处理逻辑
+ * - handle_action(): 动作处理逻辑
+ * - onInit/onStart/onStop: 生命周期钩子
+ */
+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 { createLogger } from "./log-trace/logger.js";
+import { generateId } from "../utils/id.js";
+import { ContextError, ErrorCodes } from "./errors.js";
+import * as fsSync from "fs";
+import * as path from "path";
+import { TracedAs } from "./log-trace/decorator.js";
+const logger = createLogger("environment");
+/**
+ * BaseEnvironment 实现类（非抽象）
+ *
+ * 实现 Environment 接口，提供简洁的环境基础功能。
+ * 子类可继承此类并覆盖特定方法来自定义行为。
+ */
+export class BaseEnvironment extends BaseComponent {
+    // ============ 标识 ============
+    name;
+    version;
+    // ============ 组件管理 ============
+    components = new Map();
+    /**
+     * 构造函数
+     */
+    constructor(config) {
+        super();
+        this.name = config?.name ?? "base-environment";
+        this.version = config?.version ?? "1.0.0";
+        // 注册默认组件
+        this.registerDefaultComponents();
+    }
+    /**
+     * 注册默认组件（子类可覆盖）
+     */
+    registerDefaultComponents() {
+        // 子类可覆盖以注册默认组件
+    }
+    /**
+     * 获取环境配置
+     */
+    getConfig() {
+        return {
+            name: this.name,
+            version: this.version,
+            enabled: true,
+            env: this,
+        };
+    }
+    // ============ 组件管理 ============
+    /**
+     * 注册组件
+     */
+    registerComponent(component) {
+        this.components.set(component.name, component);
+        logger.debug(`Component registered: ${component.name}`);
+    }
+    /**
+     * 注销组件
+     */
+    unregisterComponent(name) {
+        const component = this.components.get(name);
+        if (component) {
+            this.components.delete(name);
+            logger.debug(`Component unregistered: ${name}`);
+        }
+    }
+    /**
+     * 获取组件
+     */
+    getComponent(name) {
+        return this.components.get(name);
+    }
+    /**
+     * 列出所有组件
+     */
+    listComponents() {
+        return Array.from(this.components.values());
+    }
+    // ============ 核心能力（子类可覆盖） ============
+    /**
+     * 处理自然语言查询（核心入口）
+     *
+     * 委托给 AgentComponent.run() 处理
+     */
+    async handle_query(query, context) {
+        // 1. 获取 AgentComponent
+        const agentComponent = this.getComponent("agent");
+        if (!agentComponent) {
+            throw new Error("AgentComponent not found. Please register AgentComponent before calling handle_query.");
+        }
+        // 2. 获取 system prompt（从 PromptComponent 获取）
+        let systemPrompt = "You are a helpful assistant.";
+        let promptSource = "fallback";
+        try {
+            const promptComponent = this.getComponent("prompt");
+            if (promptComponent) {
+                const loadedPrompt = await promptComponent.getPrompt("default");
+                if (loadedPrompt) {
+                    systemPrompt = loadedPrompt;
+                    promptSource = "PromptComponent";
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`[handle_query] Failed to get prompt from PromptComponent: ${err}`);
+        }
+        logger.info(`[handle_query] Using system prompt from ${promptSource}, length: ${systemPrompt.length}`);
+        // 3. 读取 memory 内容并注入到 prompt（如果 {{memory}} 变量存在）
+        let finalSystemPrompt = systemPrompt;
+        if (systemPrompt.includes("{{memory}}")) {
+            try {
+                const memoryComponent = this.getComponent("memory");
+                if (memoryComponent) {
+                    const memoryContent = await memoryComponent.recallMemory();
+                    finalSystemPrompt = systemPrompt.replace("{{memory}}", memoryContent || "(No memory)");
+                    logger.info(`[handle_query] Injected memory content, length: ${memoryContent.length}`);
+                }
+                else {
+                    finalSystemPrompt = systemPrompt.replace("{{memory}}", "(Memory component not available)");
+                }
+            }
+            catch (err) {
+                logger.warn(`[handle_query] Failed to load memory content: ${err}`);
+                finalSystemPrompt = systemPrompt.replace("{{memory}}", "(Failed to load memory)");
+            }
+        }
+        // 3.1 注入 workspace_dir（当前工作目录）
+        if (finalSystemPrompt.includes("{{workspace_dir}}")) {
+            const workspaceDir = process.cwd();
+            finalSystemPrompt = finalSystemPrompt.replace("{{workspace_dir}}", workspaceDir);
+            logger.debug(`[handle_query] Injected workspace_dir: ${workspaceDir}`);
+        }
+        // 4. 根据 agentType 获取或创建 agent
+        // - 如果 context.agentType 为空或 "default"，使用默认 agent
+        // - 否则使用 context.agentType 对应的 agent（delegate-tool 会预先注册）
+        const agentName = (context?.agentType && context.agentType !== "default")
+            ? context.agentType
+            : "default";
+        let agent = agentComponent.getAgent(agentName);
+        if (!agent) {
+            // 如果指定了 agentType 但 agent 不存在，使用默认 agent
+            if (agentName !== "default") {
+                logger.warn(`[handle_query] Agent "${agentName}" not found, falling back to "default"`);
+            }
+            agent = agentComponent.getAgent("default");
+        }
+        // 如果默认 agent 也不存在，则创建
+        if (!agent) {
+            agent = agentComponent.registerAgent("default", {
+                type: "primary",
+                systemPrompt: finalSystemPrompt,
+            });
+        }
+        // 执行 agent
+        const result = await agentComponent.run(agent.name, query, context);
+        // 4. 如果有错误，检查是否是 ContextError，需要让上层处理
+        if (result.error) {
+            // 如果错误信息包含上下文阈值相关，抛出 ContextError 让 ContextHandler 处理
+            const errorMsg = result.error.toLowerCase();
+            if (errorMsg.includes("context") ||
+                errorMsg.includes("threshold") ||
+                errorMsg.includes("token") ||
+                result.error.includes("CTX_001")) {
+                // 尝试从错误消息中提取上下文使用信息
+                // 格式如: "Context threshold exceeded: 1230/10000 (12.3%)"
+                const usageMatch = result.error.match(/(\d+)\/(\d+)\s*\(([\d.]+)%\)/);
+                let usage;
+                let contextWindow;
+                if (usageMatch) {
+                    const totalTokens = parseInt(usageMatch[1], 10);
+                    usage = {
+                        promptTokens: totalTokens,
+                        completionTokens: 0,
+                        totalTokens
+                    };
+                    contextWindow = parseInt(usageMatch[2], 10);
+                }
+                // 构造 ContextError 抛出
+                const ctxError = new ContextError(result.error, ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED, context?.sessionId, usage, contextWindow);
+                throw ctxError;
+            }
+            // 其他错误继续抛出
+            throw new Error(result.error);
+        }
+        // 6. 返回响应文本
+        return result.finalText || "";
+    }
+    /**
+     * 处理动作
+     *
+     * 默认实现抛出错误，子类必须实现。
+     */
+    async handle_action(action, context) {
+        throw new Error("handle_action not implemented. Override in subclass.");
+    }
+    // ============ EnvEvent 机制 ============
+    /**
+     * 事件订阅者映射
+     */
+    eventHandlers = new Map();
+    /**
+     * 通配符订阅者（接收所有事件）
+     */
+    wildcardHandlers = new Set();
+    /**
+     * 订阅 EnvEvent（返回取消订阅函数）
+     */
+    subscribe(handler) {
+        this.wildcardHandlers.add(handler);
+        logger.debug(`EnvEvent handler subscribed (wildcard)`);
+        // 返回取消订阅函数
+        return () => {
+            this.wildcardHandlers.delete(handler);
+            logger.debug(`EnvEvent handler unsubscribed (wildcard)`);
+        };
+    }
+    /**
+     * 订阅指定类型事件
+     */
+    subscribeTo(eventType, handler) {
+        const types = Array.isArray(eventType) ? eventType : [eventType];
+        for (const type of types) {
+            if (!this.eventHandlers.has(type)) {
+                this.eventHandlers.set(type, new Set());
+            }
+            this.eventHandlers.get(type).add(handler);
+        }
+        logger.debug(`EnvEvent handler subscribed for types: ${types.join(", ")}`);
+        // 返回取消订阅函数
+        return () => {
+            for (const type of types) {
+                this.eventHandlers.get(type)?.delete(handler);
+            }
+            logger.debug(`EnvEvent handler unsubscribed for types: ${types.join(", ")}`);
+        };
+    }
+    /**
+     * 订阅所有事件（通配符）
+     *
+     * 与 subscribe 相同，为保持 API 一致性
+     */
+    subscribeAll(handler) {
+        return this.subscribe(handler);
+    }
+    /**
+     * 推送事件
+     */
+    pushEnvEvent(event) {
+        // 如果是完整 EnvEvent，直接使用；否则创建新的
+        const fullEvent = "id" in event && event.id
+            ? event
+            : {
+                id: event.id ?? generateId(),
+                type: event.type,
+                timestamp: event.timestamp ?? Date.now(),
+                metadata: {
+                    ...event.metadata,
+                    env_name: event.metadata?.env_name ?? this.name,
+                },
+                payload: event.payload ?? {},
+            };
+        // 通知通配符订阅者
+        for (const handler of this.wildcardHandlers) {
+            try {
+                handler(fullEvent);
+            }
+            catch (error) {
+                logger.error(`Error in EnvEvent handler: ${error}`);
+            }
+        }
+        // 通知特定类型订阅者
+        const handlers = this.eventHandlers.get(fullEvent.type);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(fullEvent);
+                }
+                catch (error) {
+                    logger.error(`Error in EnvEvent handler for ${fullEvent.type}: ${error}`);
+                }
+            }
+        }
+    }
+    /**
+     * 创建并推送事件（便捷方法）
+     */
+    emit(type, payload, metadata) {
+        const event = {
+            id: generateId(),
+            type,
+            timestamp: Date.now(),
+            metadata: {
+                env_name: this.name,
+                ...metadata,
+            },
+            payload,
+        };
+        this.pushEnvEvent(event);
+    }
+    // ============ 生命周期 ============
+    /**
+     * 初始化所有组件（分阶段初始化）
+     *
+     * 1. 第一阶段：初始化 ConfigComponent（如果存在）
+     * 2. 第二阶段：初始化其他组件
+     */
+    async initializeComponents() {
+        logger.debug(`Starting component initialization, total: ${this.components.size}`);
+        // 1️⃣ 第一阶段：初始化 ConfigComponent（如果存在）
+        // 特殊处理：直接访问 this.components 因为此时 ConfigComponent 尚未 init
+        // 正常情况下组件应通过 this.env.getComponent() 获取其他已初始化的组件
+        const configComp = this.components.get("config");
+        if (configComp && configComp.getStatus() === "created") {
+            logger.debug(`Initializing ConfigComponent first...`);
+            await configComp.init({
+                name: "config",
+                version: configComp.version,
+                enabled: true,
+                env: this,
+            });
+            logger.debug(`ConfigComponent initialized`);
+        }
+        else {
+            logger.debug(`No ConfigComponent found, skipping first stage`);
+        }
+        // 2️⃣ 第二阶段：初始化其他组件
+        const otherComponents = Array.from(this.components.values())
+            .filter(c => c.getStatus() === "created");
+        if (otherComponents.length > 0) {
+            logger.debug(`Initializing ${otherComponents.length} other components...`);
+            for (const component of otherComponents) {
+                logger.debug(`Initializing component: ${component.name}`);
+                await component.init({
+                    name: component.name,
+                    version: component.version,
+                    enabled: true,
+                    env: this,
+                });
+                logger.debug(`Component initialized: ${component.name}`);
+            }
+        }
+        logger.debug(`All components initialized`);
+    }
+    /**
+     * 启动所有组件
+     *
+     * 注意：由于 Environment.init() 会将组件状态设为 "running"，我们需要确保
+     * 即使组件已经是 "running" 状态，它们的 start() 方法仍然被调用。
+     * 这是因为 start() 负责注册工具等运行时资源。
+     */
+    async startComponents() {
+        // 启动所有已注册的组件（不检查状态）
+        const allComponents = Array.from(this.components.values());
+        if (allComponents.length > 0) {
+            logger.debug(`Starting ${allComponents.length} components...`);
+            for (const component of allComponents) {
+                logger.debug(`Starting component: ${component.name} (current status: ${component.getStatus()})`);
+                await component.start();
+                logger.debug(`Component started: ${component.name}`);
+            }
+        }
+    }
+    /**
+     * 停止所有组件
+     */
+    async stopComponents() {
+        const componentsToStop = Array.from(this.components.values())
+            .filter(c => c.getStatus() !== "stopped");
+        if (componentsToStop.length > 0) {
+            logger.debug(`Stopping ${componentsToStop.length} components...`);
+            for (const component of componentsToStop) {
+                logger.debug(`Stopping component: ${component.name}`);
+                await component.stop();
+                logger.debug(`Component stopped: ${component.name}`);
+            }
+        }
+    }
+    /**
+     * 初始化（可覆盖）
+     */
+    async onInit() {
+        await this.initializeComponents();
+        logger.info(`Environment "${this.name}" initialized`);
+    }
+    /**
+     * 启动（可覆盖）
+     */
+    async onStart() {
+        await this.startComponents();
+        logger.info(`Environment "${this.name}" started`);
+    }
+    /**
+     * 停止（可覆盖）
+     */
+    async onStop() {
+        await this.stopComponents();
+        // 清理事件处理器
+        this.eventHandlers.clear();
+        this.wildcardHandlers.clear();
+        logger.info(`Environment "${this.name}" stopped`);
+    }
+    /**
+     * BaseComponent 钩子
+     *
+     * Environment 特殊处理：它本身就是 env，所以不需要外部传入。
+     * 此方法覆盖 BaseComponent.init()，直接设置自引用。
+     */
+    async init() {
+        // Environment 特殊处理：设置自引用
+        // 注意：这里需要直接访问 protected env 属性，使用 TypeScript 的原型链访问
+        // 这是唯一需要绕过类型检查的地方，因为 Environment 是特殊情况
+        Object.defineProperty(this, "env", {
+            value: this,
+            writable: true,
+            enumerable: false,
+            configurable: true,
+        });
+        this.setStatus("initializing");
+        await this.onInit();
+        this.setStatus("running");
+    }
+    async start() {
+        // 注意：Environment.init() 会将状态设为 "running"，但组件的 start() 仍需被调用
+        // 所以这里使用一个内部标志来跟踪是否已经启动过
+        if (this._started)
+            return;
+        this._started = true;
+        await this.onStart();
+        this.setStatus("running");
+        logger.info(`Environment "${this.name}" started`);
+    }
+    async stop() {
+        this.setStatus("stopping");
+        await this.onStop();
+        this.setStatus("stopped");
+    }
+    // ============ 服务配置能力 ============
+    /**
+     * 从配置文件加载服务配置
+     */
+    async loadServiceConfig(configPath) {
+        // 1. 获取 ConfigComponent
+        const configComponent = this.getComponent("config");
+        if (!configComponent) {
+            throw new Error("ConfigComponent not found. Please register ConfigComponent before loading service config.");
+        }
+        // 2. 获取配置目录
+        const xdgDataHome = configComponent.getXdgDataHome();
+        // 3. 读取配置文件
+        const fullPath = path.resolve(xdgDataHome, configPath);
+        if (!fsSync.existsSync(fullPath)) {
+            throw new Error(`Service config file not found: ${fullPath}`);
+        }
+        // 4. 解析配置文件（支持 JSON/JSONC）
+        const content = fsSync.readFileSync(fullPath, "utf-8");
+        let config;
+        try {
+            config = JSON.parse(content);
+        }
+        catch (e) {
+            throw new Error(`Failed to parse service config: ${e}`);
+        }
+        logger.debug(`Service config loaded from: ${fullPath}`);
+        return config;
+    }
+    /**
+     * 生成组件初始化选项
+     */
+    generateComponentOptions(componentName, configEntry) {
+        // 1. 获取 ConfigComponent（必填）
+        const configComponent = this.getComponent("config");
+        if (!configComponent) {
+            throw new Error("ConfigComponent not found. Please register ConfigComponent before generating component options.");
+        }
+        // 2. 构建选项对象
+        const options = {
+            configComponent,
+            configPath: configEntry.configPath,
+            envPrefix: configEntry.envPrefix,
+            config: configEntry.config,
+        };
+        logger.debug(`Generated options for component: ${componentName}`);
+        return options;
+    }
+    /**
+     * 注册组件并用配置初始化
+     */
+    async registerComponentWithConfig(component, configEntry) {
+        // 1. 如果组件未注册，先注册
+        if (!this.components.has(component.name)) {
+            this.registerComponent(component);
+        }
+        // 2. 生成初始化选项
+        const options = this.generateComponentOptions(component.name, configEntry);
+        // 3. 如果组件已初始化，跳过
+        if (component.getStatus() === "running") {
+            logger.debug(`Component ${component.name} already initialized, skipping`);
+            return;
+        }
+        // 4. 初始化组件
+        await component.init({
+            name: component.name,
+            version: component.version,
+            enabled: configEntry.enabled ?? true,
+            env: this,
+            options,
+        });
+        logger.debug(`Component ${component.name} registered and initialized with config`);
+    }
+    /**
+     * 从配置文件初始化整个环境
+     */
+    async initFromConfig(configPath) {
+        // 0. 设置 Environment 自引用（如果不尚未设置）
+        if (!this.env) {
+            Object.defineProperty(this, "env", {
+                value: this,
+                writable: true,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        // 1. 加载服务配置
+        const serviceConfig = await this.loadServiceConfig(configPath);
+        // 2. 更新环境名称和版本（如果配置了）
+        if (serviceConfig.environment) {
+            if (serviceConfig.environment.name) {
+                this.name = serviceConfig.environment.name;
+            }
+            if (serviceConfig.environment.version) {
+                this.version = serviceConfig.environment.version;
+            }
+        }
+        // 3. 确保 ConfigComponent 已注册
+        const configComponent = this.getComponent("config");
+        if (!configComponent) {
+            throw new Error("ConfigComponent not found. Please register ConfigComponent before initFromConfig.");
+        }
+        // 4. 初始化 ConfigComponent
+        if (configComponent.getStatus() === "created") {
+            await configComponent.init({
+                name: "config",
+                version: configComponent.version,
+                enabled: true,
+                env: this,
+            });
+        }
+        // 5. 初始化每个配置的组件
+        const components = serviceConfig.components || {};
+        for (const [componentName, configEntry] of Object.entries(components)) {
+            // 跳过禁用的组件
+            if (configEntry.enabled === false) {
+                logger.debug(`Component ${componentName} is disabled, skipping`);
+                continue;
+            }
+            // 获取组件实例
+            const component = this.getComponent(componentName);
+            if (!component) {
+                logger.warn(`Component ${componentName} not registered, skipping`);
+                continue;
+            }
+            // 跳过 ConfigComponent（已初始化）
+            if (component.name === "config")
+                continue;
+            // 注册并初始化
+            await this.registerComponentWithConfig(component, configEntry);
+        }
+        // 6. 设置环境状态为 running
+        this.setStatus("running");
+        logger.info(`Environment "${this.name}" initialized from config: ${configPath}`);
+    }
+}
+__decorate([
+    TracedAs("env.handle_query", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], BaseEnvironment.prototype, "handle_query", null);
+//# sourceMappingURL=environment.js.map

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

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview BaseEnvironment Unit Tests
+ */
+export {};
+//# sourceMappingURL=environment.test.d.ts.map