mcp-probe-kit 1.8.0 → 1.9.0

package/build/tools/start_bugfix.js

@@ -1,3 +1,4 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * start_bugfix 智能编排工具
  *
@@ -101,11 +102,23 @@ const PROMPT_TEMPLATE = `# 🐛 Bug 修复编排指南
 `;
 export async function startBugfix(args) {
     try {
-        const errorMessage = args?.error_message;
+        // 智能参数解析，支持自然语言输入
+        const parsedArgs = parseArgs(args, {
+            defaultValues: {
+                error_message: "",
+                stack_trace: "",
+            },
+            primaryField: "error_message", // 纯文本输入默认映射到 error_message 字段
+            fieldAliases: {
+                error_message: ["error", "err", "message", "错误", "错误信息"],
+                stack_trace: ["stack", "trace", "堆栈", "调用栈"],
+            },
+        });
+        const errorMessage = getString(parsedArgs.error_message);
+        const stackTrace = getString(parsedArgs.stack_trace);
         if (!errorMessage) {
             throw new Error("缺少必填参数: error_message（错误信息）");
         }
-        const stackTrace = args?.stack_trace || "";
         const stackTraceSection = stackTrace
             ? `**堆栈跟踪**:\n\`\`\`\n${stackTrace}\n\`\`\``
             : "";

package/build/tools/start_doc.d.ts

@@ -1,9 +1,3 @@
-/**
- * start_doc 智能编排工具
- *
- * 场景：文档生成
- * 编排：[检查上下文] → gendoc → genreadme → genapi
- */
 export declare function startDoc(args: any): Promise<{
     content: {
         type: string;

package/build/tools/start_doc.js

@@ -1,3 +1,4 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * start_doc 智能编排工具
  *
@@ -166,12 +167,28 @@ const PROMPT_TEMPLATE = `# 📖 文档生成编排指南
 `;
 export async function startDoc(args) {
     try {
-        const code = args?.code || args?.project_info;
+        // 智能参数解析，支持自然语言输入
+        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 style = args?.style || "jsdoc";
-        const lang = args?.lang || "zh";
         const guide = PROMPT_TEMPLATE
             .replace(/{code}/g, code)
             .replace(/{style}/g, style)

package/build/tools/start_feature.d.ts

@@ -1,9 +1,3 @@
-/**
- * start_feature 智能编排工具
- *
- * 场景：开发新功能
- * 编排：[检查上下文] → add_feature → estimate
- */
 export declare function startFeature(args: any): Promise<{
     content: {
         type: string;

package/build/tools/start_feature.js

@@ -1,3 +1,4 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * start_feature 智能编排工具
  *
@@ -95,15 +96,29 @@ const PROMPT_TEMPLATE = `# 🚀 新功能开发编排指南
 `;
 export async function startFeature(args) {
     try {
-        const featureName = args?.feature_name;
-        const description = args?.description;
+        // 智能参数解析，支持自然语言输入
+        const parsedArgs = parseArgs(args, {
+            defaultValues: {
+                feature_name: "",
+                description: "",
+                docs_dir: "docs",
+            },
+            primaryField: "description", // 纯文本输入默认映射到 description 字段
+            fieldAliases: {
+                feature_name: ["name", "feature", "功能名", "功能名称"],
+                description: ["desc", "requirement", "描述", "需求"],
+                docs_dir: ["dir", "output", "目录", "文档目录"],
+            },
+        });
+        const featureName = getString(parsedArgs.feature_name);
+        const description = getString(parsedArgs.description);
+        const docsDir = getString(parsedArgs.docs_dir) || "docs";
         if (!featureName) {
             throw new Error("缺少必填参数: feature_name（功能名称）");
         }
         if (!description) {
             throw new Error("缺少必填参数: description（功能描述）");
         }
-        const docsDir = args?.docs_dir || "docs";
         const guide = PROMPT_TEMPLATE
             .replace(/{feature_name}/g, featureName)
             .replace(/{description}/g, description)

package/build/tools/start_onboard.d.ts

@@ -1,9 +1,3 @@
-/**
- * start_onboard 智能编排工具
- *
- * 场景：快速上手项目
- * 编排：analyze_project → init_project_context
- */
 export declare function startOnboard(args: any): Promise<{
     content: {
         type: string;

package/build/tools/start_onboard.js

@@ -1,3 +1,4 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * start_onboard 智能编排工具
  *
@@ -127,8 +128,20 @@ const PROMPT_TEMPLATE = `# 📚 快速上手编排指南
 `;
 export async function startOnboard(args) {
     try {
-        const projectPath = args?.project_path || ".";
-        const docsDir = args?.docs_dir || "docs";
+        // 智能参数解析，支持自然语言输入
+        const parsedArgs = parseArgs(args, {
+            defaultValues: {
+                project_path: ".",
+                docs_dir: "docs",
+            },
+            primaryField: "project_path", // 纯文本输入默认映射到 project_path 字段
+            fieldAliases: {
+                project_path: ["path", "dir", "directory", "路径", "项目路径"],
+                docs_dir: ["docs", "output", "目录", "文档目录"],
+            },
+        });
+        const projectPath = getString(parsedArgs.project_path) || ".";
+        const docsDir = getString(parsedArgs.docs_dir) || "docs";
         const guide = PROMPT_TEMPLATE
             .replace(/{project_path}/g, projectPath)
             .replace(/{docs_dir}/g, docsDir);

package/build/tools/start_refactor.d.ts

@@ -1,9 +1,3 @@
-/**
- * start_refactor 智能编排工具
- *
- * 场景：代码重构
- * 编排：[检查上下文] → code_review → refactor → gentest
- */
 export declare function startRefactor(args: any): Promise<{
     content: {
         type: string;

package/build/tools/start_refactor.js

@@ -1,3 +1,4 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * start_refactor 智能编排工具
  *
@@ -146,11 +147,23 @@ const PROMPT_TEMPLATE = `# ♻️ 代码重构编排指南
 `;
 export async function startRefactor(args) {
     try {
-        const code = args?.code;
+        // 智能参数解析，支持自然语言输入
+        const parsedArgs = parseArgs(args, {
+            defaultValues: {
+                code: "",
+                goal: "improve_readability",
+            },
+            primaryField: "code", // 纯文本输入默认映射到 code 字段
+            fieldAliases: {
+                code: ["source", "src", "代码", "content"],
+                goal: ["target", "objective", "目标", "重构目标"],
+            },
+        });
+        const code = getString(parsedArgs.code);
+        const goal = getString(parsedArgs.goal) || "improve_readability";
         if (!code) {
             throw new Error("缺少必填参数: code（需要重构的代码）");
         }
-        const goal = args?.goal || "improve_readability";
         const goalDesc = {
             improve_readability: "提高可读性",
             reduce_complexity: "降低复杂度",

package/build/tools/start_release.d.ts

@@ -1,9 +1,3 @@
-/**
- * start_release 智能编排工具
- *
- * 场景：发布准备
- * 编排：[检查上下文] → genchangelog → genpr
- */
 export declare function startRelease(args: any): Promise<{
     content: {
         type: string;

package/build/tools/start_release.js

@@ -1,3 +1,4 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * start_release 智能编排工具
  *
@@ -127,12 +128,26 @@ const PROMPT_TEMPLATE = `# 📦 发布准备编排指南
 `;
 export async function startRelease(args) {
     try {
-        const version = args?.version;
+        // 智能参数解析，支持自然语言输入
+        const parsedArgs = parseArgs(args, {
+            defaultValues: {
+                version: "",
+                from_tag: "上个版本 tag",
+                branch: "",
+            },
+            primaryField: "version", // 纯文本输入默认映射到 version 字段
+            fieldAliases: {
+                version: ["ver", "v", "版本", "版本号"],
+                from_tag: ["from", "start", "起始", "起始版本"],
+                branch: ["分支", "发布分支"],
+            },
+        });
+        const version = getString(parsedArgs.version);
+        const fromTag = getString(parsedArgs.from_tag) || "上个版本 tag";
+        const branch = getString(parsedArgs.branch) || "release/" + version;
         if (!version) {
             throw new Error("缺少必填参数: version（版本号，如 v1.2.0）");
         }
-        const fromTag = args?.from_tag || "上个版本 tag";
-        const branch = args?.branch || "release/" + version;
         const guide = PROMPT_TEMPLATE
             .replace(/{version}/g, version)
             .replace(/{from_tag}/g, fromTag)

package/build/tools/start_review.d.ts

@@ -1,9 +1,3 @@
-/**
- * start_review 智能编排工具
- *
- * 场景：代码体检
- * 编排：[检查上下文] → code_review → security_scan → perf
- */
 export declare function startReview(args: any): Promise<{
     content: {
         type: string;

package/build/tools/start_review.js

@@ -1,3 +1,4 @@
+import { parseArgs, getString } from "../utils/parseArgs.js";
 /**
  * start_review 智能编排工具
  *
@@ -140,11 +141,23 @@ const PROMPT_TEMPLATE = `# 🔍 代码体检编排指南
 `;
 export async function startReview(args) {
     try {
-        const code = args?.code;
+        // 智能参数解析，支持自然语言输入
+        const parsedArgs = parseArgs(args, {
+            defaultValues: {
+                code: "",
+                language: "auto",
+            },
+            primaryField: "code", // 纯文本输入默认映射到 code 字段
+            fieldAliases: {
+                code: ["source", "src", "代码", "content"],
+                language: ["lang", "语言", "编程语言"],
+            },
+        });
+        const code = getString(parsedArgs.code);
+        const language = getString(parsedArgs.language) || "auto";
         if (!code) {
             throw new Error("缺少必填参数: code（需要审查的代码）");
         }
-        const language = args?.language || "auto";
         const guide = PROMPT_TEMPLATE
             .replace(/{code}/g, code)
             .replace(/{language}/g, language);

package/build/utils/parseArgs.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 通用参数解析工具
+ * 支持自然语言输入，让 AI 工具更易用
+ *
+ * 设计理念：
+ * - AI 工具应该接受自然语言，而不是强制 JSON 格式
+ * - 用户可以直接说 "帮我生成 commit 消息" 而不是 {"changes": "..."}
+ * - 智能推断用户意图，自动映射到对应参数
+ */
+/**
+ * 解析工具参数，支持多种格式
+ * @param args - 原始参数（对象、字符串、自然语言等）
+ * @param config - 配置选项
+ * @returns 解析后的参数对象
+ */
+export declare function parseArgs<T extends Record<string, any>>(args: any, config?: {
+    defaultValues?: Partial<T>;
+    primaryField?: string;
+    fieldAliases?: Record<string, string[]>;
+}): T;
+/**
+ * 验证必填参数
+ * @param args - 参数对象
+ * @param requiredFields - 必填字段列表
+ * @throws Error 如果缺少必填参数
+ */
+export declare function validateRequired(args: Record<string, any>, requiredFields: string[]): void;
+/**
+ * 安全地获取字符串参数
+ */
+export declare function getString(value: any, defaultValue?: string): string;
+/**
+ * 安全地获取数字参数
+ */
+export declare function getNumber(value: any, defaultValue?: number): number;
+/**
+ * 安全地获取布尔参数
+ */
+export declare function getBoolean(value: any, defaultValue?: boolean): boolean;

package/build/utils/parseArgs.js

@@ -0,0 +1,153 @@
+/**
+ * 通用参数解析工具
+ * 支持自然语言输入，让 AI 工具更易用
+ *
+ * 设计理念：
+ * - AI 工具应该接受自然语言，而不是强制 JSON 格式
+ * - 用户可以直接说 "帮我生成 commit 消息" 而不是 {"changes": "..."}
+ * - 智能推断用户意图，自动映射到对应参数
+ */
+/**
+ * 解析工具参数，支持多种格式
+ * @param args - 原始参数（对象、字符串、自然语言等）
+ * @param config - 配置选项
+ * @returns 解析后的参数对象
+ */
+export function parseArgs(args, config = {}) {
+    const { defaultValues = {}, primaryField, fieldAliases = {} } = config;
+    let parsedArgs = {};
+    // 1. 处理 null/undefined - 返回默认值
+    if (args === null || args === undefined) {
+        return { ...defaultValues };
+    }
+    // 2. 处理字符串类型 - 最常见的自然语言输入
+    if (typeof args === "string") {
+        const trimmed = args.trim();
+        // 2.1 尝试解析为 JSON（兼容标准格式）
+        if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+            try {
+                parsedArgs = JSON.parse(trimmed);
+            }
+            catch {
+                // JSON 解析失败，当作普通文本处理
+                parsedArgs = mapStringToArgs(trimmed, primaryField, defaultValues);
+            }
+        }
+        // 2.2 检查是否是 key=value 格式（包含 = 且包含 & 或 ,）
+        else if (trimmed.includes("=") && /[&,]/.test(trimmed)) {
+            parsedArgs = parseKeyValueString(trimmed);
+        }
+        // 2.3 纯自然语言 - 智能映射到主字段
+        else {
+            parsedArgs = mapStringToArgs(trimmed, primaryField, defaultValues);
+        }
+    }
+    // 3. 处理对象类型 - 标准 JSON 对象
+    else if (typeof args === "object" && !Array.isArray(args)) {
+        parsedArgs = normalizeObjectKeys(args, fieldAliases);
+    }
+    // 4. 其他类型
+    else {
+        parsedArgs = { value: args };
+    }
+    // 5. 合并默认值
+    return { ...defaultValues, ...parsedArgs };
+}
+/**
+ * 将字符串映射到参数对象
+ * 智能推断用户意图
+ */
+function mapStringToArgs(text, primaryField, defaultValues) {
+    // 如果指定了主字段，直接映射
+    if (primaryField) {
+        return { [primaryField]: text };
+    }
+    // 否则映射到第一个默认值字段
+    const firstKey = Object.keys(defaultValues)[0];
+    if (firstKey) {
+        return { [firstKey]: text };
+    }
+    // 兜底：使用通用字段名
+    return { input: text };
+}
+/**
+ * 解析 key=value 格式的字符串
+ * 例如: "changes=fix bug&type=fixed"
+ */
+function parseKeyValueString(str) {
+    const result = {};
+    // 支持 & 或 , 作为分隔符
+    const pairs = str.split(/[&,]/);
+    for (const pair of pairs) {
+        const [key, ...valueParts] = pair.split("=");
+        if (key) {
+            const value = valueParts.join("=").trim();
+            result[key.trim()] = value || "";
+        }
+    }
+    return result;
+}
+/**
+ * 规范化对象的键名，支持别名映射
+ * 例如: { msg: "..." } -> { message: "..." }
+ */
+function normalizeObjectKeys(obj, aliases) {
+    const result = { ...obj };
+    // 遍历别名映射，将别名转换为标准字段名
+    for (const [standardKey, aliasList] of Object.entries(aliases)) {
+        for (const alias of aliasList) {
+            if (obj[alias] !== undefined && obj[standardKey] === undefined) {
+                result[standardKey] = obj[alias];
+                delete result[alias];
+                break;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 验证必填参数
+ * @param args - 参数对象
+ * @param requiredFields - 必填字段列表
+ * @throws Error 如果缺少必填参数
+ */
+export function validateRequired(args, requiredFields) {
+    const missing = requiredFields.filter((field) => args[field] === undefined || args[field] === null || args[field] === "");
+    if (missing.length > 0) {
+        throw new Error(`缺少必填参数: ${missing.join(", ")}`);
+    }
+}
+/**
+ * 安全地获取字符串参数
+ */
+export function getString(value, defaultValue = "") {
+    if (value === null || value === undefined) {
+        return defaultValue;
+    }
+    return String(value);
+}
+/**
+ * 安全地获取数字参数
+ */
+export function getNumber(value, defaultValue = 0) {
+    if (value === null || value === undefined) {
+        return defaultValue;
+    }
+    const num = Number(value);
+    return isNaN(num) ? defaultValue : num;
+}
+/**
+ * 安全地获取布尔参数
+ */
+export function getBoolean(value, defaultValue = false) {
+    if (value === null || value === undefined) {
+        return defaultValue;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "string") {
+        return value.toLowerCase() === "true" || value === "1";
+    }
+    return Boolean(value);
+}

package/docs/BEST_PRACTICES.md

@@ -112,6 +112,15 @@ fix_bug
 # 工作量估算
 estimate
 然后描述任务："实现用户登录功能"
+
+# 生成 Agent Skills 文档
+gen_skill
+
+# 生成单个工具的技能文档
+gen_skill --tool_name code_review
+
+# 生成分析类工具的技能文档
+gen_skill --scope analysis
 ```
 
 #### 项目管理工具