mcp-probe-kit 3.6.5 → 3.6.9

package/build/lib/harness-adapters.js

@@ -0,0 +1,166 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CANONICAL_SKILL_REL_PATH, detectHarnessContext, toLayoutHarnessManifest, } from "./harness-skill-targets.js";
+import { getMcpProbeSkillVersion } from "./workflow-skill-version.js";
+const RULES_POINTER_VERSION_KEY = "mcp-probe-kit-harness-adapter-version";
+const CLAUDE_BLOCK_BEGIN = "<!-- mcp-probe:harness begin — auto-generated; do not edit -->";
+const CLAUDE_BLOCK_END = "<!-- mcp-probe:harness end -->";
+function generateRulesPointerContent(skillCanonical, version, agentsIndexPath) {
+    return `# mcp-probe-kit MCP
+
+> ${RULES_POINTER_VERSION_KEY}: ${version}
+
+配置 **mcp-probe-kit** MCP 后，写代码 / 改文件前：
+
+1. 阅读项目根 \`${agentsIndexPath}\` 中 \`<!-- mcp-probe:context -->\` 块（MCP 触发规则）
+2. 需要完整工具表时阅读 \`${skillCanonical}\`
+
+**不要**跳过 MCP 直接改业务代码。拿不准先调 \`workflow\`。
+`;
+}
+function generateComateRulesContent(skillCanonical, version, agentsIndexPath) {
+    return `# mcp-probe-kit-mcp
+
+> ${RULES_POINTER_VERSION_KEY}: ${version}
+
+配置 mcp-probe-kit MCP 后，写代码前阅读 ${agentsIndexPath} 的 mcp-probe 块或 ${skillCanonical}。拿不准先调 workflow。
+`;
+}
+function generateClaudePointerBlock(skillCanonical, agentsPath) {
+    return `${CLAUDE_BLOCK_BEGIN}
+## MCP (mcp-probe-kit)
+
+Before coding, read the \`mcp-probe:context\` block in \`${agentsPath}\` or Skill \`${skillCanonical}\`.
+${CLAUDE_BLOCK_END}`;
+}
+function stripClaudeHarnessBlock(content) {
+    const beginIdx = content.indexOf(CLAUDE_BLOCK_BEGIN);
+    if (beginIdx === -1) {
+        return content.trim();
+    }
+    const endIdx = content.indexOf(CLAUDE_BLOCK_END);
+    if (endIdx === -1) {
+        return content.trim();
+    }
+    const before = content.slice(0, beginIdx).trimEnd();
+    const after = content.slice(endIdx + CLAUDE_BLOCK_END.length).trimStart();
+    return [before, after].filter(Boolean).join("\n\n").trim();
+}
+function mergeClaudePointer(existing, block) {
+    const userBody = existing ? stripClaudeHarnessBlock(existing) : "";
+    if (!userBody) {
+        return `${block}\n`;
+    }
+    return `${block}\n\n${userBody}\n`;
+}
+function adapterNeedsUpdate(existing, nextContent, kind, agentsIndexPath) {
+    if (!existing?.trim()) {
+        return true;
+    }
+    if (kind === "skill-mirror") {
+        return existing !== nextContent;
+    }
+    const version = getMcpProbeSkillVersion();
+    if (!existing.includes(RULES_POINTER_VERSION_KEY) || !existing.includes(version)) {
+        return true;
+    }
+    if (kind === "claude-pointer") {
+        return (!existing.includes(CANONICAL_SKILL_REL_PATH) ||
+            Boolean(agentsIndexPath && !existing.includes(agentsIndexPath)));
+    }
+    if (kind === "rules-pointer" && agentsIndexPath && !existing.includes(agentsIndexPath)) {
+        return true;
+    }
+    return existing !== nextContent;
+}
+function resolveAdapterContent(adapter, skillContent, agentsIndexPath) {
+    const version = getMcpProbeSkillVersion();
+    switch (adapter.kind) {
+        case "skill-mirror":
+            return skillContent;
+        case "rules-pointer":
+            return adapter.relPath.endsWith(".mdr")
+                ? generateComateRulesContent(CANONICAL_SKILL_REL_PATH, version, agentsIndexPath)
+                : generateRulesPointerContent(CANONICAL_SKILL_REL_PATH, version, agentsIndexPath);
+        case "claude-pointer":
+            return mergeClaudePointer(null, generateClaudePointerBlock(CANONICAL_SKILL_REL_PATH, agentsIndexPath));
+        default:
+            return skillContent;
+    }
+}
+function writeAdapterFile(projectRoot, adapter, content, agentsIndexPath) {
+    const absolute = path.join(projectRoot, adapter.relPath);
+    const existing = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : null;
+    if (adapter.kind === "claude-pointer" && existing) {
+        const block = generateClaudePointerBlock(CANONICAL_SKILL_REL_PATH, agentsIndexPath);
+        const merged = mergeClaudePointer(existing, block);
+        if (!adapterNeedsUpdate(existing, merged, adapter.kind, agentsIndexPath)) {
+            return {
+                id: adapter.id,
+                path: adapter.relPath,
+                kind: adapter.kind,
+                created: false,
+                updated: false,
+                skipped: true,
+            };
+        }
+        fs.mkdirSync(path.dirname(absolute), { recursive: true });
+        fs.writeFileSync(absolute, merged, "utf8");
+        return {
+            id: adapter.id,
+            path: adapter.relPath,
+            kind: adapter.kind,
+            created: false,
+            updated: true,
+            skipped: false,
+        };
+    }
+    if (!adapterNeedsUpdate(existing, content, adapter.kind, agentsIndexPath)) {
+        return {
+            id: adapter.id,
+            path: adapter.relPath,
+            kind: adapter.kind,
+            created: false,
+            updated: false,
+            skipped: true,
+        };
+    }
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    fs.writeFileSync(absolute, content, "utf8");
+    const hadContent = Boolean(existing?.trim());
+    return {
+        id: adapter.id,
+        path: adapter.relPath,
+        kind: adapter.kind,
+        created: !hadContent,
+        updated: hadContent,
+        skipped: false,
+    };
+}
+function collectInstalledAdapterManifest(projectRoot, detection) {
+    return detection.adaptersToWrite
+        .filter((adapter) => fs.existsSync(path.join(projectRoot, adapter.relPath)))
+        .map((adapter) => ({
+        id: adapter.id,
+        kind: adapter.kind,
+        path: adapter.relPath,
+    }));
+}
+/**
+ * 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 function ensureHarnessAdapters(projectRoot, skillContent, agentsIndexPath = "AGENTS.md") {
+    const root = path.resolve(projectRoot);
+    const detection = detectHarnessContext(root);
+    const adapters = [];
+    for (const adapter of detection.adaptersToWrite) {
+        const content = resolveAdapterContent(adapter, skillContent, agentsIndexPath);
+        adapters.push(writeAdapterFile(root, adapter, content, agentsIndexPath));
+    }
+    return {
+        detection,
+        adapters,
+        layoutHarness: toLayoutHarnessManifest(detection, collectInstalledAdapterManifest(root, detection)),
+    };
+}

package/build/lib/harness-skill-targets.d.ts

@@ -0,0 +1,38 @@
+/** Canonical Skill path — never changes per harness */
+export declare const CANONICAL_SKILL_REL_PATH = ".agents/skills/mcp-probe-kit/SKILL.md";
+export type HarnessId = "agents" | "cursor" | "claude" | "codex" | "opencode" | "trae" | "traecli" | "codebuddy" | "lingma" | "comate";
+export type HarnessAdapterKind = "skill-mirror" | "rules-pointer" | "claude-pointer";
+export interface HarnessAdapterTarget {
+    id: string;
+    harnessId: HarnessId;
+    relPath: string;
+    kind: HarnessAdapterKind;
+    /** 项目内已有该目录时才写适配层（零配置） */
+    markerDir: string;
+}
+export interface HarnessDetectionResult {
+    markerHarnesses: HarnessId[];
+    detected: HarnessId[];
+    skillCanonical: string;
+    adaptersToWrite: HarnessAdapterTarget[];
+}
+export declare const HARNESS_ADAPTER_TARGETS: HarnessAdapterTarget[];
+/**
+ * 零配置 harness 检测：项目里已有工具目录（如 `.trae/`）则写对应薄适配。
+ * AGENTS.md 与 canonical Skill 路径始终不变。
+ */
+export declare function detectHarnessContext(projectRoot: string): HarnessDetectionResult;
+export interface LayoutHarnessManifest {
+    detected: HarnessId[];
+    skillCanonical: string;
+    adapters: Array<{
+        id: string;
+        kind: HarnessAdapterKind;
+        path: string;
+    }>;
+}
+export declare function toLayoutHarnessManifest(detection: HarnessDetectionResult, writtenAdapters: Array<{
+    id: string;
+    kind: HarnessAdapterKind;
+    path: string;
+}>): LayoutHarnessManifest;

package/build/lib/harness-skill-targets.js

@@ -0,0 +1,95 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MCP_PROBE_SKILL_REL_PATH } from "./workflow-skill-template.js";
+/** Canonical Skill path — never changes per harness */
+export const CANONICAL_SKILL_REL_PATH = MCP_PROBE_SKILL_REL_PATH;
+export const HARNESS_ADAPTER_TARGETS = [
+    {
+        id: "trae-skill",
+        harnessId: "trae",
+        relPath: ".trae/skills/mcp-probe-kit/SKILL.md",
+        kind: "skill-mirror",
+        markerDir: ".trae",
+    },
+    {
+        id: "traecli-skill",
+        harnessId: "traecli",
+        relPath: ".traecli/skills/mcp-probe-kit/SKILL.md",
+        kind: "skill-mirror",
+        markerDir: ".traecli",
+    },
+    {
+        id: "codebuddy-skill",
+        harnessId: "codebuddy",
+        relPath: ".codebuddy/skills/mcp-probe-kit/SKILL.md",
+        kind: "skill-mirror",
+        markerDir: ".codebuddy",
+    },
+    {
+        id: "lingma-rules",
+        harnessId: "lingma",
+        relPath: ".lingma/rules/mcp-probe-kit-mcp.md",
+        kind: "rules-pointer",
+        markerDir: ".lingma",
+    },
+    {
+        id: "comate-rules",
+        harnessId: "comate",
+        relPath: ".comate/rules/mcp-probe-kit-mcp.mdr",
+        kind: "rules-pointer",
+        markerDir: ".comate",
+    },
+    {
+        id: "claude-pointer",
+        harnessId: "claude",
+        relPath: "CLAUDE.md",
+        kind: "claude-pointer",
+        markerDir: ".claude",
+    },
+];
+const MARKER_DIR_TO_HARNESS = {
+    ".trae": "trae",
+    ".traecli": "traecli",
+    ".codebuddy": "codebuddy",
+    ".lingma": "lingma",
+    ".comate": "comate",
+    ".cursor": "cursor",
+    ".claude": "claude",
+    ".codex": "codex",
+    ".opencode": "opencode",
+};
+function detectMarkerHarnesses(projectRoot) {
+    const found = [];
+    for (const [markerDir, harnessId] of Object.entries(MARKER_DIR_TO_HARNESS)) {
+        if (fs.existsSync(path.join(projectRoot, markerDir))) {
+            found.push(harnessId);
+        }
+    }
+    return found;
+}
+function shouldWriteAdapter(projectRoot, adapter) {
+    return fs.existsSync(path.join(projectRoot, adapter.markerDir));
+}
+/**
+ * 零配置 harness 检测：项目里已有工具目录（如 `.trae/`）则写对应薄适配。
+ * AGENTS.md 与 canonical Skill 路径始终不变。
+ */
+export function detectHarnessContext(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const markerHarnesses = detectMarkerHarnesses(root);
+    const detected = markerHarnesses.length > 0 ? markerHarnesses : ["agents"];
+    const adaptersToWrite = HARNESS_ADAPTER_TARGETS.filter((adapter) => shouldWriteAdapter(root, adapter));
+    return {
+        markerHarnesses,
+        detected,
+        skillCanonical: CANONICAL_SKILL_REL_PATH,
+        adaptersToWrite,
+    };
+}
+export function toLayoutHarnessManifest(detection, writtenAdapters) {
+    return {
+        detected: detection.detected,
+        skillCanonical: detection.skillCanonical,
+        adapters: writtenAdapters,
+    };
+}

package/build/lib/project-context-layout.d.ts

@@ -32,6 +32,15 @@ export interface ProjectContextLayoutArgs {
 }
 /** Primary env key recorded in layout.json (optional local override via projectRoot) */
 export declare const LAYOUT_PROJECT_ROOT_ENV = "MCP_PROJECT_ROOT";
+export interface LayoutManifestHarnessV1 {
+    detected: string[];
+    skillCanonical: string;
+    adapters: Array<{
+        id: string;
+        kind: string;
+        path: string;
+    }>;
+}
 export interface LayoutManifestV1 {
     version: 1;
     /** Ignored if present in old files — project root is always inferred from manifest path */
@@ -45,6 +54,8 @@ export interface LayoutManifestV1 {
     indexStyle: "agents" | "legacy";
     generatedBy: string;
     generatedAt: string;
+    /** Harness detection snapshot (AGENTS.md + canonical Skill stay harness-agnostic) */
+    harness?: LayoutManifestHarnessV1;
 }
 export declare function toPosixPath(value: string): string;
 export declare function relativeLink(fromRel: string, toRel: string): string;
@@ -66,8 +77,10 @@ export declare function manifestPathRelativeToProject(projectRoot: string, absol
 export declare function layoutAbsPath(layout: ProjectContextLayout, relativePath: string): string;
 type ProjectContextLayoutCore = Omit<ProjectContextLayout, "projectRoot" | "projectRootPosix">;
 export declare function attachProjectRoot(layout: ProjectContextLayoutCore, projectRoot: string): ProjectContextLayout;
-export declare function buildLayoutManifest(layout: ProjectContextLayout): LayoutManifestV1;
-export declare function writeLayoutManifest(projectRoot: string, layout: ProjectContextLayout): string;
+export declare function buildLayoutManifest(layout: ProjectContextLayout, harness?: LayoutManifestHarnessV1): LayoutManifestV1;
+export declare function writeLayoutManifest(projectRoot: string, layout: ProjectContextLayout, harness?: LayoutManifestHarnessV1): string;
+/** Patch harness section on an existing layout.json (e.g. after bootstrap adapters). */
+export declare function patchLayoutManifestHarness(projectRoot: string, harness: LayoutManifestHarnessV1): string | null;
 export declare function layoutFromManifest(manifest: LayoutManifestV1, fallbackProjectRoot: string, manifestFilePath?: string): ProjectContextLayout;
 export declare function resolveProjectContextLayout(projectRoot: string, args?: ProjectContextLayoutArgs): ProjectContextLayout;
 export declare function countCjkChars(text: string): number;

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

@@ -196,7 +196,7 @@ export function attachProjectRoot(layout, projectRoot) {
         projectRootPosix: projectRootToManifestValue(resolved),
     };
 }
-export function buildLayoutManifest(layout) {
+export function buildLayoutManifest(layout, harness) {
     return {
         version: 1,
         projectRootEnv: LAYOUT_PROJECT_ROOT_ENV,
@@ -207,17 +207,41 @@ export function buildLayoutManifest(layout) {
         indexStyle: layout.indexStyle,
         generatedBy: "init_project_context",
         generatedAt: new Date().toISOString(),
+        ...(harness ? { harness } : {}),
     };
 }
-export function writeLayoutManifest(projectRoot, layout) {
+export function writeLayoutManifest(projectRoot, layout, harness) {
     const resolvedRoot = path.resolve(projectRoot);
     const manifestRel = layoutManifestRel(layout.contextRoot);
-    const manifest = buildLayoutManifest(attachProjectRoot(layout, resolvedRoot));
+    const manifest = buildLayoutManifest(attachProjectRoot(layout, resolvedRoot), harness);
     const absoluteManifest = path.join(resolvedRoot, ...manifestRel.split("/"));
     fs.mkdirSync(path.dirname(absoluteManifest), { recursive: true });
     fs.writeFileSync(absoluteManifest, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
     return manifestRel;
 }
+function layoutHarnessEquals(left, right) {
+    return JSON.stringify(left ?? null) === JSON.stringify(right);
+}
+/** Patch harness section on an existing layout.json (e.g. after bootstrap adapters). */
+export function patchLayoutManifestHarness(projectRoot, harness) {
+    const resolvedRoot = path.resolve(projectRoot);
+    const existing = readLayoutManifest(resolvedRoot);
+    if (!existing) {
+        return null;
+    }
+    if (layoutHarnessEquals(existing.harness, harness)) {
+        return null;
+    }
+    const layout = layoutFromManifest(existing, resolvedRoot);
+    const manifestRel = layout.manifestPath;
+    const absoluteManifest = path.join(resolvedRoot, ...manifestRel.split("/"));
+    const updated = {
+        ...existing,
+        harness,
+    };
+    fs.writeFileSync(absoluteManifest, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
+    return manifestRel;
+}
 export function layoutFromManifest(manifest, fallbackProjectRoot, manifestFilePath) {
     const contextRoot = normalizeRelativePath(manifest.contextRoot);
     const projectRoot = resolveManifestProjectRoot(manifest, fallbackProjectRoot, manifestFilePath);

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

@@ -218,7 +218,7 @@ export declare const allToolSchemas: ({
     };
 } | {
     readonly name: "init_project_context";
-    readonly description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。";
+    readonly description: "生成/更新项目上下文写作计划（delegated）：MCP 写入 AGENTS.md 与 layout.json；project-context 分类文档与 graph-insights 由 Agent 按返回的 plan 落盘。新功能请先 start_feature，修 bug 请先 start_bugfix。";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

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

@@ -216,9 +216,21 @@ export declare const ProjectContextSchema: {
                     readonly purpose: {
                         readonly type: "string";
                     };
+                    readonly exists: {
+                        readonly type: "boolean";
+                        readonly description: "文件是否已存在于磁盘";
+                    };
+                    readonly written: {
+                        readonly type: "boolean";
+                        readonly description: "内容是否已落盘（MCP 已写或 Agent 无需再写）";
+                    };
+                    readonly agent_action_required: {
+                        readonly type: "boolean";
+                        readonly description: "是否仍需 Agent 按 plan 手动写入";
+                    };
                 };
             };
-            readonly description: "文档索引（含已写入与待生成）";
+            readonly description: "文档索引（含 exists / written / agent_action_required 状态）";
         };
         readonly writtenFiles: {
             readonly type: "array";
@@ -602,6 +614,9 @@ export interface ProjectContext {
     documentation?: Array<{
         path?: string;
         purpose?: string;
+        exists?: boolean;
+        written?: boolean;
+        agent_action_required?: boolean;
     }>;
     nextSteps?: string[];
     metadata?: Record<string, any>;

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

@@ -120,9 +120,15 @@ export const ProjectContextSchema = {
                 properties: {
                     path: { type: 'string' },
                     purpose: { type: 'string' },
+                    exists: { type: 'boolean', description: '文件是否已存在于磁盘' },
+                    written: { type: 'boolean', description: '内容是否已落盘（MCP 已写或 Agent 无需再写）' },
+                    agent_action_required: {
+                        type: 'boolean',
+                        description: '是否仍需 Agent 按 plan 手动写入',
+                    },
                 },
             },
-            description: '文档索引（含已写入与待生成）',
+            description: '文档索引（含 exists / written / agent_action_required 状态）',
         },
         writtenFiles: {
             type: 'array',