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

package/dist/core/src/env/agent/summary-agent.js

@@ -0,0 +1,473 @@
+/**
+ * @fileoverview Summary Agent
+ *
+ * 专门用于生成 session checkpoint 的 Agent
+ * 通过 PromptComponent 加载 compact prompt
+ * 调用 LLM 提取关键信息
+ *
+ * 支持 scenarioHint 场景化提示，用于指导不同场景下的压缩重点提取
+ */
+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 { createLogger } from "../log-trace/logger.js";
+import { TracedAs } from "../log-trace/decorator.js";
+const logger = createLogger("agent:summary");
+/**
+ * Summary Agent
+ *
+ * 专门用于生成 session checkpoint 的 Agent
+ */
+export class SummaryAgent {
+    promptComponent;
+    llmComponent;
+    config;
+    constructor(promptComponent, llmComponent, config) {
+        this.promptComponent = promptComponent;
+        this.llmComponent = llmComponent;
+        this.config = {
+            type: "summary",
+            promptName: "session/compact",
+            maxIterations: 1,
+            model: undefined, // 不指定模型，使用 LLMComponent 的默认模型
+            ...config,
+        };
+    }
+    /**
+     * 生成场景化压缩提示 (Compact Hint)
+     *
+     * 根据会话历史分析，生成一个场景化的压缩提示，用于指导后续的 checkpoint 生成。
+     * 这个方法用于自动触发压缩的两阶段流程中的第一阶段。
+     *
+     * @param options 生成选项
+     * @returns 场景化的压缩提示
+     */
+    async generateCompactHint(options) {
+        const { messages, sessionContext } = options;
+        logger.info("[SummaryAgent] Generating compact hint for session");
+        // 1. 格式化消息
+        const formattedMessages = this.formatMessages(messages);
+        // 2. 构建提示生成 prompt
+        const systemPrompt = this.getHintGenerationSystemPrompt();
+        const userPrompt = this.buildHintGenerationUserPrompt(formattedMessages, sessionContext);
+        // 3. 调用 LLM
+        let response;
+        try {
+            response = await this.llmComponent.invoke({
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    { role: "user", content: userPrompt },
+                ],
+                skipThresholdCheck: true,
+            });
+        }
+        catch (error) {
+            logger.error(`[SummaryAgent] Hint generation LLM invoke failed: ${error}`);
+            throw new Error(`LLM invoke failed: ${error}`);
+        }
+        // 4. 解析响应
+        const responseContent = response.output?.content || response.content || "";
+        const hint = this.parseHintResponse(responseContent);
+        logger.info("[SummaryAgent] Compact hint generated", { hint: hint.substring(0, 100) });
+        return {
+            hint,
+            rawResponse: responseContent,
+        };
+    }
+    /**
+     * 运行 Summary Agent
+     *
+     * @param options 运行选项
+     * @returns Summary Agent 结果
+     */
+    async run(options) {
+        const { messages, userContext, outputFormat, scenarioHint } = options;
+        logger.info("[SummaryAgent] Starting checkpoint generation", {
+            hasScenarioHint: !!scenarioHint
+        });
+        // 1. 格式化消息
+        const formattedMessages = this.formatMessages(messages);
+        // 2. 渲染 prompt - 支持 scenarioHint
+        const systemPrompt = this.getSystemPrompt(scenarioHint);
+        const userPrompt = this.buildUserPrompt(formattedMessages, userContext);
+        // 3. 调用 LLM（直接调用，不走 ReAct 循环）
+        // 注意：跳过阈值检查，避免循环触发压缩
+        let response;
+        try {
+            response = await this.llmComponent.invoke({
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    { role: "user", content: userPrompt },
+                ],
+                model: this.config.model,
+                skipThresholdCheck: true, // 跳过阈值检查，避免循环触发压缩
+            });
+        }
+        catch (error) {
+            logger.error(`[SummaryAgent] LLM invoke failed: ${error}`);
+            throw new Error(`LLM invoke failed: ${error}`);
+        }
+        // 4. 解析响应
+        // LLMInvokeResult 返回 { output: LLMOutput, providerId, model, latencyMs }
+        const responseContent = response.output?.content || response.content || "";
+        if (outputFormat === "json") {
+            const result = this.parseJsonResponse(responseContent);
+            logger.info(`[SummaryAgent] Checkpoint generated: "${result.title}"`);
+            return {
+                title: result.title || "Untitled Checkpoint",
+                processKeyPoints: result.processKeyPoints || [],
+                currentState: result.currentState || "",
+                nextSteps: result.nextSteps || [],
+                userIntents: result.userIntents || [],
+                rawResponse: responseContent,
+            };
+        }
+        throw new Error(`Unsupported output format: ${outputFormat}`);
+    }
+    /**
+     * 获取系统提示
+     *
+     * @param scenarioHint 场景化提示（可选）
+     */
+    getSystemPrompt(scenarioHint) {
+        let prompt = `You are a professional session analyst assistant. Your task is to extract key information from a conversation and generate a structured checkpoint.
+
+A checkpoint captures the progress and state of a session at a point in time. It should contain:
+
+1. **Process Key Points**: The key steps, discoveries, or decisions made during this part of the conversation
+2. **Current State**: The current progress and status at the end of the conversation
+3. **Next Steps**: Follow-up items and what needs to be done next
+4. **User Intents**: The underlying goals and intentions of the user (what they want to accomplish)
+
+Be concise and accurate. Avoid redundancy. Each section should be appropriately sized - not too long.`;
+        // 如果提供了 scenarioHint，将其添加到系统提示中
+        if (scenarioHint && scenarioHint.trim()) {
+            prompt += `\n\n## Scenario Context\n\n${scenarioHint.trim()}`;
+        }
+        return prompt;
+    }
+    /**
+     * 获取提示生成的系统提示
+     *
+     * 这个方法生成的 hint 是一个 "压缩指导 Prompt"，用于告诉 Compact 阶段：
+     * "在当前这个场景/目标/任务下，生成 checkpoint 时应该重点关注什么"
+     *
+     * 注意：这里生成的是"指导 Prompt"，不是"压缩要点本身"
+     *
+     * 指导 Prompt 应包含：
+     * 1. 当前正在进行什么工作
+     * 2. 进展是什么
+     * 3. 压缩时需要专注什么信息的提取
+     * 4. 这些信息对后续任务推进很重要，不能丢失
+     */
+    getHintGenerationSystemPrompt() {
+        return `You are a compact guidance prompt engineer. Your task is to analyze a conversation and generate a "compact guidance prompt" that will instruct the checkpoint generator on what information to extract and preserve during session compression.
+
+**Purpose**: The guidance prompt will be used by the checkpoint generator to understand:
+1. What work is currently in progress
+2. What progress has been made
+3. What information MUST be preserved during compression (this is critical for task continuation)
+4. What information should be the focus of extraction
+
+**Key Principle**: The preserved information should enable seamless task continuation. If critical details are lost during compression, the user will have to re-explain context when continuing this work later.
+
+**Output Format**: A structured guidance prompt (3-4 sentences) covering:
+1. Current work type and what the user is trying to accomplish
+2. Current progress and key achievements
+3. CRITICAL information that MUST be preserved (decisions, findings, remaining issues)
+4. What the checkpoint generator should focus on when extracting information
+
+**Example good outputs**:
+1. "Bug investigation: User is debugging LSP diagnostics not updating after file edits. Progress: identified root cause (getDiagnostics needs to read latest file content and trigger didChange notification), implemented fix, CI verified. CRITICAL to preserve: the fix implementation details (file path, code changes), that 2 agent-node-integration tests still fail due to test assertion timing issue (expects 'running' but completes in ~78ms) - this is unrelated to LSP work. Focus extraction on: root cause analysis, fix implementation, known remaining test issues."
+2. "Feature development: User is implementing JWT authentication for auth-service. Progress: designed auth flow, implemented token refresh logic, middleware partially done. CRITICAL to preserve: auth flow decisions (token storage, refresh strategy), completed middleware components, modules pending implementation. Focus extraction on: architectural decisions, completed components, pending work."
+3. "Refactoring: User is migrating data layer to repository pattern. Progress: migrated UserRepository and OrderRepository, 3 more pending. CRITICAL to preserve: pattern decisions (interface definitions, dependency injection approach), completed repositories, modules pending migration. Focus extraction on: pattern implementation details, completed vs pending modules."`;
+    }
+    /**
+     * 构建提示生成的用户提示
+     */
+    buildHintGenerationUserPrompt(messages, sessionContext) {
+        let prompt = `Analyze the following conversation and generate a compact guidance prompt for checkpoint generation.
+
+## Your Task
+Generate a structured guidance prompt (3-4 sentences) that will help the checkpoint generator understand:
+1. What work is currently in progress
+2. What progress has been made
+3. What information MUST be preserved during compression (critical for task continuation)
+4. What the checkpoint generator should focus on when extracting information
+
+`;
+        if (sessionContext) {
+            const ctxLines = ["## Session Context"];
+            if (sessionContext.activeTaskTitle) {
+                ctxLines.push(`- Active Task: ${sessionContext.activeTaskTitle}`);
+            }
+            if (sessionContext.workingDirectory) {
+                ctxLines.push(`- Working Directory: ${sessionContext.workingDirectory}`);
+            }
+            if (sessionContext.recentActions && sessionContext.recentActions.length > 0) {
+                ctxLines.push(`- Recent Actions: ${sessionContext.recentActions.slice(-3).join(" → ")}`);
+            }
+            if (ctxLines.length > 1) {
+                prompt += ctxLines.join("\n") + "\n\n";
+            }
+        }
+        prompt += `## Conversation to Analyze\n\n${messages}\n\n`;
+        prompt += `---\n\n`;
+        prompt += `## Output Format\n\n`;
+        prompt += `Generate a structured guidance prompt covering:\n`;
+        prompt += `1. Current work type and what the user is trying to accomplish\n`;
+        prompt += `2. Current progress and key achievements\n`;
+        prompt += `3. CRITICAL information that MUST be preserved (decisions, findings, remaining issues)\n`;
+        prompt += `4. What to focus on during extraction\n\n`;
+        prompt += `Wrap the output in a JSON object with a \`guidance_prompt\` key:\n\n`;
+        prompt += `\`\`\`json\n`;
+        prompt += `{\n`;
+        prompt += `  "guidance_prompt": "Work type: ... Progress: ... CRITICAL to preserve: ... Focus extraction on: ..."\n`;
+        prompt += `}\n`;
+        prompt += `\`\`\`\n\n`;
+        prompt += `IMPORTANT: The preserved information should enable seamless task continuation. If critical details are lost, the user will need to re-explain context when continuing this work.`;
+        return prompt;
+    }
+    /**
+     * 构建用户提示
+     */
+    buildUserPrompt(messages, userContext) {
+        let prompt = "Please analyze the following conversation and generate a checkpoint:\n\n";
+        if (userContext && userContext !== "无额外上下文") {
+            prompt += `## Context\n${userContext}\n\n`;
+        }
+        prompt += `## Conversation Content\n\n${messages}\n\n`;
+        prompt += `---\n\n`;
+        prompt += `## Output Format\n\nPlease output in the following JSON format:\n\n\`\`\`json\n{
+  "title": "Brief checkpoint title (max 30 characters)",
+  "processKeyPoints": [
+    "Point 1: Description of key discovery or decision",
+    "Point 2: Description of important step or conclusion",
+    "Point 3: ..."
+  ],
+  "currentState": "Current state description explaining progress and status (50-100 characters)",
+  "nextSteps": [
+    "Next follow-up item 1",
+    "Next follow-up item 2"
+  ],
+  "userIntents": [
+    "User intent 1: what the user wants to accomplish",
+    "User intent 2: another goal or request",
+    "User intent 3: ..."
+  ]
+}
+\`\`\`\n\n`;
+        prompt += `## Intent Extraction Guidelines\n\n`;
+        prompt += `- Extract user intents from the ENTIRE conversation flow (both user and assistant messages)\n`;
+        prompt += `- Focus on what the user WANTS to accomplish, not just what was discussed\n`;
+        prompt += `- Include both explicit requests and inferred goals\n`;
+        prompt += `- Aim for 2-5 intents, prioritize the most important ones\n`;
+        prompt += `- Be concise and specific in intent descriptions\n`;
+        prompt += `- Examples: "Fix authentication bug", "Optimize database performance", "Add unit tests for auth module"\n\n`;
+        prompt += `Make sure the JSON output is valid and can be parsed.`;
+        return prompt;
+    }
+    /**
+     * 格式化消息用于 prompt
+     */
+    formatMessages(messages) {
+        return messages
+            .map((m, i) => `[${i}] ${m.role}: ${m.content}`)
+            .join("\n\n");
+    }
+    /**
+     * 解析 JSON 响应
+     */
+    parseJsonResponse(content) {
+        // 尝试提取 JSON 代码块
+        const jsonMatch = content.match(/```json\s*([\s\S]*?)\s*```/)
+            || content.match(/```\s*([\s\S]*?)\s*```/)
+            || [null, content];
+        const jsonStr = jsonMatch[1] || content;
+        try {
+            return JSON.parse(jsonStr.trim());
+        }
+        catch {
+            // 如果解析失败，尝试修复常见问题
+            const fixed = jsonStr
+                .replace(/,\s*}/g, "}")
+                .replace(/,\s*]/g, "]")
+                .replace(/'/g, '"')
+                .trim();
+            try {
+                return JSON.parse(fixed);
+            }
+            catch (e) {
+                logger.error(`[SummaryAgent] Failed to parse JSON: ${content}`);
+                throw new Error(`Failed to parse checkpoint JSON: ${e}`);
+            }
+        }
+    }
+    /**
+     * 解析提示响应
+     *
+     * 直接返回清理后的自然语言提示
+     */
+    parseHintResponse(content) {
+        return parseCompactHintResponse(content);
+    }
+}
+__decorate([
+    TracedAs("summary-agent.generateCompactHint"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SummaryAgent.prototype, "generateCompactHint", null);
+__decorate([
+    TracedAs("summary-agent.run", { recordParams: true, recordResult: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SummaryAgent.prototype, "run", null);
+__decorate([
+    TracedAs("summary-agent.getHintGenerationSystemPrompt"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", String)
+], SummaryAgent.prototype, "getHintGenerationSystemPrompt", null);
+__decorate([
+    TracedAs("summary-agent.buildHintGenerationUserPrompt"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", String)
+], SummaryAgent.prototype, "buildHintGenerationUserPrompt", null);
+__decorate([
+    TracedAs("summary-agent.parseHintResponse"),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", String)
+], SummaryAgent.prototype, "parseHintResponse", null);
+// ============================================================================
+// 导出用于测试的纯函数
+// ============================================================================
+/**
+ * 解析 Compact Hint 响应
+ *
+ * 纯函数，可独立测试
+ *
+ * 支持的 LLM 输出格式：
+ * 1. 标准 JSON: {"guidance_prompt": "..."}
+ * 2. text + JSON 混合: "Some explanation\n{...}\nMore text"
+ * 3. ```json ... ``` 包裹
+ * 4. ``` ... ``` 包裹（无语言标识）
+ * 5. markdown 包裹的纯文本
+ * 6. 纯文本（降级处理）
+ *
+ * @param content LLM 返回的原始内容
+ * @returns 解析后的 guidance_prompt 字符串
+ */
+export function parseCompactHintResponse(content) {
+    // 1. 尝试提取 JSON 并解析 guidance_prompt
+    const jsonResult = extractGuidanceFromJson(content);
+    // 使用显式 null 检查，因为空字符串也是有效返回值
+    if (jsonResult !== null) {
+        // 2. 验证提取结果
+        const trimmed = jsonResult.trim();
+        if (!trimmed) {
+            return "[Hint extraction failed]";
+        }
+        // 3. 限制长度
+        if (trimmed.length > 500) {
+            return trimmed.substring(0, 500) + "...";
+        }
+        return trimmed;
+    }
+    // 4. 降级处理：提取纯文本（移除代码块）
+    let text = content
+        .replace(/```json\s*([\s\S]*?)\s*```/g, "$1")
+        .replace(/```markdown\s*([\s\S]*?)\s*```/g, "$1")
+        .replace(/```\s*([\s\S]*?)\s*```/g, "$1")
+        .trim();
+    if (!text) {
+        return "[Hint extraction failed]";
+    }
+    // 5. 限制长度
+    if (text.length > 500) {
+        return text.substring(0, 500) + "...";
+    }
+    return text;
+}
+/**
+ * 从 LLM 输出中提取 JSON 并解析 guidance_prompt
+ *
+ * 尝试多种提取策略：
+ * 1. 匹配 ```json ... ``` 包裹的 JSON
+ * 2. 匹配 ``` ... ``` 包裹的 JSON
+ * 3. 匹配裸 JSON 对象
+ *
+ * @returns guidance_prompt 字符串，或特殊标记 "EMPTY" 表示字段存在但值为空，或 null 表示未找到
+ */
+function extractGuidanceFromJson(content) {
+    // 策略1: 提取 ```json ... ```
+    const jsonBlockMatch = content.match(/```json\s*([\s\S]*?)\s*```/);
+    if (jsonBlockMatch) {
+        const parsed = tryParseJson(jsonBlockMatch[1]);
+        const guidancePrompt = parsed?.guidance_prompt;
+        if (typeof guidancePrompt === "string") {
+            return guidancePrompt; // 包括空字符串
+        }
+    }
+    // 策略2: 提取 ``` ... ``` (无语言标识)
+    const plainBlockMatch = content.match(/```\s*([\s\S]*?)\s*```/);
+    if (plainBlockMatch) {
+        const parsed = tryParseJson(plainBlockMatch[1]);
+        const guidancePrompt = parsed?.guidance_prompt;
+        if (typeof guidancePrompt === "string") {
+            return guidancePrompt; // 包括空字符串
+        }
+    }
+    // 策略3: 匹配整个 JSON 对象（处理 text + JSON 混合情况）
+    // 查找 {...} 模式
+    const jsonMatch = content.match(/\{[\s\S]*"guidance_prompt"[\s\S]*\}/);
+    if (jsonMatch) {
+        const parsed = tryParseJson(jsonMatch[0]);
+        const guidancePrompt = parsed?.guidance_prompt;
+        if (typeof guidancePrompt === "string") {
+            return guidancePrompt; // 包括空字符串
+        }
+    }
+    // 策略4: 尝试解析整个 content 作为 JSON
+    const parsed = tryParseJson(content.trim());
+    const guidancePrompt = parsed?.guidance_prompt;
+    if (typeof guidancePrompt === "string") {
+        return guidancePrompt; // 包括空字符串
+    }
+    return null;
+}
+/**
+ * 尝试解析 JSON，容错处理
+ */
+function tryParseJson(str) {
+    if (!str || !str.trim()) {
+        return null;
+    }
+    try {
+        return JSON.parse(str.trim());
+    }
+    catch {
+        // JSON 解析失败，尝试修复常见问题
+        try {
+            // 移除尾随逗号
+            const fixed = str
+                .replace(/,\s*}/g, "}")
+                .replace(/,\s*]/g, "]")
+                .trim();
+            return JSON.parse(fixed);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=summary-agent.js.map

package/dist/core/src/env/agent/summary-agent.parse-hint.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview SummaryAgent parseHintResponse 测试
+ *
+ * TDD 规范：覆盖 LLM 可能返回的各种输出格式
+ *
+ * 测试 parseCompactHintResponse 函数的解析逻辑
+ *
+ * Hint 阶段输出格式：JSON with guidance_prompt key
+ * 需要兼容各种 LLM 输出格式
+ */
+export {};
+//# sourceMappingURL=summary-agent.parse-hint.test.d.ts.map