mcp-probe-kit 1.15.1 → 2.0.0

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

@@ -0,0 +1,848 @@
+# vNext 架构升级 - 设计文档
+
+## 📐 技术架构
+
+### 整体架构图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    MCP Probe Kit v2.0                        │
+│                  (MCP Protocol 2025-11-25)                   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      工具集过滤层                             │
+│  ┌──────────┬──────────┬──────────┬──────────┐              │
+│  │  full    │  core    │    ui    │ workflow │              │
+│  │ (49工具) │ (15工具) │ (10工具) │ (25工具) │              │
+│  └──────────┴──────────┴──────────┴──────────┘              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    统一输出封装层                             │
+│  ┌────────────────────────────────────────────┐             │
+│  │  okText(text, meta?)                       │             │
+│  │  okStructured({schema, data, textFallback})│             │
+│  └────────────────────────────────────────────┘             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      工具执行层                               │
+│  ┌──────────────┬──────────────┬──────────────┐            │
+│  │  基础工具    │  编排工具    │  UI/UX工具   │            │
+│  │  (37个)      │  (9个)       │  (3个)       │            │
+│  └──────────────┴──────────────┴──────────────┘            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    高级功能层                                 │
+│  ┌──────────────┬──────────────┬──────────────┐            │
+│  │  Tasks API   │  Elicitation │  Schema验证  │            │
+│  │  (长任务)    │  (表单/URL)  │  (结构化)    │            │
+│  └──────────────┴──────────────┴──────────────┘            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 🏗️ 核心组件设计
+
+### 1. 工具集管理器（Toolset Manager）
+
+**职责：** 根据环境变量过滤和组织工具列表
+
+**接口：**
+```typescript
+interface ToolsetManager {
+  // 获取当前工具集配置
+  getCurrentToolset(): ToolsetType;
+  
+  // 根据工具集过滤工具列表
+  filterTools(allTools: Tool[], toolset: ToolsetType): Tool[];
+  
+  // 检查工具是否在当前工具集中
+  isToolAvailable(toolName: string, toolset: ToolsetType): boolean;
+}
+
+type ToolsetType = 'full' | 'core' | 'ui' | 'workflow';
+```
+
+**工具集定义：**
+
+```typescript
+const TOOLSET_DEFINITIONS = {
+  // 核心工具集（15个）- 日常高频使用
+  core: [
+    'interview',
+    'ask_user',
+    'init_project_context',
+    'analyze_project',
+    'code_review',
+    'security_scan',
+    'perf',
+    'debug',
+    'fix',
+    'gentest',
+    'genapi',
+    'genpr',
+    'gencommit',      // 必须包含
+    'estimate',
+    'start_bugfix',   // 至少一个编排入口
+  ],
+  
+  // UI/UX 工具集（6个）- 基于 ui-ux-pro-max-skill + json-render
+  ui: [
+    'start_ui',           // ⭐ 统一入口（推荐）
+    'ui_search',          // BM25 搜索（基于 ui-ux-pro-max-skill）
+    'ui_design_system',   // 设计系统生成（基于 ui-ux-pro-max-skill）
+    'design2code',        // 设计稿转代码
+    'genui',              // 通用 UI 生成
+    'sync_ui_data',       // 数据同步
+    // 注意：init_component_catalog 和 render_ui 作为 start_ui 的内部步骤
+    // 不在 ui toolset 暴露，但在 full 模式下仍可用
+  ],
+  
+  // 工作流工具集（25-30个）- 推荐给 AI 代理
+  workflow: [
+    // P0 编排入口
+    'start_feature',
+    'start_onboard',
+    'start_bugfix',
+    'start_ui',
+    'start_ralph',
+    
+    // 其他编排工具
+    'start_review',
+    'start_release',
+    'start_refactor',
+    'start_api',
+    'start_doc',
+    
+    // 关键依赖基础工具（最小闭环）
+    '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',
+  ],
+  
+  // 完整工具集（49个）- 默认，向后兼容
+  full: 'all', // 特殊标记，表示所有工具
+};
+```
+
+**UI 工具简化说明**：
+- v1.15 有 9 个 UI 工具，用户经常困惑该用哪个
+- v2.0 在 `ui` toolset 中只暴露 6 个对外工具
+- `init_component_catalog` 和 `render_ui` 作为 `start_ui` 的内部步骤隐藏
+- 推荐用户使用 `start_ui` 作为统一入口
+- 详见：[UI 工具简化策略](./ui-tools-strategy.md)
+
+### 2. 统一输出封装（Response Helpers）
+
+**职责：** 确保所有工具输出同时包含人类可读文本和机器可读结构
+
+**实现：**
+
+```typescript
+// src/lib/response.ts
+
+/**
+ * 返回纯文本响应（向后兼容）
+ */
+export function okText(text: string, meta?: Record<string, any>) {
+  return {
+    content: [{ type: "text", text }],
+    _meta: meta,
+  };
+}
+
+/**
+ * 返回结构化响应（新版）
+ * @param schema - JSON Schema 定义
+ * @param data - 符合 schema 的数据
+ * @param textFallback - 人类可读的文本（必填，用于旧客户端）
+ */
+export function okStructured<T>({
+  schema,
+  data,
+  textFallback,
+  meta,
+}: {
+  schema: object;
+  data: T;
+  textFallback: string;
+  meta?: Record<string, any>;
+}) {
+  return {
+    content: [{ type: "text", text: textFallback }],
+    structuredContent: data,
+    _meta: {
+      ...meta,
+      schema,
+    },
+  };
+}
+
+/**
+ * 返回错误响应
+ */
+export function errorResponse(message: string, details?: any) {
+  return {
+    content: [{ type: "text", text: `❌ 错误: ${message}` }],
+    isError: true,
+    _meta: { error: details },
+  };
+}
+```
+
+### 3. Schema 定义（Schemas）
+
+**职责：** 定义核心数据结构的 JSON Schema
+
+#### 3.1 WorkflowReport Schema
+
+```typescript
+// src/schemas/workflow-report.ts
+
+export const WorkflowReportSchema = {
+  type: "object",
+  properties: {
+    workflowName: {
+      type: "string",
+      description: "工作流名称（如 start_bugfix）",
+    },
+    summary: {
+      type: "string",
+      description: "一句话总结",
+    },
+    steps: {
+      type: "array",
+      description: "执行步骤",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          status: { 
+            type: "string", 
+            enum: ["pending", "running", "completed", "failed", "skipped"] 
+          },
+          input: { type: "object" },
+          outputs: { type: "array" },
+          notes: { type: "string" },
+          duration: { type: "number" },
+        },
+        required: ["name", "status"],
+      },
+    },
+    artifacts: {
+      type: "array",
+      description: "产出物",
+      items: {
+        type: "object",
+        properties: {
+          type: { 
+            type: "string",
+            enum: ["file", "code", "config", "doc", "test"] 
+          },
+          path: { type: "string" },
+          description: { type: "string" },
+          contentPreview: { type: "string" },
+        },
+        required: ["type", "path", "description"],
+      },
+    },
+    risks: {
+      type: "array",
+      description: "风险点",
+      items: {
+        type: "object",
+        properties: {
+          level: { type: "string", enum: ["low", "medium", "high"] },
+          description: { type: "string" },
+          mitigation: { type: "string" },
+        },
+      },
+    },
+    assumptions: {
+      type: "array",
+      description: "假设条件",
+      items: { type: "string" },
+    },
+    nextActions: {
+      type: "array",
+      description: "下一步建议",
+      items: {
+        type: "object",
+        properties: {
+          priority: { type: "number" },
+          action: { type: "string" },
+          reason: { type: "string" },
+        },
+        required: ["priority", "action"],
+      },
+    },
+    timestamps: {
+      type: "object",
+      properties: {
+        started: { type: "string", format: "date-time" },
+        completed: { type: "string", format: "date-time" },
+      },
+    },
+  },
+  required: ["workflowName", "summary", "steps", "nextActions"],
+};
+
+export interface WorkflowReport {
+  workflowName: string;
+  summary: string;
+  steps: WorkflowStep[];
+  artifacts?: Artifact[];
+  risks?: Risk[];
+  assumptions?: string[];
+  nextActions: NextAction[];
+  timestamps?: {
+    started: string;
+    completed?: string;
+  };
+}
+```
+
+#### 3.2 CommitMessage Schema
+
+```typescript
+// src/schemas/commit-message.ts
+
+export const CommitMessageSchema = {
+  type: "object",
+  properties: {
+    type: {
+      type: "string",
+      enum: ["feat", "fix", "docs", "style", "refactor", "test", "chore", "perf", "build", "ci", "revert"],
+      description: "提交类型",
+    },
+    scope: {
+      type: "string",
+      description: "影响范围（可选）",
+    },
+    subject: {
+      type: "string",
+      description: "简短描述",
+    },
+    body: {
+      type: "string",
+      description: "详细描述（可选）",
+    },
+    breaking: {
+      type: "boolean",
+      description: "是否包含破坏性更改",
+    },
+    footers: {
+      type: "array",
+      description: "页脚信息（如 Closes #123）",
+      items: { type: "string" },
+    },
+    finalMessage: {
+      type: "string",
+      description: "完整的提交消息（可直接复制）",
+    },
+  },
+  required: ["type", "subject", "finalMessage"],
+};
+
+export interface CommitMessage {
+  type: string;
+  scope?: string;
+  subject: string;
+  body?: string;
+  breaking: boolean;
+  footers?: string[];
+  finalMessage: string;
+}
+```
+
+### 4. Tasks 管理器（Tasks Manager）
+
+**职责：** 管理长时运行任务的生命周期
+
+**实现：**
+
+```typescript
+// src/lib/tasks-manager.ts
+
+interface Task {
+  taskId: string;
+  status: 'queued' | 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+  statusMessage?: string;
+  createdAt: string;
+  lastUpdatedAt: string;
+  ttl?: number;
+  pollInterval?: number;
+  result?: any;
+  error?: any;
+}
+
+export class TasksManager {
+  private tasks: Map<string, Task> = new Map();
+  
+  /**
+   * 创建新任务
+   */
+  createTask(ttl?: number): Task {
+    const taskId = crypto.randomUUID();
+    const task: Task = {
+      taskId,
+      status: 'queued',
+      createdAt: new Date().toISOString(),
+      lastUpdatedAt: new Date().toISOString(),
+      ttl,
+      pollInterval: 5000, // 5秒
+    };
+    
+    this.tasks.set(taskId, task);
+    return task;
+  }
+  
+  /**
+   * 更新任务状态
+   */
+  updateTask(taskId: string, updates: Partial<Task>): Task | null {
+    const task = this.tasks.get(taskId);
+    if (!task) return null;
+    
+    Object.assign(task, updates, {
+      lastUpdatedAt: new Date().toISOString(),
+    });
+    
+    return task;
+  }
+  
+  /**
+   * 获取任务
+   */
+  getTask(taskId: string): Task | null {
+    return this.tasks.get(taskId) || null;
+  }
+  
+  /**
+   * 取消任务
+   */
+  cancelTask(taskId: string): boolean {
+    const task = this.tasks.get(taskId);
+    if (!task || task.status === 'completed' || task.status === 'failed') {
+      return false;
+    }
+    
+    task.status = 'cancelled';
+    task.lastUpdatedAt = new Date().toISOString();
+    return true;
+  }
+  
+  /**
+   * 清理过期任务
+   */
+  cleanupExpiredTasks(): void {
+    const now = Date.now();
+    for (const [taskId, task] of this.tasks.entries()) {
+      if (task.ttl) {
+        const createdTime = new Date(task.createdAt).getTime();
+        if (now - createdTime > task.ttl) {
+          this.tasks.delete(taskId);
+        }
+      }
+    }
+  }
+}
+```
+
+### 5. Elicitation 处理器（Elicitation Handler）
+
+**职责：** 处理表单式提问和 URL 引导
+
+**实现：**
+
+```typescript
+// src/lib/elicitation-handler.ts
+
+interface ElicitationRequest {
+  mode: 'form' | 'url';
+  message: string;
+  requestedSchema?: object; // form 模式
+  url?: string;             // url 模式
+  elicitationId?: string;   // url 模式
+}
+
+export class ElicitationHandler {
+  /**
+   * 创建表单式提问
+   */
+  createFormElicitation(message: string, schema: object) {
+    return {
+      mode: 'form',
+      message,
+      requestedSchema: schema,
+    };
+  }
+  
+  /**
+   * 创建 URL 引导
+   */
+  createUrlElicitation(message: string, url: string, elicitationId: string) {
+    return {
+      mode: 'url',
+      message,
+      url,
+      elicitationId,
+    };
+  }
+  
+  /**
+   * 检测客户端是否支持 Elicitation
+   */
+  isSupported(capabilities: any): boolean {
+    return capabilities?.elicitation === true;
+  }
+  
+  /**
+   * 回退到文本提问
+   */
+  fallbackToText(message: string, options?: string[]): string {
+    let text = `❓ ${message}\n\n`;
+    
+    if (options && options.length > 0) {
+      text += '可选项：\n';
+      options.forEach((opt, i) => {
+        text += `${i + 1}. ${opt}\n`;
+      });
+    }
+    
+    text += '\n请回答：';
+    return text;
+  }
+}
+```
+
+## 🔄 工具迁移策略
+
+### P0 工具迁移优先级
+
+1. **gencommit** - 最高优先级，必须保留且增强
+2. **start_bugfix** - 高频使用，需要 Tasks 支持
+3. **start_feature** - 高频使用，需要 Tasks 支持
+4. **start_ui** - UI 工作流核心，统一入口
+5. **start_onboard** - 新用户入口
+6. **start_ralph** - 循环开发核心
+
+### UI 工具特殊说明
+
+**start_ui 的角色变化**：
+- v1.15：9 个 UI 工具之一
+- v2.0：UI 工具集的统一入口（推荐）
+
+**内部工具处理**：
+- `init_component_catalog` 和 `render_ui` 不在 `ui` toolset 暴露
+- 但 `start_ui` 内部仍可调用它们
+- 在 `full` 模式下用户仍可直接访问
+
+**迁移影响**：
+- 使用 `full` 模式（默认）：无影响
+- 使用 `ui` 模式：推荐改用 `start_ui`
+
+### 迁移步骤（以 gencommit 为例）
+
+**Before（当前）：**
+```typescript
+export async function gencommit(args: any) {
+  const message = `生成的提交消息...`;
+  return {
+    content: [{ type: "text", text: message }],
+  };
+}
+```
+
+**After（v2.0）：**
+```typescript
+import { okStructured } from '../lib/response.js';
+import { CommitMessageSchema } from '../schemas/commit-message.js';
+
+export async function gencommit(args: any) {
+  // 1. 分析变更
+  const analysis = analyzeChanges(args);
+  
+  // 2. 生成结构化数据
+  const commitData: CommitMessage = {
+    type: analysis.type,
+    scope: analysis.scope,
+    subject: analysis.subject,
+    body: analysis.body,
+    breaking: analysis.breaking,
+    footers: analysis.footers,
+    finalMessage: formatCommitMessage(analysis),
+  };
+  
+  // 3. 生成人类可读文本
+  const textFallback = `
+📝 生成的提交消息：
+
+${commitData.finalMessage}
+
+---
+类型: ${commitData.type}
+${commitData.scope ? `范围: ${commitData.scope}` : ''}
+${commitData.breaking ? '⚠️ 包含破坏性更改' : ''}
+  `.trim();
+  
+  // 4. 返回结构化响应
+  return okStructured({
+    schema: CommitMessageSchema,
+    data: commitData,
+    textFallback,
+  });
+}
+```
+
+## 🧪 测试策略
+
+### 1. 契约测试（Contract Tests）
+
+确保工具输出符合 schema：
+
+```typescript
+// tests/contracts/gencommit.test.ts
+
+import { describe, it, expect } from 'vitest';
+import { gencommit } from '../src/tools/gencommit.js';
+import { CommitMessageSchema } from '../src/schemas/commit-message.js';
+import Ajv from 'ajv';
+
+describe('gencommit 契约测试', () => {
+  const ajv = new Ajv();
+  const validate = ajv.compile(CommitMessageSchema);
+  
+  it('应该返回符合 schema 的结构化内容', async () => {
+    const result = await gencommit({ changes: 'test changes' });
+    
+    // 验证包含 content.text
+    expect(result.content).toBeDefined();
+    expect(result.content[0].text).toBeTruthy();
+    
+    // 验证 structuredContent 符合 schema
+    expect(result.structuredContent).toBeDefined();
+    const valid = validate(result.structuredContent);
+    expect(valid).toBe(true);
+  });
+  
+  it('应该包含 finalMessage 字段', async () => {
+    const result = await gencommit({ changes: 'test changes' });
+    expect(result.structuredContent.finalMessage).toBeTruthy();
+  });
+});
+```
+
+### 2. 集成测试（Integration Tests）
+
+测试工具集过滤：
+
+```typescript
+// tests/integration/toolset.test.ts
+
+describe('工具集过滤', () => {
+  it('core 工具集应该包含 gencommit', () => {
+    const tools = filterTools(allTools, 'core');
+    const hasGencommit = tools.some(t => t.name === 'gencommit');
+    expect(hasGencommit).toBe(true);
+  });
+  
+  it('workflow 工具集应该包含所有 P0 start_* 工具', () => {
+    const tools = filterTools(allTools, 'workflow');
+    const p0Tools = ['start_feature', 'start_bugfix', 'start_ui', 'start_onboard', 'start_ralph'];
+    
+    p0Tools.forEach(toolName => {
+      const hasTool = tools.some(t => t.name === toolName);
+      expect(hasTool).toBe(true);
+    });
+  });
+});
+```
+
+### 3. 兼容性测试（Compatibility Tests）
+
+确保向后兼容：
+
+```typescript
+// tests/compatibility/backward-compat.test.ts
+
+describe('向后兼容性', () => {
+  it('所有工具都应该返回 content.text', async () => {
+    for (const tool of allTools) {
+      const result = await tool.handler({});
+      expect(result.content).toBeDefined();
+      expect(result.content[0].text).toBeTruthy();
+    }
+  });
+  
+  it('full 模式应该包含所有 49 个工具', () => {
+    const tools = filterTools(allTools, 'full');
+    expect(tools.length).toBe(49);
+  });
+});
+```
+
+## 📊 性能考虑
+
+### 1. 工具列表缓存
+
+```typescript
+// 缓存过滤后的工具列表
+const toolsetCache = new Map<ToolsetType, Tool[]>();
+
+function getFilteredTools(toolset: ToolsetType): Tool[] {
+  if (toolsetCache.has(toolset)) {
+    return toolsetCache.get(toolset)!;
+  }
+  
+  const filtered = filterTools(allTools, toolset);
+  toolsetCache.set(toolset, filtered);
+  return filtered;
+}
+```
+
+### 2. Schema 验证优化
+
+```typescript
+// 预编译 schema 验证器
+const validators = new Map<string, ValidateFunction>();
+
+function getValidator(schemaName: string): ValidateFunction {
+  if (!validators.has(schemaName)) {
+    const schema = schemas[schemaName];
+    validators.set(schemaName, ajv.compile(schema));
+  }
+  return validators.get(schemaName)!;
+}
+```
+
+## 🔐 安全考虑
+
+### 1. 敏感信息处理
+
+- **不在表单中收集敏感信息**（token/密码/密钥）
+- 使用 URL 模式引导到安全页面
+- 在文档中明确标注安全最佳实践
+
+### 2. 输入验证
+
+```typescript
+// 验证用户输入
+function validateInput(input: any, schema: object): boolean {
+  const validate = ajv.compile(schema);
+  return validate(input);
+}
+```
+
+## 📝 配置管理
+
+### 环境变量
+
+```bash
+# 工具集选择
+MCP_TOOLSET=full|core|ui|workflow  # 默认: full
+
+# 调试模式
+MCP_DEBUG=1                         # 启用详细日志
+
+# 显示所有工具（调试用）
+MCP_SHOW_ALL=1                      # 忽略工具集过滤
+```
+
+### 配置文件示例
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "npx",
+      "args": ["mcp-probe-kit@2.0.0"],
+      "env": {
+        "MCP_TOOLSET": "workflow"
+      }
+    }
+  }
+}
+```
+
+**UI 工具集配置示例**：
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit-ui": {
+      "command": "npx",
+      "args": ["mcp-probe-kit@2.0.0"],
+      "env": {
+        "MCP_TOOLSET": "ui"
+      }
+    }
+  }
+}
+```
+
+**说明**：
+- `ui` 模式只显示 6 个 UI 工具
+- 推荐使用 `start_ui` 作为统一入口
+- 内部工具（`init_component_catalog`, `render_ui`）不可见
+- 如需访问内部工具，使用 `full` 模式（默认）
+
+## 🚀 部署策略
+
+### Beta 发布
+
+1. 发布 `mcp-probe-kit@2.0.0-beta.1`
+2. 在 README 中添加 beta 测试说明
+3. 收集用户反馈
+4. 修复问题并发布 beta.2, beta.3...
+
+### 稳定版发布
+
+1. 所有 P0 功能完成
+2. 通过所有测试
+3. 文档完整
+4. 至少 2 周 beta 测试期
+5. 发布 `mcp-probe-kit@2.0.0`
+
+## 📚 文档更新
+
+### 需要更新的文档
+
+1. **README.md** - 添加工具集配置说明
+2. **CHANGELOG.md** - 详细的变更日志
+3. **MIGRATION.md** - 从 v1.x 迁移指南
+4. **API.md** - 新的 API 文档
+5. **SCHEMAS.md** - Schema 定义文档
+6. **COMPATIBILITY.md** - 客户端兼容性矩阵
+
+## 🔄 回滚计划
+
+如果 v2.0 出现严重问题：
+
+1. 立即发布 v1.15.1（修复版本）
+2. 在 npm 上将 `latest` 标签指向 v1.15.1
+3. 在 README 中添加警告
+4. 修复 v2.0 问题后重新发布 v2.0.1