mcp-probe-kit 3.0.8 → 3.0.10

package/build/tools/__tests__/code_insight.unit.test.js

@@ -1,5 +1,8 @@
 import { describe, expect, test } from "vitest";
-import { codeInsight } from "../code_insight.js";
+import { codeInsight, resolveCodeInsightQuery } from "../code_insight.js";
+import * as os from "node:os";
+import * as fs from "node:fs";
+import * as path from "node:path";
 describe("code_insight 单元测试", () => {
     test("mode 非法时返回错误", async () => {
         const result = await codeInsight({
@@ -32,4 +35,81 @@ describe("code_insight 单元测试", () => {
             }
         }
     });
+    test("当前目录为家目录时提示传入 project_root", async () => {
+        const prev = process.env.MCP_ENABLE_GITNEXUS_BRIDGE;
+        process.env.MCP_ENABLE_GITNEXUS_BRIDGE = "1";
+        try {
+            const result = await codeInsight({
+                mode: "query",
+                query: "authentication middleware",
+                project_root: os.homedir(),
+            });
+            expect(result.isError).toBe(false);
+            expect("structuredContent" in result).toBe(true);
+            const structured = result.structuredContent;
+            expect(structured.status).toBe("degraded");
+            if (structured.warnings.includes("bridge_disabled")) {
+                expect(structured.summary).toMatch(/bridge/i);
+            }
+            else {
+                expect(structured.warnings).toContain("project_root_required");
+                expect(structured.summary).toMatch(/project_root/i);
+            }
+        }
+        finally {
+            if (prev === undefined) {
+                delete process.env.MCP_ENABLE_GITNEXUS_BRIDGE;
+            }
+            else {
+                process.env.MCP_ENABLE_GITNEXUS_BRIDGE = prev;
+            }
+        }
+    });
+    test("auto 模式在缺少 query/target 时使用项目概览默认查询", () => {
+        const resolved = resolveCodeInsightQuery({
+            mode: "auto",
+            query: "",
+            target: "",
+            input: "",
+        });
+        expect(resolved.finalTarget).toBe("");
+        expect(resolved.finalQuery).toMatch(/核心流程/);
+        expect(resolved.finalQuery).toMatch(/依赖关系/);
+    });
+    test("返回 docs 保存指引而不直接代写文件", async () => {
+        const prev = process.env.MCP_ENABLE_GITNEXUS_BRIDGE;
+        process.env.MCP_ENABLE_GITNEXUS_BRIDGE = "0";
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "code-insight-docs-"));
+        try {
+            const result = await codeInsight({
+                mode: "auto",
+                project_root: projectRoot,
+            });
+            expect(result.isError).toBe(false);
+            const text = String(result.content?.[0]?.text || "");
+            const structured = result.structuredContent;
+            expect(text).toMatch(/delegated plan/);
+            expect(text).toMatch(/不要只口头总结而不写文件/);
+            expect(text).toMatch(/docs\/graph-insights\/latest\.md/);
+            expect(text).toMatch(/docs\/project-context\.md/);
+            expect(structured.projectDocs.latestMarkdownFilePath).toContain("/docs/graph-insights/latest.md");
+            expect(structured.projectDocs.archiveMarkdownFilePath).toContain("/docs/graph-insights/");
+            expect(structured.projectDocs.projectContextFilePath).toContain("/docs/project-context.md");
+            expect(structured.projectDocs.navigationSnippet).toMatch(/代码图谱洞察/);
+            expect(structured.plan.mode).toBe("delegated");
+            expect(structured.plan.steps[0].outputs[0]).toContain("/docs/project-context.md");
+            const updateIndexStep = structured.plan.steps.find((step) => step.id === "update-project-context-index");
+            expect(updateIndexStep.note).toMatch(/代码图谱洞察/);
+            expect(fs.existsSync(path.join(projectRoot, "docs", "graph-insights", "latest.md"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+            if (prev === undefined) {
+                delete process.env.MCP_ENABLE_GITNEXUS_BRIDGE;
+            }
+            else {
+                process.env.MCP_ENABLE_GITNEXUS_BRIDGE = prev;
+            }
+        }
+    });
 });

package/build/tools/__tests__/fix_bug.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/__tests__/fix_bug.unit.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "vitest";
+import { fixBug } from "../fix_bug.js";
+describe("fix_bug 单元测试", () => {
+    test("返回 TBP8 结构化输出", async () => {
+        const result = await fixBug({
+            error_message: "登录提交后页面白屏",
+            stack_trace: "TypeError: Cannot read property 'token' of undefined at src/auth/login.ts:45:12",
+            expected_behavior: "提示错误并保持页面可交互",
+            actual_behavior: "页面白屏，无法继续操作",
+        });
+        expect(result.isError).toBe(false);
+        expect("structuredContent" in result).toBe(true);
+        const structured = result.structuredContent;
+        expect(structured.analysisMode).toBe("tbp8");
+        expect(structured.tbp.phenomenon).toMatch(/页面白屏|登录提交/);
+        expect(Array.isArray(structured.tbp.timeline)).toBe(true);
+        expect(structured.tbp.timeline.length).toBeGreaterThan(0);
+        expect(Array.isArray(structured.tbp.repair)).toBe(true);
+        expect(structured.affectedFiles).toContain("src/auth/login.ts");
+    });
+    test("支持 code_context 并进入证据链", async () => {
+        const result = await fixBug({
+            error_message: "接口返回成功但前端没生效",
+            code_context: "图谱摘要: auth flow\n图谱线索: query: src/modules/record/index.js",
+        });
+        expect(result.isError).toBe(false);
+        const structured = result.structuredContent;
+        expect(structured.tbp.evidence.some((item) => item.source === "code_context")).toBe(true);
+        expect(structured.fixPlan.steps[0]).toMatch(/TBP-1/);
+    });
+});

package/build/tools/__tests__/gencommit.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/__tests__/gencommit.unit.test.js

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "vitest";
+import { gencommit } from "../gencommit.js";
+describe("gencommit 单元测试", () => {
+    test("提供变更内容时返回指导文档而不是最终 commit 草稿", async () => {
+        const result = await gencommit({
+            changes: "修复登录时 token 为空导致的报错\nsrc/auth/login.ts\nsrc/auth/session.ts",
+        });
+        expect(result.isError).toBe(false);
+        expect("structuredContent" in result).toBe(true);
+        const structured = result.structuredContent;
+        expect(structured.mode).toBe("guidance");
+        expect(structured.status).toBe("ready");
+        expect(structured.hasChanges).toBe(true);
+        expect(structured.steps[2]).toMatch(/不要再调用 gencommit/);
+        expect(structured.nextAction).toMatch(/最终 commit message/);
+        expect(result.content[0].text).toMatch(/本工具返回的是说明文档/);
+        expect(result._meta?.note).toMatch(/固定提交规范说明/);
+    });
+    test("缺少变更内容时返回非空补充指引", async () => {
+        const result = await gencommit({});
+        expect(result.isError).toBe(false);
+        expect("structuredContent" in result).toBe(true);
+        const structured = result.structuredContent;
+        expect(structured.mode).toBe("guidance");
+        expect(structured.status).toBe("needs_changes");
+        expect(structured.hasChanges).toBe(false);
+        expect(structured.nextAction).toMatch(/先补充变更内容/);
+        expect(result.content[0].text).toMatch(/git diff|git diff --staged/);
+    });
+    test("结构化输出包含规则、类型列表和模板", async () => {
+        const result = await gencommit({
+            changes: "更新 README 中关于 code_insight 的使用说明",
+        });
+        const structured = result.structuredContent;
+        expect(Array.isArray(structured.rules)).toBe(true);
+        expect(structured.rules).toContain("不要再次调用 gencommit");
+        expect(Array.isArray(structured.allowedTypes)).toBe(true);
+        expect(structured.allowedTypes.some((item) => item.type === "feat")).toBe(true);
+        expect(structured.outputTemplate).toMatch(/<type>: <emoji> <subject>/);
+    });
+});

package/build/tools/__tests__/init_project_context.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/__tests__/init_project_context.unit.test.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { initProjectContext } from '../init_project_context.js';
+describe('init_project_context 单元测试', () => {
+    test('返回 delegated plan，并预置 code_insight 图谱初始化步骤', async () => {
+        const result = await initProjectContext({
+            docs_dir: 'docs',
+            project_root: 'E:/workspace/github/mcp-probe-kit',
+        });
+        expect(result.isError).toBeFalsy();
+        expect('structuredContent' in result).toBe(true);
+        if (!('structuredContent' in result)) {
+            throw new Error('structuredContent 缺失');
+        }
+        const structured = result.structuredContent;
+        expect(structured.documentation.some((item) => item.path === 'docs/graph-insights/latest.md')).toBe(true);
+        expect(structured.documentation.some((item) => item.path === 'docs/graph-insights/latest.json')).toBe(true);
+        expect(structured.metadata?.graphDocs?.latestMarkdownFilePath).toContain('/docs/graph-insights/latest.md');
+        const plan = structured.metadata?.plan;
+        expect(plan?.mode).toBe('delegated');
+        expect(plan.steps.map((step) => step.id)).toEqual([
+            'write-project-context',
+            'bootstrap-code-insight',
+            'persist-graph-docs',
+        ]);
+        expect(plan.steps[1].action).toMatch(/code_insight/);
+    });
+    test('输出文本包含 graph-insights 入口和 delegated plan', async () => {
+        const result = await initProjectContext({
+            docs_dir: 'docs',
+            project_root: 'E:/workspace/github/mcp-probe-kit',
+        });
+        const text = result.content[0].text;
+        expect(text).toMatch(/graph-insights\/latest\.md/);
+        expect(text).toMatch(/delegated plan/);
+        expect(text).toMatch(/code_insight/);
+    });
+    test('已存在 project-context.md 时不再规划重写上下文文档', async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-context-'));
+        fs.mkdirSync(path.join(projectRoot, 'docs'), { recursive: true });
+        fs.writeFileSync(path.join(projectRoot, 'docs', 'project-context.md'), '# existing context\n', 'utf8');
+        const result = await initProjectContext({
+            docs_dir: 'docs',
+            project_root: projectRoot,
+        });
+        expect(result.isError).toBeFalsy();
+        expect('structuredContent' in result).toBe(true);
+        if (!('structuredContent' in result)) {
+            throw new Error('structuredContent 缺失');
+        }
+        const structured = result.structuredContent;
+        expect(structured.metadata?.projectContextExists).toBe(true);
+        expect(structured.metadata?.plan?.steps.map((step) => step.id)).toEqual([
+            'bootstrap-code-insight',
+            'persist-graph-docs',
+        ]);
+        const text = result.content[0].text;
+        expect(text).toMatch(/已存在（将保留，不覆盖）/);
+        expect(text).toMatch(/不要重写/);
+    });
+});

package/build/tools/__tests__/start_bugfix.unit.test.js

@@ -24,9 +24,19 @@ describe('start_bugfix 单元测试', () => {
         expect(plan).toBeTruthy();
         expect(plan.mode).toBe('delegated');
         expect(Array.isArray(plan.steps)).toBe(true);
+        expect(structured.analysisMode).toBe('tbp8');
+        expect(structured.tbp.rootCauseStatement).toMatch(/A \+ B|因果句|待形成/);
         const fixStep = plan.steps.find((step) => step.tool === 'fix_bug');
         expect(fixStep).toBeTruthy();
         expect(fixStep.args.error_message).toBe('TypeError: Cannot read property');
+        expect(fixStep.args.analysis_mode).toBe('tbp8');
+        const contextStep = plan.steps.find((step) => step.tool === 'init_project_context');
+        expect(contextStep.outputs).toContain('docs/graph-insights/latest.md');
+        expect(contextStep.outputs).toContain('docs/graph-insights/latest.json');
+        expect(contextStep.when).toMatch(/graph-insights\/latest\.md/);
+        expect(contextStep.note).toMatch(/兼容老项目|补齐/);
+        expect(structured?.metadata?.graphDocs?.latestMarkdownPath).toBe('docs/graph-insights/latest.md');
+        expect(structured?.metadata?.graphContext?.summary).toMatch(/GitNexus|图谱|降级/);
     });
     test('loop 模式返回需求循环结构', async () => {
         const result = await startBugfix({

package/build/tools/__tests__/start_feature.unit.test.js

@@ -30,9 +30,16 @@ describe('start_feature 单元测试', () => {
         expect(tools).toContain('init_project_context');
         expect(tools).toContain('add_feature');
         expect(tools).toContain('estimate');
+        const contextStep = plan.steps.find((step) => step.tool === 'init_project_context');
+        expect(contextStep.outputs).toContain('docs/graph-insights/latest.md');
+        expect(contextStep.outputs).toContain('docs/graph-insights/latest.json');
+        expect(contextStep.when).toMatch(/graph-insights\/latest\.md/);
+        expect(contextStep.note).toMatch(/兼容老项目|补齐/);
         const specStep = plan.steps.find((step) => step.tool === 'add_feature');
         expect(specStep.args.feature_name).toBe('user-auth');
         expect(specStep.outputs).toContain('docs/specs/user-auth/requirements.md');
+        expect(structured?.metadata?.graphDocs?.latestMarkdownPath).toBe('docs/graph-insights/latest.md');
+        expect(structured?.metadata?.graphContext?.summary).toMatch(/GitNexus|图谱|降级/);
     });
     test('输出文本包含执行计划与关键工具名', async () => {
         const result = await startFeature({
@@ -43,6 +50,9 @@ describe('start_feature 单元测试', () => {
         expect(text).toMatch(/执行计划/);
         expect(text).toMatch(/add_feature/);
         expect(text).toMatch(/estimate/);
+        expect(text).toMatch(/graph-insights\/latest\.md/);
+        expect(text).toMatch(/任务级收敛/);
+        expect(text).toMatch(/project-context\.md/);
     });
     test('template_profile 应该透传到 add_feature 计划', async () => {
         const result = await startFeature({

package/build/tools/code_insight.d.ts

@@ -1,4 +1,14 @@
+import { type CodeInsightMode } from "../lib/gitnexus-bridge.js";
 import { type ToolExecutionContext } from "../lib/tool-execution-context.js";
+export declare function resolveCodeInsightQuery(input: {
+    mode: CodeInsightMode;
+    query: string;
+    target: string;
+    input: string;
+}): {
+    finalQuery: string;
+    finalTarget: string;
+};
 export declare function codeInsight(args: any, context?: ToolExecutionContext): Promise<import("../lib/response.js").ToolResponse | {
     content: {
         type: string;

package/build/tools/code_insight.js

@@ -1,9 +1,51 @@
+import * as path from "node:path";
 import { parseArgs, getString, getNumber, getBoolean } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
+import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
 import { runCodeInsightBridge, } from "../lib/gitnexus-bridge.js";
 import { throwIfAborted, } from "../lib/tool-execution-context.js";
 const ALLOWED_MODES = new Set(["auto", "query", "context", "impact"]);
 const ALLOWED_DIRECTIONS = new Set(["upstream", "downstream"]);
+const DEFAULT_AUTO_QUERY = "项目整体架构 核心流程 关键模块 依赖关系 入口点";
+function toPosixPath(value) {
+    return value.replace(/\\/g, "/");
+}
+function makeSafeSegment(value) {
+    return (value || "code-insight")
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48) || "code-insight";
+}
+function buildProjectDocsOutputs(input) {
+    const projectRoot = input.projectRoot?.trim();
+    if (!projectRoot) {
+        return null;
+    }
+    const docsRoot = path.join(path.resolve(projectRoot), input.docsDirName || "docs", "graph-insights");
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const suffix = makeSafeSegment(input.structured.summary || input.mode);
+    const baseName = `${timestamp}-${input.mode}-${suffix}`;
+    return {
+        markdownFilePath: toPosixPath(path.join(docsRoot, `${baseName}.md`)),
+        jsonFilePath: toPosixPath(path.join(docsRoot, `${baseName}.json`)),
+    };
+}
+function renderPlanSteps(steps) {
+    return steps
+        .map((step, index) => {
+        const lines = [`${index + 1}. ${step.action}`];
+        if (step.outputs && step.outputs.length > 0) {
+            lines.push(`   输出: ${step.outputs.join(", ")}`);
+        }
+        if (step.note) {
+            lines.push(`   说明: ${step.note}`);
+        }
+        return lines.join("\n");
+    })
+        .join("\n");
+}
 function normalizeMode(value) {
     const mode = (value || "auto").trim().toLowerCase();
     if (!ALLOWED_MODES.has(mode)) {
@@ -34,6 +76,13 @@ function summarizeExecutions(executions) {
     })
         .join("\n");
 }
+export function resolveCodeInsightQuery(input) {
+    const finalTarget = input.target || ((input.mode === "context" || input.mode === "impact") ? input.input : "");
+    const finalQuery = input.query
+        || (input.mode === "query" ? input.input : "")
+        || (input.mode === "auto" && !finalTarget ? DEFAULT_AUTO_QUERY : "");
+    return { finalQuery, finalTarget };
+}
 export async function codeInsight(args, context) {
     try {
         throwIfAborted(context?.signal, "code_insight 已取消");
@@ -55,6 +104,8 @@ export async function codeInsight(args, context) {
                 query: ["q", "keyword", "关键词"],
                 target: ["symbol", "name", "目标符号"],
                 repo: ["repository", "仓库"],
+                project_root: ["projectRoot", "project_path", "path", "dir", "directory", "项目路径", "项目根目录"],
+                docs_dir: ["docsDir", "docs", "文档目录"],
                 goal: ["目的", "目标"],
                 task_context: ["context", "taskContext", "任务上下文"],
                 direction: ["dir", "方向"],
@@ -66,20 +117,27 @@ export async function codeInsight(args, context) {
         const query = getString(parsedArgs.query);
         const target = getString(parsedArgs.target);
         const repo = getString(parsedArgs.repo);
+        const projectRoot = getString(parsedArgs.project_root);
+        const docsDirName = getString(parsedArgs.docs_dir) || "docs";
         const goal = getString(parsedArgs.goal);
         const taskContext = getString(parsedArgs.task_context);
         const direction = normalizeDirection(getString(parsedArgs.direction));
         const maxDepth = Math.max(1, getNumber(parsedArgs.max_depth, 3));
         const includeTests = getBoolean(parsedArgs.include_tests, false);
         const input = getString(parsedArgs.input);
-        const finalQuery = query || (mode === "query" ? input : "");
-        const finalTarget = target || ((mode === "context" || mode === "impact") ? input : "");
+        const { finalQuery, finalTarget } = resolveCodeInsightQuery({
+            mode,
+            query,
+            target,
+            input,
+        });
         throwIfAborted(context?.signal, "code_insight 已取消");
         const result = await runCodeInsightBridge({
             mode,
             query: finalQuery,
             target: finalTarget,
             repo: repo || undefined,
+            projectRoot: projectRoot || undefined,
             goal: goal || undefined,
             taskContext: taskContext || undefined,
             direction,
@@ -98,6 +156,8 @@ export async function codeInsight(args, context) {
 状态: ${result.available ? "可用" : "降级"}
 模式: ${result.modeRequested} -> ${result.modeResolved}
 来源: ${result.provider}
+工作区: ${result.workspaceMode}
+源目录: ${result.sourceRoot}
 
 摘要:
 ${result.summary}
@@ -106,7 +166,7 @@ ${result.summary}
 ${executionSummary}
 
 ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.trim();
-        return okStructured(message, {
+        const structured = {
             status: result.available ? "ok" : "degraded",
             provider: result.provider,
             mode: {
@@ -117,7 +177,100 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
             warnings: result.warnings,
             executions: result.executions,
             repo: result.repo || null,
+            workspaceMode: result.workspaceMode,
+            sourceRoot: result.sourceRoot,
+            analysisRoot: result.analysisRoot,
+            pathMapped: result.pathMapped,
+        };
+        const docsSnapshot = buildProjectDocsOutputs({
+            projectRoot: projectRoot || result.sourceRoot,
+            docsDirName,
+            mode,
+            structured,
         });
+        let projectDocs;
+        let persistencePlan;
+        if (docsSnapshot) {
+            const docsDir = path.dirname(docsSnapshot.markdownFilePath);
+            projectDocs = {
+                docsDir,
+                projectContextFilePath: toPosixPath(path.join(path.resolve(projectRoot || result.sourceRoot), docsDirName, "project-context.md")),
+                latestMarkdownFilePath: toPosixPath(path.join(docsDir, "latest.md")),
+                latestJsonFilePath: toPosixPath(path.join(docsDir, "latest.json")),
+                archiveMarkdownFilePath: docsSnapshot.markdownFilePath,
+                archiveJsonFilePath: docsSnapshot.jsonFilePath,
+                navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
+最近一次 code_insight 分析结果，包含调用链、上下文与影响面摘要
+`,
+                devGuideSnippet: `- **代码图谱洞察**: [graph-insights/latest.md](./graph-insights/latest.md) - 需要理解模块依赖、调用链和影响面时优先查看
+`,
+            };
+            structured.projectDocs = projectDocs;
+            structured.nextAction = `请按 delegated plan 落盘图谱文档，并更新 ${projectDocs.projectContextFilePath} 的索引入口`;
+            persistencePlan = {
+                mode: "delegated",
+                steps: [
+                    {
+                        id: "ensure-project-context",
+                        action: `检查 ${projectDocs.projectContextFilePath} 是否存在；若不存在，先调用 init_project_context 生成项目上下文索引`,
+                        outputs: [projectDocs.projectContextFilePath],
+                        note: "只有 project-context.md 存在，后续图谱文档入口才可持续复用",
+                    },
+                    {
+                        id: "save-latest-md",
+                        action: `将本次 code_insight 的文本分析结果写入 ${projectDocs.latestMarkdownFilePath}`,
+                        outputs: [projectDocs.latestMarkdownFilePath],
+                    },
+                    {
+                        id: "save-archive-md",
+                        action: `将本次 code_insight 的文本分析结果归档到 ${projectDocs.archiveMarkdownFilePath}`,
+                        outputs: [projectDocs.archiveMarkdownFilePath],
+                    },
+                    {
+                        id: "save-latest-json",
+                        action: `将本次 code_insight 的 structuredContent 写入 ${projectDocs.latestJsonFilePath}`,
+                        outputs: [projectDocs.latestJsonFilePath],
+                        note: "建议保留完整结构化结果，便于后续 AI 继续读取",
+                    },
+                    {
+                        id: "save-archive-json",
+                        action: `将本次 code_insight 的 structuredContent 归档到 ${projectDocs.archiveJsonFilePath}`,
+                        outputs: [projectDocs.archiveJsonFilePath],
+                    },
+                    {
+                        id: "update-project-context-index",
+                        action: `更新 ${projectDocs.projectContextFilePath}，在“## 📚 文档导航”加入图谱文档入口，并在“## 💡 开发时查看对应文档”加入代码图谱洞察链接`,
+                        outputs: [projectDocs.projectContextFilePath],
+                        note: `建议插入内容:\n${projectDocs.navigationSnippet}\n${projectDocs.devGuideSnippet}`,
+                    },
+                ],
+            };
+            structured.plan = persistencePlan;
+        }
+        return okStructured(projectDocs && persistencePlan
+            ? `${renderOrchestrationHeader({
+                tool: "code_insight",
+                goal: "完成图谱分析后，将结果按 delegated plan 落盘到 docs/graph-insights",
+                tasks: [
+                    "先消费本次 code_insight 返回的分析结果",
+                    "严格按 delegated plan 将 Markdown / JSON 保存到指定路径",
+                    "不要只口头总结而不写文件",
+                ],
+                notes: [
+                    `工作区模式: ${result.workspaceMode}`,
+                    `来源目录: ${result.sourceRoot}`,
+                ],
+            })}${message}
+
+## delegated plan
+${renderPlanSteps(persistencePlan.steps)}
+
+后续操作:
+- 请先确保 ${projectDocs.projectContextFilePath} 可用，并把图谱入口挂到该索引中
+- 请将本次分析保存到 ${projectDocs.latestMarkdownFilePath}
+- 如需归档，请额外保存到 ${projectDocs.archiveMarkdownFilePath}
+- 如需结构化副本，请保存 JSON 到 ${projectDocs.latestJsonFilePath} 或 ${projectDocs.archiveJsonFilePath}`
+            : message, structured);
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

package/build/tools/fix_bug.d.ts

@@ -1,10 +1,10 @@
 /**
  * fix_bug 工具
  *
- * 功能：指导完整的 Bug 修复流程
- * 模式：指令生成器模式 - 返回详细的修复指南，由 AI 执行实际操作
+ * 功能：基于 TBP 8 步法输出真因分析与修复指南
+ * 模式：指令生成器模式 - 返回详细的 RCA 与修复指南，由 AI 执行实际操作
  *
- * 流程：问题定位 → 原因分析 → 修复方案 → 验证测试
+ * 流程：定义现象 → 复盘时间线 → 排除错误方向 → 找共同模式 → 定位边界 → 陈述真因 → 闭合证据链 → 设计修复方案
  */
 /**
  * fix_bug 工具实现