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

package/dist/cli/src/services/context-handler.service.js

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview Context Handler Service
+ *
+ * 处理 env.handle_query 的上下文阈值检测和压缩逻辑
+ *
+ * 功能：
+ * 1. 包装 handle_query，捕获 ContextError
+ * 2. 两阶段自动压缩：
+ *    - 阶段1: 调用 SessionComponent.generateCompactHint() 生成场景化提示
+ *    - 阶段2: 调用 SessionComponent.compact() 并传入 scenarioHint
+ * 3. 用 checkpoint 构造新 query 并重试
+ * 4. 生成 trace id 用于调用链追踪
+ */
+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 { ContextError, ErrorCodes, getTracerProvider, TracedAs, } from "@ai-setting/roy-agent-core";
+import { createLogger } from "@ai-setting/roy-agent-core";
+// 创建 logger
+const logger = createLogger("context-handler");
+/**
+ * Context Handler Service
+ *
+ * 处理 env.handle_query 的上下文阈值检测和压缩逻辑
+ *
+ * 采用两阶段自动压缩流程：
+ * - 阶段1: 根据历史消息生成场景化的压缩提示 (generateCompactHint)
+ * - 阶段2: 使用生成的提示进行实际的压缩 (compact with scenarioHint)
+ */
+export class ContextHandlerService {
+    env;
+    sessionComponent;
+    maxRetries;
+    autoCompact;
+    tracer;
+    constructor(env, sessionComponent, options = {}) {
+        this.env = env;
+        this.sessionComponent = sessionComponent;
+        this.maxRetries = options.maxRetries ?? 1;
+        this.autoCompact = options.autoCompact ?? true;
+        // 初始化 tracer
+        this.initializeTracer();
+    }
+    /**
+     * 初始化 tracer
+     */
+    initializeTracer() {
+        try {
+            this.tracer = getTracerProvider().getTracer("roy-tracer");
+        }
+        catch {
+            // Tracer 可能尚未初始化，延迟初始化
+            this.tracer = undefined;
+        }
+    }
+    /**
+     * 获取 tracer 实例
+     */
+    getTracerInstance() {
+        if (!this.tracer) {
+            try {
+                this.tracer = getTracerProvider().getTracer("roy-tracer");
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return this.tracer;
+    }
+    /**
+     * 包装 handle_query，添加上下文阈值处理和 trace 追踪
+     */
+    async handleQueryWithContext(query, context) {
+        // 从 metadata 获取 trace id（如果上层已设置）
+        const traceId = context?.metadata?.traceId;
+        const sessionId = context?.sessionId;
+        // 获取 tracer 实例并启动根 span
+        const tracer = this.getTracerInstance();
+        const span = tracer?.startSpan("handleQueryWithContext", {
+            attributes: {
+                query: query.substring(0, 200),
+                sessionId,
+                traceId,
+            },
+        });
+        let lastError;
+        try {
+            for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+                try {
+                    // 正常执行 handle_query
+                    const result = await this.env.handle_query(query, context);
+                    // 结束根 span（成功）
+                    if (span) {
+                        span?.end(result);
+                    }
+                    return result;
+                }
+                catch (error) {
+                    // 检查是否是上下文阈值异常
+                    if (error instanceof ContextError && error.code === ErrorCodes.CONTEXT_THRESHOLD_EXCEEDED) {
+                        lastError = error;
+                        if (attempt >= this.maxRetries) {
+                            logger.error("Context threshold exceeded after max retries", {
+                                attempt,
+                                maxRetries: this.maxRetries
+                            });
+                            // 结束根 span（失败）
+                            if (span) {
+                                span?.end(undefined, error);
+                            }
+                            throw error;
+                        }
+                        if (!this.autoCompact) {
+                            logger.warn("Auto compact disabled, propagating error");
+                            // 结束根 span（失败）
+                            if (span) {
+                                span?.end(undefined, error);
+                            }
+                            throw error;
+                        }
+                        logger.info(`Context threshold exceeded, compacting (attempt ${attempt + 1}/${this.maxRetries + 1})`);
+                        // 发布阈值即将压缩事件
+                        this.env.pushEnvEvent({
+                            type: "context.threshold_exceeded",
+                            metadata: {
+                                sessionId,
+                                traceId,
+                            },
+                            payload: {
+                                totalTokens: error.usage?.totalTokens,
+                                contextWindow: error.contextWindow,
+                                attempt: attempt + 1,
+                            },
+                        });
+                        // 执行两阶段压缩
+                        const compactResult = await this.compactSessionWithTwoPhases(context?.sessionId, query);
+                        if (!compactResult.success) {
+                            logger.error("Compact failed", { error: compactResult.error });
+                            // 结束根 span（失败）
+                            if (span) {
+                                span?.end(undefined, error);
+                            }
+                            throw error;
+                        }
+                        // 用新的 query 重试
+                        if (compactResult.newQuery) {
+                            query = compactResult.newQuery;
+                        }
+                        continue;
+                    }
+                    // 其他错误直接抛出
+                    // 结束根 span（失败）
+                    if (span) {
+                        span?.end(undefined, error);
+                    }
+                    throw error;
+                }
+            }
+            throw lastError ?? new Error("Unexpected exit from handleQueryWithContext");
+        }
+        finally {
+            // 清理 span 上下文
+            if (span) {
+                tracer?.endSpan(span);
+            }
+        }
+    }
+    /**
+     * 执行两阶段 session compact
+     *
+     * 阶段1: 生成场景化压缩提示 (generateCompactHint)
+     * 阶段2: 使用提示进行压缩 (compact with scenarioHint)
+     */
+    async compactSessionWithTwoPhases(sessionId, originalQuery) {
+        if (!sessionId) {
+            return { success: false, error: "No session ID provided" };
+        }
+        try {
+            // 发布压缩开始事件
+            this.env.pushEnvEvent({
+                type: "context.compacting",
+                metadata: { sessionId },
+                payload: { phase: "two-phase" },
+            });
+            // ========================================
+            // 阶段1: 生成场景化压缩提示
+            // ========================================
+            let scenarioHint = "";
+            try {
+                scenarioHint = await this.sessionComponent.generateCompactHint(sessionId);
+                logger.info("[Phase 1] Compact hint generated", {
+                    sessionId,
+                    hintLength: scenarioHint.length,
+                    hintPreview: scenarioHint.substring(0, 100),
+                });
+            }
+            catch (hintError) {
+                // 如果生成提示失败，继续使用空提示（不影响主流程）
+                logger.warn("[Phase 1] Hint generation failed, continuing with empty hint", {
+                    error: hintError instanceof Error ? hintError.message : String(hintError),
+                });
+                scenarioHint = "";
+            }
+            // 发布提示生成完成事件
+            this.env.pushEnvEvent({
+                type: "context.hint_generated",
+                metadata: { sessionId },
+                payload: {
+                    hintLength: scenarioHint.length,
+                    hintPreview: scenarioHint.substring(0, 200),
+                },
+            });
+            // ========================================
+            // 阶段2: 执行实际压缩
+            // ========================================
+            const result = await this.sessionComponent.compact(sessionId, {
+                summary: originalQuery
+                    ? `Auto-compacted. Original query: ${originalQuery.substring(0, 200)}${originalQuery.length > 200 ? "..." : ""}`
+                    : "Auto-compacted due to context threshold",
+                scenarioHint, // 传入场景化提示
+            });
+            // 发布压缩完成事件
+            this.env.pushEnvEvent({
+                type: "context.compacted",
+                metadata: { sessionId },
+                payload: {
+                    checkpointId: result.checkpoint.id,
+                    messagesCompacted: result.deletedMessageCount,
+                    scenarioHintUsed: !!scenarioHint,
+                },
+            });
+            // 构造新 query
+            const newQuery = this.constructQueryWithCheckpoint(result.checkpoint, originalQuery);
+            logger.info("[Phase 2] Compact completed", {
+                checkpointId: result.checkpoint.id,
+                deletedMessageCount: result.deletedMessageCount,
+                scenarioHintUsed: !!scenarioHint,
+            });
+            return {
+                success: true,
+                checkpoint: result.checkpoint,
+                newQuery,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error("Two-phase compact failed", { error: errorMessage });
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * 执行 session compact（兼容旧接口，内部调用两阶段版本）
+     */
+    async compactSession(sessionId, originalQuery) {
+        return this.compactSessionWithTwoPhases(sessionId, originalQuery);
+    }
+    /**
+     * 用 checkpoint 构造新 query
+     */
+    constructQueryWithCheckpoint(checkpoint, originalQuery) {
+        const parts = [];
+        parts.push("【会话历史摘要】");
+        parts.push(checkpoint.summary);
+        if (checkpoint.processKeyPoints.length > 0) {
+            parts.push("");
+            parts.push("【已完成的工作】");
+            checkpoint.processKeyPoints.forEach((point, i) => {
+                parts.push(`${i + 1}. ${point}`);
+            });
+        }
+        if (checkpoint.currentState) {
+            parts.push("");
+            parts.push("【当前状态】");
+            parts.push(checkpoint.currentState);
+        }
+        if (checkpoint.nextSteps.length > 0) {
+            parts.push("");
+            parts.push("【待完成的任务】");
+            checkpoint.nextSteps.forEach((step, i) => {
+                parts.push(`${i + 1}. ${step}`);
+            });
+        }
+        if (originalQuery) {
+            parts.push("");
+            parts.push("【用户新输入】");
+            parts.push(originalQuery);
+        }
+        return parts.join("\n");
+    }
+}
+__decorate([
+    TracedAs("context-handler.compactSessionWithTwoPhases", { recordParams: true, recordResult: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], ContextHandlerService.prototype, "compactSessionWithTwoPhases", null);
+__decorate([
+    TracedAs("context-handler.constructQuery"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", String)
+], ContextHandlerService.prototype, "constructQueryWithCheckpoint", null);
+//# sourceMappingURL=context-handler.service.js.map

package/dist/cli/src/services/environment.service.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Environment Service
+ *
+ * 封装 Environment 实例的创建和管理
+ */
+import { BaseEnvironment, SessionComponent, LLMComponent, ToolComponent, AgentComponent, LogTraceComponent, SkillComponent, CommandsComponent } from "@ai-setting/roy-agent-core";
+import { MemoryPlugin } from "@ai-setting/roy-agent-core";
+import { OutputService } from "./output.service";
+export interface EnvironmentServiceOptions {
+    /** 工作目录 */
+    workDir?: string;
+    /** 环境名称 */
+    envName?: string;
+    /** 配置文件路径（绝对路径） */
+    configPath?: string;
+    /** 安静模式 - 抑制日志输出到控制台（仅影响环境初始化日志） */
+    quiet?: boolean;
+    /** 要加载的插件名称列表 */
+    plugins?: string[];
+    /** Session 存储配置（用于测试隔离） */
+    sessionStorage?: {
+        /** 存储类型 */
+        type?: "memory" | "sqlite";
+        /** SQLite 数据库路径（当 type=sqlite 时） */
+        dbPath?: string;
+    };
+}
+export interface ComponentInitOptions {
+    /** ConfigComponent 配置 */
+    configPath?: string;
+}
+/**
+ * EnvironmentService - CLI 环境服务
+ *
+ * 负责创建和管理 BaseEnvironment 实例及其组件
+ */
+export declare class EnvironmentService {
+    private environment;
+    private output;
+    private options;
+    private configComponent?;
+    private sessionComponent?;
+    private llmComponent?;
+    private toolComponent?;
+    private agentComponent?;
+    private skillComponent?;
+    private logTraceComponent?;
+    private promptComponent?;
+    private taskComponent?;
+    private mcpComponent?;
+    private commandsComponent?;
+    private memoryComponent?;
+    private memoryPlugin?;
+    private eventSourceComponent?;
+    private workflowComponent?;
+    constructor(output?: OutputService);
+    /**
+     * 获取已创建的 Environment 实例
+     */
+    getEnvironment(): BaseEnvironment | null;
+    /**
+     * 获取 SessionComponent 实例
+     */
+    getSession(): SessionComponent | null;
+    /**
+     * 获取 LLMComponent 实例
+     */
+    getLLM(): LLMComponent | null;
+    /**
+     * 获取 ToolComponent 实例
+     */
+    getTool(): ToolComponent | null;
+    /**
+     * 获取 AgentComponent 实例
+     */
+    getAgent(): AgentComponent | null;
+    /**
+     * 获取 SkillComponent 实例
+     */
+    getSkill(): SkillComponent | null;
+    /**
+     * 获取 CommandsComponent 实例
+     */
+    getCommands(): CommandsComponent | null;
+    /**
+     * 获取 LogTraceComponent 实例
+     */
+    getLogTrace(): LogTraceComponent | null;
+    /**
+     * 获取 MemoryPlugin 实例（用于 shared instances with MemoryComponent）
+     */
+    getMemoryPlugin(): MemoryPlugin | null;
+    /**
+     * 释放环境资源
+     */
+    dispose(): Promise<void>;
+    /**
+     * 创建 CLI 环境
+     *
+     * 配置目录优先级：
+     * 1. --config 参数指定的路径
+     * 2. 工作目录下的 .roy-agent/config.jsonc（项目级覆盖）
+     * 3. ~/.roy-agent/config.jsonc（用户级默认）
+     */
+    create(options?: EnvironmentServiceOptions): Promise<BaseEnvironment>;
+    /**
+     * 注册 commands-prompt Hook
+     *
+     * 将收藏命令的能力动态注入 default prompt
+     */
+    private registerCommandsPromptHook;
+    /**
+     * 加载组件插件
+     *
+     * 通用方法，从全局注册表获取组件插件定义，加载并注册到目标组件
+     */
+    private loadComponentPlugins;
+    /**
+     * 渲染命令表格 section
+     */
+    private renderCommandsSection;
+    /**
+     * 加载 Coder Plugins
+     *
+     * 根据插件名称列表加载对应的 coder-harness 插件
+     */
+    private loadCoderPlugins;
+}
+//# sourceMappingURL=environment.service.d.ts.map