mcp-probe-kit 3.1.0 → 3.2.0

package/build/tools/check_spec.js

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseArgs, getString } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { handleToolError } from '../utils/error-handler.js';
+import { resolveWorkspaceRoot } from '../lib/workspace-root.js';
+import { validateSpecDocuments } from '../lib/spec-validator.js';
+/**
+ * check_spec 工具（P1「填写后校验」闸门）
+ *
+ * 读取 docs/specs/{feature_name}/{requirements,design,tasks}.md，
+ * 机械校验完整性。未通过则列出逐条待修项并要求补全后重跑，通过前不应进入实现。
+ */
+const DEFAULT_DOCS_DIR = 'docs';
+function readIfExists(filePath) {
+    try {
+        return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+function formatIssue(issue) {
+    const tag = issue.severity === 'error' ? '必须修复' : '提醒';
+    return `- [${tag}] (${issue.file}) ${issue.message}`;
+}
+export async function checkSpec(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                feature_name: '',
+                docs_dir: DEFAULT_DOCS_DIR,
+            },
+            primaryField: 'feature_name',
+            fieldAliases: {
+                feature_name: ['name', 'feature', 'spec', '功能名', '功能名称', '规格'],
+                docs_dir: ['dir', 'output', '目录', '文档目录'],
+                project_root: ['projectRoot', 'project_path', 'projectPath', 'root', '项目路径', '项目根目录'],
+            },
+        });
+        const featureName = getString(parsed.feature_name);
+        const docsDir = getString(parsed.docs_dir) || DEFAULT_DOCS_DIR;
+        const projectRoot = resolveWorkspaceRoot(getString(parsed.project_root));
+        if (!featureName) {
+            throw new Error('请提供 feature_name（要校验的规格目录名，对应 docs/specs/<feature_name>/）');
+        }
+        const specDir = path.join(projectRoot, docsDir, 'specs', featureName);
+        const report = validateSpecDocuments({
+            requirements: readIfExists(path.join(specDir, 'requirements.md')),
+            design: readIfExists(path.join(specDir, 'design.md')),
+            tasks: readIfExists(path.join(specDir, 'tasks.md')),
+        });
+        const relDir = `${docsDir}/specs/${featureName}`;
+        const issueLines = report.issues.length > 0
+            ? report.issues.map(formatIssue).join('\n')
+            : '- 无';
+        const text = report.passed
+            ? `# ✅ 规格校验通过：${featureName}
+
+${report.summary}
+
+**需求清单**: ${report.frIds.join(', ') || '（未发现 FR）'}
+${report.warningCount > 0 ? `\n仍有 ${report.warningCount} 个提醒（非阻塞，建议处理）：\n${issueLines}\n` : ''}
+**下一步**: 规格已具备可实现性，可进入实现/估算阶段。`
+            : `# ❌ 规格校验未通过：${featureName}
+
+${report.summary}
+
+## 待修复（${relDir}）
+${issueLines}
+
+## 处理方式
+1. 按上述每一条补全 \`${relDir}/\` 下的 requirements.md / design.md / tasks.md
+2. **重新运行** \`check_spec\`（同样的 feature_name）直到通过
+3. **校验通过前不要开始写实现代码** —— 这是为了确保需求被完整实现，而不是写到一半才发现规格有缺口`;
+        return okStructured(text, report);
+    }
+    catch (error) {
+        return handleToolError(error, 'check_spec');
+    }
+}

package/build/tools/index.d.ts

@@ -6,6 +6,7 @@ export { gentest } from "./gentest.js";
 export { refactor } from "./refactor.js";
 export { initProjectContext } from "./init_project_context.js";
 export { addFeature } from "./add_feature.js";
+export { checkSpec } from "./check_spec.js";
 export { fixBug } from "./fix_bug.js";
 export { estimate } from "./estimate.js";
 export { startFeature } from "./start_feature.js";

package/build/tools/index.js

@@ -6,6 +6,7 @@ export { gentest } from "./gentest.js";
 export { refactor } from "./refactor.js";
 export { initProjectContext } from "./init_project_context.js";
 export { addFeature } from "./add_feature.js";
+export { checkSpec } from "./check_spec.js";
 export { fixBug } from "./fix_bug.js";
 export { estimate } from "./estimate.js";
 // 智能编排工具

package/build/tools/start_bugfix.js

@@ -425,6 +425,17 @@ ${graphContext.highlights.length > 0
 `;
         const memoryContext = await loadMemoryInjectionContext([errorMessage, stackTrace, codeContext].filter(Boolean).join("\n"), "bugfix");
         const memoryGuideSection = renderMemoryGuideSection(memoryContext);
+        // 记忆优先：先消化历史同类 Bug 的根因/修复（坑），再做 TBP 真因分析
+        const memoryRecallStep = memoryContext.enabled
+            ? [{
+                    id: 'recall-memory',
+                    tool: 'search_memory',
+                    when: '开干前（下方「历史经验与坑」已自动注入相似历史修复；需要更多同类案例时再调）',
+                    args: { query: errorMessage, limit: 5 },
+                    outputs: [],
+                    note: '先看历史同类 Bug 的根因与已验证修复，优先复用其修复路径并规避同类坑；据此收敛 TBP-4/5/6 的真因方向',
+                }]
+            : [];
         if (requirementsMode === "loop") {
             throwIfAborted(context?.signal, "start_bugfix(loop) 已取消");
             await reportToolProgress(context, 70, "start_bugfix: 生成 loop 计划");
@@ -450,6 +461,7 @@ ${graphContext.highlights.length > 0
             const plan = {
                 mode: 'delegated',
                 steps: [
+                    ...memoryRecallStep,
                     {
                         id: 'context',
                         tool: 'init_project_context',
@@ -512,19 +524,18 @@ ${graphContext.highlights.length > 0
                 ],
                 notes: [
                     ...headerNotes,
-                    ...(memoryContext.enabled ? ['记忆系统: 已启用，历史修复经验全文已自动注入，结束后评估沉淀'] : []),
+                    ...(memoryContext.enabled ? ['记忆优先: 已自动注入历史同类 Bug 的根因与修复（见顶部），先复用、规避同类坑；结束后评估沉淀'] : []),
                 ],
             });
             const loopTemplate = profileDecision.resolved === 'strict'
                 ? LOOP_PROMPT_TEMPLATE_STRICT
                 : LOOP_PROMPT_TEMPLATE_GUIDED;
-            const guide = (header + loopTemplate
+            const renderedLoopPrompt = loopTemplate
                 .replace(/{error_message}/g, errorMessage)
                 .replace(/{analysis_mode}/g, analysisMode)
                 .replace(/{question_budget}/g, String(questionBudget))
-                .replace(/{assumption_cap}/g, String(assumptionCap)))
-                + graphGuideSection
-                + memoryGuideSection;
+                .replace(/{assumption_cap}/g, String(assumptionCap));
+            const guide = header + memoryGuideSection + renderedLoopPrompt + graphGuideSection;
             const loopReport = {
                 mode: 'loop',
                 round: 1,
@@ -577,22 +588,22 @@ ${graphContext.highlights.length > 0
             ],
             notes: [
                 ...headerNotes,
-                ...(memoryContext.enabled ? ['记忆系统: 已启用，相似历史经验全文已自动注入'] : []),
+                ...(memoryContext.enabled ? ['记忆优先: 已自动注入历史同类 Bug 的根因与修复（见顶部），先复用、规避同类坑'] : []),
             ],
         });
         const promptTemplate = profileDecision.resolved === 'strict'
             ? PROMPT_TEMPLATE_STRICT
             : PROMPT_TEMPLATE_GUIDED;
-        const guide = (header + promptTemplate
+        const renderedPrompt = promptTemplate
             .replace(/{error_message}/g, errorMessage)
             .replace(/{stack_trace}/g, stackTrace)
             .replace(/{analysis_mode}/g, analysisMode)
-            .replace(/{stack_trace_section}/g, stackTraceSection))
-            + graphGuideSection
-            + memoryGuideSection;
+            .replace(/{stack_trace_section}/g, stackTraceSection);
+        const guide = header + memoryGuideSection + renderedPrompt + graphGuideSection;
         const plan = {
             mode: 'delegated',
             steps: [
+                ...memoryRecallStep,
                 {
                     id: 'context',
                     tool: 'init_project_context',

package/build/tools/start_feature.js

@@ -91,7 +91,14 @@ const PROMPT_TEMPLATE = `# 🚀 新功能开发编排（委托式）
 - \`{docs_dir}/specs/{feature_name}/design.md\`
 - \`{docs_dir}/specs/{feature_name}/tasks.md\`
 
-### 2) 工作量估算
+### 2) 校验规格完整性（闸门）
+**调用**: \`check_spec\`
+\`\`\`json
+{ "feature_name": "{feature_name}", "docs_dir": "{docs_dir}" }
+\`\`\`
+**未通过**：按报告逐条补全 requirements/design/tasks 后**重跑 check_spec**；**通过前不要写实现代码**。
+
+### 3) 工作量估算
 **调用**: \`estimate\`
 \`\`\`json
 {
@@ -305,6 +312,17 @@ ${graphContext.highlights.length > 0
             .join("\n");
         const memoryContext = await loadMemoryInjectionContext(`${featureName}\n${description}`, 'feature');
         const memoryGuideSection = renderMemoryGuideSection(memoryContext);
+        // 记忆优先：把"先检索消化历史经验/坑"作为编排的显式第一步
+        const memoryRecallStep = memoryContext.enabled
+            ? [{
+                    id: 'recall-memory',
+                    tool: 'search_memory',
+                    when: '开干前（下方「历史经验与坑」已自动注入 top 命中；需要更多历史需求/坑时再调）',
+                    args: { query: `${featureName} ${description}`, limit: 5 },
+                    outputs: [],
+                    note: '先消化历史经验与可复用模式，并逐条核对「历史坑」是否已在本次设计中规避；据此收敛需求范围，并把要点填入 requirements.md 的「历史经验与坑」节',
+                }]
+            : [];
         if (requirementsMode === "loop") {
             throwIfAborted(context?.signal, "start_feature(loop) 已取消");
             await reportToolProgress(context, 70, "start_feature: 生成 loop 计划");
@@ -330,6 +348,7 @@ ${graphContext.highlights.length > 0
             const plan = {
                 mode: 'delegated',
                 steps: [
+                    ...memoryRecallStep,
                     {
                         id: 'context',
                         tool: 'init_project_context',
@@ -369,6 +388,14 @@ ${graphContext.highlights.length > 0
                             `${docsDir}/specs/${featureName}/tasks.md`,
                         ],
                     },
+                    {
+                        id: 'check-spec',
+                        tool: 'check_spec',
+                        when: 'stopConditions.ready=true 且 requirements/design/tasks 已落盘',
+                        args: { feature_name: featureName, docs_dir: docsDir, ...(projectRoot ? { project_root: projectRoot } : {}) },
+                        outputs: [],
+                        note: '未通过则按报告补全规格后重跑 check_spec；通过前不要写实现代码',
+                    },
                     {
                         id: 'estimate',
                         tool: 'estimate',
@@ -392,17 +419,16 @@ ${graphContext.highlights.length > 0
                 notes: [
                     `模板档位: ${templateProfile}`,
                     graphStatusNote,
-                    ...(memoryContext.enabled ? ['记忆系统: 已启用，历史经验全文已自动注入，结束后评估是否沉淀'] : []),
+                    ...(memoryContext.enabled ? ['记忆优先: 已自动注入历史经验与坑（见顶部），开干前先消化、约束范围并规避同类坑；结束后评估是否沉淀'] : []),
                 ],
             });
-            const guide = (header + LOOP_PROMPT_TEMPLATE
+            const renderedLoopPrompt = LOOP_PROMPT_TEMPLATE
                 .replace(/{feature_name}/g, featureName)
                 .replace(/{description}/g, description)
                 .replace(/{project_root}/g, toWorkspacePath(projectRoot))
                 .replace(/{question_budget}/g, String(questionBudget))
-                .replace(/{assumption_cap}/g, String(assumptionCap)))
-                + graphGuideSection
-                + memoryGuideSection;
+                .replace(/{assumption_cap}/g, String(assumptionCap));
+            const guide = header + memoryGuideSection + renderedLoopPrompt + graphGuideSection;
             const loopReport = {
                 mode: 'loop',
                 round: 1,
@@ -452,20 +478,20 @@ ${graphContext.highlights.length > 0
             notes: [
                 `模板档位: ${templateProfile}`,
                 graphStatusNote,
-                ...(memoryContext.enabled ? ['记忆系统: 已启用，历史经验全文已自动注入'] : []),
+                ...(memoryContext.enabled ? ['记忆优先: 已自动注入历史经验与坑（见顶部），开干前先消化、约束范围并规避同类坑'] : []),
             ],
         });
-        const guide = (header + PROMPT_TEMPLATE
+        const renderedPrompt = PROMPT_TEMPLATE
             .replace(/{feature_name}/g, featureName)
             .replace(/{description}/g, description)
             .replace(/{docs_dir}/g, docsDir)
             .replace(/{project_root}/g, (projectRoot || process.cwd()).replace(/\\/g, "/"))
-            .replace(/{template_profile}/g, templateProfile))
-            + graphGuideSection
-            + memoryGuideSection;
+            .replace(/{template_profile}/g, templateProfile);
+        const guide = header + memoryGuideSection + renderedPrompt + graphGuideSection;
         const plan = {
             mode: 'delegated',
             steps: [
+                ...memoryRecallStep,
                 {
                     id: 'context',
                     tool: 'init_project_context',
@@ -487,6 +513,14 @@ ${graphContext.highlights.length > 0
                         `${docsDir}/specs/${featureName}/tasks.md`,
                     ],
                 },
+                {
+                    id: 'check-spec',
+                    tool: 'check_spec',
+                    when: 'requirements/design/tasks 落盘后、进入估算/实现前',
+                    args: { feature_name: featureName, docs_dir: docsDir, ...(projectRoot ? { project_root: projectRoot } : {}) },
+                    outputs: [],
+                    note: '未通过则按报告逐条补全规格后重跑 check_spec；通过前不要写实现代码',
+                },
                 {
                     id: 'estimate',
                     tool: 'estimate',
@@ -526,6 +560,7 @@ ${graphContext.highlights.length > 0
                 `如果缺少 ${graphDocs.latestMarkdownPath} / ${graphDocs.latestJsonPath}，先调用 init_project_context 补齐图谱初始化`,
                 `优先读取 ${graphDocs.latestMarkdownPath} 获取模块依赖与调用链摘要`,
                 '调用 add_feature 工具生成功能规格文档',
+                '调用 check_spec 校验规格完整性，未通过先补全再重跑（通过前不要写实现代码）',
                 '调用 estimate 工具进行工作量估算',
                 '按照 tasks.md 开始开发',
             ],

package/build/tools/start_ui.js

@@ -565,6 +565,17 @@ export async function startUi(args, context) {
         headerNotes.push(buildSkillHeaderNote(skillBridge));
         const memoryContext = await loadMemoryInjectionContext(description || templateName, 'ui');
         const memoryGuideSection = renderMemoryGuideSection(memoryContext);
+        // 记忆优先：先复用历史 UI 资产/模式并规避历史 UI 坑，再进入设计与渲染
+        const memoryRecallStep = memoryContext.enabled
+            ? [{
+                    id: 'recall-memory',
+                    tool: 'search_memory',
+                    when: '开干前（下方「历史经验与坑」已自动注入相似 UI 资产与坑；需要更多时再调）',
+                    args: { query: description || templateName, limit: 5 },
+                    outputs: [],
+                    note: '先复用历史可复用 UI 组件/布局/交互模式，并规避历史 UI 坑（交互/兼容性/可访问性）',
+                }]
+            : [];
         // 验证 mode 参数
         const validModes = ["auto", "manual"];
         if (mode && !validModes.includes(mode)) {
@@ -629,6 +640,7 @@ start_ui <描述> --requirements_mode=loop
             const plan = {
                 mode: 'delegated',
                 steps: [
+                    ...memoryRecallStep,
                     skillBridgeStep,
                     {
                         id: 'loop-1',
@@ -712,17 +724,17 @@ start_ui <描述> --requirements_mode=loop
                 ],
                 notes: [
                     ...headerNotes,
-                    ...(memoryContext.enabled ? ['记忆系统: 已启用，先复用历史 UI 资产，再决定是否沉淀本次结果'] : []),
+                    ...(memoryContext.enabled ? ['记忆优先: 已自动注入相似历史 UI 资产与坑（见顶部），先复用并规避同类坑；再决定是否沉淀'] : []),
                 ],
             });
             const loopTemplate = profileDecision.resolved === 'strict'
                 ? LOOP_PROMPT_TEMPLATE_STRICT
                 : LOOP_PROMPT_TEMPLATE_GUIDED;
-            const guide = header + skillBridgeSection + loopTemplate
+            const renderedLoopPrompt = loopTemplate
                 .replace(/{description}/g, description)
                 .replace(/{question_budget}/g, String(questionBudget))
-                .replace(/{assumption_cap}/g, String(assumptionCap))
-                + memoryGuideSection;
+                .replace(/{assumption_cap}/g, String(assumptionCap));
+            const guide = header + memoryGuideSection + skillBridgeSection + renderedLoopPrompt;
             const loopReport = {
                 mode: 'loop',
                 round: 1,
@@ -862,6 +874,7 @@ ${recommendation.reasoning}
             const plan = {
                 mode: 'delegated',
                 steps: [
+                    ...memoryRecallStep,
                     skillBridgeStep,
                     {
                         id: 'context',
@@ -929,10 +942,10 @@ ${recommendation.reasoning}
                 ],
                 notes: [
                     ...headerNotes,
-                    ...(memoryContext.enabled ? ['记忆系统: 已启用，相似历史 UI 经验全文已自动注入'] : []),
+                    ...(memoryContext.enabled ? ['记忆优先: 已自动注入相似历史 UI 资产与坑（见顶部），先复用并规避同类坑'] : []),
                 ],
             });
-            const smartPlan = header + skillBridgeSection + (profileDecision.resolved === 'strict' ? smartPlanStrict : smartPlanGuided) + memoryGuideSection;
+            const smartPlan = header + memoryGuideSection + skillBridgeSection + (profileDecision.resolved === 'strict' ? smartPlanStrict : smartPlanGuided);
             // Create structured UI report for auto mode
             const uiReport = {
                 summary: `智能 UI 开发：${description}`,
@@ -1060,21 +1073,22 @@ start_ui "设置页面" --framework=react
             ],
             notes: [
                 ...headerNotes,
-                ...(memoryContext.enabled ? ['记忆系统: 已启用，相似历史 UI 经验全文已自动注入'] : []),
+                ...(memoryContext.enabled ? ['记忆优先: 已自动注入相似历史 UI 资产与坑（见顶部），先复用并规避同类坑'] : []),
             ],
         });
         const baseTemplate = profileDecision.resolved === 'strict'
             ? PROMPT_TEMPLATE_STRICT
             : PROMPT_TEMPLATE_GUIDED;
-        let guide = header + skillBridgeSection + baseTemplate;
-        guide = safeReplace(guide, '{description}', escapeJson(description));
-        guide = safeReplace(guide, '{productType}', productType);
-        guide = safeReplace(guide, '{framework}', framework);
-        guide = safeReplace(guide, '{templateName}', templateName);
-        guide += memoryGuideSection;
+        let body = skillBridgeSection + baseTemplate;
+        body = safeReplace(body, '{description}', escapeJson(description));
+        body = safeReplace(body, '{productType}', productType);
+        body = safeReplace(body, '{framework}', framework);
+        body = safeReplace(body, '{templateName}', templateName);
+        const guide = header + memoryGuideSection + body;
         const plan = {
             mode: 'delegated',
             steps: [
+                ...memoryRecallStep,
                 skillBridgeStep,
                 {
                     id: 'context',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.1.0",
-  "description": "AI-Powered Development Toolkit - MCP Server with 26 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, UI/UX Pro Max, and Requirements Interview.",
+  "version": "3.2.0",
+  "description": "AI-Powered Development Toolkit - MCP Server with 27 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, UI/UX Pro Max, and Requirements Interview.",
   "mcpName": "io.github.mybolide/mcp-probe-kit",
   "type": "module",
   "main": "build/index.js",