mcp-probe-kit 1.8.1 → 1.10.0

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/HOW_TO_TRIGGER.html

@@ -179,6 +179,62 @@ table th { background-color: #ddd; font-weight: bold; }
 <p><strong>2. 使用上下文：</strong> "这个方法性能不好，帮我优化" - AI会调用 perf 分析，然后 refactor</p>
 <p><strong>3. 明确范围：</strong> "审查所有API文件" - code_review @api/*.ts</p>
 
+<div class="divider"></div>
+
+<h2>OpenCode / oh-my-opencode 使用</h2>
+
+<h3>配置 MCP</h3>
+<p>在 <code>~/.opencode/mcp.json</code> 中添加：</p>
+<p><code>{ "mcpServers": { "mcp-probe-kit": { "command": "npx", "args": ["mcp-probe-kit@latest"] } } }</code></p>
+
+<h3>命令行调用</h3>
+<p><strong>/tool</strong> - 列出所有可用工具</p>
+<p><strong>/tool code_review</strong> - 调用指定工具</p>
+<p><strong>/mcp</strong> - 查看 MCP 服务器状态</p>
+
+<h3>对话式调用（推荐）</h3>
+<p>直接在对话中使用关键词，AI 会自动调用对应工具：</p>
+<p>"审查这段代码" → code_review</p>
+<p>"debug 这个错误" → debug</p>
+<p>"生成测试" → gentest</p>
+<p>"start_feature 用户登录" → start_feature</p>
+
+<h3>oh-my-opencode 高级功能</h3>
+<p><strong>关键词检测器</strong> - 自动检测提示中的关键词并激活专门模式：</p>
+<table>
+<thead>
+<tr><th>关键词</th><th>模式</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>ultrawork</code> / <code>ulw</code></td><td>最大性能模式</td><td>并行智能体编排</td></tr>
+<tr><td><code>search</code> / <code>find</code></td><td>搜索模式</td><td>并行 explore + librarian 智能体</td></tr>
+<tr><td><code>analyze</code> / <code>investigate</code></td><td>深度分析模式</td><td>多阶段专家咨询</td></tr>
+</tbody>
+</table>
+
+<p><strong>Ralph Loop</strong> - 自引用开发循环，持续运行直到任务完成：</p>
+<p>使用 <code>/ralph-loop "构建一个 REST API"</code> 开始</p>
+<p>结束条件：检测到 &lt;promise&gt;DONE&lt;/promise&gt;、达到最大迭代次数（默认100）或 <code>/cancel-ralph</code></p>
+<p>配置：<code>oh-my-opencode.json</code> 中 <code>{ "ralph_loop": { "enabled": true, "default_max_iterations": 100 } }</code></p>
+
+<h3>常用命令示例</h3>
+<table>
+<thead>
+<tr><th>命令</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>/tool code_review</code></td><td>代码审查</td></tr>
+<tr><td><code>/tool debug</code></td><td>调试分析</td></tr>
+<tr><td><code>/tool gentest</code></td><td>生成测试</td></tr>
+<tr><td><code>/tool gencommit</code></td><td>生成提交信息</td></tr>
+<tr><td><code>/tool start_feature</code></td><td>新功能开发编排</td></tr>
+<tr><td><code>/tool start_review</code></td><td>代码体检编排</td></tr>
+<tr><td><code>/tool start_bugfix</code></td><td>Bug修复编排</td></tr>
+<tr><td><code>ulw 重构这个模块</code></td><td>最大性能模式</td></tr>
+<tr><td><code>/ralph-loop "任务描述"</code></td><td>自引用循环</td></tr>
+</tbody>
+</table>
+
 <div style="text-align:center;margin-top:0.4cm;padding:0.2cm;border-top:1px solid #000;">
 <p style="font-size:10pt;"><strong>MCP Probe Kit v1.8.1 - AI 开发增强工具集（40个工具）</strong></p>
 </div>