mcp-probe-kit 3.6.5 → 3.6.9

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__/file-delivery.unit.test.d.ts

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

package/build/lib/__tests__/file-delivery.unit.test.js

@@ -0,0 +1,62 @@
+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 { buildFileStatusEntries } from "../file-delivery.js";
+const tempDirs = [];
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("buildFileStatusEntries", () => {
+    test("marks MCP-created files as written", () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "file-delivery-"));
+        tempDirs.push(projectRoot);
+        const result = buildFileStatusEntries(projectRoot, [{ path: "docs/guide.md", purpose: "User guide" }], [{ path: "docs/guide.md", action: "created" }], []);
+        expect(result).toEqual([
+            {
+                path: "docs/guide.md",
+                purpose: "User guide",
+                exists: false,
+                written: true,
+                agent_action_required: false,
+            },
+        ]);
+    });
+    test("treats pre-existing on-disk files as written when not pending", () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "file-delivery-"));
+        tempDirs.push(projectRoot);
+        const relPath = "docs/existing.md";
+        fs.mkdirSync(path.join(projectRoot, "docs"), { recursive: true });
+        fs.writeFileSync(path.join(projectRoot, relPath), "# existing", "utf8");
+        const result = buildFileStatusEntries(projectRoot, [{ path: relPath }], [], []);
+        expect(result).toEqual([
+            {
+                path: relPath,
+                exists: true,
+                written: true,
+                agent_action_required: false,
+            },
+        ]);
+    });
+    test("pending files require agent action and are not written", () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "file-delivery-"));
+        tempDirs.push(projectRoot);
+        const relPath = "docs/pending.md";
+        fs.mkdirSync(path.join(projectRoot, "docs"), { recursive: true });
+        fs.writeFileSync(path.join(projectRoot, relPath), "stub", "utf8");
+        const result = buildFileStatusEntries(projectRoot, [{ path: relPath }], [{ path: relPath, action: "skipped" }], [{ path: relPath, reason: "Agent must fill template" }]);
+        expect(result).toEqual([
+            {
+                path: relPath,
+                exists: true,
+                written: false,
+                agent_action_required: true,
+            },
+        ]);
+    });
+});

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-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/file-delivery.d.ts

@@ -11,7 +11,18 @@ export interface FileDeliveryReport {
     writtenFiles: DeliveredFile[];
     pendingFiles: PendingFile[];
 }
+export interface FileStatusEntry {
+    path: string;
+    exists: boolean;
+    written: boolean;
+    agent_action_required: boolean;
+    purpose?: string;
+}
 export declare function toPosixRel(relPath: string): string;
 export declare function writeProjectFile(projectRoot: string, relPath: string, content: string, policy: "ifMissing" | "always"): DeliveredFile;
+export declare function buildFileStatusEntries(projectRoot: string, entries: Array<{
+    path: string;
+    purpose?: string;
+}>, writtenFiles: DeliveredFile[], pendingFiles: PendingFile[]): FileStatusEntry[];
 export declare function mergeDeliveryReports(...reports: FileDeliveryReport[]): FileDeliveryReport;
 export declare function formatFileDeliverySection(report: FileDeliveryReport): string;

package/build/lib/file-delivery.js

@@ -14,6 +14,26 @@ export function writeProjectFile(projectRoot, relPath, content, policy) {
     fs.writeFileSync(absPath, content, "utf8");
     return { path: posixPath, action: existed ? "updated" : "created" };
 }
+export function buildFileStatusEntries(projectRoot, entries, writtenFiles, pendingFiles) {
+    const writtenByMcp = new Set(writtenFiles
+        .filter((file) => file.action === "created" || file.action === "updated")
+        .map((file) => toPosixRel(file.path)));
+    const pendingPaths = new Set(pendingFiles.map((file) => toPosixRel(file.path)));
+    return entries.map(({ path: relPath, purpose }) => {
+        const posixPath = toPosixRel(relPath);
+        const absPath = path.join(path.resolve(projectRoot), ...posixPath.split("/"));
+        const exists = fs.existsSync(absPath);
+        const agent_action_required = pendingPaths.has(posixPath);
+        const written = writtenByMcp.has(posixPath) || (exists && !agent_action_required);
+        return {
+            path: posixPath,
+            ...(purpose !== undefined ? { purpose } : {}),
+            exists,
+            written,
+            agent_action_required,
+        };
+    });
+}
 export function mergeDeliveryReports(...reports) {
     return {
         writtenFiles: reports.flatMap((report) => report.writtenFiles),

package/build/lib/harness-adapters.d.ts

@@ -0,0 +1,19 @@
+import { type HarnessAdapterKind, type HarnessDetectionResult, type LayoutHarnessManifest } from "./harness-skill-targets.js";
+export interface HarnessAdapterWriteResult {
+    id: string;
+    path: string;
+    kind: HarnessAdapterKind;
+    created: boolean;
+    updated: boolean;
+    skipped: boolean;
+}
+export interface HarnessAdapterEnsureResult {
+    detection: HarnessDetectionResult;
+    adapters: HarnessAdapterWriteResult[];
+    layoutHarness: LayoutHarnessManifest;
+}
+/**
+ * Write optional harness adapters. AGENTS.md and canonical Skill are unchanged.
+ * Canonical Skill must already exist at `.agents/skills/mcp-probe-kit/SKILL.md`.
+ */
+export declare function ensureHarnessAdapters(projectRoot: string, skillContent: string, agentsIndexPath?: string): HarnessAdapterEnsureResult;