mcp-probe-kit 1.15.1 → 2.0.1

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 测试

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 收集反馈