mcp-probe-kit 1.15.1 → 2.0.1

package/docs/specs/v2.1-planning.md

@@ -0,0 +1,335 @@
+# MCP Probe Kit v2.1 版本规划
+
+## 📋 版本信息
+
+**版本号**: 2.1.0  
+**计划发布**: 2026-02-15  
+**当前状态**: 📝 规划中  
+**上一版本**: 2.0.0 (2026-01-27)
+
+---
+
+## 🎯 版本目标
+
+v2.1 版本聚焦于**优化开发体验**和**提升文档质量**，主要改进项目上下文管理和文档组织方式。
+
+**核心主题**: 模块化与效率提升
+
+---
+
+## ✨ 主要特性
+
+### 1. 模块化项目上下文 (project-context-modular)
+
+**优先级**: P1  
+**状态**: 📝 规格设计完成  
+**预估工作量**: 5 故事点（9-14 小时）
+
+#### 功能描述
+
+改进 `init_project_context` 工具，支持生成模块化的项目上下文文档。
+
+**核心改进**：
+- 将单一的 `project-context.md` 拆分为索引文件 + 5 个分类文档
+- 按需加载，减少 AI 上下文压力
+- 保持向后兼容，默认使用单文件模式
+
+**文档结构**：
+```
+docs/
+├── project-context.md          # 索引文件
+└── project-context/            # 分类文档
+    ├── tech-stack.md           # 技术栈
+    ├── architecture.md         # 架构
+    ├── coding-standards.md     # 编码规范
+    ├── dependencies.md         # 依赖
+    └── workflows.md            # 工作流
+```
+
+**使用方式**：
+```bash
+# 单文件模式（默认，向后兼容）
+init_project_context
+
+# 模块化模式（新功能）
+init_project_context mode=modular
+```
+
+**规格文档**: [docs/specs/project-context-modular/](./project-context-modular/)
+
+---
+
+## 📊 工作量估算
+
+### 总体估算
+
+| 特性 | 故事点 | 预估时间 | 优先级 |
+|------|--------|----------|--------|
+| project-context-modular | 5 | 9-14h | P1 |
+| **总计** | **5** | **9-14h** | |
+
+### 时间分配
+
+| 阶段 | 时间 | 占比 |
+|------|------|------|
+| 开发 | 6-8h | 60% |
+| 测试 | 2-3h | 25% |
+| 文档 | 1-2h | 12% |
+| 验收 | 0.5-1h | 5% |
+
+---
+
+## 📅 开发计划
+
+### 里程碑
+
+| 里程碑 | 日期 | 内容 |
+|--------|------|------|
+| M1: 规格完成 | 2026-01-27 ✅ | 需求、设计、任务文档完成 |
+| M2: 开发完成 | 2026-01-30 | 核心功能实现，测试通过 |
+| M3: 文档完成 | 2026-02-03 | README、在线文档更新 |
+| M4: 发布准备 | 2026-02-10 | 最终测试、CHANGELOG |
+| M5: 正式发布 | 2026-02-15 | npm 发布，文档上线 |
+
+### 详细时间线
+
+#### Week 1 (2026-01-27 - 2026-02-02)
+
+**Day 1-2: 核心开发**
+- [ ] 创建模板文件（6个）
+- [ ] 实现项目信息分析函数
+- [ ] 实现模板渲染和文件生成
+- [ ] 添加 mode 参数支持
+
+**Day 3: 测试和优化**
+- [ ] 编写单元测试
+- [ ] 编写集成测试
+- [ ] 性能优化
+- [ ] 错误处理
+
+#### Week 2 (2026-02-03 - 2026-02-09)
+
+**Day 1-2: 文档更新**
+- [ ] 更新 README.md
+- [ ] 更新在线文档
+- [ ] 添加使用示例
+- [ ] 更新 CHANGELOG
+
+**Day 3-4: 验收和测试**
+- [ ] 手动测试（多种项目类型）
+- [ ] 兼容性测试
+- [ ] 性能测试
+- [ ] 代码审查
+
+#### Week 3 (2026-02-10 - 2026-02-15)
+
+**Day 1-2: 发布准备**
+- [ ] 最终测试
+- [ ] 版本号更新
+- [ ] 构建和打包
+- [ ] 发布说明
+
+**Day 3: 正式发布**
+- [ ] npm 发布
+- [ ] 文档网站更新
+- [ ] GitHub Release
+- [ ] 社区通知
+
+---
+
+## 🎯 成功指标
+
+### 功能指标
+
+- [ ] 模块化模式正常工作
+- [ ] 单文件模式保持兼容
+- [ ] 文档独立完整
+- [ ] 性能满足要求（< 2秒）
+
+### 质量指标
+
+- [ ] 代码覆盖率 > 80%
+- [ ] 所有测试通过
+- [ ] 无严重 Bug
+- [ ] 向后兼容 100%
+
+### 用户体验指标
+
+- [ ] 文档清晰易懂
+- [ ] 使用简单直观
+- [ ] 错误提示友好
+- [ ] 性能体验良好
+
+---
+
+## ⚠️ 风险管理
+
+### 主要风险
+
+| 风险 | 影响 | 概率 | 缓解措施 | 负责人 |
+|------|------|------|----------|--------|
+| 向后兼容性破坏 | 高 | 低 | 默认单文件模式，充分测试 | 开发团队 |
+| 发布延期 | 中 | 中 | 预留缓冲时间，简化非核心功能 | PM |
+| 用户接受度低 | 中 | 低 | 提供清晰文档，保持可选性 | 产品团队 |
+
+### 应急计划
+
+**如果开发延期**：
+- 优先保证核心功能（模块化模式）
+- 简化测试范围（仅核心流程）
+- 延后文档更新（可在 2.1.1 补充）
+
+**如果发现严重 Bug**：
+- 立即修复并重新测试
+- 延后发布日期
+- 发布 Hotfix 版本
+
+---
+
+## 📝 发布说明（草稿）
+
+### v2.1.0 - 模块化与效率提升
+
+**发布日期**: 2026-02-15
+
+#### 🎉 新特性
+
+**模块化项目上下文**
+- 支持生成模块化的项目上下文文档
+- 将项目信息分类到 5 个独立文档
+- 提供索引文件进行导航
+- 按需加载，减少 AI 上下文压力
+
+#### 🔧 改进
+
+- 优化文档组织方式
+- 提升大型项目的分析性能
+- 改进错误提示信息
+
+#### 🐛 修复
+
+- 修复 xxx 问题
+- 修复 xxx 问题
+
+#### 📚 文档
+
+- 更新 README.md
+- 更新在线文档
+- 添加模块化模式使用指南
+
+#### ⚠️ 破坏性变更
+
+无。本版本完全向后兼容。
+
+#### 🔄 迁移指南
+
+无需迁移。默认行为保持不变。
+
+如需使用新的模块化模式：
+```bash
+init_project_context mode=modular
+```
+
+---
+
+## 🔗 相关资源
+
+### 规格文档
+- [project-context-modular 规格](./project-context-modular/)
+  - [需求文档](./project-context-modular/requirements.md)
+  - [设计文档](./project-context-modular/design.md)
+  - [任务清单](./project-context-modular/tasks.md)
+  - [工作量估算](./project-context-modular/estimate.md)
+
+### 项目文档
+- [README.md](../../README.md)
+- [CHANGELOG.md](../../CHANGELOG.md)
+- [在线文档](https://mcp-probe-kit.bytezonex.com)
+
+### 开发资源
+- [GitHub Repository](https://github.com/mybolide/mcp-probe-kit)
+- [npm Package](https://www.npmjs.com/package/mcp-probe-kit)
+- [Issue Tracker](https://github.com/mybolide/mcp-probe-kit/issues)
+
+---
+
+## 📞 团队协作
+
+### 角色分工
+
+| 角色 | 负责人 | 职责 |
+|------|--------|------|
+| 产品经理 | - | 需求管理、优先级决策 |
+| 技术负责人 | - | 技术方案、代码审查 |
+| 开发工程师 | - | 功能实现、单元测试 |
+| 测试工程师 | - | 测试计划、质量保证 |
+| 文档工程师 | - | 文档编写、示例代码 |
+
+### 沟通机制
+
+- **每日站会**: 同步进度，识别阻塞
+- **周会**: 回顾进展，调整计划
+- **代码审查**: 所有代码必须经过审查
+- **文档审查**: 所有文档必须经过审查
+
+---
+
+## 📈 后续规划
+
+### v2.2 候选特性
+
+- 支持自定义文档模板
+- 支持多语言文档生成
+- 支持文档自动更新
+- 集成到 CI/CD 流程
+
+### 长期规划
+
+- 构建完整的项目知识库
+- 支持团队协作和共享
+- 集成更多 AI 工具
+- 提供可视化界面
+
+---
+
+## ✅ 检查清单
+
+### 开发前
+
+- [x] 需求文档完成
+- [x] 设计文档完成
+- [x] 任务清单完成
+- [x] 工作量估算完成
+- [ ] 技术方案评审通过
+- [ ] 资源分配确认
+
+### 开发中
+
+- [ ] 代码实现完成
+- [ ] 单元测试通过
+- [ ] 集成测试通过
+- [ ] 代码审查通过
+- [ ] 性能测试通过
+
+### 发布前
+
+- [ ] 文档更新完成
+- [ ] CHANGELOG 更新
+- [ ] 版本号更新
+- [ ] 最终测试通过
+- [ ] 发布说明准备
+
+### 发布后
+
+- [ ] npm 发布成功
+- [ ] 文档网站更新
+- [ ] GitHub Release 创建
+- [ ] 社区通知发送
+- [ ] 监控用户反馈
+
+---
+
+*规划版本: 1.0.0*  
+*创建时间: 2026-01-27*  
+*维护者: MCP Probe Kit Team*  
+*状态: 规划中*

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 待开始