mcp-probe-kit 3.3.0 → 3.6.0

package/build/tools/start_bugfix.js

@@ -1,13 +1,15 @@
 import * as fs from "node:fs";
 import { parseArgs, getString, getNumber } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
+import { attachHandles } from "../lib/handles.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
 import { BugFixReportSchema, RequirementsLoopSchema } from "../schemas/structured-output.js";
 import { reportToolProgress, throwIfAborted, } from "../lib/tool-execution-context.js";
 import { buildBugfixGraphContext } from "../lib/gitnexus-bridge.js";
-import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, } from "../lib/memory-orchestration.js";
+import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, buildOrchestrationHandles, } from "../lib/memory-orchestration.js";
 import { resolveWorkspaceRoot, isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
 import { layoutAbsPath, parseLayoutArgsFromRecord, resolveProjectContextLayout, } from "../lib/project-context-layout.js";
+import { buildCheckSpecPlanStep, renderSpecGatePromptSection, resolveBugfixSpecGate, } from "../lib/spec-gate.js";
 function decideTemplateProfile(description) {
     const text = description || '';
     const lengthScore = text.length >= 200 ? 2 : text.length >= 120 ? 1 : 0;
@@ -120,6 +122,8 @@ const PROMPT_TEMPLATE_GUIDED = `# 🐛 Bug 修复编排指南（TBP 8 步真因
 
 **产出**: 测试代码
 
+{spec_gate_section}
+
 ---
 
 ## ✅ 完成检查
@@ -177,6 +181,7 @@ const PROMPT_TEMPLATE_STRICT = `# 🐛 Bug 修复编排（严格 | TBP 8 步）
   "framework": "[根据项目上下文选择: jest/vitest/mocha]"
 }
 \`\`\`
+{spec_gate_section}
 
 ---
 
@@ -307,6 +312,8 @@ export async function startBugfix(args, context) {
                 stack_trace: ["stack", "trace", "堆栈", "调用栈"],
                 code_context: ["code_context", "code", "context", "相关代码", "代码上下文"],
                 project_root: ["projectRoot", "project_path", "projectPath", "root", "project_root", "项目路径", "项目根目录"],
+                docs_dir: ["dir", "output", "目录", "文档目录"],
+                feature_name: ["name", "feature", "spec", "功能名", "功能名称", "规格"],
                 analysis_mode: ["analysis_mode", "methodology", "rca", "tbp", "分析方法"],
                 template_profile: ["profile", "template_profile", "模板档位", "模板模式"],
                 requirements_mode: ["mode", "requirements_mode", "loop", "需求模式"],
@@ -320,6 +327,7 @@ export async function startBugfix(args, context) {
         const codeContext = getString(parsedArgs.code_context);
         const projectRoot = getString(parsedArgs.project_root);
         const docsDir = getString(parsedArgs.docs_dir) || "docs";
+        const featureNameInput = getString(parsedArgs.feature_name);
         if (isLikelyProjectNamedRelativePath(projectRoot)) {
             return {
                 content: [{
@@ -388,6 +396,18 @@ export async function startBugfix(args, context) {
             layoutManifest: layout.manifestPath,
         };
         const graphDocsMissing = !bootstrapState.latestMarkdownExists || !bootstrapState.latestJsonExists;
+        const specGate = resolveBugfixSpecGate({
+            featureName: featureNameInput,
+            projectRoot: layout.projectRoot,
+            docsDir,
+            hintText: combinedText,
+        });
+        const specGateSection = specGate ? renderSpecGatePromptSection(specGate) : '';
+        if (specGate) {
+            headerNotes.push(specGate.detected
+                ? `规格闸门: 已自动关联 ${specGate.specDir}/，修复后需 check_spec`
+                : `规格闸门: 关联 ${specGate.specDir}/，修复后需 check_spec`);
+        }
         const graphContext = await buildBugfixGraphContext({
             errorMessage,
             stackTrace,
@@ -571,7 +591,7 @@ ${graphContext.highlights.length > 0
                 },
             };
             await reportToolProgress(context, 95, "start_bugfix: loop 输出已生成");
-            return okStructured(guide, loopReport, {
+            return okStructured(guide, attachHandles(loopReport, buildOrchestrationHandles(memoryContext)), {
                 schema: RequirementsLoopSchema,
                 note: 'AI 应按轮次澄清 Bug 需求并更新结构化输出，满足结束条件后再进入 fix_bug / gentest',
             });
@@ -598,7 +618,8 @@ ${graphContext.highlights.length > 0
             .replace(/{error_message}/g, errorMessage)
             .replace(/{stack_trace}/g, stackTrace)
             .replace(/{analysis_mode}/g, analysisMode)
-            .replace(/{stack_trace_section}/g, stackTraceSection);
+            .replace(/{stack_trace_section}/g, stackTraceSection)
+            .replace(/{spec_gate_section}/g, specGateSection);
         const guide = header + memoryGuideSection + renderedPrompt + graphGuideSection;
         const plan = {
             mode: 'delegated',
@@ -635,6 +656,7 @@ ${graphContext.highlights.length > 0
                     },
                     outputs: [],
                 },
+                ...(specGate ? [buildCheckSpecPlanStep(specGate.featureName, specGate.docsDir)] : []),
                 ...(memoryContext.enabled ? [buildMemoryPlanStep('bugfix')] : []),
             ],
         };
@@ -659,6 +681,13 @@ ${graphContext.highlights.length > 0
                     status: 'pending',
                     description: '调用 gentest 工具生成测试用例',
                 },
+                ...(specGate
+                    ? [{
+                            name: '规格闸门校验',
+                            status: 'pending',
+                            description: `修复后调用 check_spec 校验 ${specGate.specDir}/`,
+                        }]
+                    : []),
             ],
             artifacts: [],
             nextSteps: [
@@ -670,6 +699,9 @@ ${graphContext.highlights.length > 0
                 '调用 fix_bug 工具分析问题并形成因果句真因',
                 '调用 gentest 工具生成回归测试',
                 '运行测试验证修复',
+                ...(specGate
+                    ? [`修复后调用 check_spec 校验 ${specGate.specDir}/，未通过先补规格再重跑`]
+                    : []),
             ],
             rootCause: '待分析（需要调用 fix_bug 工具）',
             fixPlan: '待制定（需要调用 fix_bug 工具）',
@@ -709,10 +741,11 @@ ${graphContext.highlights.length > 0
                     graphDocsMissing,
                 },
                 graphContext,
+                ...(specGate ? { specGate } : {}),
             },
         };
         await reportToolProgress(context, 95, "start_bugfix: 执行计划输出已生成");
-        return okStructured(guide, bugfixReport, {
+        return okStructured(guide, attachHandles(bugfixReport, buildOrchestrationHandles(memoryContext)), {
             schema: BugFixReportSchema,
             note: 'AI 应该按照指南执行步骤，并在每个步骤完成后更新 structuredContent 中的状态',
         });

package/build/tools/start_feature.js

@@ -1,11 +1,12 @@
 import * as fs from "node:fs";
 import { parseArgs, getString, getNumber } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
+import { attachHandles } from "../lib/handles.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
 import { FeatureReportSchema, RequirementsLoopSchema } from "../schemas/structured-output.js";
 import { reportToolProgress, throwIfAborted, } from "../lib/tool-execution-context.js";
 import { buildFeatureGraphContext } from "../lib/gitnexus-bridge.js";
-import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, } from "../lib/memory-orchestration.js";
+import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, buildOrchestrationHandles, } from "../lib/memory-orchestration.js";
 import { resolveWorkspaceRoot, toWorkspacePath, isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
 import { layoutAbsPath, parseLayoutArgsFromRecord, resolveProjectContextLayout, } from "../lib/project-context-layout.js";
 /**
@@ -463,7 +464,7 @@ ${graphContext.highlights.length > 0
                 },
             };
             await reportToolProgress(context, 95, "start_feature: loop 输出已生成");
-            return okStructured(guide, loopReport, {
+            return okStructured(guide, attachHandles(loopReport, buildOrchestrationHandles(memoryContext)), {
                 schema: RequirementsLoopSchema,
                 note: 'AI 应按轮次澄清需求并更新结构化输出，满足结束条件后再进入 add_feature / estimate',
             });
@@ -595,7 +596,7 @@ ${graphContext.highlights.length > 0
             },
         };
         await reportToolProgress(context, 95, "start_feature: 执行计划输出已生成");
-        return okStructured(guide, featureReport, {
+        return okStructured(guide, attachHandles(featureReport, buildOrchestrationHandles(memoryContext)), {
             schema: FeatureReportSchema,
             note: 'AI 应该按照指南执行步骤，并在每个步骤完成后更新 structuredContent 中的状态和估算信息',
         });

package/build/tools/start_ui.js

@@ -10,13 +10,14 @@
 import { parseArgs, getString, getNumber } from "../utils/parseArgs.js";
 import { getReasoningEngine } from "./ui-ux-tools.js";
 import { okStructured } from "../lib/response.js";
+import { attachHandles } from "../lib/handles.js";
 import { renderOrchestrationHeader } from "../lib/orchestration-guidance.js";
 import { buildSkillBridgePlanStep, buildSkillHeaderNote, detectSkillBridge, renderSkillBridgeSection, } from "../lib/skill-bridge.js";
 import { UIReportSchema, RequirementsLoopSchema } from "../schemas/structured-output.js";
 import { detectProjectType } from "../lib/project-detector.js";
 import { resolveWorkspaceRoot, isLikelyProjectNamedRelativePath, buildProjectRootRetryHint } from "../lib/workspace-root.js";
 import { reportToolProgress, throwIfAborted, } from "../lib/tool-execution-context.js";
-import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, } from "../lib/memory-orchestration.js";
+import { buildMemoryPlanStep, loadMemoryInjectionContext, renderMemoryGuideSection, buildOrchestrationHandles, } from "../lib/memory-orchestration.js";
 import { isShadcnStack } from "../lib/shadcn-ui.js";
 import { renderUiHardRules, renderUiBannedList, renderPreFlightChecklist } from "../lib/quality-constraints.js";
 /** 渲染代码步骤统一注入的 UI 硬约束 + 黑名单 + 交付前自检 */
@@ -782,7 +783,7 @@ start_ui <描述> --requirements_mode=loop
                 },
             };
             await reportToolProgress(context, 95, "start_ui: loop 输出已生成");
-            return okStructured(guide, loopReport, {
+            return okStructured(guide, attachHandles(loopReport, buildOrchestrationHandles(memoryContext)), {
                 schema: RequirementsLoopSchema,
                 note: 'AI 应按轮次澄清 UI 需求并更新结构化输出，满足结束条件后再执行 UI 计划',
             });
@@ -1035,7 +1036,7 @@ ${recommendation.reasoning}
                 },
             };
             await reportToolProgress(context, 95, "start_ui: auto 输出已生成");
-            return okStructured(smartPlan, uiReport, {
+            return okStructured(smartPlan, attachHandles(uiReport, buildOrchestrationHandles(memoryContext)), {
                 schema: UIReportSchema,
                 note: 'AI 应该按照智能计划执行步骤，并在每个步骤完成后更新 structuredContent',
             });
@@ -1238,7 +1239,7 @@ start_ui "设置页面" --framework=react
             },
         };
         await reportToolProgress(context, 95, "start_ui: manual 输出已生成");
-        return okStructured(guide, uiReport, {
+        return okStructured(guide, attachHandles(uiReport, buildOrchestrationHandles(memoryContext)), {
             schema: UIReportSchema,
             note: 'AI 应该按照指南执行步骤，并在每个步骤完成后更新 structuredContent',
         });

package/build/tools/update_memory_asset.d.ts

@@ -0,0 +1,7 @@
+export declare function updateMemoryAsset(args: any): Promise<import("../lib/response.js").ToolResponse | {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+}>;

package/build/tools/update_memory_asset.js

@@ -0,0 +1,98 @@
+import { parseArgs, getString, getNumber } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { createMemoryClient } from '../lib/memory-client.js';
+import { handleToolError } from '../utils/error-handler.js';
+import { attachHandles, buildMemoryAssetHandles } from '../lib/handles.js';
+function fieldProvided(args, ...keys) {
+    const record = args?.input && typeof args.input === 'object' && !Array.isArray(args.input)
+        ? { ...args, ...args.input }
+        : args;
+    if (!record || typeof record !== 'object' || Array.isArray(record)) {
+        return false;
+    }
+    return keys.some((key) => key in record && record[key] !== undefined && record[key] !== null);
+}
+export async function updateMemoryAsset(args) {
+    try {
+        const parsed = parseArgs(args, {
+            fieldAliases: {
+                code_snippet: ['code', 'snippet'],
+                file_path: ['path'],
+                source_project: ['project'],
+                source_path: ['source'],
+            },
+        });
+        const assetId = getString(parsed.asset_id);
+        if (!assetId) {
+            throw new Error('缺少必填参数: asset_id');
+        }
+        const patch = {};
+        if (fieldProvided(args, 'name')) {
+            patch.name = getString(parsed.name);
+        }
+        if (fieldProvided(args, 'type')) {
+            patch.type = getString(parsed.type);
+        }
+        if (fieldProvided(args, 'description')) {
+            patch.description = getString(parsed.description);
+        }
+        if (fieldProvided(args, 'summary')) {
+            patch.summary = getString(parsed.summary);
+        }
+        if (fieldProvided(args, 'content', 'code_snippet', 'code', 'snippet')) {
+            patch.content = getString(parsed.content) || getString(parsed.code_snippet);
+        }
+        if (fieldProvided(args, 'tags')) {
+            patch.tags = Array.isArray(parsed.tags)
+                ? parsed.tags.filter((item) => typeof item === 'string')
+                : [];
+        }
+        if (fieldProvided(args, 'confidence')) {
+            patch.confidence = getNumber(parsed.confidence, 0.7);
+        }
+        if (fieldProvided(args, 'usage')) {
+            patch.usage = getString(parsed.usage);
+        }
+        if (fieldProvided(args, 'source_project', 'project')) {
+            patch.sourceProject = getString(parsed.source_project);
+        }
+        if (fieldProvided(args, 'source_path', 'source', 'file_path', 'path')) {
+            patch.sourcePath = getString(parsed.source_path) || getString(parsed.file_path);
+        }
+        if (Object.keys(patch).length === 0) {
+            throw new Error('至少提供一个待更新字段: name, type, description, summary, content, tags, confidence, usage 等');
+        }
+        const client = createMemoryClient();
+        if (!client.isEnabled()) {
+            return okStructured('记忆服务未开启，已跳过更新。', { enabled: false, updated: false, asset: null });
+        }
+        const warnings = [];
+        const nextType = patch.type;
+        const nextContent = patch.content;
+        if (nextType === 'bugfix' && nextContent) {
+            const requiredSections = ['【现象】', '【根因】', '【修复】'];
+            const missing = requiredSections.filter((section) => !nextContent.includes(section));
+            if (missing.length > 0) {
+                warnings.push(`建议 content 包含 ${missing.join('、')}，便于跨仓库检索与复用`);
+            }
+        }
+        if (patch.sourceProject || patch.sourcePath) {
+            warnings.push('跨仓库共享记忆时请勿依赖 source_project/source_path；路径请写入 content 正文（可选）');
+        }
+        const { updated, asset } = await client.updateAsset(assetId, patch);
+        if (!updated || !asset) {
+            return okStructured(`未找到记忆资产: ${assetId}`, { enabled: true, updated: false, asset: null });
+        }
+        return okStructured(`已更新记忆资产: ${asset.name}`, attachHandles({
+            enabled: true,
+            updated: true,
+            asset,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        }, {
+            memory_assets: buildMemoryAssetHandles([{ id: asset.id, name: asset.name, type: asset.type, summary: asset.summary }], 'update_memory_asset'),
+        }));
+    }
+    catch (error) {
+        return handleToolError(error, 'update_memory_asset');
+    }
+}

package/build/tools/workflow.d.ts

@@ -0,0 +1,13 @@
+/**
+ * workflow — 开发工作流路由（只读指南）
+ *
+ * 根据用户意图生成「何时调哪个 MCP 工具」的分阶段计划，
+ * 用于约束 Agent 先走 start_* / code_insight / check_spec，而不是直接写代码。
+ */
+export declare function workflow(args: unknown): Promise<import("../lib/response.js").ToolResponse | {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+}>;

package/build/tools/workflow.js

@@ -0,0 +1,69 @@
+import { parseArgs, getString } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { handleToolError } from '../utils/error-handler.js';
+import { buildDevWorkflow, renderWorkflowMarkdown } from '../lib/dev-workflow.js';
+import { ensureMcpProbeKitBootstrap } from '../lib/workflow-skill-installer.js';
+import { resolveWorkspaceRoot } from '../lib/workspace-root.js';
+/**
+ * workflow — 开发工作流路由（只读指南）
+ *
+ * 根据用户意图生成「何时调哪个 MCP 工具」的分阶段计划，
+ * 用于约束 Agent 先走 start_* / code_insight / check_spec，而不是直接写代码。
+ */
+export async function workflow(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                intent: '',
+                input: '',
+                scenario: 'auto',
+                description: '',
+            },
+            primaryField: 'intent',
+            fieldAliases: {
+                intent: ['input', 'description', 'goal', 'task', '需求', '目标', '描述'],
+                scenario: ['mode', 'type', '场景', '类型'],
+            },
+        });
+        const intent = getString(parsed.intent) ||
+            getString(parsed.input) ||
+            getString(parsed.description);
+        const scenario = getString(parsed.scenario) || 'auto';
+        const plan = buildDevWorkflow(intent, { scenario });
+        const text = renderWorkflowMarkdown(plan, intent);
+        const projectRoot = resolveWorkspaceRoot('');
+        const bootstrap = ensureMcpProbeKitBootstrap(projectRoot);
+        return okStructured(text, {
+            scenario: plan.scenario,
+            scenarioLabel: plan.scenarioLabel,
+            confidence: plan.confidence,
+            summary: plan.summary,
+            firstTool: plan.firstTool,
+            firstToolArgsHint: plan.firstToolArgsHint ?? null,
+            phases: plan.phases,
+            avoid: plan.avoid,
+            memoryNotes: plan.memoryNotes,
+            projectSkill: {
+                relPath: bootstrap.skill.skillRelPath,
+                existed: bootstrap.skill.existed,
+                created: bootstrap.skill.created,
+                updated: bootstrap.skill.updated,
+                version: bootstrap.skill.version,
+                previousVersion: bootstrap.skill.previousVersion,
+            },
+            agentsMd: {
+                path: bootstrap.agentsMd.path,
+                existed: bootstrap.agentsMd.existed,
+                created: bootstrap.agentsMd.created,
+                updated: bootstrap.agentsMd.updated,
+            },
+            handles: {
+                next_tool: plan.firstTool,
+                next_args: plan.firstToolArgsHint ?? {},
+            },
+        });
+    }
+    catch (error) {
+        return handleToolError(error, 'workflow');
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.3.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.",
+  "version": "3.6.0",
+  "description": "AI-Powered Development Toolkit - MCP Server with 30 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, MCP Skill auto-sync, UI/UX Pro Max, and Requirements Interview.",
   "mcpName": "io.github.mybolide/mcp-probe-kit",
   "type": "module",
   "main": "build/index.js",
@@ -21,7 +21,9 @@
     "prepublishOnly": "npm run build",
     "sync-ui-data": "tsx scripts/sync-ui-data.ts",
     "sync-version": "node scripts/sync-version.mjs",
-    "prebuild": "npm run sync-version && npm run sync-ui-data",
+    "verify-workflow-skill": "tsx scripts/verify-workflow-skill.ts",
+    "sync-workflow-skill": "tsx scripts/sync-workflow-skill.ts",
+    "prebuild": "npm run sync-version && npm run sync-ui-data && npm run verify-workflow-skill && npm run sync-workflow-skill",
     "docs:serve": "npx http-server docs -p 8080 -o"
   },
   "keywords": [