mcp-probe-kit 3.2.0 → 3.6.0

package/build/lib/__tests__/quality-constraints.unit.test.js

@@ -0,0 +1,54 @@
+import { describe, test, expect } from 'vitest';
+import { CODE_LIMITS, BANNED_CODE_PATTERNS, UI_HARD_RULES, UI_BANNED_LIST, renderCodeLimits, renderBannedPatterns, renderUiHardRules, renderUiBannedList, renderPreFlightChecklist, } from '../quality-constraints.js';
+describe('quality-constraints（质量约束单一真相源）', () => {
+    test('CODE_LIMITS 数值符合预期（单文件 500 / 函数 50）', () => {
+        expect(CODE_LIMITS.maxFileLines).toBe(500);
+        expect(CODE_LIMITS.maxFunctionLines).toBe(50);
+        expect(CODE_LIMITS.maxNestingDepth).toBe(4);
+        expect(CODE_LIMITS.maxParameters).toBe(3);
+    });
+    test('黑名单与硬约束清单非空', () => {
+        expect(BANNED_CODE_PATTERNS.length).toBeGreaterThan(0);
+        expect(UI_HARD_RULES.length).toBeGreaterThan(0);
+        expect(UI_BANNED_LIST.length).toBeGreaterThan(0);
+    });
+    test('代码完整性黑名单含关键占位模式', () => {
+        expect(BANNED_CODE_PATTERNS).toContain('// TODO');
+        expect(BANNED_CODE_PATTERNS).toContain('// ...');
+    });
+    test('UI 黑名单含 em-dash 零容忍与 AI 紫蓝渐变', () => {
+        expect(UI_BANNED_LIST.some((b) => b.includes('em-dash'))).toBe(true);
+        expect(UI_BANNED_LIST.some((b) => b.includes('紫蓝渐变'))).toBe(true);
+    });
+    test('renderCodeLimits 输出含 500 行红线', () => {
+        const out = renderCodeLimits();
+        expect(out).toContain('500');
+        expect(out).toContain('HIGH');
+    });
+    test('renderBannedPatterns 输出含 CRITICAL 与二元规则', () => {
+        const out = renderBannedPatterns();
+        expect(out).toContain('CRITICAL');
+        expect(out).toContain('二元');
+    });
+    test('renderUiHardRules 含 4pt 间距阶梯与对比度阈值', () => {
+        const out = renderUiHardRules();
+        expect(out).toContain('4, 8, 12, 16, 24, 32, 48, 64, 96');
+        expect(out).toContain('4.5:1');
+    });
+    test('renderUiBannedList 输出每条以 ❌ 标记', () => {
+        const out = renderUiBannedList();
+        expect(out).toContain('❌');
+    });
+    test('renderPreFlightChecklist 含 Scope-lock 与完整性勾选项', () => {
+        const out = renderPreFlightChecklist();
+        expect(out).toContain('Pre-Flight');
+        expect(out).toContain('Scope-lock');
+        expect(out).toContain('占位符');
+    });
+    // 防回归：注入下游 prompt 的渲染输出自身不得含 em-dash，否则与「em-dash 零容忍」自相矛盾
+    test('代码类渲染输出不含 em-dash（避免规则自相矛盾）', () => {
+        expect(renderCodeLimits()).not.toContain('—');
+        expect(renderBannedPatterns()).not.toContain('—');
+        expect(renderPreFlightChecklist()).not.toContain('—');
+    });
+});

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__/spec-validator.unit.test.js

@@ -1,75 +1,81 @@
 import { describe, test, expect } from 'vitest';
 import { validateSpecDocuments, extractFrIds } from '../spec-validator.js';
-const goodReq = `# 需求文档：demo
-
-## 功能概述
-做一个登录功能。
-
-## 历史经验与坑（来自记忆库）
-- 可复用经验: 无
-- 必须规避的坑: 无
-
-## 范围边界
-In Scope: 登录
-Out of Scope: 注册
-
-## 需求列表
-### FR-1: 登录
-**优先级:** Must
-**用户故事:** 作为用户，我想登录，以便访问系统。
-#### 验收标准（EARS）
-1. WHEN 提交正确凭证 THEN 系统 SHALL 登录成功
-
-## 非功能需求
-- NFR-1: 登录响应 < 1s
-
-## 依赖关系
-- 无
+const goodReq = `# 需求文档：demo
+
+## 功能概述
+做一个登录功能。
+
+## 历史经验与坑（来自记忆库）
+- 可复用经验: 无
+- 必须规避的坑: 无
+
+## 范围边界
+In Scope: 登录
+Out of Scope: 注册
+
+## 需求列表
+### FR-1: 登录
+**优先级:** Must
+**用户故事:** 作为用户，我想登录，以便访问系统。
+#### 验收标准（EARS）
+1. WHEN 提交正确凭证 THEN 系统 SHALL 登录成功
+
+## 非功能需求
+- NFR-1: 登录响应 < 1s
+
+## 依赖关系
+- 无
 `;
-const goodDesign = `# 设计文档：demo
-
-## 概述
-登录设计。
-**对应需求:** FR-1
-
-## 技术方案
-### 技术选型
-使用 JWT。
-
-## 数据模型
-不涉及。
-
-## API 设计
-POST /api/login
-
-## 文件结构
-src/login.ts
-
-## 设计决策
-决策 1：用 JWT。
-
-## 风险评估
-无。
+const goodDesign = `# 设计文档：demo
+
+## 概述
+登录设计。
+**对应需求:** FR-1
+
+## 技术方案
+### 技术选型
+使用 JWT。
+
+## 数据模型
+不涉及。
+
+## API 设计
+POST /api/login
+
+## 文件结构
+src/login.ts
+
+## 设计决策
+决策 1：用 JWT。
+
+## 风险评估
+无。
 `;
-const goodTasks = `# 任务清单：demo
-
-## 概述
-任务分解。
-
-## 任务列表
-### 阶段 2: 核心实现
-- [ ] 2.1 实现登录接口 — _需求: FR-1_ ｜ _设计: API 设计_
-
-## 检查点
-- [ ] 阶段 2 完成后：登录可用
-
-## 需求覆盖矩阵
-| 需求 ID | 设计章节 | 任务编号 | 状态 |
-| FR-1 | API 设计 | 2.1 | 未开始 |
-
-## 文件变更清单
-| 文件 | 操作 | 说明 |
-| src/login.ts | 新建 | 登录接口 |
+const goodTasks = `# 任务清单：demo
+
+## 概述
+任务分解。
+
+## 交付物清单（Scope-lock）
+- 预计新建文件数: 1 个
+- 预计修改文件数: 0 个
+
+## 任务列表
+### 阶段 2: 核心实现
+- [ ] 2.1 实现登录接口 POST /api/login，校验邮箱并返回 JWT
+  - 证据块: 先读 src/router.ts:1，确认路由注册方式
+  - _需求: FR-1_ ｜ _设计: API 设计_
+
+## 检查点
+- [ ] 阶段 2 完成后：登录可用
+
+## 需求覆盖矩阵
+| 需求 ID | 设计章节 | 任务编号 | 状态 |
+| FR-1 | API 设计 | 2.1 | 未开始 |
+
+## 文件变更清单
+| 文件 | 操作 | 说明 |
+| src/login.ts | 新建 | 登录接口 |
 `;
 describe('spec-validator（P1 填写后校验）', () => {
     test('完整规格通过校验', () => {
@@ -98,12 +104,12 @@ describe('spec-validator（P1 填写后校验）', () => {
         expect(r.issues.some((i) => i.code === 'no_acceptance')).toBe(true);
     });
     test('FR 未进 tasks 覆盖矩阵 → 跨文档未覆盖', () => {
-        const reqTwoFr = goodReq.replace('## 非功能需求', `### FR-2: 登出
-**优先级:** Should
-**用户故事:** 作为用户，我想登出。
-#### 验收标准（EARS）
-1. WHEN 点击登出 THEN 系统 SHALL 退出登录
-
+        const reqTwoFr = goodReq.replace('## 非功能需求', `### FR-2: 登出
+**优先级:** Should
+**用户故事:** 作为用户，我想登出。
+#### 验收标准（EARS）
+1. WHEN 点击登出 THEN 系统 SHALL 退出登录
+
 ## 非功能需求`);
         const r = validateSpecDocuments({ requirements: reqTwoFr, design: goodDesign, tasks: goodTasks });
         expect(r.passed).toBe(false);
@@ -112,4 +118,30 @@ describe('spec-validator（P1 填写后校验）', () => {
     test('extractFrIds 去重并保序', () => {
         expect(extractFrIds('FR-1 写了 FR-1 又写 FR-2')).toEqual(['FR-1', 'FR-2']);
     });
+    test('tasks 缺少「交付物清单」章节 → 未通过', () => {
+        const tasksNoScope = goodTasks.replace(/## 交付物清单（Scope-lock）[\s\S]*?\n\n/, '');
+        // 防 fixture 漂移导致替换失效造成假通过
+        expect(tasksNoScope).not.toContain('交付物清单');
+        const r = validateSpecDocuments({ requirements: goodReq, design: goodDesign, tasks: tasksNoScope });
+        expect(r.passed).toBe(false);
+        expect(r.issues.some((i) => i.file === 'tasks' && i.code === 'missing_section')).toBe(true);
+    });
+    test('任务无「证据块」→ thin_task 提醒（warning，不阻断）', () => {
+        const tasksThin = goodTasks.replace('  - 证据块: 先读 src/router.ts:1，确认路由注册方式\n', '');
+        expect(tasksThin).not.toBe(goodTasks);
+        const r = validateSpecDocuments({ requirements: goodReq, design: goodDesign, tasks: tasksThin });
+        expect(r.issues.some((i) => i.code === 'thin_task')).toBe(true);
+        expect(r.warningCount).toBeGreaterThan(0);
+        // 核心语义：thin_task 是 warning，不应阻断 passed
+        expect(r.passed).toBe(true);
+    });
+    test('裸 [填写] 占位（无冒号）也应被检出', () => {
+        const r = validateSpecDocuments({
+            requirements: goodReq + '\n- 备注: [填写]',
+            design: goodDesign,
+            tasks: goodTasks,
+        });
+        expect(r.passed).toBe(false);
+        expect(r.issues.some((i) => i.file === 'requirements' && i.code === 'placeholder')).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/agents-md-template.js

@@ -1,21 +1,26 @@
 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);
 }
 function memorySection(locale) {
     if (locale === "zh-CN") {
-        return `
-记忆（需 MEMORY_QDRANT_URL 等已配置）：
-- 检索：\`start_*\` 命中后**自动注入**历史经验全文；中途补查可用 \`search_memory\`；单条精读仍可用 \`read_memory_asset\`
-- 沉淀：跨仓库共享**勿填** source_project/source_path；路径写进 content；summary 写检索关键词
-- Bug 修完验证通过 → **必须** \`memorize_asset\` type=\`bugfix\` tags=\`bugfix,root-cause\`（content 含【现象】【根因】【修复】【验证】）
+        return `
+记忆（需 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\``;
     }
-    return `
-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
-- After verified bugfix → MUST \`memorize_asset\` type=\`bugfix\` (sections: symptom, root cause, fix, verification)
+    return `
+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,31 +30,34 @@ 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，逐步执行完再结束。
-
-- 新功能 → \`start_feature\`（会先搜记忆）
-- Bug → \`start_bugfix\`（会先搜记忆）
-- UI → \`start_ui\`（会先搜记忆）
-- 不熟代码 / 影响面 → \`code_insight\`（context / impact / auto）
-- 缺上下文 → \`init_project_context\`
-- 提交 → \`gencommit\`
-
-上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）
+        return `## MCP（必须先调）
+需已配置 mcp-probe-kit。写代码前先读 Skill：[MCP 调用时机](${skillLink})（\`${MCP_PROBE_SKILL_REL_PATH}\`，首次 MCP 调用自动创建）。
+
+- 不确定用哪个 MCP → \`workflow\`（返回 firstTool）
+- 新功能 → \`start_feature\`（会先搜记忆）
+- Bug → \`start_bugfix\`（会先搜记忆）
+- UI → \`start_ui\`（会先搜记忆）
+- 不熟代码 / 影响面 → \`code_insight\`（context / impact / auto）
+- 缺上下文 → \`init_project_context\`
+- 提交 → \`gencommit\`
+
+上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）
 图谱：大改前读 [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.
-
-- Feature → \`start_feature\` (searches memory first)
-- Bug → \`start_bugfix\` (searches memory first)
-- UI → \`start_ui\` (searches memory first)
-- Unfamiliar code / impact → \`code_insight\` (context / impact / auto)
-- Missing context → \`init_project_context\`
-- Commit → \`gencommit\`
-
-Context: before coding read [project-context](${ctxIndex}) (links to \`${layout.modularDir}/\`)
+    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).
+
+- Unsure which MCP → \`workflow\` (returns firstTool)
+- Feature → \`start_feature\` (searches memory first)
+- Bug → \`start_bugfix\` (searches memory first)
+- UI → \`start_ui\` (searches memory first)
+- Unfamiliar code / impact → \`code_insight\` (context / impact / auto)
+- 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)}`;
 }
 export function generateAgentsMdTemplate(input) {

package/build/lib/cursor-history-client.d.ts

@@ -0,0 +1,54 @@
+export interface CursorConversationSummary {
+    composerId: string;
+    name: string;
+    createdAt?: number;
+    lastUpdatedAt?: number;
+    workspaceId?: string;
+    workspacePath?: string;
+    mode?: string;
+    contextUsagePercent?: number;
+    subtitle?: string;
+    isArchived?: boolean;
+    source: 'composerHeaders';
+}
+export interface CursorConversationMessage {
+    bubbleId: string;
+    type: number;
+    text: string;
+    createdAt?: string;
+    requestId?: string;
+}
+export interface CursorConversationDetail {
+    composerId: string;
+    messages: CursorConversationMessage[];
+}
+export interface CursorHistorySearchResult {
+    composerId: string;
+    conversationName: string;
+    bubbleId: string;
+    type: number;
+    text: string;
+    createdAt?: string;
+    requestId?: string;
+}
+export declare class CursorHistoryClient {
+    private withDatabase;
+    private loadConversationIndex;
+    listConversations(params?: {
+        titleQuery?: string;
+        workspaceQuery?: string;
+        includeArchived?: boolean;
+        limit?: number;
+    }): Promise<CursorConversationSummary[]>;
+    searchHistory(params: {
+        query: string;
+        composerId?: string;
+        limit?: number;
+    }): Promise<CursorHistorySearchResult[]>;
+    readConversation(params: {
+        composerId: string;
+        limit?: number;
+        includeEmpty?: boolean;
+    }): Promise<CursorConversationDetail>;
+}
+export declare function createCursorHistoryClient(): CursorHistoryClient;