mcp-probe-kit 3.0.24 → 3.2.0

package/build/tools/start_doc.js

@@ -0,0 +1,207 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
+/**
+ * start_doc 智能编排工具
+ *
+ * 场景：文档生成
+ * 编排：[检查上下文] → gendoc → genreadme → genapi
+ */
+const PROMPT_TEMPLATE = `# 📖 文档生成编排指南
+
+## 🎯 目标
+
+为项目/代码生成完整的文档
+
+**输入内容**:
+\`\`\`
+{code}
+\`\`\`
+
+---
+
+## 📋 步骤 0: 项目上下文（自动处理）
+
+**操作**:
+1. 检查 \`docs/project-context.md\` 是否存在
+2. **如果不存在**：
+   - 调用 \`init_project_context\` 工具
+   - 等待生成完成
+3. **读取** \`docs/project-context.md\` 内容
+4. 了解项目的文档风格、技术栈
+
+---
+
+## 📝 步骤 1: 生成代码注释
+
+**调用工具**: \`gendoc\`
+
+**参数**:
+\`\`\`json
+{
+  "code": "[代码内容]",
+  "style": "{style}",
+  "lang": "{lang}"
+}
+\`\`\`
+
+**生成内容**:
+- 函数/方法注释
+- 参数说明
+- 返回值说明
+- 使用示例
+
+**产出**: 带注释的代码
+
+---
+
+## 📄 步骤 2: 生成 README
+
+**调用工具**: \`genreadme\`
+
+**参数**:
+\`\`\`json
+{
+  "project_info": "[项目信息或代码]",
+  "style": "standard"
+}
+\`\`\`
+
+**生成内容**:
+- 项目简介
+- 功能特性
+- 安装使用
+- API 说明
+- 贡献指南
+
+**产出**: README.md
+
+---
+
+## 🔌 步骤 3: 生成 API 文档（如适用）
+
+**调用工具**: \`genapi\`
+
+**参数**:
+\`\`\`json
+{
+  "code": "[API 相关代码]",
+  "format": "markdown"
+}
+\`\`\`
+
+**生成内容**:
+- API 端点列表
+- 请求/响应格式
+- 参数说明
+
+**产出**: API 文档
+
+---
+
+## ✅ 完成检查
+
+- [ ] 项目上下文已读取
+- [ ] 代码注释已生成
+- [ ] README 已生成
+- [ ] API 文档已生成（如适用）
+
+---
+
+## 📊 输出汇总
+
+完成后，向用户提供：
+
+### 1. 代码注释
+
+\`\`\`typescript
+/**
+ * [函数描述]
+ * @param {Type} param - [参数说明]
+ * @returns {Type} [返回值说明]
+ * @example
+ * [使用示例]
+ */
+\`\`\`
+
+### 2. README.md
+
+\`\`\`markdown
+# 项目名称
+
+## 简介
+...
+
+## 功能特性
+...
+
+## 快速开始
+...
+
+## API 文档
+...
+
+## 贡献指南
+...
+
+## 许可证
+...
+\`\`\`
+
+### 3. API 文档（如适用）
+
+\`\`\`markdown
+## API 参考
+...
+\`\`\`
+
+### 4. 文档清单
+
+| 文档 | 状态 | 位置 |
+|------|------|------|
+| 代码注释 | ✅ | 源代码中 |
+| README | ✅ | README.md |
+| API 文档 | ✅/- | docs/api.md |
+
+---
+
+*编排工具: MCP Probe Kit - start_doc*
+`;
+export async function startDoc(args) {
+    try {
+        // 智能参数解析，支持自然语言输入
+        const parsedArgs = parseArgs(args, {
+            defaultValues: {
+                code: "",
+                project_info: "",
+                style: "jsdoc",
+                lang: "zh",
+            },
+            primaryField: "code", // 纯文本输入默认映射到 code 字段
+            fieldAliases: {
+                code: ["source", "src", "代码", "content"],
+                project_info: ["info", "project", "项目信息"],
+                style: ["format", "type", "风格", "注释风格"],
+                lang: ["language", "语言"],
+            },
+        });
+        const code = getString(parsedArgs.code) || getString(parsedArgs.project_info);
+        const style = getString(parsedArgs.style) || "jsdoc";
+        const lang = getString(parsedArgs.lang) || "zh";
+        if (!code) {
+            throw new Error("缺少必填参数: code 或 project_info");
+        }
+        const guide = PROMPT_TEMPLATE
+            .replace(/{code}/g, code)
+            .replace(/{style}/g, style)
+            .replace(/{lang}/g, lang);
+        return {
+            content: [{ type: "text", text: guide }],
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `❌ 编排执行失败: ${errorMsg}` }],
+            isError: true,
+        };
+    }
+}

package/build/tools/start_feature.js

@@ -54,114 +54,121 @@ function extractFeatureInfo(input) {
         description: input,
     };
 }
-const PROMPT_TEMPLATE = `# 🚀 新功能开发编排（委托式）
-
-本工具仅生成 **执行计划（steps）**。AI 需要按顺序调用对应工具并落盘文档。
-
-## 🎯 目标
-开发新功能：**{feature_name}**
-功能描述：{description}
-
----
-
-## ✅ 执行计划（按顺序）
-
-### 0) 项目上下文（如缺失）
-**检查**:
-- \`{docs_dir}/project-context.md\`
-- \`{docs_dir}/graph-insights/latest.md\`
-- \`{docs_dir}/graph-insights/latest.json\`
-**缺失则调用**: \`init_project_context\`
-\`\`\`json
-{ "docs_dir": "{docs_dir}", "project_root": "{project_root}" }
-\`\`\`
-
-### 1) 生成功能规格
-**调用**: \`add_feature\`
-\`\`\`json
-{
-  "feature_name": "{feature_name}",
-  "description": "{description}",
-  "docs_dir": "{docs_dir}",
-  "template_profile": "{template_profile}"
-}
-\`\`\`
-**预期输出**:
-- \`{docs_dir}/specs/{feature_name}/requirements.md\`
-- \`{docs_dir}/specs/{feature_name}/design.md\`
-- \`{docs_dir}/specs/{feature_name}/tasks.md\`
-
-### 2) 工作量估算
-**调用**: \`estimate\`
-\`\`\`json
-{
-  "task_description": "实现 {feature_name} 功能：{description}",
-  "code_context": "参考生成的 tasks.md 中的任务列表"
-}
-\`\`\`
-
----
-
-## ✅ 输出汇总（执行完成后）
-1. 规格文档位置: \`{docs_dir}/specs/{feature_name}/\`
-2. 图谱入口: \`{docs_dir}/graph-insights/latest.md\`
-3. 估算结果: 故事点 + 时间区间
-4. 主要风险（如有）
-5. 下一步: 按 tasks.md 开始开发
-
----
-
+const PROMPT_TEMPLATE = `# 🚀 新功能开发编排（委托式）
+
+本工具仅生成 **执行计划（steps）**。AI 需要按顺序调用对应工具并落盘文档。
+
+## 🎯 目标
+开发新功能：**{feature_name}**
+功能描述：{description}
+
+---
+
+## ✅ 执行计划（按顺序）
+
+### 0) 项目上下文（如缺失）
+**检查**:
+- \`{docs_dir}/project-context.md\`
+- \`{docs_dir}/graph-insights/latest.md\`
+- \`{docs_dir}/graph-insights/latest.json\`
+**缺失则调用**: \`init_project_context\`
+\`\`\`json
+{ "docs_dir": "{docs_dir}", "project_root": "{project_root}" }
+\`\`\`
+
+### 1) 生成功能规格
+**调用**: \`add_feature\`
+\`\`\`json
+{
+  "feature_name": "{feature_name}",
+  "description": "{description}",
+  "docs_dir": "{docs_dir}",
+  "template_profile": "{template_profile}"
+}
+\`\`\`
+**预期输出**:
+- \`{docs_dir}/specs/{feature_name}/requirements.md\`
+- \`{docs_dir}/specs/{feature_name}/design.md\`
+- \`{docs_dir}/specs/{feature_name}/tasks.md\`
+
+### 2) 校验规格完整性（闸门）
+**调用**: \`check_spec\`
+\`\`\`json
+{ "feature_name": "{feature_name}", "docs_dir": "{docs_dir}" }
+\`\`\`
+**未通过**：按报告逐条补全 requirements/design/tasks 后**重跑 check_spec**；**通过前不要写实现代码**。
+
+### 3) 工作量估算
+**调用**: \`estimate\`
+\`\`\`json
+{
+  "task_description": "实现 {feature_name} 功能：{description}",
+  "code_context": "参考生成的 tasks.md 中的任务列表"
+}
+\`\`\`
+
+---
+
+## ✅ 输出汇总（执行完成后）
+1. 规格文档位置: \`{docs_dir}/specs/{feature_name}/\`
+2. 图谱入口: \`{docs_dir}/graph-insights/latest.md\`
+3. 估算结果: 故事点 + 时间区间
+4. 主要风险（如有）
+5. 下一步: 按 tasks.md 开始开发
+
+---
+
 *编排工具: MCP Probe Kit - start_feature*`;
-const LOOP_PROMPT_TEMPLATE = `# 🧭 需求澄清与补全（Requirements Loop）
-
-本模式用于**生产级稳健补全**：在不改变用户意图的前提下补齐关键要素，并输出可审计的结构化结果。
-
-## 🎯 目标
-开发新功能：**{feature_name}**  
-功能描述：{description}
-
-## ✅ 规则
-1. **不覆盖用户原始需求**
-2. **补全内容必须标注来源**（User / Derived / Assumption）
-3. **假设必须进入待确认列表**
-4. **每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}**
-
----
-
-## 🔁 执行步骤（每轮）
-
-### 1) 生成待确认问题
-使用 \`ask_user\` 提问，问题来源于“功能需求补全清单”（角色/触发/约束/异常/依赖等）。
-
-**调用示例**:
-\`\`\`json
-{
-  "questions": [
-    { "question": "目标用户或角色是谁？", "context": "角色定义", "required": true },
-    { "question": "触发场景是什么？", "context": "业务场景", "required": true }
-  ]
-}
-\`\`\`
-
-### 2) 更新结构化输出
-将回答补入 \`requirements\`，并标注来源：
-- User：用户明确回答
-- Derived：合理推导
-- Assumption：无法确认但补全（需确认）
-
-### 3) 自检与结束
-若 \`openQuestions\` 为空且无高风险假设，则结束 loop，进入规格生成与估算。
-
----
-
-## ✅ 结束后继续
-当满足结束条件时，执行：
-1. 调用 \`add_feature\` 生成规格文档
-2. 调用 \`estimate\` 进行工作量估算
-
----
-
-*编排工具: MCP Probe Kit - start_feature (requirements loop)*
+const LOOP_PROMPT_TEMPLATE = `# 🧭 需求澄清与补全（Requirements Loop）
+
+本模式用于**生产级稳健补全**：在不改变用户意图的前提下补齐关键要素，并输出可审计的结构化结果。
+
+## 🎯 目标
+开发新功能：**{feature_name}**  
+功能描述：{description}
+
+## ✅ 规则
+1. **不覆盖用户原始需求**
+2. **补全内容必须标注来源**（User / Derived / Assumption）
+3. **假设必须进入待确认列表**
+4. **每轮问题 ≤ {question_budget}，假设 ≤ {assumption_cap}**
+
+---
+
+## 🔁 执行步骤（每轮）
+
+### 1) 生成待确认问题
+使用 \`ask_user\` 提问，问题来源于“功能需求补全清单”（角色/触发/约束/异常/依赖等）。
+
+**调用示例**:
+\`\`\`json
+{
+  "questions": [
+    { "question": "目标用户或角色是谁？", "context": "角色定义", "required": true },
+    { "question": "触发场景是什么？", "context": "业务场景", "required": true }
+  ]
+}
+\`\`\`
+
+### 2) 更新结构化输出
+将回答补入 \`requirements\`，并标注来源：
+- User：用户明确回答
+- Derived：合理推导
+- Assumption：无法确认但补全（需确认）
+
+### 3) 自检与结束
+若 \`openQuestions\` 为空且无高风险假设，则结束 loop，进入规格生成与估算。
+
+---
+
+## ✅ 结束后继续
+当满足结束条件时，执行：
+1. 调用 \`add_feature\` 生成规格文档
+2. 调用 \`estimate\` 进行工作量估算
+
+---
+
+*编排工具: MCP Probe Kit - start_feature (requirements loop)*
 `;
 function buildOpenQuestions(questionBudget) {
     const base = [
@@ -278,18 +285,18 @@ export async function startFeature(args, context) {
         const graphStatusNote = graphContext.available
             ? `任务图谱收敛: 可用（${graphContext.mode}）`
             : "任务图谱收敛: 已降级（自动回退）";
-        const graphGuideSection = `
-
-## 🧠 代码图谱上下文
-- 基线入口: ${graphDocs.latestMarkdownPath}
-- 基线结构化副本: ${graphDocs.latestJsonPath}
-- 基线状态: ${graphDocsMissing ? "缺失（需要补初始化）" : "可用"}
-- 任务级收敛: ${graphContext.available ? "可用" : "降级"}
-- 任务级摘要: ${graphContext.summary}
+        const graphGuideSection = `
+
+## 🧠 代码图谱上下文
+- 基线入口: ${graphDocs.latestMarkdownPath}
+- 基线结构化副本: ${graphDocs.latestJsonPath}
+- 基线状态: ${graphDocsMissing ? "缺失（需要补初始化）" : "可用"}
+- 任务级收敛: ${graphContext.available ? "可用" : "降级"}
+- 任务级摘要: ${graphContext.summary}
 ${graphContext.highlights.length > 0
             ? `- 任务级线索:\n${graphContext.highlights.slice(0, 3).map((item) => `  - ${item}`).join("\n")}`
-            : "- 任务级线索: 无"}
-- 使用方式: 先参考基线图谱，再使用本次任务图谱线索约束模块边界和改动范围
+            : "- 任务级线索: 无"}
+- 使用方式: 先参考基线图谱，再使用本次任务图谱线索约束模块边界和改动范围
 `;
         const estimateCodeContext = [
             `参考生成的 ${docsDir}/specs/${featureName}/tasks.md`,
@@ -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_product.js

@@ -89,7 +89,7 @@ export async function startProduct(args, context) {
             ],
             notes: [buildSkillHeaderNote(skillBridge)],
         });
-        const guidanceText = header + skillBridgeSection + `# 🚀 产品设计工作流执行指导
+        const guidanceText = header + skillBridgeSection + `# 🚀 产品设计工作流执行指导
 
 基于${requirementsSource}，请按照以下步骤完成从需求到 HTML 原型的完整产品设计流程。
 

package/build/tools/start_refactor.d.ts

@@ -0,0 +1,13 @@
+export declare function startRefactor(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;