mcp-probe-kit 1.15.0 → 2.0.0

package/docs/specs/vnext-upgrade/completed/M8.1-SUMMARY.md

@@ -0,0 +1,247 @@
+# M8.1: Schema 定义 - 完成总结 ✅
+
+**完成日期**: 2026-01-26  
+**故事点**: 10  
+**实际用时**: 约 1 小时
+
+---
+
+## 🎯 任务目标
+
+为所有 43 个待迁移工具定义完整的 JSON Schema 和 TypeScript 类型定义。
+
+---
+
+## ✅ 主要成果
+
+### 1. 按功能分类的 Schema 文件
+
+创建了 6 个分类文件 + 1 个索引文件：
+
+| 文件 | 工具数 | 描述 |
+|------|--------|------|
+| `core-tools.ts` | 7 | 核心开发工具 |
+| `generation-tools.ts` | 12 | 代码生成工具 |
+| `workflow-tools.ts` | 5 | 工作流编排工具 |
+| `project-tools.ts` | 8 | 项目管理工具 |
+| `ui-ux-tools.ts` | 6 | UI/UX 工具 |
+| `helper-tools.ts` | 3 | 辅助工具 |
+| `index.ts` | - | 统一导出 + 工具映射 |
+
+### 2. Schema 定义统计
+
+- **总 Schema 数**: 41 个（43 个工具，interview 和 ask_user 已支持 Elicitation）
+- **TypeScript 类型**: 41 个接口定义
+- **Schema 映射表**: 完整的工具名称 -> Schema 映射
+
+### 3. 核心开发工具 Schema (7 个)
+
+1. **CodeReviewReportSchema** - 代码审查报告
+   - 问题列表（严重程度、类别、建议）
+   - 代码优点和改进建议
+   - 代码指标（复杂度、可维护性、测试覆盖率）
+
+2. **DebugReportSchema** - 调试报告
+   - 根本原因分析
+   - 错误类型和位置
+   - 调试策略和解决方案
+
+3. **BugAnalysisSchema** - Bug 分析
+   - Bug 类型和严重程度
+   - 受影响的组件和文件
+   - 修复计划和测试计划
+
+4. **TestSuiteSchema** - 测试套件
+   - 测试用例列表
+   - 边界条件测试
+   - Mock 数据和覆盖率目标
+
+5. **RefactorPlanSchema** - 重构计划
+   - 重构步骤
+   - 风险评估
+   - 预估工作量和预期收益
+
+6. **SecurityReportSchema** - 安全报告
+   - 漏洞列表（类型、严重程度、修复建议）
+   - 合规性检查
+   - 安全建议
+
+7. **PerformanceReportSchema** - 性能报告
+   - 性能瓶颈
+   - 性能指标
+   - 优化建议
+
+### 4. 代码生成工具 Schema (12 个)
+
+- DocumentationSchema (gendoc)
+- APIDocumentationSchema (genapi)
+- SQLQuerySchema (gensql)
+- ReadmeSchema (genreadme)
+- UIComponentSchema (genui)
+- MockDataSchema (gen_mock)
+- ChangelogSchema (genchangelog)
+- PullRequestSchema (genpr)
+- CodeFixSchema (fix)
+- ExplanationSchema (explain)
+- ConversionSchema (convert)
+- CSSOrderSchema (css_order)
+
+### 5. 工作流编排工具 Schema (5 个)
+
+- ReviewWorkflowSchema (start_review)
+- ReleaseWorkflowSchema (start_release)
+- RefactorWorkflowSchema (start_refactor)
+- APIWorkflowSchema (start_api)
+- DocWorkflowSchema (start_doc)
+
+**注**: 所有编排工具都基于 `WorkflowReportSchema`
+
+### 6. 项目管理工具 Schema (8 个)
+
+- ProjectInitSchema (init_project)
+- ProjectContextSchema (init_project_context)
+- FeatureSpecSchema (add_feature)
+- ProjectAnalysisSchema (analyze_project)
+- EstimateSchema (estimate)
+- DependencyReportSchema (check_deps)
+- SplitPlanSchema (split)
+- ConflictResolutionSchema (resolve_conflict)
+
+### 7. UI/UX 工具 Schema (6 个)
+
+- DesignSystemSchema (ui_design_system)
+- UISearchResultSchema (ui_search)
+- SyncReportSchema (sync_ui_data)
+- Design2CodeSchema (design2code)
+- ComponentCatalogSchema (init_component_catalog)
+- RenderResultSchema (render_ui)
+
+### 8. 辅助工具 Schema (3 个)
+
+- ShellDetectionSchema (detect_shell)
+- SettingInitSchema (init_setting)
+- SkillDocSchema (gen_skill)
+
+---
+
+## 📦 产出物
+
+### 文件列表
+
+```
+src/schemas/output/
+├── index.ts                    # 统一导出 + 工具映射
+├── core-tools.ts               # 核心开发工具 Schema (7 个)
+├── generation-tools.ts         # 代码生成工具 Schema (12 个)
+├── workflow-tools.ts           # 工作流编排工具 Schema (5 个)
+├── project-tools.ts            # 项目管理工具 Schema (8 个)
+├── ui-ux-tools.ts              # UI/UX 工具 Schema (6 个)
+└── helper-tools.ts             # 辅助工具 Schema (3 个)
+```
+
+### 代码统计
+
+- **总行数**: 约 2,500 行
+- **Schema 定义**: 41 个
+- **TypeScript 接口**: 41 个
+- **辅助函数**: 3 个（getSchemaName, supportsStructuredOutput, getSupportedTools）
+
+---
+
+## 🎨 设计亮点
+
+### 1. 按功能分类
+
+将 Schema 按功能分类到不同文件，而不是按优先级（P0/P1/P2），使得：
+- 文件组织更清晰
+- 易于查找和维护
+- 符合业务逻辑
+
+### 2. 统一导出
+
+通过 `index.ts` 统一导出所有 Schema，提供：
+- 简洁的导入方式
+- 工具名称 -> Schema 的映射表
+- 辅助函数（检查工具是否支持结构化输出）
+
+### 3. 完整的类型定义
+
+每个 Schema 都有对应的 TypeScript 接口，提供：
+- 类型安全
+- IDE 自动补全
+- 编译时检查
+
+### 4. 详细的注释
+
+每个 Schema 都有：
+- 用途说明
+- 字段描述
+- 枚举值说明
+
+---
+
+## 🔗 使用示例
+
+```typescript
+// 导入 Schema
+import { 
+  CodeReviewReportSchema, 
+  CodeReviewReport 
+} from '@/schemas/output';
+
+// 使用 Schema
+const report: CodeReviewReport = {
+  summary: '代码审查完成',
+  overallScore: 85,
+  issues: [
+    {
+      severity: 'medium',
+      category: 'quality',
+      message: '函数过长，建议拆分',
+      suggestion: '将函数拆分为多个小函数',
+    },
+  ],
+};
+
+// 使用辅助函数
+import { supportsStructuredOutput, getSchemaName } from '@/schemas/output';
+
+if (supportsStructuredOutput('code_review')) {
+  const schemaName = getSchemaName('code_review');
+  console.log(schemaName); // 'CodeReviewReportSchema'
+}
+```
+
+---
+
+## ✅ 验收标准
+
+- [x] 所有 41 个 Schema 定义完成
+- [x] 所有 Schema 都有对应的 TypeScript 类型
+- [x] 所有 Schema 都有详细的 JSDoc 注释
+- [x] Schema 按功能分类到不同文件
+- [x] 提供统一的导出和辅助函数
+- [x] 文档更新完成
+
+---
+
+## 🎯 下一步
+
+**M8.2: P1 高价值工具迁移**
+
+开始迁移 7 个 P1 工具：
+1. code_review
+2. debug
+3. fix_bug
+4. gentest
+5. refactor
+6. security_scan
+7. perf
+
+**预估时间**: 2 周  
+**故事点**: 14
+
+---
+
+**最后更新**: 2026-01-26  
+**状态**: ✅ 已完成

package/docs/specs/vnext-upgrade/completed/M8.2-SUMMARY.md

@@ -0,0 +1,296 @@
+# M8.2 P1 高价值工具迁移 - 完成总结
+
+## 📊 任务概览
+
+| 指标 | 数值 |
+|------|------|
+| 任务编号 | M8.2 |
+| 任务名称 | P1 高价值工具迁移到结构化输出 |
+| 工具数量 | 7 个 |
+| 故事点 | 14 |
+| 开始日期 | 2026-01-26 |
+| 完成日期 | 2026-01-26 |
+| 实际耗时 | < 1 天 |
+| 状态 | ✅ 已完成（代码迁移 + 契约测试） |
+
+---
+
+## ✅ 已完成工作
+
+### 1. 工具迁移（7/7）
+
+所有 7 个 P1 高价值工具已成功迁移到结构化输出：
+
+| 工具名称 | Schema 类型 | 状态 | 说明 |
+|---------|------------|------|------|
+| code_review | CodeReviewReport | ✅ | 代码审查，支持多种审查重点 |
+| debug | DebugReport | ✅ | 调试分析，提供根因分析和解决方案 |
+| fix_bug | BugAnalysis | ✅ | Bug 修复指导，完整的修复流程 |
+| gentest | TestSuite | ✅ | 测试用例生成，支持多种测试框架 |
+| refactor | RefactorPlan | ✅ | 重构建议，包含风险评估 |
+| security_scan | SecurityReport | ✅ | 安全扫描，检测常见漏洞 |
+| perf | PerformanceReport | ✅ | 性能分析，识别瓶颈和优化建议 |
+
+### 2. 代码实现
+
+**实现特点**:
+- ✅ 所有工具使用 `okStructured(message, structuredData, { schema })` 返回
+- ✅ 保留了工具的核心功能和指导文本
+- ✅ 添加了结构化数据对象，便于程序化处理
+- ✅ 错误处理统一使用结构化输出
+- ✅ 保持向后兼容（保留 `content.text` 输出）
+- ✅ 所有工具都添加了 `_meta.schema` 字段
+
+**Schema 定义位置**:
+- `src/schemas/output/core-tools.ts` - 包含所有 7 个工具的 Schema 和 TypeScript 类型
+
+**工具文件**:
+- `src/tools/code_review.ts` - 代码审查
+- `src/tools/debug.ts` - 调试分析
+- `src/tools/fix_bug.ts` - Bug 修复指导
+- `src/tools/gentest.ts` - 测试用例生成
+- `src/tools/refactor.ts` - 重构建议
+- `src/tools/security_scan.ts` - 安全扫描
+- `src/tools/perf.ts` - 性能分析
+
+### 3. 契约测试（28/28）
+
+已为所有 7 个工具编写契约测试并全部通过：
+
+| 工具名称 | 测试数量 | 状态 | 测试内容 |
+|---------|---------|------|---------|
+| code_review | 4 | ✅ | 基本响应、Schema 验证、_meta 字段、多种审查重点 |
+| debug | 4 | ✅ | 基本响应、Schema 验证、_meta 字段、带上下文错误 |
+| fix_bug | 4 | ✅ | 基本响应、Schema 验证、_meta 字段、完整 bug 信息 |
+| gentest | 4 | ✅ | 基本响应、Schema 验证、_meta 字段、多种测试框架 |
+| security_scan | 4 | ✅ | 基本响应、Schema 验证、_meta 字段、多种扫描类型 |
+| perf | 4 | ✅ | 基本响应、Schema 验证、_meta 字段、多种分析类型 |
+| refactor | 4 | ✅ | 基本响应、Schema 验证、_meta 字段、多种重构目标 |
+| **总计** | **28** | **✅** | **全部通过** |
+
+**测试文件**: `tests/contracts/structured-output.test.ts`  
+**测试运行**: `npm test -- tests/contracts/structured-output.test.ts`  
+**测试结果**: 73/73 通过（包含之前的 45 个测试）
+
+### 4. 编译验证
+
+- ✅ TypeScript 编译成功通过（`npm run build`）
+- ✅ 所有导入路径正确（使用 `.js` 扩展名）
+- ✅ Schema 类型定义完整
+
+---
+
+## 📈 进度统计
+
+### 整体进度
+
+- **已完成故事点**: 86/88（97.7%）
+- **工具迁移进度**: 37/39（94.9%）
+
+### 按类别统计
+
+| 类别 | 已完成 | 总数 | 完成率 | 测试状态 |
+|------|--------|------|--------|---------|
+| P0 工具 | 6 | 6 | 100% | ✅ 24 测试 |
+| P1 工具 | 7 | 7 | 100% | ✅ 28 测试 |
+| 生成工具 | 7 | 7 | 100% | ⏳ 待测试 |
+| 编排工具 | 5 | 5 | 100% | ⏳ 待测试 |
+| 项目管理工具 | 7 | 7 | 100% | ⏳ 待测试 |
+| UI/UX 工具 | 5 | 5 | 100% | ✅ 21 测试 |
+| 辅助工具 | 0 | 0 | N/A | N/A（已取消） |
+
+**总测试数**: 73/135（54.1%）
+
+---
+
+## 🔍 技术细节
+
+### Schema 设计
+
+所有 P1 工具的 Schema 都设计为独立的类型，包含工具特定的字段：
+
+#### CodeReviewReport Schema
+```typescript
+interface CodeReviewReport {
+  summary: string;
+  overallScore: number;
+  issues: Array<{
+    severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
+    category: 'security' | 'performance' | 'quality' | 'style' | 'best-practice';
+    message: string;
+    // ... 其他字段
+  }>;
+  strengths?: string[];
+  recommendations?: string[];
+}
+```
+
+#### DebugReport Schema
+```typescript
+interface DebugReport {
+  summary: string;
+  rootCause: string;
+  errorType: 'syntax' | 'runtime' | 'logic' | 'performance' | 'memory' | 'network' | 'unknown';
+  solutions: Array<{
+    title: string;
+    description: string;
+    code?: string;
+    priority?: 'high' | 'medium' | 'low';
+  }>;
+  // ... 其他字段
+}
+```
+
+#### BugAnalysis Schema
+```typescript
+interface BugAnalysis {
+  summary: string;
+  bugType: 'functional' | 'performance' | 'security' | 'ui' | 'data' | 'integration';
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  rootCause: string;
+  fixPlan: {
+    steps: string[];
+    estimatedTime?: string;
+    risks?: string[];
+  };
+  testPlan?: {
+    unitTests?: string[];
+    integrationTests?: string[];
+    manualTests?: string[];
+  };
+}
+```
+
+#### TestSuite Schema
+```typescript
+interface TestSuite {
+  summary: string;
+  framework: 'jest' | 'vitest' | 'mocha' | 'jasmine' | 'pytest' | 'junit';
+  testCases: Array<{
+    name: string;
+    type: 'unit' | 'integration' | 'e2e' | 'performance';
+    code: string;
+    assertions?: string[];
+  }>;
+  edgeCases?: Array<{...}>;
+  mockData?: Record<string, any>;
+}
+```
+
+#### SecurityReport Schema
+```typescript
+interface SecurityReport {
+  summary: string;
+  overallRisk: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  vulnerabilities: Array<{
+    type: 'injection' | 'xss' | 'csrf' | 'auth' | 'crypto' | 'data-exposure' | 'dos' | 'other';
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    title: string;
+    description: string;
+    remediation?: string;
+  }>;
+}
+```
+
+#### PerformanceReport Schema
+```typescript
+interface PerformanceReport {
+  summary: string;
+  overallScore: number;
+  bottlenecks: Array<{
+    type: 'algorithm' | 'memory' | 'database' | 'network' | 'rendering' | 'io';
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    description: string;
+  }>;
+  optimizations: Array<{
+    title: string;
+    description: string;
+    priority: 'high' | 'medium' | 'low';
+    expectedImprovement?: string;
+  }>;
+}
+```
+
+#### RefactorPlan Schema
+```typescript
+interface RefactorPlan {
+  summary: string;
+  goal: 'improve_readability' | 'reduce_complexity' | 'improve_performance' | 'improve_maintainability' | 'modernize';
+  refactoringSteps: Array<{
+    step: number;
+    title: string;
+    description: string;
+    before?: string;
+    after?: string;
+  }>;
+  riskAssessment: {
+    level: 'low' | 'medium' | 'high';
+    risks: string[];
+    mitigations?: string[];
+  };
+}
+```
+
+---
+
+## ⏭️ 下一步计划
+
+### 剩余任务
+
+1. **M8.3: 生成工具测试**（21 个测试）
+   - gendoc, genapi, gensql, genreadme, gen_mock, genchangelog, genpr
+
+2. **M8.4: 编排工具测试**（20 个测试）
+   - start_review, start_release, start_refactor, start_api, start_doc
+
+3. **M8.5: 项目管理工具测试**（21 个测试）
+   - init_project, init_project_context, add_feature, analyze_project, estimate, check_deps, resolve_conflict
+
+4. **M8.9: 文档完善**（6 故事点）
+   - 更新所有文档，添加使用示例和 Schema 说明
+
+**预估时间**: 2-3 周
+
+---
+
+## 📝 经验总结
+
+### 成功经验
+
+1. **Schema 设计清晰** - 每个工具有独立的 Schema，字段明确且类型安全
+2. **保留核心功能** - 迁移时保留了工具的核心指导文本和功能
+3. **错误处理统一** - 所有工具使用结构化输出处理错误
+4. **测试覆盖全面** - 每个工具 4 个测试，覆盖基本功能、Schema 验证、_meta 字段和特殊场景
+5. **编译验证及时** - 确保所有代码编译通过，类型安全
+
+### 工具特点
+
+**指令生成器模式**:
+- 所有 P1 工具都采用此模式
+- 返回详细的操作指南和分析报告
+- 由 AI 根据指南执行实际操作
+- 结构化输出提供元数据和配置信息
+
+**多样化支持**:
+- code_review: 支持 quality、security、performance、all 等审查重点
+- gentest: 支持 jest、vitest、mocha 等测试框架
+- security_scan: 支持 all、injection、auth、crypto 等扫描类型
+- perf: 支持 algorithm、memory、react、database 等分析类型
+- refactor: 支持多种重构目标
+
+---
+
+## 🎯 质量指标
+
+- ✅ 代码迁移完成率: 100%（7/7）
+- ✅ 测试覆盖率: 100%（28/28）
+- ✅ TypeScript 编译: 通过
+- ✅ 所有测试: 通过
+- ✅ Schema 定义: 完整
+- ✅ 向后兼容: 保持
+
+---
+
+**文档版本**: v1.0  
+**最后更新**: 2026-01-26  
+**状态**: ✅ M8.2 已完成（代码迁移 + 契约测试）