mcp-probe-kit 1.15.0 → 2.0.0

package/docs/specs/vnext-upgrade/00-OVERVIEW.md

@@ -0,0 +1,258 @@
+# vNext 架构升级 - 总体规划
+
+## 📊 项目概览
+
+### 基本信息
+
+| 项目 | 信息 |
+|------|------|
+| 项目名称 | MCP Probe Kit vNext 架构升级 |
+| 目标版本 | v2.0 |
+| 当前状态 | M3 已完成，M8 待开始 |
+| 总工具数 | 49 个 |
+| 已迁移工具 | 6 个（12.2%）|
+| 预估总工作量 | 100 故事点 |
+| 预估总时间 | 10-14 周 |
+| 开始日期 | 2026-01-01 |
+| 预计完成日期 | 2026-04-30 |
+
+---
+
+## 🎯 项目目标
+
+### 核心目标
+
+1. **升级到最新 MCP 协议**
+   - 从旧协议升级到 MCP 2025-11-25
+   - 支持最新的 SDK 特性（v1.25.3）
+
+2. **实现结构化输出**
+   - 所有 49 个工具支持结构化输出
+   - 定义完整的 JSON Schema
+   - 保持向后兼容性
+
+3. **增强工具管理**
+   - 工具集过滤（core/ui/workflow/full）
+   - 统一输出封装
+   - 更好的错误处理
+
+4. **支持长任务**
+   - Tasks API 实现
+   - 任务生命周期管理
+   - 任务状态查询
+
+5. **改进用户交互**
+   - Elicitation 支持
+   - interview 和 ask_user 工具
+   - 智能回退方案
+
+---
+
+## 🚀 核心策略
+
+### 一次性完成所有工具
+
+**原则**: 不发布半成品，所有 49 个工具必须全部支持结构化输出后才发布 v2.0
+
+**理由**:
+1. **用户体验一致性** - 所有工具都支持结构化输出
+2. **避免混乱** - 不会有"部分工具支持，部分不支持"的情况
+3. **文档完整性** - 一次性提供完整的文档和示例
+4. **减少维护成本** - 不需要维护多个版本
+5. **专业形象** - 展示完整、成熟的产品
+
+---
+
+## 📋 里程碑规划
+
+### 已完成的里程碑 ✅
+
+| 里程碑 | 任务数 | 故事点 | 时间 | 完成日期 | 状态 |
+|--------|--------|--------|------|----------|------|
+| M1: SDK 升级 | 5 | 3 | 2-3天 | 2026-01-10 | ✅ |
+| M2: 工具集 + 统一输出 | 6 | 5 | 3-4天 | 2026-01-15 | ✅ |
+| M4: Tasks API | 5 | 5 | 3-5天 | 2026-01-20 | ✅ |
+| M5: Elicitation | 4 | 3 | 2-3天 | 2026-01-23 | ✅ |
+| M3: P0 工具结构化 | 8 | 12 | 1周 | 2026-01-26 | ✅ |
+
+**已完成**: 28 任务，28 故事点，约 3 周
+
+### 进行中的里程碑 🎯
+
+| 里程碑 | 任务数 | 故事点 | 预估时间 | 状态 |
+|--------|--------|--------|----------|------|
+| M8: 完成所有工具 | 9 | 88 | 8-10周 | 🔴 未开始 |
+| M6: 文档完善 | 4 | 6 | 1周 | 🟡 部分完成 |
+| M7: Beta 测试与发布 | 5 | 6 | 3-5周 | 🔴 未开始 |
+
+**待完成**: 18 任务，100 故事点，约 12-16 周
+
+---
+
+## 🗓️ 时间表
+
+### 整体时间线
+
+```
+第 1-3 周   ✅ M1-M5 + M3（基础设施 + P0 工具）
+第 4-5 周   🎯 M8.1 + M8.2（Schema 定义 + P1 工具）
+第 6-8 周   🎯 M8.3（基础生成工具）
+第 9-10 周  🎯 M8.4 + M8.5（编排 + 项目管理）
+第 11 周    🎯 M8.6 + M8.7（UI/UX + 辅助工具）
+第 12 周    🎯 M8.8（完整集成测试）
+第 13 周    🎯 M8.9（完善文档）
+第 14 周    🎯 M6 最终文档 + M7 Beta 准备
+第 15-16 周 🎯 M7 Beta 测试（至少 2 周）
+第 17 周    🎯 M7 兼容性测试 + 正式发布
+```
+
+**总计**: 约 17 周（4 个月）
+
+---
+
+## 📊 工具分组
+
+### 第 1 组: P0 核心工具（已完成）✅
+
+**工具数**: 6 个  
+**状态**: ✅ 已完成  
+**完成日期**: 2026-01-26
+
+- ✅ gencommit - Commit 消息生成
+- ✅ start_feature - 功能开发工作流
+- ✅ start_bugfix - Bug 修复工作流
+- ✅ start_ui - UI 开发工作流
+- ✅ start_onboard - 项目上手工作流
+- ✅ start_ralph - Ralph Loop 循环开发
+
+### 第 2 组: P1 高价值工具
+
+**工具数**: 7 个  
+**状态**: 🔴 未开始  
+**预估时间**: 2 周
+
+- code_review - 代码审查
+- debug - 调试分析
+- fix_bug - Bug 修复指导
+- gentest - 生成测试
+- refactor - 重构建议
+- security_scan - 安全扫描
+- perf - 性能分析
+
+### 第 3 组: 基础生成工具
+
+**工具数**: 12 个  
+**状态**: 🔴 未开始  
+**预估时间**: 2-3 周
+
+- gendoc, genapi, gensql, genreadme
+- genui, gen_mock, genchangelog, genpr
+- fix, explain, convert, css_order
+
+### 第 4 组: 编排工具
+
+**工具数**: 5 个  
+**状态**: 🔴 未开始  
+**预估时间**: 1-2 周
+
+- start_review, start_release, start_refactor
+- start_api, start_doc
+
+### 第 5 组: 项目管理工具
+
+**工具数**: 8 个  
+**状态**: 🔴 未开始  
+**预估时间**: 1-2 周
+
+- init_project, init_project_context, add_feature
+- analyze_project, estimate, check_deps
+- split, resolve_conflict
+
+### 第 6 组: UI/UX 工具
+
+**工具数**: 6 个  
+**状态**: 🔴 未开始  
+**预估时间**: 1 周
+
+- ui_design_system, ui_search, sync_ui_data
+- design2code, init_component_catalog, render_ui
+
+### 第 7 组: 辅助工具
+
+**工具数**: 3 个  
+**状态**: 🔴 未开始  
+**预估时间**: 3-5 天
+
+- detect_shell, init_setting, gen_skill
+
+**注**: interview 和 ask_user 已支持 Elicitation，不需要额外迁移
+
+---
+
+## 🎯 成功标准
+
+### v2.0 发布必须满足的条件
+
+**功能完整性**:
+- ✅ 所有基础设施完成（M1-M5）
+- ✅ P0 工具完成（M3）
+- [ ] 所有 43 个剩余工具完成（M8）
+- [ ] 所有 49 个工具支持结构化输出
+
+**测试完整性**:
+- [ ] 159 个契约测试全部通过
+- [ ] 所有集成测试通过
+- [ ] 性能测试通过
+- [ ] 兼容性测试通过
+
+**文档完整性**:
+- [ ] 所有工具文档完成
+- [ ] Schema 参考文档完成
+- [ ] 迁移指南完成
+- [ ] 文档站完成
+
+**质量标准**:
+- [ ] 无 P0/P1 Bug
+- [ ] 代码覆盖率 > 80%
+- [ ] TypeScript 类型检查通过
+- [ ] 向后兼容性 100%
+
+**Beta 测试**:
+- [ ] 至少 2 周 Beta 测试
+- [ ] 收集并处理用户反馈
+- [ ] 修复发现的问题
+
+---
+
+## 📈 进度指标
+
+### 当前进度
+
+- **完成度**: 12/100 故事点（12%）
+- **工具完成度**: 6/49 工具（12.2%）
+- **已用时间**: 3 周
+- **预估剩余时间**: 10-14 周
+
+### 关键指标
+
+| 指标 | 当前值 | 目标值 | 完成度 |
+|------|--------|--------|--------|
+| 工具迁移 | 6 | 49 | 12.2% |
+| Schema 定义 | 6 | 49 | 12.2% |
+| 契约测试 | 24 | 159 | 15.1% |
+| 文档覆盖 | 6 | 49 | 12.2% |
+
+---
+
+## 🔗 相关文档
+
+- **[需求文档](./requirements.md)** - 详细需求说明
+- **[设计文档](./design.md)** - 架构设计和技术方案
+- **[任务索引](./tasks/00-INDEX.md)** - 所有任务的详细计划
+- **[快速参考](./QUICK_REFERENCE.md)** - 常用命令和快速查询
+
+---
+
+**最后更新**: 2026-01-26  
+**文档版本**: v3.0  
+**状态**: 🎯 M8 待开始

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

@@ -0,0 +1,328 @@
+# Beta 版本发布指南
+
+## 📋 发布清单
+
+### ✅ 已完成（M6.3）
+
+- [x] 版本号更新为 2.0.0-beta.1
+- [x] CHANGELOG.md 更新
+- [x] README.md 添加 Beta 测试说明
+- [x] 任务文档更新
+- [x] 完成总结文档
+
+### 🚀 待执行（发布到 npm）
+
+```bash
+# 1. 确保所有更改已提交
+git add .
+git commit -m "chore: 🤖 准备 v2.0.0-beta.1 发布"
+
+# 2. 构建项目
+npm run build
+
+# 3. 运行所有测试
+npm test
+
+# 4. 发布到 npm（使用 beta 标签）
+npm publish --tag beta
+
+# 5. 创建 Git 标签
+git tag v2.0.0-beta.1
+git push origin v2.0.0-beta.1
+
+# 6. 推送到 GitHub
+git push origin main
+```
+
+### 📢 发布后操作
+
+1. **创建 GitHub Discussion**
+   - 标题: "v2.0.0-beta.1 Beta 测试 - 欢迎反馈"
+   - 内容: 包含新特性、测试重点、反馈方式
+   - 链接: https://github.com/mybolide/mcp-probe-kit/discussions
+
+2. **创建 GitHub Release（可选）**
+   - 标题: "v2.0.0-beta.1 - Beta Release"
+   - 标签: v2.0.0-beta.1
+   - 标记为 "Pre-release"
+   - 内容: 从 CHANGELOG.md 复制
+
+3. **社交媒体宣传（可选）**
+   - Twitter/X
+   - Reddit (r/programming, r/MachineLearning)
+   - Hacker News
+
+## 📊 Beta 测试计划
+
+### 测试期
+
+- **开始日期**: 2026-01-26
+- **结束日期**: 2026-02-09（至少 2 周）
+- **目标**: 收集至少 10 个用户反馈
+
+### 测试重点
+
+1. **工具集过滤**
+   - 测试 `MCP_TOOLSET=core/ui/workflow/full`
+   - 验证工具数量正确
+   - 验证必须工具存在
+
+2. **Tasks API**
+   - 测试任务创建和查询
+   - 测试任务取消
+   - 测试 TTL 清理
+
+3. **向后兼容性**
+   - 从 v1.x 升级测试
+   - 验证所有工具正常工作
+   - 验证输出格式兼容
+
+4. **客户端兼容性**
+   - Cursor
+   - Claude Desktop
+   - Cline
+   - Continue
+
+### 反馈收集
+
+**渠道**:
+- GitHub Issues（Bug 报告）
+- GitHub Discussions（功能建议、使用体验）
+
+**关注指标**:
+- Bug 数量和严重程度
+- 功能请求
+- 性能问题
+- 兼容性问题
+- 用户满意度
+
+## 🔄 Beta 迭代计划
+
+### Beta.2（如需要）
+
+**触发条件**:
+- 发现 P0 Bug
+- 重要功能缺失
+- 严重性能问题
+
+**发布流程**:
+1. 修复问题
+2. 更新版本号为 2.0.0-beta.2
+3. 更新 CHANGELOG
+4. 重新发布
+5. 通知测试用户
+
+### Beta.3+（如需要）
+
+重复 Beta.2 流程
+
+## ✅ 稳定版发布条件
+
+满足以下所有条件才能发布 v2.0.0 稳定版：
+
+1. **测试完成**
+   - [x] 至少 2 周 Beta 测试期
+   - [ ] 收集至少 10 个用户反馈
+   - [ ] 所有 P0 Bug 已修复
+   - [ ] 所有 P1 Bug 已修复或延后
+
+2. **兼容性验证**
+   - [ ] Cursor 测试通过
+   - [ ] Claude Desktop 测试通过
+   - [ ] Cline 测试通过（如可能）
+   - [ ] Continue 测试通过（如可能）
+
+3. **文档完善**
+   - [x] CHANGELOG 完整
+   - [x] MIGRATION.md 完整
+   - [x] COMPATIBILITY.md 完整
+   - [ ] GitHub Pages 文档站完善
+
+4. **性能验证**
+   - [x] 所有性能测试通过
+   - [ ] 无性能退化
+   - [ ] 内存使用正常
+
+## 📝 发布公告模板
+
+### GitHub Discussion
+
+```markdown
+# v2.0.0-beta.1 Beta 测试 - 欢迎反馈 🎉
+
+大家好！
+
+我们很高兴地宣布 MCP Probe Kit v2.0 的第一个 Beta 版本正式发布！
+
+## 🎯 核心特性
+
+### 1. 工具集管理
+通过 `MCP_TOOLSET` 环境变量按需加载工具：
+- `core` (15个) - 日常高频工具
+- `ui` (6个) - UI/UX 设计工具
+- `workflow` (32个) - 智能编排工具
+- `full` (49个) - 所有工具（默认）
+
+### 2. Tasks API
+支持长时间运行的任务：
+- 任务状态管理
+- 任务查询和取消
+- TTL 自动清理
+
+### 3. Elicitation 支持
+智能用户交互：
+- 文本格式回退（当前实现）
+- 表单式提问（未来支持）
+- 向后兼容所有客户端
+
+### 4. 统一输出格式
+100% 向后兼容：
+- `okText()` - 纯文本响应
+- `okStructured()` - 结构化响应（为未来准备）
+- `errorResponse()` - 错误响应
+
+## 📊 性能基准
+
+- 工具集定义访问: < 10ms
+- 任务创建: < 10ms
+- 任务查询: < 5ms
+- 批量任务 (100个): < 50ms
+- 并发任务 (50个): < 100ms
+- 内存使用: ~13 MB
+
+## 🧪 如何参与测试
+
+### 安装 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
+\`\`\`
+
+### 测试重点
+
+请重点测试以下功能：
+
+- ✅ 工具集过滤（`MCP_TOOLSET=core/ui/workflow/full`）
+- ✅ Tasks API（长任务支持）
+- ✅ 所有 49 个工具的正常工作
+- ✅ 向后兼容性（从 v1.x 升级）
+- ✅ 不同 MCP 客户端的兼容性
+
+### 反馈方式
+
+遇到问题或有建议？请通过以下方式反馈：
+
+1. **Bug 报告**: [GitHub Issues](https://github.com/mybolide/mcp-probe-kit/issues)
+2. **功能建议**: 在本 Discussion 中回复
+3. **使用体验**: 在本 Discussion 中分享
+
+## ⚠️ 已知限制
+
+- 结构化输出延后到 v2.1
+- 工具任务化延后到 v2.1
+- 文档站待完善
+
+## 📚 文档
+
+- [CHANGELOG](https://github.com/mybolide/mcp-probe-kit/blob/main/CHANGELOG.md)
+- [迁移指南](https://github.com/mybolide/mcp-probe-kit/blob/main/docs/MIGRATION.md)
+- [兼容性矩阵](https://github.com/mybolide/mcp-probe-kit/blob/main/docs/COMPATIBILITY.md)
+
+## 🚀 下一步计划
+
+- M6.4: Beta 测试与反馈收集（2 周）
+- M6.5: 最终兼容性测试
+- M6.6: 稳定版发布 (v2.0.0)
+
+感谢大家的支持和测试！🙏
+
+---
+
+**测试期**: 2026-01-26 至 2026-02-09（至少 2 周）
+```
+
+### GitHub Release
+
+```markdown
+# v2.0.0-beta.1 - Beta Release
+
+## 🎉 Beta 版本发布
+
+这是 v2.0 的第一个 Beta 版本，包含了全新的架构升级和核心功能。
+
+## ✅ 已完成的里程碑
+
+- **M1**: SDK 升级 + 基础回归
+- **M2**: 工具集管理 + 统一输出
+- **M4**: Tasks API
+- **M5**: Elicitation
+- **M6.1**: 核心文档编写
+- **M6.2**: 性能基准测试
+
+## 🎯 核心特性
+
+1. **工具集管理** - 按需加载工具
+2. **Tasks API** - 长任务支持
+3. **Elicitation 支持** - 智能用户交互
+4. **统一输出格式** - 100% 向后兼容
+
+## 📊 性能基准
+
+- 所有核心操作 < 10ms
+- 内存使用 ~13 MB
+- 57+ 个测试全部通过
+
+## 🧪 参与 Beta 测试
+
+安装：
+\`\`\`bash
+npm install -g mcp-probe-kit@2.0.0-beta.1
+\`\`\`
+
+反馈：[GitHub Discussions](https://github.com/mybolide/mcp-probe-kit/discussions)
+
+## 📚 文档
+
+- [CHANGELOG](CHANGELOG.md)
+- [迁移指南](docs/MIGRATION.md)
+- [兼容性矩阵](docs/COMPATIBILITY.md)
+
+## ⚠️ 已知限制
+
+- 结构化输出延后到 v2.1
+- 工具任务化延后到 v2.1
+- 文档站待完善
+
+---
+
+**测试期**: 2026-01-26 至 2026-02-09（至少 2 周）
+```
+
+## 📞 联系方式
+
+如有紧急问题，请联系：
+- GitHub: [@mybolide](https://github.com/mybolide)
+- Email: 通过 GitHub Issues 联系
+
+## 🎉 总结
+
+Beta 版本发布准备就绪！执行上述步骤即可完成发布。
+
+**关键步骤**：
+1. ✅ 代码准备完成
+2. 🚀 执行发布命令
+3. 📢 创建 Discussion
+4. 🧪 开始 Beta 测试