mcp-probe-kit 1.10.1 → 1.13.0

package/build/utils/parseArgs.js

@@ -44,7 +44,18 @@ export function parseArgs(args, config = {}) {
     }
     // 3. 处理对象类型 - 标准 JSON 对象
     else if (typeof args === "object" && !Array.isArray(args)) {
-        parsedArgs = normalizeObjectKeys(args, fieldAliases);
+        // 3.1 检查是否有嵌套的 input 字段（MCP 常见格式）
+        // 例如: {"input": {"feature_name": "...", "description": "..."}}
+        if (args.input && typeof args.input === "object" && !Array.isArray(args.input)) {
+            // 展平嵌套结构，优先使用 input 内的字段
+            parsedArgs = { ...args, ...args.input };
+            delete parsedArgs.input; // 移除 input 字段避免冲突
+        }
+        else {
+            parsedArgs = args;
+        }
+        // 3.2 规范化字段名（处理别名）
+        parsedArgs = normalizeObjectKeys(parsedArgs, fieldAliases);
     }
     // 4. 其他类型
     else {

package/docs/BEST_PRACTICES.md

@@ -17,6 +17,40 @@
 
 ## 🎯 工具调用写法指南
 
+### 访谈工具调用 🆕
+
+#### interview - 需求访谈
+
+```
+# 方式 1：直接调用
+interview "用户登录认证功能"
+
+# 方式 2：对话式
+interview
+然后 AI 会询问功能描述
+
+# 自动完成：
+# ✓ 生成 12-15 个结构化问题（4个阶段）
+# ✓ 保存访谈记录到 docs/interviews/
+# ✓ 可选：立即开发或稍后使用
+```
+
+#### ask_user - AI 主动提问
+
+```
+# AI 自动调用（遇到不确定因素时）
+ask_user "优化目标是性能还是可读性？"
+
+# 用户主动触发
+"有什么需要我确认的吗？"
+"问我几个问题吧"
+
+# 带选项的提问
+ask_user --options ["方案A: 性能优先", "方案B: 可读性优先"]
+```
+
+---
+
 ### 基础工具调用
 
 #### 代码质量工具
@@ -284,10 +318,116 @@ start_doc @src/
 # ✓ 生成 API 文档
 ```
 
+#### start_ralph - Ralph Loop 循环开发（推荐）🆕
+
+```
+# 启动循环开发
+start_ralph "实现用户登录功能"
+
+# 指定模式和参数
+start_ralph --goal "修复登录 bug" --mode safe --max_iterations 10
+
+# 自动完成：
+# ✓ 生成 .ralph/ 目录结构
+# ✓ 生成 PROMPT.md（循环 prompt）
+# ✓ 生成 @fix_plan.md（任务清单）
+# ✓ 生成 PROGRESS.md（迭代日志）
+# ✓ 生成安全模式脚本（多重保护）
+# ✓ 提供执行指南
+
+# 然后：
+cd .ralph
+chmod +x ralph_loop_safe.sh  # Linux/Mac
+./ralph_loop_safe.sh
+
+# Windows:
+# powershell -ExecutionPolicy Bypass -File ralph_loop_safe.ps1
+```
+
 ---
 
 ## 💡 使用技巧
 
+### 0. Interview 模式最佳实践 🆕
+
+#### 何时使用 Interview 模式
+
+**✅ 推荐使用：**
+```
+- 需求描述简短、不明确
+- 复杂的业务功能
+- 涉及多方协作的功能
+- 有较多技术约束的功能
+- 第一次做某类功能
+```
+
+**❌ 不推荐使用：**
+```
+- 简单的 Bug 修复
+- 需求非常明确的功能
+- 紧急的小改动
+- 重复性的简单任务
+```
+
+#### Interview 工作流程
+
+**流程 1：立即开发**
+```
+1. interview "用户登录功能"
+   # 生成 12-15 个问题
+
+2. 回答所有问题
+   # AI 生成访谈记录
+
+3. start_feature --from-interview user-login
+   # 基于访谈生成规格文档
+
+4. 根据 tasks.md 开始编码
+```
+
+**流程 2：分步进行**
+```
+第1天:
+1. interview "用户登录功能"
+2. 回答问题
+3. AI 保存访谈记录
+
+第3天:
+1. "开始做登录功能"
+2. start_feature --from-interview user-login
+3. AI 读取之前的访谈，生成规格
+```
+
+**流程 3：仅生成规格**
+```
+1. interview "用户登录功能"
+2. 回答问题
+3. add_feature --from-interview user-login
+   # 只生成规格文档，不估算工作量
+```
+
+#### ask_user 使用场景
+
+```
+场景1: 技术方案选择
+AI: "可以用两种方案实现"
+调用: ask_user --options ["方案A: 性能优先", "方案B: 可读性优先"]
+
+场景2: 代码审查时
+AI: "发现了性能问题，但不确定优先级"
+调用: ask_user "这个性能问题的优先级如何？"
+
+场景3: Bug 修复时
+AI: "需要确认是否向后兼容"
+调用: ask_user "修复这个 Bug 是否需要保持向后兼容？"
+
+场景4: 功能开发时
+AI: "支付方式有多种选择"
+调用: ask_user "你希望支持哪些支付方式？"
+```
+
+---
+
 ### 1. 优先使用智能编排
 
 **❌ 不推荐（手动调用多个工具）**
@@ -349,7 +489,30 @@ interface User {
 
 ### 4. 组合使用工具
 
-#### 场景：开发新功能的完整流程
+#### 场景：Interview 模式开发新功能 🆕
+
+```
+1. interview "用户个人资料"
+   # 访谈澄清需求
+
+2. 回答 12-15 个问题
+
+3. start_feature --from-interview user-profile
+   # 生成规格文档和估算
+
+4. 根据 tasks.md 开始编码...
+
+5. start_review @src/profile/
+   # 代码体检
+
+6. gentest @src/profile/ProfileCard.tsx
+   # 补充测试
+
+7. gencommit
+   # 提交代码
+```
+
+#### 场景：传统方式开发新功能
 
 ```
 1. start_feature user-profile "用户个人资料"
@@ -591,7 +754,10 @@ start_refactor @code.ts --goal reduce_complexity
 ```
 需要做什么？
 │
-├─ 开发新功能
+├─ 需求不明确？
+│  └─ interview ✅ → 访谈澄清 → start_feature
+│
+├─ 开发新功能（需求明确）
 │  └─ start_feature ✅
 │
 ├─ 修复 Bug
@@ -632,22 +798,50 @@ start_refactor @code.ts --goal reduce_complexity
 
 | 命令 | 用途 | 频率 |
 |------|------|------|
+| `interview` | 需求访谈 | ⭐⭐⭐⭐⭐ 🆕 |
 | `start_feature` | 开发新功能 | ⭐⭐⭐⭐⭐ |
 | `start_bugfix` | 修复 Bug | ⭐⭐⭐⭐⭐ |
+| `start_ralph` | 循环开发 | ⭐⭐⭐⭐ 🆕 |
 | `start_review` | 代码体检 | ⭐⭐⭐⭐ |
 | `gencommit` | 生成提交 | ⭐⭐⭐⭐ |
 | `gentest` | 生成测试 | ⭐⭐⭐⭐ |
+| `ask_user` | AI 提问 | ⭐⭐⭐ 🆕 |
 | `start_onboard` | 快速上手 | ⭐⭐⭐ |
 | `start_refactor` | 代码重构 | ⭐⭐⭐ |
-| `check_deps` | 检查依赖 | ⭐⭐⭐ |
-| `start_release` | 准备发布 | ⭐⭐ |
-| `start_api` | API 开发 | ⭐⭐ |
 
 ---
 
 ## 💬 实际对话示例
 
-### 示例 1：开发新功能
+### 示例 1：Interview 模式开发新功能 🆕
+
+```
+你: interview "用户设置页面"
+
+AI: 好的，我来帮你访谈这个需求。
+
+[阶段 1: 背景理解]
+Q1: 这个功能要解决什么问题或痛点？
+Q2: 主要用户是谁？他们的使用场景是什么？
+Q3: 这个功能的业务驱动是什么？
+
+[阶段 2: 功能边界]
+Q4: 这个功能的核心价值是什么？
+Q5: 功能范围包括哪些？不包括哪些？
+...
+
+你: [回答所有问题]
+
+AI: 好的，访谈完成。
+✓ 已生成 docs/interviews/user-settings-interview.md
+
+下一步：
+- 立即开发: start_feature --from-interview user-settings
+- 生成规格: add_feature --from-interview user-settings
+- 稍后开发: 访谈记录已保存，随时可用
+```
+
+### 示例 2：开发新功能（需求明确）
 
 ```
 你: start_feature user-settings "用户设置页面"

package/docs/HOW_TO_TRIGGER.html

@@ -28,7 +28,11 @@ table th { background-color: #ddd; font-weight: bold; }
 <body>
 <h1>MCP 工具触发快速手册</h1>
 
-<h2>基础工具（32个）</h2>
+<h2>基础工具（34个）</h2>
+
+<h3>需求访谈（2个）🆕</h3>
+<p><strong>interview</strong> <span class="keyword">访谈</span><span class="keyword">需求不明确</span><span class="keyword">想清楚</span> | "interview 用户认证功能" "先把需求想清楚"</p>
+<p><strong>ask_user</strong> <span class="keyword">提问</span><span class="keyword">确认</span><span class="keyword">澄清</span> | AI会自动调用，用户也可主动触发</p>
 
 <h3>代码质量（8个）</h3>
 <p><strong>detect_shell</strong> <span class="keyword">套壳</span><span class="keyword">检测</span> | "detect_shell"</p>
@@ -67,6 +71,8 @@ table th { background-color: #ddd; font-weight: bold; }
 <p><strong>analyze_project</strong> <span class="keyword">项目分析</span> | "analyze_project" "分析项目结构"</p>
 <p><strong>init_project_context</strong> <span class="keyword">项目上下文</span> | "init_project_context"</p>
 <p><strong>add_feature</strong> <span class="keyword">添加功能</span> | "add_feature user-auth '用户认证'"</p>
+<p><strong>interview</strong> <span class="keyword">访谈</span><span class="keyword">需求不明确</span> | "interview 用户认证功能"</p>
+<p><strong>ask_user</strong> <span class="keyword">提问</span><span class="keyword">确认</span> | AI主动提问工具</p>
 
 <div class="divider"></div>
 
@@ -88,6 +94,9 @@ table th { background-color: #ddd; font-weight: bold; }
 <p><strong>start_api</strong> <span class="keyword">API开发</span><span class="keyword">接口开发</span> | "为这个API生成完整资料" | 自动：上下文-文档-Mock-测试</p>
 <p><strong>start_doc</strong> <span class="keyword">完整文档</span> | "生成完整文档" | 自动：上下文-注释-README-API</p>
 
+<h3>循环开发类（1个）🆕</h3>
+<p><strong>start_ralph</strong> <span class="keyword">Ralph Loop</span><span class="keyword">循环开发</span><span class="keyword">迭代开发</span> | "start_ralph 实现用户登录功能" | 自动：生成环境-安全脚本-多轮迭代</p>
+
 <div class="divider"></div>
 
 <h2>快速触发技巧</h2>
@@ -136,6 +145,8 @@ table th { background-color: #ddd; font-weight: bold; }
 <tr><td>项目分析</td><td>项目分析、分析项目</td><td><code>analyze_project</code></td></tr>
 <tr><td>项目上下文</td><td>项目上下文</td><td><code>init_project_context</code></td></tr>
 <tr><td>添加功能</td><td>添加功能、新功能规格</td><td><code>add_feature</code></td></tr>
+<tr><td>需求访谈</td><td>访谈、需求不明确、想清楚</td><td><code>interview</code> 🆕</td></tr>
+<tr><td>AI提问</td><td>提问、确认、澄清</td><td><code>ask_user</code> 🆕</td></tr>
 </tbody>
 </table>
 
@@ -151,6 +162,7 @@ table th { background-color: #ddd; font-weight: bold; }
 <tr><td>代码体检</td><td><code>start_review</code> ***</td><td>上下文-审查-安全-性能</td></tr>
 <tr><td>完整重构</td><td><code>start_refactor</code> ***</td><td>上下文-审查-重构-测试</td></tr>
 <tr><td>准备发布</td><td><code>start_release</code> ***</td><td>上下文-Changelog-PR</td></tr>
+<tr><td>Ralph Loop</td><td><code>start_ralph</code> *** 🆕</td><td>生成环境-安全脚本-多轮迭代</td></tr>
 <tr><td>API开发</td><td><code>start_api</code> **</td><td>上下文-文档-Mock-测试</td></tr>
 <tr><td>生成文档</td><td><code>start_doc</code> **</td><td>上下文-注释-README-API</td></tr>
 </tbody>
@@ -236,7 +248,7 @@ table th { background-color: #ddd; font-weight: bold; }
 </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>
+<p style="font-size:10pt;"><strong>MCP Probe Kit v1.12.0 - AI 开发增强工具集（42个工具）</strong></p>
 </div>
 
 </body>

package/docs/HOW_TO_TRIGGER.md

@@ -26,6 +26,45 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ## 🔑 工具触发关键词
 
+### 🆕 0️⃣ 需求访谈 → `interview` / `ask_user`
+
+**触发关键词**：访谈、需求不明确、想清楚、澄清需求、提问、确认
+
+#### `interview` - 结构化访谈
+
+**✅ 推荐说法**
+```
+"我想做登录功能"（需求不明确时）
+"interview 用户认证功能"
+"帮我访谈一下这个需求"
+"先把需求想清楚再开发"
+"需求不太明确，先访谈一下"
+```
+
+**使用场景**
+- 需求描述简短、不明确
+- 复杂的业务功能
+- 涉及多方协作
+- 有较多技术约束
+
+#### `ask_user` - AI 主动提问
+
+**✅ AI 会自动调用**
+```
+当 AI 遇到不确定因素时会主动提问：
+"优化目标是性能还是可读性？"
+"是否需要向后兼容？"
+"你希望支持哪些支付方式？"
+```
+
+**用户也可以主动触发**
+```
+"有什么需要我确认的吗？"
+"问我几个问题吧"
+```
+
+---
+
 ### 1️⃣ 调试问题 → `debug`
 
 **触发关键词**：调试、debug、分析错误、为什么报错、bug、问题
@@ -232,26 +271,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ---
 
-### 1️⃣1️⃣ 代码转换 → `convert`
-
-**触发关键词**：转换、改成、转为、迁移
-
-**✅ 推荐说法**
-```
-"把这个转成 TypeScript"
-"Class 组件改成 Hooks"
-"转换成 ES6 语法"
-"迁移到 Vue 3"
-```
-
-**❌ 不推荐说法**
-```
-"换一下"（没说换成什么）
-```
-
----
-
-### 1️⃣2️⃣ 生成 Mock 数据 → `gen_mock`
+### 1️⃣1️⃣ 生成 Mock 数据 → `gen_mock`
 
 **触发关键词**：Mock、模拟数据、假数据、测试数据
 
@@ -270,97 +290,97 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ---
 
-### 1️⃣3️⃣ Bug 修复流程 → `fix_bug`
+### 1️⃣2️⃣ 生成 Agent Skills → `gen_skill`
 
-**触发关键词**：修复 Bug、Bug 修复、解决问题、修这个错误
+**触发关键词**：Skills、技能文档、Agent Skills、SKILL.md
 
 **✅ 推荐说法**
 ```
-"修复这个 Bug"
-"帮我解决这个错误"
-"fix_bug 这个问题"
-"完整修复这个 Bug"
+"生成 Agent Skills 文档"
+"gen_skill"
+"生成技能文档"
+"为 code_review 生成 SKILL.md"
 ```
 
 **❌ 不推荐说法**
 ```
-"搞定这个"（意图不明）
+"生成文档"（太笼统，可能调用其他工具）
 ```
 
 ---
 
-### 1️⃣4️⃣ 工作量估算 → `estimate`
+### 1️⃣3️⃣ 代码转换 → `convert`
 
-**触发关键词**：估算、工作量、需要多久、故事点
+**触发关键词**：转换、改成、转为、迁移
 
 **✅ 推荐说法**
 ```
-"估算工作量"
-"这个任务需要多久"
-"评估开发时间"
-"给个故事点估算"
+"把这个转成 TypeScript"
+"Class 组件改成 Hooks"
+"转换成 ES6 语法"
+"迁移到 Vue 3"
 ```
 
 **❌ 不推荐说法**
 ```
-"要多久"（太简短）
+"换一下"（没说换成什么）
 ```
 
 ---
 
-### 1️⃣5️⃣ 生成 SQL → `gensql`
+### 1️⃣4️⃣ Bug 修复流程 → `fix_bug`
 
-**触发关键词**：SQL、查询、数据库、建表
+**触发关键词**：修复 Bug、Bug 修复、解决问题、修这个错误
 
 **✅ 推荐说法**
 ```
-"生成 SQL 查询"
-"写个查询语句"
-"创建数据库表"
-"查询最近30天的用户"
+"修复这个 Bug"
+"帮我解决这个错误"
+"fix_bug 这个问题"
+"完整修复这个 Bug"
 ```
 
 **❌ 不推荐说法**
 ```
-"查一下"（没说要生成 SQL）
+"搞定这个"（意图不明）
 ```
 
 ---
 
-### 1️⃣6️⃣ 生成 Agent Skills → `gen_skill`
+### 1️⃣5️⃣ 工作量估算 → `estimate`
 
-**触发关键词**：Skills、技能文档、Agent Skills、SKILL.md
+**触发关键词**：估算、工作量、需要多久、故事点
 
 **✅ 推荐说法**
 ```
-"生成 Agent Skills 文档"
-"gen_skill"
-"生成技能文档"
-"为 code_review 生成 SKILL.md"
+"估算工作量"
+"这个任务需要多久"
+"评估开发时间"
+"给个故事点估算"
 ```
 
 **❌ 不推荐说法**
 ```
-"生成文档"（太笼统，可能调用其他工具）
+"要多久"（太简短）
 ```
 
 ---
 
-### 1️⃣7️⃣ 生成 UI 组件 → `genui`
+### 1️⃣6️⃣ 生成 SQL → `gensql`
 
-**触发关键词**：组件、UI、界面、按钮、表单
+**触发关键词**：SQL、查询、数据库、建表
 
 **✅ 推荐说法**
 ```
-"生成一个 Button 组件"
-"创建登录表单"
-"写个 Modal 组件"
-"生成用户卡片 UI"
+"生成 SQL 查询"
+"写个查询语句"
+"创建数据库表"
+"查询最近30天的用户"
 ```
 
 **❌ 不推荐说法**
 ```
-"做个界面"（没说具体是什么）
+"查一下"（没说要生成 SQL）
 ```
 
 ---
@@ -405,8 +425,6 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ---
 
----
-
 ## 🚀 智能编排工具触发
 
 > 智能编排工具自动组合多个基础工具，一键完成复杂工作流
@@ -415,7 +433,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 #### 🎯 开发流程类
 
-####### 1️⃣7️⃣ 新功能开发 → `start_feature`
+##### 1️⃣9️⃣ 新功能开发 → `start_feature`
 
 **触发关键词**：新功能、开发功能、添加功能、实现功能、feature
 
@@ -438,7 +456,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ---
 
-##### 1️⃣8️⃣ Bug 修复编排 → `start_bugfix`
+##### 2️⃣0️⃣ Bug 修复编排 → `start_bugfix`
 
 **触发关键词**：修 Bug、Bug 修复、解决错误、完整修复、bugfix
 
@@ -460,7 +478,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ---
 
-##### 2️⃣2️⃣ 快速上手 → `start_onboard`
+##### 2️⃣3️⃣ 快速上手 → `start_onboard`
 
 **触发关键词**：了解项目、快速上手、分析项目、onboard、接手项目
 
@@ -485,7 +503,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 #### 🔍 质量保障类
 
-##### 1️⃣9️⃣ 代码体检 → `start_review`
+##### 2️⃣1️⃣ 代码体检 → `start_review`
 
 **触发关键词**：全面审查、代码体检、完整检查、全面检查、review
 
@@ -532,7 +550,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 #### 📦 发布管理类
 
-##### 2️⃣0️⃣ 发布准备 → `start_release`
+##### 2️⃣4️⃣ 发布准备 → `start_release`
 
 **触发关键词**：发布、release、准备发布、版本发布
 
@@ -556,7 +574,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 #### 📝 文档生成类
 
-##### 2️⃣3️⃣ API 开发 → `start_api`
+##### 2️⃣5️⃣ API 开发 → `start_api`
 
 **触发关键词**：API 开发、接口开发、API 资料、接口文档
 
@@ -578,7 +596,7 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ---
 
-##### 2️⃣4️⃣ 文档生成 → `start_doc`
+##### 2️⃣6️⃣ 文档生成 → `start_doc`
 
 **触发关键词**：生成完整文档、项目文档、全套文档
 
@@ -600,6 +618,41 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ---
 
+##### 2️⃣7️⃣ Ralph Loop 循环开发 → `start_ralph` 🆕
+
+**触发关键词**：Ralph Loop、循环开发、迭代开发、自动循环、多轮开发
+
+**自动执行**：生成 .ralph/ 目录 → 安全模式脚本 → 执行指南
+
+**✅ 推荐说法**
+```
+"start_ralph 实现用户登录功能"
+"用 Ralph Loop 开发这个功能"
+"启动循环开发模式"
+"ralph 模式修复这个 bug"
+"创建 Ralph Loop 环境"
+```
+
+**❌ 不推荐说法**
+```
+"循环一下"（意图不明）
+"自动开发"（太笼统）
+```
+
+**使用场景**
+- 需要多轮迭代的复杂功能
+- Bug 修复需要多次尝试
+- 代码重构需要小步快跑
+- 测试驱动开发（TDD）流程
+
+**安全特性**
+- 默认安全模式（多重保护）
+- 人工确认（每轮确认）
+- 紧急停止（STOP 文件）
+- 失控保护（重复检测、变更量检测）
+
+---
+
 ### 🎯 智能编排 vs 基础工具
 
 | 场景 | 基础工具 | 智能编排 | 推荐 |
@@ -908,6 +961,7 @@ AI: [自动调用 start_review 编排]
 | 你想做什么 | 关键词 | 调用的工具 | 自动执行 |
 |-----------|--------|-----------|----------|
 | 准备发布 | 发布、release、版本发布 | `start_release` ⭐⭐⭐ | 上下文 → Changelog → PR |
+| Ralph Loop | 循环开发、迭代开发、ralph | `start_ralph` ⭐⭐⭐ 🆕 | 生成环境 → 安全脚本 → 多轮迭代 |
 
 #### 📝 文档生成类
 
@@ -995,6 +1049,13 @@ AI: [自动调用 start_review 编排]
 "全面检查这个模块的代码质量"
 ```
 
+### Ralph Loop 循环开发 🆕
+```
+"start_ralph 实现用户登录功能"
+"用 Ralph Loop 修复这个 bug"
+"启动循环开发模式"
+```
+
 ---
 
 ## 🎯 记住这些要点