mcp-probe-kit 3.0.8 → 3.0.10

package/build/tools/fix_bug.js

@@ -1,321 +1,232 @@
 /**
  * fix_bug 工具
  *
- * 功能：指导完整的 Bug 修复流程
- * 模式：指令生成器模式 - 返回详细的修复指南，由 AI 执行实际操作
+ * 功能：基于 TBP 8 步法输出真因分析与修复指南
+ * 模式：指令生成器模式 - 返回详细的 RCA 与修复指南，由 AI 执行实际操作
  *
- * 流程：问题定位 → 原因分析 → 修复方案 → 验证测试
+ * 流程：定义现象 → 复盘时间线 → 排除错误方向 → 找共同模式 → 定位边界 → 陈述真因 → 闭合证据链 → 设计修复方案
  */
-const PROMPT_TEMPLATE = `# Bug 修复指南
-
-## 🐛 Bug 信息
-
-**错误信息**: 
-\`\`\`
-{error_message}
-\`\`\`
-
-{stack_trace_section}
-
-{reproduce_section}
-
-{behavior_section}
-
----
-
-## 📍 阶段 1: 问题定位
-
-### 步骤 1.1: 分析错误信息
-
-1. **识别错误类型**:
-   - 语法错误（SyntaxError）
-   - 运行时错误（TypeError, ReferenceError, RangeError）
-   - 逻辑错误（结果不符合预期）
-   - 异步错误（Promise rejection, 回调异常）
-
-2. **提取关键信息**:
-   - 错误名称: [从错误信息中提取]
-   - 错误消息: [具体描述]
-   - 发生位置: [文件:行号]
-
-### 步骤 1.2: 分析堆栈跟踪
-
-**操作**:
-1. 找到堆栈中第一个项目文件（排除 node_modules）
-2. 追踪调用链，理解执行流程
-3. 记录所有相关的项目文件
-
-**相关文件列表**:
-| 文件 | 行号 | 函数/方法 |
-|------|------|-----------|
-| [文件路径] | [行号] | [函数名] |
-
-### 步骤 1.3: 读取相关代码
-
-**操作**: 读取以下文件并分析：
-- 错误发生的文件
-- 调用链上的文件
-- 相关的配置文件
-- 相关的测试文件（如有）
-
-### 📋 定位结论
-
-| 项目 | 内容 |
-|------|------|
-| 问题文件 | [文件路径] |
-| 问题位置 | 第 X 行 |
-| 问题代码 | \`[代码片段]\` |
-| 触发条件 | [什么情况下触发] |
-
----
-
-## 🔍 阶段 2: 原因分析
-
-### 步骤 2.1: 5 Whys 分析
-
-使用 5 Whys 方法深入分析根本原因：
-
-1. **Why 1**: 为什么会出现这个错误？
-   - [答案]
-
-2. **Why 2**: 为什么会 [Why 1 的答案]？
-   - [答案]
-
-3. **Why 3**: 为什么会 [Why 2 的答案]？
-   - [答案]
-
-4. **Why 4**: 为什么会 [Why 3 的答案]？
-   - [答案]
-
-5. **Why 5**: 为什么会 [Why 4 的答案]？
-   - [答案]
-
-### 步骤 2.2: 代码逻辑分析
-
-1. **数据流分析**: 追踪数据从输入到出错位置的流动
-2. **状态分析**: 检查相关变量/状态在出错时的值
-3. **边界条件**: 检查是否处理了所有边界情况
-4. **异常处理**: 检查是否有适当的错误处理
-
-### 📋 分析结论
-
-| 项目 | 内容 |
-|------|------|
-| 直接原因 | [直接导致错误的原因] |
-| 根本原因 | [深层次的原因] |
-| 触发条件 | [什么情况下会触发] |
-| 影响范围 | [受影响的功能/模块] |
-
----
-
-## 🔧 阶段 3: 修复方案
-
-### 步骤 3.1: 设计修复方案
-
-**方案 A**: [方案描述]
-- 修改内容: [具体修改]
-- 优点: [优点]
-- 缺点: [缺点]
-- 风险: [潜在风险]
-
-**方案 B**: [备选方案描述]
-- 修改内容: [具体修改]
-- 优点: [优点]
-- 缺点: [缺点]
-- 风险: [潜在风险]
-
-**选择方案**: [选择的方案]
-**选择理由**: [为什么选择这个方案]
-
-### 步骤 3.2: 影响范围评估
-
-| 影响项 | 说明 |
-|--------|------|
-| 修改文件 | [文件列表] |
-| 影响功能 | [功能列表] |
-| 需要测试 | [测试范围] |
-| 是否需要回归 | [是/否] |
-
-### 步骤 3.3: 实施修复
-
-**修改文件**: \`[文件路径]\`
-
-**修改前**:
-\`\`\`
-[原代码]
-\`\`\`
-
-**修改后**:
-\`\`\`
-[新代码]
-\`\`\`
-
-**修改说明**: [解释修改的原因和逻辑]
-
----
-
-## ✅ 阶段 4: 验证测试
-
-### 步骤 4.1: 单元测试
-
-为修复编写针对性的单元测试：
-
-\`\`\`typescript
-describe('[功能描述]', () => {
-  // 测试正常情况
-  it('should [正常行为描述]', () => {
-    // 测试代码
-  });
-  
-  // 测试修复的 Bug 场景
-  it('should handle [Bug 场景]', () => {
-    // 测试代码 - 确保 Bug 已修复
-  });
-  
-  // 测试边界情况
-  it('should handle [边界情况]', () => {
-    // 边界测试
-  });
-});
-\`\`\`
-
-### 步骤 4.2: 手动验证
-
-1. [ ] 按原复现步骤验证问题已修复
-2. [ ] 验证正常流程不受影响
-3. [ ] 验证边界情况处理正确
-4. [ ] 验证错误处理正确
-
-### 步骤 4.3: 回归测试
-
-1. [ ] 运行相关模块的测试
-2. [ ] 运行全量测试（如有 CI）
-3. [ ] 检查是否引入新问题
-
----
-
-## 📋 修复检查清单
-
-### 定位阶段
-- [ ] 错误类型已识别
-- [ ] 问题代码已定位
-- [ ] 相关文件已读取
-
-### 分析阶段
-- [ ] 5 Whys 分析已完成
-- [ ] 根本原因已确定
-- [ ] 影响范围已评估
-
-### 修复阶段
-- [ ] 修复方案已设计
-- [ ] 代码修改已完成
-- [ ] 修改已解释清楚
-
-### 验证阶段
-- [ ] 单元测试已添加
-- [ ] 手动验证已通过
-- [ ] 回归测试已通过
-
-### 提交阶段
-- [ ] 代码已提交
-- [ ] Commit message 清晰描述了修复内容
-
----
-
-## 📝 修复总结
-
-完成修复后，填写以下总结：
-
-| 项目 | 内容 |
-|------|------|
-| Bug 描述 | [简述] |
-| 根本原因 | [原因] |
-| 修复方案 | [方案] |
-| 修改文件 | [文件列表] |
-| 测试覆盖 | [测试情况] |
-| 修复时间 | [耗时] |
-
----
-
-## 💡 经验教训
-
-记录本次 Bug 的经验教训，避免类似问题：
-
-1. **代码层面**: [如何避免写出类似 Bug]
-2. **测试层面**: [应该增加什么测试]
-3. **流程层面**: [流程上如何改进]
-
----
-
-## 📤 输出格式要求
-
-请严格按以下 JSON 格式输出修复指南：
-
-\`\`\`json
-{
-  "bug_summary": "Bug 简述（一句话）",
-  "analysis": {
-    "error_type": "错误类型",
-    "direct_cause": "直接原因",
-    "root_cause": "根本原因",
-    "affected_scope": "影响范围"
-  },
-  "location": {
-    "file": "问题文件路径",
-    "line": 42,
-    "function": "问题函数名",
-    "code_snippet": "问题代码片段"
-  },
-  "fix_plan": {
-    "chosen_solution": "选择的修复方案",
-    "reason": "选择理由",
-    "steps": [
-      { "step": 1, "action": "修复步骤", "file": "文件", "change": "变更内容" }
-    ],
-    "code_before": "修改前代码",
-    "code_after": "修改后代码"
-  },
-  "verification": {
-    "test_cases": ["测试用例1", "测试用例2"],
-    "manual_checks": ["手动验证项1", "手动验证项2"]
-  }
-}
-\`\`\`
-
-## ⚠️ 边界约束
-
-- ❌ 仅提供修复指南，不保证自动修改代码
-- ❌ 不执行代码或命令
-- ✅ 输出结构化修复方案和验证步骤
-- 💡 如需自动修复，可配合 fix 工具应用 patch
-
----
-
-*指南版本: 1.0.0*
-*工具: MCP Probe Kit - fix_bug*
-`;
 import { parseArgs, getString } from "../utils/parseArgs.js";
-import { okText } from "../lib/response.js";
+import { okStructured } from "../lib/response.js";
 import { renderGuidanceHeader } from "../lib/guidance.js";
 import { handleToolError } from "../utils/error-handler.js";
+const PROMPT_TEMPLATE = `# TBP 8 步 Bug 真因分析与修复指南
+
+## 🐛 Bug 信息
+
+**错误信息**:
+\`\`\`
+{error_message}
+\`\`\`
+
+{stack_trace_section}
+
+{reproduce_section}
+
+{behavior_section}
+
+{code_context_section}
+
+---
+
+## TBP-1 现象
+
+先把用户可见的问题定义准确，避免“坏了/卡了/有问题”这类泛化描述。
+
+要求：
+1. 用 1-2 句定义现象
+2. 明确是“慢”“停滞”“失败”“回归”还是“未生效”
+3. 如果提供了期望/实际行为，必须纳入现象定义
+
+## TBP-2 时间线
+
+基于现有信息复盘事件顺序，至少回答：
+1. 什么时候开始
+2. 中间发生了什么
+3. 最后停在什么状态
+
+优先记录：
+- 用户输入 / 复现步骤
+- first progress / first error
+- tool call / stack / stop / timeout
+- 关键文件或模块
+
+## TBP-3 不是这个
+
+列出当前应优先排除的错误方向，并说明需要什么证据排除。
+
+常见排除项：
+- 不是单纯网络慢
+- 不是前端展示截断
+- 不是消息没转发
+- 不是纯粹的超时表象
+- 不是用户输入丢失
+
+## TBP-4 共同模式
+
+对比成功/失败样本，找出从哪一步开始分叉。
+
+重点检查：
+- 传输层
+- 会话状态机
+- 完成态判定
+- 工具执行
+- 文件写入
+- 重试策略
+
+## TBP-5 边界
+
+明确指出问题失控落在哪一层：
+- 上游模型 / SDK
+- 网关状态机
+- session 复用
+- tool 执行层
+- 文件系统
+- 环境配置
+- UI 展示层
+
+## TBP-6 真因
+
+真因必须写成因果句：
+\`A + B 在条件 D 下导致了 C\`
+
+不允许只写：
+- 超时了
+- SDK 有 bug
+- 返回慢
+
+## TBP-7 证据链
+
+说明：
+1. 哪些证据支持真因
+2. 哪些现象若出现会推翻它，但现场没有出现
+3. 为什么其他解释更弱
+
+## TBP-8 修复
+
+只有在证据链闭合后，才开始设计修复。
+
+每个修复方案都要说明：
+- 改哪一层
+- 为什么这是修真因，不是补症状
+- 风险是什么
+- 怎么验证
+
+---
+
+## 📤 输出格式要求
+
+请严格按以下 JSON 格式输出修复指南：
+
+\`\`\`json
+{
+  "bug_summary": "Bug 简述（一句话）",
+  "analysis_mode": "tbp8",
+  "analysis": {
+    "error_type": "错误类型",
+    "direct_cause": "直接原因",
+    "root_cause": "根本原因",
+    "affected_scope": "影响范围"
+  },
+  "tbp": {
+    "phenomenon": "TBP-1 现象",
+    "timeline": [],
+    "ruled_out": [],
+    "common_pattern": "TBP-4 共同模式",
+    "boundary": "TBP-5 边界",
+    "root_cause_statement": "A + B 在条件 D 下导致 C",
+    "evidence": [],
+    "repair": []
+  },
+  "location": {
+    "file": "问题文件路径",
+    "line": 42,
+    "function": "问题函数名",
+    "code_snippet": "问题代码片段"
+  },
+  "fix_plan": {
+    "chosen_solution": "选择的修复方案",
+    "reason": "选择理由",
+    "steps": [
+      { "step": 1, "action": "修复步骤", "file": "文件", "change": "变更内容" }
+    ],
+    "code_before": "修改前代码",
+    "code_after": "修改后代码"
+  },
+  "verification": {
+    "test_cases": ["测试用例1", "测试用例2"],
+    "manual_checks": ["手动验证项1", "手动验证项2"]
+  }
+}
+\`\`\`
+
+## ⚠️ 护栏
+
+- 不要一看到新现象就补一个新分支，先判断是不是同一类根因在换表现
+- 不要把“超时”直接当真因，要先分清是没进展、慢进展，还是结果已出现但判定过严
+- 不要只看单一样本就下结论，有对比样本时必须做对比
+- 如果证据不足，要明确说明还缺什么证据
+
+---
+
+*指南版本: 2.0.0*
+*工具: MCP Probe Kit - fix_bug*
+`;
+function inferBugType(text) {
+    if (/timeout|latency|slow|卡|慢|超时/i.test(text))
+        return "performance";
+    if (/auth|permission|unauthor|token|登录|权限/i.test(text))
+        return "security";
+    if (/ui|render|white screen|白屏|按钮|页面/i.test(text))
+        return "ui";
+    if (/sql|db|data|schema|缓存|数据/i.test(text))
+        return "data";
+    if (/api|request|network|gateway|integration|调用失败/i.test(text))
+        return "integration";
+    return "functional";
+}
+function inferSeverity(text) {
+    if (/crash|fatal|panic|生产故障|数据丢失|security|权限绕过/i.test(text))
+        return "critical";
+    if (/white screen|白屏|500|无法登录|阻塞|不可用|timeout|超时/i.test(text))
+        return "high";
+    if (/error|exception|失败|异常/i.test(text))
+        return "medium";
+    return "low";
+}
+function extractFilePaths(text) {
+    if (!text)
+        return [];
+    const matches = text.match(/[A-Za-z]:[\\/][^:\n\r\t]+|(?:src|app|lib|server|client|docs)[\\/][^:\n\r\t)]+/g) || [];
+    return Array.from(new Set(matches.map((item) => item.replace(/\\/g, "/")))).slice(0, 8);
+}
+function summarizePhenomenon(errorMessage, expectedBehavior, actualBehavior) {
+    if (expectedBehavior || actualBehavior) {
+        return `实际表现为“${actualBehavior || errorMessage}”，但期望是“${expectedBehavior || "保持正常行为"}”。`;
+    }
+    return `当前可见现象是“${errorMessage}”，需要先区分它属于失败、停滞、未生效还是性能退化。`;
+}
 /**
  * fix_bug 工具实现
  */
 export async function fixBug(args) {
     try {
-        // 智能参数解析，支持自然语言输入
         const parsedArgs = parseArgs(args, {
             defaultValues: {
                 error_message: "",
                 stack_trace: "",
+                code_context: "",
+                analysis_mode: "tbp8",
                 steps_to_reproduce: "",
                 expected_behavior: "",
                 actual_behavior: "",
             },
-            primaryField: "error_message", // 纯文本输入默认映射到 error_message 字段
+            primaryField: "error_message",
             fieldAliases: {
                 error_message: ["error", "err", "message", "错误", "错误信息"],
                 stack_trace: ["stack", "trace", "堆栈", "调用栈"],
+                code_context: ["code_context", "code", "context", "相关代码", "代码上下文"],
+                analysis_mode: ["analysis_mode", "methodology", "tbp", "rca", "分析方法"],
                 steps_to_reproduce: ["steps", "reproduce", "步骤", "复现步骤"],
                 expected_behavior: ["expected", "期望", "期望行为"],
                 actual_behavior: ["actual", "实际", "实际行为"],
@@ -323,45 +234,119 @@ export async function fixBug(args) {
         });
         const errorMessage = getString(parsedArgs.error_message);
         const stackTrace = getString(parsedArgs.stack_trace);
+        const codeContext = getString(parsedArgs.code_context);
+        const analysisMode = (getString(parsedArgs.analysis_mode) || "tbp8").toLowerCase() === "tbp8"
+            ? "tbp8"
+            : "tbp8";
         const stepsToReproduce = getString(parsedArgs.steps_to_reproduce);
         const expectedBehavior = getString(parsedArgs.expected_behavior);
         const actualBehavior = getString(parsedArgs.actual_behavior);
         if (!errorMessage) {
             throw new Error("缺少必填参数: error_message（错误信息）");
         }
-        // 构建可选部分
         const stackTraceSection = stackTrace
             ? `**堆栈跟踪**:\n\`\`\`\n${stackTrace}\n\`\`\``
             : "**堆栈跟踪**: 未提供（建议提供以便更准确定位）";
         const reproduceSection = stepsToReproduce
             ? `**复现步骤**:\n${stepsToReproduce}`
             : "";
-        let behaviorSection = "";
-        if (expectedBehavior || actualBehavior) {
-            behaviorSection = [
-                expectedBehavior ? `**期望行为**: ${expectedBehavior}` : "",
-                actualBehavior ? `**实际行为**: ${actualBehavior}` : "",
-            ]
-                .filter(Boolean)
-                .join("\n\n");
-        }
+        const behaviorSection = [expectedBehavior ? `**期望行为**: ${expectedBehavior}` : "", actualBehavior ? `**实际行为**: ${actualBehavior}` : ""]
+            .filter(Boolean)
+            .join("\n\n");
+        const codeContextSection = codeContext
+            ? `**代码/图谱上下文**:\n\`\`\`\n${codeContext}\n\`\`\``
+            : "";
         const header = renderGuidanceHeader({
             tool: "fix_bug",
-            goal: "分析 Bug 并提供修复指南。AI 应根据指南执行实际修复。",
-            tasks: ["基于错误信息分析根因", "提供修复步骤", "建议验证方案"],
-            outputs: ["修复指南（文本）"],
+            goal: "基于 TBP 8 步法分析 Bug 真因，并提供修复指南。AI 应根据指南执行实际修复。",
+            tasks: ["先定义现象并复盘时间线", "闭合证据链后形成真因", "输出修复步骤与验证方案"],
+            outputs: ["TBP 真因分析指南", "结构化 RCA 数据"],
         });
         const guide = `${header}${PROMPT_TEMPLATE
             .replace(/{error_message}/g, errorMessage)
             .replace(/{stack_trace_section}/g, stackTraceSection)
             .replace(/{reproduce_section}/g, reproduceSection)
-            .replace(/{behavior_section}/g, behaviorSection)}`;
-        return okText(guide, {
-            schema: (await import('../schemas/output/core-tools.js')).BugAnalysisSchema,
-            note: "本工具返回 Bug 修复指南，AI 应根据指南执行问题定位、原因分析、代码修复和验证测试",
+            .replace(/{behavior_section}/g, behaviorSection)
+            .replace(/{code_context_section}/g, codeContextSection)}`;
+        const evidence = [
+            { type: "symptom", detail: errorMessage, source: "error_message" },
+            ...(stepsToReproduce ? [{ type: "timeline", detail: stepsToReproduce, source: "steps_to_reproduce" }] : []),
+            ...(stackTrace ? [{ type: "stack", detail: stackTrace, source: "stack_trace" }] : []),
+            ...(codeContext ? [{ type: "code", detail: codeContext, source: "code_context" }] : []),
+            ...(expectedBehavior ? [{ type: "comparison", detail: `期望行为: ${expectedBehavior}`, source: "expected_behavior" }] : []),
+            ...(actualBehavior ? [{ type: "comparison", detail: `实际行为: ${actualBehavior}`, source: "actual_behavior" }] : []),
+        ];
+        const affectedFiles = [...extractFilePaths(stackTrace), ...extractFilePaths(codeContext)]
+            .filter((value, index, array) => array.indexOf(value) === index);
+        const structuredData = {
+            summary: `TBP 8 步真因分析：${errorMessage.substring(0, 60)}${errorMessage.length > 60 ? "..." : ""}`,
+            bugType: inferBugType([errorMessage, actualBehavior, codeContext].filter(Boolean).join("\n")),
+            severity: inferSeverity([errorMessage, actualBehavior].filter(Boolean).join("\n")),
+            analysisMode,
+            rootCause: "待通过 TBP-6 真因分析确认；在证据链闭合前不直接给出确定性修复结论。",
+            affectedComponents: affectedFiles.length > 0 ? affectedFiles.map((item) => item.split("/").slice(0, -1).join("/") || item) : [],
+            affectedFiles,
+            fixPlan: {
+                steps: [
+                    "先完成 TBP-1：精确定义现象，避免泛化描述",
+                    "完成 TBP-2 时间线，明确开始、经过、终止状态",
+                    "完成 TBP-3 与 TBP-4，排除错误方向并对比成功/失败样本",
+                    "在 TBP-5/6 确认问题边界与因果句真因后，再修改代码",
+                ],
+                estimatedTime: "30-90 分钟（取决于证据完整度）",
+                risks: [
+                    "如果跳过 TBP 1-7，容易只修表象不修真因",
+                    "如果没有成功样本对比，TBP-4 共同模式结论可能偏弱",
+                ],
+            },
+            testPlan: {
+                unitTests: ["覆盖触发 Bug 的最小输入场景", "覆盖修复后的边界条件"],
+                integrationTests: ["覆盖完整调用链或关键交互路径"],
+                manualTests: ["按原复现步骤再次验证", "验证成功样本与失败样本分叉点已消失"],
+            },
+            preventionMeasures: [
+                "补充针对该边界条件的自动化测试",
+                "把关键状态与错误上下文写入日志，便于 TBP-2 时间线复盘",
+                "对完成态判定、文件写入、重试等边界增加显式校验",
+            ],
+            tbp: {
+                phenomenon: summarizePhenomenon(errorMessage, expectedBehavior, actualBehavior),
+                timeline: [
+                    { order: 1, event: "收到问题现象", evidence: errorMessage },
+                    ...(stepsToReproduce ? [{ order: 2, event: "获得复现步骤", evidence: stepsToReproduce }] : []),
+                    ...(stackTrace ? [{ order: 3, event: "获得堆栈或错误栈", evidence: stackTrace }] : []),
+                    ...(codeContext ? [{ order: 4, event: "获得代码/图谱上下文", evidence: codeContext }] : []),
+                ],
+                ruledOut: [
+                    "尚不能直接归因于“纯超时”或“SDK 有 bug”，需要先完成时间线与边界分析",
+                    "尚不能直接归因于“网络慢”，除非有传输层证据支持",
+                ],
+                commonPattern: "优先比较成功与失败样本，从调用链、状态机、工具执行、文件写入等维度找分叉点。",
+                boundary: "待定位；默认优先排查工具执行层、状态机、文件写入层和环境配置层。",
+                rootCauseStatement: "待形成 “A + B 在条件 D 下导致 C” 的因果句；在证据闭环前不下最终结论。",
+                evidence,
+                repair: [
+                    {
+                        layer: "analysis",
+                        action: "先补齐现象、时间线、对比样本和边界信息，再进入代码修复",
+                        risk: "证据不足时过早修复，可能导致重复返工",
+                        verification: "确认 TBP-7 证据链能解释全部关键现象",
+                    },
+                    {
+                        layer: "implementation",
+                        action: "只修改真因所在层，不以“兜底分支”替代根因修复",
+                        risk: "补症状会掩盖真正失控边界",
+                        verification: "验证原问题消失且未引入新的回归",
+                    },
+                ],
+            },
+        };
+        return okStructured(guide, structuredData, {
+            schema: (await import("../schemas/output/core-tools.js")).BugAnalysisSchema,
+            note: "本工具默认采用 TBP 8 步法输出真因分析与修复指南，AI 应先完成证据闭环，再执行代码修复和验证测试",
         });
     }
     catch (error) {
-        return handleToolError(error, 'fix_bug');
+        return handleToolError(error, "fix_bug");
     }
 }