autosnippet 3.2.9 → 3.2.11

package/dist/lib/service/agent/capabilities.js

@@ -0,0 +1,405 @@
+/**
+ * Capabilities — 可组合的 Agent 技能模块
+ *
+ * 核心思想: Agent 的能力不由"类型"决定，而由加载了哪些 Capability 模块决定。
+ *
+ * 每个 Capability 提供:
+ *   1. promptFragment — 系统提示词片段 (告诉 LLM 它能做什么)
+ *   2. tools — 工具白名单 (该能力需要哪些工具)
+ *   3. hooks — 生命周期钩子 (可选的前/后处理)
+ *
+ * 组合示例:
+ *   - 用户聊天 = Conversation + CodeAnalysis
+ *   - 冷启动分析 = CodeAnalysis + KnowledgeProduction
+ *   - 飞书远程执行 = Conversation + SystemInteraction
+ *   - 智能全能 = Conversation + CodeAnalysis + KnowledgeProduction + SystemInteraction
+ *
+ * 这就是为什么"飞书聊天"和"前端聊天"是同一个概念:
+ *   它们加载相同的 Capability，只是到达方式 (Transport) 不同。
+ *
+ * @module capabilities
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { PACKAGE_ROOT } from '../../shared/package-root.js';
+// ─── Base Capability ─────────────────────────────────────
+/**
+ * Capability 基类 — 所有技能模块的抽象接口
+ */
+export class Capability {
+    /** 能力名称 */
+    get name() {
+        throw new Error('Subclass must implement name');
+    }
+    /** 系统提示词片段 */
+    get promptFragment() {
+        throw new Error('Subclass must implement promptFragment');
+    }
+    /** 工具白名单 */
+    get tools() {
+        return [];
+    }
+    /**
+     * 构建 prompt 时调用，可注入动态上下文
+     */
+    buildContext(_context) {
+        return null;
+    }
+    /**
+     * 每轮 ReAct 步骤前的钩子
+     */
+    onBeforeStep(_stepState) { }
+    /**
+     * 每轮 ReAct 步骤后的钩子
+     */
+    onAfterStep(_stepResult) { }
+}
+// ─── Conversation — 对话能力 ─────────────────────
+/**
+ * 对话能力: 多轮问答、知识检索、记忆管理
+ *
+ * 核心工具: 知识库搜索、语义搜索
+ * 用于: 用户聊天、飞书聊天、任何需要对话的场景
+ */
+export class Conversation extends Capability {
+    #memoryCoordinator;
+    #soulContent;
+    #projectBriefing;
+    /**
+     * @param {Object} [opts]
+     * @param {Object} [opts.memoryCoordinator] - MemoryCoordinator 实例
+     * @param {string} [opts.soulPath] - SOUL.md 路径
+     * @param {string} [opts.projectBriefing] 项目概况文本
+     */
+    constructor(opts = {}) {
+        super();
+        this.#memoryCoordinator = opts.memoryCoordinator || null;
+        this.#projectBriefing = opts.projectBriefing || null;
+        // 加载 SOUL.md (人格定义)
+        const soulPath = opts.soulPath || path.resolve(PACKAGE_ROOT, 'SOUL.md');
+        try {
+            this.#soulContent = fs.existsSync(soulPath)
+                ? fs.readFileSync(soulPath, 'utf-8').trim()
+                : null;
+        }
+        catch {
+            this.#soulContent = null;
+        }
+    }
+    get name() {
+        return 'conversation';
+    }
+    get promptFragment() {
+        return `## 对话能力
+你是 AutoSnippet 知识管理助手。
+
+行为规则:
+1. 回答问题时优先从知识库搜索相关知识
+2. 用户要求编辑/创建知识时，通过工具完成
+3. 每轮至少调用一个工具获取信息（除非纯闲聊）
+4. 保持对话连贯性，引用之前的上下文`;
+    }
+    get tools() {
+        return [
+            // 知识检索 (内部 ToolRegistry 名称)
+            'search_knowledge',
+            'search_recipes',
+            'get_recipe_detail',
+            'get_related_recipes',
+            // 语义搜索
+            'semantic_search_code',
+            // 知识管理
+            'submit_knowledge',
+            'knowledge_overview',
+            // 项目统计
+            'get_project_stats',
+        ];
+    }
+    buildContext(context) {
+        const parts = [];
+        // SOUL.md 人格注入
+        if (this.#soulContent) {
+            parts.push(this.#soulContent);
+        }
+        // 项目概况 (优先用 context 传入的, 回退到构造器注入的)
+        const briefing = context.projectBriefing || this.#projectBriefing;
+        if (briefing) {
+            parts.push(`## 项目概况\n${briefing}`);
+        }
+        // 记忆注入
+        if (this.#memoryCoordinator) {
+            try {
+                const memoryContext = this.#memoryCoordinator.buildPromptInjection(context.memoryMode || 'user');
+                if (memoryContext) {
+                    parts.push(`## 记忆上下文\n${memoryContext}`);
+                }
+            }
+            catch {
+                /* non-critical */
+            }
+        }
+        return parts.length > 0 ? parts.join('\n\n') : null;
+    }
+    onAfterStep(stepResult) {
+        // 缓存工具结果到记忆
+        if (this.#memoryCoordinator && stepResult.toolCalls?.length) {
+            try {
+                for (const tc of stepResult.toolCalls) {
+                    this.#memoryCoordinator.cacheToolResult?.(tc.tool, tc.args, tc.result);
+                }
+            }
+            catch {
+                /* non-critical */
+            }
+        }
+    }
+}
+// ─── CodeAnalysis — 代码分析能力 ─────────────────
+/**
+ * 代码分析能力: AST 解析、代码搜索、结构理解
+ *
+ * 核心工具: AST 工具集 + 文件读取 + 代码搜索
+ * 用于: 用户聊天中的代码问题、冷启动分析、目标扫描
+ */
+export class CodeAnalysis extends Capability {
+    get name() {
+        return 'code_analysis';
+    }
+    get promptFragment() {
+        return `## 代码分析能力
+你是高级软件架构师，可以深度分析代码结构。
+
+分析策略:
+| 阶段 | 目标 |
+|------|------|
+| 全局扫描 | get_project_overview + list_project_structure |
+| 结构化探索 | get_class_hierarchy / search_project_code 批量搜索 |
+| 深度验证 | read_project_file 阅读关键实现 |
+| 输出总结 | 停止工具调用，输出分析 |
+
+关键规则:
+- 批量搜索: search_project_code({ patterns: [...] })
+- 批量读文件: read_project_file({ filePaths: [...] })
+- 不要重复搜索相同关键词
+- 输出时包含具体文件路径和代码位置`;
+    }
+    get tools() {
+        return [
+            // AST 结构
+            'get_project_overview',
+            'get_class_hierarchy',
+            'get_class_info',
+            'get_protocol_info',
+            'get_method_overrides',
+            'get_category_map',
+            // 搜索与读取
+            'search_project_code',
+            'read_project_file',
+            'list_project_structure',
+            'get_file_summary',
+            'semantic_search_code',
+            // 图谱
+            'query_code_graph',
+            // 探索追踪
+            'get_previous_analysis',
+            'note_finding',
+            'get_previous_evidence',
+        ];
+    }
+}
+// ─── KnowledgeProduction — 知识生产能力 ─────────
+/**
+ * 知识生产能力: 将分析结果转化为结构化知识候选
+ *
+ * 核心工具: 知识提交 + Guard 检查
+ * 用于: 冷启动提交、扫描后提交、用户主动创建知识
+ */
+export class KnowledgeProduction extends Capability {
+    get name() {
+        return 'knowledge_production';
+    }
+    get promptFragment() {
+        return `## 知识生产能力
+你是知识管理专家，将代码分析转化为结构化知识候选。
+
+每个候选必须有:
+1. 清晰的标题 (使用项目真实类名/模块名)
+2. 项目特写风格的正文 (content.markdown)
+3. 相关文件路径
+4. 正确的 kind (rule / pattern / fact)
+5. 完整的 Cursor 交付字段
+
+工作流:
+1. 识别分析中的知识点
+2. read_project_file 获取代码片段 (如需)
+3. submit_knowledge 或 submit_with_check 提交
+4. 提交优先于完美 — 文件读取失败时用已有信息直接提交`;
+    }
+    get tools() {
+        // 与旧版 PRODUCER_TOOLS 保持一致: 仅 3 个核心工具
+        // guard_check_code / validate_candidate 不需要：提交时 UnifiedValidator 已自动校验
+        // 额外工具会分散 LLM 注意力，浪费 produce 轮次在验证而非提交上
+        return [
+            'submit_knowledge',
+            'submit_with_check',
+            'read_project_file', // 获取代码片段用于知识正文
+        ];
+    }
+}
+// ─── SystemInteraction — 系统交互能力 ────────────
+/**
+ * 系统交互能力: 终端命令执行、文件写入、环境探测、项目探索
+ *
+ * 核心工具: 终端执行 + 文件写入 + 环境信息 + 项目读取
+ * 用于: 飞书远程执行、自动化脚本、任何需要操作本地系统的场景
+ *
+ * ⚙️ 安全设计 (3 层防护):
+ *   1. 工具层: run_safe_command / write_project_file 内置硬编码黑名单
+ *   2. Policy 层: SafetyPolicy.checkCommand() / checkFilePath() 动态拦截
+ *   3. Runtime 层: reactLoop 工具执行前自动调用 PolicyEngine.validateToolCall()
+ *
+ * ⚠️ 该能力通常搭配 SafetyPolicy 使用
+ */
+export class SystemInteraction extends Capability {
+    #projectRoot;
+    /**
+     * @param {Object} [opts]
+     * @param {string} [opts.projectRoot] 项目根目录 (限制操作范围)
+     */
+    constructor(opts = {}) {
+        super();
+        this.#projectRoot = opts.projectRoot || process.cwd();
+    }
+    get name() {
+        return 'system_interaction';
+    }
+    get promptFragment() {
+        return `## 系统交互能力
+你可以在本地环境中执行终端命令、写入文件、探索项目。
+
+能力:
+1. **终端命令**: run_safe_command 执行 shell 命令 (git, npm, ls, grep 等)
+2. **文件写入**: write_project_file 创建/覆盖项目内文件
+3. **环境探测**: get_environment_info 获取 OS/Node/Git/项目信息
+4. **项目探索**: 搜索代码、读取文件、列出目录结构
+
+安全规则:
+- 所有操作限制在项目目录 (${this.#projectRoot}) 内
+- 危险命令 (sudo, rm -rf /, shutdown 等) 被自动拦截
+- 受保护文件 (.git/, node_modules/, .env) 不可写入
+- SafetyPolicy 可进一步约束可执行命令和可访问路径
+
+最佳实践:
+- 执行命令前先 get_environment_info 了解环境
+- git 命令用于查看状态、diff、log，不建议执行 push/commit
+- 需要管道/重定向时用 sh -c "命令" 包装
+
+项目路径: ${this.#projectRoot}`;
+    }
+    get tools() {
+        return [
+            // 终端执行
+            'run_safe_command',
+            // 文件写入
+            'write_project_file',
+            // 环境探测
+            'get_environment_info',
+            // 项目探索 (只读)
+            'search_project_code',
+            'read_project_file',
+            'list_project_structure',
+            'get_project_overview',
+            'get_file_summary',
+        ];
+    }
+}
+// ─── ScanProduction — 扫描知识生产能力 ─────────
+/**
+ * 扫描知识生产能力: 将分析结果转化为标准 Recipe
+ *
+ * 与冷启动 KnowledgeProduction 的区别:
+ *   - 使用 collect_scan_recipe 工具（内存收集，不入库）
+ *   - 冷启动用 submit_knowledge（直接入库）
+ *   - 字段 schema 完全一致 — 产出质量相同
+ *
+ * 用于: scanKnowledge produce 阶段
+ */
+export class ScanProduction extends Capability {
+    get name() {
+        return 'scan_production';
+    }
+    get promptFragment() {
+        return `## 知识生产能力
+你是知识管理专家，将代码分析转化为结构化知识候选。
+
+每个候选必须有:
+1. 清晰的标题 (使用项目真实类名/模块名)
+2. 项目特写风格的正文 (content.markdown ≥200字)
+3. 设计原理说明 (content.rationale)
+4. 相关文件路径 (reasoning.sources)
+5. 正确的 kind (rule / pattern / fact)
+6. 完整的 Cursor 交付字段 (trigger, doClause, whenClause 等)
+
+工作流:
+1. 识别分析中的知识点
+2. read_project_file 获取代码片段 (如需)
+3. collect_scan_recipe 逐个提交每个知识点
+4. 每个独立模式/发现单独提交 — 不要合并`;
+    }
+    get tools() {
+        return [
+            'collect_scan_recipe', // 扫描专用 Recipe 收集
+            'read_project_file', // 获取代码片段
+        ];
+    }
+}
+// ─── Capability 注册表 ─────────────────────────
+/**
+ * 所有内置 Capability 的注册表
+ *
+ * 用于按名称查找和实例化:
+ *   const cap = CapabilityRegistry.create('conversation', { memoryCoordinator });
+ */
+export const CapabilityRegistry = {
+    _registry: new Map([
+        ['conversation', Conversation],
+        ['code_analysis', CodeAnalysis],
+        ['knowledge_production', KnowledgeProduction],
+        ['scan_production', ScanProduction],
+        ['system_interaction', SystemInteraction],
+    ]),
+    /**
+     * 按名称创建 Capability 实例
+     * @param {string} name
+     * @param {Object} [opts]
+     * @returns {Capability}
+     */
+    create(name, opts = {}) {
+        const Cls = this._registry.get(name);
+        if (!Cls) {
+            throw new Error(`Unknown capability: ${name}`);
+        }
+        return new Cls(opts);
+    },
+    /**
+     * 注册自定义 Capability
+     * @param {string} name
+     * @param {typeof Capability} cls
+     */
+    register(name, cls) {
+        this._registry.set(name, cls);
+    },
+    /** 所有注册名 */
+    get names() {
+        return [...this._registry.keys()];
+    },
+};
+export default {
+    Capability,
+    Conversation,
+    CodeAnalysis,
+    KnowledgeProduction,
+    SystemInteraction,
+    CapabilityRegistry,
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/lib/service/agent/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../../lib/service/agent/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAmC5D,4DAA4D;AAE5D;;GAEG;AACH,MAAM,OAAO,UAAU;IACrB,WAAW;IACX,IAAI,IAAI;QACN,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IAED,cAAc;IACd,IAAI,cAAc;QAChB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,YAAY;IACZ,IAAI,KAAK;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,QAAiB;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,UAAmB,IAAG,CAAC;IAEpC;;OAEG;IACH,WAAW,CAAC,WAAoB,IAAG,CAAC;CACrC;AAED,gDAAgD;AAEhD;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,UAAU;IAC1C,kBAAkB,CAAC;IACnB,YAAY,CAAC;IACb,gBAAgB,CAAC;IAEjB;;;;;OAKG;IACH,YAAY,OAAyB,EAAE;QACrC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC;QACzD,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC;QAErD,oBAAoB;QACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QACxE,IAAI,CAAC;YACH,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;gBACzC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE;gBAC3C,CAAC,CAAC,IAAI,CAAC;QACX,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,IAAI,IAAI;QACN,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,IAAI,cAAc;QAChB,OAAO;;;;;;;oBAOS,CAAC;IACnB,CAAC;IAED,IAAI,KAAK;QACP,OAAO;YACL,4BAA4B;YAC5B,kBAAkB;YAClB,gBAAgB;YAChB,mBAAmB;YACnB,qBAAqB;YACrB,OAAO;YACP,sBAAsB;YACtB,OAAO;YACP,kBAAkB;YAClB,oBAAoB;YACpB,OAAO;YACP,mBAAmB;SACpB,CAAC;IACJ,CAAC;IAED,YAAY,CAAC,OAAqB;QAChC,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,eAAe;QACf,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChC,CAAC;QAED,oCAAoC;QACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC,gBAAgB,CAAC;QAClE,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,CAAC,IAAI,CAAC,YAAY,QAAQ,EAAE,CAAC,CAAC;QACrC,CAAC;QAED,OAAO;QACP,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,CAAC,oBAAoB,CAChE,OAAO,CAAC,UAAU,IAAI,MAAM,CAC7B,CAAC;gBACF,IAAI,aAAa,EAAE,CAAC;oBAClB,KAAK,CAAC,IAAI,CAAC,aAAa,aAAa,EAAE,CAAC,CAAC;gBAC3C,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtD,CAAC;IAED,WAAW,CAAC,UAAsB;QAChC,YAAY;QACZ,IAAI,IAAI,CAAC,kBAAkB,IAAI,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YAC5D,IAAI,CAAC;gBACH,KAAK,MAAM,EAAE,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;oBACtC,IAAI,CAAC,kBAAkB,CAAC,eAAe,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,8CAA8C;AAE9C;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,UAAU;IAC1C,IAAI,IAAI;QACN,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,IAAI,cAAc;QAChB,OAAO;;;;;;;;;;;;;;;mBAeQ,CAAC;IAClB,CAAC;IAED,IAAI,KAAK;QACP,OAAO;YACL,SAAS;YACT,sBAAsB;YACtB,qBAAqB;YACrB,gBAAgB;YAChB,mBAAmB;YACnB,sBAAsB;YACtB,kBAAkB;YAClB,QAAQ;YACR,qBAAqB;YACrB,mBAAmB;YACnB,wBAAwB;YACxB,kBAAkB;YAClB,sBAAsB;YACtB,KAAK;YACL,kBAAkB;YAClB,OAAO;YACP,uBAAuB;YACvB,cAAc;YACd,uBAAuB;SACxB,CAAC;IACJ,CAAC;CACF;AAED,6CAA6C;AAE7C;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,UAAU;IACjD,IAAI,IAAI;QACN,OAAO,sBAAsB,CAAC;IAChC,CAAC;IAED,IAAI,cAAc;QAChB,OAAO;;;;;;;;;;;;;;8BAcmB,CAAC;IAC7B,CAAC;IAED,IAAI,KAAK;QACP,qCAAqC;QACrC,uEAAuE;QACvE,wCAAwC;QACxC,OAAO;YACL,kBAAkB;YAClB,mBAAmB;YACnB,mBAAmB,EAAE,eAAe;SACrC,CAAC;IACJ,CAAC;CACF;AAED,8CAA8C;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,iBAAkB,SAAQ,UAAU;IAC/C,YAAY,CAAC;IAEb;;;OAGG;IACH,YAAY,OAA8B,EAAE;QAC1C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACxD,CAAC;IAED,IAAI,IAAI;QACN,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO;;;;;;;;;;iBAUM,IAAI,CAAC,YAAY;;;;;;;;;;QAU1B,IAAI,CAAC,YAAY,EAAE,CAAC;IAC1B,CAAC;IAED,IAAI,KAAK;QACP,OAAO;YACL,OAAO;YACP,kBAAkB;YAClB,OAAO;YACP,oBAAoB;YACpB,OAAO;YACP,sBAAsB;YACtB,YAAY;YACZ,qBAAqB;YACrB,mBAAmB;YACnB,wBAAwB;YACxB,sBAAsB;YACtB,kBAAkB;SACnB,CAAC;IACJ,CAAC;CACF;AAED,0CAA0C;AAE1C;;;;;;;;;GASG;AACH,MAAM,OAAO,cAAe,SAAQ,UAAU;IAC5C,IAAI,IAAI;QACN,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO;;;;;;;;;;;;;;;wBAea,CAAC;IACvB,CAAC;IAED,IAAI,KAAK;QACP,OAAO;YACL,qBAAqB,EAAE,iBAAiB;YACxC,mBAAmB,EAAE,SAAS;SAC/B,CAAC;IACJ,CAAC;CACF;AAED,+CAA+C;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS,EAAE,IAAI,GAAG,CAA4B;QAC5C,CAAC,cAAc,EAAE,YAAY,CAAC;QAC9B,CAAC,eAAe,EAAE,YAAY,CAAC;QAC/B,CAAC,sBAAsB,EAAE,mBAAmB,CAAC;QAC7C,CAAC,iBAAiB,EAAE,cAAc,CAAC;QACnC,CAAC,oBAAoB,EAAE,iBAAiB,CAAC;KAC1C,CAAC;IAEF;;;;;OAKG;IACH,MAAM,CAAC,IAAY,EAAE,OAAgC,EAAE;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,IAAK,GAAyD,CAAC,IAAI,CAAC,CAAC;IAC9E,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,IAAY,EAAE,GAAsB;QAC3C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,YAAY;IACZ,IAAI,KAAK;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;CACF,CAAC;AAEF,eAAe;IACb,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,mBAAmB;IACnB,iBAAiB;IACjB,kBAAkB;CACnB,CAAC"}

package/dist/lib/service/agent/context/ContextWindow.d.ts

@@ -0,0 +1,192 @@
+/**
+ * ContextWindow — Agent 的上下文窗口管理器
+ *
+ * 业界最佳实践:
+ *   - OpenAI Compaction: 阈值触发自动压缩，保留关键上下文
+ *   - LangChain trim_messages: 按 token 裁剪，保证消息合法性
+ *   - Anthropic 长上下文: 长文档前置，查询后置
+ *   - Gemini API: functionResponse 必须紧跟 functionCall
+ *
+ * 设计不变量:
+ *   1. messages[0] 始终是原始 user prompt（不可删除）
+ *   2. assistant(toolCalls) 与其 tool results 是原子单元（不可拆分）
+ *   3. 每次 AI 调用前自动压缩到 TOKEN_BUDGET 以内
+ *   4. 不通过追加 user 消息来控制 AI 行为（由 ExplorationTracker 管理）
+ *
+ * 三级递进压缩:
+ *   L1 (60-80%): 截断旧的 tool results 内容
+ *   L2 (80-95%): 摘要历史轮次，保留最后 2 轮完整链
+ *   L3 (>95%):  仅保留 prompt + 最后 1 轮 + 已提交列表
+ *
+ * @module ContextWindow
+ */
+/** 工具调用信息 */
+interface ToolCallInfo {
+    id: string;
+    name: string;
+    args?: Record<string, unknown>;
+}
+/** 上下文窗口中的消息 */
+export interface ContextMessage {
+    role: 'user' | 'assistant' | 'tool';
+    content?: string | null;
+    toolCalls?: ToolCallInfo[];
+    toolCallId?: string;
+    name?: string;
+}
+/** 工具结果配额 */
+interface ToolResultQuota {
+    maxChars?: number;
+    maxMatches?: number;
+}
+/**
+ * 一组相关消息的原子单元:
+ * - assistant(toolCalls) + 所有后续 tool results
+ * - 或单独的 user/assistant 文本消息
+ *
+ * @typedef {Object} MessageRound
+ * @property {'tool-round'|'text'} type
+ * @property {Array<Object>} messages 本轮包含的消息
+ * @property {number} estimatedTokens 估算 token 数
+ */
+export declare class ContextWindow {
+    #private;
+    /**
+     * 模型名 → 上下文窗口大小映射（token 数）。
+     * 键为正则模式，按优先级从上到下匹配。
+     * 值为模型的原始上下文窗口上限。
+     * @type {Array<[RegExp, number]>}
+     */
+    static MODEL_CONTEXT_WINDOWS: (number | RegExp)[][];
+    /**
+     * 根据模型名称解析合适的 ContextWindow token 预算。
+     *
+     * 策略: 取模型最大上下文窗口的一个安全分片，
+     *   - 大窗口 (≥200k): 预算 32000（tool schemas + system prompt 占显著空间）
+     *   - 中窗口 (≥64k):  预算 24000
+     *   - 小窗口 (≥16k):  预算 12000
+     *   - 微窗口 (<16k):  预算 = 窗口 × 0.7（留 30% 给 prompt/tool schema）
+     *
+     * @param {string} modelName 模型名称，如 'gemini-3-flash-preview', 'gpt-4o-mini'
+     * @param {{ isSystem?: boolean }} [opts] - isSystem 为 true 时给予更高预算
+     * @returns {number} 建议的 token 预算
+     */
+    static resolveTokenBudget(modelName: string, opts?: {
+        isSystem?: boolean;
+    }): number;
+    /**
+     * @param {number} [tokenBudget=24000] - token 预算上限
+     */
+    constructor(tokenBudget?: number);
+    /**
+     * 追加用户消息
+     * @param {string} content
+     */
+    appendUserMessage(content: string): void;
+    /**
+     * 追加阶段过渡引导消息 — 轻量级 user 消息，用于在 ExplorationTracker 阶段转换时
+     * 向 AI 明确传达新阶段的行为期望。与 appendUserMessage 功能相同，
+     * 独立命名以便审计和搜索。
+     * @param {string} content
+     */
+    appendUserNudge(content: string): void;
+    /**
+     * 追加 assistant 消息（含工具调用）
+     * @param {string|null} text - assistant 文本
+     * @param {Array} toolCalls - [{id, name, args}]
+     */
+    appendAssistantWithToolCalls(text: string | null, toolCalls: ToolCallInfo[]): void;
+    /**
+     * 追加工具结果（必须紧跟 assistant toolCalls 后）
+     * @param {string} toolCallId
+     * @param {string} name 工具名
+     * @param {string} content 工具返回内容（已经过 ToolResultLimiter 截断）
+     */
+    appendToolResult(toolCallId: string, name: string, content: string): void;
+    /**
+     * 追加 assistant 纯文本消息（无工具调用）
+     * @param {string} text
+     */
+    appendAssistantText(text: string): void;
+    /**
+     * 在每次 AI 调用前调用 — 根据 token 使用率执行分级压缩
+     *
+     * @returns {{ level: number, removed: number }} 压缩结果
+     */
+    compactIfNeeded(): {
+        level: number;
+        removed: number;
+    };
+    /**
+     * 导出消息（供 AI Provider 使用）
+     * @returns {Array<Object>}
+     */
+    toMessages(): ContextMessage[];
+    /**
+     * 获取消息数量
+     * @returns {number}
+     */
+    get length(): number;
+    /**
+     * 获取 token 预算
+     * @returns {number}
+     */
+    get tokenBudget(): number;
+    /**
+     * 估算当前 token 使用量
+     * @returns {number}
+     */
+    estimateTokens(): number;
+    /**
+     * 获取 token 使用率 (0-1)
+     * @returns {number}
+     */
+    getTokenUsageRatio(): number;
+    /**
+     * 获取动态工具结果配额
+     * 根据当前 token 使用率返回工具结果的大小限制
+     * @returns {{ maxChars: number, maxMatches: number }}
+     */
+    getToolResultQuota(): {
+        maxChars: number;
+        maxMatches: number;
+    };
+    /**
+     * 获取压缩日志（用于调试）
+     * @returns {Array<string>}
+     */
+    getCompactionLog(): string[];
+    /**
+     * 获取被压缩掉的已提交候选标题
+     * @returns {Set<string>}
+     */
+    getCompactedSubmits(): Set<unknown>;
+    /**
+     * 清空消息 — 仅保留首条 prompt
+     * 用于致命错误后的恢复
+     */
+    resetToPromptOnly(): void;
+    /**
+     * Pipeline 阶段隔离 — 清空全部消息。
+     *
+     * 用于 PipelineStrategy 在阶段间重置 ContextWindow：
+     *   analyze → (reset) → produce
+     *
+     * reactLoop 会将新阶段的 prompt 追加为 messages[0]，
+     * systemPrompt 通过 chatWithTools 参数独立传递，不受影响。
+     *
+     * 保留 compactedSubmits 以支持跨阶段提交去重。
+     */
+    resetForNewStage(): void;
+}
+/**
+ * 工具结果入口限制器 — 在工具结果进入 ContextWindow 前压缩
+ *
+ * @param {string} toolName 工具名
+ * @param {*} result 工具原始返回
+ * @param {{ maxChars: number, maxMatches: number }} quota 动态配额
+ * @returns {string} 压缩后的结果字符串
+ */
+export declare function limitToolResult(toolName: string, result: unknown, quota: ToolResultQuota): string;
+export {};
+//# sourceMappingURL=ContextWindow.d.ts.map

package/dist/lib/service/agent/context/ContextWindow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextWindow.d.ts","sourceRoot":"","sources":["../../../../../lib/service/agent/context/ContextWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,aAAa;AACb,UAAU,YAAY;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,gBAAgB;AAChB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA6BD,aAAa;AACb,UAAU,eAAe;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AAEH,qBAAa,aAAa;;IAYxB;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,wBAiC1B;IAEF;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO;IA6B9E;;OAEG;gBACS,WAAW,SAAQ;IAO/B;;;OAGG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM;IAIjC;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM;IAI/B;;;;OAIG;IACH,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE;IAQ3E;;;;;OAKG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IASlE;;;OAGG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM;IAShC;;;;OAIG;IACH,eAAe;;;;IAgJf;;;OAGG;IACH,UAAU;IAIV;;;OAGG;IACH,IAAI,MAAM,WAET;IAED;;;OAGG;IACH,IAAI,WAAW,WAEd;IAED;;;OAGG;IACH,cAAc;IAad;;;OAGG;IACH,kBAAkB;IAIlB;;;;OAIG;IACH,kBAAkB;;;;IAclB;;;OAGG;IACH,gBAAgB;IAIhB;;;OAGG;IACH,mBAAmB;IAInB;;;OAGG;IACH,iBAAiB;IASjB;;;;;;;;;;OAUG;IACH,gBAAgB;CAyDjB;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,UA2CxF"}