mcp-probe-kit 1.15.1 → 2.0.0

package/docs/specs/vnext-upgrade/tasks/M8.1-SCHEMA-DEFINITION.md

@@ -0,0 +1,300 @@
+# M8.1: Schema 定义
+
+## 📊 任务概览
+
+| 项目 | 信息 |
+|------|------|
+| 任务编号 | M8.1 |
+| 任务名称 | 定义所有工具的 Schema |
+| 故事点 | 10 |
+| 预估时间 | 1-2 周 |
+| 优先级 | P0 |
+| 依赖 | M3 已完成 |
+| 状态 | ✅ 已完成 |
+| 完成日期 | 2026-01-26 |
+
+---
+
+## 🎯 任务目标
+
+为所有 43 个待迁移工具定义完整的 JSON Schema 和 TypeScript 类型定义。
+
+---
+
+## 📋 详细任务
+
+### 第 2 组: P1 高价值工具 Schema（7 个）
+
+#### 1. CodeReviewReportSchema
+```typescript
+export const CodeReviewReportSchema = {
+  type: 'object',
+  properties: {
+    summary: { type: 'string', description: '审查总结' },
+    overallScore: { type: 'number', minimum: 0, maximum: 100, description: '总体评分' },
+    issues: {
+      type: 'array',
+      description: '问题列表',
+      items: {
+        type: 'object',
+        properties: {
+          severity: { 
+            type: 'string', 
+            enum: ['critical', 'high', 'medium', 'low', 'info'],
+            description: '严重程度'
+          },
+          category: { 
+            type: 'string', 
+            enum: ['security', 'performance', 'quality', 'style'],
+            description: '问题类别'
+          },
+          line: { type: 'number', description: '行号' },
+          file: { type: 'string', description: '文件路径' },
+          message: { type: 'string', description: '问题描述' },
+          suggestion: { type: 'string', description: '修复建议' },
+        },
+        required: ['severity', 'category', 'message'],
+      },
+    },
+    strengths: { 
+      type: 'array', 
+      items: { type: 'string' },
+      description: '代码优点'
+    },
+    recommendations: { 
+      type: 'array', 
+      items: { type: 'string' },
+      description: '改进建议'
+    },
+  },
+  required: ['summary', 'overallScore', 'issues'],
+} as const;
+```
+
+#### 2. DebugReportSchema
+- 根因分析
+- 调试策略
+- 解决方案列表
+- 相关代码位置
+
+#### 3. BugAnalysisSchema
+- Bug 描述
+- 影响范围
+- 修复计划
+- 测试计划
+- 预估工作量
+
+#### 4. TestSuiteSchema
+- 测试框架
+- 测试用例列表
+- 边界条件
+- Mock 数据
+- 覆盖率目标
+
+#### 5. RefactorPlanSchema
+- 重构目标
+- 重构步骤
+- 风险评估
+- 回滚计划
+- 预估工作量
+
+#### 6. SecurityReportSchema
+- 漏洞列表
+- 风险等级
+- 修复建议
+- 合规性检查
+
+#### 7. PerformanceReportSchema
+- 瓶颈分析
+- 性能指标
+- 优化建议
+- 预期提升
+
+---
+
+### 第 3 组: 基础生成工具 Schema（12 个）
+
+#### 8. DocumentationSchema
+- 文档类型（JSDoc/TSDoc/Javadoc）
+- 函数/类/模块文档
+- 参数说明
+- 返回值说明
+- 示例代码
+
+#### 9-19. 其他生成工具 Schema
+- APIDocumentationSchema
+- SQLQuerySchema
+- ReadmeSchema
+- UIComponentSchema
+- MockDataSchema
+- ChangelogSchema
+- PullRequestSchema
+- CodeFixSchema
+- ExplanationSchema
+- ConversionSchema
+- CSSOrderSchema
+
+---
+
+### 第 4 组: 编排工具 Schema（5 个）
+
+所有编排工具都基于 `WorkflowReportSchema`，只需添加特定字段。
+
+#### 20. ReviewWorkflowSchema
+```typescript
+export const ReviewWorkflowSchema = {
+  type: 'object',
+  allOf: [
+    { $ref: '#/definitions/WorkflowReport' },
+  ],
+  properties: {
+    reviewResults: {
+      type: 'object',
+      properties: {
+        codeReview: { type: 'object', description: '代码审查结果' },
+        securityScan: { type: 'object', description: '安全扫描结果' },
+        perfAnalysis: { type: 'object', description: '性能分析结果' },
+      },
+    },
+    overallScore: { type: 'number', description: '总体评分' },
+  },
+  required: ['reviewResults', 'overallScore'],
+} as const;
+```
+
+#### 21-24. 其他编排工具 Schema
+- ReleaseWorkflowSchema
+- RefactorWorkflowSchema
+- APIWorkflowSchema
+- DocWorkflowSchema
+
+---
+
+### 第 5 组: 项目管理工具 Schema（8 个）
+
+#### 25-32. 项目管理工具 Schema
+- ProjectInitSchema
+- ProjectContextSchema
+- FeatureSpecSchema
+- ProjectAnalysisSchema
+- EstimateSchema
+- DependencyReportSchema
+- SplitPlanSchema
+- ConflictResolutionSchema
+
+---
+
+### 第 6 组: UI/UX 工具 Schema（6 个）
+
+#### 33-38. UI/UX 工具 Schema
+- DesignSystemSchema
+- UISearchResultSchema
+- SyncReportSchema
+- Design2CodeSchema
+- ComponentCatalogSchema
+- RenderResultSchema
+
+---
+
+### 第 7 组: 辅助工具 Schema（3 个）
+
+#### 39-41. 辅助工具 Schema
+- ShellDetectionSchema
+- SettingInitSchema
+- SkillDocSchema
+
+---
+
+## 📝 实施步骤
+
+### 步骤 1: 扩展 Schema 文件
+
+编辑 `src/schemas/structured-output.ts`，添加所有新的 Schema 定义。
+
+### 步骤 2: 添加 TypeScript 类型
+
+为每个 Schema 添加对应的 TypeScript 接口定义。
+
+```typescript
+export interface CodeReviewReport {
+  summary: string;
+  overallScore: number;
+  issues: Array<{
+    severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
+    category: 'security' | 'performance' | 'quality' | 'style';
+    line?: number;
+    file?: string;
+    message: string;
+    suggestion?: string;
+  }>;
+  strengths?: string[];
+  recommendations?: string[];
+}
+```
+
+### 步骤 3: 编写 Schema 文档
+
+在每个 Schema 定义上方添加详细的 JSDoc 注释。
+
+### 步骤 4: 验证 Schema
+
+创建测试文件验证所有 Schema 的有效性。
+
+```typescript
+// tests/schemas/validation.test.ts
+import Ajv from 'ajv';
+import { CodeReviewReportSchema } from '../../src/schemas/structured-output';
+
+describe('Schema Validation', () => {
+  const ajv = new Ajv();
+  
+  it('should validate CodeReviewReportSchema', () => {
+    const validate = ajv.compile(CodeReviewReportSchema);
+    const validData = {
+      summary: 'Code looks good',
+      overallScore: 85,
+      issues: [],
+    };
+    expect(validate(validData)).toBe(true);
+  });
+});
+```
+
+---
+
+## ✅ 验收标准
+
+- [ ] 所有 41 个 Schema 定义完成
+- [ ] 所有 Schema 都有对应的 TypeScript 类型
+- [ ] 所有 Schema 都有详细的 JSDoc 注释
+- [ ] 所有 Schema 通过 JSON Schema 验证
+- [ ] TypeScript 类型检查通过
+- [ ] Schema 文档完整
+
+---
+
+## 📦 产出物
+
+1. **扩展的 Schema 文件**
+   - `src/schemas/structured-output.ts`（新增 41 个 Schema）
+
+2. **Schema 验证测试**
+   - `tests/schemas/validation.test.ts`
+
+3. **Schema 文档**
+   - 每个 Schema 的 JSDoc 注释
+   - 使用示例
+
+---
+
+## 🔗 相关文档
+
+- **[任务索引](./00-INDEX.md)** - 返回任务列表
+- **[M8.2 P1 工具迁移](./M8.2-P1-TOOLS.md)** - 下一个任务
+- **[现有 Schema](../../../src/schemas/structured-output.ts)** - 当前 Schema 定义
+
+---
+
+**最后更新**: 2026-01-26  
+**任务状态**: 🔴 未开始  
+**负责人**: TBD

package/docs/specs/vnext-upgrade/tasks/M8.2-P1-TOOLS.md

@@ -0,0 +1,249 @@
+# M8.2: P1 高价值工具迁移
+
+## 📊 任务概览
+
+| 项目 | 信息 |
+|------|------|
+| 任务编号 | M8.2 |
+| 任务名称 | P1 高价值工具迁移 |
+| 故事点 | 14 |
+| 预估时间 | 2 周 |
+| 优先级 | P0 |
+| 依赖 | M8.1 |
+| 状态 | ✅ 已完成 |
+
+---
+
+## 🎯 任务目标
+
+迁移 7 个 P1 高价值工具到结构化输出，这些是用户最常用的开发工具。
+
+---
+
+## 📋 工具列表
+
+### 1. code_review - 代码审查
+
+**文件**: `src/tools/code_review.ts`  
+**Schema**: `CodeReviewReportSchema`  
+**测试数**: 4 个
+
+**迁移步骤**:
+1. 导入 `okStructured`, `CodeReviewReportSchema`, `CodeReviewReport`
+2. 创建结构化数据对象
+3. 使用 `okStructured()` 返回
+4. 保持 `content.text` 输出
+5. 添加 4 个契约测试
+
+**验收标准**:
+- [x] 返回结构化的审查报告
+- [x] 包含问题列表、严重程度、建议
+- [ ] 4 个契约测试通过
+- [x] 向后兼容
+
+---
+
+### 2. debug - 调试分析 ✅
+
+**文件**: `src/tools/debug.ts`  
+**Schema**: `DebugReportSchema`  
+**测试数**: 4 个
+
+**验收标准**:
+- [x] 返回结构化的调试报告
+- [x] 包含根因分析、调试策略
+- [ ] 4 个契约测试通过
+- [x] 向后兼容
+
+---
+
+### 3. fix_bug - Bug 修复指导 ✅
+
+**文件**: `src/tools/fix_bug.ts`  
+**Schema**: `BugAnalysisSchema`  
+**测试数**: 4 个
+
+**验收标准**:
+- [x] 返回结构化的 Bug 分析
+- [x] 包含修复计划、测试计划
+- [ ] 4 个契约测试通过
+- [x] 向后兼容
+
+---
+
+### 4. gentest - 生成测试 ✅
+
+**文件**: `src/tools/gentest.ts`  
+**Schema**: `TestSuiteSchema`  
+**测试数**: 4 个
+
+**验收标准**:
+- [x] 返回结构化的测试套件
+- [x] 包含测试用例、边界情况
+- [ ] 4 个契约测试通过
+- [x] 向后兼容
+
+---
+
+### 5. refactor - 重构建议 ✅
+
+**文件**: `src/tools/refactor.ts`  
+**Schema**: `RefactorPlanSchema`  
+**测试数**: 4 个
+
+**验收标准**:
+- [x] 返回结构化的重构计划
+- [x] 包含重构步骤、风险评估
+- [ ] 4 个契约测试通过
+- [x] 向后兼容
+
+---
+
+### 6. security_scan - 安全扫描 ✅
+
+**文件**: `src/tools/security_scan.ts`  
+**Schema**: `SecurityReportSchema`  
+**测试数**: 4 个
+
+**验收标准**:
+- [x] 返回结构化的安全报告
+- [x] 包含漏洞列表、修复建议
+- [ ] 4 个契约测试通过
+- [x] 向后兼容
+
+---
+
+### 7. perf - 性能分析 ✅
+
+**文件**: `src/tools/perf.ts`  
+**Schema**: `PerformanceReportSchema`  
+**测试数**: 4 个
+
+**验收标准**:
+- [x] 返回结构化的性能报告
+- [x] 包含瓶颈分析、优化建议
+- [ ] 4 个契约测试通过
+- [x] 向后兼容
+
+---
+
+## 📝 标准迁移流程
+
+### 对于每个工具
+
+1. **更新工具文件**
+   ```typescript
+   import { okStructured } from '../lib/response';
+   import { CodeReviewReportSchema, CodeReviewReport } from '../schemas/structured-output';
+   
+   // ... 工具逻辑 ...
+   
+   const structuredData: CodeReviewReport = {
+     summary: '...',
+     overallScore: 85,
+     issues: [...],
+     // ...
+   };
+   
+   return okStructured(
+     CodeReviewReportSchema,
+     structuredData,
+     textOutput // 保持向后兼容
+   );
+   ```
+
+2. **添加契约测试**
+   ```typescript
+   // tests/contracts/structured-output.test.ts
+   describe('code_review', () => {
+     it('should return structured output', async () => {
+       const result = await server.callTool('code_review', { code: '...' });
+       expect(result.structuredContent).toBeDefined();
+       expect(result.structuredContent.summary).toBeDefined();
+     });
+     
+     // ... 3 more tests
+   });
+   ```
+
+3. **运行测试**
+   ```bash
+   npm test -- tests/contracts/structured-output.test.ts
+   ```
+
+4. **更新文档**
+   - 更新 `docs/STRUCTURED_OUTPUT.md`
+   - 添加使用示例
+
+---
+
+## ✅ 验收标准
+
+- [x] 所有 7 个工具使用 `okStructured()` 返回
+- [x] 所有工具保持 `content.text` 输出
+- [ ] 至少 28 个契约测试通过（7 × 4）
+- [x] TypeScript 类型检查通过
+- [x] TypeScript 编译成功
+- [x] 测试文件类型错误已修复
+- [ ] 所有工具文档更新
+
+---
+
+## 📦 产出物
+
+1. **更新的工具文件**（7 个）
+2. **契约测试**（28 个新测试）
+3. **更新的文档**
+
+---
+
+## 🔗 相关文档
+
+- **[任务索引](./00-INDEX.md)**
+- **[M8.1 Schema 定义](./M8.1-SCHEMA-DEFINITION.md)** - 前置任务
+- **[M8.3 生成工具迁移](./M8.3-GENERATION-TOOLS.md)** - 下一个任务
+
+---
+
+**最后更新**: 2026-01-26  
+**任务状态**: ✅ 已完成（代码迁移完成，待添加测试）  
+**负责人**: AI Assistant
+
+---
+
+## 📝 完成记录
+
+**完成时间**: 2026-01-26
+
+**已完成工作**:
+1. ✅ 迁移 7 个 P1 工具到结构化输出
+   - code_review
+   - debug
+   - fix_bug
+   - gentest
+   - refactor
+   - security_scan
+   - perf
+2. ✅ 所有工具使用 `okStructured()` 返回
+3. ✅ 保持向后兼容（保留 `content.text` 输出）
+4. ✅ TypeScript 类型检查通过
+5. ✅ TypeScript 编译成功
+6. ✅ 修复测试文件类型错误（21 个错误）
+7. ✅ 修复导入路径问题（添加 .js 扩展名）
+
+**待完成工作**:
+1. ⏳ 添加 28 个契约测试（7 × 4）
+2. ⏳ 更新工具文档
+
+**文件变更**:
+- `src/tools/code_review.ts` - 添加结构化输出
+- `src/tools/debug.ts` - 添加结构化输出
+- `src/tools/fix_bug.ts` - 添加结构化输出
+- `src/tools/gentest.ts` - 添加结构化输出
+- `src/tools/refactor.ts` - 添加结构化输出
+- `src/tools/security_scan.ts` - 添加结构化输出
+- `src/tools/perf.ts` - 添加结构化输出
+- `src/schemas/output/index.ts` - 修复导入路径
+- `src/schemas/output/workflow-tools.ts` - 修复导入路径
+- `src/tools/__tests__/start_ui.integration.test.ts` - 修复类型错误
+- `src/tools/__tests__/start_ui.property.test.ts` - 修复类型错误

package/docs/specs/vnext-upgrade/tasks/M8.3-GENERATION-TOOLS.md

@@ -0,0 +1,49 @@
+# M8.3: 基础生成工具迁移
+
+## 📊 任务概览
+
+| 项目 | 信息 |
+|------|------|
+| 任务编号 | M8.3 |
+| 故事点 | 18 |
+| 预估时间 | 2-3 周 |
+| 优先级 | P0 |
+| 依赖 | M8.2 |
+| 工具数 | 12 个 |
+| 测试数 | 36 个（每工具 3 个）|
+| 状态 | 🔴 未开始 |
+
+---
+
+## 📋 工具列表
+
+1. **gendoc** - 生成代码注释（DocumentationSchema）
+2. **genapi** - 生成 API 文档（APIDocumentationSchema）
+3. **gensql** - 生成 SQL 查询（SQLQuerySchema）
+4. **genreadme** - 生成 README（ReadmeSchema）
+5. **genui** - 生成 UI 组件（UIComponentSchema）
+6. **gen_mock** - 生成 Mock 数据（MockDataSchema）
+7. **genchangelog** - 生成 Changelog（ChangelogSchema）
+8. **genpr** - 生成 PR 描述（PullRequestSchema）
+9. **fix** - 自动修复代码（CodeFixSchema）
+10. **explain** - 代码解释（ExplanationSchema）
+11. **convert** - 代码转换（ConversionSchema）
+12. **css_order** - CSS 属性排序（CSSOrderSchema）
+
+---
+
+## 📝 标准迁移流程
+
+每个工具按照 M8.2 的标准流程迁移，每个工具至少 3 个契约测试。
+
+---
+
+## ✅ 验收标准
+
+- [ ] 所有 12 个工具迁移完成
+- [ ] 至少 36 个契约测试通过
+- [ ] TypeScript 类型检查通过
+
+---
+
+**[返回任务索引](./00-INDEX.md)** | **[下一个: M8.4](./M8.4-ORCHESTRATION-TOOLS.md)**

package/docs/specs/vnext-upgrade/tasks/M8.4-ORCHESTRATION-TOOLS.md

@@ -0,0 +1,28 @@
+# M8.4: 编排工具迁移
+
+## 📊 任务概览
+
+| 项目 | 信息 |
+|------|------|
+| 任务编号 | M8.4 |
+| 故事点 | 10 |
+| 预估时间 | 1-2 周 |
+| 工具数 | 5 个 |
+| 测试数 | 20 个（每工具 4 个）|
+| 状态 | 🔴 未开始 |
+
+---
+
+## 📋 工具列表
+
+1. **start_review** - 代码审查工作流（ReviewWorkflowSchema）
+2. **start_release** - 发布工作流（ReleaseWorkflowSchema）
+3. **start_refactor** - 重构工作流（RefactorWorkflowSchema）
+4. **start_api** - API 开发工作流（APIWorkflowSchema）
+5. **start_doc** - 文档工作流（DocWorkflowSchema）
+
+**注**: 所有编排工具都基于 `WorkflowReportSchema`
+
+---
+
+**[返回任务索引](./00-INDEX.md)** | **[下一个: M8.5](./M8.5-PROJECT-TOOLS.md)**

package/docs/specs/vnext-upgrade/tasks/M8.5-PROJECT-TOOLS.md

@@ -0,0 +1,29 @@
+# M8.5: 项目管理工具迁移
+
+## 📊 任务概览
+
+| 项目 | 信息 |
+|------|------|
+| 任务编号 | M8.5 |
+| 故事点 | 12 |
+| 预估时间 | 1-2 周 |
+| 工具数 | 8 个 |
+| 测试数 | 24 个（每工具 3 个）|
+| 状态 | 🔴 未开始 |
+
+---
+
+## 📋 工具列表
+
+1. **init_project** - 初始化项目
+2. **init_project_context** - 初始化项目上下文
+3. **add_feature** - 添加功能
+4. **analyze_project** - 分析项目
+5. **estimate** - 工作量估算
+6. **check_deps** - 检查依赖
+7. **split** - 拆分文件
+8. **resolve_conflict** - 解决冲突
+
+---
+
+**[返回任务索引](./00-INDEX.md)** | **[下一个: M8.6](./M8.6-UI-TOOLS.md)**

package/docs/specs/vnext-upgrade/tasks/M8.6-UI-TOOLS.md

@@ -0,0 +1,66 @@
+# M8.6: UI/UX 工具迁移
+
+## 📊 任务概览
+
+| 项目 | 信息 |
+|------|------|
+| 任务编号 | M8.6 |
+| 故事点 | 8 |
+| 预估时间 | 1 周 |
+| 工具数 | 5 个 |
+| 测试数 | 21 个（ui_search 9个，其他每工具 3 个）|
+| 状态 | ✅ 已完成（代码迁移） |
+| 完成日期 | 2026-01-26 |
+
+---
+
+## 📋 工具列表
+
+1. ✅ **ui_design_system** - 设计系统生成
+2. ✅ **ui_search** - UI 搜索（支持 3 种模式）
+3. ✅ **sync_ui_data** - 同步 UI 数据
+4. ✅ **init_component_catalog** - 初始化组件目录（内部工具，新创建）
+5. ✅ **render_ui** - 渲染 UI（内部工具，新创建）
+
+**已删除工具**:
+- ❌ **design2code** - 已合并到 start_ui 工作流
+
+## 📊 完成情况
+
+- **代码迁移**: ✅ 已完成（5/5 工具）
+- **TypeScript 编译**: ✅ 通过
+- **契约测试**: ⏳ 待完成（21 个测试）
+- **文档更新**: ⏳ 待完成
+
+## 🔍 实现亮点
+
+1. **新增内部工具** - 创建了 init_component_catalog 和 render_ui 两个内部工具
+2. **多模式支持** - ui_search 支持 search/catalog/template 三种模式
+3. **智能推理** - ui_design_system 使用 AI 推理引擎生成设计系统
+4. **结构化输出** - 所有工具使用 okStructured() 返回结构化数据
+
+## 📝 详细总结
+
+查看完整的实现细节和技术文档：[M8.6-SUMMARY.md](../completed/M8.6-SUMMARY.md)
+
+## ✅ 测试完成情况
+
+- **契约测试**: ✅ 已完成（21 个测试全部通过）
+  - ui_design_system: 3 个测试 ✅
+  - ui_search: 9 个测试 ✅（3 种模式 × 3）
+  - sync_ui_data: 3 个测试 ✅
+  - init_component_catalog: 3 个测试 ✅
+  - render_ui: 3 个测试 ✅
+
+**测试文件**: `tests/contracts/structured-output.test.ts`
+
+**测试覆盖**:
+- 基本响应结构验证
+- Schema 字段类型验证
+- _meta 字段和 schema 信息验证
+- 多模式支持验证（ui_search）
+- 错误处理验证
+
+---
+
+**[返回任务索引](./00-INDEX.md)** | **[下一个: M8.7](./M8.7-HELPER-TOOLS.md)**