mcp-probe-kit 3.0.17 → 3.0.19

package/build/tools/init_project_context.js

@@ -3,6 +3,9 @@ import { okStructured } from "../lib/response.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
 import { detectProjectType } from "../lib/project-detector.js";
 import { resolveWorkspaceRoot, isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
+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';
 /**
@@ -18,9 +21,6 @@ import * as path from 'path';
  */
 // 默认文档目录
 const DEFAULT_DOCS_DIR = "docs";
-function toPosixPath(value) {
-    return value.replace(/\\/g, "/");
-}
 function renderPlanSteps(steps) {
     return steps
         .map((step, index) => {
@@ -139,137 +139,183 @@ function generateDevGuide(docs) {
             result += `\n### ${category}\n${items.join('\n')}\n`;
         }
     }
-    result += `\n### 理解代码图谱
-- **代码图谱洞察**: [latest.md](./graph-insights/latest.md) - 需要快速理解模块依赖、调用链、影响面时优先查看
+    result += `\n### 理解代码图谱
+- **代码图谱洞察**: [latest.md](./graph-insights/latest.md) - 需要快速理解模块依赖、调用链、影响面时优先查看
 `;
     return result || '\n### 开发指南\n查看上面的文档导航，根据需要选择对应的文档。\n';
 }
 /**
  * 生成项目上下文文档指导
  */
-async function generateProjectContext(docsDir, projectRoot) {
+async function generateProjectContext(layout, projectRoot) {
     try {
-        // 检测项目类型
         const resolvedRoot = resolveWorkspaceRoot(projectRoot);
-        const detection = detectProjectType(resolvedRoot);
-        const projectInfo = getProjectInfo(resolvedRoot);
+        const projectRootAbs = layout.projectRoot || resolvedRoot;
+        const detection = detectProjectType(projectRootAbs);
+        const projectInfo = getProjectInfo(projectRootAbs);
         const docs = getDocumentList(detection.category);
-        const projectContextPath = toPosixPath(path.join(resolvedRoot, docsDir, 'project-context.md'));
-        const projectContextExists = fs.existsSync(path.join(resolvedRoot, docsDir, 'project-context.md'));
-        const graphDocsRoot = toPosixPath(path.join(resolvedRoot, docsDir, 'graph-insights'));
+        const docsDir = layout.contextRoot;
+        const modularExists = legacyProjectContextExists(projectRootAbs, layout);
+        const agentsPath = toPosixPath(layoutAbsPath(layout, layout.indexPath));
         const graphDocs = {
-            latestMarkdownFilePath: `${graphDocsRoot}/latest.md`,
-            latestJsonFilePath: `${graphDocsRoot}/latest.json`,
+            latestMarkdownFilePath: layout.latestMarkdownPath,
+            latestJsonFilePath: layout.latestJsonPath,
         };
+        const existingAgentsRaw = fs.existsSync(layoutAbsPath(layout, layout.indexPath))
+            ? fs.readFileSync(layoutAbsPath(layout, layout.indexPath), "utf8")
+            : undefined;
+        const locale = detectDocumentLocale(projectRootAbs, existingAgentsRaw);
+        const agentsInner = generateAgentsMdInner({
+            layout,
+            locale,
+            projectName: projectInfo.name,
+            projectVersion: projectInfo.version,
+            description: projectInfo.description,
+            language: detection.language,
+            framework: detection.framework,
+            category: detection.category,
+            docs,
+            projectRootPosix: layout.projectRootPosix,
+            graphReady: false,
+        });
+        const mergedAgents = mergeAgentsMdBlock(existingAgentsRaw, agentsInner);
+        const manifestWritten = writeLayoutManifest(projectRootAbs, layout);
+        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: projectContextExists
+            mode: "delegated",
+            steps: modularExists
                 ? [
                     {
-                        id: 'bootstrap-code-insight',
-                        action: `检测到现有 ${projectContextPath}，跳过重写上下文文档，直接调用 code_insight 补齐图谱文档`,
+                        id: "bootstrap-code-insight",
+                        action: `检测到现有 ${layout.legacyIndexPath}，跳过重写分类文档，调用 code_insight 补齐图谱`,
+                        outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
+                        note: `调用参数: ${codeInsightArgs}`,
+                    },
+                    {
+                        id: "persist-graph-docs",
+                        action: `执行 code_insight 的 delegated plan，写入 ${layout.graphDir}/`,
                         outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
-                        note: `调用参数建议: {"mode":"auto","project_root":"${toPosixPath(resolvedRoot)}","docs_dir":"${docsDir}"}`,
+                        note: "保留现有 project-context 分类文档",
                     },
                     {
-                        id: 'persist-graph-docs',
-                        action: `严格执行 code_insight 返回的 delegated plan，将图谱结果写入 ${docsDir}/graph-insights/ 并仅更新 ${projectContextPath} 中的图谱入口`,
-                        outputs: [projectContextPath, graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
-                        note: '保留现有 project-context 内容，只补 graph-insights 入口，避免覆盖老文档。',
+                        id: "finalize-agents-md",
+                        action: `将下方 agentsMdTemplate 写入 ${layout.indexPath}（mcp-probe 块置顶，保留用户原有内容）`,
+                        outputs: [layout.indexPath],
+                        note: `mergeMode: ${mergedAgents.mergeMode}；layout manifest 已由服务端写入 ${manifestWritten}`,
                     },
                 ]
                 : [
                     {
-                        id: 'write-project-context',
-                        action: `按下方模板创建 ${projectContextPath} 以及 ${docsDir}/project-context/ 下的分类文档`,
-                        outputs: [
-                            projectContextPath,
-                            ...docs.map((doc) => toPosixPath(path.join(resolvedRoot, docsDir, 'project-context', doc.file))),
-                        ],
-                        note: '先完成项目上下文骨架，再启动图谱分析，这样后续入口才稳定。',
+                        id: "write-modular-docs",
+                        action: `先创建 ${layout.legacyIndexPath}（文档索引），再创建 ${layout.modularDir}/ 分类文档`,
+                        outputs: [layout.legacyIndexPath, ...modularOutputs],
+                        note: modularExists
+                            ? "跳过：索引与分类文档已存在"
+                            : "project-context.md 是细节入口；AGENTS.md 仅含 MCP 规则",
+                    },
+                    {
+                        id: "bootstrap-code-insight",
+                        action: "调用 code_insight 做整体图谱分析",
+                        outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
+                        note: `调用参数: ${codeInsightArgs}`,
                     },
                     {
-                        id: 'bootstrap-code-insight',
-                        action: `调用 code_insight 对项目做一次整体图谱分析，生成首份图谱文档`,
+                        id: "persist-graph-docs",
+                        action: `执行 code_insight 的 delegated plan，写入 ${layout.graphDir}/`,
                         outputs: [graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
-                        note: `调用参数建议: {"mode":"auto","project_root":"${toPosixPath(resolvedRoot)}","docs_dir":"${docsDir}"}`,
                     },
                     {
-                        id: 'persist-graph-docs',
-                        action: `严格执行 code_insight 返回的 delegated plan，将图谱结果写入 ${docsDir}/graph-insights/ 并刷新索引`,
-                        outputs: [projectContextPath, graphDocs.latestMarkdownFilePath, graphDocs.latestJsonFilePath],
-                        note: '后续 feature / bugfix 编排直接读取这份图谱文档，不再各自重新触发 code_insight。',
+                        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, docsDir, resolvedRoot, {
-            projectContextExists,
+        const guide = generateGuideText(detection, projectInfo, docs, layout, resolvedRoot, {
+            modularExists,
         });
         const header = renderOrchestrationHeader({
-            tool: 'init_project_context',
-            goal: projectContextExists
-                ? '检测到现有项目上下文，仅补齐代码图谱入口'
-                : '生成项目上下文文档，并为后续编排预置代码图谱入口',
-            tasks: projectContextExists
-                ? [
-                    '保留现有 project-context.md',
-                    '调用 code_insight 生成或刷新图谱文档',
-                    '仅补 graph-insights 索引入口',
-                ]
-                : [
-                    '先写 project-context 文档骨架',
-                    '再调用 code_insight 生成首份图谱文档',
-                    '将 graph-insights 挂回 project-context.md 索引',
-                ],
-            notes: [`项目根目录: ${toPosixPath(resolvedRoot)}`, `文档目录: ${docsDir}`],
+            tool: "init_project_context",
+            goal: modularExists
+                ? "补齐图谱与 AGENTS.md 入口（保留现有分类文档）"
+                : "生成项目上下文、图谱入口与 AGENTS.md 操作规则",
+            tasks: modularExists
+                ? ["保留现有分类文档", "code_insight 生成图谱", `写入 ${layout.indexPath}`]
+                : ["写分类文档", "code_insight", `写入 ${layout.indexPath}`],
+            notes: [
+                `项目根目录: ${toPosixPath(resolvedRoot)}`,
+                `上下文目录: ${docsDir}`,
+                `索引: ${layout.indexPath}`,
+                `layout: ${manifestWritten}（已服务端写入）`,
+            ],
         });
-        // 构建结构化数据
         const structuredData = {
-            summary: projectContextExists
-                ? `检测到现有项目上下文，仅补齐 ${detection.category} 项目的图谱分析入口`
-                : `生成 ${detection.category} 项目的上下文文档，并初始化图谱分析入口`,
+            summary: modularExists
+                ? `检测到现有项目上下文，补齐图谱与 ${layout.indexPath}`
+                : `生成 ${detection.category} 项目上下文与 ${layout.indexPath}`,
             mode: "modular",
             projectOverview: {
                 name: projectInfo.name,
                 description: projectInfo.description,
                 techStack: detection.framework ? [detection.framework] : [],
-                architecture: detection.category
+                architecture: detection.category,
             },
             documentation: [
+                { path: layout.indexPath, purpose: "Harness 入口（MCP 触发规则，省 token）" },
                 {
-                    path: `${docsDir}/project-context.md`,
-                    purpose: '项目上下文索引文件（入口）'
+                    path: layout.legacyIndexPath,
+                    purpose: "项目上下文索引（写代码前优先读，链到分类文档）",
                 },
-                ...docs.map(doc => ({
-                    path: `${docsDir}/project-context/${doc.file}`,
-                    purpose: doc.purpose
+                ...docs.map((doc) => ({
+                    path: `${layout.modularDir}/${doc.file}`,
+                    purpose: doc.purpose,
                 })),
                 {
-                    path: `${docsDir}/graph-insights/latest.md`,
-                    purpose: '最新代码图谱洞察（由 code_insight 维护）',
+                    path: layout.latestMarkdownPath,
+                    purpose: "最新代码图谱洞察（由 code_insight 维护）",
                 },
                 {
-                    path: `${docsDir}/graph-insights/latest.json`,
-                    purpose: '最新代码图谱结构化结果（由 code_insight 维护）',
+                    path: layout.latestJsonPath,
+                    purpose: "最新代码图谱结构化结果（由 code_insight 维护）",
                 },
+                { path: layout.manifestPath, purpose: "layout manifest（工具链路径发现）" },
             ],
             nextSteps: [
-                ...(projectContextExists ? ['保留现有 project-context.md，不重写已有分类文档'] : [`按模板生成 ${docsDir}/project-context.md 和分类文档`]),
-                '调用 code_insight 完成项目整体图谱分析',
-                `将图谱文档保存到 ${docsDir}/graph-insights/ 并更新 project-context.md 索引`,
+                ...(modularExists
+                    ? [`保留 ${layout.legacyIndexPath} 与分类文档`]
+                    : [`生成 ${layout.modularDir}/ 分类文档`]),
+                "调用 code_insight",
+                `将 agentsMdTemplate 写入 ${layout.indexPath}`,
             ],
             metadata: {
                 plan,
                 graphDocs,
-                projectContextFilePath: projectContextPath,
-                projectContextExists,
+                layout,
+                locale,
+                agentsMdTemplate: mergedAgents.content,
+                agentsMdMergeMode: mergedAgents.mergeMode,
+                manifestWritten,
+                projectContextFilePath: agentsPath,
+                legacyProjectContextExists: modularExists,
+                projectContextExists: modularExists,
             },
         };
-        return okStructured(`${header}${guide}
-
-## delegated plan
-${renderPlanSteps(plan.steps)}
+        return okStructured(`${header}${guide}
+
+## AGENTS.md 终稿（finalize-agents-md 使用 fsWrite 写入 \`${layout.indexPath}\`）
+
+\`\`\`markdown
+${mergedAgents.content}
+\`\`\`
+
+## delegated plan
+${renderPlanSteps(plan.steps)}
 `, structuredData, {
             schema: (await import("../schemas/output/project-tools.js")).ProjectContextSchema,
         });
@@ -282,157 +328,159 @@ ${renderPlanSteps(plan.steps)}
 /**
  * 生成指导文本
  */
-function generateGuideText(detection, projectInfo, docs, docsDir, projectRoot, options) {
+function generateGuideText(detection, projectInfo, docs, layout, projectRoot, options) {
     const timestamp = new Date().toISOString();
-    const projectContextExists = options?.projectContextExists === true;
-    return `# 项目上下文文档生成指导
-
-## 📊 项目信息
-
-- **项目名称**: ${projectInfo.name}
-- **版本**: ${projectInfo.version}
-- **语言**: ${detection.language}
-- **框架**: ${detection.framework || '未检测到'}
-- **类型**: ${detection.category}
-- **置信度**: ${detection.confidence}%
-
-## 🔎 当前状态
-
-- **project-context.md**: ${projectContextExists ? '已存在（将保留，不覆盖）' : '不存在（需要生成）'}
-- **图谱文档**: 需要确保 ${docsDir}/graph-insights/latest.md 与 latest.json 可用
-
-## 📋 需要生成的文档
-
-请按照以下结构生成 **${docs.length + 1}** 个上下文文档，并为图谱文档预留入口：
-
-\`\`\`
-${docsDir}/
-├── project-context.md          # 索引文件（必须首先生成）
-└── project-context/            # 分类文档目录
-${docs.map(doc => `    ├── ${doc.file.padEnd(28)} # ${doc.title}`).join('\n')}
-\n${docsDir}/graph-insights/
-    ├── latest.md               # 最近一次 code_insight 的 Markdown 摘要
-    └── latest.json             # 最近一次 code_insight 的结构化结果
-\`\`\`
-
----
-
-## 🎯 生成步骤
-
+    const docsDir = layout.contextRoot;
+    const projectContextExists = options?.modularExists === true;
+    return `# 项目上下文文档生成指导
+
+## 📊 项目信息
+
+- **项目名称**: ${projectInfo.name}
+- **版本**: ${projectInfo.version}
+- **语言**: ${detection.language}
+- **框架**: ${detection.framework || '未检测到'}
+- **类型**: ${detection.category}
+- **置信度**: ${detection.confidence}%
+
+## 🔎 当前状态
+
+- **${layout.indexPath}**: Agent 入口（finalize-agents-md 写入，mcp-probe 块置顶）
+- **${layout.legacyIndexPath}**: ${projectContextExists ? '已存在（将保留分类文档）' : '将随分类文档一并生成'}
+- **图谱文档**: 需要确保 ${layout.latestMarkdownPath} 与 ${layout.latestJsonPath} 可用
+
+## 📋 需要生成的文档
+
+请按照以下结构生成 **${docs.length + 1}** 个上下文文档，并为图谱文档预留入口：
+
+\`\`\`
+${docsDir}/
+├── project-context.md          # 索引文件（必须首先生成）
+└── project-context/            # 分类文档目录
+${docs.map(doc => `    ├── ${doc.file.padEnd(28)} # ${doc.title}`).join('\n')}
+\n${docsDir}/graph-insights/
+    ├── latest.md               # 最近一次 code_insight 的 Markdown 摘要
+    └── latest.json             # 最近一次 code_insight 的结构化结果
+\`\`\`
+
+---
+
+## 🎯 生成步骤
+
 ${projectContextExists
-        ? `### 已存在项目上下文（仅补图谱）
-
-检测到 \`${docsDir}/project-context.md\` 已存在：
-
-- **不要重写** 现有 \`${docsDir}/project-context.md\`
-- **不要重写** \`${docsDir}/project-context/\` 下已有分类文档
-- 直接调用 \`code_insight\` 补齐 \`${docsDir}/graph-insights/latest.md\` 与 \`${docsDir}/graph-insights/latest.json\`
-- 仅在 \`project-context.md\` 中补充或刷新图谱入口
-
----
+        ? `### 已存在项目上下文（仅补图谱）
+
+检测到 \`${docsDir}/project-context.md\` 已存在：
+
+- **不要重写** 现有 \`${docsDir}/project-context.md\`
+- **不要重写** \`${docsDir}/project-context/\` 下已有分类文档
+- 直接调用 \`code_insight\` 补齐 \`${docsDir}/graph-insights/latest.md\` 与 \`${docsDir}/graph-insights/latest.json\`
+- 仅在 \`project-context.md\` 中补充或刷新图谱入口
+
+---
 `
-        : ''}
-
-### 第一步：生成索引文件（最重要！）
-
-**文件**: \`${docsDir}/project-context.md\`
-
-这是项目上下文的**灵魂**，必须首先生成。它是所有文档的入口和导航中心。
-
-**模板**:
-
-\`\`\`markdown
-# ${projectInfo.name} - 项目上下文
-
-> 本文档是项目上下文的索引文件，提供项目概览和文档导航。
-
-## 📊 项目概览
-
-| 属性 | 值 |
-|------|-----|
-| 项目名称 | ${projectInfo.name} |
-| 版本 | ${projectInfo.version} |
-| 语言 | ${detection.language} |
-| 框架 | ${detection.framework || '无'} |
-| 类型 | ${detection.category} |
-| 描述 | ${projectInfo.description || '待补充'} |
-
-## 📚 文档导航
-
-${docs.map(doc => `### [${doc.title}](./project-context/${doc.file})
-${doc.purpose}
-`).join('\n')}
-### [代码图谱洞察](./graph-insights/latest.md)
-最近一次 code_insight 分析结果，包含模块依赖、调用链和影响面摘要
-
-## 🚀 快速开始
-
-1. 阅读 [技术栈](./project-context/tech-stack.md) 了解项目使用的技术
-2. 阅读 [架构设计](./project-context/architecture.md) 了解项目结构
-3. 阅读 [代码图谱洞察](./graph-insights/latest.md) 快速理解模块依赖与调用链
-4. 根据需要查看具体的操作指南
-
-## 💡 开发时查看对应文档
-
-根据你要做的事情，查看对应的文档：
-
-${generateDevGuide(docs)}
-
----
-*生成时间: ${timestamp}*  
-*生成工具: MCP Probe Kit - init_project_context v2.1*
-\`\`\`
-
-${projectContextExists ? '**如果该文件已存在，跳过此步骤，不要覆盖**' : '**使用 fsWrite 创建此文件**'}
-
----
-
-### 第二步：生成分类文档
-
-${docs.map((doc, index) => generateDocTemplate(doc, index + 2, projectInfo, detection, docsDir)).join('\n\n---\n\n')}
-
----
-
-## ✅ 完成标准
-
-请确认：
-
-- [ ] ${projectContextExists ? '保留现有 project-context 及分类文档，不做覆盖' : `已使用 fsWrite 创建 **${docs.length + 1}** 个文件`}
-- [ ] 索引文件 \`project-context.md\` ${projectContextExists ? '已存在并保留' : '已创建（最重要！）'}
-- [ ] 索引文件已包含 \`graph-insights/latest.md\` 的入口
-- [ ] 所有文档都包含**真实的文件路径**（不是 [xxx] 占位符）
-- [ ] 所有文档都包含**实际的代码示例**（从项目中复制）
-- [ ] 所有步骤都具体可操作
-- [ ] 所有示例都来自项目实际代码
-
----
-
-## 🔄 完成文档骨架后立即执行
-
-1. 调用 \`code_insight\`
-\`\`\`json
-{
-  "mode": "auto",
-  "project_root": "${toPosixPath(projectRoot)}",
-  "docs_dir": "${docsDir}"
-}
-\`\`\`
-2. 严格执行 \`code_insight\` 返回的 delegated plan
-3. 确保 \`${docsDir}/graph-insights/latest.md\` 和 \`${docsDir}/graph-insights/latest.json\` 已写入
-4. 若已有旧图谱，按 delegated plan 归档时间戳版本
-
----
-
-**重要提示**:
-1. **必须从项目中提取真实示例** - 不要编造代码
-2. **路径必须真实存在** - 检查文件是否存在
-3. **步骤必须具体** - 不要写"根据需要修改"这种模糊的话
-4. **代码必须完整** - 不要用 ... 省略
-
----
-
-*工具: MCP Probe Kit - init_project_context*  
-*版本: 2.1.0*
+        : ''}
+
+### 第一步：生成索引文件（最重要！）
+
+**文件**: \`${docsDir}/project-context.md\`
+
+这是项目上下文的**灵魂**，必须首先生成。它是所有文档的入口和导航中心。
+
+**模板**:
+
+\`\`\`markdown
+# ${projectInfo.name} - 项目上下文
+
+> 本文档是项目上下文的索引文件，提供项目概览和文档导航。
+
+## 📊 项目概览
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | ${projectInfo.name} |
+| 版本 | ${projectInfo.version} |
+| 语言 | ${detection.language} |
+| 框架 | ${detection.framework || '无'} |
+| 类型 | ${detection.category} |
+| 描述 | ${projectInfo.description || '待补充'} |
+
+## 📚 文档导航
+
+${docs.map(doc => `### [${doc.title}](./project-context/${doc.file})
+${doc.purpose}
+`).join('\n')}
+### [代码图谱洞察](./graph-insights/latest.md)
+最近一次 code_insight 分析结果，包含模块依赖、调用链和影响面摘要
+
+## 🚀 快速开始
+
+1. 阅读 [技术栈](./project-context/tech-stack.md) 了解项目使用的技术
+2. 阅读 [架构设计](./project-context/architecture.md) 了解项目结构
+3. 阅读 [代码图谱洞察](./graph-insights/latest.md) 快速理解模块依赖与调用链
+4. 根据需要查看具体的操作指南
+
+## 💡 开发时查看对应文档
+
+根据你要做的事情，查看对应的文档：
+
+${generateDevGuide(docs)}
+
+---
+*生成时间: ${timestamp}*  
+*生成工具: MCP Probe Kit - init_project_context v2.1*
+\`\`\`
+
+${projectContextExists ? '**如果该文件已存在，跳过此步骤，不要覆盖**' : '**使用 fsWrite 创建此文件**'}
+
+---
+
+### 第二步：生成分类文档
+
+${docs.map((doc, index) => generateDocTemplate(doc, index + 2, projectInfo, detection, docsDir)).join('\n\n---\n\n')}
+
+---
+
+## ✅ 完成标准
+
+请确认：
+
+- [ ] ${projectContextExists ? '保留现有 project-context 及分类文档，不做覆盖' : `已使用 fsWrite 创建 **${docs.length + 1}** 个文件`}
+- [ ] 索引文件 \`project-context.md\` ${projectContextExists ? '已存在并保留' : '已创建（最重要！）'}
+- [ ] 索引文件已包含 \`graph-insights/latest.md\` 的入口
+- [ ] 所有文档都包含**真实的文件路径**（不是 [xxx] 占位符）
+- [ ] 所有文档都包含**实际的代码示例**（从项目中复制）
+- [ ] 所有步骤都具体可操作
+- [ ] 所有示例都来自项目实际代码
+
+---
+
+## 🔄 完成文档骨架后立即执行
+
+1. 调用 \`code_insight\`
+\`\`\`json
+{
+  "mode": "auto",
+  "project_root": "${toPosixPath(projectRoot)}",
+  "docs_dir": "${docsDir}"
+}
+\`\`\`
+2. 严格执行 \`code_insight\` 返回的 delegated plan
+3. 确保 \`${docsDir}/graph-insights/latest.md\` 和 \`${docsDir}/graph-insights/latest.json\` 已写入
+4. 若已有旧图谱，按 delegated plan 归档时间戳版本
+
+---
+
+**重要提示**:
+1. **必须从项目中提取真实示例** - 不要编造代码
+2. **路径必须真实存在** - 检查文件是否存在
+3. **步骤必须具体** - 不要写"根据需要修改"这种模糊的话
+4. **代码必须完整** - 不要用 ... 省略
+
+---
+
+*工具: MCP Probe Kit - init_project_context*  
+*版本: 2.1.0*
 `;
 }
 /**
@@ -442,286 +490,286 @@ function generateDocTemplate(doc, step, projectInfo, detection, docsDir) {
     const timestamp = new Date().toISOString();
     // 根据文档类型生成不同的模板
     const templates = {
-        'tech-stack.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
-
-**用途**: ${doc.purpose}
-
-**模板**:
-
-\`\`\`markdown
-# 技术栈
-
-> 本文档描述 ${projectInfo.name} 的技术栈信息。
-
-## 基本信息
-
-| 属性 | 值 |
-|------|-----|
-| 项目名称 | ${projectInfo.name} |
-| 版本 | ${projectInfo.version} |
-| 语言 | ${detection.language} |
-| 框架 | ${detection.framework || '无'} |
-
-## 技术栈详情
-
-### 核心技术
-
-| 类别 | 技术 | 版本 |
-|------|------|------|
-| 语言 | [从 package.json 或配置文件中提取] | [版本] |
-| 运行时 | [Node.js/Python/Java 等] | [版本] |
-| 框架 | [主要框架] | [版本] |
-
-### 开发工具
-
-| 类别 | 工具 | 用途 |
-|------|------|------|
-| 构建工具 | [如 TypeScript, Webpack] | [用途] |
-| 测试框架 | [如 Jest, Vitest] | [用途] |
-| 代码检查 | [如 ESLint, Prettier] | [用途] |
-
-### 主要依赖
-
-列出 5-10 个最重要的依赖包及其用途。
-
----
-*返回索引: [../project-context.md](../project-context.md)*
-\`\`\`
-
-**填写指导**:
-1. 读取 \`package.json\` 获取依赖信息
-2. 读取 \`tsconfig.json\` 或其他配置文件
-3. 列出最重要的 5-10 个依赖包
+        'tech-stack.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
+
+**用途**: ${doc.purpose}
+
+**模板**:
+
+\`\`\`markdown
+# 技术栈
+
+> 本文档描述 ${projectInfo.name} 的技术栈信息。
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | ${projectInfo.name} |
+| 版本 | ${projectInfo.version} |
+| 语言 | ${detection.language} |
+| 框架 | ${detection.framework || '无'} |
+
+## 技术栈详情
+
+### 核心技术
+
+| 类别 | 技术 | 版本 |
+|------|------|------|
+| 语言 | [从 package.json 或配置文件中提取] | [版本] |
+| 运行时 | [Node.js/Python/Java 等] | [版本] |
+| 框架 | [主要框架] | [版本] |
+
+### 开发工具
+
+| 类别 | 工具 | 用途 |
+|------|------|------|
+| 构建工具 | [如 TypeScript, Webpack] | [用途] |
+| 测试框架 | [如 Jest, Vitest] | [用途] |
+| 代码检查 | [如 ESLint, Prettier] | [用途] |
+
+### 主要依赖
+
+列出 5-10 个最重要的依赖包及其用途。
+
+---
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+**填写指导**:
+1. 读取 \`package.json\` 获取依赖信息
+2. 读取 \`tsconfig.json\` 或其他配置文件
+3. 列出最重要的 5-10 个依赖包
 4. 说明每个依赖的用途`,
-        'architecture.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
-
-**用途**: ${doc.purpose}
-
-**模板**:
-
-\`\`\`markdown
-# 架构设计
-
-> 本文档描述 ${projectInfo.name} 的架构和项目结构。
-
-## 项目结构
-
-\`\`\`
-[使用 listDirectory 工具生成目录树，深度 2-3 层]
-\`\`\`
-
-## 主要目录说明
-
-| 目录 | 用途 |
-|------|------|
-| [目录名] | [从实际项目中分析得出] |
-
-## 入口文件
-
-- **主入口**: \`[实际的入口文件路径，如 src/index.ts]\`
-- **配置文件**: \`[如 package.json, tsconfig.json]\`
-
-## 架构模式
-
-- **项目类型**: ${detection.category}
-- **设计模式**: [从代码中识别，如 MVC, 工具集合, 插件系统等]
-- **模块划分**: [说明主要模块及其职责]
-
-## 核心模块
-
-### [模块名称]
-- **位置**: \`[实际路径]\`
-- **职责**: [模块功能]
-- **主要文件**: [列出 2-3 个关键文件]
-
----
-*返回索引: [../project-context.md](../project-context.md)*
-\`\`\`
-
-**填写指导**:
-1. 使用 listDirectory 工具查看项目结构
-2. 读取主要目录下的文件
-3. 识别项目的组织方式
+        'architecture.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
+
+**用途**: ${doc.purpose}
+
+**模板**:
+
+\`\`\`markdown
+# 架构设计
+
+> 本文档描述 ${projectInfo.name} 的架构和项目结构。
+
+## 项目结构
+
+\`\`\`
+[使用 listDirectory 工具生成目录树，深度 2-3 层]
+\`\`\`
+
+## 主要目录说明
+
+| 目录 | 用途 |
+|------|------|
+| [目录名] | [从实际项目中分析得出] |
+
+## 入口文件
+
+- **主入口**: \`[实际的入口文件路径，如 src/index.ts]\`
+- **配置文件**: \`[如 package.json, tsconfig.json]\`
+
+## 架构模式
+
+- **项目类型**: ${detection.category}
+- **设计模式**: [从代码中识别，如 MVC, 工具集合, 插件系统等]
+- **模块划分**: [说明主要模块及其职责]
+
+## 核心模块
+
+### [模块名称]
+- **位置**: \`[实际路径]\`
+- **职责**: [模块功能]
+- **主要文件**: [列出 2-3 个关键文件]
+
+---
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+**填写指导**:
+1. 使用 listDirectory 工具查看项目结构
+2. 读取主要目录下的文件
+3. 识别项目的组织方式
 4. 找出核心模块和关键文件`,
-        'how-to-add-api.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
-
-**用途**: ${doc.purpose}
-
-**模板**:
-
-\`\`\`markdown
-# 如何添加新接口
-
-> 本文档指导如何在 ${projectInfo.name} 中添加新的 API 接口。
-
-## 第一步：找到路由定义位置
-
-项目的路由定义在：\`[实际路径，如 src/routes/, src/api/]\`
-
-**现有示例**（从项目中找一个真实的路由文件）:
-\`\`\`[语言]
-[复制一个实际的路由定义代码]
-\`\`\`
-
-## 第二步：创建新路由
-
-1. 在 \`[路径]\` 目录下创建文件 \`[命名规范].ts\`
-2. 定义路由：
-
-\`\`\`[语言]
-[基于项目实际代码风格的示例]
-\`\`\`
-
-## 第三步：实现业务逻辑
-
-业务逻辑通常在：\`[实际路径，如 src/controllers/, src/services/]\`
-
-**现有示例**:
-\`\`\`[语言]
-[复制一个实际的 controller/service 代码]
-\`\`\`
-
-## 第四步：数据验证
-
-项目使用 [验证库名称] 进行数据验证。
-
-**示例**:
-\`\`\`[语言]
-[从项目中找一个验证示例]
-\`\`\`
-
-## 第五步：注册路由
-
-在 \`[实际文件路径]\` 中注册新路由：
-
-\`\`\`[语言]
-[实际的路由注册代码]
-\`\`\`
-
-## 第六步：测试
-
-运行测试命令：\`[实际命令，如 npm test]\`
-
----
-*返回索引: [../project-context.md](../project-context.md)*
-\`\`\`
-
-**填写指导**:
-1. 搜索 src/routes, src/api, src/controllers 等目录
-2. 找 2-3 个现有的 API 接口作为参考
-3. 复制实际的代码示例（不要编造）
+        'how-to-add-api.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
+
+**用途**: ${doc.purpose}
+
+**模板**:
+
+\`\`\`markdown
+# 如何添加新接口
+
+> 本文档指导如何在 ${projectInfo.name} 中添加新的 API 接口。
+
+## 第一步：找到路由定义位置
+
+项目的路由定义在：\`[实际路径，如 src/routes/, src/api/]\`
+
+**现有示例**（从项目中找一个真实的路由文件）:
+\`\`\`[语言]
+[复制一个实际的路由定义代码]
+\`\`\`
+
+## 第二步：创建新路由
+
+1. 在 \`[路径]\` 目录下创建文件 \`[命名规范].ts\`
+2. 定义路由：
+
+\`\`\`[语言]
+[基于项目实际代码风格的示例]
+\`\`\`
+
+## 第三步：实现业务逻辑
+
+业务逻辑通常在：\`[实际路径，如 src/controllers/, src/services/]\`
+
+**现有示例**:
+\`\`\`[语言]
+[复制一个实际的 controller/service 代码]
+\`\`\`
+
+## 第四步：数据验证
+
+项目使用 [验证库名称] 进行数据验证。
+
+**示例**:
+\`\`\`[语言]
+[从项目中找一个验证示例]
+\`\`\`
+
+## 第五步：注册路由
+
+在 \`[实际文件路径]\` 中注册新路由：
+
+\`\`\`[语言]
+[实际的路由注册代码]
+\`\`\`
+
+## 第六步：测试
+
+运行测试命令：\`[实际命令，如 npm test]\`
+
+---
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+**填写指导**:
+1. 搜索 src/routes, src/api, src/controllers 等目录
+2. 找 2-3 个现有的 API 接口作为参考
+3. 复制实际的代码示例（不要编造）
 4. 说明项目特定的命名和组织方式`,
-        'how-to-new-page.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
-
-**用途**: ${doc.purpose}
-
-**模板**:
-
-\`\`\`markdown
-# 如何创建新页面
-
-> 本文档指导如何在 ${projectInfo.name} 中创建新的页面组件。
-
-## 第一步：找到页面目录
-
-项目的页面组件在：\`[实际路径，如 src/pages/, src/views/, app/]\`
-
-**现有示例**（从项目中找一个真实的页面）:
-\`\`\`[语言]
-[复制一个实际的页面组件代码]
-\`\`\`
-
-## 第二步：创建页面文件
-
-1. 在 \`[路径]\` 目录下创建 \`[命名规范].tsx\`
-2. 定义组件：
-
-\`\`\`[语言]
-[基于项目实际代码风格的示例]
-\`\`\`
-
-## 第三步：配置路由
-
-项目使用 [路由库名称]。
-
-**路由配置位置**: \`[实际文件路径]\`
-
-**示例**:
-\`\`\`[语言]
-[从项目中找路由配置示例]
-\`\`\`
-
-## 第四步：获取数据
-
-项目使用 [数据获取方式，如 useEffect, getServerSideProps, loader]。
-
-**示例**:
-\`\`\`[语言]
-[从项目中找数据获取示例]
-\`\`\`
-
-## 第五步：编写样式
-
-项目使用 [样式方案，如 CSS Modules, Tailwind, styled-components]。
-
-**示例**:
-\`\`\`[语言]
-[从项目中找样式示例]
-\`\`\`
-
----
-*返回索引: [../project-context.md](../project-context.md)*
-\`\`\`
-
-**填写指导**:
-1. 搜索 src/pages, src/views, app 等目录
-2. 找 1-2 个现有页面作为参考
-3. 复制实际的组件代码
+        'how-to-new-page.md': `**文件**: \`${docsDir}/project-context/${doc.file}\`
+
+**用途**: ${doc.purpose}
+
+**模板**:
+
+\`\`\`markdown
+# 如何创建新页面
+
+> 本文档指导如何在 ${projectInfo.name} 中创建新的页面组件。
+
+## 第一步：找到页面目录
+
+项目的页面组件在：\`[实际路径，如 src/pages/, src/views/, app/]\`
+
+**现有示例**（从项目中找一个真实的页面）:
+\`\`\`[语言]
+[复制一个实际的页面组件代码]
+\`\`\`
+
+## 第二步：创建页面文件
+
+1. 在 \`[路径]\` 目录下创建 \`[命名规范].tsx\`
+2. 定义组件：
+
+\`\`\`[语言]
+[基于项目实际代码风格的示例]
+\`\`\`
+
+## 第三步：配置路由
+
+项目使用 [路由库名称]。
+
+**路由配置位置**: \`[实际文件路径]\`
+
+**示例**:
+\`\`\`[语言]
+[从项目中找路由配置示例]
+\`\`\`
+
+## 第四步：获取数据
+
+项目使用 [数据获取方式，如 useEffect, getServerSideProps, loader]。
+
+**示例**:
+\`\`\`[语言]
+[从项目中找数据获取示例]
+\`\`\`
+
+## 第五步：编写样式
+
+项目使用 [样式方案，如 CSS Modules, Tailwind, styled-components]。
+
+**示例**:
+\`\`\`[语言]
+[从项目中找样式示例]
+\`\`\`
+
+---
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+**填写指导**:
+1. 搜索 src/pages, src/views, app 等目录
+2. 找 1-2 个现有页面作为参考
+3. 复制实际的组件代码
 4. 说明路由配置方式`
     };
     // 如果没有特定模板，使用通用模板
-    const template = templates[doc.file] || `**文件**: \`${docsDir}/project-context/${doc.file}\`
-
-**用途**: ${doc.purpose}
-
-**模板**:
-
-\`\`\`markdown
-# ${doc.title}
-
-> 本文档描述 ${projectInfo.name} 的 ${doc.title.toLowerCase()}。
-
-## 概述
-
-[简要说明本文档的内容]
-
-## 详细步骤
-
-### 第一步：[步骤名称]
-
-[具体说明]
-
-**示例**:
-\`\`\`[语言]
-[从项目中提取的实际代码]
-\`\`\`
-
-### 第二步：[步骤名称]
-
-[具体说明]
-
----
-*返回索引: [../project-context.md](../project-context.md)*
-\`\`\`
-
-**填写指导**:
-1. 分析项目相关代码
-2. 提取真实示例
+    const template = templates[doc.file] || `**文件**: \`${docsDir}/project-context/${doc.file}\`
+
+**用途**: ${doc.purpose}
+
+**模板**:
+
+\`\`\`markdown
+# ${doc.title}
+
+> 本文档描述 ${projectInfo.name} 的 ${doc.title.toLowerCase()}。
+
+## 概述
+
+[简要说明本文档的内容]
+
+## 详细步骤
+
+### 第一步：[步骤名称]
+
+[具体说明]
+
+**示例**:
+\`\`\`[语言]
+[从项目中提取的实际代码]
+\`\`\`
+
+### 第二步：[步骤名称]
+
+[具体说明]
+
+---
+*返回索引: [../project-context.md](../project-context.md)*
+\`\`\`
+
+**填写指导**:
+1. 分析项目相关代码
+2. 提取真实示例
 3. 编写具体步骤`;
-    return `### 第${step}步：${doc.title}
-
-${template}
-
+    return `### 第${step}步：${doc.title}
+
+${template}
+
 **使用 fsWrite 创建此文件**`;
 }
 /**
@@ -736,16 +784,18 @@ export async function initProjectContext(args) {
     let docsDir = DEFAULT_DOCS_DIR;
     let projectRoot = resolveWorkspaceRoot();
     try {
-        // 智能参数解析，支持自然语言输入
         const parsedArgs = parseArgs(args, {
             defaultValues: {
                 docs_dir: DEFAULT_DOCS_DIR,
-                project_root: resolveWorkspaceRoot()
+                project_root: resolveWorkspaceRoot(),
             },
             primaryField: "docs_dir",
             fieldAliases: {
-                docs_dir: ["dir", "output", "directory", "目录", "文档目录"],
-                project_root: ["root", "path", "项目路径"]
+                docs_dir: ["dir", "directory", "文档目录", "docsDir"],
+                project_root: ["root", "path", "项目路径"],
+                output: ["index", "index_path", "agents_md"],
+                output_dir: ["outputDir"],
+                index_style: ["indexStyle", "style"],
             },
         });
         docsDir = getString(parsedArgs.docs_dir) || DEFAULT_DOCS_DIR;
@@ -764,8 +814,15 @@ export async function initProjectContext(args) {
                 },
             };
         }
-        // 生成项目上下文
-        return await generateProjectContext(docsDir, projectRoot);
+        const layoutArgs = parseLayoutArgsFromRecord({
+            docs_dir: docsDir,
+            output: getString(parsedArgs.output),
+            output_dir: getString(parsedArgs.output_dir),
+            filename: getString(parsedArgs.filename),
+            index_style: getString(parsedArgs.index_style),
+        });
+        const layout = resolveProjectContextLayout(projectRoot, layoutArgs);
+        return await generateProjectContext(layout, projectRoot);
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);