mcp-probe-kit 3.0.18 → 3.0.19

package/build/tools/start_bugfix.js

@@ -1,5 +1,4 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
 import { parseArgs, getString, getNumber } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
@@ -8,6 +7,7 @@ import { reportToolProgress, throwIfAborted, } from "../lib/tool-execution-conte
 import { buildBugfixGraphContext } from "../lib/gitnexus-bridge.js";
 import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, } from "../lib/memory-orchestration.js";
 import { resolveWorkspaceRoot, isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
+import { layoutAbsPath, parseLayoutArgsFromRecord, resolveProjectContextLayout, } from "../lib/project-context-layout.js";
 function decideTemplateProfile(description) {
     const text = description || '';
     const lengthScore = text.length >= 200 ? 2 : text.length >= 120 ? 1 : 0;
@@ -46,232 +46,232 @@ function resolveTemplateProfile(rawProfile, description) {
         warning: `模板档位 "${rawProfile}" 不支持，已回退为 ${fallback}`,
     };
 }
-const PROMPT_TEMPLATE_GUIDED = `# 🐛 Bug 修复编排指南（TBP 8 步真因分析）
-
-## 🎯 目标
-
-修复以下 Bug：
-
-**错误信息**:
-\`\`\`
-{error_message}
-\`\`\`
-
-{stack_trace_section}
-
----
-
-## 📋 步骤 0: 项目上下文与取证基线（自动处理）
-
-**操作**:
-1. 检查 \`docs/project-context.md\` 是否存在
-2. 检查 \`docs/graph-insights/latest.md\` 和 \`docs/graph-insights/latest.json\` 是否存在
-3. **如果任一缺失**：
-   - 调用 \`init_project_context\` 工具
-   - 等待生成完成
-4. **读取** \`docs/project-context.md\` 与图谱文档
-5. 了解项目的技术栈、架构、测试框架和调用链
-6. 后续步骤参考此上下文
-
----
-
-## 🔍 步骤 1: 先做 TBP 1-7，再决定修复
-
-**调用工具**: \`fix_bug\`
-
-**参数**:
-\`\`\`json
-{
-  "error_message": "{error_message}",
-  "stack_trace": "{stack_trace}"
-}
-\`\`\`
-
-**执行要点**:
-1. 先定义现象，不能泛化
-2. 复盘时间线，尽量带时间/步骤/状态
-3. 明确排除错误方向，并说明为什么不是
-4. 对比成功/失败样本，找分叉点
-5. 定位问题边界（模型 / 状态机 / 工具 / 文件 / 环境）
-6. 用因果句陈述真因：A + B 在条件 D 下导致 C
-7. 闭合证据链后，才进入修复设计
-8. 修复必须说明风险与验证方式
-
-**产出**: 修复后的代码
-
----
-
-## 🧪 步骤 2: 生成回归测试
-
-**调用工具**: \`gentest\`
-
-**参数**:
-\`\`\`json
-{
-  "code": "[修复后的代码]",
-  "framework": "[根据项目上下文选择: jest/vitest/mocha]"
-}
-\`\`\`
-
-**执行要点**:
-1. 为修复的代码生成测试
-2. 包含 Bug 场景的测试用例
-3. 包含边界情况测试
-
-**产出**: 测试代码
-
----
-
-## ✅ 完成检查
-
-- [ ] 项目上下文已读取
-- [ ] TBP-1~TBP-7 已闭合
-- [ ] 真因已写成因果句
-- [ ] 代码已修复
-- [ ] 测试已添加
-- [ ] 测试已通过
-
----
-
-## 📝 输出汇总
-
-完成后，向用户汇总：
-
-1. **TBP 现象**: [精确定义的问题]
-2. **TBP 时间线**: [关键事件顺序]
-3. **已排除方向**: [不是哪些原因]
-4. **问题边界**: [失控发生在哪一层]
-5. **Bug 真因**: [根本原因]
-6. **修复方案**: [修复说明]
-7. **修改文件**: [文件列表]
-8. **测试覆盖**: [测试情况]
-
----
-
-*编排工具: MCP Probe Kit - start_bugfix*
+const PROMPT_TEMPLATE_GUIDED = `# 🐛 Bug 修复编排指南（TBP 8 步真因分析）
+
+## 🎯 目标
+
+修复以下 Bug：
+
+**错误信息**:
+\`\`\`
+{error_message}
+\`\`\`
+
+{stack_trace_section}
+
+---
+
+## 📋 步骤 0: 项目上下文与取证基线（自动处理）
+
+**操作**:
+1. 检查 \`docs/project-context.md\` 是否存在
+2. 检查 \`docs/graph-insights/latest.md\` 和 \`docs/graph-insights/latest.json\` 是否存在
+3. **如果任一缺失**：
+   - 调用 \`init_project_context\` 工具
+   - 等待生成完成
+4. **读取** \`docs/project-context.md\` 与图谱文档
+5. 了解项目的技术栈、架构、测试框架和调用链
+6. 后续步骤参考此上下文
+
+---
+
+## 🔍 步骤 1: 先做 TBP 1-7，再决定修复
+
+**调用工具**: \`fix_bug\`
+
+**参数**:
+\`\`\`json
+{
+  "error_message": "{error_message}",
+  "stack_trace": "{stack_trace}"
+}
+\`\`\`
+
+**执行要点**:
+1. 先定义现象，不能泛化
+2. 复盘时间线，尽量带时间/步骤/状态
+3. 明确排除错误方向，并说明为什么不是
+4. 对比成功/失败样本，找分叉点
+5. 定位问题边界（模型 / 状态机 / 工具 / 文件 / 环境）
+6. 用因果句陈述真因：A + B 在条件 D 下导致 C
+7. 闭合证据链后，才进入修复设计
+8. 修复必须说明风险与验证方式
+
+**产出**: 修复后的代码
+
+---
+
+## 🧪 步骤 2: 生成回归测试
+
+**调用工具**: \`gentest\`
+
+**参数**:
+\`\`\`json
+{
+  "code": "[修复后的代码]",
+  "framework": "[根据项目上下文选择: jest/vitest/mocha]"
+}
+\`\`\`
+
+**执行要点**:
+1. 为修复的代码生成测试
+2. 包含 Bug 场景的测试用例
+3. 包含边界情况测试
+
+**产出**: 测试代码
+
+---
+
+## ✅ 完成检查
+
+- [ ] 项目上下文已读取
+- [ ] TBP-1~TBP-7 已闭合
+- [ ] 真因已写成因果句
+- [ ] 代码已修复
+- [ ] 测试已添加
+- [ ] 测试已通过
+
+---
+
+## 📝 输出汇总
+
+完成后，向用户汇总：
+
+1. **TBP 现象**: [精确定义的问题]
+2. **TBP 时间线**: [关键事件顺序]
+3. **已排除方向**: [不是哪些原因]
+4. **问题边界**: [失控发生在哪一层]
+5. **Bug 真因**: [根本原因]
+6. **修复方案**: [修复说明]
+7. **修改文件**: [文件列表]
+8. **测试覆盖**: [测试情况]
+
+---
+
+*编排工具: MCP Probe Kit - start_bugfix*
 `;
-const PROMPT_TEMPLATE_STRICT = `# 🐛 Bug 修复编排（严格 | TBP 8 步）
-
-## 🎯 目标
-修复 Bug：{error_message}
-
-{stack_trace_section}
-
----
-
-## ✅ 执行计划（按顺序）
-
-1) 检查 \`docs/project-context.md\` 与 \`docs/graph-insights/latest.*\`，任一缺失则调用 \`init_project_context\`
-2) 调用 \`fix_bug\`
-\`\`\`json
-{
-  "error_message": "{error_message}",
-  "stack_trace": "{stack_trace}",
-  "analysis_mode": "{analysis_mode}"
-}
-\`\`\`
-3) 调用 \`gentest\`
-\`\`\`json
-{
-  "code": "[修复后的代码]",
-  "framework": "[根据项目上下文选择: jest/vitest/mocha]"
-}
-\`\`\`
-
----
-
-## ✅ 输出汇总
-1. TBP 现象
-2. TBP 时间线
-3. 已排除方向
-4. 问题边界
-5. Bug 真因
-6. 修复方案
-7. 修改文件
-8. 测试覆盖
-
----
-
-*编排工具: MCP Probe Kit - start_bugfix*
+const PROMPT_TEMPLATE_STRICT = `# 🐛 Bug 修复编排（严格 | TBP 8 步）
+
+## 🎯 目标
+修复 Bug：{error_message}
+
+{stack_trace_section}
+
+---
+
+## ✅ 执行计划（按顺序）
+
+1) 检查 \`docs/project-context.md\` 与 \`docs/graph-insights/latest.*\`，任一缺失则调用 \`init_project_context\`
+2) 调用 \`fix_bug\`
+\`\`\`json
+{
+  "error_message": "{error_message}",
+  "stack_trace": "{stack_trace}",
+  "analysis_mode": "{analysis_mode}"
+}
+\`\`\`
+3) 调用 \`gentest\`
+\`\`\`json
+{
+  "code": "[修复后的代码]",
+  "framework": "[根据项目上下文选择: jest/vitest/mocha]"
+}
+\`\`\`
+
+---
+
+## ✅ 输出汇总
+1. TBP 现象
+2. TBP 时间线
+3. 已排除方向
+4. 问题边界
+5. Bug 真因
+6. 修复方案
+7. 修改文件
+8. 测试覆盖
+
+---
+
+*编排工具: MCP Probe Kit - start_bugfix*
 `;
-const LOOP_PROMPT_TEMPLATE_GUIDED = `# 🧭 Bug 需求澄清与补全（TBP RCA Loop）
-
-本模式用于**生产级稳健补全**：在不改变用户意图的前提下补齐 TBP 8 步真因分析所需证据。
-
-## 🎯 目标
-修复 Bug：{error_message}
-
-## ✅ 规则
-1. **不覆盖用户原始描述**
-2. **补全内容必须标注来源**（User / Derived / Assumption）
-3. **假设必须进入待确认列表**
-4. **每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}**
-
----
-
-## 🔁 执行步骤（每轮）
-
-### 1) 生成待确认问题
-使用 \`ask_user\` 提问，问题来源于 TBP 清单（现象/时间线/对比样本/边界/验证）。
-
-**调用示例**:
-\`\`\`json
-{
-  "questions": [
-    { "question": "复现步骤是什么？", "context": "复现步骤", "required": true },
-    { "question": "期望行为是什么？", "context": "期望行为", "required": true }
-  ]
-}
-\`\`\`
-
-### 2) 更新结构化输出
-将回答补入 \`requirements\`，并标注来源：
-- User：用户明确回答
-- Derived：合理推导
-- Assumption：无法确认但补全（需确认）
-
-### 3) 自检与结束
-若 \`openQuestions\` 为空且无高风险假设，则结束 loop，进入 TBP-6/7/8 修复流程。
-
----
-
-## ✅ 结束后继续
-当满足结束条件时，执行：
-1. 调用 \`fix_bug\` 完成 TBP 8 步分析与修复方案
-2. 调用 \`gentest\` 生成回归测试
-
----
-
-*编排工具: MCP Probe Kit - start_bugfix (requirements loop)*
+const LOOP_PROMPT_TEMPLATE_GUIDED = `# 🧭 Bug 需求澄清与补全（TBP RCA Loop）
+
+本模式用于**生产级稳健补全**：在不改变用户意图的前提下补齐 TBP 8 步真因分析所需证据。
+
+## 🎯 目标
+修复 Bug：{error_message}
+
+## ✅ 规则
+1. **不覆盖用户原始描述**
+2. **补全内容必须标注来源**（User / Derived / Assumption）
+3. **假设必须进入待确认列表**
+4. **每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}**
+
+---
+
+## 🔁 执行步骤（每轮）
+
+### 1) 生成待确认问题
+使用 \`ask_user\` 提问，问题来源于 TBP 清单（现象/时间线/对比样本/边界/验证）。
+
+**调用示例**:
+\`\`\`json
+{
+  "questions": [
+    { "question": "复现步骤是什么？", "context": "复现步骤", "required": true },
+    { "question": "期望行为是什么？", "context": "期望行为", "required": true }
+  ]
+}
+\`\`\`
+
+### 2) 更新结构化输出
+将回答补入 \`requirements\`，并标注来源：
+- User：用户明确回答
+- Derived：合理推导
+- Assumption：无法确认但补全（需确认）
+
+### 3) 自检与结束
+若 \`openQuestions\` 为空且无高风险假设，则结束 loop，进入 TBP-6/7/8 修复流程。
+
+---
+
+## ✅ 结束后继续
+当满足结束条件时，执行：
+1. 调用 \`fix_bug\` 完成 TBP 8 步分析与修复方案
+2. 调用 \`gentest\` 生成回归测试
+
+---
+
+*编排工具: MCP Probe Kit - start_bugfix (requirements loop)*
 `;
-const LOOP_PROMPT_TEMPLATE_STRICT = `# 🧭 Bug 需求澄清与补全（TBP RCA Loop | 严格）
-
-本模式用于稳健补全关键信息，不改变用户意图。
-
-## 🎯 目标
-修复 Bug：{error_message}
-
-## ✅ 规则
-1. 不覆盖用户原始描述
-2. 补全内容标注来源（User / Derived / Assumption）
-3. 假设进入待确认列表
-4. 每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}
-
----
-
-## 🔁 执行步骤（每轮）
-1) 使用 \`ask_user\` 提问补全关键信息
-2) 更新结构化输出并标注来源
-3) 若 \`openQuestions\` 为空且无高风险假设则结束
-
----
-
-## ✅ 结束后继续
-当满足结束条件时，调用 \`fix_bug\` 与 \`gentest\`
-
----
-
-*编排工具: MCP Probe Kit - start_bugfix (requirements loop)*
+const LOOP_PROMPT_TEMPLATE_STRICT = `# 🧭 Bug 需求澄清与补全（TBP RCA Loop | 严格）
+
+本模式用于稳健补全关键信息，不改变用户意图。
+
+## 🎯 目标
+修复 Bug：{error_message}
+
+## ✅ 规则
+1. 不覆盖用户原始描述
+2. 补全内容标注来源（User / Derived / Assumption）
+3. 假设进入待确认列表
+4. 每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}
+
+---
+
+## 🔁 执行步骤（每轮）
+1) 使用 \`ask_user\` 提问补全关键信息
+2) 更新结构化输出并标注来源
+3) 若 \`openQuestions\` 为空且无高风险假设则结束
+
+---
+
+## ✅ 结束后继续
+当满足结束条件时，调用 \`fix_bug\` 与 \`gentest\`
+
+---
+
+*编排工具: MCP Probe Kit - start_bugfix (requirements loop)*
 `;
 function buildBugfixQuestions(questionBudget) {
     const base = [
@@ -319,6 +319,7 @@ export async function startBugfix(args, context) {
         const stackTrace = getString(parsedArgs.stack_trace);
         const codeContext = getString(parsedArgs.code_context);
         const projectRoot = getString(parsedArgs.project_root);
+        const docsDir = getString(parsedArgs.docs_dir) || "docs";
         if (isLikelyProjectNamedRelativePath(projectRoot)) {
             return {
                 content: [{
@@ -371,15 +372,20 @@ export async function startBugfix(args, context) {
         }
         throwIfAborted(context?.signal, "start_bugfix 已取消");
         await reportToolProgress(context, 55, "start_bugfix: 刷新图谱并收敛问题范围");
+        const resolvedProjectRoot = resolveWorkspaceRoot(projectRoot);
+        const layout = resolveProjectContextLayout(resolvedProjectRoot, parseLayoutArgsFromRecord({ docs_dir: docsDir }));
         const graphDocs = {
-            latestMarkdownPath: "docs/graph-insights/latest.md",
-            latestJsonPath: "docs/graph-insights/latest.json",
+            latestMarkdownPath: layout.latestMarkdownPath,
+            latestJsonPath: layout.latestJsonPath,
         };
-        const resolvedProjectRoot = resolveWorkspaceRoot(projectRoot);
         const bootstrapState = {
-            projectContextExists: fs.existsSync(path.join(resolvedProjectRoot, "docs", "project-context.md")),
-            latestMarkdownExists: fs.existsSync(path.join(resolvedProjectRoot, "docs", "graph-insights", "latest.md")),
-            latestJsonExists: fs.existsSync(path.join(resolvedProjectRoot, "docs", "graph-insights", "latest.json")),
+            projectContextExists: fs.existsSync(layoutAbsPath(layout, layout.indexPath)) ||
+                fs.existsSync(layoutAbsPath(layout, layout.legacyIndexPath)),
+            latestMarkdownExists: fs.existsSync(layoutAbsPath(layout, layout.latestMarkdownPath)),
+            latestJsonExists: fs.existsSync(layoutAbsPath(layout, layout.latestJsonPath)),
+            indexPath: layout.indexPath,
+            projectRoot: layout.projectRootPosix,
+            layoutManifest: layout.manifestPath,
         };
         const graphDocsMissing = !bootstrapState.latestMarkdownExists || !bootstrapState.latestJsonExists;
         const graphContext = await buildBugfixGraphContext({
@@ -404,18 +410,18 @@ export async function startBugfix(args, context) {
         ]
             .filter(Boolean)
             .join("\n\n");
-        const graphGuideSection = `
-
-## 🧠 代码图谱上下文
-- 基线入口: ${graphDocs.latestMarkdownPath}
-- 基线结构化副本: ${graphDocs.latestJsonPath}
-- 基线状态: ${graphDocsMissing ? "缺失（需要补初始化）" : "可用"}
-- 任务级收敛: ${graphContext.available ? "可用" : "降级"}
-- 任务级摘要: ${graphContext.summary}
+        const graphGuideSection = `
+
+## 🧠 代码图谱上下文
+- 基线入口: ${graphDocs.latestMarkdownPath}
+- 基线结构化副本: ${graphDocs.latestJsonPath}
+- 基线状态: ${graphDocsMissing ? "缺失（需要补初始化）" : "可用"}
+- 任务级收敛: ${graphContext.available ? "可用" : "降级"}
+- 任务级摘要: ${graphContext.summary}
 ${graphContext.highlights.length > 0
             ? `- 任务级线索:\n${graphContext.highlights.slice(0, 3).map((item) => `  - ${item}`).join("\n")}`
-            : "- 任务级线索: 无"}
-- 使用方式: 先读取基线图谱，再用本次任务图谱做 TBP-4 / TBP-5 / TBP-6 的边界与真因收敛
+            : "- 任务级线索: 无"}
+- 使用方式: 先读取基线图谱，再用本次任务图谱做 TBP-4 / TBP-5 / TBP-6 的边界与真因收敛
 `;
         const memoryContext = await loadMemoryInjectionContext([errorMessage, stackTrace, codeContext].filter(Boolean).join("\n"));
         const memoryGuideSection = renderMemoryGuideSection(memoryContext);
@@ -447,12 +453,12 @@ ${graphContext.highlights.length > 0
                     {
                         id: 'context',
                         tool: 'init_project_context',
-                        when: `缺少 docs/project-context.md 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
+                        when: `缺少 ${layout.indexPath} 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
                         args: {
                             docs_dir: 'docs',
                             ...(projectRoot ? { project_root: projectRoot } : {}),
                         },
-                        outputs: ['docs/project-context.md', graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
+                        outputs: [layout.indexPath, graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
                         note: `兼容老项目：如果旧项目没有 graph-insights/latest.*，先补齐图谱初始化再进入 bug 收敛`,
                     },
                     {
@@ -494,7 +500,7 @@ ${graphContext.highlights.length > 0
                         },
                         outputs: [],
                     },
-                    ...(memoryContext.enabled ? [buildMemoryPlanStep()] : []),
+                    ...(memoryContext.enabled ? [buildMemoryPlanStep('bugfix')] : []),
                 ],
             };
             const header = renderOrchestrationHeader({
@@ -590,12 +596,12 @@ ${graphContext.highlights.length > 0
                 {
                     id: 'context',
                     tool: 'init_project_context',
-                    when: `缺少 docs/project-context.md 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
+                    when: `缺少 ${layout.indexPath} 或 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}`,
                     args: {
-                        docs_dir: 'docs',
+                        docs_dir: layout.contextRoot,
                         ...(projectRoot ? { project_root: projectRoot } : {}),
                     },
-                    outputs: ['docs/project-context.md', graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
+                    outputs: [layout.indexPath, graphDocs.latestMarkdownPath, graphDocs.latestJsonPath],
                     note: `兼容老项目：如果旧项目没有 graph-insights/latest.*，先补齐图谱初始化再进入 bug 收敛`,
                 },
                 {
@@ -618,7 +624,7 @@ ${graphContext.highlights.length > 0
                     },
                     outputs: [],
                 },
-                ...(memoryContext.enabled ? [buildMemoryPlanStep()] : []),
+                ...(memoryContext.enabled ? [buildMemoryPlanStep('bugfix')] : []),
             ],
         };
         // 创建结构化的 Bug 修复报告
@@ -630,7 +636,7 @@ ${graphContext.highlights.length > 0
                 {
                     name: '检查项目上下文',
                     status: 'pending',
-                    description: '检查 docs/project-context.md 与 graph-insights/latest.* 是否存在，缺失则调用 init_project_context',
+                    description: `检查 ${layout.indexPath} 与 graph-insights/latest.* 是否存在，缺失则调用 init_project_context`,
                 },
                 {
                     name: 'Bug 分析与修复',