mcp-probe-kit 3.6.3 → 3.6.8

package/build/lib/project-context-writer.js

@@ -0,0 +1,120 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { layoutAbsPath } from "./project-context-layout.js";
+function writeFileEnsuringDir(absPath, content) {
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, content, "utf8");
+}
+function writeIfMissing(layout, relPath, content) {
+    const absPath = layoutAbsPath(layout, relPath);
+    if (fs.existsSync(absPath)) {
+        return { path: relPath, action: "skipped" };
+    }
+    writeFileEnsuringDir(absPath, content);
+    return { path: relPath, action: "created" };
+}
+function writeAlways(layout, relPath, content) {
+    const absPath = layoutAbsPath(layout, relPath);
+    const existed = fs.existsSync(absPath);
+    writeFileEnsuringDir(absPath, content);
+    return { path: relPath, action: existed ? "updated" : "created" };
+}
+export function buildProjectContextIndexMarkdown(projectInfo, detection, docs, docsDir) {
+    const timestamp = new Date().toISOString();
+    const docNav = docs
+        .map((doc) => `### [${doc.title}](./project-context/${doc.file})
+${doc.purpose}
+`)
+        .join("\n");
+    return `# ${projectInfo.name} - 项目上下文
+
+> 本文档是项目上下文的索引文件，提供项目概览和文档导航。
+
+## 📊 项目概览
+
+| 属性 | 值 |
+|------|-----|
+| 项目名称 | ${projectInfo.name} |
+| 版本 | ${projectInfo.version} |
+| 语言 | ${detection.language} |
+| 框架 | ${detection.framework || "无"} |
+| 类型 | ${detection.category} |
+| 描述 | ${projectInfo.description || "待补充"} |
+
+## 📚 文档导航
+
+${docNav}
+### [代码图谱洞察](./graph-insights/latest.md)
+最近一次 code_insight 分析结果，包含模块依赖、调用链和影响面摘要
+
+## 🚀 快速开始
+
+1. 阅读 [技术栈](./project-context/tech-stack.md) 了解项目使用的技术
+2. 阅读 [架构设计](./project-context/architecture.md) 了解项目结构
+3. 阅读 [代码图谱洞察](./graph-insights/latest.md) 快速理解模块依赖与调用链
+4. 根据需要查看具体的操作指南
+
+---
+*生成时间: ${timestamp}*  
+*生成工具: mcp-probe-kit init_project_context*
+`;
+}
+export function buildModularDocSkeleton(doc, projectInfo, detection) {
+    return `# ${doc.title}
+
+> ${doc.purpose}
+
+## 概述
+
+本文档描述 **${projectInfo.name}** 的${doc.title}。请根据仓库实际代码补充下方各节（勿留空占位）。
+
+## 项目信息
+
+| 属性 | 值 |
+|------|-----|
+| 语言 | ${detection.language} |
+| 框架 | ${detection.framework || "无"} |
+| 类型 | ${detection.category} |
+
+## 待补充
+
+- 从项目中提取真实路径与代码示例
+- 步骤需具体可操作
+
+---
+*返回索引: [../project-context.md](../project-context.md)*
+`;
+}
+/**
+ * 由 init_project_context 服务端直接落盘（勿依赖 Agent fsWrite）。
+ */
+export function writeProjectContextArtifacts(input) {
+    const { layout, mergedAgentsContent, skipModularDocs, projectInfo, detection, docs } = input;
+    const docsDir = layout.contextRoot;
+    const agentsMd = writeAlways(layout, layout.indexPath, mergedAgentsContent);
+    let projectContextIndex = null;
+    const modularDocs = [];
+    if (!skipModularDocs) {
+        projectContextIndex = writeIfMissing(layout, layout.legacyIndexPath, buildProjectContextIndexMarkdown(projectInfo, detection, docs, docsDir));
+        for (const doc of docs) {
+            const rel = `${layout.modularDir}/${doc.file}`;
+            modularDocs.push(writeIfMissing(layout, rel, buildModularDocSkeleton(doc, projectInfo, detection)));
+        }
+    }
+    return { agentsMd, projectContextIndex, modularDocs };
+}
+export function formatWriteSummary(result) {
+    const lines = ["## 已写入磁盘（MCP 服务端）"];
+    const push = (record) => {
+        const verb = record.action === "created" ? "已创建" : record.action === "updated" ? "已更新" : "已跳过（已存在）";
+        lines.push(`- \`${record.path}\` — ${verb}`);
+    };
+    push(result.agentsMd);
+    if (result.projectContextIndex) {
+        push(result.projectContextIndex);
+    }
+    for (const doc of result.modularDocs) {
+        push(doc);
+    }
+    return lines.join("\n");
+}

package/build/lib/tool-annotations.js

@@ -14,7 +14,7 @@
  */
 export const TOOL_ANNOTATIONS = {
     // —— 只读指南型（可安全自动放行）——
-    init_project: { title: '初始化项目', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    init_project: { title: '初始化项目', readOnlyHint: false, idempotentHint: true, openWorldHint: false }, // 仅写 Skill + AGENTS.md
     workflow: { title: '开发工作流路由', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     gencommit: { title: '生成提交信息', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     code_review: { title: '代码审查', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
@@ -43,7 +43,7 @@ export const TOOL_ANNOTATIONS = {
     start_feature: { title: '新功能开发编排', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
     start_bugfix: { title: 'Bug 修复编排', readOnlyHint: true, idempotentHint: false, openWorldHint: true },
     // —— 写型（工具自身落盘 / 写记忆 / 写缓存，非破坏）——
-    init_project_context: { title: '生成项目上下文', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, // 自己写 docs/.mcp-probe/layout.json（其余为指令）
+    init_project_context: { title: '生成项目上下文', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, // 仅写 AGENTS.md + layout.json
     memorize_asset: { title: '沉淀记忆资产', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }, // 写 Qdrant
     delete_memory_asset: { title: '删除记忆资产', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }, // 删 Qdrant
     update_memory_asset: { title: '更新记忆资产', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }, // 写 Qdrant

package/build/lib/workflow-skill-installer.d.ts

@@ -1,3 +1,4 @@
+import { type HarnessAdapterEnsureResult } from "./harness-adapters.js";
 export interface SkillEnsureResult {
     skillPath: string;
     skillRelPath: string;
@@ -17,6 +18,7 @@ export interface McpProbeKitBootstrapResult {
     projectRoot: string;
     skill: SkillEnsureResult;
     agentsMd: AgentsMdEnsureResult;
+    harness?: HarnessAdapterEnsureResult;
     /** 工作区可能解析失败（写到了 mcp-probe-kit 安装目录） */
     workspaceWarning?: string;
 }

package/build/lib/workflow-skill-installer.js

@@ -1,10 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { agentsSkillReferenceSatisfied, resolveAgentsSkillRefMode, } from "./agents-skill-ref.js";
 import { generateAgentsMdInner } from "./agents-md-template.js";
 import { mergeAgentsMdBlock } from "./merge-agents-md.js";
-import { detectDocumentLocale, resolveProjectContextLayout, toPosixPath, } from "./project-context-layout.js";
 import { generateWorkflowSkillContent, LEGACY_WORKFLOW_SKILL_REL_PATH, MCP_PROBE_SKILL_REL_PATH, } from "./workflow-skill-template.js";
-import { agentsContextNeedsUpgrade, getMcpProbeSkillVersion, parseSkillVersionMarker, skillContentNeedsUpgrade, } from "./workflow-skill-version.js";
+import { agentsContextNeedsUpgrade, getMcpProbeSkillVersion, parseSkillInstalledVersion, skillContentNeedsUpgrade, } from "./workflow-skill-version.js";
+import { ensureHarnessAdapters } from "./harness-adapters.js";
+import { detectDocumentLocale, patchLayoutManifestHarness, resolveProjectContextLayout, toPosixPath, } from "./project-context-layout.js";
 import { isLikelyProjectNamedRelativePath, getMcpPackageInstallRoot, resolveWorkspaceRoot, } from "./workspace-root.js";
 function buildWorkspaceWarning(projectRoot) {
     const normalizedRoot = path.resolve(projectRoot);
@@ -42,6 +44,7 @@ function buildAgentsMdInner(projectRoot, existingAgentsContent) {
     const layout = resolveProjectContextLayout(projectRoot);
     const locale = detectDocumentLocale(projectRoot, existingAgentsContent);
     const graphReady = fs.existsSync(path.join(projectRoot, layout.latestMarkdownPath));
+    const contextReady = fs.existsSync(path.join(projectRoot, layout.legacyIndexPath));
     return generateAgentsMdInner({
         layout,
         locale,
@@ -53,6 +56,7 @@ function buildAgentsMdInner(projectRoot, existingAgentsContent) {
         docs: [],
         projectRootPosix: toPosixPath(projectRoot),
         graphReady,
+        contextReady,
     });
 }
 function agentsMdNeedsUpdate(content, skillRelPath, targetVersion) {
@@ -68,6 +72,9 @@ function agentsMdNeedsUpdate(content, skillRelPath, targetVersion) {
     if (!content.includes(skillRelPath)) {
         return true;
     }
+    if (!agentsSkillReferenceSatisfied(content, resolveAgentsSkillRefMode())) {
+        return true;
+    }
     if (agentsContextNeedsUpgrade(content, targetVersion)) {
         return true;
     }
@@ -85,7 +92,7 @@ export function ensureMcpProbeSkill(projectRoot) {
     const skillPath = path.join(root, MCP_PROBE_SKILL_REL_PATH);
     const targetVersion = getMcpProbeSkillVersion();
     const existing = fs.existsSync(skillPath) ? fs.readFileSync(skillPath, "utf8") : null;
-    const previousVersion = existing ? parseSkillVersionMarker(existing) : null;
+    const previousVersion = existing ? parseSkillInstalledVersion(existing) : null;
     if (!skillContentNeedsUpgrade(existing, targetVersion)) {
         return {
             skillPath,
@@ -144,10 +151,17 @@ export function ensureAgentsMdSkillReference(projectRoot) {
 export function ensureMcpProbeKitBootstrap(projectRoot) {
     const root = path.resolve(projectRoot);
     const workspaceWarning = buildWorkspaceWarning(root);
+    const skill = ensureMcpProbeSkill(root);
+    const agentsMd = ensureAgentsMdSkillReference(root);
+    const skillContent = fs.readFileSync(skill.skillPath, "utf8");
+    const layout = resolveProjectContextLayout(root);
+    const harness = ensureHarnessAdapters(root, skillContent, layout.indexPath);
+    patchLayoutManifestHarness(root, harness.layoutHarness);
     return {
         projectRoot: root,
-        skill: ensureMcpProbeSkill(root),
-        agentsMd: ensureAgentsMdSkillReference(root),
+        skill,
+        agentsMd,
+        harness,
         workspaceWarning,
     };
 }

package/build/lib/workflow-skill-template.d.ts

@@ -6,4 +6,7 @@ export declare const MCP_PROBE_SKILL_REL_PATH = ".agents/skills/mcp-probe-kit/SK
 /** @deprecated 旧路径，仅用于检测并升级 AGENTS.md 引用 */
 export declare const LEGACY_WORKFLOW_SKILL_REL_PATH = ".agents/skills/workflow/SKILL.md";
 export declare function generateWorkflowSkillBody(skillVersion?: string): string;
+export declare const MCP_PROBE_SKILL_NAME = "mcp-probe-kit";
+export declare const MCP_PROBE_SKILL_DESCRIPTION = "\u5C06\u7528\u6237\u610F\u56FE\u8DEF\u7531\u5230 mcp-probe-kit MCP \u5DE5\u5177\uFF08start_feature\u3001start_bugfix\u3001code_insight\u3001workflow\u3001gencommit \u7B49\uFF09\u3002\u5728\u5DF2\u914D\u7F6E MCP \u4E14\u51C6\u5907\u5199\u4EE3\u7801\u524D\u8BFB\u53D6\uFF1B\u4EC5\u8BF4\u660E\u8C03\u54EA\u4E2A MCP\uFF0C\u4E0D\u662F\u9879\u76EE\u7814\u53D1\u6D41\u7A0B\u672C\u8EAB\u3002Routes intent to mcp-probe-kit MCP tools; read before coding when MCP is configured.";
+export declare function formatSkillFrontmatter(skillVersion?: string): string;
 export declare function generateWorkflowSkillContent(skillVersion?: string): string;

package/build/lib/workflow-skill-template.js

@@ -4,7 +4,7 @@
  */
 import { VERSION } from "../version.js";
 import { MCP_INTENT_QUICK_LOOKUP, MCP_SKILL_AVOID_RULES, MCP_SKILL_COMMON_FLOWS, MCP_TOOL_SKILL_GROUPS, } from "./mcp-tool-skill-registry.js";
-import { formatSkillVersionMarker } from "./workflow-skill-version.js";
+import { SKILL_VERSION_FRONTMATTER_KEY } from "./workflow-skill-version.js";
 export const MCP_PROBE_SKILL_REL_PATH = ".agents/skills/mcp-probe-kit/SKILL.md";
 /** @deprecated 旧路径，仅用于检测并升级 AGENTS.md 引用 */
 export const LEGACY_WORKFLOW_SKILL_REL_PATH = ".agents/skills/workflow/SKILL.md";
@@ -74,12 +74,19 @@ ${renderAvoidRules()}
 *mcp-probe-kit 按版本自动同步（当前 \`${skillVersion}\`）。路径：\`${MCP_PROBE_SKILL_REL_PATH}\`*
 `;
 }
+export const MCP_PROBE_SKILL_NAME = "mcp-probe-kit";
+export const MCP_PROBE_SKILL_DESCRIPTION = `将用户意图路由到 mcp-probe-kit MCP 工具（start_feature、start_bugfix、code_insight、workflow、gencommit 等）。在已配置 MCP 且准备写代码前读取；仅说明调哪个 MCP，不是项目研发流程本身。Routes intent to mcp-probe-kit MCP tools; read before coding when MCP is configured.`;
+export function formatSkillFrontmatter(skillVersion = VERSION) {
+    return `---
+name: ${MCP_PROBE_SKILL_NAME}
+description: >-
+  ${MCP_PROBE_SKILL_DESCRIPTION}
+${SKILL_VERSION_FRONTMATTER_KEY}: "${skillVersion}"
+---`;
+}
 export function generateWorkflowSkillContent(skillVersion = VERSION) {
-    const versionMarker = formatSkillVersionMarker(skillVersion);
-    return `${versionMarker}
+    return `${formatSkillFrontmatter(skillVersion)}
 
 ${generateWorkflowSkillBody(skillVersion)}
-
-${versionMarker}
 `;
 }

package/build/lib/workflow-skill-version.d.ts

@@ -1,4 +1,6 @@
-/** Skill 文件首行版本标记：`<!-- mcp-probe-kit-skill-version: 3.5.0 -->` */
+/** Skill frontmatter 版本字段 */
+export declare const SKILL_VERSION_FRONTMATTER_KEY = "mcp-probe-kit-version";
+/** @deprecated 旧版 HTML 版本标记，仍用于解析历史文件 */
 export declare const SKILL_VERSION_MARKER = "mcp-probe-kit-skill-version";
 /** AGENTS.md mcp-probe 块内版本标记 */
 export declare const AGENTS_CONTEXT_VERSION_MARKER = "mcp-probe:context-version";
@@ -6,6 +8,10 @@ export declare function getMcpProbeSkillVersion(): string;
 export declare function formatSkillVersionMarker(version?: string): string;
 export declare function formatAgentsContextVersionMarker(version?: string): string;
 export declare function parseSkillVersionMarker(content: string): string | null;
+/** 从 Skill 正文解析已安装版本（frontmatter 优先，HTML 注释兜底） */
+export declare function parseSkillInstalledVersion(content: string): string | null;
+/** 是否缺少 Agent Skill 发现所需的 YAML frontmatter */
+export declare function skillFrontmatterNeedsUpgrade(content: string): boolean;
 export declare function parseAgentsContextVersion(content: string): string | null;
 /** 比较 semver（仅主版本号段，忽略 prerelease 后缀） */
 export declare function compareSemver(a: string, b: string): number;

package/build/lib/workflow-skill-version.js

@@ -1,5 +1,7 @@
 import { VERSION } from "../version.js";
-/** Skill 文件首行版本标记：`<!-- mcp-probe-kit-skill-version: 3.5.0 -->` */
+/** Skill frontmatter 版本字段 */
+export const SKILL_VERSION_FRONTMATTER_KEY = "mcp-probe-kit-version";
+/** @deprecated 旧版 HTML 版本标记，仍用于解析历史文件 */
 export const SKILL_VERSION_MARKER = "mcp-probe-kit-skill-version";
 /** AGENTS.md mcp-probe 块内版本标记 */
 export const AGENTS_CONTEXT_VERSION_MARKER = "mcp-probe:context-version";
@@ -17,6 +19,44 @@ export function parseSkillVersionMarker(content) {
     const match = content.match(pattern);
     return match?.[1]?.trim() ?? null;
 }
+function parseSkillVersionFromFrontmatter(content) {
+    if (!content.trimStart().startsWith("---")) {
+        return null;
+    }
+    const end = content.indexOf("\n---", 3);
+    if (end === -1) {
+        return null;
+    }
+    const header = content.slice(0, end + 4);
+    const pattern = new RegExp(`^${SKILL_VERSION_FRONTMATTER_KEY}:\\s*["']?([^"'\\n]+)["']?\\s*$`, "m");
+    const match = header.match(pattern);
+    return match?.[1]?.trim().replace(/^["']|["']$/g, "") ?? null;
+}
+/** 从 Skill 正文解析已安装版本（frontmatter 优先，HTML 注释兜底） */
+export function parseSkillInstalledVersion(content) {
+    return parseSkillVersionFromFrontmatter(content) ?? parseSkillVersionMarker(content);
+}
+/** 是否缺少 Agent Skill 发现所需的 YAML frontmatter */
+export function skillFrontmatterNeedsUpgrade(content) {
+    if (!content.trimStart().startsWith("---")) {
+        return true;
+    }
+    const end = content.indexOf("\n---", 3);
+    if (end === -1) {
+        return true;
+    }
+    const header = content.slice(0, end + 4);
+    if (!/^name:\s*mcp-probe-kit\s*$/m.test(header)) {
+        return true;
+    }
+    if (!/^description:\s*>?-?\s*\S/m.test(header)) {
+        return true;
+    }
+    if (!new RegExp(`^${SKILL_VERSION_FRONTMATTER_KEY}:\\s*`, "m").test(header)) {
+        return true;
+    }
+    return false;
+}
 export function parseAgentsContextVersion(content) {
     const pattern = new RegExp(`<!--\\s*${AGENTS_CONTEXT_VERSION_MARKER}:\\s*([^\\s>]+)\\s*-->`, "i");
     const match = content.match(pattern);
@@ -49,7 +89,10 @@ export function skillContentNeedsUpgrade(existing, targetVersion = VERSION) {
     if (!existing?.trim()) {
         return true;
     }
-    const installed = parseSkillVersionMarker(existing);
+    if (skillFrontmatterNeedsUpgrade(existing)) {
+        return true;
+    }
+    const installed = parseSkillInstalledVersion(existing);
     if (!installed) {
         return true;
     }

package/build/schemas/output/project-tools.d.ts

@@ -70,6 +70,50 @@ export declare const ProjectInitSchema: {
                     readonly items: {
                         readonly type: "string";
                     };
+                    readonly description: "已废弃，请用 writtenFiles / plannedFiles";
+                };
+                readonly writtenFiles: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "已写入磁盘的路径";
+                };
+                readonly plannedFiles: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "规划中尚未创建的路径";
+                };
+            };
+        };
+        readonly writtenFiles: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                    };
+                    readonly action: {
+                        readonly type: "string";
+                        readonly enum: readonly ["created", "updated", "skipped"];
+                    };
+                };
+            };
+        };
+        readonly pendingFiles: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                    };
                 };
             };
         };
@@ -174,6 +218,36 @@ export declare const ProjectContextSchema: {
                     };
                 };
             };
+            readonly description: "文档索引（含已写入与待生成）";
+        };
+        readonly writtenFiles: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                    };
+                    readonly action: {
+                        readonly type: "string";
+                        readonly enum: readonly ["created", "updated", "skipped"];
+                    };
+                };
+            };
+        };
+        readonly pendingFiles: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                    };
+                };
+            };
         };
         readonly nextSteps: {
             readonly type: "array";
@@ -268,6 +342,41 @@ export declare const FeatureSpecSchema: {
                 };
             };
         };
+        readonly writtenFiles: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                    };
+                    readonly action: {
+                        readonly type: "string";
+                        readonly enum: readonly ["created", "updated", "skipped"];
+                    };
+                };
+            };
+        };
+        readonly pendingFiles: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly specPaths: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
     };
     readonly required: readonly ["summary", "featureName", "requirements", "tasks"];
 };
@@ -459,7 +568,17 @@ export interface ProjectInit {
     structure: {
         directories?: string[];
         files?: string[];
+        writtenFiles?: string[];
+        plannedFiles?: string[];
     };
+    writtenFiles?: Array<{
+        path: string;
+        action: 'created' | 'updated' | 'skipped';
+    }>;
+    pendingFiles?: Array<{
+        path: string;
+        reason: string;
+    }>;
     techStack?: string[];
     dependencies?: Record<string, string>;
     scripts?: Record<string, string>;
@@ -486,6 +605,14 @@ export interface ProjectContext {
     }>;
     nextSteps?: string[];
     metadata?: Record<string, any>;
+    writtenFiles?: Array<{
+        path: string;
+        action: 'created' | 'updated' | 'skipped';
+    }>;
+    pendingFiles?: Array<{
+        path: string;
+        reason: string;
+    }>;
 }
 export interface FeatureSpec {
     summary: string;
@@ -509,6 +636,15 @@ export interface FeatureSpec {
         normal?: string;
         pessimistic?: string;
     };
+    writtenFiles?: Array<{
+        path: string;
+        action: 'created' | 'updated' | 'skipped';
+    }>;
+    pendingFiles?: Array<{
+        path: string;
+        reason: string;
+    }>;
+    specPaths?: string[];
 }
 export interface Estimate {
     summary: string;

package/build/schemas/output/project-tools.js

@@ -32,7 +32,29 @@ export const ProjectInitSchema = {
             description: '项目结构',
             properties: {
                 directories: { type: 'array', items: { type: 'string' } },
-                files: { type: 'array', items: { type: 'string' } },
+                files: { type: 'array', items: { type: 'string' }, description: '已废弃，请用 writtenFiles / plannedFiles' },
+                writtenFiles: { type: 'array', items: { type: 'string' }, description: '已写入磁盘的路径' },
+                plannedFiles: { type: 'array', items: { type: 'string' }, description: '规划中尚未创建的路径' },
+            },
+        },
+        writtenFiles: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    action: { type: 'string', enum: ['created', 'updated', 'skipped'] },
+                },
+            },
+        },
+        pendingFiles: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    reason: { type: 'string' },
+                },
             },
         },
         techStack: {
@@ -100,6 +122,27 @@ export const ProjectContextSchema = {
                     purpose: { type: 'string' },
                 },
             },
+            description: '文档索引（含已写入与待生成）',
+        },
+        writtenFiles: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    action: { type: 'string', enum: ['created', 'updated', 'skipped'] },
+                },
+            },
+        },
+        pendingFiles: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    reason: { type: 'string' },
+                },
+            },
         },
         nextSteps: {
             type: 'array',
@@ -156,6 +199,27 @@ export const FeatureSpecSchema = {
                 pessimistic: { type: 'string' },
             },
         },
+        writtenFiles: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    action: { type: 'string', enum: ['created', 'updated', 'skipped'] },
+                },
+            },
+        },
+        pendingFiles: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    reason: { type: 'string' },
+                },
+            },
+        },
+        specPaths: { type: 'array', items: { type: 'string' } },
     },
     required: ['summary', 'featureName', 'requirements', 'tasks'],
 };

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

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

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

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { addFeature } from "../add_feature.js";
+describe("add_feature 不落盘", () => {
+    test("仅返回模板与 pendingFiles，不写 specs 文件", async () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-probe-add-feature-"));
+        const cwd = process.cwd();
+        process.chdir(projectRoot);
+        try {
+            const result = await addFeature({
+                feature_name: "user-auth",
+                description: "用户登录与注册",
+            });
+            expect(result.isError).toBeFalsy();
+            const structured = result.structuredContent;
+            expect(structured.pendingFiles).toHaveLength(3);
+            expect(structured.writtenFiles).toBeUndefined();
+            expect(fs.existsSync(path.join(projectRoot, "docs", "specs", "user-auth", "requirements.md"))).toBe(false);
+            const text = String(result.content[0].text);
+            expect(text).toMatch(/由 Agent 落盘/);
+            expect(text).toMatch(/MCP \*\*不会\*\*写入磁盘/);
+        }
+        finally {
+            process.chdir(cwd);
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+});

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

@@ -128,7 +128,7 @@ describe("code_insight 单元测试", () => {
             }
         }
     });
-    test("返回 docs 保存指引而不直接代写文件", async () => {
+    test("save_to_docs 时返回 delegated plan，由 Agent 落盘图谱文件", 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-"));
@@ -146,13 +146,11 @@ describe("code_insight 单元测试", () => {
             expect(text).toMatch(/使用场景指南/);
             expect(structured.projectDocs.latestMarkdownFilePath).toMatch(/docs\/graph-insights\/latest\.md$/);
             expect(structured.projectDocs.archiveMarkdownFilePath).toContain("/docs/graph-insights/");
-            expect(structured.projectDocs.projectContextFilePath).toMatch(/\/(AGENTS\.md|docs\/project-context\.md)$/);
-            expect(structured.projectDocs.navigationSnippet).toMatch(/代码图谱洞察/);
             expect(structured.plan.mode).toBe("delegated");
             expect(structured.plan.steps).toHaveLength(2);
             expect(structured.plan.steps[0].id).toBe("consume-result");
             expect(structured.plan.steps[1].id).toBe("optional-save");
-            expect(structured.plan.steps[1].outputs[0]).toMatch(/docs\/graph-insights\/latest\.md$/);
+            expect(structured.writtenFiles).toBeUndefined();
             expect(fs.existsSync(path.join(projectRoot, "docs", "graph-insights", "latest.md"))).toBe(false);
         }
         finally {