autosnippet 3.2.7 → 3.2.9

package/lib/service/agent/domain/insight-producer.js

@@ -0,0 +1,267 @@
+/**
+ * insight-producer.js — Insight Producer 领域函数
+ *
+ * 从旧 ProducerAgent.js 提取的纯领域逻辑:
+ * - Producer System Prompt
+ * - 工具白名单
+ * - 预算常量
+ * - Prompt 构建器 (v1 + v2)
+ * - 代码上下文注入 (evidenceMap → prompt section)
+ * - 拒绝率门控 (producerRejectionGateEvaluator)
+ *
+ * 被 PipelineStrategy 的 bootstrap preset 直接引用。
+ * 不再包含任何 Agent 类 — Agent 由 AgentRuntime + PipelineStrategy 驱动。
+ *
+ * @module insight-producer
+ */
+
+import { buildProducerStyleGuide, SUBMIT_REQUIREMENTS } from '../../../shared/StyleGuide.js';
+
+// ──────────────────────────────────────────────────────────────────
+// System Prompt — Producer 专用 (~150 tokens)
+// ──────────────────────────────────────────────────────────────────
+
+export const PRODUCER_SYSTEM_PROMPT = `你是知识管理专家。你会收到一段代码分析文本，需要将其中的知识点转化为结构化的知识候选。
+
+核心原则: 分析文本已经包含了所有发现，你的唯一工作是将它们格式化为 submit_knowledge 调用。
+
+每个候选必须:
+1. 有清晰的标题 (描述知识点的核心，使用项目真实类名)
+2. 有项目特写风格的正文 (content.markdown 字段，结合代码展示)
+3. 标注相关文件路径
+4. 选择正确的 kind (rule/pattern/fact)
+5. 提供完整的 Cursor 交付字段 (trigger, doClause, whenClause 等)
+
+工作流程:
+1. 阅读分析文本，识别每个独立的知识点/发现
+2. 用 read_project_file 批量获取关键代码片段:
+   read_project_file({ filePaths: ["FileA.m", "FileB.m"], maxLines: 80 })
+3. 立刻调用 submit_knowledge 提交
+4. 重复直到分析中的所有知识点都已提交
+
+关键规则:
+- 分析中的每个要点/段落都应转化为至少一个候选
+- read_project_file 支持 filePaths 数组批量读取多个文件，一次调用完成
+- read_project_file 时读取足够多的行数（startLine + maxLines 至少 30 行）
+- reasoning.sources 必须是非空数组，填写相关文件路径如 ["FileName.m"]
+- 如果分析提到了 3 个模式，就应该提交 3 个候选，不要合并
+- 禁止: 不要搜索新文件、不要做额外分析，专注于格式化和提交
+
+容错规则:
+- 如果 read_project_file 返回"文件不存在"或错误，不要重试同一文件的其他路径变体
+- 文件读取失败时，直接使用分析文本中已有的代码和描述来提交候选
+- 永远不要因为文件读取失败而跳过知识点 — 分析文本已经包含足够信息
+- 先提交候选，再考虑是否需要读取更多代码（提交优先于验证）`;
+
+// ──────────────────────────────────────────────────────────────────
+// Producer 可用工具白名单 — 只做格式化和提交
+// ──────────────────────────────────────────────────────────────────
+
+export const PRODUCER_TOOLS = ['submit_knowledge', 'submit_with_check', 'read_project_file'];
+
+// ──────────────────────────────────────────────────────────────────
+// Producer 预算
+// ──────────────────────────────────────────────────────────────────
+
+export const PRODUCER_BUDGET = {
+  maxIterations: 24,
+  searchBudget: 4,
+  searchBudgetGrace: 3,
+  maxSubmits: 10,
+  softSubmitLimit: 10,
+  idleRoundsToExit: 3,
+};
+
+// ──────────────────────────────────────────────────────────────────
+// 项目特写风格指南 (从共享 StyleGuide.js 获取)
+// ──────────────────────────────────────────────────────────────────
+
+const STYLE_GUIDE = buildProducerStyleGuide();
+
+// ──────────────────────────────────────────────────────────────────
+// Prompt 构建
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 构建 Producer Prompt (v1 — 用于 AnalysisReport)
+ *
+ * @param {import('./bootstrap-gate.js').AnalysisReport} analysisReport
+ * @param {object} dimConfig — { id, label, allowedKnowledgeTypes, outputType }
+ * @param {object} projectInfo — { name }
+ * @returns {string}
+ */
+export function buildProducerPrompt(analysisReport, dimConfig, projectInfo) {
+  const parts = [];
+
+  parts.push(`将以下对 ${projectInfo.name} 项目 "${dimConfig.label}" 维度的分析，转化为知识候选:`);
+  parts.push(`---\n${analysisReport.analysisText}\n---`);
+
+  if (analysisReport.referencedFiles.length > 0) {
+    parts.push(`分析中引用的关键文件: ${analysisReport.referencedFiles.join(', ')}`);
+  }
+
+  parts.push(`维度约束:
+- dimensionId: ${dimConfig.id}
+- 允许的 knowledgeType: ${(dimConfig.allowedKnowledgeTypes || []).join(', ') || '(all)'}
+- category: ${dimConfig.id}`);
+
+  parts.push(STYLE_GUIDE);
+  parts.push(SUBMIT_REQUIREMENTS);
+
+  return parts.join('\n\n');
+}
+
+/**
+ * 构建 Producer Prompt v2 — 用于 AnalysisArtifact
+ *
+ * 相比 v1 增加:
+ * - §3 结构化发现 (findings)
+ * - §4 代码证据 (evidenceMap → code context)
+ * - §5 负空间信号
+ *
+ * @param {import('./bootstrap-gate.js').AnalysisArtifact} artifact
+ * @param {object} dimConfig
+ * @param {object} projectInfo
+ * @returns {string}
+ */
+export function buildProducerPromptV2(artifact, dimConfig, projectInfo) {
+  const parts = [];
+
+  parts.push(`将以下对 ${projectInfo.name} 项目 "${dimConfig.label}" 维度的分析，转化为知识候选:`);
+  parts.push(`---\n${artifact.analysisText}\n---`);
+
+  // §3 结构化发现
+  if (artifact.findings?.length > 0) {
+    const findingLines = ['## 关键发现 (Analyst 已确认)'];
+    const sorted = [...artifact.findings].sort((a, b) => b.importance - a.importance);
+    for (const f of sorted) {
+      const badge = f.importance >= 8 ? '⚠️' : '📋';
+      findingLines.push(`${badge} **[${f.importance}/10]** ${f.finding}`);
+      if (f.evidence) {
+        findingLines.push(`  证据: ${f.evidence}`);
+      }
+    }
+    findingLines.push('');
+    findingLines.push('☝️ 上述每个发现都应至少转化为一个候选。');
+    parts.push(findingLines.join('\n'));
+  }
+
+  // §4 代码证据
+  const codeContext = buildCodeContextSection(artifact.evidenceMap);
+  if (codeContext) {
+    parts.push(codeContext);
+  }
+
+  // §5 负空间信号
+  if (artifact.negativeSignals?.length > 0) {
+    const nsLines = ['## ⛔ 不存在的模式 (不要猜测)'];
+    for (const ns of artifact.negativeSignals.slice(0, 5)) {
+      nsLines.push(`- "${ns.searchPattern}" — ${ns.implication}`);
+    }
+    parts.push(nsLines.join('\n'));
+  }
+
+  // §6 引用文件
+  if (artifact.referencedFiles.length > 0) {
+    parts.push(`分析中引用的关键文件: ${artifact.referencedFiles.slice(0, 15).join(', ')}`);
+  }
+
+  // §7 维度约束
+  parts.push(`维度约束:
+- dimensionId: ${dimConfig.id}
+- 允许的 knowledgeType: ${(dimConfig.allowedKnowledgeTypes || []).join(', ') || '(all)'}
+- category: ${dimConfig.id}`);
+
+  // §8 写作指南 + 提交要求
+  parts.push(STYLE_GUIDE);
+  parts.push(SUBMIT_REQUIREMENTS);
+
+  return parts.join('\n\n');
+}
+
+// ──────────────────────────────────────────────────────────────────
+// 代码上下文注入 (Producer v2 辅助)
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 从 evidenceMap 构建代码上下文段
+ *
+ * 策略: 按代码片段数量排序
+ * 预算: ≤ 4000 chars (~1000 tokens)
+ *
+ * @param {Map<string, import('./EvidenceCollector.js').EvidenceEntry>} evidenceMap
+ * @returns {string|null}
+ */
+export function buildCodeContextSection(evidenceMap) {
+  if (!evidenceMap || evidenceMap.size === 0) return null;
+
+  const parts = ['## 📄 Analyst 已读取的代码 (直接引用, 无需 read_file)'];
+  let totalChars = 0;
+  const BUDGET = 4000;
+
+  const sortedEntries = [...evidenceMap.values()]
+    .filter((e) => e.codeSnippets.length > 0)
+    .sort((a, b) => b.codeSnippets.length - a.codeSnippets.length);
+
+  for (const entry of sortedEntries) {
+    if (totalChars >= BUDGET) break;
+
+    const header = `### ${entry.filePath}${entry.role ? ` (${entry.role})` : ''}`;
+    parts.push(header);
+    totalChars += header.length;
+
+    if (entry.summary) {
+      parts.push(entry.summary);
+      totalChars += entry.summary.length;
+    }
+
+    for (const snippet of entry.codeSnippets.slice(0, 2)) {
+      if (totalChars >= BUDGET) break;
+      const codeBlock = `\`\`\`\n// L${snippet.startLine}-${snippet.endLine}\n${snippet.content}\n\`\`\``;
+      if (snippet.analystNote) {
+        parts.push(`> ${snippet.analystNote}`);
+        totalChars += snippet.analystNote.length + 4;
+      }
+      parts.push(codeBlock);
+      totalChars += codeBlock.length;
+    }
+  }
+
+  return parts.length > 1 ? parts.join('\n') : null;
+}
+
+// ──────────────────────────────────────────────────────────────────
+// PipelineStrategy gate.evaluator — 拒绝率门控
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * Producer 拒绝率门控 — 面向 PipelineStrategy gate.evaluator
+ *
+ * 当 produce 阶段的提交拒绝率过高时触发 retry。
+ *
+ * @param {object} source — produce 阶段的 reactLoop 返回值
+ * @param {object} _phaseResults
+ * @param {object} _strategyContext
+ * @returns {{ action: 'pass'|'retry', reason: string }}
+ */
+export function producerRejectionGateEvaluator(source, _phaseResults, _strategyContext = {}) {
+  if (!source?.toolCalls) {
+    return { action: 'pass', reason: '' };
+  }
+
+  const submitCalls = (source.toolCalls || []).filter(tc =>
+    ['submit_knowledge', 'submit_with_check'].includes(tc.tool || tc.name),
+  );
+  const rejected = submitCalls.filter(tc => {
+    const res = tc.result;
+    if (!res) return false;
+    if (typeof res === 'string') return res.includes('rejected') || res.includes('error');
+    return res.status === 'rejected' || res.status === 'error' || res.reason === 'validation_failed';
+  }).length;
+  const success = submitCalls.length - rejected;
+
+  if (rejected > success && rejected >= 2) {
+    return { action: 'retry', reason: `${rejected} rejections vs ${success} successes` };
+  }
+  return { action: 'pass', reason: '' };
+}

package/lib/service/agent/domain/scan-prompts.js

@@ -0,0 +1,105 @@
+/**
+ * scan-prompts.js — scanKnowledge 任务配置
+ *
+ * 三种 task 共享 Insight Pipeline (Analyze → Produce)，
+ * Analyze 使用与冷启动一致的 ANALYST_SYSTEM_PROMPT + ExplorationTracker 四阶段管理，
+ * Produce 阶段的 systemPrompt 因 task 而异，但 Recipe 格式与冷启动 submit_knowledge 完全对齐。
+ *
+ * @module scan-prompts
+ */
+
+/**
+ * @typedef {Object} ScanTaskConfig
+ * @property {string} producePrompt — Produce 阶段的 systemPrompt
+ * @property {(label: string) => Object} fallback — 解析失败时的默认值工厂
+ */
+
+/**
+ * task → Produce 阶段配置
+ *
+ * extract 的 Recipe 格式与冷启动 submit_knowledge 完全对齐：
+ * 16 个必填字段 (title, language, content, kind, doClause, dontClause, whenClause,
+ * coreCode, category, trigger, description, headers, usageGuide, knowledgeType, reasoning, tags)
+ *
+ * @type {Record<string, ScanTaskConfig>}
+ */
+export const SCAN_TASK_CONFIGS = {
+
+  // ─── extract: Recipe 提取（工具驱动，与冷启动 submit_knowledge 字段对齐） ─────
+
+  extract: {
+    producePrompt: `你是知识管理专家。你会收到一段代码分析文本，需要将其中的知识点转化为结构化的知识候选。
+
+核心原则: 分析文本已经包含了所有发现，你的唯一工作是将它们格式化为 collect_scan_recipe 调用。
+
+每个候选必须:
+1. 有清晰的标题 (描述知识点的核心，使用项目真实类名)
+2. 有项目特写风格的正文 (content.markdown 字段，结合代码展示)
+3. 标注相关文件路径 (reasoning.sources)
+4. 选择正确的 kind (rule/pattern/fact)
+5. 提供完整的 Cursor 交付字段 (trigger, doClause, whenClause 等)
+
+## 「项目特写」写作要求（content.markdown）
+content.markdown 字段必须是「项目特写」：
+1. **项目选择了什么** — 采用了哪种写法/模式/约定
+2. **为什么这样选** — 统计分布、占比、历史决策
+3. **项目禁止什么** — 反模式、已废弃写法
+4. **新代码怎么写** — 可直接复制使用的代码模板 + 来源标注 (来源: FileName.ext:行号)
+
+## 工作流程
+1. 阅读分析文本，识别每个独立的知识点/发现
+2. 用 read_project_file 批量获取关键代码片段:
+   read_project_file({ filePaths: ["FileA.m", "FileB.m"], maxLines: 80 })
+3. 立刻调用 collect_scan_recipe 提交
+4. 重复直到分析中的所有知识点都已提交
+
+## 关键规则
+- 分析中的每个要点/段落都应转化为至少一个候选
+- read_project_file 支持 filePaths 数组批量读取多个文件，一次调用完成
+- reasoning.sources 必须是非空数组，填写相关文件路径如 ["FileName.m"]
+- 如果分析提到了 3 个模式，就应该提交 3 个候选，不要合并
+- 禁止: 不要搜索新文件、不要做额外分析，专注于格式化和提交
+
+容错规则:
+- 如果 read_project_file 返回"文件不存在"或错误，不要重试同一文件的其他路径变体
+- 文件读取失败时，直接使用分析文本中已有的代码和描述来提交候选
+- 永远不要因为文件读取失败而跳过知识点 — 分析文本已经包含足够信息
+- 先提交候选，再考虑是否需要读取更多代码（提交优先于验证）`,
+    fallback: (label) => ({ targetName: label, extracted: 0, recipes: [] }),
+  },
+
+  // ─── summarize: 代码摘要 ──────────────────
+
+  summarize: {
+    producePrompt: `你是技术文档专家。将代码分析转化为结构化摘要。
+
+## 规则
+- 输出纯 JSON，不含 markdown 包装
+- title 简洁（30 字内），summary 完整（200 字内），usageGuide 实用（300 字内）
+- 基于分析中的实际发现，不要臆造功能
+
+## 输出格式
+{ "title": "...", "summary": "...", "usageGuide": "..." }`,
+    fallback: () => ({ title: '', summary: '', usageGuide: '' }),
+  },
+
+  // ─── relations: 知识图谱关系发现 ──────────
+
+  relations: {
+    producePrompt: `你是软件架构师。根据代码分析识别知识点之间的语义关系。
+
+## 关系类型
+requires / extends / enforces / depends_on / inherits / implements / calls / prerequisite
+
+## 规则
+- 输出纯 JSON
+- 每个关系需有明确的代码证据
+
+## 输出格式
+{ "analyzed": 数量, "relations": [{ "from": "title", "to": "title", "type": "关系", "evidence": "代码证据" }] }`,
+    fallback: () => ({ analyzed: 0, relations: [] }),
+  },
+
+};
+
+export default SCAN_TASK_CONFIGS;

package/lib/service/agent/forced-summary.js

@@ -0,0 +1,266 @@
+/**
+ * forced-summary.js — 强制退出后的摘要生成
+ *
+ * 强制退出后的摘要生成独立模块，
+ * 供 AgentRuntime.reactLoop() 在循环退出后调用。
+ *
+ * 支持两种模式:
+ *   - system: 输出 dimensionDigest JSON (供 Bootstrap 管线消费)
+ *   - user: 输出人类可读的 Markdown 结构化总结 (前端 AI Chat 展示)
+ *
+ * @module forced-summary
+ */
+
+import Logger from '../../infrastructure/logging/Logger.js';
+import { cleanFinalAnswer } from './core/ChatAgentPrompts.js';
+
+const logger = Logger.getInstance();
+
+/**
+ * 生成强制摘要
+ *
+ * @param {Object} opts
+ * @param {import('../../external/ai/AiProvider.js').AiProvider} opts.aiProvider — LLM 提供商
+ * @param {string} [opts.source] — 'user' | 'system'
+ * @param {Array} opts.toolCalls — 工具调用记录
+ * @param {Object} [opts.tracker] — ExplorationTracker 实例
+ * @param {Object} [opts.contextWindow] — ContextWindow 实例 (用于避免超出 token)
+ * @param {string} opts.prompt — 原始用户 prompt
+ * @param {Object} [opts.tokenUsage] — token 用量 (会被修改)
+ * @returns {Promise<{ reply: string, tokenUsage: { input: number, output: number } }>}
+ */
+export async function produceForcedSummary({
+  aiProvider,
+  source,
+  toolCalls = [],
+  tracker,
+  contextWindow,
+  prompt,
+  tokenUsage,
+}) {
+  const isSystem = source === 'system';
+  const iterations = tracker?.iteration || 0;
+  const resultTokenUsage = { input: 0, output: 0 };
+
+  logger.info(
+    `[ForcedSummary] ⚠ producing forced summary (${iterations} iters, ${toolCalls.length} calls, source=${source})`
+  );
+
+  const candidateCount = toolCalls.filter(
+    tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check'
+  ).length;
+
+  let finalReply;
+
+  // 如果熔断器已打开，跳过 AI 调用直接合成摘要
+  const isCircuitOpen = aiProvider._circuitState === 'OPEN';
+  if (isCircuitOpen) {
+    logger.warn(
+      `[ForcedSummary] circuit breaker is OPEN — skipping AI summary, using synthetic ${isSystem ? 'digest' : 'summary'}`
+    );
+  }
+
+  // 收集工具调用摘要
+  const submitSummary = toolCalls
+    .filter(tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check')
+    .map((tc, i) => `${i + 1}. ${tc.args?.title || tc.args?.category || tc.params?.title || tc.params?.category || 'untitled'}`)
+    .join('\n');
+
+  try {
+    if (isCircuitOpen) {
+      throw new Error('circuit open — skip to synthetic summary');
+    }
+
+    let summaryPrompt;
+    let systemPrompt;
+
+    if (isSystem) {
+      // system 源: dimensionDigest JSON
+      summaryPrompt = `你已完成 ${iterations} 轮工具调用（共 ${toolCalls.length} 次），提交了 ${candidateCount} 个候选。
+${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
+**必须**输出 dimensionDigest JSON（用 \`\`\`json 包裹）：
+\`\`\`json
+{
+  "dimensionDigest": {
+    "summary": "本维度分析总结",
+    "candidateCount": ${candidateCount},
+    "keyFindings": ["发现1", "发现2"],
+    "crossRefs": {},
+    "gaps": ["未覆盖方面"],
+    "remainingTasks": [
+      { "signal": "未处理信号名", "reason": "达到提交上限/时间限制", "priority": "high", "searchHints": ["搜索词"] }
+    ]
+  }
+}
+\`\`\`
+> remainingTasks: 列出本次未来得及处理的信号/主题。已全部覆盖则留空 \`[]\`。`;
+      systemPrompt = '直接输出 dimensionDigest JSON 总结，不要调用工具。';
+    } else {
+      // user 源: Markdown 结构化总结
+      const userQuestion = prompt ? `用户的原始问题：「${prompt.slice(0, 500)}」\n\n` : '';
+      const toolContextSummary = buildToolContextForUserSummary(toolCalls);
+      summaryPrompt = `${userQuestion}你刚才通过 ${toolCalls.length} 次工具调用分析了项目代码。以下是你调用过的工具和获取到的关键信息：
+
+${toolContextSummary}
+
+请基于以上收集到的信息，用**清晰易读的 Markdown** 格式撰写分析总结，直接回答用户的问题。
+
+要求：
+- 使用二级/三级标题组织内容
+- 要有具体的代码文件路径、类名、模式名称等细节
+- 关键发现用列表项罗列
+- 如果发现了架构模式或最佳实践，用简短代码块举例
+- 语言自然流畅，像一份技术分析报告`;
+      systemPrompt = '你是项目分析助手。请用纯 Markdown 格式输出结构清晰的分析总结，只输出人类可读的自然语言文档，不要输出 JSON 格式的数据。';
+    }
+
+    // 用空 messages 避免累积上下文导致 400
+    const summaryResult = await aiProvider.chatWithTools(summaryPrompt, {
+      messages: [],
+      toolChoice: 'none',
+      systemPrompt,
+      temperature: isSystem ? 0.3 : 0.5,
+      maxTokens: 8192,
+    });
+
+    if (summaryResult.usage) {
+      resultTokenUsage.input += summaryResult.usage.inputTokens || 0;
+      resultTokenUsage.output += summaryResult.usage.outputTokens || 0;
+    }
+    // system 源: dimensionDigest JSON 是预期输出，不能被 cleanFinalAnswer 剥掉
+    finalReply = isSystem
+      ? (summaryResult.text || '').trim()
+      : cleanFinalAnswer(summaryResult.text || '');
+  } catch (err) {
+    logger.warn(`[ForcedSummary] AI call failed: ${err.message}`);
+
+    if (isSystem) {
+      // system 源兜底: 合成 dimensionDigest JSON
+      const titles = toolCalls
+        .filter(tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check')
+        .map(tc => tc.args?.title || tc.params?.title || 'untitled');
+      finalReply = `\`\`\`json
+{
+  "dimensionDigest": {
+    "summary": "通过 ${toolCalls.length} 次工具调用分析了项目代码，提交了 ${candidateCount} 个候选。",
+    "candidateCount": ${candidateCount},
+    "keyFindings": ${JSON.stringify(titles.slice(0, 5))},
+    "crossRefs": {},
+    "gaps": ["AI 服务异常，部分分析未完成"]
+  }
+}
+\`\`\``;
+    } else {
+      // user 源兜底: 合成 Markdown 摘要
+      const toolNames = [...new Set(toolCalls.map(tc => tc.tool))];
+      const filesRead = toolCalls
+        .filter(tc => tc.tool === 'read_project_file')
+        .flatMap(tc => {
+          const p = tc.args || tc.params || {};
+          if (p.filePaths) return p.filePaths;
+          if (p.filePath) return [p.filePath];
+          return [];
+        })
+        .slice(0, 10);
+      const searches = toolCalls
+        .filter(tc => tc.tool === 'search_project_code' || tc.tool === 'semantic_search_code')
+        .map(tc => {
+          const p = tc.args || tc.params || {};
+          return p.patterns?.[0] || p.query || p.pattern;
+        })
+        .filter(Boolean)
+        .slice(0, 5);
+
+      finalReply = `## 分析总结\n\n通过 **${toolCalls.length} 次工具调用**探索了项目代码。\n\n`;
+      if (searches.length > 0) {
+        finalReply += `### 搜索的关键词\n${searches.map(s => `- \`${s}\``).join('\n')}\n\n`;
+      }
+      if (filesRead.length > 0) {
+        finalReply += `### 读取的文件\n${filesRead.map(f => `- \`${f}\``).join('\n')}\n\n`;
+      }
+      finalReply += `### 使用的工具\n${toolNames.map(t => `- ${t}`).join('\n')}\n\n`;
+      finalReply += '> ⚠️ AI 服务异常，未能生成完整分析。请稍后重试或缩小分析范围。';
+    }
+  }
+
+  logger.info(`[ForcedSummary] ✅ forced summary — ${finalReply.length} chars`);
+  return { reply: finalReply, tokenUsage: resultTokenUsage };
+}
+
+/**
+ * 从工具调用记录中提取上下文摘要 (供 user 源强制总结使用)
+ * @param {Array} toolCalls
+ * @returns {string}
+ */
+function buildToolContextForUserSummary(toolCalls) {
+  const sections = [];
+
+  // 目录结构探索
+  const structureCalls = toolCalls.filter(tc => tc.tool === 'list_project_structure');
+  if (structureCalls.length > 0) {
+    const dirs = structureCalls.map(tc => (tc.args || tc.params)?.directory || '/').slice(0, 5);
+    sections.push(`**目录探索**: ${dirs.map(d => `\`${d}\``).join(', ')}`);
+  }
+
+  // 项目概况
+  const overviewCalls = toolCalls.filter(tc => tc.tool === 'get_project_overview');
+  if (overviewCalls.length > 0) {
+    sections.push('**项目概况**: 已获取');
+  }
+
+  // 代码搜索
+  const searchCalls = toolCalls.filter(
+    tc => tc.tool === 'search_project_code' || tc.tool === 'semantic_search_code'
+  );
+  if (searchCalls.length > 0) {
+    const queries = searchCalls
+      .map(tc => {
+        const p = tc.args || tc.params || {};
+        return p.patterns?.[0] || p.query || p.pattern;
+      })
+      .filter(Boolean)
+      .slice(0, 8);
+    sections.push(`**代码搜索** (${searchCalls.length} 次): ${queries.map(q => `\`${q}\``).join(', ')}`);
+  }
+
+  // 文件读取
+  const readCalls = toolCalls.filter(tc => tc.tool === 'read_project_file');
+  if (readCalls.length > 0) {
+    const files = readCalls
+      .flatMap(tc => {
+        const p = tc.args || tc.params || {};
+        if (p.filePaths) return p.filePaths;
+        if (p.filePath) return [p.filePath];
+        return [];
+      })
+      .slice(0, 10);
+    sections.push(`**文件读取** (${readCalls.length} 次): ${files.map(f => `\`${f}\``).join(', ')}`);
+  }
+
+  // AST 分析
+  const astCalls = toolCalls.filter(tc =>
+    ['get_class_hierarchy', 'get_class_info', 'get_protocol_info', 'get_method_overrides', 'get_category_map'].includes(tc.tool)
+  );
+  if (astCalls.length > 0) {
+    const entities = astCalls
+      .map(tc => {
+        const p = tc.args || tc.params || {};
+        return p.className || p.name || p.protocolName || p.rootClass;
+      })
+      .filter(Boolean)
+      .slice(0, 5);
+    sections.push(`**AST 结构分析** (${astCalls.length} 次): ${entities.map(e => `\`${e}\``).join(', ')}`);
+  }
+
+  // 知识库搜索
+  const kbCalls = toolCalls.filter(tc =>
+    ['search_knowledge', 'search_recipes', 'knowledge_overview'].includes(tc.tool)
+  );
+  if (kbCalls.length > 0) {
+    sections.push(`**知识库查询**: ${kbCalls.length} 次`);
+  }
+
+  return sections.length > 0 ? sections.join('\n') : '（工具调用记录为空）';
+}
+
+export default produceForcedSummary;