mcp-probe-kit 3.6.3 → 3.6.8

package/README.md

@@ -421,7 +421,9 @@ No installation needed, use the latest version directly.
 }
 ```
 
-> **Skill 自动安装**：任意 MCP 工具调用会在用户项目写入 `.agents/skills/mcp-probe-kit/SKILL.md`。工作区根目录**自动识别**（Cursor 注入 `WORKSPACE_FOLDER_PATHS`；OpenCode 等项目级 `opencode.json` 会设置进程 cwd），**无需**在每台客户端配置 `MCP_PROJECT_ROOT`。仅全局 MCP 且无法识别工作区时，可选手动设置 `MCP_PROJECT_ROOT` 或在工具参数传 `project_root`。需 **v3.6.3+**。
+> **Skill & AGENTS auto-bootstrap (v3.6.3+)**: Every MCP tool call writes `.agents/skills/mcp-probe-kit/SKILL.md` and merges the `mcp-probe:context` block into `AGENTS.md`. Workspace root is **auto-detected** (Cursor injects `WORKSPACE_FOLDER_PATHS`; OpenCode project `opencode.json` sets cwd). No per-client `MCP_PROJECT_ROOT` unless global MCP cannot resolve the workspace — then set `MCP_PROJECT_ROOT` or pass `project_root` in tool args.
+
+> **Multi-harness adapters (v3.6.8+)**: `AGENTS.md` and the canonical Skill stay the **single rule source**. If the project already has `.trae/`, `.lingma/`, `.comate/`, `.codebuddy/`, or `.claude/`, matching thin adapters (skill mirror or rules pointer) are written automatically — **no env vars**.
 
 #### Claude Desktop Configuration
 

package/build/index.js

@@ -389,6 +389,7 @@ function withBootstrapMeta(result, bootstrap) {
                 projectRoot: bootstrap.projectRoot,
                 skill: bootstrap.skill,
                 agentsMd: bootstrap.agentsMd,
+                harness: bootstrap.harness ?? null,
                 workspaceWarning: bootstrap.workspaceWarning ?? null,
             },
         },

package/build/lib/__tests__/agents-md-template.unit.test.js

@@ -21,6 +21,8 @@ describe('generateAgentsMdInner', () => {
         expect(md).toContain('start_bugfix');
         expect(md).toContain('memorize_asset');
         expect(md).toContain('mcp-probe-kit/SKILL.md');
+        expect(md).toContain('@.agents/skills/mcp-probe-kit/SKILL.md');
+        expect(md).toContain('待 Agent 落盘');
         expect(md).toContain('bugfix');
         expect(md).toContain('search_memory');
         expect(md).toContain('自动注入');

package/build/lib/__tests__/agents-skill-ref.unit.test.d.ts

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

package/build/lib/__tests__/agents-skill-ref.unit.test.js

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { agentsSkillReferenceSatisfied, formatAgentsSkillReference, resolveAgentsSkillRefMode, } from "../agents-skill-ref.js";
+import { MCP_PROBE_SKILL_REL_PATH } from "../workflow-skill-template.js";
+const prev = process.env.MCP_AGENTS_SKILL_REF;
+afterEach(() => {
+    if (prev === undefined) {
+        delete process.env.MCP_AGENTS_SKILL_REF;
+    }
+    else {
+        process.env.MCP_AGENTS_SKILL_REF = prev;
+    }
+});
+describe("agents-skill-ref", () => {
+    test("默认 both 模式包含 @ 与链接", () => {
+        delete process.env.MCP_AGENTS_SKILL_REF;
+        const text = formatAgentsSkillReference(".agents/skills/mcp-probe-kit/SKILL.md");
+        expect(text).toContain(`@${MCP_PROBE_SKILL_REL_PATH}`);
+        expect(text).toContain("[MCP 调用时机]");
+    });
+    test("at 模式仅 @ 引用", () => {
+        process.env.MCP_AGENTS_SKILL_REF = "at";
+        expect(resolveAgentsSkillRefMode()).toBe("at");
+        const text = formatAgentsSkillReference("skill.md");
+        expect(text).toContain("@");
+        expect(text).not.toContain("[MCP 调用时机]");
+    });
+    test("agentsSkillReferenceSatisfied 校验 both", () => {
+        const ok = `before @${MCP_PROBE_SKILL_REL_PATH} and [link](${MCP_PROBE_SKILL_REL_PATH})`;
+        expect(agentsSkillReferenceSatisfied(ok, "both")).toBe(true);
+        expect(agentsSkillReferenceSatisfied(`only ${MCP_PROBE_SKILL_REL_PATH}`, "both")).toBe(false);
+    });
+});

package/build/lib/__tests__/harness-adapters.unit.test.d.ts

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

package/build/lib/__tests__/harness-adapters.unit.test.js

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { ensureHarnessAdapters } from "../harness-adapters.js";
+import { patchLayoutManifestHarness, readLayoutManifest, resolveProjectContextLayout, writeLayoutManifest, } from "../project-context-layout.js";
+import { generateWorkflowSkillContent } from "../workflow-skill-template.js";
+import { VERSION } from "../../version.js";
+const tempDirs = [];
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("harness-adapters", () => {
+    test("规则指针使用自定义 indexPath", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-adapter-"));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, ".lingma"), { recursive: true });
+        const customIndex = "docs/project-context.md";
+        ensureHarnessAdapters(root, generateWorkflowSkillContent(VERSION), customIndex);
+        const text = fs.readFileSync(path.join(root, ".lingma/rules/mcp-probe-kit-mcp.md"), "utf8");
+        expect(text).toContain(customIndex);
+        expect(text).not.toContain("阅读项目根 `AGENTS.md`");
+    });
+    test("第二次 bootstrap 仍记录已存在的 adapters", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-adapter-"));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, ".trae"), { recursive: true });
+        const skill = generateWorkflowSkillContent(VERSION);
+        const first = ensureHarnessAdapters(root, skill);
+        expect(first.layoutHarness.adapters).toHaveLength(1);
+        const second = ensureHarnessAdapters(root, skill);
+        expect(second.adapters[0]?.skipped).toBe(true);
+        expect(second.layoutHarness.adapters).toEqual(first.layoutHarness.adapters);
+    });
+    test("patchLayoutManifestHarness 保留 generatedAt 且无变化时不写盘", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-adapter-"));
+        tempDirs.push(root);
+        const layout = resolveProjectContextLayout(root, {});
+        writeLayoutManifest(root, layout, {
+            detected: ["agents"],
+            skillCanonical: ".agents/skills/mcp-probe-kit/SKILL.md",
+            adapters: [],
+        });
+        const manifestPath = path.join(root, "docs", ".mcp-probe", "layout.json");
+        const before = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        const generatedAt = before.generatedAt;
+        const generatedBy = before.generatedBy;
+        const noop = patchLayoutManifestHarness(root, before.harness);
+        expect(noop).toBeNull();
+        const afterNoop = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        expect(afterNoop.generatedAt).toBe(generatedAt);
+        fs.mkdirSync(path.join(root, ".trae"), { recursive: true });
+        const harnessResult = ensureHarnessAdapters(root, generateWorkflowSkillContent(VERSION));
+        const patched = patchLayoutManifestHarness(root, harnessResult.layoutHarness);
+        expect(patched).not.toBeNull();
+        const afterPatch = readLayoutManifest(root);
+        expect(afterPatch?.generatedAt).toBe(generatedAt);
+        expect(afterPatch?.generatedBy).toBe(generatedBy);
+        expect(afterPatch?.harness?.adapters).toHaveLength(1);
+        const patchedAgain = patchLayoutManifestHarness(root, harnessResult.layoutHarness);
+        expect(patchedAgain).toBeNull();
+    });
+});

package/build/lib/__tests__/harness-skill-targets.unit.test.d.ts

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

package/build/lib/__tests__/harness-skill-targets.unit.test.js

@@ -0,0 +1,59 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { ensureHarnessAdapters } from "../harness-adapters.js";
+import { CANONICAL_SKILL_REL_PATH, detectHarnessContext } from "../harness-skill-targets.js";
+import { generateWorkflowSkillContent } from "../workflow-skill-template.js";
+import { VERSION } from "../../version.js";
+const tempDirs = [];
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("harness-skill-targets", () => {
+    test("无工具目录时不写适配层", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-"));
+        tempDirs.push(root);
+        const detection = detectHarnessContext(root);
+        expect(detection.adaptersToWrite).toHaveLength(0);
+        expect(detection.detected).toEqual(["agents"]);
+        expect(detection.skillCanonical).toBe(CANONICAL_SKILL_REL_PATH);
+    });
+    test("存在 .trae 时自动写 trae Skill 镜像", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-"));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, ".trae"), { recursive: true });
+        const skill = generateWorkflowSkillContent(VERSION);
+        const result = ensureHarnessAdapters(root, skill);
+        expect(result.adapters.some((a) => a.path === ".trae/skills/mcp-probe-kit/SKILL.md")).toBe(true);
+        const mirror = fs.readFileSync(path.join(root, ".trae/skills/mcp-probe-kit/SKILL.md"), "utf8");
+        expect(mirror).toBe(skill);
+        expect(result.detection.detected).toContain("trae");
+    });
+    test("存在 .lingma 时自动写规则指针", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-"));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, ".lingma"), { recursive: true });
+        const result = ensureHarnessAdapters(root, generateWorkflowSkillContent(VERSION), "AGENTS.md");
+        const lingma = result.adapters.find((a) => a.id === "lingma-rules");
+        expect(lingma?.created).toBe(true);
+        const text = fs.readFileSync(path.join(root, ".lingma/rules/mcp-probe-kit-mcp.md"), "utf8");
+        expect(text).toContain("AGENTS.md");
+        expect(text).toContain(CANONICAL_SKILL_REL_PATH);
+    });
+    test("AGENTS.md 引用路径不因 harness 变化", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-"));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, ".trae"), { recursive: true });
+        fs.mkdirSync(path.join(root, ".lingma"), { recursive: true });
+        ensureHarnessAdapters(root, generateWorkflowSkillContent(VERSION));
+        const detection = detectHarnessContext(root);
+        expect(detection.skillCanonical).toBe(".agents/skills/mcp-probe-kit/SKILL.md");
+        expect(detection.adaptersToWrite).toHaveLength(2);
+    });
+});

package/build/lib/__tests__/project-context-writer.unit.test.d.ts

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

package/build/lib/__tests__/project-context-writer.unit.test.js

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { resolveProjectContextLayout } from "../project-context-layout.js";
+import { writeProjectContextArtifacts } from "../project-context-writer.js";
+describe("project-context-writer", () => {
+    test("写入 AGENTS.md 与 modular 骨架", () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-probe-writer-"));
+        const layout = resolveProjectContextLayout(projectRoot, { docs_dir: "docs" });
+        const docs = [
+            { file: "tech-stack.md", title: "技术栈", purpose: "技术栈说明" },
+            { file: "architecture.md", title: "架构设计", purpose: "架构说明" },
+        ];
+        const result = writeProjectContextArtifacts({
+            layout,
+            mergedAgentsContent: "# AGENTS\n",
+            skipModularDocs: false,
+            projectInfo: { name: "demo", version: "1.0.0", description: "test" },
+            detection: { language: "TypeScript", framework: "node", category: "library" },
+            docs,
+        });
+        expect(result.agentsMd.action).toBe("created");
+        expect(fs.existsSync(path.join(projectRoot, "AGENTS.md"))).toBe(true);
+        expect(fs.existsSync(path.join(projectRoot, "docs", "project-context.md"))).toBe(true);
+        expect(fs.existsSync(path.join(projectRoot, "docs", "project-context", "tech-stack.md"))).toBe(true);
+    });
+});

package/build/lib/__tests__/project-mcp-resources.unit.test.js

@@ -43,7 +43,7 @@ describe("project-mcp-resources", () => {
             ensureAndDiscoverProjectResources(root);
             const content = readProjectResourceContent("probe://project/skill", root);
             expect(content?.mimeType).toBe("text/markdown");
-            expect(content?.text).toContain("mcp-probe-kit-skill-version");
+            expect(content?.text).toContain("mcp-probe-kit-version:");
         });
     });
 });

package/build/lib/__tests__/workflow-skill-frontmatter.unit.test.d.ts

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

package/build/lib/__tests__/workflow-skill-frontmatter.unit.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "vitest";
+import { formatSkillFrontmatter, generateWorkflowSkillContent, MCP_PROBE_SKILL_NAME, } from "../workflow-skill-template.js";
+import { formatSkillVersionMarker, parseSkillInstalledVersion, skillFrontmatterNeedsUpgrade, skillContentNeedsUpgrade, } from "../workflow-skill-version.js";
+describe("workflow-skill frontmatter", () => {
+    test("生成的 Skill 以 YAML frontmatter 开头", () => {
+        const content = generateWorkflowSkillContent("3.6.6");
+        expect(content.startsWith("---\n")).toBe(true);
+        expect(content).toContain(`name: ${MCP_PROBE_SKILL_NAME}`);
+        expect(content).toContain("description: >-");
+        expect(content).toContain('mcp-probe-kit-version: "3.6.6"');
+        expect(content).toContain("# MCP 调用时机");
+        expect(content).not.toContain(formatSkillVersionMarker("3.6.6"));
+    });
+    test("从 frontmatter 解析版本", () => {
+        const header = formatSkillFrontmatter("3.6.5");
+        expect(parseSkillInstalledVersion(`${header}\n\n# body`)).toBe("3.6.5");
+    });
+    test("旧 HTML 注释版本仍可解析", () => {
+        const legacy = `${formatSkillVersionMarker("3.6.3")}\n# old\n`;
+        expect(parseSkillInstalledVersion(legacy)).toBe("3.6.3");
+    });
+    test("缺 frontmatter 时触发升级", () => {
+        const legacy = `${formatSkillVersionMarker("9.9.9")}\n# body\n`;
+        expect(skillFrontmatterNeedsUpgrade(legacy)).toBe(true);
+        expect(skillContentNeedsUpgrade(legacy, "3.6.6")).toBe(true);
+    });
+    test("同版本标准 frontmatter 不升级", () => {
+        const content = generateWorkflowSkillContent("3.6.6");
+        expect(skillContentNeedsUpgrade(content, "3.6.6")).toBe(false);
+    });
+});

package/build/lib/__tests__/workflow-skill-installer.unit.test.js

@@ -5,7 +5,7 @@ import { afterEach, describe, expect, test } from "vitest";
 import { VERSION } from "../../version.js";
 import { ensureAgentsMdSkillReference, ensureMcpProbeKitBootstrap, ensureMcpProbeSkill, resolveProjectRootFromToolArgs, } from "../workflow-skill-installer.js";
 import { formatSkillVersionMarker, agentsContextNeedsUpgrade, compareSemver, skillContentNeedsUpgrade, } from "../workflow-skill-version.js";
-import { LEGACY_WORKFLOW_SKILL_REL_PATH, MCP_PROBE_SKILL_REL_PATH, } from "../workflow-skill-template.js";
+import { generateWorkflowSkillContent, LEGACY_WORKFLOW_SKILL_REL_PATH, MCP_PROBE_SKILL_REL_PATH, } from "../workflow-skill-template.js";
 import { wrapMcpProbeBlock } from "../merge-agents-md.js";
 const tempDirs = [];
 afterEach(() => {
@@ -36,10 +36,11 @@ describe("workflow-skill-installer", () => {
         expect(result.updated).toBe(false);
         expect(result.version).toBe(VERSION);
         const text = fs.readFileSync(path.join(root, MCP_PROBE_SKILL_REL_PATH), "utf8");
-        expect(text).toContain(formatSkillVersionMarker(VERSION));
+        expect(text).toContain('name: mcp-probe-kit');
+        expect(text).toContain('mcp-probe-kit-version:');
         expect(text).toContain("MCP 调用时机");
     });
-    test("同版本 Skill 不覆盖", () => {
+    test("仅 HTML 注释同版本会升级为 frontmatter", () => {
         const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
         tempDirs.push(root);
         const skillPath = path.join(root, MCP_PROBE_SKILL_REL_PATH);
@@ -47,11 +48,24 @@ describe("workflow-skill-installer", () => {
         fs.mkdirSync(path.dirname(skillPath), { recursive: true });
         fs.writeFileSync(skillPath, content, "utf8");
         const result = ensureMcpProbeSkill(root);
+        expect(result.updated).toBe(true);
+        const text = fs.readFileSync(skillPath, "utf8");
+        expect(text).toContain("name: mcp-probe-kit");
+        expect(text).not.toBe(content);
+    });
+    test("标准 frontmatter 同版本不覆盖", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        const skillPath = path.join(root, MCP_PROBE_SKILL_REL_PATH);
+        const content = generateWorkflowSkillContent(VERSION);
+        fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+        fs.writeFileSync(skillPath, content, "utf8");
+        const result = ensureMcpProbeSkill(root);
         expect(result.created).toBe(false);
         expect(result.updated).toBe(false);
         expect(fs.readFileSync(skillPath, "utf8")).toBe(content);
     });
-    test("旧版本 Skill 会升级覆盖", () => {
+    test("旧版 HTML 注释 Skill 会升级", () => {
         const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
         tempDirs.push(root);
         const skillPath = path.join(root, MCP_PROBE_SKILL_REL_PATH);
@@ -61,11 +75,11 @@ describe("workflow-skill-installer", () => {
         expect(result.updated).toBe(true);
         expect(result.previousVersion).toBe("0.1.0");
         const text = fs.readFileSync(skillPath, "utf8");
-        expect(text).toContain(formatSkillVersionMarker(VERSION));
+        expect(text).toContain('name: mcp-probe-kit');
         expect(text).toContain("何时调用");
         expect(text).not.toContain("stale tools list");
     });
-    test("无 AGENTS.md 时创建并引用 Skill", () => {
+    test("无 AGENTS.md 时创建并 @ 引用 Skill", () => {
         const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
         tempDirs.push(root);
         const result = ensureAgentsMdSkillReference(root);
@@ -73,6 +87,7 @@ describe("workflow-skill-installer", () => {
         const agents = fs.readFileSync(path.join(root, "AGENTS.md"), "utf8");
         expect(agents).toContain("mcp-probe:context-version");
         expect(agents).toContain(MCP_PROBE_SKILL_REL_PATH);
+        expect(agents).toContain(`@${MCP_PROBE_SKILL_REL_PATH}`);
     });
     test("已有 AGENTS.md 但缺 Skill 引用时更新", () => {
         const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));

package/build/lib/agents-md-template.d.ts

@@ -15,6 +15,7 @@ export interface AgentsMdTemplateInput {
     }>;
     projectRootPosix: string;
     graphReady: boolean;
+    contextReady?: boolean;
     /** @deprecated kept for callers; memory rules are always included in AGENTS.md */
     memoryEnabled?: boolean;
 }

package/build/lib/agents-md-template.js

@@ -1,4 +1,5 @@
 import { relativeLink } from "./project-context-layout.js";
+import { formatAgentsSkillReference, formatAgentsSkillReferenceEn, } from "./agents-skill-ref.js";
 import { MCP_PROBE_SKILL_REL_PATH } from "./workflow-skill-template.js";
 function link(layout, targetRel) {
     return relativeLink(layout.indexPath, targetRel);
@@ -28,12 +29,20 @@ Memory (requires MEMORY_* env):
  */
 export function generateAgentsMdInner(input) {
     const { layout, locale } = input;
+    const contextReady = input.contextReady === true;
+    const graphReady = input.graphReady === true;
     const graph = link(layout, layout.latestMarkdownPath);
     const ctxIndex = link(layout, layout.legacyIndexPath);
     const skillLink = link(layout, MCP_PROBE_SKILL_REL_PATH);
+    const contextLineZh = contextReady
+        ? `上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）`
+        : `上下文：待 Agent 落盘后读 [project-context](${ctxIndex})（可先 \`init_project_context\` + 按模板写 \`${layout.modularDir}/\`）`;
+    const graphLineZh = graphReady
+        ? `图谱：大改前读 [latest](${graph})；过期 \`code_insight\` mode=auto save_to_docs=true`
+        : `图谱：待 \`code_insight\` 落盘后读 [latest](${graph})（save_to_docs=true，由 Agent 写入）`;
     if (locale === "zh-CN") {
         return `## MCP（必须先调）
-需已配置 mcp-probe-kit。写代码前先读 Skill：[MCP 调用时机](${skillLink})（\`${MCP_PROBE_SKILL_REL_PATH}\`，首次 MCP 调用自动创建）。
+需已配置 mcp-probe-kit。${formatAgentsSkillReference(skillLink)}（首次 MCP 调用自动创建 Skill 文件）。
 
 - 不确定用哪个 MCP → \`workflow\`（返回 firstTool）
 - 新功能 → \`start_feature\`（会先搜记忆）
@@ -43,11 +52,17 @@ export function generateAgentsMdInner(input) {
 - 缺上下文 → \`init_project_context\`
 - 提交 → \`gencommit\`
 
-上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）
-图谱：大改前读 [latest](${graph})；过期 \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
+${contextLineZh}
+${graphLineZh}${memorySection(locale)}`;
     }
+    const contextLineEn = contextReady
+        ? `Context: before coding read [project-context](${ctxIndex}) (links to \`${layout.modularDir}/\`)`
+        : `Context: read [project-context](${ctxIndex}) after Agent creates it (\`init_project_context\` + templates)`;
+    const graphLineEn = graphReady
+        ? `Graph: read [latest](${graph}) before large changes; refresh \`code_insight\` mode=auto save_to_docs=true`
+        : `Graph: read [latest](${graph}) after Agent saves code_insight output (save_to_docs=true)`;
     return `## MCP (call first)
-Requires mcp-probe-kit. Before coding, read Skill: [When to call MCP](${skillLink}) (\`${MCP_PROBE_SKILL_REL_PATH}\`, auto-created on first MCP call).
+Requires mcp-probe-kit. ${formatAgentsSkillReferenceEn(skillLink)} (Skill file auto-created on first MCP call).
 
 - Unsure which MCP → \`workflow\` (returns firstTool)
 - Feature → \`start_feature\` (searches memory first)
@@ -57,8 +72,8 @@ Requires mcp-probe-kit. Before coding, read Skill: [When to call MCP](${skillLin
 - Missing context → \`init_project_context\`
 - Commit → \`gencommit\`
 
-Context: before coding read [project-context](${ctxIndex}) (links to \`${layout.modularDir}/\`)
-Graph: read [latest](${graph}) before large changes; refresh \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
+${contextLineEn}
+${graphLineEn}${memorySection(locale)}`;
 }
 export function generateAgentsMdTemplate(input) {
     return generateAgentsMdInner(input);

package/build/lib/agents-skill-ref.d.ts

@@ -0,0 +1,6 @@
+export type AgentsSkillRefMode = "link" | "at" | "both";
+/** AGENTS.md 中如何引用 mcp-probe-kit Skill（默认 both：@ 强绑定 + Markdown 链接） */
+export declare function resolveAgentsSkillRefMode(): AgentsSkillRefMode;
+export declare function formatAgentsSkillReference(skillLink: string, mode?: AgentsSkillRefMode): string;
+export declare function formatAgentsSkillReferenceEn(skillLink: string, mode?: AgentsSkillRefMode): string;
+export declare function agentsSkillReferenceSatisfied(content: string, mode?: AgentsSkillRefMode): boolean;

package/build/lib/agents-skill-ref.js

@@ -0,0 +1,45 @@
+import { MCP_PROBE_SKILL_REL_PATH } from "./workflow-skill-template.js";
+/** AGENTS.md 中如何引用 mcp-probe-kit Skill（默认 both：@ 强绑定 + Markdown 链接） */
+export function resolveAgentsSkillRefMode() {
+    const raw = process.env.MCP_AGENTS_SKILL_REF?.trim().toLowerCase();
+    if (raw === "link" || raw === "at" || raw === "both") {
+        return raw;
+    }
+    return "both";
+}
+export function formatAgentsSkillReference(skillLink, mode = resolveAgentsSkillRefMode()) {
+    const atRef = `@${MCP_PROBE_SKILL_REL_PATH}`;
+    const linkRef = `[MCP 调用时机](${skillLink})`;
+    switch (mode) {
+        case "at":
+            return `写代码前先读 Skill：${atRef}`;
+        case "link":
+            return `写代码前先读 Skill：${linkRef}（\`${MCP_PROBE_SKILL_REL_PATH}\`）`;
+        default:
+            return `写代码前先读 Skill：${atRef}（或 ${linkRef}）`;
+    }
+}
+export function formatAgentsSkillReferenceEn(skillLink, mode = resolveAgentsSkillRefMode()) {
+    const atRef = `@${MCP_PROBE_SKILL_REL_PATH}`;
+    const linkRef = `[When to call MCP](${skillLink})`;
+    switch (mode) {
+        case "at":
+            return `Before coding, read Skill: ${atRef}`;
+        case "link":
+            return `Before coding, read Skill: ${linkRef} (\`${MCP_PROBE_SKILL_REL_PATH}\`)`;
+        default:
+            return `Before coding, read Skill: ${atRef} (or ${linkRef})`;
+    }
+}
+export function agentsSkillReferenceSatisfied(content, mode = resolveAgentsSkillRefMode()) {
+    const hasAt = content.includes(`@${MCP_PROBE_SKILL_REL_PATH}`);
+    const hasLink = content.includes(MCP_PROBE_SKILL_REL_PATH);
+    switch (mode) {
+        case "at":
+            return hasAt;
+        case "link":
+            return hasLink;
+        default:
+            return hasAt && hasLink;
+    }
+}

package/build/lib/feature-spec-writer.d.ts

@@ -0,0 +1,12 @@
+import { type FileDeliveryReport } from "./file-delivery.js";
+export interface FeatureSpecTemplates {
+    requirements: string;
+    design: string;
+    tasks: string;
+}
+export declare function writeFeatureSpecFiles(input: {
+    projectRoot: string;
+    docsDir: string;
+    featureName: string;
+    templates: FeatureSpecTemplates;
+}): FileDeliveryReport;

package/build/lib/feature-spec-writer.js

@@ -0,0 +1,14 @@
+import { mergeDeliveryReports, writeProjectFile, } from "./file-delivery.js";
+export function writeFeatureSpecFiles(input) {
+    const base = `${input.docsDir}/specs/${input.featureName}`;
+    const root = input.projectRoot;
+    const report = mergeDeliveryReports({
+        writtenFiles: [
+            writeProjectFile(root, `${base}/requirements.md`, input.templates.requirements, "ifMissing"),
+            writeProjectFile(root, `${base}/design.md`, input.templates.design, "ifMissing"),
+            writeProjectFile(root, `${base}/tasks.md`, input.templates.tasks, "ifMissing"),
+        ],
+        pendingFiles: [],
+    });
+    return report;
+}

package/build/lib/file-delivery.d.ts

@@ -0,0 +1,17 @@
+export type FileWriteAction = "created" | "updated" | "skipped";
+export interface DeliveredFile {
+    path: string;
+    action: FileWriteAction;
+}
+export interface PendingFile {
+    path: string;
+    reason: string;
+}
+export interface FileDeliveryReport {
+    writtenFiles: DeliveredFile[];
+    pendingFiles: PendingFile[];
+}
+export declare function toPosixRel(relPath: string): string;
+export declare function writeProjectFile(projectRoot: string, relPath: string, content: string, policy: "ifMissing" | "always"): DeliveredFile;
+export declare function mergeDeliveryReports(...reports: FileDeliveryReport[]): FileDeliveryReport;
+export declare function formatFileDeliverySection(report: FileDeliveryReport): string;

package/build/lib/file-delivery.js

@@ -0,0 +1,42 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function toPosixRel(relPath) {
+    return relPath.replace(/\\/g, "/");
+}
+export function writeProjectFile(projectRoot, relPath, content, policy) {
+    const posixPath = toPosixRel(relPath);
+    const absPath = path.join(path.resolve(projectRoot), ...posixPath.split("/"));
+    const existed = fs.existsSync(absPath);
+    if (policy === "ifMissing" && existed) {
+        return { path: posixPath, action: "skipped" };
+    }
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, content, "utf8");
+    return { path: posixPath, action: existed ? "updated" : "created" };
+}
+export function mergeDeliveryReports(...reports) {
+    return {
+        writtenFiles: reports.flatMap((report) => report.writtenFiles),
+        pendingFiles: reports.flatMap((report) => report.pendingFiles),
+    };
+}
+export function formatFileDeliverySection(report) {
+    const lines = ["## 文件落盘状态"];
+    if (report.writtenFiles.length > 0) {
+        lines.push("", "### 已写入（MCP 服务端）");
+        for (const file of report.writtenFiles) {
+            const verb = file.action === "created" ? "已创建" : file.action === "updated" ? "已更新" : "已跳过（已存在）";
+            lines.push(`- \`${file.path}\` — ${verb}`);
+        }
+    }
+    if (report.pendingFiles.length > 0) {
+        lines.push("", "### 尚未创建（仅规划 / 待后续步骤）");
+        for (const file of report.pendingFiles) {
+            lines.push(`- \`${file.path}\` — ${file.reason}`);
+        }
+    }
+    if (report.writtenFiles.length === 0 && report.pendingFiles.length === 0) {
+        lines.push("", "- 无文件变更");
+    }
+    return lines.join("\n");
+}

package/build/lib/graph-insights-writer.d.ts

@@ -0,0 +1,10 @@
+import type { CodeInsightBridgeResult } from "./gitnexus-bridge.js";
+import { type ProjectContextLayout } from "./project-context-layout.js";
+import { type FileDeliveryReport } from "./file-delivery.js";
+export declare function buildGraphInsightMarkdown(result: CodeInsightBridgeResult, structured: Record<string, unknown>): string;
+export declare function persistGraphInsightsDocs(input: {
+    projectRoot: string;
+    layout: ProjectContextLayout;
+    result: CodeInsightBridgeResult;
+    structured: Record<string, unknown>;
+}): FileDeliveryReport;

package/build/lib/graph-insights-writer.js

@@ -0,0 +1,65 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { layoutAbsPath } from "./project-context-layout.js";
+import { mergeDeliveryReports, toPosixRel, writeProjectFile, } from "./file-delivery.js";
+function makeSafeSegment(value) {
+    return (value || "code-insight")
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48) || "code-insight";
+}
+export function buildGraphInsightMarkdown(result, structured) {
+    const mode = structured.mode;
+    const executionLines = result.executions
+        .map((item) => {
+        if (item.ok) {
+            return `- **${item.tool}**${item.status ? ` [${item.status}]` : ""}: ${(item.text || "已返回结果").replace(/\s+/g, " ").slice(0, 500)}`;
+        }
+        return `- **${item.tool}** ⚠️: ${(item.error || "调用失败").replace(/\s+/g, " ").slice(0, 300)}`;
+    })
+        .join("\n");
+    return `# 代码图谱洞察
+
+> 由 mcp-probe-kit \`code_insight\` 自动生成
+
+| 字段 | 值 |
+|------|-----|
+| 状态 | ${String(structured.status ?? "ok")} |
+| 模式 | ${mode?.requested ?? "auto"} → ${mode?.resolved ?? "auto"} |
+| 来源 | ${result.provider} |
+| 工作区 | ${result.workspaceMode} |
+| 生成时间 | ${new Date().toISOString()} |
+
+## 摘要
+
+${result.summary}
+
+## 执行记录
+
+${executionLines || "- 无执行记录"}
+
+${result.warnings.length > 0 ? `\n## 警告\n\n${result.warnings.map((w) => `- ${w}`).join("\n")}\n` : ""}`;
+}
+export function persistGraphInsightsDocs(input) {
+    const markdown = buildGraphInsightMarkdown(input.result, input.structured);
+    const json = JSON.stringify(input.structured, null, 2);
+    const root = path.resolve(input.projectRoot);
+    const latestMd = writeProjectFile(root, input.layout.latestMarkdownPath, markdown, "always");
+    const latestJson = writeProjectFile(root, input.layout.latestJsonPath, json, "always");
+    const graphAbs = layoutAbsPath(input.layout, input.layout.graphDir);
+    fs.mkdirSync(graphAbs, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const suffix = makeSafeSegment(input.result.summary || String(input.structured.status ?? "ok"));
+    const mode = input.structured.mode?.resolved ?? "auto";
+    const archiveBase = `${timestamp}-${mode}-${suffix}`;
+    const archiveMdRel = toPosixRel(path.join(input.layout.graphDir, `${archiveBase}.md`));
+    const archiveJsonRel = toPosixRel(path.join(input.layout.graphDir, `${archiveBase}.json`));
+    const archiveMd = writeProjectFile(root, archiveMdRel, markdown, "always");
+    const archiveJson = writeProjectFile(root, archiveJsonRel, json, "always");
+    return mergeDeliveryReports({
+        writtenFiles: [latestMd, latestJson, archiveMd, archiveJson],
+        pendingFiles: [],
+    });
+}