mcp-probe-kit 3.3.0 → 3.6.1

package/build/lib/__tests__/mcp-tool-skill-registry.unit.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { allToolSchemas } from "../../schemas/index.js";
+import { formatSkillRegistryMismatchMessage, listMcpToolSkillRegistryNames, validateMcpToolSkillRegistry, } from "../mcp-tool-skill-registry.js";
+import { generateWorkflowSkillContent } from "../workflow-skill-template.js";
+describe("mcp-tool-skill-registry", () => {
+    it("与 allToolSchemas 工具名一一对应", () => {
+        const registered = allToolSchemas.map((tool) => tool.name).sort();
+        const result = validateMcpToolSkillRegistry(registered);
+        expect(result.ok, formatSkillRegistryMismatchMessage(result)).toBe(true);
+        expect(listMcpToolSkillRegistryNames().length).toBe(registered.length);
+    });
+    it("生成的 Skill 正文包含每个注册工具", () => {
+        const content = generateWorkflowSkillContent("0.0.0-test");
+        for (const name of listMcpToolSkillRegistryNames()) {
+            expect(content).toContain(`\`${name}\``);
+        }
+    });
+});

package/build/lib/__tests__/memory-client.unit.test.js

@@ -80,4 +80,109 @@ describe('memory-client 去重逻辑', () => {
         expect(result.normalizedContentHash).toBe(existingAsset.normalizedContentHash);
         expect(fetchMock.mock.calls.some(([url]) => String(url).includes('/points?wait=true'))).toBe(false);
     });
+    test('deleteAsset 删除已存在资产并返回快照', async () => {
+        vi.stubEnv('MEMORY_QDRANT_URL', 'http://127.0.0.1:50008');
+        const asset = {
+            id: 'asset-to-delete',
+            name: 'ObsoletePattern',
+            type: 'pattern',
+            description: '过时模式',
+            summary: '不再使用',
+            content: 'old snippet',
+            tags: ['pattern'],
+            confidence: 0.7,
+            createdAt: '2026-01-01T00:00:00.000Z',
+            updatedAt: '2026-01-01T00:00:00.000Z',
+        };
+        const fetchMock = vi.fn(async (input, init) => {
+            const url = String(input);
+            if (url.includes(`/points/${asset.id}`) && init?.method !== 'POST' && init?.method !== 'PUT') {
+                return new Response(JSON.stringify({ result: { payload: asset } }), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            if (url.includes('/points/delete')) {
+                return new Response(JSON.stringify({ status: 'ok' }), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            throw new Error(`unexpected fetch: ${url}`);
+        });
+        globalThis.fetch = fetchMock;
+        const client = new MemoryClient();
+        const result = await client.deleteAsset(asset.id);
+        expect(result.deleted).toBe(true);
+        expect(result.asset?.name).toBe('ObsoletePattern');
+        expect(fetchMock.mock.calls.some(([url, init]) => String(url).includes('/points/delete') && init?.method === 'POST')).toBe(true);
+    });
+    test('deleteAsset 对不存在的资产返回 deleted=false', async () => {
+        vi.stubEnv('MEMORY_QDRANT_URL', 'http://127.0.0.1:50008');
+        const fetchMock = vi.fn(async (input) => {
+            const url = String(input);
+            if (url.includes('/points/missing-id')) {
+                return new Response(JSON.stringify({ result: null }), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            throw new Error(`unexpected fetch: ${url}`);
+        });
+        globalThis.fetch = fetchMock;
+        const client = new MemoryClient();
+        const result = await client.deleteAsset('missing-id');
+        expect(result.deleted).toBe(false);
+        expect(result.asset).toBeNull();
+    });
+    test('updateAsset 更新已存在资产并保留 createdAt', async () => {
+        vi.stubEnv('MEMORY_QDRANT_URL', 'http://127.0.0.1:50008');
+        vi.stubEnv('MEMORY_EMBEDDING_URL', 'http://127.0.0.1:11434/api/embeddings');
+        vi.stubEnv('MEMORY_EMBEDDING_MODEL', 'nomic-embed-text');
+        const asset = {
+            id: 'asset-to-update',
+            name: 'PatternA',
+            type: 'pattern',
+            description: '旧描述',
+            summary: '旧摘要',
+            content: 'old snippet',
+            tags: ['pattern'],
+            confidence: 0.7,
+            createdAt: '2026-01-01T00:00:00.000Z',
+            updatedAt: '2026-01-01T00:00:00.000Z',
+        };
+        const fetchMock = vi.fn(async (input, init) => {
+            const url = String(input);
+            if (url.endsWith('/api/embeddings')) {
+                return new Response(JSON.stringify({ embedding: [0.1, 0.2, 0.3] }), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            if (url.includes(`/points/${asset.id}`) && init?.method !== 'POST' && init?.method !== 'PUT') {
+                return new Response(JSON.stringify({ result: { payload: asset } }), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            if (url.endsWith('/collections/mcp_probe_memory') && !init?.method) {
+                return new Response('', { status: 200 });
+            }
+            if (url.includes('/points?wait=true') && init?.method === 'PUT') {
+                return new Response(JSON.stringify({ status: 'ok' }), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            throw new Error(`unexpected fetch: ${url}`);
+        });
+        globalThis.fetch = fetchMock;
+        const client = new MemoryClient();
+        const result = await client.updateAsset(asset.id, { summary: '新摘要' });
+        expect(result.updated).toBe(true);
+        expect(result.asset?.summary).toBe('新摘要');
+        expect(result.asset?.createdAt).toBe(asset.createdAt);
+        expect(result.asset?.id).toBe(asset.id);
+        expect(fetchMock.mock.calls.some(([url, init]) => String(url).includes('/points?wait=true') && init?.method === 'PUT')).toBe(true);
+    });
 });

package/build/lib/__tests__/spec-gate.unit.test.d.ts

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

package/build/lib/__tests__/spec-gate.unit.test.js

@@ -0,0 +1,54 @@
+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 { resolveBugfixFeatureName, resolveBugfixSpecGate, specArtifactsExist, } from '../spec-gate.js';
+const tempDirs = [];
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+function makeSpecTree(featureName) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'spec-gate-'));
+    tempDirs.push(root);
+    const specDir = path.join(root, 'docs', 'specs', featureName);
+    fs.mkdirSync(specDir, { recursive: true });
+    fs.writeFileSync(path.join(specDir, 'requirements.md'), '# requirements\n');
+    return root;
+}
+describe('spec-gate', () => {
+    test('显式 feature_name 优先', () => {
+        const root = makeSpecTree('user-auth');
+        expect(resolveBugfixFeatureName('payment', root, 'docs', 'user-auth login failed')).toBe('payment');
+    });
+    test('仅一个 spec 目录时自动识别', () => {
+        const root = makeSpecTree('only-feature');
+        expect(resolveBugfixFeatureName('', root, 'docs', 'random error')).toBe('only-feature');
+    });
+    test('错误描述唯一匹配 spec 目录', () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'spec-gate-'));
+        tempDirs.push(root);
+        for (const name of ['user-auth', 'billing']) {
+            const specDir = path.join(root, 'docs', 'specs', name);
+            fs.mkdirSync(specDir, { recursive: true });
+            fs.writeFileSync(path.join(specDir, 'tasks.md'), '# tasks\n');
+        }
+        expect(resolveBugfixFeatureName('', root, 'docs', 'billing invoice total mismatch')).toBe('billing');
+    });
+    test('resolveBugfixSpecGate 在规格存在时返回上下文', () => {
+        const root = makeSpecTree('checkout-flow');
+        const gate = resolveBugfixSpecGate({
+            featureName: 'checkout-flow',
+            projectRoot: root,
+            docsDir: 'docs',
+            hintText: 'checkout failed',
+        });
+        expect(gate?.featureName).toBe('checkout-flow');
+        expect(gate?.specDir).toBe('docs/specs/checkout-flow');
+        expect(specArtifactsExist(root, 'docs', 'checkout-flow')).toBe(true);
+    });
+});

package/build/lib/__tests__/task-defaults.unit.test.d.ts

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

package/build/lib/__tests__/task-defaults.unit.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, test, afterEach } from 'vitest';
+import { isAutoTaskTool, shouldAutoEscalateToTask } from '../task-defaults.js';
+const originalDisable = process.env.MCP_DISABLE_AUTO_TASK;
+afterEach(() => {
+    if (originalDisable === undefined) {
+        delete process.env.MCP_DISABLE_AUTO_TASK;
+    }
+    else {
+        process.env.MCP_DISABLE_AUTO_TASK = originalDisable;
+    }
+});
+describe('task-defaults', () => {
+    test('code_insight 与 scan 属于自动 Task 工具', () => {
+        expect(isAutoTaskTool('code_insight')).toBe(true);
+        expect(isAutoTaskTool('scan_and_extract_patterns')).toBe(true);
+        expect(isAutoTaskTool('search_memory')).toBe(false);
+    });
+    test('默认对长耗时工具自动升级为 Task', () => {
+        delete process.env.MCP_DISABLE_AUTO_TASK;
+        expect(shouldAutoEscalateToTask('code_insight', false)).toBe(true);
+        expect(shouldAutoEscalateToTask('code_insight', true)).toBe(false);
+    });
+    test('MCP_DISABLE_AUTO_TASK=1 时关闭自动 Task', () => {
+        process.env.MCP_DISABLE_AUTO_TASK = '1';
+        expect(shouldAutoEscalateToTask('code_insight', false)).toBe(false);
+    });
+});

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

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

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/__tests__/workspace-root.unit.test.d.ts

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

package/build/lib/__tests__/workspace-root.unit.test.js

@@ -0,0 +1,31 @@
+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 { resolveFromWorkspaceFolderPathsEnv, resolveWorkspaceRoot, } from "../workspace-root.js";
+const original = process.env.WORKSPACE_FOLDER_PATHS;
+const tempDirs = [];
+afterEach(() => {
+    if (original === undefined) {
+        delete process.env.WORKSPACE_FOLDER_PATHS;
+    }
+    else {
+        process.env.WORKSPACE_FOLDER_PATHS = original;
+    }
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("workspace-root WORKSPACE_FOLDER_PATHS", () => {
+    test("解析 JSON 数组形式", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "ws-"));
+        tempDirs.push(root);
+        fs.writeFileSync(path.join(root, "package.json"), "{}", "utf8");
+        process.env.WORKSPACE_FOLDER_PATHS = JSON.stringify([root]);
+        expect(resolveFromWorkspaceFolderPathsEnv()).toBe(path.resolve(root));
+        expect(resolveWorkspaceRoot("")).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;