mcp-probe-kit 1.10.1 → 1.13.0

package/build/schemas/project-tools.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 项目管理工具的 Schema 定义
+ */
+export declare const projectToolSchemas: readonly [{
+    readonly name: "analyze_project";
+    readonly description: "当用户需要了解项目结构、分析项目技术栈时使用。分析项目结构、技术栈、架构模式，输出项目全景报告";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly project_path: {
+                readonly type: "string";
+                readonly description: "项目路径。可选，默认为当前目录";
+            };
+            readonly max_depth: {
+                readonly type: "number";
+                readonly description: "分析深度。可选，默认 5";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "init_project_context";
+    readonly description: "当用户需要生成项目上下文文档、帮助团队快速上手时使用。生成项目上下文文档（技术栈/架构/编码规范），供后续开发参考";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly docs_dir: {
+                readonly type: "string";
+                readonly description: "文档目录。可选，默认 docs";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "add_feature";
+    readonly description: "当用户需要添加新功能、生成功能规格文档时使用。生成新功能规格文档（需求/设计/任务清单），基于项目上下文";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly feature_name: {
+                readonly type: "string";
+                readonly description: "功能名称（kebab-case 格式，如 user-auth）。可选，如果不提供会从 description 自动提取";
+            };
+            readonly description: {
+                readonly type: "string";
+                readonly description: "功能详细描述。可以是简短的自然语言（如'添加用户认证功能'）或详细的需求说明";
+            };
+            readonly docs_dir: {
+                readonly type: "string";
+                readonly description: "文档输出目录，默认为 docs";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "estimate";
+    readonly description: "当用户需要估算开发工作量、评估任务时间时使用。估算开发工作量，输出故事点、时间范围（乐观/正常/悲观）、风险点";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly task_description: {
+                readonly type: "string";
+                readonly description: "任务描述。可以是简短的自然语言（如'估算开发工作量'）或详细的任务说明";
+            };
+            readonly code_context: {
+                readonly type: "string";
+                readonly description: "相关代码或文件上下文。可选，有助于更准确的估算";
+            };
+            readonly team_size: {
+                readonly type: "number";
+                readonly description: "团队规模（人数）。可选，默认为 1";
+            };
+            readonly experience_level: {
+                readonly type: "string";
+                readonly description: "经验水平：junior（初级）、mid（中级）、senior（高级）。可选，默认为 mid";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
+}];

package/build/schemas/project-tools.js

@@ -0,0 +1,89 @@
+/**
+ * 项目管理工具的 Schema 定义
+ */
+export const projectToolSchemas = [
+    {
+        name: "analyze_project",
+        description: "当用户需要了解项目结构、分析项目技术栈时使用。分析项目结构、技术栈、架构模式，输出项目全景报告",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_path: {
+                    type: "string",
+                    description: "项目路径。可选，默认为当前目录",
+                },
+                max_depth: {
+                    type: "number",
+                    description: "分析深度。可选，默认 5",
+                },
+            },
+            required: [],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: "init_project_context",
+        description: "当用户需要生成项目上下文文档、帮助团队快速上手时使用。生成项目上下文文档（技术栈/架构/编码规范），供后续开发参考",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docs_dir: {
+                    type: "string",
+                    description: "文档目录。可选，默认 docs",
+                },
+            },
+            required: [],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: "add_feature",
+        description: "当用户需要添加新功能、生成功能规格文档时使用。生成新功能规格文档（需求/设计/任务清单），基于项目上下文",
+        inputSchema: {
+            type: "object",
+            properties: {
+                feature_name: {
+                    type: "string",
+                    description: "功能名称（kebab-case 格式，如 user-auth）。可选，如果不提供会从 description 自动提取",
+                },
+                description: {
+                    type: "string",
+                    description: "功能详细描述。可以是简短的自然语言（如'添加用户认证功能'）或详细的需求说明",
+                },
+                docs_dir: {
+                    type: "string",
+                    description: "文档输出目录，默认为 docs",
+                },
+            },
+            required: [],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: "estimate",
+        description: "当用户需要估算开发工作量、评估任务时间时使用。估算开发工作量，输出故事点、时间范围（乐观/正常/悲观）、风险点",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task_description: {
+                    type: "string",
+                    description: "任务描述。可以是简短的自然语言（如'估算开发工作量'）或详细的任务说明",
+                },
+                code_context: {
+                    type: "string",
+                    description: "相关代码或文件上下文。可选，有助于更准确的估算",
+                },
+                team_size: {
+                    type: "number",
+                    description: "团队规模（人数）。可选，默认为 1",
+                },
+                experience_level: {
+                    type: "string",
+                    description: "经验水平：junior（初级）、mid（中级）、senior（高级）。可选，默认为 mid",
+                },
+            },
+            required: [],
+            additionalProperties: true,
+        },
+    },
+];

package/build/tools/add_feature.js

@@ -1,4 +1,4 @@
-import { parseArgs, getString, validateRequired } from "../utils/parseArgs.js";
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * add_feature 工具
  *
@@ -12,6 +12,46 @@ import { parseArgs, getString, validateRequired } from "../utils/parseArgs.js";
  */
 // 默认文档目录
 const DEFAULT_DOCS_DIR = "docs";
+/**
+ * 从自然语言输入中提取功能名和描述
+ * @param input - 自然语言输入
+ * @returns 提取的功能名和描述
+ */
+function extractFeatureInfo(input) {
+    // 移除常见的引导词
+    let text = input
+        .replace(/^(添加|实现|开发|创建|新增|生成|构建|做|要|想要|需要|帮我|请|麻烦)/i, "")
+        .trim();
+    // 移除结尾的"功能"、"模块"等词
+    text = text.replace(/(功能|模块|特性|组件|系统|服务)$/i, "").trim();
+    // 如果文本很短（少于20个字符），直接作为功能名
+    if (text.length < 20) {
+        const name = text
+            .toLowerCase()
+            .replace(/[\s\u4e00-\u9fa5]+/g, "-") // 将空格和中文替换为连字符
+            .replace(/[^a-z0-9-]/g, "") // 移除非字母数字和连字符
+            .replace(/-+/g, "-") // 合并多个连字符
+            .replace(/^-|-$/g, ""); // 移除首尾连字符
+        return {
+            name: name || "new-feature",
+            description: input,
+        };
+    }
+    // 如果文本较长，尝试提取关键词作为功能名
+    // 提取前几个关键词
+    const words = text.split(/[\s,，、]+/).filter(w => w.length > 0);
+    const keyWords = words.slice(0, 3).join(" ");
+    const name = keyWords
+        .toLowerCase()
+        .replace(/[\s\u4e00-\u9fa5]+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return {
+        name: name || "new-feature",
+        description: input,
+    };
+}
 // 提示词模板
 const PROMPT_TEMPLATE = `# 添加新功能指南
 
@@ -431,18 +471,41 @@ export async function addFeature(args) {
                 description: "",
                 docs_dir: DEFAULT_DOCS_DIR,
             },
-            primaryField: "description", // 纯文本输入默认映射到 description 字段
+            primaryField: "input", // 纯文本输入默认映射到 input 字段
             fieldAliases: {
                 feature_name: ["name", "feature", "功能名", "功能名称"],
                 description: ["desc", "requirement", "描述", "需求"],
                 docs_dir: ["dir", "output", "目录", "文档目录"],
             },
         });
-        const featureName = getString(parsedArgs.feature_name);
-        const description = getString(parsedArgs.description);
+        let featureName = getString(parsedArgs.feature_name);
+        let description = getString(parsedArgs.description);
         const docsDir = getString(parsedArgs.docs_dir) || DEFAULT_DOCS_DIR;
+        // 如果是纯自然语言输入（input 字段有值但 feature_name 和 description 为空）
+        const input = getString(parsedArgs.input);
+        if (input && !featureName && !description) {
+            // 智能提取功能名和描述
+            // 尝试从自然语言中提取功能名（通常是关键词）
+            const extracted = extractFeatureInfo(input);
+            featureName = extracted.name;
+            description = extracted.description;
+        }
+        // 如果只有 description 没有 feature_name，尝试从 description 提取
+        if (!featureName && description) {
+            const extracted = extractFeatureInfo(description);
+            featureName = extracted.name;
+            if (!description || description === featureName) {
+                description = extracted.description;
+            }
+        }
         // 验证必填参数
-        validateRequired(parsedArgs, ["feature_name", "description"]);
+        if (!featureName || !description) {
+            throw new Error("请提供功能名称和描述。\n\n" +
+                "示例用法：\n" +
+                "- 自然语言：'添加用户认证功能'\n" +
+                "- 详细描述：'实现用户登录、注册和密码重置功能'\n" +
+                "- JSON格式：{\"feature_name\": \"user-auth\", \"description\": \"用户认证功能\"}");
+        }
         // 构建指南文本（替换占位符）
         const guide = PROMPT_TEMPLATE
             .replace(/{feature_name}/g, featureName)

package/build/tools/ask_user.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ask_user - 向用户提问工具
+ * 当 AI 需要更多信息时，可以主动向用户提问
+ */
+export declare function askUser(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/build/tools/ask_user.js

@@ -0,0 +1,124 @@
+/**
+ * ask_user - 向用户提问工具
+ * 当 AI 需要更多信息时，可以主动向用户提问
+ */
+import { parseArgs } from "../utils/parseArgs.js";
+export async function askUser(args) {
+    try {
+        // 解析参数
+        const parsed = parseArgs(args, {
+            primaryField: "question",
+            fieldAliases: {
+                question: ["q", "ask"],
+            },
+        });
+        const question = parsed.question;
+        const questions = parsed.questions;
+        const context = parsed.context;
+        const reason = parsed.reason;
+        if (!question && !questions) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `# ❓ 向用户提问工具
+
+## 使用方法
+
+### 单个问题
+\`\`\`
+ask_user "你希望支持哪些支付方式？"
+\`\`\`
+
+### 多个问题
+\`\`\`
+ask_user --questions [
+  "目标用户是谁？",
+  "预期的并发量是多少？",
+  "有预算限制吗？"
+]
+\`\`\`
+
+### 带上下文的问题
+\`\`\`
+ask_user "是否需要支持移动端？" --context "当前只有 PC 端实现"
+\`\`\`
+
+## 使用场景
+
+- 需求不明确时主动澄清
+- 技术方案选择需要用户决策
+- 发现潜在风险需要确认
+- 需要补充业务背景信息
+
+## 最佳实践
+
+1. **问题要具体** - 避免过于宽泛的问题
+2. **提供上下文** - 说明为什么要问这个问题
+3. **给出选项** - 如果有明确的选项，列出来
+4. **标注重要性** - 区分必答和可选问题`,
+                    },
+                ],
+            };
+        }
+        const lines = [];
+        lines.push("# ❓ AI 需要向你确认一些信息");
+        lines.push("");
+        if (reason) {
+            lines.push(`**提问原因**: ${reason}`);
+            lines.push("");
+        }
+        if (context) {
+            lines.push("## 背景信息");
+            lines.push("");
+            lines.push(context);
+            lines.push("");
+        }
+        lines.push("## 问题");
+        lines.push("");
+        if (questions && questions.length > 0) {
+            // 多个问题
+            for (let i = 0; i < questions.length; i++) {
+                const q = questions[i];
+                const required = q.required !== false ? "**[必答]**" : "_[可选]_";
+                lines.push(`### ${i + 1}. ${q.question} ${required}`);
+                lines.push("");
+                if (q.context) {
+                    lines.push(`_${q.context}_`);
+                    lines.push("");
+                }
+                if (q.options && q.options.length > 0) {
+                    lines.push("**可选项**:");
+                    for (const option of q.options) {
+                        lines.push(`- ${option}`);
+                    }
+                    lines.push("");
+                }
+                lines.push("**你的回答**: ");
+                lines.push("");
+                lines.push("---");
+                lines.push("");
+            }
+        }
+        else if (question) {
+            // 单个问题
+            lines.push(`**${question}**`);
+            lines.push("");
+            lines.push("**你的回答**: ");
+            lines.push("");
+        }
+        lines.push("---");
+        lines.push("");
+        lines.push("💡 **提示**: 请回答上述问题，我会根据你的回答继续工作。");
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `❌ 提问失败: ${errorMsg}` }],
+            isError: true,
+        };
+    }
+}

package/build/tools/css_order.js

@@ -1,61 +1,61 @@
 // css_order 工具实现
 export async function cssOrder(_args) {
     try {
-        const message = `请根据以下规则**书写或重排 CSS**（不是解释规则）。目标是让 CSS 属性顺序更一致、可读、可维护。
-
-如果我提供了 CSS 片段/文件，请直接给出**已按规则整理后的 CSS**；如果没提供，请先让我提供需要处理的 CSS。
-
----
-
-## 排序逻辑（由外向内，由大到小）
-
-将属性分为五类，按顺序排列：
-
-### 1. 定位属性 (Positioning)
-决定元素“在哪里”。
-- \`position\` / \`z-index\` / \`top\` / \`right\` / \`bottom\` / \`left\` / \`float\` / \`clear\`
-
-### 2. 盒子模型 (Box Model)
-决定元素“占多大空间”。
-- \`display\` / \`flex\` / \`grid\` 相关属性
-- \`width\` / \`height\` / \`max-width\` / \`min-width\`
-- \`margin\` / \`padding\` / \`border\`
-- \`box-sizing\` / \`overflow\`
-
-### 3. 文本排版 (Typography)
-决定元素内“文字内容”的样式。
-- \`font-family\` / \`font-size\` / \`font-weight\` / \`line-height\`
-- \`text-align\` / \`text-transform\` / \`text-decoration\` / \`letter-spacing\` / \`white-space\` / \`color\`
-
-### 4. 视觉表现 (Visual/Decoration)
-决定元素“皮肤”的外观。
-- \`background\` / \`box-shadow\` / \`opacity\` / \`visibility\` / \`cursor\` / \`outline\`
-
-### 5. 其他与交互 (Misc/Transitions)
-动效和交互相关。
-- \`transition\` / \`animation\` / \`transform\` / \`will-change\`
-
----
-
-## 处理要求
-
-1. **只调整属性顺序，不改动语义**（除非存在明显重复/冲突属性）。
-2. **保留注释与格式风格**（缩进、空行、选择器顺序不变）。
-3. **同类属性保持原有相对顺序**，除非有明显更合理的排序。
-4. 如果存在 **CSS 变量**（\`--*\`）或自定义属性，放在**当前类的最前**。
-5. 如遇 CSS-in-JS、Tailwind 或非标准语法，**只处理可确定的纯 CSS 属性**。
-
----
-
-## 快速对比表
-
-| 顺序 | 类别 | 常用属性举例 | 核心目的 |
-| --- | --- | --- | --- |
-| **1** | **定位** | \`position\`, \`z-index\`, \`top\` | 确定位置 |
-| **2** | **盒模型** | \`display\`, \`width\`, \`margin\`, \`padding\` | 确定形状和间距 |
-| **3** | **排版** | \`font\`, \`line-height\`, \`color\`, \`text-align\` | 确定内容样式 |
-| **4** | **视觉** | \`background\`, \`border-radius\`, \`box-shadow\` | 确定外观修饰 |
-| **5** | **其他** | \`transition\`, \`transform\`, \`animation\` | 确定动态交互 |
+        const message = `请根据以下规则**书写或重排 CSS**（不是解释规则）。目标是让 CSS 属性顺序更一致、可读、可维护。
+
+如果我提供了 CSS 片段/文件，请直接给出**已按规则整理后的 CSS**；如果没提供，请先让我提供需要处理的 CSS。
+
+---
+
+## 排序逻辑（由外向内，由大到小）
+
+将属性分为五类，按顺序排列：
+
+### 1. 定位属性 (Positioning)
+决定元素“在哪里”。
+- \`position\` / \`z-index\` / \`top\` / \`right\` / \`bottom\` / \`left\` / \`float\` / \`clear\`
+
+### 2. 盒子模型 (Box Model)
+决定元素“占多大空间”。
+- \`display\` / \`flex\` / \`grid\` 相关属性
+- \`width\` / \`height\` / \`max-width\` / \`min-width\`
+- \`margin\` / \`padding\` / \`border\`
+- \`box-sizing\` / \`overflow\`
+
+### 3. 文本排版 (Typography)
+决定元素内“文字内容”的样式。
+- \`font-family\` / \`font-size\` / \`font-weight\` / \`line-height\`
+- \`text-align\` / \`text-transform\` / \`text-decoration\` / \`letter-spacing\` / \`white-space\` / \`color\`
+
+### 4. 视觉表现 (Visual/Decoration)
+决定元素“皮肤”的外观。
+- \`background\` / \`box-shadow\` / \`opacity\` / \`visibility\` / \`cursor\` / \`outline\`
+
+### 5. 其他与交互 (Misc/Transitions)
+动效和交互相关。
+- \`transition\` / \`animation\` / \`transform\` / \`will-change\`
+
+---
+
+## 处理要求
+
+1. **只调整属性顺序，不改动语义**（除非存在明显重复/冲突属性）。
+2. **保留注释与格式风格**（缩进、空行、选择器顺序不变）。
+3. **同类属性保持原有相对顺序**，除非有明显更合理的排序。
+4. 如果存在 **CSS 变量**（\`--*\`）或自定义属性，放在**当前类的最前**。
+5. 如遇 CSS-in-JS、Tailwind 或非标准语法，**只处理可确定的纯 CSS 属性**。
+
+---
+
+## 快速对比表
+
+| 顺序 | 类别 | 常用属性举例 | 核心目的 |
+| --- | --- | --- | --- |
+| **1** | **定位** | \`position\`, \`z-index\`, \`top\` | 确定位置 |
+| **2** | **盒模型** | \`display\`, \`width\`, \`margin\`, \`padding\` | 确定形状和间距 |
+| **3** | **排版** | \`font\`, \`line-height\`, \`color\`, \`text-align\` | 确定内容样式 |
+| **4** | **视觉** | \`background\`, \`border-radius\`, \`box-shadow\` | 确定外观修饰 |
+| **5** | **其他** | \`transition\`, \`transform\`, \`animation\` | 确定动态交互 |
 `;
         return {
             content: [

package/build/tools/index.d.ts

@@ -38,3 +38,6 @@ export { startOnboard } from "./start_onboard.js";
 export { startApi } from "./start_api.js";
 export { startDoc } from "./start_doc.js";
 export { genSkill } from "./gen_skill.js";
+export { startRalph } from "./start_ralph.js";
+export { interview } from "./interview.js";
+export { askUser } from "./ask_user.js";

package/build/tools/index.js

@@ -39,3 +39,7 @@ export { startOnboard } from "./start_onboard.js";
 export { startApi } from "./start_api.js";
 export { startDoc } from "./start_doc.js";
 export { genSkill } from "./gen_skill.js";
+export { startRalph } from "./start_ralph.js";
+// 访谈工具
+export { interview } from "./interview.js";
+export { askUser } from "./ask_user.js";

package/build/tools/interview.d.ts

@@ -0,0 +1,18 @@
+/**
+ * interview - 需求访谈工具
+ * 在开发前通过结构化访谈澄清需求，避免理解偏差
+ * 生成访谈记录文件，供后续 start_feature/add_feature 使用
+ */
+export declare function interview(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;