mcp-probe-kit 1.11.0 → 1.15.0

package/docs/BEST_PRACTICES.md

@@ -2,11 +2,15 @@
 
 > 完整的工具调用指南和使用技巧
 
+**版本**: v1.14.0 | **工具总数**: 46 个
+
 ---
 
 ## 📖 目录
 
 - [工具调用写法指南](#工具调用写法指南)
+  - [UI/UX 工具调用](#uiux-工具调用) 🆕
+  - [访谈工具调用](#访谈工具调用)
   - [基础工具调用](#基础工具调用)
   - [智能编排调用](#智能编排调用)
 - [使用技巧](#使用技巧)
@@ -17,6 +21,123 @@
 
 ## 🎯 工具调用写法指南
 
+### UI/UX 工具调用 🆕
+
+#### ui_design_system - 设计系统生成
+
+```
+# 方式 1：最简单（只指定技术栈）
+ui_design_system --stack react
+
+# 方式 2：指定主色调
+ui_design_system --stack react --primary-color "#3b82f6"
+
+# 方式 3：完整配置
+ui_design_system \
+  --stack nextjs \
+  --color-scheme light \
+  --primary-color "#3b82f6" \
+  --typography modern \
+  --spacing normal \
+  --border-radius medium
+
+# 方式 4：对话式
+"帮我生成一个 React 设计系统，主色调用蓝色"
+"为我的 Tailwind 项目生成配置"
+
+# 自动完成：
+# ✓ 生成完整的色彩系统（11 级色阶）
+# ✓ 生成字体系统（Sans/Serif/Mono）
+# ✓ 生成间距系统（基于 4px）
+# ✓ 生成组件样式（圆角、阴影、动画）
+# ✓ 输出可直接使用的代码
+```
+
+#### ui_search - UI/UX 智能搜索
+
+```
+# 方式 1：简单搜索
+ui_search "button primary"
+
+# 方式 2：指定类别
+ui_search "button" --category react
+
+# 方式 3：完整配置
+ui_search \
+  --query "button primary hover" \
+  --category react \
+  --limit 5 \
+  --min-score 1.0
+
+# 方式 4：对话式
+"我需要一个 React 的主按钮组件"
+"搜索一下蓝色主题的配色方案"
+"表单验证有什么 UX 最佳实践？"
+
+# 搜索技巧：
+# ✓ 使用具体关键词："primary button hover" 而不是 "button"
+# ✓ 指定类别：colors, icons, react, vue, ux-guidelines 等
+# ✓ 调整结果数量：--limit 3（快速预览）或 --limit 20（详细搜索）
+# ✓ 支持中英文：可以搜索 "按钮" 或 "button"
+```
+
+#### sync_ui_data - 数据同步
+
+```
+# 方式 1：检查更新
+sync_ui_data
+
+# 方式 2：强制同步
+sync_ui_data --force
+
+# 方式 3：详细日志
+sync_ui_data --force --verbose
+
+# 方式 4：对话式
+"检查一下 UI 数据有没有更新"
+"强制更新 UI 数据"
+
+# 数据位置：
+# ✓ 内嵌数据：npm 包内部（离线可用）
+# ✓ 缓存数据：~/.mcp-probe-kit/ui-ux-data/（自动更新）
+```
+
+---
+
+### 访谈工具调用
+
+#### interview - 需求访谈
+
+```
+# 方式 1：直接调用
+interview "用户登录认证功能"
+
+# 方式 2：对话式
+interview
+然后 AI 会询问功能描述
+
+# 自动完成：
+# ✓ 生成 12-15 个结构化问题（4个阶段）
+# ✓ 保存访谈记录到 docs/interviews/
+# ✓ 可选：立即开发或稍后使用
+```
+
+#### ask_user - AI 主动提问
+
+```
+# AI 自动调用（遇到不确定因素时）
+ask_user "优化目标是性能还是可读性？"
+
+# 用户主动触发
+"有什么需要我确认的吗？"
+"问我几个问题吧"
+
+# 带选项的提问
+ask_user --options ["方案A: 性能优先", "方案B: 可读性优先"]
+```
+
+---
+
 ### 基础工具调用
 
 #### 代码质量工具
@@ -284,10 +405,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 +576,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 +841,10 @@ start_refactor @code.ts --goal reduce_complexity
 ```
 需要做什么？
 │
-├─ 开发新功能
+├─ 需求不明确？
+│  └─ interview ✅ → 访谈澄清 → start_feature
+│
+├─ 开发新功能（需求明确）
 │  └─ start_feature ✅
 │
 ├─ 修复 Bug
@@ -632,22 +885,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 "用户设置页面"
@@ -724,10 +1005,179 @@ AI: 好的，我来对支付 API 进行全面体检。
 
 ---
 
+## 🎨 UI/UX 工具使用技巧 🆕
+
+### 设计系统生成技巧
+
+**1. 新项目启动**
+```
+# 步骤 1：生成基础设计系统
+ui_design_system --stack react
+
+# 步骤 2：根据需求调整
+ui_design_system --stack react --primary-color "#3b82f6" --border-radius large
+
+# 步骤 3：复制生成的代码到项目中
+```
+
+**2. 技术栈选择**
+```
+# React 项目
+ui_design_system --stack react
+
+# Next.js 项目
+ui_design_system --stack nextjs
+
+# Tailwind 项目（生成 tailwind.config.js）
+ui_design_system --stack tailwind
+
+# Vue 项目
+ui_design_system --stack vue
+```
+
+**3. 主题定制**
+```
+# 浅色主题
+ui_design_system --stack react --color-scheme light
+
+# 深色主题
+ui_design_system --stack react --color-scheme dark
+
+# 自适应主题
+ui_design_system --stack react --color-scheme auto
+```
+
+### UI 搜索技巧
+
+**1. 组件搜索**
+```
+# ❌ 不好：太模糊
+ui_search "button"
+
+# ✅ 好：具体明确
+ui_search "button primary hover effect" --category react
+
+# ✅ 更好：指定技术栈
+ui_search "button primary" --category react --limit 5
+```
+
+**2. 颜色搜索**
+```
+# 搜索配色方案
+ui_search "blue professional" --category colors
+
+# 搜索特定用途的颜色
+ui_search "saas tech primary color" --category colors
+
+# 搜索完整色阶
+ui_search "blue gradient" --category colors
+```
+
+**3. 最佳实践搜索**
+```
+# 搜索 UX 指南
+ui_search "form validation" --category ux-guidelines
+
+# 搜索性能优化
+ui_search "react performance" --category react-performance
+
+# 搜索设计模式
+ui_search "card layout" --category web-interface
+```
+
+**4. 调整搜索结果**
+```
+# 快速预览（3 个结果）
+ui_search "button" --limit 3
+
+# 详细搜索（20 个结果）
+ui_search "button" --limit 20
+
+# 过滤低相关性结果
+ui_search "button" --min-score 2.0
+```
+
+### 数据同步技巧
+
+**1. 定期检查**
+```
+# 每周检查一次（推荐）
+sync_ui_data
+
+# 如果已是最新版本，不会重复下载
+```
+
+**2. 遇到问题时**
+```
+# 搜索结果不准确？强制更新
+sync_ui_data --force --verbose
+
+# 查看详细日志
+sync_ui_data --verbose
+```
+
+**3. 数据位置**
+```
+# 内嵌数据（离线可用）
+位置：npm 包内部
+更新：重新安装 mcp-probe-kit
+
+# 缓存数据（自动更新）
+位置：~/.mcp-probe-kit/ui-ux-data/
+更新：首次使用时自动检查
+
+# 手动同步（立即更新）
+命令：sync_ui_data --force
+```
+
+### 组合使用技巧
+
+**场景 1：新项目完整流程**
+```
+# 步骤 1：生成设计系统
+ui_design_system --stack react --primary-color "#3b82f6"
+
+# 步骤 2：搜索需要的组件
+ui_search "button card form" --category react
+
+# 步骤 3：搜索配色方案
+ui_search "blue professional" --category colors
+
+# 步骤 4：应用到项目
+```
+
+**场景 2：优化现有项目**
+```
+# 步骤 1：搜索最佳实践
+ui_search "form validation ux" --category ux-guidelines
+
+# 步骤 2：搜索优化方案
+ui_search "react performance" --category react-performance
+
+# 步骤 3：搜索改进的组件
+ui_search "button loading state" --category react
+```
+
+**场景 3：设计系统迁移**
+```
+# 步骤 1：生成新的设计系统
+ui_design_system --stack tailwind
+
+# 步骤 2：搜索对应的组件
+ui_search "button" --category tailwind
+
+# 步骤 3：逐步替换旧组件
+```
+
+---
+
 ## 📚 相关文档
 
 - [README](../README.md) - 项目介绍和快速开始
 - [工具列表](../README.md#功能特性) - 所有工具的详细说明
+- [UI/UX 快速开始](../QUICK-START-UI-UX.md) - UI/UX 工具快速入门 🆕
+- [UI/UX 完整文档](./UI-UX-PRO-MAX-GUIDE.md) - UI/UX 工具详细文档 🆕
+- [UI/UX 使用演示](./UI-UX-DEMO.md) - UI/UX 工具使用示例 🆕
 - [常见问题](../README.md#常见问题) - FAQ
 
 ---