mcp-probe-kit 1.10.1 → 1.13.0

package/docs/MCP-Probe-Kit-/344/275/277/347/224/250/346/211/213/345/206/214.md

@@ -1,5 +1,78 @@
 # MCP Probe Kit 工具使用手册
 
+## 🎯 需求访谈工具 🆕
+
+### 1. interview - 需求访谈模式
+**用途：** 在开发前通过结构化访谈澄清需求，避免理解偏差
+
+**核心理念：** 先慢下来，把问题想清楚，反而能更快地交付正确的解决方案
+
+**提问示例：**
+- "interview 用户登录功能"
+- "帮我访谈一下这个需求：商品推荐系统"
+- "需求不太明确，先访谈一下"
+
+**参数说明：**
+- `description`: 功能描述（必填）
+- `context`: 补充背景（可选）
+
+**访谈内容：**
+- **阶段 1**: 背景理解（3个问题）- 痛点、用户、业务驱动
+- **阶段 2**: 功能边界（4个问题）- 核心价值、范围、输入输出
+- **阶段 3**: 技术约束（4个问题）- 技术栈、性能、兼容性、安全
+- **阶段 4**: 验收标准（3个问题）- 成功标准、测试场景、效果衡量
+
+**工作流程：**
+```
+1. AI 生成 12-15 个结构化问题
+2. 用户回答所有问题
+3. AI 生成访谈记录 docs/interviews/{feature-name}-interview.md
+4. 用户选择：
+   - 立即开发: start_feature --from-interview {feature-name}
+   - 生成规格: add_feature --from-interview {feature-name}
+   - 稍后开发: 访谈记录已保存，随时可用
+```
+
+**适用场景：**
+- ✅ 需求不明确的新功能
+- ✅ 复杂的业务功能
+- ✅ 涉及多方协作的功能
+- ❌ 简单的 Bug 修复
+- ❌ 需求非常明确的功能
+
+---
+
+### 2. ask_user - AI 主动提问
+**用途：** AI 可在任何时候向用户提问，澄清不确定的信息
+
+**提问示例：**
+- AI 会自动调用（当遇到不确定因素时）
+- 用户也可主动触发："有什么需要我确认的吗？"
+
+**参数说明：**
+- `question`: 问题内容（必填）
+- `questions`: 多个问题列表（可选）
+- `options`: 选项列表（可选）
+- `context`: 问题背景（可选）
+- `required`: 是否必答（可选）
+
+**使用场景：**
+```
+场景1: 代码审查时
+AI: "发现了性能问题，但不确定优先级"
+调用: ask_user "这个性能问题的优先级如何？是否需要立即优化？"
+
+场景2: 技术方案选择
+AI: "可以用两种方案，不确定你的偏好"
+调用: ask_user --options ["方案A: 性能优先", "方案B: 可读性优先"]
+
+场景3: Bug 修复时
+AI: "需要确认是否向后兼容"
+调用: ask_user "修复这个 Bug 是否需要保持向后兼容？"
+```
+
+---
+
 ## 📋 基础生成工具
 
 ### 1. gencommit - 生成 Git 提交信息
@@ -146,9 +219,41 @@
 
 ---
 
+### 11. gen_skill - 生成 Agent Skills 文档
+**用途：** 为工具生成技能文档
+
+**提问示例：**
+- "生成所有工具的技能文档"
+- "为 code_review 生成 SKILL.md"
+- "导出工具使用说明"
+
+**参数说明：**
+- `scope`: all/basic/generation/analysis（可选）
+- `tool_name`: 指定工具名称（可选）
+- `lang`: zh/en
+- `output_dir`: 输出目录（可选）
+
+---
+
+### 12. design2code - 设计稿转代码
+**用途：** 将设计稿转换为前端代码
+
+**提问示例：**
+- "根据这个设计稿生成代码：[图片 URL]"
+- "把这个 UI 转成 Vue 组件"
+- "实现这个页面布局：[描述或图片]"
+
+**参数说明：**
+- `input`: 图片 URL/base64/HTML/描述（必填）
+- `framework`: vue/react
+- `component_type`: page/component
+- `style_solution`: tailwind/css-modules/styled-components
+
+---
+
 ## 🔍 分析诊断工具
 
-### 11. debug - 错误调试分析
+### 1. debug - 错误调试分析
 **用途：** 分析错误信息，定位问题根因
 
 **提问示例：**
@@ -162,7 +267,7 @@
 
 ---
 
-### 12. code_review - 代码审查
+### 2. code_review - 代码审查
 **用途：** 审查代码质量、安全性、性能
 
 **提问示例：**
@@ -176,7 +281,7 @@
 
 ---
 
-### 13. security_scan - 安全扫描
+### 3. security_scan - 安全扫描
 **用途：** 专项安全漏洞检测
 
 **提问示例：**
@@ -190,7 +295,7 @@
 
 ---
 
-### 14. perf - 性能分析
+### 4. perf - 性能分析
 **用途：** 分析性能瓶颈
 
 **提问示例：**
@@ -204,7 +309,7 @@
 
 ---
 
-### 15. check_deps - 依赖检查
+### 5. check_deps - 依赖检查
 **用途：** 检查依赖健康度和安全漏洞
 
 **提问示例：**
@@ -216,7 +321,7 @@
 
 ---
 
-### 16. explain - 代码解释
+### 6. explain - 代码解释
 **用途：** 解释代码逻辑和实现原理
 
 **提问示例：**
@@ -230,7 +335,7 @@
 
 ---
 
-### 17. analyze_project - 项目分析
+### 7. analyze_project - 项目分析
 **用途：** 分析项目结构、技术栈、架构
 
 **提问示例：**
@@ -247,7 +352,7 @@
 
 ## 🔧 重构优化工具
 
-### 18. refactor - 重构建议
+### 1. refactor - 重构建议
 **用途：** 提供代码重构方案
 
 **提问示例：**
@@ -261,7 +366,7 @@
 
 ---
 
-### 19. fix - 自动修复
+### 2. fix - 自动修复
 **用途：** 自动修复 Lint/格式化/类型错误
 
 **提问示例：**
@@ -275,7 +380,7 @@
 
 ---
 
-### 20. convert - 代码转换
+### 3. convert - 代码转换
 **用途：** 转换代码格式或框架
 
 **提问示例：**
@@ -290,7 +395,7 @@
 
 ---
 
-### 21. split - 文件拆分
+### 4. split - 文件拆分
 **用途：** 拆分大文件为小模块
 
 **提问示例：**
@@ -304,7 +409,7 @@
 
 ---
 
-### 22. resolve_conflict - 解决冲突
+### 5. resolve_conflict - 解决冲突
 **用途：** 分析并解决 Git 合并冲突
 
 **提问示例：**
@@ -317,7 +422,7 @@
 
 ---
 
-### 23. design2code - 设计稿转代码
+### 6. design2code - 设计稿转代码
 **用途：** 将设计稿转换为前端代码
 
 **提问示例：**
@@ -335,7 +440,7 @@
 
 ## 🎯 工作流编排工具
 
-### 24. start_feature - 新功能开发流程
+### 1. start_feature - 新功能开发流程
 **用途：** 完整的新功能开发编排
 
 **提问示例：**
@@ -352,7 +457,7 @@
 
 ---
 
-### 25. start_bugfix - Bug 修复流程
+### 2. start_bugfix - Bug 修复流程
 **用途：** 完整的 Bug 修复编排
 
 **提问示例：**
@@ -368,7 +473,7 @@
 
 ---
 
-### 26. start_review - 代码全面体检
+### 3. start_review - 代码全面体检
 **用途：** 代码审查 + 安全扫描 + 性能分析
 
 **提问示例：**
@@ -382,7 +487,7 @@
 
 ---
 
-### 27. start_release - 发布准备流程
+### 4. start_release - 发布准备流程
 **用途：** 生成 Changelog + PR 描述
 
 **提问示例：**
@@ -397,7 +502,7 @@
 
 ---
 
-### 28. start_refactor - 重构流程
+### 5. start_refactor - 重构流程
 **用途：** 审查现状 → 重构建议 → 生成测试
 
 **提问示例：**
@@ -411,7 +516,7 @@
 
 ---
 
-### 29. start_onboard - 快速上手流程
+### 6. start_onboard - 快速上手流程
 **用途：** 分析项目 → 生成上下文文档
 
 **提问示例：**
@@ -425,7 +530,7 @@
 
 ---
 
-### 30. start_api - API 开发流程
+### 7. start_api - API 开发流程
 **用途：** 生成文档 → 生成 Mock → 生成测试
 
 **提问示例：**
@@ -440,7 +545,7 @@
 
 ---
 
-### 31. start_doc - 文档补全流程
+### 8. start_doc - 文档补全流程
 **用途：** 注释 → README → API 文档
 
 **提问示例：**
@@ -455,9 +560,137 @@
 
 ---
 
+### 9. start_ralph - Ralph Wiggum Loop 循环开发 🆕
+**用途：** 生成 Ralph Loop 工作目录和安全模式脚本，实现循环迭代开发
+
+**核心理念：** 通过循环喂同一个 PROMPT 让 agent 多轮迭代完成任务，同时提供多重安全保护防止无人值守时费用失控
+
+**提问示例：**
+- "启动 Ralph Loop 开发用户认证功能"
+- "用 Ralph 模式修复登录 bug"
+- "创建 Ralph Loop 循环开发环境"
+
+**参数说明：**
+- `goal`: 目标描述（必填）- 例如："实现用户认证功能"
+- `mode`: safe（安全模式，默认）/ normal（普通模式）
+- `completion_promise`: 完成条件（可选）- 默认："tests passing + requirements met"
+- `test_command`: 测试命令（可选）- 默认："npm test"
+- `cli_command`: CLI 命令名（可选）- 默认："claude-code"
+- `max_iterations`: 最大迭代次数（可选）- safe 默认：8
+- `max_minutes`: 最大运行分钟（可选）- safe 默认：25
+- `confirm_every`: 确认频率（可选）- safe 默认：1（每轮确认）
+- `confirm_timeout`: 确认超时秒数（可选）- safe 默认：20
+- `max_same_output`: 最大重复次数（可选）- safe 默认：2
+- `max_diff_lines`: 最大变更行数（可选）- safe 默认：300
+- `cooldown_seconds`: 冷却时间（可选）- safe 默认：8
+
+**生成内容：**
+```
+.ralph/
+├── PROMPT.md              # 循环 prompt（含目标、规则、退出条件）
+├── @fix_plan.md           # 任务分解清单（agent 更新）
+├── PROGRESS.md            # 迭代日志（agent 更新）
+├── ralph_loop_safe.sh     # 安全模式脚本（默认，推荐）
+└── ralph_loop.sh          # 普通模式脚本（可选）
+```
+
+**安全保护机制（Safe Mode）：**
+1. **硬上限**
+   - 最大迭代次数：达到上限必停
+   - 最大运行时间：达到时长必停
+
+2. **人工确认**
+   - 每轮提示确认（可配置频率）
+   - 超时自动停止（默认 20 秒）
+   - 非交互环境拒绝运行
+
+3. **紧急停止**
+   - 创建 `STOP` 文件立即退出
+   - Ctrl+C 手动停止
+
+4. **失控保护**
+   - 输出重复检测（避免卡死循环）
+   - Git diff 变更量检测（超过阈值停止）
+   - 冷却时间（降低请求频率）
+
+5. **双门控退出**
+   - 必须同时满足：`COMPLETION_PROMISE_MET: true` + `EXIT_SIGNAL: true`
+   - 避免误判提前退出
+
+**使用流程：**
+```bash
+# 1. 生成 Ralph Loop 环境
+claude-code "使用 start_ralph 启动开发，goal='实现用户认证功能'"
+
+# 2. 创建 .ralph 目录并复制文件
+mkdir -p .ralph
+cd .ralph
+# 复制生成的 PROMPT.md、@fix_plan.md、PROGRESS.md、脚本文件
+
+# 3. 运行安全模式脚本
+chmod +x ralph_loop_safe.sh
+./ralph_loop_safe.sh
+
+# 4. 监控进度
+tail -f ralph.log          # 查看日志
+cat PROGRESS.md            # 查看进度
+cat @fix_plan.md           # 查看任务
+
+# 5. 紧急停止（如需要）
+touch STOP
+```
+
+**调整参数：**
+```bash
+# 增加最大迭代次数
+MAX_ITERS=15 ./ralph_loop_safe.sh
+
+# 延长运行时间
+MAX_MINUTES=40 ./ralph_loop_safe.sh
+
+# 使用不同的 CLI 命令
+CLI_COMMAND='claude' ./ralph_loop_safe.sh
+
+# 减少确认频率（每 3 轮确认一次）
+CONFIRM_EVERY=3 ./ralph_loop_safe.sh
+```
+
+**与其他工具协同：**
+```bash
+# 推荐工作流：
+# 1. 生成项目上下文
+claude-code "使用 init_project_context 生成项目文档"
+
+# 2. 生成功能规格（可选）
+claude-code "使用 start_feature 生成用户认证功能规格"
+
+# 3. 启动 Ralph Loop
+claude-code "使用 start_ralph 启动开发，goal='实现 docs/specs/user-auth/ 中的功能'"
+
+# 4. 执行循环
+cd .ralph && ./ralph_loop_safe.sh
+```
+
+**适用场景：**
+- ✅ 需要多轮迭代的复杂功能开发
+- ✅ Bug 修复需要多次尝试
+- ✅ 代码重构需要小步快跑
+- ✅ 测试驱动开发（TDD）流程
+- ❌ 简单的一次性任务
+- ❌ 需要大量人工决策的任务
+
+**注意事项：**
+- 默认安全模式非常保守，适合首次使用
+- 确保测试命令正确（首轮会自动识别）
+- 在 git 仓库中使用效果最佳
+- 监控 API 费用，避免超支
+- 普通模式无确认，谨慎使用
+
+---
+
 ## 🏗️ 项目管理工具
 
-### 32. init_project - 初始化项目
+### 1. init_project - 初始化项目
 **用途：** 创建项目结构和任务分解
 
 **提问示例：**
@@ -471,7 +704,7 @@
 
 ---
 
-### 33. init_project_context - 生成项目上下文
+### 2. init_project_context - 生成项目上下文
 **用途：** 生成技术栈/架构/编码规范文档
 
 **提问示例：**
@@ -484,7 +717,7 @@
 
 ---
 
-### 34. add_feature - 添加功能规格
+### 3. add_feature - 添加功能规格
 **用途：** 生成功能需求/设计/任务清单
 
 **提问示例：**
@@ -499,7 +732,7 @@
 
 ---
 
-### 35. fix_bug - Bug 修复指导
+### 4. fix_bug - Bug 修复指导
 **用途：** 根因分析 + 修复方案 + 验证步骤
 
 **提问示例：**
@@ -515,7 +748,7 @@
 
 ---
 
-### 36. estimate - 工作量估算
+### 5. estimate - 工作量估算
 **用途：** 估算开发时间和风险
 
 **提问示例：**
@@ -533,7 +766,7 @@
 
 ## 🛠️ 其他工具
 
-### 37. detect_shell - 检测 AI 环境
+### 1. detect_shell - 检测 AI 环境
 **用途：** 识别是否为套壳产品
 
 **提问示例：**
@@ -546,7 +779,7 @@
 
 ---
 
-### 38. init_setting - 初始化 Cursor 配置
+### 2. init_setting - 初始化 Cursor 配置
 **用途：** 写入推荐的 AI 设置
 
 **提问示例：**
@@ -558,7 +791,7 @@
 
 ---
 
-### 39. css_order - CSS 属性排序
+### 3. css_order - CSS 属性排序
 **用途：** 按规范重排 CSS 属性
 
 **提问示例：**
@@ -569,7 +802,7 @@
 
 ---
 
-### 40. gen_skill - 生成 Agent Skills 文档
+### 4. gen_skill - 生成 Agent Skills 文档
 **用途：** 为工具生成技能文档
 
 **提问示例：**
@@ -586,21 +819,45 @@
 
 ## 💡 使用技巧
 
-### 1. 组合使用
+### 1. Interview 模式最佳实践 🆕
+
+**何时使用 Interview 模式：**
+- ✅ 需求描述简短、不明确
+- ✅ 复杂的业务功能
+- ✅ 涉及多方协作的功能
+- ❌ 简单的 Bug 修复
+- ❌ 需求非常明确的功能
+
+**工作流程：**
+```
+方式1: 立即开发
+1. interview "用户登录功能"
+2. 回答 12-15 个问题
+3. start_feature --from-interview user-login
+4. 根据 tasks.md 开始编码
+
+方式2: 分步进行
+第1天: interview "用户登录功能" → 回答问题
+第3天: start_feature --from-interview user-login → 开始开发
+```
+
+---
+
+### 2. 组合使用
 - 先用 `debug` 定位问题 → 再用 `fix` 自动修复
 - 先用 `analyze_project` 了解项目 → 再用 `add_feature` 添加功能
 - 先用 `code_review` 审查 → 再用 `refactor` 重构
 
-### 2. 工作流优先
+### 3. 工作流优先
 - 复杂任务优先使用 `start_*` 系列工具（自动编排多个步骤）
 - 简单任务使用单个工具（更快更直接）
 
-### 3. 提供完整信息
+### 4. 提供完整信息
 - 粘贴完整的错误堆栈（不要截断）
 - 提供相关代码上下文（不要只给一行）
 - 描述清楚期望结果
 
-### 4. 善用可选参数
+### 5. 善用可选参数
 - 大多数工具会自动检测（如框架、语言）
 - 只在需要明确指定时才传参数
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-probe-kit",
-  "version": "1.10.1",
-  "description": "AI Development Enhancement Toolkit - MCP Server with 40 practical tools (32 basic + 8 orchestration) for code quality, development efficiency, and project management",
+  "version": "1.13.0",
+  "description": "AI Development Enhancement Toolkit - MCP Server with 43 practical tools (34 basic + 9 orchestration) for code quality, development efficiency, and project management. Now with Ralph Loop for iterative development and interview mode for better requirement gathering.",
   "type": "module",
   "main": "build/index.js",
   "bin": {