mcp-probe-kit 3.2.0 → 3.6.0

package/build/lib/template-loader.js

@@ -14,8 +14,8 @@ const TEMPLATE_VALIDATORS = {
         requiredFields: ['技术选型'],
     },
     'specs/feature/tasks.md': {
-        requiredSections: ['概述', '任务列表', '检查点', '文件变更清单'],
-        requiredFields: ['阶段 1', '阶段 2', '阶段 3'],
+        requiredSections: ['概述', '交付物清单', '任务列表', '检查点', '文件变更清单'],
+        requiredFields: ['阶段 1', '阶段 2', '阶段 3', '证据块'],
     },
 };
 const EMBEDDED_TEMPLATES = {
@@ -214,36 +214,60 @@ const EMBEDDED_TEMPLATES = {
 
 实现 {feature_name} 功能的任务分解。每条任务都要回链到需求（FR）与设计章节，确保不漏、不越界。
 
+> **二元禁令（零容忍）**：本文件及后续实现的交付物中，禁止出现 \`[填写]\`、\`TODO\`、\`// ...\`、省略号占位。
+> 这不是"尽量"，是"零"。任何用占位符代替真实内容的行为都视为未完成。
+
+---
+
+## 交付物清单（Scope-lock）
+
+> 先数清楚要产出什么，锁定数量。实现完成前必须回读本清单逐项核对，数量对不上即未完成。
+
+- **预计新建文件数**: [填写：N 个]
+- **预计修改文件数**: [填写：N 个]
+- **预计新增/修改函数数**: [填写：约 N 个]
+- **交付物逐项列举**:
+  1. [填写：交付物 1，如 src/auth/login.ts]
+  2. [填写：交付物 2]
+
 ---
 
 ## 任务列表
 
-> 每条任务：动词开头、单一明确、可在一次提交内完成，并标注 _需求_ 与 _设计_。
-> 示例：2.1 实现登录接口 POST /api/login — _需求: FR-1_ ｜ _设计: API 设计_
+> **每条任务的硬性结构**（缺一不可）：
+> 1. **标题**：[动词] + [对象] + [约束/验收点]。如"实现登录接口 POST /api/login，校验邮箱格式并返回 JWT"。
+>    - ❌ 反例（过于宽泛，会被打回）："优化登录"、"处理用户模块"
+> 2. **证据块**：动手前先读相关代码，贴出关键原文片段（文件:行号 + 代码），证明已理解现状再改。
+> 3. **涉及文件 + 行数预算**：列出本任务触及的文件；单文件预计超 500 行时，必须在此写明拆分方案（拆成哪些模块/组件）。
+> 4. **回链**：标注 _需求: FR-n_ 与 _设计: 章节_。
 
 ### 阶段 1: 准备工作
 
-- [ ] 1.1 [填写：任务标题]
-  - [填写：具体操作说明]
+- [ ] 1.1 [填写：动词+对象+约束的具体标题]
+  - **证据块**: [填写：先读 \`文件:行号\`，贴出现状关键片段]
+  - **涉及文件**: [填写：路径 + 行数预算；超 500 行写拆分方案]
   - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
 ### 阶段 2: 核心实现
 
-- [ ] 2.1 [填写：任务标题]
-  - [填写：具体操作说明]
+- [ ] 2.1 [填写：动词+对象+约束的具体标题]
+  - **证据块**: [填写：先读 \`文件:行号\`，贴出现状关键片段]
+  - **涉及文件**: [填写：路径 + 行数预算；超 500 行写拆分方案]
   - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
-- [ ] 2.2 [填写：任务标题]
-  - [填写：具体操作说明]
+- [ ] 2.2 [填写：动词+对象+约束的具体标题]
+  - **证据块**: [填写：先读 \`文件:行号\`，贴出现状关键片段]
+  - **涉及文件**: [填写：路径 + 行数预算；超 500 行写拆分方案]
   - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
 
 ### 阶段 3: 集成测试
 
-- [ ] 3.1 [填写：任务标题（对照验收标准逐条核验）]
-  - [填写：具体操作说明]
+- [ ] 3.1 [填写：动词+对象+约束的标题（对照验收标准逐条核验）]
+  - **证据块**: [填写：先读相关测试/接口现状]
+  - **涉及文件**: [填写：测试文件路径]
   - _需求: [填写：FR-n]_ ｜ _设计: [填写：design.md 章节]_
 
 ---
@@ -269,19 +293,23 @@ const EMBEDDED_TEMPLATES = {
 
 ## 文件变更清单
 
-| 文件 | 操作 | 说明 |
-|------|------|------|
-| [填写：文件路径] | 新建/修改 | [填写：说明] |
+| 文件 | 操作 | 行数预算 | 说明 |
+|------|------|----------|------|
+| [填写：文件路径] | 新建/修改 | [填写：预计行数] | [填写：说明] |
 
 ---
 
 ## 检查清单
 
+- [ ] 交付物清单（Scope-lock）已填，实现后数量已逐项核对
+- [ ] 每条任务标题是"动词+对象+约束"的具体描述，无宽泛标题
+- [ ] 每条任务含证据块（先读后写）
+- [ ] 每条任务标注涉及文件与行数预算，超 500 行的有拆分方案
 - [ ] 任务分阶段合理，粒度可在单次提交内完成
-- [ ] 每项任务可执行且可验证
 - [ ] 每条任务都回链到 FR 与 design 章节
 - [ ] 需求覆盖矩阵已填，无遗漏的 FR
 - [ ] 阶段 3 包含"对照验收标准核验"
+- [ ] 全文无 \`[填写]\` / \`TODO\` / 省略号占位（二元禁令）
 `,
     'specs/feature/strict/requirements.md': `# 需求文档：{feature_name}
 
@@ -399,26 +427,50 @@ const EMBEDDED_TEMPLATES = {
 
 实现 {feature_name} 的任务分解；每条任务回链 FR 与 design 章节。
 
+> **二元禁令**：交付物中零容忍 \`[填写]\` / \`TODO\` / \`// ...\` 等占位。动手前先读相关代码贴出证据，再写实现。单文件超 500 行必须拆分。
+
+---
+
+## 交付物清单（Scope-lock）
+
+- 预计文件数: [填写：N]
+- 预计任务数: [填写：N]
+
+> 实现完成前回读本清单逐项核对，数量不符即未完成。
+
 ---
 
 ## 任务列表
 
+> 每条任务标题须为「[动词]+[对象]+[约束]」的具体写法（如「新建 auth.service.ts 实现 JWT 签发，≤120 行」），禁止「优化登录」式宽泛描述。
+
 ### 阶段 1: 准备工作
 
-- [ ] 1.1 [填写：任务标题] — _需求: [填写：FR-n]_ ｜ _设计: [填写：章节]_
+- [ ] 1.1 [填写：动词+对象+约束]
+  - 证据块: [填写：动手前需读的文件:行号]
+  - 文件: [填写：路径]（预算 [填写] 行，超 500 行拆分）
+  - _需求: [填写：FR-n]_ · _设计: [填写：章节]_
 
 ---
 
 ### 阶段 2: 核心实现
 
-- [ ] 2.1 [填写：任务标题] — _需求: [填写：FR-n]_ ｜ _设计: [填写：章节]_
-- [ ] 2.2 [填写：任务标题] — _需求: [填写：FR-n]_ ｜ _设计: [填写：章节]_
+- [ ] 2.1 [填写：动词+对象+约束]
+  - 证据块: [填写：文件:行号]
+  - 文件: [填写：路径]（预算 [填写] 行）
+  - _需求: [填写：FR-n]_ · _设计: [填写：章节]_
+- [ ] 2.2 [填写：动词+对象+约束]
+  - 证据块: [填写：文件:行号]
+  - 文件: [填写：路径]（预算 [填写] 行）
+  - _需求: [填写：FR-n]_ · _设计: [填写：章节]_
 
 ---
 
 ### 阶段 3: 集成测试
 
-- [ ] 3.1 [填写：任务标题（对照验收标准核验）] — _需求: [填写：FR-n]_
+- [ ] 3.1 [填写：动词+对象+约束（对照验收标准逐条核验）]
+  - 验收点: [填写：对应哪条验收标准]
+  - _需求: [填写：FR-n]_
 
 ---
 
@@ -440,9 +492,17 @@ const EMBEDDED_TEMPLATES = {
 
 ## 文件变更清单
 
-| 文件 | 操作 | 说明 |
-|------|------|------|
-| [填写：文件路径] | 新建/修改 | [填写：说明] |
+| 文件 | 操作 | 行数预算 | 说明 |
+|------|------|----------|------|
+| [填写：文件路径] | 新建/修改 | [填写：≤500] | [填写：说明] |
+
+---
+
+## 交付前自检
+
+- [ ] 无占位符 / TODO / 省略注释
+- [ ] 交付物数量与 Scope-lock 一致
+- [ ] 每个文件 ≤ 500 行、每条任务回链 FR
 `,
 };
 export function normalizeTemplateProfile(input) {

package/build/lib/tool-annotations.js

@@ -15,6 +15,7 @@
 export const TOOL_ANNOTATIONS = {
     // —— 只读指南型（可安全自动放行）——
     init_project: { title: '初始化项目', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    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 },
     gentest: { title: '生成测试', readOnlyHint: true, idempotentHint: true, openWorldHint: false },
@@ -44,6 +45,8 @@ export const TOOL_ANNOTATIONS = {
     // —— 写型（工具自身落盘 / 写记忆 / 写缓存，非破坏）——
     init_project_context: { title: '生成项目上下文', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, // 自己写 docs/.mcp-probe/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
     sync_ui_data: { title: '同步 UI 数据', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }, // 下载 + 写缓存
 };
 /**

package/build/lib/toolset-manager.js

@@ -14,6 +14,7 @@ import { allToolSchemas } from '../schemas/index.js';
 export const TOOLSET_DEFINITIONS = {
     // 核心工具集 - 日常高频工具
     core: [
+        'workflow',
         'gencommit',
         'code_review',
         'code_insight',
@@ -35,6 +36,7 @@ export const TOOLSET_DEFINITIONS = {
     ],
     // 工作流工具集 - 包含核心 + 编排 + 交互
     workflow: [
+        'workflow',
         // 核心工具
         'gencommit',
         'code_review',

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

@@ -0,0 +1,38 @@
+export interface SkillEnsureResult {
+    skillPath: string;
+    skillRelPath: string;
+    existed: boolean;
+    created: boolean;
+    updated: boolean;
+    version: string;
+    previousVersion: string | null;
+}
+export interface AgentsMdEnsureResult {
+    path: string;
+    existed: boolean;
+    created: boolean;
+    updated: boolean;
+}
+export interface McpProbeKitBootstrapResult {
+    projectRoot: string;
+    skill: SkillEnsureResult;
+    agentsMd: AgentsMdEnsureResult;
+}
+export declare function resolveProjectRootFromToolArgs(args: unknown): string;
+/**
+ * 同步用户项目 Skill：缺失则创建；已安装版本落后于 kit 则覆盖升级。
+ */
+export declare function ensureMcpProbeSkill(projectRoot: string): SkillEnsureResult;
+/**
+ * 确保 AGENTS.md 存在且含 mcp-probe 块与 Skill 引用；无则创建，有则按版本合并更新。
+ */
+export declare function ensureAgentsMdSkillReference(projectRoot: string): AgentsMdEnsureResult;
+/**
+ * 任意 MCP 工具调用前的项目增强：安装 Skill + 同步 AGENTS.md 引用（始终开启）。
+ */
+export declare function ensureMcpProbeKitBootstrap(projectRoot: string): McpProbeKitBootstrapResult;
+export declare function ensureMcpProbeKitBootstrapForToolCall(_toolName: string, args: unknown): McpProbeKitBootstrapResult | null;
+/** @deprecated 使用 ensureMcpProbeKitBootstrap */
+export declare function ensureProjectWorkflowSkill(projectRoot: string): McpProbeKitBootstrapResult;
+/** @deprecated 使用 ensureMcpProbeKitBootstrapForToolCall */
+export declare function ensureWorkflowSkillForToolCall(toolName: string, args: unknown): McpProbeKitBootstrapResult | null;

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

@@ -0,0 +1,158 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+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 { isLikelyProjectNamedRelativePath, resolveWorkspaceRoot, } from "./workspace-root.js";
+function flattenToolArgs(args) {
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+        return {};
+    }
+    const base = args;
+    const nested = base.input && typeof base.input === "object" && !Array.isArray(base.input)
+        ? base.input
+        : {};
+    return { ...base, ...nested };
+}
+export function resolveProjectRootFromToolArgs(args) {
+    const record = flattenToolArgs(args);
+    const explicit = (typeof record.project_root === "string" ? record.project_root.trim() : "") ||
+        (typeof record.projectRoot === "string" ? record.projectRoot.trim() : "") ||
+        (typeof record.project_path === "string" ? record.project_path.trim() : "");
+    if (explicit && !isLikelyProjectNamedRelativePath(explicit)) {
+        return resolveWorkspaceRoot(explicit);
+    }
+    return resolveWorkspaceRoot("");
+}
+function buildAgentsMdInner(projectRoot, existingAgentsContent) {
+    const layout = resolveProjectContextLayout(projectRoot);
+    const locale = detectDocumentLocale(projectRoot, existingAgentsContent);
+    const graphReady = fs.existsSync(path.join(projectRoot, layout.latestMarkdownPath));
+    return generateAgentsMdInner({
+        layout,
+        locale,
+        projectName: path.basename(projectRoot),
+        projectVersion: "0.0.0",
+        description: "",
+        language: "",
+        category: "app",
+        docs: [],
+        projectRootPosix: toPosixPath(projectRoot),
+        graphReady,
+    });
+}
+function agentsMdNeedsUpdate(content, skillRelPath, targetVersion) {
+    if (!content?.trim()) {
+        return true;
+    }
+    if (!content.includes("mcp-probe:context")) {
+        return true;
+    }
+    if (content.includes(LEGACY_WORKFLOW_SKILL_REL_PATH)) {
+        return true;
+    }
+    if (!content.includes(skillRelPath)) {
+        return true;
+    }
+    if (agentsContextNeedsUpgrade(content, targetVersion)) {
+        return true;
+    }
+    return false;
+}
+function writeSkillFile(skillPath, version) {
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+    fs.writeFileSync(skillPath, generateWorkflowSkillContent(version), "utf8");
+}
+/**
+ * 同步用户项目 Skill：缺失则创建；已安装版本落后于 kit 则覆盖升级。
+ */
+export function ensureMcpProbeSkill(projectRoot) {
+    const root = path.resolve(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;
+    if (!skillContentNeedsUpgrade(existing, targetVersion)) {
+        return {
+            skillPath,
+            skillRelPath: MCP_PROBE_SKILL_REL_PATH,
+            existed: Boolean(existing?.trim()),
+            created: false,
+            updated: false,
+            version: targetVersion,
+            previousVersion,
+        };
+    }
+    writeSkillFile(skillPath, targetVersion);
+    const hadContent = Boolean(existing?.trim());
+    return {
+        skillPath,
+        skillRelPath: MCP_PROBE_SKILL_REL_PATH,
+        existed: hadContent,
+        created: !hadContent,
+        updated: hadContent,
+        version: targetVersion,
+        previousVersion,
+    };
+}
+/**
+ * 确保 AGENTS.md 存在且含 mcp-probe 块与 Skill 引用；无则创建，有则按版本合并更新。
+ */
+export function ensureAgentsMdSkillReference(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const layout = resolveProjectContextLayout(root);
+    const agentsPath = path.join(root, layout.indexPath);
+    const existing = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : null;
+    const targetVersion = getMcpProbeSkillVersion();
+    if (!agentsMdNeedsUpdate(existing, MCP_PROBE_SKILL_REL_PATH, targetVersion)) {
+        return {
+            path: layout.indexPath,
+            existed: Boolean(existing?.trim()),
+            created: false,
+            updated: false,
+        };
+    }
+    const inner = buildAgentsMdInner(root, existing ?? undefined);
+    const { content, mergeMode } = mergeAgentsMdBlock(existing, inner, targetVersion);
+    fs.mkdirSync(path.dirname(agentsPath), { recursive: true });
+    fs.writeFileSync(agentsPath, content, "utf8");
+    const hadContent = Boolean(existing?.trim());
+    return {
+        path: layout.indexPath,
+        existed: hadContent,
+        created: !hadContent,
+        updated: hadContent && mergeMode !== "skipped-empty",
+    };
+}
+/**
+ * 任意 MCP 工具调用前的项目增强：安装 Skill + 同步 AGENTS.md 引用（始终开启）。
+ */
+export function ensureMcpProbeKitBootstrap(projectRoot) {
+    const root = path.resolve(projectRoot);
+    return {
+        projectRoot: root,
+        skill: ensureMcpProbeSkill(root),
+        agentsMd: ensureAgentsMdSkillReference(root),
+    };
+}
+export function ensureMcpProbeKitBootstrapForToolCall(_toolName, args) {
+    try {
+        const projectRoot = resolveProjectRootFromToolArgs(args);
+        return ensureMcpProbeKitBootstrap(projectRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[MCP Probe Kit] mcp-probe-kit bootstrap failed: ${message}`);
+        return null;
+    }
+}
+/** @deprecated 使用 ensureMcpProbeKitBootstrap */
+export function ensureProjectWorkflowSkill(projectRoot) {
+    return ensureMcpProbeKitBootstrap(projectRoot);
+}
+/** @deprecated 使用 ensureMcpProbeKitBootstrapForToolCall */
+export function ensureWorkflowSkillForToolCall(toolName, args) {
+    return ensureMcpProbeKitBootstrapForToolCall(toolName, args);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 由 mcp-tool-skill-registry 生成 Skill 正文（勿在此硬编码工具表）。
+ * 本仓库 dogfood 文件由 `npm run sync-workflow-skill`（prebuild）自动写入。
+ */
+export declare const MCP_PROBE_SKILL_REL_PATH = ".agents/skills/mcp-probe-kit/SKILL.md";
+/** @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 function generateWorkflowSkillContent(skillVersion?: string): string;

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

@@ -0,0 +1,85 @@
+/**
+ * 由 mcp-tool-skill-registry 生成 Skill 正文（勿在此硬编码工具表）。
+ * 本仓库 dogfood 文件由 `npm run sync-workflow-skill`（prebuild）自动写入。
+ */
+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";
+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";
+function renderIntentQuickLookup() {
+    const rows = MCP_INTENT_QUICK_LOOKUP.map((entry) => `| ${entry.signal} | \`${entry.firstTool}\` |`).join("\n");
+    return `| 用户说什么 / 什么情况 | 第一个 MCP |
+|----------------------|------------|
+${rows}`;
+}
+function renderToolGroups() {
+    return MCP_TOOL_SKILL_GROUPS.map((group) => {
+        const rows = group.tools
+            .map((tool) => `| \`${tool.name}\` | ${tool.whenToCall} |`)
+            .join("\n");
+        const note = group.note ? `\n\n*${group.note}*` : "";
+        return `### ${group.title}
+
+| MCP | 何时调用 |
+|-----|----------|
+${rows}${note}`;
+    }).join("\n\n");
+}
+function renderCommonFlows() {
+    return MCP_SKILL_COMMON_FLOWS.map((flow) => `**${flow.label}**：\`${flow.chain}\``).join("\n\n");
+}
+function renderAvoidRules() {
+    return MCP_SKILL_AVOID_RULES.map((rule) => `- ${rule}`).join("\n");
+}
+export function generateWorkflowSkillBody(skillVersion = VERSION) {
+    return `# MCP 调用时机 — mcp-probe-kit
+
+> 本 Skill 只回答一件事：**什么情况 → 调哪个 MCP**。不是开发流程剧本。
+> 由 mcp-probe-kit 自动安装；Cursor 从 \`.agents/skills/\` 加载。
+
+## 总规则
+
+1. **先查下表**，有对应 MCP 就先调，再写代码 / 改文件
+2. **拿不准** → \`workflow\`：\`{ "intent": "<用户原话>" }\`
+3. \`start_*\` 会列出后续该调的 MCP；按返回逐步调用即可
+
+---
+
+## 意图速查（第一个该调的 MCP）
+
+${renderIntentQuickLookup()}
+
+---
+
+## 全工具：何时调用
+
+${renderToolGroups()}
+
+---
+
+## 常见链路（只是调用顺序参考）
+
+${renderCommonFlows()}
+
+---
+
+## 不要
+
+${renderAvoidRules()}
+
+---
+
+*mcp-probe-kit 按版本自动同步（当前 \`${skillVersion}\`）。路径：\`${MCP_PROBE_SKILL_REL_PATH}\`*
+`;
+}
+export function generateWorkflowSkillContent(skillVersion = VERSION) {
+    const versionMarker = formatSkillVersionMarker(skillVersion);
+    return `${versionMarker}
+
+${generateWorkflowSkillBody(skillVersion)}
+
+${versionMarker}
+`;
+}

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

@@ -0,0 +1,15 @@
+/** Skill 文件首行版本标记：`<!-- mcp-probe-kit-skill-version: 3.5.0 -->` */
+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";
+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;
+export declare function parseAgentsContextVersion(content: string): string | null;
+/** 比较 semver（仅主版本号段，忽略 prerelease 后缀） */
+export declare function compareSemver(a: string, b: string): number;
+/** 已安装 Skill 是否落后于当前 kit 版本（无标记视为过期） */
+export declare function skillContentNeedsUpgrade(existing: string | null | undefined, targetVersion?: string): boolean;
+/** AGENTS.md mcp-probe 块是否落后于当前 kit 版本 */
+export declare function agentsContextNeedsUpgrade(existing: string | null | undefined, targetVersion?: string): boolean;

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

@@ -0,0 +1,68 @@
+import { VERSION } from "../version.js";
+/** Skill 文件首行版本标记：`<!-- mcp-probe-kit-skill-version: 3.5.0 -->` */
+export const SKILL_VERSION_MARKER = "mcp-probe-kit-skill-version";
+/** AGENTS.md mcp-probe 块内版本标记 */
+export const AGENTS_CONTEXT_VERSION_MARKER = "mcp-probe:context-version";
+export function getMcpProbeSkillVersion() {
+    return VERSION;
+}
+export function formatSkillVersionMarker(version = VERSION) {
+    return `<!-- ${SKILL_VERSION_MARKER}: ${version} -->`;
+}
+export function formatAgentsContextVersionMarker(version = VERSION) {
+    return `<!-- ${AGENTS_CONTEXT_VERSION_MARKER}: ${version} -->`;
+}
+export function parseSkillVersionMarker(content) {
+    const pattern = new RegExp(`<!--\\s*${SKILL_VERSION_MARKER}:\\s*([^\\s>]+)\\s*-->`, "i");
+    const match = content.match(pattern);
+    return match?.[1]?.trim() ?? null;
+}
+export function parseAgentsContextVersion(content) {
+    const pattern = new RegExp(`<!--\\s*${AGENTS_CONTEXT_VERSION_MARKER}:\\s*([^\\s>]+)\\s*-->`, "i");
+    const match = content.match(pattern);
+    return match?.[1]?.trim() ?? null;
+}
+/** 比较 semver（仅主版本号段，忽略 prerelease 后缀） */
+export function compareSemver(a, b) {
+    const normalize = (value) => value
+        .trim()
+        .replace(/^v/i, "")
+        .split("-")[0]
+        .split(".")
+        .map((part) => {
+        const n = Number.parseInt(part, 10);
+        return Number.isFinite(n) ? n : 0;
+    });
+    const left = normalize(a);
+    const right = normalize(b);
+    const length = Math.max(left.length, right.length);
+    for (let i = 0; i < length; i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0) {
+            return diff > 0 ? 1 : -1;
+        }
+    }
+    return 0;
+}
+/** 已安装 Skill 是否落后于当前 kit 版本（无标记视为过期） */
+export function skillContentNeedsUpgrade(existing, targetVersion = VERSION) {
+    if (!existing?.trim()) {
+        return true;
+    }
+    const installed = parseSkillVersionMarker(existing);
+    if (!installed) {
+        return true;
+    }
+    return compareSemver(installed, targetVersion) < 0;
+}
+/** AGENTS.md mcp-probe 块是否落后于当前 kit 版本 */
+export function agentsContextNeedsUpgrade(existing, targetVersion = VERSION) {
+    if (!existing?.trim()) {
+        return true;
+    }
+    const installed = parseAgentsContextVersion(existing);
+    if (!installed) {
+        return true;
+    }
+    return compareSemver(installed, targetVersion) < 0;
+}