mcp-probe-kit 1.15.1 → 2.0.0

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

@@ -0,0 +1,338 @@
+# v2.0 快速参考卡片
+
+## 🎯 核心变更一览
+
+### 工具集（Toolset）
+
+| 模式 | 工具数 | 用途 | 配置 |
+|------|--------|------|------|
+| **full** | 49 | 所有工具（默认） | 无需配置 |
+| **core** | 15 | 日常高频工具 | `MCP_TOOLSET=core` |
+| **ui** | 6 | UI/UX 开发 | `MCP_TOOLSET=ui` |
+| **workflow** | 25-30 | AI 代理推荐 | `MCP_TOOLSET=workflow` |
+
+### UI 工具简化
+
+| v1.15 | v2.0 (ui toolset) | v2.0 (full) |
+|-------|-------------------|-------------|
+| 9 个工具 | 6 个对外工具 | 9 个工具 |
+| 用户困惑 | 清晰明确 | 完全兼容 |
+
+**推荐**: 使用 `start_ui` 作为统一入口 ⭐
+
+---
+
+## 📋 工具集清单
+
+### Core（15 个）- 日常必备
+
+```
+✅ interview          - 需求访谈
+✅ ask_user           - AI 提问
+✅ init_project_context - 项目上下文
+✅ analyze_project    - 项目分析
+✅ code_review        - 代码审查
+✅ security_scan      - 安全扫描
+✅ perf               - 性能分析
+✅ debug              - 调试助手
+✅ fix                - 自动修复
+✅ gentest            - 测试生成
+✅ genapi             - API 文档
+✅ genpr              - PR 描述
+✅ gencommit          - 提交消息 ⭐ 必须保留
+✅ estimate           - 工作量估算
+✅ start_bugfix       - Bug 修复流程
+```
+
+### UI（6 个）- UI/UX 开发
+
+```
+⭐ start_ui           - 统一入口（推荐）
+✅ ui_search          - 智能搜索
+✅ ui_design_system   - 设计系统生成
+✅ design2code        - 设计稿转代码
+✅ genui              - 通用 UI 生成
+✅ sync_ui_data       - 数据同步
+
+❌ init_component_catalog - 内部工具（full 可用）
+❌ render_ui          - 内部工具（full 可用）
+```
+
+### Workflow（25-30 个）- AI 代理推荐
+
+**P0 编排入口（5 个）**：
+```
+⭐ start_feature      - 新功能开发
+⭐ start_bugfix       - Bug 修复
+⭐ start_ui           - UI 开发
+⭐ start_onboard      - 快速上手
+⭐ start_ralph        - 循环开发
+```
+
+**其他编排（5 个）**：
+```
+✅ start_review       - 代码体检
+✅ start_release      - 发布准备
+✅ start_refactor     - 代码重构
+✅ start_api          - API 开发
+✅ start_doc          - 文档生成
+```
+
+**关键依赖（15-20 个）**：
+```
+interview, ask_user, init_project_context, analyze_project,
+add_feature, estimate, code_review, security_scan, perf,
+debug, fix, gentest, gencommit, genpr, genchangelog,
+genapi, gen_mock, design2code, ui_design_system, ui_search
+```
+
+---
+
+## 🔧 配置示例
+
+### 默认配置（Full 模式）
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["mcp-probe-kit@2.0.0"]
+    }
+  }
+}
+```
+
+### Core 模式（日常开发）
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["mcp-probe-kit@2.0.0"],
+      "env": {
+        "MCP_TOOLSET": "core"
+      }
+    }
+  }
+}
+```
+
+### UI 模式（UI 开发）
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit-ui": {
+      "command": "npx",
+      "args": ["mcp-probe-kit@2.0.0"],
+      "env": {
+        "MCP_TOOLSET": "ui"
+      }
+    }
+  }
+}
+```
+
+### Workflow 模式（AI 代理）
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["mcp-probe-kit@2.0.0"],
+      "env": {
+        "MCP_TOOLSET": "workflow"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 📊 P0 工具结构化输出
+
+### gencommit
+
+**输入**: 代码变更  
+**输出**: 
+```typescript
+{
+  type: "feat" | "fix" | "docs" | ...,
+  scope?: string,
+  subject: string,
+  body?: string,
+  breaking: boolean,
+  footers?: string[],
+  finalMessage: string  // 可直接复制
+}
+```
+
+### start_bugfix
+
+**输入**: 错误信息  
+**输出**:
+```typescript
+{
+  workflowName: "start_bugfix",
+  summary: string,
+  steps: [...],
+  artifacts: [...],
+  rootCause: {...},
+  fixPlan: {...},
+  testPlan: {...},
+  commitDraft: {...},
+  nextActions: [...]
+}
+```
+
+### start_feature
+
+**输入**: 功能名称 + 描述  
+**输出**:
+```typescript
+{
+  workflowName: "start_feature",
+  summary: string,
+  steps: [...],
+  specArtifacts: {...},
+  estimate: {...},
+  dependencies: [...],
+  nextActions: [...]
+}
+```
+
+### start_ui
+
+**输入**: UI 需求描述  
+**输出**:
+```typescript
+{
+  workflowName: "start_ui",
+  summary: string,
+  steps: [...],
+  designSystem: {...},
+  catalog: {...},
+  renderedCode: string,
+  consistencyRules: [...],
+  nextActions: [...]
+}
+```
+
+---
+
+## 🎯 使用建议
+
+### 场景 1：日常开发
+**推荐**: `core` 模式
+```bash
+# 配置
+MCP_TOOLSET=core
+
+# 常用工具
+gencommit, code_review, gentest, start_bugfix
+```
+
+### 场景 2：UI 开发
+**推荐**: `ui` 模式
+```bash
+# 配置
+MCP_TOOLSET=ui
+
+# 统一入口
+start_ui "登录页面"
+start_ui "用户列表"
+```
+
+### 场景 3：AI 代理
+**推荐**: `workflow` 模式
+```bash
+# 配置
+MCP_TOOLSET=workflow
+
+# 编排工具
+start_feature, start_bugfix, start_ui, start_ralph
+```
+
+### 场景 4：高级用户
+**推荐**: `full` 模式（默认）
+```bash
+# 无需配置，所有 49 个工具可用
+# 包括内部工具：init_component_catalog, render_ui
+```
+
+---
+
+## ⚡ 快速命令
+
+### 检查工具集
+```bash
+# 查看当前工具集
+echo $MCP_TOOLSET
+
+# 临时切换工具集
+MCP_TOOLSET=ui npx mcp-probe-kit@2.0.0
+```
+
+### 测试工具
+```bash
+# 测试 gencommit
+npx mcp-probe-kit@2.0.0 gencommit
+
+# 测试 start_ui
+npx mcp-probe-kit@2.0.0 start_ui "登录页面"
+```
+
+### 查看版本
+```bash
+npx mcp-probe-kit@2.0.0 --version
+```
+
+---
+
+## 🔍 故障排查
+
+### 问题 1：工具找不到
+**原因**: 可能使用了非 `full` 模式  
+**解决**: 
+```bash
+# 方案 1：切换到 full 模式
+MCP_TOOLSET=full
+
+# 方案 2：检查工具是否在当前 toolset 中
+# 查看 docs/specs/vnext-upgrade/README.md
+```
+
+### 问题 2：UI 内部工具不可见
+**原因**: `ui` 模式下隐藏了内部工具  
+**解决**:
+```bash
+# 方案 1：使用 start_ui 统一入口（推荐）
+start_ui "页面名称"
+
+# 方案 2：切换到 full 模式
+MCP_TOOLSET=full
+```
+
+### 问题 3：输出格式不对
+**原因**: 旧客户端不支持结构化输出  
+**解决**: 
+- 所有工具都有 `content.text` 输出
+- 检查客户端是否支持 MCP 2025-11-25
+
+---
+
+## 📚 相关文档
+
+- [完整需求文档](./requirements.md)
+- [技术设计文档](./design.md)
+- [任务分解文档](./tasks.md)
+- [UI 工具简化策略](./ui-tools-strategy.md)
+- [vNext PRD](../../vnext/vNext-PRD.md)
+
+---
+
+**打印建议**: A4 纸单面打印，作为快速参考卡片

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

@@ -0,0 +1,125 @@
+# vNext 架构升级 - 文档索引
+
+## 📚 文档导航
+
+### 🎯 核心文档（必读）
+
+1. **[总体规划](./00-OVERVIEW.md)** - 项目概览、目标、策略
+2. **[需求文档](./requirements.md)** - 详细需求说明
+3. **[设计文档](./design.md)** - 架构设计和技术方案
+4. **[快速参考](./QUICK_REFERENCE.md)** - 常用命令和快速查询
+
+### 📋 任务计划
+
+1. **[任务总览](./tasks/00-INDEX.md)** ⭐ - 所有任务的索引
+2. **[M8.1 Schema 定义](./tasks/M8.1-SCHEMA-DEFINITION.md)** - 定义所有工具的 Schema
+3. **[M8.2 P1 工具迁移](./tasks/M8.2-P1-TOOLS.md)** - 高价值工具迁移
+4. **[M8.3 生成工具迁移](./tasks/M8.3-GENERATION-TOOLS.md)** - 基础生成工具迁移
+5. **[M8.4 编排工具迁移](./tasks/M8.4-ORCHESTRATION-TOOLS.md)** - 编排工具迁移
+6. **[M8.5 项目管理工具迁移](./tasks/M8.5-PROJECT-TOOLS.md)** - 项目管理工具迁移
+7. **[M8.6 UI/UX 工具迁移](./tasks/M8.6-UI-TOOLS.md)** - UI/UX 工具迁移
+8. **[M8.7 辅助工具迁移](./tasks/M8.7-HELPER-TOOLS.md)** - 辅助工具迁移
+9. **[M8.8 集成测试](./tasks/M8.8-INTEGRATION-TESTS.md)** - 完整集成测试
+10. **[M8.9 文档完善](./tasks/M8.9-DOCUMENTATION.md)** - 文档完善
+
+### ✅ 已完成的里程碑
+
+1. **[M1-M2 完成总结](./completed/M1-M2-SUMMARY.md)** - SDK 升级 + 工具集
+2. **[M4 完成总结](./completed/M4-SUMMARY.md)** - Tasks API
+3. **[M5 完成总结](./M5_COMPLETION_SUMMARY.md)** - Elicitation
+4. **[M3 完成总结](./M3_COMPLETION_SUMMARY.md)** - P0 工具结构化输出
+
+### 🚀 发布相关
+
+1. **[Beta 发布指南](./BETA_RELEASE_GUIDE.md)** - Beta 版本发布流程
+2. **[GitHub Discussion 模板](./GITHUB_DISCUSSION_TEMPLATE.md)** - 用户反馈收集
+
+### 📊 进度追踪
+
+- **当前状态**: M3 已完成，M8 待开始
+- **完成度**: 12/100 故事点（12%），6/49 工具（12.2%）
+- **预估剩余时间**: 10-14 周
+
+---
+
+## 🗂️ 文档结构
+
+```
+docs/specs/vnext-upgrade/
+├── README.md                          # 本文件（索引）
+├── 00-OVERVIEW.md                     # 总体规划
+├── requirements.md                    # 需求文档
+├── design.md                          # 设计文档
+├── QUICK_REFERENCE.md                 # 快速参考
+├── BETA_RELEASE_GUIDE.md              # Beta 发布指南
+├── GITHUB_DISCUSSION_TEMPLATE.md      # Discussion 模板
+│
+├── tasks/                             # 任务计划目录
+│   ├── 00-INDEX.md                    # 任务索引
+│   ├── M8.1-SCHEMA-DEFINITION.md      # Schema 定义任务
+│   ├── M8.2-P1-TOOLS.md               # P1 工具迁移任务
+│   ├── M8.3-GENERATION-TOOLS.md       # 生成工具迁移任务
+│   ├── M8.4-ORCHESTRATION-TOOLS.md    # 编排工具迁移任务
+│   ├── M8.5-PROJECT-TOOLS.md          # 项目管理工具迁移任务
+│   ├── M8.6-UI-TOOLS.md               # UI/UX 工具迁移任务
+│   ├── M8.7-HELPER-TOOLS.md           # 辅助工具迁移任务
+│   ├── M8.8-INTEGRATION-TESTS.md      # 集成测试任务
+│   └── M8.9-DOCUMENTATION.md          # 文档完善任务
+│
+└── completed/                         # 已完成的里程碑
+    ├── M1-M2-SUMMARY.md               # M1-M2 完成总结
+    ├── M4-SUMMARY.md                  # M4 完成总结
+    ├── M5-SUMMARY.md                  # M5 完成总结（链接）
+    └── M3-SUMMARY.md                  # M3 完成总结（链接）
+```
+
+---
+
+## 🎯 快速开始
+
+### 如果你是新加入的开发者
+
+1. 阅读 **[总体规划](./00-OVERVIEW.md)** 了解项目背景
+2. 阅读 **[需求文档](./requirements.md)** 了解详细需求
+3. 阅读 **[设计文档](./design.md)** 了解技术方案
+4. 查看 **[任务索引](./tasks/00-INDEX.md)** 了解当前进度
+
+### 如果你要开始开发
+
+1. 查看 **[任务索引](./tasks/00-INDEX.md)** 找到当前任务
+2. 阅读对应的任务文档（如 `M8.1-SCHEMA-DEFINITION.md`）
+3. 按照任务文档中的步骤执行
+4. 完成后更新任务状态
+
+### 如果你要发布版本
+
+1. 阅读 **[Beta 发布指南](./BETA_RELEASE_GUIDE.md)**
+2. 确保所有任务完成
+3. 运行所有测试
+4. 按照发布流程执行
+
+---
+
+## 📝 文档更新记录
+
+| 日期 | 版本 | 更新内容 | 作者 |
+|------|------|----------|------|
+| 2026-01-26 | v3.0 | 重组文档结构，创建任务索引 | - |
+| 2026-01-26 | v2.0 | 完成 M3（P0 工具迁移） | - |
+| 2026-01-20 | v1.0 | 初始版本 | - |
+
+---
+
+## 🔗 相关链接
+
+- **项目根目录**: `../../..`
+- **源代码**: `../../../src`
+- **测试代码**: `../../../tests`
+- **工具清单**: `../../../tools-manifest.json`
+- **结构化输出文档**: `../../STRUCTURED_OUTPUT.md`
+
+---
+
+**最后更新**: 2026-01-26  
+**当前版本**: v3.0  
+**状态**: 🎯 M8 待开始

package/docs/specs/vnext-upgrade/STATUS-UPDATE-2026-01-26.md

@@ -0,0 +1,230 @@
+# vNext 升级状态更新 - 2026-01-26
+
+## 🎉 重大里程碑达成
+
+### ✅ M8.8 完整集成测试 - 已完成！
+
+**完成时间**: 2026-01-26  
+**状态**: 所有契约测试 100% 完成
+
+---
+
+## 📊 当前状态
+
+### 整体进度
+
+| 指标 | 完成情况 | 进度 |
+|------|----------|------|
+| 故事点 | 86/88 | 97.7% |
+| 工具迁移 | 37/39 | 94.9% |
+| 测试覆盖 | 142/142 | **100%** ✅ |
+
+### 已完成的里程碑
+
+1. ✅ **M8.1**: Schema 定义（10 故事点）
+2. ✅ **M8.2**: P1 高价值工具（14 故事点）
+3. ✅ **M8.3**: 基础生成工具（18 故事点）
+4. ✅ **M8.4**: 编排工具（10 故事点）
+5. ✅ **M8.5**: 项目管理工具（12 故事点）
+6. ✅ **M8.6**: UI/UX 工具（8 故事点）
+7. ✅ **M8.8**: 完整集成测试（6 故事点）✨
+
+**总计**: 78 故事点已完成
+
+---
+
+## 🎯 测试覆盖详情
+
+### 契约测试统计
+
+| 类别 | 工具数 | 测试数 | 状态 |
+|------|--------|--------|------|
+| P0 工具 | 6 | 24 | ✅ 100% |
+| P1 工具 | 7 | 28 | ✅ 100% |
+| 生成工具 | 7 | 28 | ✅ 100% |
+| 编排工具 | 5 | 20 | ✅ 100% |
+| 项目管理工具 | 7 | 21 | ✅ 100% |
+| UI/UX 工具 | 5 | 21 | ✅ 100% |
+| **总计** | **37** | **142** | **✅ 100%** |
+
+### 测试执行结果
+
+```bash
+npm test -- tests/contracts/structured-output.test.ts
+
+✓ tests/contracts/structured-output.test.ts (142 tests) 2144ms
+  ✓ 应该返回包含 content 和 structuredContent 的响应 1292ms
+
+Test Files  1 passed (1)
+     Tests  142 passed (142)
+  Duration  2.62s
+```
+
+**关键成果**:
+- ✅ 所有 142 个测试通过
+- ✅ 测试执行时间 < 3 秒
+- ✅ 0 个失败，0 个跳过
+
+---
+
+## 📝 本次更新内容
+
+### 1. 文档更新
+
+#### 更新的文档
+- ✅ `docs/specs/vnext-upgrade/tasks/00-INDEX.md`
+  - 更新测试覆盖率为 142/142（100%）
+  - 更新 M8.5 状态为"已完成（代码迁移 + 契约测试）"
+  - 更新 M8.8 状态为"已完成"
+  - 更新整体进度为 86/88 故事点（97.7%）
+
+- ✅ `docs/specs/vnext-upgrade/PROGRESS-SUMMARY.md`
+  - 更新故事点为 86/88（97.7%）
+  - 添加 M8.8 完成记录
+  - 更新下一步行动为 M8.9
+
+- ✅ `docs/specs/vnext-upgrade/tasks/M8.8-INTEGRATION-TESTS.md`
+  - 更新依赖为 M8.5 ✅
+  - 更新状态为"已完成"
+  - 添加完成总结
+  - 更新测试统计（142 个测试）
+
+- ✅ `docs/specs/vnext-upgrade/tasks/M8.9-DOCUMENTATION.md`
+  - 更新依赖为 M8.8 ✅
+  - 更新状态为"可以开始"
+  - 更新工具数量为 37 个
+
+#### 新增的文档
+- ✅ `docs/specs/vnext-upgrade/completed/M8.8-TEST-SUMMARY.md`
+  - M8.8 完整集成测试完成总结
+  - 详细的测试统计和覆盖详情
+  - 技术实现说明
+  - 经验总结
+
+- ✅ `.kiro/specs/m8.9-documentation-requirements.md`
+  - M8.9 文档完善需求规格
+  - 6 个用户故事
+  - 详细的交付物清单
+  - 工作量估算（25 小时）
+
+### 2. 状态同步
+
+所有文档中的进度数据已同步：
+- 故事点: 86/88（97.7%）
+- 工具迁移: 37/39（94.9%）
+- 测试覆盖: 142/142（100%）✅
+
+---
+
+## 🎯 下一步行动
+
+### M8.9: 文档完善 🟡
+
+**状态**: 可以开始  
+**故事点**: 6  
+**预估时间**: 1 周（25 小时）  
+**依赖**: M8.8 ✅（已完成）
+
+#### 主要任务
+
+1. **核心文档更新**（7 小时）
+   - README.md
+   - docs/STRUCTURED_OUTPUT.md
+   - CHANGELOG.md
+
+2. **工具分类文档**（8 小时）
+   - P0 核心工具文档
+   - P1 高价值工具文档
+   - 生成工具文档
+   - 编排工具文档
+   - 项目管理工具文档
+   - UI/UX 工具文档
+
+3. **文档站页面**（5.5 小时）
+   - 所有工具参考页面
+   - Schema 完整参考页面
+   - 迁移指南页面
+   - 使用示例页面
+
+4. **工具清单更新**（0.5 小时）
+   - tools-manifest.json
+
+5. **中文文档更新**（2 小时）
+   - docs/MCP-Probe-Kit-使用手册.md
+
+#### 验收标准
+
+- [ ] 所有 37 个工具都有文档
+- [ ] 所有 Schema 都有定义和示例
+- [ ] 所有核心文档都已更新
+- [ ] 文档站页面完整
+- [ ] 中英文文档都已更新
+
+---
+
+## 📈 项目进度可视化
+
+```
+M8.1 Schema 定义        ████████████████████ 100% ✅
+M8.2 P1 工具           ████████████████████ 100% ✅
+M8.3 生成工具          ████████████████████ 100% ✅
+M8.4 编排工具          ████████████████████ 100% ✅
+M8.5 项目管理工具      ████████████████████ 100% ✅
+M8.6 UI/UX 工具        ████████████████████ 100% ✅
+M8.7 辅助工具          ████████████████████ 已取消 ❌
+M8.8 集成测试          ████████████████████ 100% ✅
+M8.9 文档完善          ░░░░░░░░░░░░░░░░░░░░   0% 🟡
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+总体进度               ██████████████████░░  97.7%
+```
+
+---
+
+## 🎊 关键成就
+
+1. **100% 测试覆盖**: 所有 37 个工具的契约测试全部完成
+2. **高质量**: 所有 142 个测试 100% 通过
+3. **快速执行**: 测试执行时间 < 3 秒
+4. **清晰文档**: 每个阶段都有详细的完成总结
+5. **工具精简**: 删除 10 个过时工具，提高维护性
+6. **结构化输出**: 所有工具都正确实现了 _meta.schema 字段
+
+---
+
+## 📚 相关文档
+
+### 完成总结
+- [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.9-DOCUMENTATION.md](./tasks/M8.9-DOCUMENTATION.md) - 文档完善任务 🟡
+
+### 需求规格
+- [m8.9-documentation-requirements.md](../../.kiro/specs/m8.9-documentation-requirements.md) - M8.9 需求规格 ✨
+
+### 其他文档
+- [PROGRESS-SUMMARY.md](./PROGRESS-SUMMARY.md) - 进度总结
+- [TOOL_CLEANUP.md](./TOOL_CLEANUP.md) - 工具清理方案
+- [STRUCTURED_OUTPUT.md](../STRUCTURED_OUTPUT.md) - 结构化输出规范
+
+---
+
+## 🎯 总结
+
+M8.8 完整集成测试任务已成功完成，所有 142 个契约测试 100% 通过。vNext 升级项目已完成 97.7%，只剩最后一个里程碑 M8.9（文档完善）。
+
+**下一步**: 开始 M8.9 文档完善任务，预计 1 周完成。
+
+---
+
+**更新时间**: 2026-01-26  
+**文档版本**: v1.0  
+**维护者**: MCP Probe Kit Team