mcp-probe-kit 3.6.3 → 3.6.8

package/build/tools/__tests__/init_project.write.unit.test.d.ts

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

package/build/tools/__tests__/init_project.write.unit.test.js

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { initProject } from "../init_project.js";
+describe("init_project 落盘边界", () => {
+    test("仅写入 Skill 与 AGENTS.md，docs 由 Agent 创建", async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-probe-init-project-"));
+        const result = await initProject({
+            project_name: "Demo App",
+            project_root: projectRoot,
+            input: "一个简单的演示应用",
+        });
+        expect(result.isError).toBeFalsy();
+        const structured = result.structuredContent;
+        expect(structured.writtenFiles.length).toBe(2);
+        expect(structured.pendingFiles.length).toBeGreaterThan(0);
+        expect(fs.existsSync(path.join(projectRoot, "AGENTS.md"))).toBe(true);
+        expect(fs.existsSync(path.join(projectRoot, "docs", "project-context.md"))).toBe(false);
+        expect(fs.existsSync(path.join(projectRoot, "docs", "specs", "demo-app", "requirements.md"))).toBe(false);
+    });
+});

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

@@ -1,74 +1,78 @@
-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，含 finalize-agents-md 与 AGENTS.md 模板', async () => {
-        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-init-'));
+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("MCP 仅写入 AGENTS.md 与 layout.json", async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-probe-kit-init-"));
         const result = await initProjectContext({
-            docs_dir: 'docs',
+            docs_dir: "docs",
             project_root: projectRoot,
         });
         expect(result.isError).toBeFalsy();
-        expect('structuredContent' in result).toBe(true);
-        if (!('structuredContent' in result)) {
-            throw new Error('structuredContent 缺失');
+        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 === 'AGENTS.md')).toBe(true);
-        expect(structured.documentation.some((item) => item.path === 'docs/graph-insights/latest.md')).toBe(true);
-        expect(structured.metadata?.layout?.indexPath).toBe('AGENTS.md');
-        expect(structured.metadata?.agentsMdTemplate).toMatch(/mcp-probe:context begin/);
-        expect(structured.metadata?.manifestWritten).toBe('docs/.mcp-probe/layout.json');
-        expect(fs.existsSync(path.join(projectRoot, 'docs', '.mcp-probe', 'layout.json'))).toBe(true);
+        expect(structured.writtenFiles.some((f) => f.path === "AGENTS.md")).toBe(true);
+        expect(structured.writtenFiles.some((f) => f.path === "docs/.mcp-probe/layout.json")).toBe(true);
+        expect(structured.pendingFiles.some((f) => f.path === "docs/project-context.md")).toBe(true);
+        expect(fs.existsSync(path.join(projectRoot, "docs", ".mcp-probe", "layout.json"))).toBe(true);
+        expect(fs.existsSync(path.join(projectRoot, "AGENTS.md"))).toBe(true);
+        expect(fs.existsSync(path.join(projectRoot, "docs", "project-context.md"))).toBe(false);
+        expect(fs.existsSync(path.join(projectRoot, "docs", "project-context", "tech-stack.md"))).toBe(false);
         const plan = structured.metadata?.plan;
-        expect(plan?.mode).toBe('delegated');
+        expect(plan?.mode).toBe("delegated");
         expect(plan.steps.map((step) => step.id)).toEqual([
-            'write-modular-docs',
-            'bootstrap-code-insight',
-            'persist-graph-docs',
-            'finalize-agents-md',
+            "write-modular-docs",
+            "bootstrap-code-insight",
+            "persist-graph-docs",
         ]);
-        expect(plan.steps[0].outputs).toContain('docs/project-context.md');
-        expect(plan.steps[3].id).toBe('finalize-agents-md');
+        const text = result.content[0].text;
+        expect(text).toMatch(/文件落盘状态/);
+        expect(text).toMatch(/尚未创建/);
     });
-    test('输出文本包含 AGENTS.md 与 MCP 触发规则', async () => {
-        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-init-'));
+    test("输出文本包含 AGENTS.md 与 MCP 触发规则", async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-probe-kit-init-"));
         const result = await initProjectContext({
             project_root: projectRoot,
         });
         const text = result.content[0].text;
         expect(text).toMatch(/AGENTS\.md/);
-        expect(text).toMatch(/start_feature/);
-        expect(text).toMatch(/finalize-agents-md/);
+        expect(text).toMatch(/文件落盘状态/);
     });
-    test('已存在 project-context 分类文档时跳过重写 modular', async () => {
-        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-context-'));
-        fs.mkdirSync(path.join(projectRoot, 'docs', 'project-context'), { recursive: true });
-        fs.writeFileSync(path.join(projectRoot, 'docs', 'project-context.md'), '# existing context\n', 'utf8');
+    test("已存在 project-context 分类文档时跳过重写 modular", async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-probe-kit-context-"));
+        fs.mkdirSync(path.join(projectRoot, "docs", "project-context"), { recursive: true });
+        fs.writeFileSync(path.join(projectRoot, "docs", "project-context.md"), "# existing context\n", "utf8");
         const result = await initProjectContext({
-            docs_dir: 'docs',
+            docs_dir: "docs",
             project_root: projectRoot,
         });
         expect(result.isError).toBeFalsy();
         const structured = result.structuredContent;
         expect(structured.metadata?.legacyProjectContextExists).toBe(true);
         expect(structured.metadata?.plan?.steps.map((step) => step.id)).toEqual([
-            'bootstrap-code-insight',
-            'persist-graph-docs',
-            'finalize-agents-md',
+            "bootstrap-code-insight",
+            "persist-graph-docs",
         ]);
+        expect(structured.pendingFiles.every((f) => !f.path.startsWith("docs/project-context"))).toBe(true);
+        expect(fs.readFileSync(path.join(projectRoot, "docs", "project-context.md"), "utf8")).toBe("# existing context\n");
+        expect(fs.existsSync(path.join(projectRoot, "AGENTS.md"))).toBe(true);
         const text = result.content[0].text;
         expect(text).toMatch(/保留/);
     });
-    test('已有 AGENTS.md 用户内容时 prepend merge', async () => {
-        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-probe-kit-agents-'));
-        fs.writeFileSync(path.join(projectRoot, 'AGENTS.md'), '# Custom rules\n', 'utf8');
-        const result = await initProjectContext({ project_root: projectRoot });
-        const structured = result.structuredContent;
-        expect(structured.metadata?.agentsMdMergeMode).toBe('prepended');
-        expect(structured.metadata?.agentsMdTemplate).toMatch(/<!-- mcp-probe:context begin/);
-        expect(structured.metadata?.agentsMdTemplate).toContain('# Custom rules');
+    test("已有 AGENTS.md 时 merge 而非覆盖", async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-probe-kit-agents-"));
+        fs.writeFileSync(path.join(projectRoot, "AGENTS.md"), "# Custom rules\n", "utf8");
+        const result = await initProjectContext({
+            project_root: projectRoot,
+        });
+        const agents = fs.readFileSync(path.join(projectRoot, "AGENTS.md"), "utf8");
+        expect(agents).toContain("# Custom rules");
+        expect(agents).toMatch(/mcp-probe:context/);
+        expect(result.structuredContent.metadata?.agentsMdMergeMode).not.toBe("replaced");
     });
 });

package/build/tools/add_feature.js

@@ -1,12 +1,12 @@
 import { parseArgs, getString } from "../utils/parseArgs.js";
-import { okText } from "../lib/response.js";
+import { okStructured } from "../lib/response.js";
 import { loadTemplate, normalizeTemplateProfile } from "../lib/template-loader.js";
 import { handleToolError } from "../utils/error-handler.js";
 /**
  * add_feature 工具
  *
  * 功能：为已有项目添加新功能的规格文档
- * 模式：指令生成器模式 - 返回详细的生成指南，由 AI 执行实际操作
+ * 模式：指令生成器 — MCP 返回模板与要求，由调用方 Agent 按模板落盘
  *
  * 输出文件：
  * - docs/specs/{feature_name}/requirements.md - 需求文档
@@ -236,9 +236,9 @@ ${combinedValidation.warnings.length > 0 ? `- 其他警告: ${combinedValidation
 
 ---
 
-## 📝 创建文档
+## 📝 创建文档（由 Agent 落盘）
 
-请在 \`${docsDir}/specs/${featureName}/\` 目录下创建以下三个文件：
+MCP **不会**写入磁盘。请根据下方模板，在 \`${docsDir}/specs/${featureName}/\` 创建三个文件并替换占位符。
 
 ### 文件 1: requirements.md
 
@@ -286,9 +286,26 @@ ${fenceClose}
 *指南版本: 1.1.0*
 *工具: MCP Probe Kit - add_feature*
 `;
-        return okText(guide, {
+        const specPaths = [
+            `${docsDir}/specs/${featureName}/requirements.md`,
+            `${docsDir}/specs/${featureName}/design.md`,
+            `${docsDir}/specs/${featureName}/tasks.md`,
+        ];
+        const pendingFiles = specPaths.map((specPath) => ({
+            path: specPath,
+            reason: "由 Agent 根据本工具返回的模板写入",
+        }));
+        const structuredData = {
+            summary: `功能规格：${featureName}`,
+            featureName,
+            requirements: ["见 requirements.md 模板"],
+            tasks: [{ id: "1", title: "按模板创建 specs 文档", description: "将下方模板落盘并补充真实内容" }],
+            pendingFiles,
+            specPaths,
+        };
+        return okStructured(guide, structuredData, {
             schema: (await import("../schemas/output/project-tools.js")).FeatureSpecSchema,
-            note: "本工具返回功能规格生成指南，AI 应根据指南创建需求、设计和任务文档",
+            note: "本工具返回模板与要求，不代写文件；Agent 须按指南创建 specs",
             template: {
                 profile: templateProfile,
                 requested: profileDecision.requested,

package/build/tools/code_insight.js

@@ -197,7 +197,7 @@ function renderUsageGuide() {
 ## 下一步建议
 - 查询不精确: 增加 \`goal\`（例如“理解登录认证流程”）
 - 出现歧义: 传入 \`uid\` 或 \`file_path\` 重新执行
-- 需要落盘: 传 \`save_to_docs: true\`，再按 delegated plan 写入 docs/graph-insights`;
+- 需要落盘: 传 \`save_to_docs: true\`，再按 delegated plan 由 Agent 写入 docs/graph-insights`;
 }
 export function resolveCodeInsightQuery(input) {
     const finalTarget = input.target || ((input.mode === "context" || input.mode === "impact") ? input.input : "");
@@ -369,7 +369,7 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
         structured.nextAction = delegatedPlan?.kind === "ambiguity"
             ? "请先选择 uid 或 file_path 重新调用 code_insight 完成消歧"
             : projectDocs
-                ? `请按 delegated plan 落盘图谱文档，并更新 ${projectDocs.projectContextFilePath} 的索引入口`
+                ? `请按 delegated plan 由 Agent 落盘图谱文档，并更新 ${projectDocs.projectContextFilePath} 的索引入口`
                 : null;
         const structuredWithHandles = attachHandles(structured, {
             graph_resource: DEFAULT_GRAPH_RESOURCE_URI,
@@ -379,7 +379,7 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
                 tool: "code_insight",
                 goal: delegatedPlan.kind === "ambiguity"
                     ? "先完成符号消歧，再继续图谱分析"
-                    : "完成图谱分析后，将结果按 delegated plan 落盘到 docs/graph-insights",
+                    : "完成图谱分析后，由 Agent 按 delegated plan 落盘到 docs/graph-insights",
                 tasks: delegatedPlan.kind === "ambiguity"
                     ? [
                         "先阅读本次 code_insight 返回的 candidates",

package/build/tools/init_project.js

@@ -37,6 +37,21 @@ export async function initProject(args) {
             : "";
         const featureSlug = projectName.toLowerCase().replace(/\s+/g, '-');
         const agentsRel = toPosixPath(bootstrap.agentsMd.path);
+        const bootstrapWritten = [
+            { path: MCP_PROBE_SKILL_REL_PATH, action: bootstrap.skill.created ? "created" : bootstrap.skill.updated ? "updated" : "skipped" },
+            { path: agentsRel, action: bootstrap.agentsMd.created ? "created" : bootstrap.agentsMd.updated ? "updated" : "skipped" },
+        ];
+        const pendingFiles = [
+            { path: "docs/project-context.md", reason: "由 Agent 按指南创建" },
+            { path: "docs/constitution.md", reason: "由 Agent 按指南创建" },
+            { path: `docs/specs/${featureSlug}/requirements.md`, reason: "由 Agent 按指南创建" },
+            { path: `docs/specs/${featureSlug}/design.md`, reason: "由 Agent 按指南创建" },
+            { path: `docs/specs/${featureSlug}/tasks.md`, reason: "由 Agent 按指南创建" },
+            { path: `docs/specs/${featureSlug}/research.md`, reason: "由 Agent 按指南创建" },
+            { path: "scripts/check-prerequisites.sh", reason: "由 Agent 按指南创建" },
+            { path: "scripts/setup.sh", reason: "由 Agent 按指南创建" },
+            { path: "src/", reason: "由 Agent 按项目类型创建源代码目录" },
+        ];
         const message = `你需要按照 Spec-Driven Development（规范驱动开发）的方式初始化项目，参考 https://github.com/github/spec-kit 的工作流程。
 
 📋 **项目需求**：
@@ -208,7 +223,7 @@ ${warningBlock}
 7. 识别可以并行执行的任务以优化开发效率
 
 🚀 **开始执行**：
-现在请按照上述步骤创建项目结构和所有必需的文档。`;
+MCP 已写入 Skill 与 AGENTS.md。请按上述步骤由 Agent 创建 docs、scripts、src 及 specs 文档。`;
         // 创建结构化数据对象
         const structuredData = {
             summary: `初始化项目：${projectName}`,
@@ -234,29 +249,17 @@ ${warningBlock}
                     'scripts/',
                     'src/'
                 ],
-                files: [
-                    MCP_PROBE_SKILL_REL_PATH,
-                    agentsRel,
-                    'docs/project-context.md',
-                    'docs/constitution.md',
-                    `docs/specs/${featureSlug}/requirements.md`,
-                    `docs/specs/${featureSlug}/design.md`,
-                    `docs/specs/${featureSlug}/tasks.md`,
-                    `docs/specs/${featureSlug}/research.md`,
-                    'scripts/check-prerequisites.sh',
-                    'scripts/setup.sh'
-                ]
+                writtenFiles: bootstrapWritten.map((file) => file.path),
+                plannedFiles: pendingFiles.map((file) => file.path),
             },
+            writtenFiles: bootstrapWritten,
+            pendingFiles,
             nextSteps: [
-                '确认 .agents/skills/mcp-probe-kit/SKILL.md 与 AGENTS.md 已落盘',
-                '创建项目目录结构',
-                '生成 project-context.md',
-                '生成 constitution.md',
-                '生成需求文档 requirements.md',
-                '生成设计文档 design.md',
-                '生成任务清单 tasks.md',
-                '生成技术调研 research.md',
-                '创建辅助脚本'
+                '确认 Skill 与 AGENTS.md 已落盘',
+                '按指南创建 docs/ 文档与 specs',
+                '创建 scripts/ 辅助脚本',
+                '创建 src/ 源代码目录',
+                '运行 init_project_context 生成完整上下文与图谱',
             ]
         };
         return okStructured(message, structuredData, {

package/build/tools/init_project_context.js

@@ -6,8 +6,12 @@ import { resolveWorkspaceRoot, isLikelyProjectNamedRelativePath, buildProjectRoo
 import { detectDocumentLocale, layoutAbsPath, legacyProjectContextExists, parseLayoutArgsFromRecord, resolveProjectContextLayout, toPosixPath, writeLayoutManifest, } from "../lib/project-context-layout.js";
 import { mergeAgentsMdBlock } from "../lib/merge-agents-md.js";
 import { generateAgentsMdInner } from "../lib/agents-md-template.js";
-import * as fs from 'fs';
-import * as path from 'path';
+import { ensureHarnessAdapters } from "../lib/harness-adapters.js";
+import { generateWorkflowSkillContent, MCP_PROBE_SKILL_REL_PATH } from "../lib/workflow-skill-template.js";
+import { getMcpProbeSkillVersion } from "../lib/workflow-skill-version.js";
+import { formatFileDeliverySection, writeProjectFile, } from "../lib/file-delivery.js";
+import * as fs from "fs";
+import * as path from "path";
 /**
  * init_project_context 工具
  *
@@ -176,16 +180,55 @@ async function generateProjectContext(layout, projectRoot) {
             category: detection.category,
             docs,
             projectRootPosix: layout.projectRootPosix,
-            graphReady: false,
+            graphReady: fs.existsSync(layoutAbsPath(layout, layout.latestMarkdownPath)),
+            contextReady: modularExists,
         });
         const mergedAgents = mergeAgentsMdBlock(existingAgentsRaw, agentsInner);
-        const manifestWritten = writeLayoutManifest(projectRootAbs, layout);
+        const skillPath = layoutAbsPath(layout, MCP_PROBE_SKILL_REL_PATH);
+        const skillContent = fs.existsSync(skillPath)
+            ? fs.readFileSync(skillPath, "utf8")
+            : generateWorkflowSkillContent(getMcpProbeSkillVersion());
+        const harnessResult = ensureHarnessAdapters(projectRootAbs, skillContent, layout.indexPath);
+        const manifestWritten = writeLayoutManifest(projectRootAbs, layout, harnessResult.layoutHarness);
+        const agentsMdWritten = writeProjectFile(projectRootAbs, layout.indexPath, mergedAgents.content, "always");
+        const writtenFiles = [
+            agentsMdWritten,
+            { path: manifestWritten, action: "updated" },
+            ...harnessResult.adapters
+                .filter((a) => a.created || a.updated)
+                .map((a) => ({
+                path: a.path,
+                action: (a.created ? "created" : "updated"),
+            })),
+        ];
+        const pendingFiles = [
+            ...(modularExists
+                ? []
+                : [
+                    {
+                        path: layout.legacyIndexPath,
+                        reason: "由 Agent 按本工具返回的模板写入",
+                    },
+                    ...docs.map((doc) => ({
+                        path: `${layout.modularDir}/${doc.file}`,
+                        reason: "由 Agent 按模板写入",
+                    })),
+                ]),
+            {
+                path: graphDocs.latestMarkdownFilePath,
+                reason: "由 Agent 按 code_insight 分析结果写入",
+            },
+            {
+                path: graphDocs.latestJsonFilePath,
+                reason: "由 Agent 按 code_insight 结构化结果写入",
+            },
+        ];
+        const deliverySection = formatFileDeliverySection({ writtenFiles, pendingFiles });
         const codeInsightArgs = JSON.stringify({
             mode: "auto",
             project_root: layout.projectRootPosix,
             docs_dir: docsDir,
         });
-        const modularOutputs = docs.map((doc) => `${layout.modularDir}/${doc.file}`);
         const plan = {
             mode: "delegated",
             steps: modularExists
@@ -194,60 +237,49 @@ async function generateProjectContext(layout, projectRoot) {
                         id: "bootstrap-code-insight",
                         action: `检测到现有 ${layout.legacyIndexPath}，跳过重写分类文档，调用 code_insight 补齐图谱`,
                         outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
-                        note: `调用参数: ${codeInsightArgs}`,
+                        note: `调用参数: ${codeInsightArgs}；${layout.indexPath} 与 layout 已由 MCP 写入`,
                     },
                     {
                         id: "persist-graph-docs",
-                        action: `执行 code_insight 的 delegated plan，写入 ${layout.graphDir}/`,
+                        action: `执行 code_insight 的 delegated plan，由 Agent 写入 ${layout.graphDir}/`,
                         outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
                         note: "保留现有 project-context 分类文档",
                     },
-                    {
-                        id: "finalize-agents-md",
-                        action: `将下方 agentsMdTemplate 写入 ${layout.indexPath}（mcp-probe 块置顶，保留用户原有内容）`,
-                        outputs: [layout.indexPath],
-                        note: `mergeMode: ${mergedAgents.mergeMode}；layout manifest 已由服务端写入 ${manifestWritten}`,
-                    },
                 ]
                 : [
                     {
                         id: "write-modular-docs",
-                        action: `先创建 ${layout.legacyIndexPath}（文档索引），再创建 ${layout.modularDir}/ 分类文档`,
-                        outputs: [layout.legacyIndexPath, ...modularOutputs],
-                        note: modularExists
-                            ? "跳过：索引与分类文档已存在"
-                            : "project-context.md 是细节入口；AGENTS.md 仅含 MCP 规则",
+                        action: `由 Agent 创建 ${layout.legacyIndexPath} 与 ${layout.modularDir}/ 分类文档（见下方模板）`,
+                        outputs: [
+                            layout.legacyIndexPath,
+                            ...docs.map((doc) => `${layout.modularDir}/${doc.file}`),
+                        ],
                     },
                     {
                         id: "bootstrap-code-insight",
                         action: "调用 code_insight 做整体图谱分析",
                         outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
-                        note: `调用参数: ${codeInsightArgs}`,
+                        note: `调用参数: ${codeInsightArgs}；${layout.indexPath} 已由 MCP 写入`,
                     },
                     {
                         id: "persist-graph-docs",
-                        action: `执行 code_insight 的 delegated plan，写入 ${layout.graphDir}/`,
+                        action: `执行 code_insight 的 delegated plan，由 Agent 写入 ${layout.graphDir}/`,
                         outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
                     },
-                    {
-                        id: "finalize-agents-md",
-                        action: `将下方 agentsMdTemplate 写入 ${layout.indexPath}（mcp-probe 块置顶）`,
-                        outputs: [layout.indexPath],
-                        note: `mergeMode: ${mergedAgents.mergeMode}；manifest 已写入 ${manifestWritten}`,
-                    },
                 ],
         };
         const guide = generateGuideText(detection, projectInfo, docs, layout, resolvedRoot, {
             modularExists,
+            agentsMdWritten: true,
         });
         const header = renderOrchestrationHeader({
             tool: "init_project_context",
             goal: modularExists
-                ? "补齐图谱与 AGENTS.md 入口（保留现有分类文档）"
-                : "生成项目上下文、图谱入口与 AGENTS.md 操作规则",
+                ? "补齐图谱（保留现有分类文档；AGENTS.md 已由 MCP 写入）"
+                : "写入 AGENTS.md 与 layout，由 Agent 生成 project-context 与图谱",
             tasks: modularExists
-                ? ["保留现有分类文档", "code_insight 生成图谱", `写入 ${layout.indexPath}`]
-                : ["写分类文档", "code_insight", `写入 ${layout.indexPath}`],
+                ? ["保留现有分类文档", "code_insight + Agent 落盘图谱"]
+                : ["MCP 已写 AGENTS.md 与 layout", "Agent 写分类文档", "code_insight + Agent 落盘图谱"],
             notes: [
                 `项目根目录: ${toPosixPath(resolvedRoot)}`,
                 `上下文目录: ${docsDir}`,
@@ -289,16 +321,17 @@ async function generateProjectContext(layout, projectRoot) {
             nextSteps: [
                 ...(modularExists
                     ? [`保留 ${layout.legacyIndexPath} 与分类文档`]
-                    : [`生成 ${layout.modularDir}/ 分类文档`]),
-                "调用 code_insight",
-                `将 agentsMdTemplate 写入 ${layout.indexPath}`,
+                    : [`由 Agent 按模板创建 ${layout.modularDir}/ 分类文档`]),
+                "调用 code_insight，由 Agent 落盘图谱",
+                `${layout.indexPath} 与 ${manifestWritten} 已由 MCP 写入（mergeMode: ${mergedAgents.mergeMode}）`,
             ],
+            writtenFiles,
+            pendingFiles,
             metadata: {
                 plan,
                 graphDocs,
                 layout,
                 locale,
-                agentsMdTemplate: mergedAgents.content,
                 agentsMdMergeMode: mergedAgents.mergeMode,
                 manifestWritten,
                 projectContextFilePath: agentsPath,
@@ -306,15 +339,12 @@ async function generateProjectContext(layout, projectRoot) {
                 projectContextExists: modularExists,
             },
         };
-        return okStructured(`${header}${guide}
-
-## AGENTS.md 终稿（finalize-agents-md 使用 fsWrite 写入 \`${layout.indexPath}\`）
+        return okStructured(`${header}
+${deliverySection}
 
-\`\`\`markdown
-${mergedAgents.content}
-\`\`\`
+${guide}
 
-## delegated plan
+## 后续 delegated plan（分类文档与图谱由 Agent 落盘）
 ${renderPlanSteps(plan.steps)}
 `, structuredData, {
             schema: (await import("../schemas/output/project-tools.js")).ProjectContextSchema,
@@ -332,7 +362,14 @@ function generateGuideText(detection, projectInfo, docs, layout, projectRoot, op
     const timestamp = new Date().toISOString();
     const docsDir = layout.contextRoot;
     const projectContextExists = options?.modularExists === true;
+    const agentsMdWritten = options?.agentsMdWritten === true;
     return `# 项目上下文文档生成指导
+${agentsMdWritten ? `
+## ⚠️ 文件落盘说明
+
+**MCP 已写入** \`${layout.indexPath}\` 与 \`${layout.manifestPath}\`。  
+**分类文档与图谱**须由 Agent 按下方模板与 \`code_insight\` 结果自行落盘（见 pendingFiles）。
+` : ""}
 
 ## 📊 项目信息
 
@@ -345,8 +382,8 @@ function generateGuideText(detection, projectInfo, docs, layout, projectRoot, op
 
 ## 🔎 当前状态
 
-- **${layout.indexPath}**: Agent 入口（finalize-agents-md 写入，mcp-probe 块置顶）
-- **${layout.legacyIndexPath}**: ${projectContextExists ? '已存在（将保留分类文档）' : '将随分类文档一并生成'}
+- **${layout.indexPath}**: Agent 入口（${agentsMdWritten ? "已由 MCP 写入" : "待 MCP 写入"}，mcp-probe 块置顶）
+- **${layout.legacyIndexPath}**: ${projectContextExists ? "已存在（将保留分类文档）" : "由 Agent 按模板创建"}
 - **图谱文档**: 需要确保 ${layout.latestMarkdownPath} 与 ${layout.latestJsonPath} 可用
 
 ## 📋 需要生成的文档
@@ -431,7 +468,7 @@ ${generateDevGuide(docs)}
 *生成工具: MCP Probe Kit - init_project_context v2.1*
 \`\`\`
 
-${projectContextExists ? '**如果该文件已存在，跳过此步骤，不要覆盖**' : '**使用 fsWrite 创建此文件**'}
+${projectContextExists ? '**如果该文件已存在，跳过此步骤，不要覆盖**' : '**由 Agent 使用 fsWrite 创建此文件**'}
 
 ---
 
@@ -445,7 +482,7 @@ ${docs.map((doc, index) => generateDocTemplate(doc, index + 2, projectInfo, dete
 
 请确认：
 
-- [ ] ${projectContextExists ? '保留现有 project-context 及分类文档，不做覆盖' : `已使用 fsWrite 创建 **${docs.length + 1}** 个文件`}
+- [ ] ${projectContextExists ? '保留现有 project-context 及分类文档，不做覆盖' : `由 Agent 创建 **${docs.length + 1}** 个分类文档`}
 - [ ] 索引文件 \`project-context.md\` ${projectContextExists ? '已存在并保留' : '已创建（最重要！）'}
 - [ ] 索引文件已包含 \`graph-insights/latest.md\` 的入口
 - [ ] 所有文档都包含**真实的文件路径**（不是 [xxx] 占位符）
@@ -770,7 +807,7 @@ function generateDocTemplate(doc, step, projectInfo, detection, docsDir) {
 
 ${template}
 
-**使用 fsWrite 创建此文件**`;
+**由 Agent 使用 fsWrite 创建此文件**`;
 }
 /**
  * init_project_context 工具实现