mcp-probe-kit 1.15.0 → 2.0.0

package/docs/specs/vnext-upgrade/GITHUB_DISCUSSION_TEMPLATE.md

@@ -0,0 +1,236 @@
+# GitHub Discussion 模板 - v2.0.0-beta.1 Beta 测试
+
+## 📋 使用说明
+
+将以下内容复制到 GitHub Discussions 中创建新讨论：
+
+1. 访问：https://github.com/mybolide/mcp-probe-kit/discussions/new
+2. 选择类别：**Announcements** 或 **General**
+3. 标题：`v2.0.0-beta.1 Beta 测试 - 欢迎反馈 🎉`
+4. 复制下面的内容到正文
+
+---
+
+## 正文内容
+
+```markdown
+# v2.0.0-beta.1 Beta 测试 - 欢迎反馈 🎉
+
+大家好！
+
+我们很高兴地宣布 **MCP Probe Kit v2.0** 的第一个 Beta 版本正式发布！这是一次重大的架构升级，带来了全新的功能和更好的性能。
+
+## 🎯 核心特性
+
+### 1. 工具集管理
+通过 `MCP_TOOLSET` 环境变量按需加载工具，降低 AI 选择困惑：
+
+- **`core`** (15个) - 日常高频工具（gencommit、code_review、debug 等）
+- **`ui`** (6个) - UI/UX 设计工具（start_ui、ui_search、design2code 等）
+- **`workflow`** (32个) - 智能编排工具（start_feature、start_bugfix 等）
+- **`full`** (49个) - 所有工具（默认，向后兼容）
+
+**配置示例：**
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@2.0.0-beta.1"],
+      "env": {
+        "MCP_TOOLSET": "workflow"
+      }
+    }
+  }
+}
+```
+
+### 2. Tasks API
+支持长时间运行的任务，不再担心超时：
+
+- ✅ 任务状态管理（working/completed/failed/cancelled）
+- ✅ 任务查询和取消
+- ✅ TTL 自动清理
+- ✅ 16 个集成测试全部通过
+
+**使用场景：**
+- 长时间运行的 `start_ralph` 循环开发
+- 复杂的 `start_ui` 设计系统生成
+- 大型项目的 `analyze_project` 分析
+
+### 3. Elicitation 支持
+智能用户交互，让 AI 更懂你的需求：
+
+- ✅ 文本格式回退（当前实现，所有客户端支持）
+- 🔮 表单式提问（未来支持，等待客户端实现）
+- ✅ 向后兼容所有客户端
+- ✅ 11 个集成测试全部通过
+
+**核心理念：** "先慢下来，把问题想清楚"
+
+### 4. 统一输出格式
+100% 向后兼容，为未来做好准备：
+
+- `okText()` - 纯文本响应（当前所有工具使用）
+- `okStructured()` - 结构化响应（v2.1 实现）
+- `errorResponse()` - 错误响应
+
+## 📊 性能基准
+
+所有性能测试通过（9 个测试）：
+
+| 指标 | 基准 | 实际 |
+|------|------|------|
+| 工具集定义访问 | < 10ms | ✅ 通过 |
+| 任务创建 | < 10ms | ✅ 通过 |
+| 任务查询 | < 5ms | ✅ 通过 |
+| 批量任务 (100个) | < 50ms | ✅ 通过 |
+| 并发任务 (50个) | < 100ms | ✅ 通过 |
+| 内存使用 | ~13 MB | ✅ 正常 |
+
+**测试覆盖：** 57+ 个测试全部通过
+
+## 🧪 如何参与测试
+
+### 安装 Beta 版本
+
+**方式 1: npx（推荐）**
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["-y", "mcp-probe-kit@2.0.0-beta.1"]
+    }
+  }
+}
+```
+
+**方式 2: 全局安装**
+```bash
+npm install -g mcp-probe-kit@2.0.0-beta.1
+```
+
+### 测试重点
+
+请重点测试以下功能：
+
+#### 1. 工具集过滤
+```json
+// 测试不同工具集
+"env": { "MCP_TOOLSET": "core" }      // 应该只显示 15 个工具
+"env": { "MCP_TOOLSET": "ui" }        // 应该只显示 6 个工具
+"env": { "MCP_TOOLSET": "workflow" }  // 应该只显示 32 个工具
+"env": { "MCP_TOOLSET": "full" }      // 应该显示所有 49 个工具（默认）
+```
+
+#### 2. Tasks API
+- 测试长任务支持（如 `start_ralph`）
+- 测试任务查询和取消
+- 验证任务状态转换
+
+#### 3. 所有工具正常工作
+- 验证所有 49 个工具可以正常调用
+- 检查输出格式是否正确
+- 测试错误处理
+
+#### 4. 向后兼容性
+- 从 v1.x 升级测试
+- 验证现有配置继续工作
+- 确认无破坏性更改
+
+#### 5. 客户端兼容性
+- Cursor
+- Claude Desktop
+- Cline
+- Continue
+
+### 反馈方式
+
+遇到问题或有建议？请通过以下方式反馈：
+
+1. **🐛 Bug 报告**: [GitHub Issues](https://github.com/mybolide/mcp-probe-kit/issues)
+   - 请包含：错误信息、复现步骤、环境信息
+   
+2. **💡 功能建议**: 在本 Discussion 中回复
+   - 描述你希望的功能
+   - 说明使用场景
+   
+3. **📝 使用体验**: 在本 Discussion 中分享
+   - 你最喜欢的新特性
+   - 遇到的困难
+   - 改进建议
+
+## ⚠️ 已知限制
+
+1. **结构化输出延后到 v2.1**
+   - Schema 已定义
+   - 实际实现延后
+   - 不阻塞 v2.0 发布
+
+2. **工具任务化延后到 v2.1**
+   - Tasks API 基础设施已完成
+   - 工具集成延后
+   - 当前工具为"指导型"
+
+3. **文档站待完善**
+   - 基础框架已完成
+   - 详细页面待 Beta 测试后完善
+
+## 📚 文档
+
+- 📖 [CHANGELOG](https://github.com/mybolide/mcp-probe-kit/blob/main/CHANGELOG.md) - 详细变更日志
+- 🔄 [迁移指南](https://github.com/mybolide/mcp-probe-kit/blob/main/docs/MIGRATION.md) - 从 v1.x 升级
+- ✅ [兼容性矩阵](https://github.com/mybolide/mcp-probe-kit/blob/main/docs/COMPATIBILITY.md) - 客户端支持情况
+- 📋 [Tasks API 文档](https://github.com/mybolide/mcp-probe-kit/blob/main/docs/TASKS.md) - Tasks API 使用指南
+- 💬 [Elicitation 文档](https://github.com/mybolide/mcp-probe-kit/blob/main/docs/ELICITATION.md) - 用户交互指南
+
+## 🚀 下一步计划
+
+- **M6.4**: Beta 测试与反馈收集（2 周，至 2026-02-09）
+- **M6.5**: 最终兼容性测试
+- **M6.6**: 稳定版发布 (v2.0.0)
+- **v2.1**: 结构化输出、工具任务化
+
+## 🎁 特别感谢
+
+感谢所有在开发过程中提供反馈和建议的用户！你们的支持是我们前进的动力。
+
+## 📅 测试时间表
+
+- **开始日期**: 2026-01-26
+- **结束日期**: 2026-02-09（至少 2 周）
+- **目标**: 收集至少 10 个用户反馈
+
+---
+
+**让我们一起打造更好的 MCP Probe Kit！** 🚀
+
+如果你觉得这个项目有用，请给我们一个 ⭐ Star：https://github.com/mybolide/mcp-probe-kit
+
+有任何问题，欢迎在下方评论！👇
+```
+
+---
+
+## 📝 创建步骤
+
+1. 访问 GitHub Discussions：https://github.com/mybolide/mcp-probe-kit/discussions/new
+2. 选择类别：**Announcements**
+3. 标题：`v2.0.0-beta.1 Beta 测试 - 欢迎反馈 🎉`
+4. 复制上面的正文内容
+5. 点击 "Start discussion"
+
+## 🔗 创建后
+
+创建 Discussion 后，请：
+
+1. 将 Discussion URL 添加到 README.md
+2. 将 Discussion URL 添加到 CHANGELOG.md
+3. 在 Twitter/X 等社交媒体分享
+4. 通知现有用户（如果有邮件列表）
+
+## ✅ 完成标记
+
+创建 Discussion 后，在 `tasks.md` 中标记：
+- [x] 创建 GitHub Discussion 收集反馈

package/docs/specs/vnext-upgrade/M8.9-PROGRESS-UPDATE.md

@@ -0,0 +1,248 @@
+# M8.9 文档完善 - 进度更新
+
+**更新时间**: 2026-01-26  
+**状态**: 🟡 进行中
+
+---
+
+## ✅ 已完成工作
+
+### 1. 核心文档更新（3/3）
+
+#### 1.1 README.md ✅
+**更新内容**:
+- ✅ 更新工具总数：49 个 → 37 个
+- ✅ 添加结构化输出特性说明
+- ✅ 更新功能特性章节
+- ✅ 更新工具分类（7+7+7+5+5+2）
+- ✅ 更新项目结构（添加 schemas/ 目录）
+- ✅ 删除已清理工具的说明
+- ✅ 保留核心工具的详细文档
+
+**工作量**: 2 小时
+
+#### 1.2 docs/STRUCTURED_OUTPUT.md ✅
+**当前状态**: 已存在完整文档
+**内容**:
+- ✅ 结构化输出概念说明
+- ✅ 6 个 P0 工具的示例
+- ✅ Schema 定义说明
+- ✅ 最佳实践
+- ✅ 向后兼容性说明
+
+**无需更新**: 文档已完整
+
+#### 1.3 CHANGELOG.md ✅
+**更新内容**:
+- ✅ 添加 v2.0.0 版本记录
+- ✅ 详细的架构升级说明
+- ✅ 已删除工具列表（10 个）
+- ✅ 保留工具列表（37 个）
+- ✅ Schema 定义说明
+- ✅ 性能优化记录
+- ✅ 向后兼容性说明
+
+**工作量**: 1 小时
+
+---
+
+## 🔄 进行中工作
+
+### 2. 工具分类文档（0/6）
+
+需要创建以下文档：
+
+#### 2.1 docs/tools/CORE-TOOLS.md 🔴
+**内容**:
+- [ ] 7 个核心开发工具的详细文档
+- [ ] 每个工具的参数说明
+- [ ] 每个工具的使用示例
+- [ ] 每个工具的 Schema 定义
+
+**预估工作量**: 1.5 小时
+
+#### 2.2 docs/tools/GENERATION-TOOLS.md 🔴
+**内容**:
+- [ ] 7 个代码生成工具的详细文档
+- [ ] 每个工具的参数说明
+- [ ] 每个工具的使用示例
+- [ ] 每个工具的 Schema 定义
+
+**预估工作量**: 1.5 小时
+
+#### 2.3 docs/tools/PROJECT-TOOLS.md 🔴
+**内容**:
+- [ ] 7 个项目管理工具的详细文档
+- [ ] 每个工具的参数说明
+- [ ] 每个工具的使用示例
+- [ ] 每个工具的 Schema 定义
+
+**预估工作量**: 1.5 小时
+
+#### 2.4 docs/tools/WORKFLOW-TOOLS.md 🔴
+**内容**:
+- [ ] 5 个工作流编排工具的详细文档
+- [ ] 每个工具的参数说明
+- [ ] 每个工具的使用示例
+- [ ] 每个工具的 Schema 定义
+
+**预估工作量**: 1 小时
+
+#### 2.5 docs/tools/UI-UX-TOOLS.md 🔴
+**内容**:
+- [ ] 5 个 UI/UX 工具的详细文档
+- [ ] 每个工具的参数说明
+- [ ] 每个工具的使用示例
+- [ ] 每个工具的 Schema 定义
+
+**预估工作量**: 1 小时
+
+#### 2.6 docs/tools/HELPER-TOOLS.md 🔴
+**内容**:
+- [ ] 2 个访谈工具的详细文档
+- [ ] 每个工具的参数说明
+- [ ] 每个工具的使用示例
+
+**预估工作量**: 0.5 小时
+
+---
+
+### 3. 文档站页面（0/4）
+
+#### 3.1 docs/pages/all-tools.html 🔴
+**内容**:
+- [ ] 所有 37 个工具的列表
+- [ ] 按类别分组
+- [ ] 每个工具的简短描述
+- [ ] 链接到详细文档
+
+**预估工作量**: 1 小时
+
+#### 3.2 docs/pages/schemas.html 🔴
+**内容**:
+- [ ] 所有 Schema 的完整参考
+- [ ] 每个 Schema 的字段说明
+- [ ] 每个 Schema 的示例
+- [ ] 搜索和过滤功能
+
+**预估工作量**: 2 小时
+
+#### 3.3 docs/pages/migration.html 🔴
+**内容**:
+- [ ] 迁移指南
+- [ ] 向后兼容性说明
+- [ ] 破坏性变更（如果有）
+- [ ] 迁移示例
+
+**预估工作量**: 1 小时
+
+#### 3.4 docs/pages/examples.html 🔴
+**内容**:
+- [ ] 常见使用场景的示例
+- [ ] 工具组合使用示例
+- [ ] 最佳实践示例
+
+**预估工作量**: 1.5 小时
+
+---
+
+### 4. 工具清单更新（0/1）
+
+#### 4.1 tools-manifest.json 🔴
+**内容**:
+- [ ] 更新 `structuredOutput.tools` 列表（37 个工具）
+- [ ] 更新 `structuredOutput.schemas` 映射
+- [ ] 更新覆盖率统计（100%）
+- [ ] 更新工具分类
+
+**预估工作量**: 0.5 小时
+
+---
+
+### 5. 中文文档更新（0/1）
+
+#### 5.1 docs/MCP-Probe-Kit-使用手册.md 🔴
+**内容**:
+- [ ] 更新工具列表
+- [ ] 添加结构化输出说明
+- [ ] 更新使用示例
+- [ ] 添加 vNext 升级说明
+
+**预估工作量**: 2 小时
+
+---
+
+## 📊 进度统计
+
+| 任务类别 | 已完成 | 总数 | 完成率 |
+|---------|--------|------|--------|
+| 核心文档 | 3 | 3 | 100% |
+| 工具分类文档 | 0 | 6 | 0% |
+| 文档站页面 | 0 | 4 | 0% |
+| 工具清单 | 0 | 1 | 0% |
+| 中文文档 | 0 | 1 | 0% |
+| **总计** | **3** | **15** | **20%** |
+
+**工作量统计**:
+- 已完成: 3 小时
+- 待完成: 13 小时
+- 总计: 16 小时
+
+---
+
+## 🎯 下一步计划
+
+### 优先级 P0（必须完成）
+
+1. **工具分类文档**（7 小时）
+   - 创建 6 个工具分类文档
+   - 每个工具都有详细的参数说明和示例
+
+2. **工具清单更新**（0.5 小时）
+   - 更新 tools-manifest.json
+
+3. **中文文档更新**（2 小时）
+   - 更新使用手册
+
+### 优先级 P1（建议完成）
+
+4. **文档站页面**（5.5 小时）
+   - 创建 4 个文档站页面
+   - 提供完整的工具参考和示例
+
+---
+
+## 📝 注意事项
+
+1. **工具数量变化**
+   - 原 49 个工具 → 37 个工具
+   - 已删除 10 个过时工具
+   - 已合并 2 个重复工具
+
+2. **Schema 定义**
+   - 41 个 Schema 定义
+   - 按功能分类到 6 个文件
+   - 所有工具都有 `_meta.schema` 字段
+
+3. **测试覆盖**
+   - 142 个契约测试，100% 通过
+   - 测试执行时间 < 3 秒
+
+4. **向后兼容性**
+   - 所有工具保持 `content.text` 字段
+   - 旧客户端可正常使用
+
+---
+
+## 🔗 相关文档
+
+- [M8.9-DOCUMENTATION.md](../tasks/M8.9-DOCUMENTATION.md) - 任务文档
+- [m8.9-documentation-requirements.md](../../../.kiro/specs/m8.9-documentation-requirements.md) - 需求规格
+- [PROGRESS-SUMMARY.md](../PROGRESS-SUMMARY.md) - 进度总结
+- [00-INDEX.md](../tasks/00-INDEX.md) - 任务索引
+
+---
+
+**更新时间**: 2026-01-26  
+**文档版本**: v1.0  
+**维护者**: MCP Probe Kit Team

package/docs/specs/vnext-upgrade/PROGRESS-SUMMARY.md

@@ -0,0 +1,195 @@
+# vNext 升级进度总结
+
+**更新时间**: 2026-01-26  
+**当前状态**: 🟢 契约测试完成（100% 完成）
+
+---
+
+## 📊 整体进度
+
+| 指标 | 完成情况 |
+|------|----------|
+| 故事点 | 86/88（97.7%）|
+| 工具迁移 | 37/39（94.9%）|
+| 测试覆盖 | 142/142（100%）|
+
+---
+
+## ✅ 已完成工作
+
+### M8.1: Schema 定义 ✅
+- **完成日期**: 2026-01-26
+- **产出**: 41 个 Schema 定义，按功能分类到 6 个文件
+- **状态**: 100% 完成
+
+### M8.2: P1 高价值工具 ✅
+- **完成日期**: 2026-01-26
+- **工具数**: 7 个
+- **测试数**: 28 个（100% 通过）
+- **状态**: 代码迁移 + 契约测试完成
+
+**工具列表**:
+1. ✅ code_review - 代码审查
+2. ✅ debug - 调试分析
+3. ✅ fix_bug - Bug 修复指导
+4. ✅ gentest - 生成测试
+5. ✅ refactor - 重构建议
+6. ✅ security_scan - 安全扫描
+7. ✅ perf - 性能分析
+
+### M8.3: 生成工具 ✅
+- **完成日期**: 2026-01-26
+- **工具数**: 7 个（原 12 个，已清理 5 个）
+- **测试数**: 28 个（100% 通过）
+- **状态**: 代码迁移 + 契约测试完成
+
+**工具列表**:
+1. ✅ gendoc - 生成代码注释
+2. ✅ genapi - 生成 API 文档
+3. ✅ gensql - 生成 SQL 查询
+4. ✅ genreadme - 生成 README
+5. ✅ gen_mock - 生成 Mock 数据
+6. ✅ genchangelog - 生成 Changelog
+7. ✅ genpr - 生成 PR 描述
+
+### M8.4: 编排工具 ✅
+- **完成日期**: 2026-01-26
+- **工具数**: 5 个
+- **测试数**: 20 个（100% 通过）
+- **状态**: 代码迁移 + 契约测试完成
+
+**工具列表**:
+1. ✅ start_review - 代码审查工作流
+2. ✅ start_release - 发布工作流
+3. ✅ start_refactor - 重构工作流
+4. ✅ start_api - API 开发工作流
+5. ✅ start_doc - 文档工作流
+
+### M8.5: 项目管理工具 ✅
+- **完成日期**: 2026-01-26
+- **工具数**: 7 个
+- **测试数**: 21 个（100% 通过）
+- **状态**: 代码迁移 + 契约测试完成
+
+**工具列表**:
+1. ✅ init_project - 初始化项目（代码✅，测试✅）
+2. ✅ init_project_context - 初始化项目上下文（代码✅，测试✅）
+3. ✅ add_feature - 添加功能（代码✅，测试✅）
+4. ✅ analyze_project - 分析项目（代码✅，测试✅）
+5. ✅ estimate - 工作量估算（代码✅，测试✅）
+6. ✅ check_deps - 检查依赖（代码✅，测试✅）
+7. ✅ resolve_conflict - 解决冲突（代码✅，测试✅）
+
+### M8.6: UI/UX 工具 ✅
+- **完成日期**: 2026-01-26
+- **工具数**: 5 个
+- **测试数**: 21 个（100% 通过）
+- **状态**: 代码迁移 + 契约测试完成
+
+**工具列表**:
+1. ✅ ui_design_system - 设计系统生成
+2. ✅ ui_search - UI 搜索
+3. ✅ sync_ui_data - 同步 UI 数据
+4. ✅ init_component_catalog - 初始化组件目录
+5. ✅ render_ui - 渲染 UI
+
+### M8.8: 完整集成测试 ✅
+- **完成日期**: 2026-01-26
+- **测试数**: 142 个（100% 通过）
+- **状态**: 所有契约测试完成
+
+**测试覆盖**:
+- P0 工具: 24 个测试 ✅
+- P1 工具: 28 个测试 ✅
+- 生成工具: 28 个测试 ✅
+- 编排工具: 20 个测试 ✅
+- 项目管理工具: 21 个测试 ✅
+- UI/UX 工具: 21 个测试 ✅
+
+### 工具清理 ✅
+- **删除工具数**: 10 个
+- **原因**: 功能重叠、过于简单、或已合并到其他工具
+- **详情**: 见 [TOOL_CLEANUP.md](./TOOL_CLEANUP.md)
+
+---
+
+## 🎊 里程碑达成
+
+### 契约测试 100% 完成！
+
+- **总测试数**: 142 个
+- **通过率**: 100%
+- **覆盖工具**: 37 个（所有已迁移工具）
+- **测试类型**: 基本响应、Schema 验证、_meta 字段
+
+---
+
+## 📈 测试覆盖详情
+
+### 已完成测试（142/142）
+
+| 类别 | 测试数 | 状态 |
+|------|--------|------|
+| P0 工具 | 24/24 | ✅ 100% |
+| P1 工具 | 28/28 | ✅ 100% |
+| 生成工具 | 28/28 | ✅ 100% |
+| 编排工具 | 20/20 | ✅ 100% |
+| 项目管理工具 | 21/21 | ✅ 100% |
+| UI/UX 工具 | 21/21 | ✅ 100% |
+| **总计** | **142** | **100%** |
+
+---
+
+## 🎯 下一步行动
+
+### M8.9: 文档完善 🟡
+
+**状态**: 可以开始  
+**故事点**: 6  
+**依赖**: M8.8 完成 ✅  
+**任务**: 
+- 更新所有文档
+- 添加使用示例
+- 添加 Schema 说明
+- 更新 README
+- 添加迁移指南
+
+---
+
+## 📚 相关文档
+
+### 完成总结
+- [M8.2-SUMMARY.md](./completed/M8.2-SUMMARY.md) - P1 工具迁移总结
+- [M8.3-SUMMARY.md](./completed/M8.3-SUMMARY.md) - 生成工具迁移总结
+- [M8.3-TEST-SUMMARY.md](./completed/M8.3-TEST-SUMMARY.md) - 生成工具测试总结
+- [M8.4-SUMMARY.md](./completed/M8.4-SUMMARY.md) - 编排工具迁移总结
+- [M8.4-TEST-SUMMARY.md](./completed/M8.4-TEST-SUMMARY.md) - 编排工具测试总结
+- [M8.5-TEST-SUMMARY.md](./completed/M8.5-TEST-SUMMARY.md) - 项目管理工具测试总结
+- [M8.6-SUMMARY.md](./completed/M8.6-SUMMARY.md) - UI/UX 工具迁移总结
+- [M8.8-TEST-SUMMARY.md](./completed/M8.8-TEST-SUMMARY.md) - 完整集成测试总结
+
+### 任务文档
+- [00-INDEX.md](./tasks/00-INDEX.md) - 任务索引和进度
+- [M8.5-PROJECT-TOOLS.md](./tasks/M8.5-PROJECT-TOOLS.md) - 项目管理工具任务
+- [M8.8-INTEGRATION-TESTS.md](./tasks/M8.8-INTEGRATION-TESTS.md) - 集成测试任务
+- [M8.9-DOCUMENTATION.md](./tasks/M8.9-DOCUMENTATION.md) - 文档完善任务
+
+### 其他文档
+- [TOOL_CLEANUP.md](./TOOL_CLEANUP.md) - 工具清理方案
+- [STRUCTURED_OUTPUT.md](../STRUCTURED_OUTPUT.md) - 结构化输出规范
+
+---
+
+## 🎉 关键成果
+
+1. **100% 测试覆盖**: 所有 37 个已迁移工具的契约测试全部完成
+2. **高质量**: 所有 142 个测试 100% 通过
+3. **清晰文档**: 每个阶段都有详细的完成总结
+4. **工具精简**: 删除 10 个过时工具，提高维护性
+5. **结构化输出**: 所有工具都正确实现了 _meta.schema 字段
+
+---
+
+**文档版本**: v1.1  
+**最后更新**: 2026-01-26  
+**维护者**: MCP Probe Kit Team