mcp-probe-kit 1.15.1 → 2.0.0

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

@@ -0,0 +1,221 @@
+# vNext 架构升级 - 需求文档
+
+## 📋 概述
+
+**功能名称**: vNext 架构升级  
+**优先级**: P0（关键）  
+**目标版本**: 2.0.0  
+**协议版本**: MCP 2025-11-25  
+**预估工作量**: 13-21 故事点（大型史诗）
+
+## 🎯 目标
+
+将 MCP Probe Kit 从 49 个工具的集合转变为智能化、结构化、可扩展的开发助手：
+
+1. **降低 AI 选择困惑** - 通过工具集组织（core/ui/workflow/full）
+2. **支持长时运行工作流** - 通过 Tasks API 处理复杂操作
+3. **提供机器可读输出** - 通过结构化 schema 和验证
+4. **标准化用户交互** - 通过 Elicitation 处理表单和敏感数据
+5. **保持向后兼容** - 所有现有用户无缝继续使用
+
+## 🔍 问题陈述
+
+### 当前痛点
+
+1. **工具过载**（49 个工具）
+   - AI 模型难以选择正确的工具
+   - 用户认知负担高
+   - 频繁出现工具选择错误
+   - **UI 工具特别混乱**：9 个 UI 工具，用户不知道用哪个
+
+2. **工作流不稳定**
+   - `start_*` 编排工具在长时操作时超时
+   - 信息缺失导致工作流失败
+   - 输出格式不一致，难以串联
+
+3. **输出不可机器读取**
+   - 大多数工具返回非结构化文本
+   - AI 必须解析自然语言（容易出错）
+   - 难以验证或串联结果
+
+4. **客户端能力差异**
+   - 不同 MCP 客户端支持不同功能
+   - 缺乏优雅降级策略
+   - 跨平台用户体验差
+
+5. **核心工具未被优先展示**
+   - 高价值工具如 `gencommit` 和 `start_*` 被淹没
+   - 常见工作流缺乏清晰入口
+   - **UI 工具缺乏统一入口**：`init_component_catalog` 和 `render_ui` 等内部工具暴露给用户
+
+## 👥 用户故事
+
+### US-1: 简化工具发现
+**作为** 使用 AI 辅助的开发者  
+**我希望** 只看到与当前任务相关的工具  
+**以便** AI 不会浪费时间探索无关选项
+
+**验收标准：**
+- [ ] `MCP_TOOLSET=workflow` 只显示 25-30 个编排工具
+- [ ] `MCP_TOOLSET=core` 只显示 15 个核心工具
+- [ ] `MCP_TOOLSET=ui` 只显示 6 个 UI/UX 工具（推荐用 `start_ui` 作为统一入口）
+  - 包含：`start_ui`, `ui_search`, `ui_design_system`, `design2code`, `genui`, `sync_ui_data`
+  - 隐藏：`init_component_catalog`, `render_ui`（作为 `start_ui` 内部步骤）
+- [ ] 默认 `full` 模式保留所有 49 个工具（向后兼容）
+
+### US-2: 可靠的长时工作流
+**作为** 运行 `start_bugfix` 的开发者  
+**我希望** 工作流作为后台任务运行  
+**以便** 我可以检查进度而不会阻塞或超时
+
+**验收标准：**
+- [ ] `start_bugfix` 立即返回 taskId
+- [ ] 可以每 5 秒轮询任务状态
+- [ ] 完成时可以获取最终结果
+- [ ] 需要时可以取消任务
+- [ ] 在不支持的客户端上回退到同步模式
+
+### US-3: 结构化提交消息
+**作为** 使用 `gencommit` 的开发者  
+**我希望** 获得包含 type/scope/subject 字段的结构化输出  
+**以便** 我可以在工作流中程序化使用提交消息
+
+**验收标准：**
+- [ ] 返回包含所有提交字段的 `structuredContent`
+- [ ] 包含可直接复制的 `finalMessage`
+- [ ] 仍为旧客户端提供可读的 `content.text`
+- [ ] 集成到 `start_bugfix` 和 `start_feature` 报告中
+
+### US-4: 交互式需求收集
+**作为** 开始新功能的开发者  
+**我希望** AI 通过表单向我提出结构化问题  
+**以便** 我不必手动格式化答案
+
+**验收标准：**
+- [ ] `interview` 在支持时使用 Elicitation 表单
+- [ ] 为常见选择提供枚举选项
+- [ ] 验证必填字段
+- [ ] 在旧客户端上回退到基于文本的问答
+
+### US-5: 向后兼容性
+**作为** 现有用户  
+**我希望** 当前设置继续工作  
+**以便** 我不必重新配置任何东西
+
+**验收标准：**
+- [ ] 所有 49 个工具在 `full` 模式（默认）下仍然可用
+- [ ] 每个工具都返回 `content.text`（人类可读）
+- [ ] 旧客户端仍可调用所有工具
+- [ ] 现有工具签名无破坏性更改
+
+## 📊 成功指标
+
+### 定量指标
+- **工具选择准确率**: 90%+ 首次选择正确（当前约 70%）
+- **工作流完成率**: P0 start_* 工具达到 95%+（当前约 80%）
+- **输出解析错误**: <5%（当前约 25%）
+- **客户端兼容性**: 100% 向后兼容
+
+### 定性指标
+- AI 花费更少时间"探索"工具
+- 用户报告结果更一致
+- 工作流无需人工干预即可完成
+- 失败时有清晰的错误消息
+
+## 🚫 非目标
+
+1. **不改变核心理念** - 仍然是"指令生成器"模式（不写文件系统）
+2. **不删除工具** - 所有 49 个工具保持可用
+3. **不要求特定客户端** - 必须跨 Cursor/Claude Desktop/Cline/Continue 工作
+4. **不添加高权限操作** - 不直接执行代码或网络访问
+
+## 🔗 依赖关系
+
+### 技术依赖
+- 升级到 `@modelcontextprotocol/sdk` v1.25.3+
+- MCP 协议 2025-11-25 支持
+- Node.js 16+（现有要求）
+
+### 功能依赖
+- 工具集机制（FR-2）必须在工作流重构之前实现
+- 结构化输出辅助函数（FR-3）必须在工具迁移之前存在
+- Schema 定义（FR-4）必须在 P0 工具更新之前完成
+
+## 🎯 目标用户
+
+1. **AI 代理**（主要）
+   - 需要清晰的工具组织
+   - 需要机器可读的输出
+   - 受益于结构化工作流
+
+2. **开发者**（主要）
+   - 想要可靠、可预测的结果
+   - 需要长时操作不阻塞
+   - 期望向后兼容
+
+3. **高级用户**（次要）
+   - 可能想要自定义工具集
+   - 欣赏用于脚本的结构化数据
+   - 重视 Tasks 等高级功能
+
+## 📝 假设
+
+1. 大多数用户最初会保持使用 `full` 工具集
+2. Cursor 和 Claude Desktop 将是主要测试客户端
+3. Tasks API 支持将在各客户端逐步推出
+4. 用户更看重可靠性而非前沿功能
+
+## ⚠️ 风险与缓解措施
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| 对现有用户的破坏性更改 | 高 | 中 | 所有工具强制包含 `content.text`；默认 `full` 模式 |
+| 客户端不兼容 | 高 | 高 | 能力检测 + 优雅降级 |
+| 性能下降 | 中 | 低 | 对 P0 工具进行基准测试；优化热路径 |
+| 采用阻力 | 中 | 中 | 清晰的迁移指南；beta 测试期 |
+| 复杂度增加 | 中 | 高 | 全面的文档；辅助工具 |
+
+## 🗓️ 分阶段推出
+
+### 阶段 1：基础（M1-M2）
+- SDK 升级
+- 工具集机制
+- 结构化输出辅助函数
+- 基础测试
+
+### 阶段 2：核心工具（M3）
+- P0 start_* 工具重构
+- WorkflowReport schema
+- gencommit 增强
+
+### 阶段 3：高级功能（M4-M5）
+- Tasks API 集成
+- Elicitation 支持
+- 全面测试
+
+### 阶段 4：完善与发布（M6）
+- 文档
+- 迁移指南
+- Beta 版本
+- 稳定版本
+
+## 📚 相关文档
+
+- [设计文档](./design.md) - 技术架构和实现细节
+- [任务分解](./tasks.md) - 详细任务列表和估算
+- [UI 工具简化策略](./ui-tools-strategy.md) - UI/UX 工具集设计理念
+- [vNext PRD](../../vnext/vNext-PRD.md) - 原始产品需求
+- [MCP 指南](../../vnext/MCP_2025-11-25_GUIDE.md) - 协议规范指南
+
+## ✅ 完成定义
+
+- [ ] 所有 P0 工具（5 个 start_* + gencommit）完全迁移
+- [ ] 工具集过滤正常工作
+- [ ] 结构化输出通过 schema 验证
+- [ ] Tasks API 功能正常且有回退
+- [ ] Elicitation 工作正常且有回退
+- [ ] 保持 100% 向后兼容
+- [ ] 文档完整
+- [ ] 在 2+ 个 MCP 客户端上测试
+- [ ] 整合 Beta 反馈
+- [ ] 达到性能基准

package/docs/specs/vnext-upgrade/tasks/00-INDEX.md

@@ -0,0 +1,335 @@
+# M8: 完成所有工具迁移 - 任务索引
+
+## 📊 总体概览
+
+| 指标 | 数值 |
+|------|------|
+| 总任务数 | 9 个子任务 |
+| 总工具数 | 39 个（原 49 个，已清理 10 个）|
+| 总故事点 | 88 |
+| 预估时间 | 8-10 周 |
+| 当前状态 | 🟢 契约测试完成 |
+| 已完成故事点 | 80/88（90.9%）|
+| 已完成工具 | 37/39（94.9%）|
+| 测试覆盖率 | 142/142（100%）✅|
+
+**重要更新**: v2.0 已删除 10 个过时工具，从 49 个减少到 39 个（详见 [TOOL_CLEANUP.md](../TOOL_CLEANUP.md)）
+
+---
+
+## 📋 任务列表
+
+### M8.1 Schema 定义 ✅
+
+**文档**: [M8.1-SCHEMA-DEFINITION.md](./M8.1-SCHEMA-DEFINITION.md)
+
+- **故事点**: 10
+- **预估时间**: 1-2 周
+- **优先级**: P0
+- **依赖**: M3 已完成
+- **状态**: ✅ 已完成
+- **完成日期**: 2026-01-26
+- **产出**: 41 个新 Schema 定义（按功能分类到 6 个文件）
+
+**任务描述**: 为所有 43 个待迁移工具定义 JSON Schema 和 TypeScript 类型
+
+**Schema 文件组织**:
+- `src/schemas/output/core-tools.ts` - 核心开发工具 (7 个)
+- `src/schemas/output/generation-tools.ts` - 代码生成工具 (12 个)
+- `src/schemas/output/workflow-tools.ts` - 工作流编排工具 (5 个)
+- `src/schemas/output/project-tools.ts` - 项目管理工具 (8 个)
+- `src/schemas/output/ui-ux-tools.ts` - UI/UX 工具 (6 个)
+- `src/schemas/output/helper-tools.ts` - 辅助工具 (3 个)
+- `src/schemas/output/index.ts` - 统一导出
+
+---
+
+### M8.2 P1 高价值工具迁移 ✅
+
+**文档**: [M8.2-P1-TOOLS.md](./M8.2-P1-TOOLS.md)
+
+- **故事点**: 14
+- **预估时间**: 2 周
+- **优先级**: P0
+- **依赖**: M8.1
+- **状态**: ✅ 已完成（代码迁移）
+- **完成日期**: 2026-01-26
+- **工具数**: 7 个
+
+**工具列表**:
+1. ✅ code_review - 代码审查
+2. ✅ debug - 调试分析
+3. ✅ fix_bug - Bug 修复指导
+4. ✅ gentest - 生成测试
+5. ✅ refactor - 重构建议
+6. ✅ security_scan - 安全扫描
+7. ✅ perf - 性能分析
+
+**待完成**: 契约测试（28 个）
+
+---
+
+### M8.3 基础生成工具迁移 ✅
+
+**文档**: [M8.3-GENERATION-TOOLS.md](./M8.3-GENERATION-TOOLS.md)
+
+- **故事点**: 18
+- **预估时间**: 2-3 周
+- **优先级**: P0
+- **依赖**: M8.2
+- **状态**: ✅ 已完成（代码迁移 + 契约测试）
+- **完成日期**: 2026-01-26
+- **工具数**: 7 个（原 12 个，已清理 5 个）
+
+**工具列表**:
+1. ✅ gendoc - 生成代码注释
+2. ✅ genapi - 生成 API 文档
+3. ✅ gensql - 生成 SQL 查询
+4. ✅ genreadme - 生成 README
+5. ✅ gen_mock - 生成 Mock 数据
+6. ✅ genchangelog - 生成 Changelog
+7. ✅ genpr - 生成 PR 描述
+
+**已删除工具** (不再需要迁移):
+- ❌ genui - 已合并到 start_ui
+- ❌ fix - 功能与 code_review 重叠
+- ❌ explain - AI 核心能力，不需要工具
+- ❌ convert - 功能过于宽泛
+- ❌ css_order - 规范已整合到 ui_design_system
+
+**已完成**: ✅ 契约测试（28 个，全部通过）
+
+---
+
+### M8.4 编排工具迁移 ✅
+
+**文档**: [M8.4-ORCHESTRATION-TOOLS.md](./M8.4-ORCHESTRATION-TOOLS.md)
+
+- **故事点**: 10
+- **预估时间**: 1-2 周
+- **优先级**: P0
+- **依赖**: M8.3
+- **状态**: ✅ 已完成（代码迁移 + 契约测试）
+- **完成日期**: 2026-01-26
+- **工具数**: 5 个
+
+**工具列表**:
+1. ✅ start_review - 代码审查工作流
+2. ✅ start_release - 发布工作流
+3. ✅ start_refactor - 重构工作流
+4. ✅ start_api - API 开发工作流
+5. ✅ start_doc - 文档工作流
+
+**已完成**: ✅ 契约测试（20 个，全部通过）
+
+---
+
+### M8.5 项目管理工具迁移 ✅
+
+**文档**: [M8.5-PROJECT-TOOLS.md](./M8.5-PROJECT-TOOLS.md)
+
+- **故事点**: 12
+- **预估时间**: 1-2 周
+- **优先级**: P1
+- **依赖**: M8.4
+- **状态**: ✅ 已完成（代码迁移 + 契约测试）
+- **完成日期**: 2026-01-26
+- **工具数**: 7 个（原 8 个，已删除 split）
+
+**工具列表**:
+1. ✅ init_project - 初始化项目
+2. ✅ init_project_context - 初始化项目上下文
+3. ✅ add_feature - 添加功能
+4. ✅ analyze_project - 分析项目
+5. ✅ estimate - 工作量估算
+6. ✅ check_deps - 检查依赖
+7. ✅ resolve_conflict - 解决冲突
+
+**已删除工具**:
+- ❌ split - 功能过于简单
+
+**已完成**: ✅ 契约测试（21 个，全部通过）
+
+---
+
+### M8.6 UI/UX 工具迁移 ✅
+
+**文档**: [M8.6-UI-TOOLS.md](./M8.6-UI-TOOLS.md)
+
+- **故事点**: 8
+- **预估时间**: 1 周
+- **优先级**: P1
+- **依赖**: M8.5
+- **状态**: ✅ 已完成（代码迁移 + 契约测试）
+- **完成日期**: 2026-01-26
+- **工具数**: 5 个
+
+**工具列表**:
+1. ✅ ui_design_system - 设计系统生成
+2. ✅ ui_search - UI 搜索
+3. ✅ sync_ui_data - 同步 UI 数据
+4. ✅ init_component_catalog - 初始化组件目录（内部，新创建）
+5. ✅ render_ui - 渲染 UI（内部，新创建）
+
+**已删除工具**:
+- ❌ design2code - 已合并到 start_ui
+
+**已完成**: ✅ 契约测试（21 个，全部通过）
+
+---
+
+### M8.7 辅助工具迁移 ❌
+
+**文档**: [M8.7-HELPER-TOOLS.md](./M8.7-HELPER-TOOLS.md)
+
+- **故事点**: 4
+- **预估时间**: 已取消
+- **优先级**: P2
+- **依赖**: M8.6
+- **状态**: ❌ 已取消（所有工具已删除）
+- **工具数**: 0 个（原 3 个，全部删除）
+
+**已删除工具**:
+- ❌ detect_shell - 功能过于简单
+- ❌ init_setting - 不是高频工具
+- ❌ gen_skill - 开发者内部工具
+
+---
+
+### M8.8 完整集成测试 ✅
+
+**文档**: [M8.8-INTEGRATION-TESTS.md](./M8.8-INTEGRATION-TESTS.md)
+
+- **故事点**: 6
+- **预估时间**: 1 周
+- **优先级**: P0
+- **依赖**: M8.6（M8.7 已取消）
+- **状态**: ✅ 已完成
+- **完成日期**: 2026-01-26
+
+**任务描述**: 为所有 37 个工具添加契约测试，确保 100% 覆盖
+
+**测试统计**:
+- 契约测试: 142 个（100% 通过）✅
+- 覆盖工具: 37 个（所有已迁移工具）
+- 测试类型: 基本响应、Schema 验证、_meta 字段
+
+---
+
+### M8.9 文档完善 🔴
+
+**文档**: [M8.9-DOCUMENTATION.md](./M8.9-DOCUMENTATION.md)
+
+- **故事点**: 6
+- **预估时间**: 1 周
+- **优先级**: P0
+- **依赖**: M8.8
+
+**任务描述**: 更新所有文档，添加所有工具的使用示例和 Schema 说明
+
+---
+
+## 📊 进度追踪
+
+### 按阶段统计
+
+| 阶段 | 工具数 | 故事点 | 预估时间 | 状态 |
+|------|--------|--------|----------|------|
+| M8.1: Schema 定义 | - | 10 | 1-2 周 | ✅ |
+| M8.2: P1 工具 | 7 | 14 | 2 周 | ✅ |
+| M8.3: 生成工具 | 7 | 18 | 2-3 周 | ✅ |
+| M8.4: 编排工具 | 5 | 10 | 1-2 周 | ✅ |
+| M8.5: 项目管理 | 7 | 12 | 1-2 周 | ✅ |
+| M8.6: UI/UX 工具 | 5 | 8 | 1 周 | ✅ |
+| M8.7: 辅助工具 | 0 | 4 | 已取消 | ❌ |
+| M8.8: 集成测试 | - | 6 | 1 周 | ✅ |
+| M8.9: 文档完善 | - | 6 | 1 周 | 🔴 |
+| **总计** | **39** | **88** | **8-10 周** | |
+
+**注**: 原 43 个工具，已清理 10 个过时工具，剩余 39 个（包含 6 个 P0 工具已完成）
+
+### 完成度
+
+- **已完成**: 86/88 故事点（97.7%）
+- **进行中**: 0/88 故事点（0%）
+- **未开始**: 2/88 故事点（2.3%）
+
+**工具迁移进度**: 37/39 工具已迁移（94.9%）
+- P0 工具: 6/6 已完成（100%）
+- P1 工具: 7/7 已完成（100%）
+- 生成工具: 7/7 已完成（100%）
+- 编排工具: 5/5 已完成（100%）
+- 项目管理工具: 7/7 已完成（100%）
+- UI/UX 工具: 5/5 已完成（100%）
+- 辅助工具: 0/0 已取消（N/A）
+
+**测试覆盖进度**: 142/142 测试已完成（100%）✅
+- P0 工具: 24/24 测试（100%）
+- P1 工具: 28/28 测试（100%）
+- 生成工具: 28/28 测试（100%）
+- 编排工具: 20/20 测试（100%）
+- 项目管理工具: 21/21 测试（100%）✅
+- UI/UX 工具: 21/21 测试（100%）
+
+**工具清理**: 10 个过时工具已删除（详见 [TOOL_CLEANUP.md](../TOOL_CLEANUP.md)）
+
+---
+
+## 🎯 下一步行动
+
+### 开始 M8.9: 文档完善
+
+**任务**: 更新所有文档，添加使用示例和 Schema 说明  
+**文档**: [M8.9-DOCUMENTATION.md](./M8.9-DOCUMENTATION.md)  
+**预估时间**: 1 周  
+**故事点**: 6
+
+**具体步骤**:
+1. 更新主 README.md
+2. 为每个工具添加使用示例
+3. 添加 Schema 说明文档
+4. 更新 API 文档
+5. 添加迁移指南
+
+**已完成的里程碑**:
+- ✅ M8.1: Schema 定义
+- ✅ M8.2: P1 高价值工具（7 个）
+- ✅ M8.3: 基础生成工具（7 个）
+- ✅ M8.4: 编排工具（5 个）
+- ✅ M8.5: 项目管理工具（7 个）
+- ✅ M8.6: UI/UX 工具（5 个）
+- ✅ M8.8: 集成测试（142 个契约测试）✅
+- ✅ 工具清理（删除 10 个过时工具）
+
+**待完成**:
+- ⏳ M8.9: 文档完善（最后一个里程碑！）
+
+---
+
+## 📝 任务执行规范
+
+### 每个任务的标准流程
+
+1. **阅读任务文档** - 了解任务目标和验收标准
+2. **创建分支** - `git checkout -b feature/M8.x-task-name`
+3. **实现功能** - 按照任务文档执行
+4. **编写测试** - 至少达到要求的测试数量
+5. **运行测试** - 确保所有测试通过
+6. **更新文档** - 同步更新相关文档
+7. **代码审查** - 自我审查或团队审查
+8. **合并代码** - 合并到主分支
+9. **更新状态** - 更新任务状态为"已完成"
+
+### 质量标准
+
+- 所有新代码必须有测试
+- TypeScript 类型检查必须通过
+- 所有测试必须通过
+- 代码覆盖率 > 80%
+- 文档必须同步更新
+
+---
+
+**最后更新**: 2026-01-26  
+**文档版本**: v1.3  
+**状态**: 🟢 M8 进行顺利（M8.1 ✅, M8.2 ✅, M8.3 ✅, 工具清理 ✅）