mcp-probe-kit 1.3.0 → 1.6.0

package/docs/BEST_PRACTICES.md

@@ -0,0 +1,722 @@
+# 📚 MCP Probe Kit 最佳实践
+
+> 完整的工具调用指南和使用技巧
+
+---
+
+## 📖 目录
+
+- [工具调用写法指南](#工具调用写法指南)
+  - [基础工具调用](#基础工具调用)
+  - [智能编排调用](#智能编排调用)
+- [使用技巧](#使用技巧)
+- [进阶技巧](#进阶技巧)
+- [注意事项](#注意事项)
+
+---
+
+## 🎯 工具调用写法指南
+
+### 基础工具调用
+
+#### 代码质量工具
+
+```
+# 套壳检测
+detect_shell
+
+# 代码审查（审查当前文件）
+code_review
+
+# 代码审查（审查指定文件）
+code_review @src/utils/helper.ts
+
+# 安全扫描
+security_scan @api/user.ts
+
+# 调试助手（然后粘贴错误信息）
+debug
+
+# 生成测试
+gentest @src/components/Button.tsx
+
+# 重构建议
+refactor @legacy-code.js
+
+# 性能分析
+perf @slow-function.ts
+
+# 自动修复
+fix @file-with-errors.ts
+```
+
+#### 开发效率工具
+
+```
+# 生成 commit 消息
+gencommit
+
+# 生成 API 文档
+genapi @api/user.ts
+
+# 生成代码注释
+gendoc @utils/format.ts
+
+# 生成 PR 描述
+genpr
+
+# 生成 Changelog
+genchangelog v1.2.0
+
+# 生成 SQL
+gensql
+然后描述需求："查询最近30天注册的活跃用户"
+
+# 生成 UI 组件
+genui
+然后描述："创建一个带加载状态的 Button 组件"
+
+# 生成 Mock 数据
+gen_mock
+然后提供数据结构：
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+# 代码解释
+explain @complex-algorithm.ts
+
+# 代码转换
+convert @old-code.js
+然后说明："转为 TypeScript"
+
+# CSS 属性排序
+css_order
+
+# 生成 README
+genreadme
+
+# 文件拆分
+split @LargeComponent.tsx
+
+# Bug 修复流程
+fix_bug
+然后提供错误信息和堆栈
+
+# 工作量估算
+estimate
+然后描述任务："实现用户登录功能"
+```
+
+#### 项目管理工具
+
+```
+# 初始化 AI 配置
+init_setting
+
+# 初始化项目（Spec-Driven）
+init_project
+然后提供需求描述或 @requirements.md
+
+# 检查依赖健康度
+check_deps
+
+# 解决 Git 冲突
+resolve_conflict
+然后粘贴冲突内容或打开冲突文件
+
+# 分析项目结构
+analyze_project
+
+# 生成项目上下文
+init_project_context
+
+# 添加新功能
+add_feature user-auth "用户登录认证功能"
+```
+
+---
+
+### 智能编排调用
+
+#### start_feature - 新功能开发（推荐）
+
+```
+# 方式 1：直接调用
+start_feature user-profile "用户个人资料管理"
+
+# 方式 2：对话式
+start_feature
+然后 AI 会询问功能名称和描述
+
+# 自动完成：
+# ✓ 检查/生成项目上下文
+# ✓ 生成功能规格（需求/设计/任务）
+# ✓ 工作量估算
+```
+
+#### start_bugfix - Bug 修复（推荐）
+
+```
+# 方式 1：提供错误信息
+start_bugfix
+然后粘贴错误信息和堆栈
+
+# 方式 2：简洁调用
+遇到 Bug 时直接说："start_bugfix 帮我修复这个错误"
+
+# 自动完成：
+# ✓ 检查/生成项目上下文
+# ✓ 问题定位和原因分析
+# ✓ 生成修复方案
+# ✓ 生成回归测试
+# ✓ 生成 commit 消息
+```
+
+#### start_review - 代码体检（推荐）
+
+```
+# 审查当前文件
+start_review
+
+# 审查指定文件
+start_review @src/api/payment.ts
+
+# 自动完成：
+# ✓ 检查/生成项目上下文
+# ✓ 代码质量审查
+# ✓ 安全漏洞扫描
+# ✓ 性能分析
+# ✓ 生成综合报告
+```
+
+#### start_release - 发布准备（推荐）
+
+```
+# 准备发布 v1.2.0
+start_release v1.2.0
+
+# 指定起始版本
+start_release v1.2.0 --from v1.1.0
+
+# 自动完成：
+# ✓ 检查/生成项目上下文
+# ✓ 生成 Changelog
+# ✓ 生成 PR 描述
+# ✓ 提供发布检查清单
+```
+
+#### start_refactor - 代码重构（推荐）
+
+```
+# 重构当前文件
+start_refactor
+
+# 重构指定文件
+start_refactor @legacy/old-module.js
+
+# 指定重构目标
+start_refactor @code.ts --goal reduce_complexity
+
+# 自动完成：
+# ✓ 检查/生成项目上下文
+# ✓ 代码审查发现问题
+# ✓ 生成重构方案
+# ✓ 生成保护测试
+```
+
+#### start_onboard - 快速上手项目（推荐）
+
+```
+# 分析当前项目
+start_onboard
+
+# 分析指定项目
+start_onboard /path/to/project
+
+# 自动完成：
+# ✓ 深度分析项目结构
+# ✓ 生成项目上下文文档
+# ✓ 提供项目概览和快速开始指南
+```
+
+#### start_api - API 开发（推荐）
+
+```
+# 为 API 生成完整资料
+start_api @api/user.ts
+
+# 自动完成：
+# ✓ 检查/生成项目上下文
+# ✓ 生成 API 文档
+# ✓ 生成 Mock 数据
+# ✓ 生成 API 测试
+```
+
+#### start_doc - 文档生成（推荐）
+
+```
+# 为项目生成完整文档
+start_doc
+
+# 为指定代码生成文档
+start_doc @src/
+
+# 自动完成：
+# ✓ 检查/生成项目上下文
+# ✓ 生成代码注释
+# ✓ 生成 README
+# ✓ 生成 API 文档
+```
+
+---
+
+## 💡 使用技巧
+
+### 1. 优先使用智能编排
+
+**❌ 不推荐（手动调用多个工具）**
+```
+1. init_project_context
+2. add_feature user-auth "用户登录"
+3. estimate "实现用户登录功能"
+```
+
+**✅ 推荐（使用智能编排）**
+```
+start_feature user-auth "用户登录认证功能"
+# 一键完成所有步骤
+```
+
+---
+
+### 2. 善用文件引用
+
+**引用单个文件**
+```
+code_review @src/utils/helper.ts
+```
+
+**引用多个文件**
+```
+code_review @src/utils/helper.ts @src/utils/format.ts
+```
+
+**引用整个目录**
+```
+start_doc @src/components/
+```
+
+---
+
+### 3. 对话式调用
+
+大多数工具支持对话式调用，AI 会引导你提供必要信息：
+
+```
+# 直接调用工具名
+gen_mock
+
+# AI 会询问：
+# "请提供数据结构定义（TypeScript interface 或 JSON Schema）"
+
+# 你提供：
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+# AI 会继续询问其他可选参数
+```
+
+---
+
+### 4. 组合使用工具
+
+#### 场景：开发新功能的完整流程
+
+```
+1. start_feature user-profile "用户个人资料"
+   # 生成规格文档和估算
+
+2. 根据 tasks.md 开始编码...
+
+3. start_review @src/profile/
+   # 代码体检
+
+4. gentest @src/profile/ProfileCard.tsx
+   # 补充测试
+
+5. gencommit
+   # 提交代码
+```
+
+#### 场景：修复 Bug 的完整流程
+
+```
+1. start_bugfix
+   # 粘贴错误信息，自动完成分析、修复、测试
+
+2. 验证修复...
+
+3. gencommit
+   # 已在 start_bugfix 中生成，直接使用
+```
+
+#### 场景：代码重构
+
+```
+1. start_review @old-code.ts
+   # 先体检，发现问题
+
+2. start_refactor @old-code.ts
+   # 重构并生成测试
+
+3. gencommit
+   # 提交重构
+```
+
+---
+
+### 5. 项目初始化最佳实践
+
+#### 新项目
+
+```
+1. init_project
+   # 提供需求，生成项目结构
+
+2. init_setting
+   # 配置 AI
+
+3. init_project_context
+   # 生成项目上下文
+
+4. 开始开发...
+```
+
+#### 接手老项目
+
+```
+1. start_onboard
+   # 快速了解项目（包含 analyze_project + init_project_context）
+
+2. check_deps
+   # 检查依赖健康度
+
+3. start_review @src/
+   # 代码质量评估
+
+4. 开始维护...
+```
+
+---
+
+### 6. 安全开发最佳实践
+
+#### 开发阶段
+
+```
+1. 编写代码...
+
+2. security_scan @new-feature.ts
+   # 安全扫描
+
+3. start_review @new-feature.ts
+   # 全面体检（包含安全扫描）
+```
+
+#### 发布前
+
+```
+1. start_review @src/
+   # 全面代码体检
+
+2. check_deps
+   # 检查依赖漏洞
+
+3. start_release v1.2.0
+   # 准备发布
+```
+
+---
+
+### 7. 文档维护最佳实践
+
+#### 代码文档
+
+```
+1. gendoc @src/utils/
+   # 生成代码注释
+
+2. genapi @api/
+   # 生成 API 文档
+
+3. start_doc @src/
+   # 生成完整文档（包含上述两步）
+```
+
+#### 项目文档
+
+```
+1. genreadme
+   # 生成/更新 README
+
+2. genchangelog v1.2.0
+   # 更新 Changelog
+
+3. init_project_context
+   # 更新项目上下文
+```
+
+---
+
+### 8. 性能优化流程
+
+```
+1. perf @slow-function.ts
+   # 性能分析
+
+2. start_refactor @slow-function.ts --goal improve_performance
+   # 重构优化
+
+3. gentest @optimized-function.ts
+   # 性能测试
+
+4. 对比优化前后性能...
+
+5. gencommit
+   # 提交优化
+```
+
+---
+
+## 🎓 进阶技巧
+
+### 批量操作
+
+```
+# 批量审查多个文件
+code_review @src/api/*.ts
+
+# 批量生成测试
+gentest @src/components/*.tsx
+
+# 批量生成文档
+start_doc @src/
+```
+
+### 自定义参数
+
+```
+# 指定测试框架
+gentest @component.tsx --framework vitest
+
+# 指定文档格式
+genapi @api.ts --format openapi
+
+# 指定 Mock 数据数量
+gen_mock --count 10
+
+# 指定重构目标
+start_refactor @code.ts --goal reduce_complexity
+```
+
+### 链式调用
+
+```
+# 一次对话完成多个操作
+"帮我审查 @user.ts，然后生成测试，最后生成 commit 消息"
+
+# AI 会依次调用：
+# 1. code_review @user.ts
+# 2. gentest @user.ts
+# 3. gencommit
+```
+
+---
+
+## ⚠️ 注意事项
+
+### 1. 智能编排会自动处理项目上下文
+
+- 无需手动调用 `init_project_context`
+- 首次使用会自动生成
+- 后续调用会自动读取
+
+### 2. 文件引用使用 @ 符号
+
+- `@file.ts` - 引用文件
+- `@folder/` - 引用目录
+- `@*.ts` - 通配符匹配
+
+### 3. 大型项目建议分批处理
+
+- 不要一次审查整个项目
+- 按模块或功能分批进行
+- 避免超时或响应过长
+
+### 4. 定期更新项目上下文
+
+- 技术栈变更后重新运行 `init_project_context`
+- 保持上下文文档最新
+- 有助于 AI 生成更准确的代码
+
+### 5. 善用编排工具
+
+- 优先使用 `start_*` 编排工具
+- 减少手动调用多个工具的次数
+- 提高开发效率
+
+---
+
+## 📊 工具选择决策树
+
+```
+需要做什么？
+│
+├─ 开发新功能
+│  └─ start_feature ✅
+│
+├─ 修复 Bug
+│  └─ start_bugfix ✅
+│
+├─ 代码审查
+│  ├─ 只看质量 → code_review
+│  ├─ 只看安全 → security_scan
+│  ├─ 只看性能 → perf
+│  └─ 全面体检 → start_review ✅
+│
+├─ 重构代码
+│  └─ start_refactor ✅
+│
+├─ 接手项目
+│  └─ start_onboard ✅
+│
+├─ 开发 API
+│  └─ start_api ✅
+│
+├─ 生成文档
+│  ├─ 只要 README → genreadme
+│  ├─ 只要 API 文档 → genapi
+│  └─ 完整文档 → start_doc ✅
+│
+├─ 准备发布
+│  └─ start_release ✅
+│
+└─ 其他单一任务
+   └─ 使用对应的基础工具
+```
+
+---
+
+## 🚀 快速参考
+
+### 最常用的 10 个命令
+
+| 命令 | 用途 | 频率 |
+|------|------|------|
+| `start_feature` | 开发新功能 | ⭐⭐⭐⭐⭐ |
+| `start_bugfix` | 修复 Bug | ⭐⭐⭐⭐⭐ |
+| `start_review` | 代码体检 | ⭐⭐⭐⭐ |
+| `gencommit` | 生成提交 | ⭐⭐⭐⭐ |
+| `gentest` | 生成测试 | ⭐⭐⭐⭐ |
+| `start_onboard` | 快速上手 | ⭐⭐⭐ |
+| `start_refactor` | 代码重构 | ⭐⭐⭐ |
+| `check_deps` | 检查依赖 | ⭐⭐⭐ |
+| `start_release` | 准备发布 | ⭐⭐ |
+| `start_api` | API 开发 | ⭐⭐ |
+
+---
+
+## 💬 实际对话示例
+
+### 示例 1：开发新功能
+
+```
+你: start_feature user-settings "用户设置页面"
+
+AI: 好的，我来帮你开发用户设置功能。
+
+[检查项目上下文...]
+✓ 已读取项目上下文
+
+[生成功能规格...]
+✓ 已生成 docs/specs/user-settings/requirements.md
+✓ 已生成 docs/specs/user-settings/design.md
+✓ 已生成 docs/specs/user-settings/tasks.md
+
+[工作量估算...]
+✓ 预估：5 故事点 / 1-2 天
+✓ 主要风险：需要集成第三方服务
+
+下一步：请按照 tasks.md 中的任务清单开始开发。
+```
+
+### 示例 2：修复 Bug
+
+```
+你: start_bugfix
+
+AI: 请提供错误信息和堆栈跟踪。
+
+你: [粘贴错误信息]
+TypeError: Cannot read property 'name' of undefined
+  at UserProfile.render (UserProfile.tsx:45)
+
+AI: 好的，我来帮你修复这个 Bug。
+
+[问题定位...]
+✓ 问题文件：UserProfile.tsx:45
+✓ 原因：user 对象可能为 null
+
+[生成修复方案...]
+✓ 修复方案：添加空值检查
+
+[生成测试...]
+✓ 已生成回归测试
+
+[生成 commit...]
+✓ Commit 消息：fix: 🐛 修复用户资料页面空指针异常
+
+修复完成！请验证后提交。
+```
+
+### 示例 3：代码体检
+
+```
+你: start_review @src/api/payment.ts
+
+AI: 好的，我来对支付 API 进行全面体检。
+
+[代码质量审查...]
+✓ 发现 3 个问题
+
+[安全扫描...]
+⚠️ 发现 1 个高危漏洞：硬编码 API 密钥
+
+[性能分析...]
+✓ 性能良好
+
+综合评分：6/10
+
+建议优先修复：
+1. [高危] 移除硬编码的 API 密钥
+2. [中] 添加错误处理
+3. [低] 改进命名规范
+```
+
+---
+
+## 📚 相关文档
+
+- [README](../README.md) - 项目介绍和快速开始
+- [工具列表](../README.md#功能特性) - 所有工具的详细说明
+- [常见问题](../README.md#常见问题) - FAQ
+
+---
+
+**Made with ❤️ for AI-Powered Development**