mcp-probe-kit 3.3.0 → 3.6.0

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

@@ -0,0 +1,110 @@
+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 { 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 { wrapMcpProbeBlock } from "../merge-agents-md.js";
+const tempDirs = [];
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("workflow-skill-version", () => {
+    test("compareSemver 比较主次补丁", () => {
+        expect(compareSemver("3.5.0", "3.5.1")).toBeLessThan(0);
+        expect(compareSemver("3.6.0", "3.5.9")).toBeGreaterThan(0);
+        expect(compareSemver("3.5.0", "3.5.0")).toBe(0);
+    });
+    test("无版本标记视为需要升级", () => {
+        expect(skillContentNeedsUpgrade("# custom", VERSION)).toBe(true);
+        expect(agentsContextNeedsUpgrade("<!-- mcp-probe:context begin -->", VERSION)).toBe(true);
+    });
+});
+describe("workflow-skill-installer", () => {
+    test("缺失时创建 mcp-probe-kit Skill", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        const result = ensureMcpProbeSkill(root);
+        expect(result.created).toBe(true);
+        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("MCP 调用时机");
+    });
+    test("同版本 Skill 不覆盖", () => {
+        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 = `${formatSkillVersionMarker(VERSION)}\n# same version\n`;
+        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 会升级覆盖", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        const skillPath = path.join(root, MCP_PROBE_SKILL_REL_PATH);
+        fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+        fs.writeFileSync(skillPath, `${formatSkillVersionMarker("0.1.0")}\n# stale tools list\n`, "utf8");
+        const result = ensureMcpProbeSkill(root);
+        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("何时调用");
+        expect(text).not.toContain("stale tools list");
+    });
+    test("无 AGENTS.md 时创建并引用 Skill", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        const result = ensureAgentsMdSkillReference(root);
+        expect(result.created).toBe(true);
+        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);
+    });
+    test("已有 AGENTS.md 但缺 Skill 引用时更新", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        fs.writeFileSync(path.join(root, "AGENTS.md"), "# Custom rules\n", "utf8");
+        const result = ensureAgentsMdSkillReference(root);
+        expect(result.updated).toBe(true);
+        const agents = fs.readFileSync(path.join(root, "AGENTS.md"), "utf8");
+        expect(agents).toContain("# Custom rules");
+        expect(agents).toContain(MCP_PROBE_SKILL_REL_PATH);
+    });
+    test("旧 workflow Skill 路径会触发 AGENTS.md 更新", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        const legacyBlock = wrapMcpProbeBlock(`## MCP\nSee [skill](${LEGACY_WORKFLOW_SKILL_REL_PATH})`, "0.1.0");
+        fs.writeFileSync(path.join(root, "AGENTS.md"), `${legacyBlock}\n`, "utf8");
+        const result = ensureAgentsMdSkillReference(root);
+        expect(result.updated).toBe(true);
+        const agents = fs.readFileSync(path.join(root, "AGENTS.md"), "utf8");
+        expect(agents).toContain(MCP_PROBE_SKILL_REL_PATH);
+        expect(agents).toContain(`mcp-probe:context-version: ${VERSION}`);
+    });
+    test("bootstrap 同时处理 Skill 与 AGENTS.md", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        const result = ensureMcpProbeKitBootstrap(root);
+        expect(result.skill.created).toBe(true);
+        expect(result.agentsMd.created).toBe(true);
+    });
+    test("从 tool args 解析 project_root", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "wf-skill-"));
+        tempDirs.push(root);
+        expect(resolveProjectRootFromToolArgs({ project_root: root })).toBe(path.resolve(root));
+    });
+});

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

@@ -1,4 +1,5 @@
 import { relativeLink } from "./project-context-layout.js";
+import { MCP_PROBE_SKILL_REL_PATH } from "./workflow-skill-template.js";
 function link(layout, targetRel) {
     return relativeLink(layout.indexPath, targetRel);
 }
@@ -8,6 +9,8 @@ function memorySection(locale) {
 记忆（需 MEMORY_QDRANT_URL 等已配置）：
 - 检索：\`start_*\` 命中后**自动注入**历史经验全文；中途补查可用 \`search_memory\`；单条精读仍可用 \`read_memory_asset\`
 - 沉淀：跨仓库共享**勿填** source_project/source_path；路径写进 content；summary 写检索关键词
+- 修正：已有资产可用 \`update_memory_asset\` 按 asset_id 原地更新（保留 ID）
+- 清理：过时/错误/重复沉淀可用 \`delete_memory_asset\`（删除前建议 \`read_memory_asset\` 确认）
 - Bug 修完验证通过 → **必须** \`memorize_asset\` type=\`bugfix\` tags=\`bugfix,root-cause\`（content 含【现象】【根因】【修复】【验证】）
 - 功能/UI 可复用产出 → \`memorize_asset\` type=\`pattern\`/\`component\``;
     }
@@ -15,6 +18,8 @@ function memorySection(locale) {
 Memory (requires MEMORY_* env):
 - Search: \`start_*\` auto-injects full memory hits; use \`search_memory\` mid-task; \`read_memory_asset\` for a specific id
 - Store: do NOT use source_project/source_path for cross-repo pools; put paths in content; write keyword-rich summary
+- Update: fix existing entries in place with \`update_memory_asset\` by asset_id (preserves ID)
+- Cleanup: remove stale/wrong/duplicate entries with \`delete_memory_asset\` (confirm via \`read_memory_asset\` first)
 - After verified bugfix → MUST \`memorize_asset\` type=\`bugfix\` (sections: symptom, root cause, fix, verification)
 - Reusable feature/UI → \`memorize_asset\` type=\`pattern\`/\`component\``;
 }
@@ -25,10 +30,12 @@ export function generateAgentsMdInner(input) {
     const { layout, locale } = input;
     const graph = link(layout, layout.latestMarkdownPath);
     const ctxIndex = link(layout, layout.legacyIndexPath);
+    const skillLink = link(layout, MCP_PROBE_SKILL_REL_PATH);
     if (locale === "zh-CN") {
         return `## MCP（必须先调）
-需已配置 mcp-probe-kit。\`start_*\` 若返回 delegated plan，逐步执行完再结束。
+需已配置 mcp-probe-kit。写代码前先读 Skill：[MCP 调用时机](${skillLink})（\`${MCP_PROBE_SKILL_REL_PATH}\`，首次 MCP 调用自动创建）。
 
+- 不确定用哪个 MCP → \`workflow\`（返回 firstTool）
 - 新功能 → \`start_feature\`（会先搜记忆）
 - Bug → \`start_bugfix\`（会先搜记忆）
 - UI → \`start_ui\`（会先搜记忆）
@@ -40,8 +47,9 @@ export function generateAgentsMdInner(input) {
 图谱：大改前读 [latest](${graph})；过期 \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
     }
     return `## MCP (call first)
-Requires mcp-probe-kit. Complete every \`start_*\` delegated plan step before done.
+Requires mcp-probe-kit. Before coding, read Skill: [When to call MCP](${skillLink}) (\`${MCP_PROBE_SKILL_REL_PATH}\`, auto-created on first MCP call).
 
+- Unsure which MCP → \`workflow\` (returns firstTool)
 - Feature → \`start_feature\` (searches memory first)
 - Bug → \`start_bugfix\` (searches memory first)
 - UI → \`start_ui\` (searches memory first)

package/build/lib/dev-workflow.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 开发工作流路由：根据用户意图生成「何时调哪个 MCP 工具」的委托式指南。
+ * 解决 Agent 直接写代码、跳过 start_* / code_insight / check_spec 的问题。
+ */
+export type WorkflowScenario = 'feature' | 'bugfix' | 'ui' | 'explore' | 'commit' | 'review' | 'refactor' | 'onboard' | 'spec' | 'memory' | 'unknown';
+export interface WorkflowToolStep {
+    tool: string;
+    required: boolean;
+    when: string;
+    note?: string;
+}
+export interface WorkflowPhase {
+    id: string;
+    title: string;
+    when: string;
+    steps: WorkflowToolStep[];
+}
+export interface DevWorkflowPlan {
+    scenario: WorkflowScenario;
+    scenarioLabel: string;
+    confidence: 'high' | 'medium' | 'low';
+    summary: string;
+    firstTool: string;
+    firstToolArgsHint?: Record<string, unknown>;
+    phases: WorkflowPhase[];
+    avoid: string[];
+    memoryNotes: string[];
+}
+export declare function detectWorkflowScenario(intent: string, explicit?: string): {
+    scenario: WorkflowScenario;
+    confidence: 'high' | 'medium' | 'low';
+};
+export declare function buildDevWorkflow(intent: string, options?: {
+    scenario?: string;
+}): DevWorkflowPlan;
+export declare function renderWorkflowMarkdown(plan: DevWorkflowPlan, intent: string): string;