@maidang1/hataraku 0.0.3

package/docs/plan/mcp-2026-02-05.md

@@ -0,0 +1,700 @@
+# MCP 和 Skills 系统集成完善计划
+
+## 项目概述
+
+本计划旨在完善当前项目中的 MCP (Model Context Protocol) 实现，参考 OpenAI Codex 的 MCP 实现方式，增强连接管理、错误处理、性能优化和配置管理功能。
+
+**参考资料**：
+- [OpenAI Codex MCP 文档](https://developers.openai.com/codex/mcp/)
+- [Model Context Protocol GitHub](https://github.com/modelcontextprotocol)
+- [MCP 超时和重试最佳实践](https://octopus.com/blog/mcp-timeout-retry)
+
+## 当前状态分析
+
+### 已完成的功能
+
+✅ **MCP 基础实现**
+- 支持 Stdio 和 HTTP 两种传输方式
+- McpTool 类包装 MCP 工具
+- 基本的连接生命周期事件（start, success, error）
+- 三层配置优先级系统（local > project > user）
+- Agent 中已集成 MCP 工具加载
+
+✅ **Skills 系统**
+- 完整的分层协调器架构（Discovery, Parser, Validation, Cache）
+- 支持多作用域（Repo, User, System, Admin）
+- 事件驱动系统
+- 配置化设计
+- 与 MCP 的基础集成（Skills 可声明 MCP 依赖）
+
+### 需要改进的部分
+
+⚠️ **MCP 连接管理**
+- 连接失败只记录警告，没有重试机制
+- 缺少连接池和状态管理
+- 没有健康检查机制
+- 缺少优雅关闭和资源清理
+
+⚠️ **性能和缓存**
+- 没有 MCP 工具列表的缓存，每次初始化都要重新连接
+- 没有工具调用超时限制
+- 缺少启动超时配置
+
+⚠️ **Skills 依赖管理**
+- Skill 依赖处理是简化版本
+- 缺少重复检测和冲突解决机制
+- 没有依赖图构建和循环依赖检测
+
+⚠️ **配置管理**
+- 缺少工具过滤功能（enabledTools/disabledTools）
+- 缺少服务器启用/禁用开关
+- 缺少认证配置支持（bearer token, OAuth）
+- 缺少超时配置（startup_timeout_sec, tool_timeout_sec）
+
+## 实施计划
+
+### 阶段 1：MCP 连接管理增强（优先级：高）
+
+#### 目标
+实现健壮的 MCP 连接管理系统，包括连接池、重连策略、健康检查和优雅关闭。
+
+#### 关键文件
+
+**新增文件**：
+- `src/core/mcp/connection-manager.ts` - 连接池和生命周期管理
+- `src/core/mcp/retry-strategy.ts` - 重连策略（指数退避）
+- `src/core/mcp/health-checker.ts` - 健康检查机制
+- `src/core/mcp/tool-cache.ts` - MCP 工具缓存
+- `src/core/mcp/types.ts` - MCP 类型定义扩展
+- `src/core/mcp/transport.ts` - 传输层创建逻辑（从 index.ts 提取）
+
+**修改文件**：
+- `src/core/mcp/index.ts` - 重构以使用 ConnectionManager
+
+#### 实施细节
+
+**1.1 连接管理器 (ConnectionManager)**
+
+核心功能：
+- 管理多个 MCP 服务器连接的生命周期
+- 连接状态机：DISCONNECTED → CONNECTING → CONNECTED → RECONNECTING → FAILED
+- 自动重连机制（使用 RetryStrategy）
+- 事件发射：connectionStateChanged, connectionError, reconnectAttempt
+- 支持优雅关闭和资源清理
+
+关键接口：
+```typescript
+class ConnectionManager extends EventEmitter {
+  async connect(serverName: string, config: McpServerConfig, transport: Transport): Promise<Client>
+  async reconnect(serverName: string): Promise<void>
+  getConnection(serverName: string): ManagedConnection | undefined
+  getAllConnections(): ManagedConnection[]
+  async disconnect(serverName: string): Promise<void>
+  async disconnectAll(): Promise<void>
+}
+```
+
+**1.2 重连策略 (RetryStrategy)**
+
+核心功能：
+- 指数退避算法：delay = min(initialDelay * 2^attempt, maxDelay)
+- 添加抖动（jitter）避免雷鸣群效应
+- 可配置的最大重试次数（默认 3 次）
+- 智能错误分类（网络错误可重试，配置错误不可重试）
+
+配置参数：
+- `maxRetries`: 3（默认）
+- `initialDelay`: 1000ms（默认）
+- `maxDelay`: 30000ms（默认）
+- `jitterFactor`: 0.1（默认）
+
+**1.3 健康检查 (HealthChecker)**
+
+核心功能：
+- 定期检查 MCP 服务器健康状态（默认 60 秒间隔）
+- 使用 `client.listTools()` 作为健康检查探针
+- 记录延迟和错误信息
+- 触发 onUnhealthy 回调用于自动重连
+
+**1.4 工具缓存 (McpToolCache)**
+
+核心功能：
+- 缓存 MCP 服务器的工具列表
+- TTL 机制（默认 5 分钟）
+- 支持手动失效和自动过期清理
+- 减少重复的 listTools 调用
+
+**1.5 配置类型扩展**
+
+新增配置字段（参考 OpenAI Codex）：
+```typescript
+interface McpServerConfig {
+  // 现有字段
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+  url?: string
+  headers?: Record<string, string>
+
+  // 新增字段
+  enabled?: boolean                    // 是否启用（默认 true）
+  startupTimeoutSec?: number          // 启动超时（默认 30s）
+  toolTimeoutSec?: number             // 工具调用超时（默认 60s）
+  enabledTools?: string[]             // 工具白名单
+  disabledTools?: string[]            // 工具黑名单
+  maxRetries?: number                 // 最大重试次数（默认 3）
+  retryDelay?: number                 // 初始重试延迟（默认 1000ms）
+  healthCheckInterval?: number        // 健康检查间隔（默认 60000ms）
+
+  // 认证配置
+  auth?: {
+    type: "bearer" | "oauth" | "basic"
+    token?: string
+    username?: string
+    password?: string
+  }
+}
+```
+
+#### 验证方案
+
+1. **连接管理测试**
+   - 启动应用，验证 MCP 服务器正常连接
+   - 手动停止 MCP 服务器，验证自动重连
+   - 检查日志中的重连尝试和指数退避延迟
+
+2. **工具缓存测试**
+   - 首次加载记录时间
+   - 第二次加载应使用缓存（显著更快）
+   - 等待 TTL 过期后验证缓存失效
+
+3. **健康检查测试**
+   - 运行应用超过 60 秒
+   - 检查健康检查日志
+   - 模拟服务器故障，验证健康检查检测到问题
+
+4. **配置测试**
+   - 测试 `enabled: false` 禁用服务器
+   - 测试 `enabledTools` 白名单过滤
+   - 测试 `disabledTools` 黑名单过滤
+   - 测试超时配置
+
+---
+
+### 阶段 2：Skills 依赖管理增强（优先级：中）
+
+#### 目标
+完善 Skills 系统中 MCP 工具依赖的解析、冲突检测和加载管理。
+
+#### 关键文件
+
+**新增文件**：
+- `src/core/skills/dependency/resolver.ts` - 依赖解析器
+- `src/core/skills/dependency/conflict-detector.ts` - 冲突检测
+- `src/core/skills/dependency/graph.ts` - 依赖图构建
+- `src/core/skills/dependency/types.ts` - 依赖类型定义
+- `src/core/skills/integration/mcp-loader.ts` - MCP 依赖加载器
+- `src/core/skills/integration/tool-mapper.ts` - 工具映射
+- `src/core/skills/integration/lifecycle.ts` - 生命周期管理
+
+**修改文件**：
+- `src/core/agent/index.ts` - 使用新的依赖解析器
+
+#### 实施细节
+
+**2.1 依赖解析器 (DependencyResolver)**
+
+核心功能：
+- 解析 Skill 的 MCP 工具依赖
+- 构建依赖图检测循环依赖
+- 拓扑排序确定加载顺序
+- 版本冲突检测和解决策略
+
+关键接口：
+```typescript
+class DependencyResolver {
+  resolve(skills: SkillMetadata[]): ResolvedDependencies
+  detectConflicts(dependencies: ToolDependency[]): Conflict[]
+  buildDependencyGraph(skills: SkillMetadata[]): DependencyGraph
+}
+```
+
+**2.2 冲突检测 (ConflictDetector)**
+
+冲突类型：
+- **版本冲突**：同一 MCP 服务器的不同版本
+- **配置冲突**：同一服务器的不同配置（URL、命令等）
+- **工具名称冲突**：不同服务器提供相同名称的工具
+
+解决策略：
+- **优先级策略**：Repo > User > System > Admin
+- **最新版本策略**：选择最新版本
+- **用户选择策略**：提示用户选择（通过 AskUserQuestion）
+
+**2.3 MCP 依赖加载器 (McpDependencyLoader)**
+
+核心功能：
+- 从 Skills 依赖中提取 MCP 服务器配置
+- 合并到全局 MCP 配置中
+- 去重和冲突解决
+- 动态加载 MCP 工具
+
+当前实现位置：`src/core/agent/index.ts:127-145`（简化版本）
+
+改进点：
+- 添加重复检测
+- 添加冲突解决
+- 支持依赖版本约束
+- 支持可选依赖和必需依赖
+
+#### 验证方案
+
+1. **依赖解析测试**
+   - 创建多个 Skills，声明相同的 MCP 依赖
+   - 验证去重逻辑
+   - 验证依赖图构建
+
+2. **冲突检测测试**
+   - 创建两个 Skills，声明同一 MCP 服务器的不同配置
+   - 验证冲突检测和解决策略
+   - 检查日志中的冲突警告
+
+3. **循环依赖测试**
+   - 创建循环依赖的 Skills（如果支持 Skill 间依赖）
+   - 验证循环检测和错误报告
+
+---
+
+### 阶段 3：配置管理和工具过滤（优先级：中）
+
+#### 目标
+增强配置系统，支持工具过滤、认证配置和超时设置。
+
+#### 关键文件
+
+**修改文件**：
+- `src/core/config/index.ts` - 扩展配置 schema
+- `src/core/mcp/index.ts` - 实现工具过滤逻辑
+
+#### 实施细节
+
+**3.1 工具过滤**
+
+实现逻辑：
+```typescript
+function filterTools(
+  tools: McpToolDefinition[],
+  config: McpServerConfig
+): McpToolDefinition[] {
+  let filtered = tools;
+
+  // 白名单过滤
+  if (config.enabledTools && config.enabledTools.length > 0) {
+    filtered = filtered.filter(tool =>
+      config.enabledTools!.includes(tool.name)
+    );
+  }
+
+  // 黑名单过滤
+  if (config.disabledTools && config.disabledTools.length > 0) {
+    filtered = filtered.filter(tool =>
+      !config.disabledTools!.includes(tool.name)
+    );
+  }
+
+  return filtered;
+}
+```
+
+**3.2 超时配置**
+
+实现位置：
+- `startupTimeoutSec`：在 `client.connect()` 时使用 Promise.race 实现超时
+- `toolTimeoutSec`：在 `McpTool.execute()` 时使用 Promise.race 实现超时
+
+示例：
+```typescript
+async function connectWithTimeout(
+  client: Client,
+  transport: Transport,
+  timeoutSec: number = 30
+): Promise<void> {
+  const timeoutPromise = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error('Connection timeout')), timeoutSec * 1000)
+  );
+
+  await Promise.race([
+    client.connect(transport),
+    timeoutPromise
+  ]);
+}
+```
+
+**3.3 认证配置**
+
+支持的认证类型：
+- **Bearer Token**：在 HTTP headers 中添加 `Authorization: Bearer <token>`
+- **Basic Auth**：在 HTTP headers 中添加 `Authorization: Basic <base64>`
+- **OAuth**：实现 OAuth 2.0 客户端凭证流程
+
+实现位置：`src/core/mcp/transport.ts`
+
+#### 验证方案
+
+1. **工具过滤测试**
+   - 配置 `enabledTools: ["tool1", "tool2"]`
+   - 验证只有这两个工具被加载
+   - 配置 `disabledTools: ["tool3"]`
+   - 验证 tool3 被排除
+
+2. **超时测试**
+   - 配置 `startupTimeoutSec: 5`
+   - 使用一个慢启动的 MCP 服务器
+   - 验证 5 秒后超时并报错
+
+3. **认证测试**
+   - 配置 bearer token 认证
+   - 验证 HTTP 请求包含正确的 Authorization header
+   - 测试认证失败的错误处理
+
+---
+
+### 阶段 4：UI 和用户体验改进（优先级：低）
+
+#### 目标
+提供更好的用户反馈和配置管理界面。
+
+#### 关键文件
+
+**修改文件**：
+- `src/render/index.tsx` - 增强 MCP 状态显示
+
+#### 实施细节
+
+**4.1 增强 MCP 状态显示**
+
+当前实现：
+- ✅ 连接开始：`🔌 MCP 连接中: ${serverName}`
+- ✅ 连接成功：`✅ MCP 已连接: ${serverName} (tools: ${toolCount})`
+- ❌ 连接失败：`❌ MCP 连接失败: ${serverName}\n${error.message}`
+
+改进点：
+- 显示重连尝试：`🔄 MCP 重连中: ${serverName} (尝试 ${attempt}/${maxRetries})`
+- 显示健康检查状态：`💚 MCP 健康: ${serverName} (延迟: ${latency}ms)`
+- 显示工具过滤信息：`🔧 MCP 工具已过滤: ${serverName} (${filteredCount}/${totalCount})`
+- 显示缓存命中：`⚡ MCP 缓存命中: ${serverName}`
+
+**4.2 配置验证和错误提示**
+
+在加载配置时验证：
+- 检查必需字段（command 或 url）
+- 检查冲突配置（enabledTools 和 disabledTools 同时包含相同工具）
+- 检查超时值的合理性（不能为负数或过大）
+- 提供清晰的错误消息
+
+#### 验证方案
+
+1. **UI 测试**
+   - 启动应用，观察 MCP 连接状态消息
+   - 模拟连接失败，观察重连消息
+   - 观察健康检查状态更新
+
+2. **配置验证测试**
+   - 提供无效配置（缺少 command 和 url）
+   - 验证错误消息清晰易懂
+   - 提供冲突配置，验证警告消息
+
+---
+
+## 关键文件清单
+
+### 需要创建的文件（共 13 个）
+
+**MCP 连接管理（6 个）**：
+```
+src/core/mcp/connection-manager.ts
+src/core/mcp/retry-strategy.ts
+src/core/mcp/health-checker.ts
+src/core/mcp/tool-cache.ts
+src/core/mcp/types.ts
+src/core/mcp/transport.ts
+```
+
+**Skills 依赖管理（7 个）**：
+```
+src/core/skills/dependency/resolver.ts
+src/core/skills/dependency/conflict-detector.ts
+src/core/skills/dependency/graph.ts
+src/core/skills/dependency/types.ts
+src/core/skills/integration/mcp-loader.ts
+src/core/skills/integration/tool-mapper.ts
+src/core/skills/integration/lifecycle.ts
+```
+
+### 需要修改的文件（共 4 个）
+
+```
+src/core/mcp/index.ts              # 重构以使用 ConnectionManager
+src/core/config/index.ts           # 扩展配置 schema
+src/core/agent/index.ts            # 使用新的依赖解析器
+src/render/index.tsx               # 增强 MCP 状态显示
+```
+
+---
+
+## 技术细节
+
+### 重连策略：指数退避算法
+
+```
+尝试次数 | 延迟计算 | 实际延迟（含抖动）
+--------|---------|------------------
+0       | 1s      | 1.0s - 1.1s
+1       | 2s      | 2.0s - 2.2s
+2       | 4s      | 4.0s - 4.4s
+3       | 8s      | 8.0s - 8.8s
+4       | 16s     | 16.0s - 17.6s
+5       | 30s (max) | 30.0s - 33.0s
+```
+
+公式：`delay = min(initialDelay * 2^attempt, maxDelay) + jitter`
+
+### 缓存策略
+
+**MCP 工具列表缓存**：
+- TTL：5 分钟（可配置）
+- 失效条件：
+  - 超过 TTL
+  - 手动调用 `invalidate()`
+  - 连接断开后重连
+- 缓存键：服务器名称
+
+**Skills 加载结果缓存**：
+- 已在 `src/core/skills/cache/` 中实现
+- TTL：5 分钟（可配置）
+- 失效条件：
+  - 超过 TTL
+  - 手动调用 `forceReload`
+
+### 错误分类
+
+**可重试错误**：
+- `ECONNREFUSED` - 连接被拒绝
+- `ETIMEDOUT` - 连接超时
+- `ENOTFOUND` - 主机未找到
+- `socket hang up` - Socket 挂起
+
+**不可重试错误**：
+- 配置错误（缺少必需字段）
+- 认证错误（401, 403）
+- 协议错误（MCP 协议不兼容）
+
+### 工具超时实现
+
+```typescript
+async execute(input: any): Promise<string> {
+  const timeoutMs = this.config.toolTimeoutSec
+    ? this.config.toolTimeoutSec * 1000
+    : 60000;
+
+  const timeoutPromise = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error('Tool execution timeout')), timeoutMs)
+  );
+
+  const result = await Promise.race([
+    this.client.callTool({ name: this.toolName, arguments: input }),
+    timeoutPromise
+  ]);
+
+  return formatToolResult(result);
+}
+```
+
+---
+
+## 端到端验证方案
+
+### 测试场景 1：正常启动和工具调用
+
+1. 启动应用：`bun run src/index.ts`
+2. 验证 MCP 服务器连接成功
+3. 列出可用工具（应包含 MCP 工具）
+4. 调用一个 MCP 工具
+5. 验证工具执行成功
+
+### 测试场景 2：连接失败和自动重连
+
+1. 配置一个无效的 MCP 服务器（错误的 URL 或命令）
+2. 启动应用
+3. 观察连接失败和重连尝试
+4. 验证指数退避延迟
+5. 验证达到最大重试次数后停止
+
+### 测试场景 3：工具缓存
+
+1. 首次启动应用，记录 MCP 工具加载时间
+2. 不关闭应用，等待 1 分钟
+3. 触发工具列表刷新（如果有此功能）
+4. 验证使用缓存（加载时间显著减少）
+5. 等待 5 分钟（TTL 过期）
+6. 再次刷新，验证缓存失效并重新加载
+
+### 测试场景 4：Skills 依赖加载
+
+1. 创建一个 Skill，声明 MCP 工具依赖
+2. 启动应用
+3. 验证 MCP 服务器被自动加载
+4. 验证 Skill 可以使用依赖的工具
+5. 创建第二个 Skill，声明相同的 MCP 依赖
+6. 验证去重逻辑（不会重复加载）
+
+### 测试场景 5：工具过滤
+
+1. 配置 MCP 服务器，设置 `enabledTools: ["tool1"]`
+2. 启动应用
+3. 验证只有 tool1 被加载
+4. 修改配置为 `disabledTools: ["tool2"]`
+5. 重启应用
+6. 验证 tool2 被排除
+
+### 测试场景 6：健康检查和自动恢复
+
+1. 启动应用，MCP 服务器正常连接
+2. 运行应用超过 60 秒
+3. 观察健康检查日志
+4. 手动停止 MCP 服务器进程
+5. 等待健康检查检测到故障
+6. 观察自动重连尝试
+7. 重新启动 MCP 服务器
+8. 验证连接恢复
+
+---
+
+## 向后兼容性
+
+### 保持现有接口不变
+
+**SkillsManager**：
+```typescript
+class SkillsManager {
+  constructor(codexHome: string)  // 保持不变
+  getSkillsForCwd(cwd: string, forceReload?: boolean): SkillLoadOutcome  // 保持不变
+  clearCache(): void  // 保持不变
+}
+```
+
+**loadMcpTools**：
+```typescript
+export async function loadMcpTools(
+  mcpServersOverride?: Record<string, McpServerConfig>,
+  hooks?: {
+    onServerConnectStart?: (serverName: string) => void;
+    onServerConnectSuccess?: (serverName: string, toolCount: number) => void;
+    onServerConnectError?: (serverName: string, error: Error) => void;
+  }
+): Promise<{
+  tools: Tool[];
+  cleanup: () => Promise<void>;
+  // 新增：返回 ConnectionManager 供高级用户使用
+  connectionManager?: ConnectionManager;
+}>
+```
+
+### 配置向后兼容
+
+所有新增的配置字段都是可选的，默认值保持现有行为：
+- `enabled`: 默认 `true`
+- `startupTimeoutSec`: 默认 `30`
+- `toolTimeoutSec`: 默认 `60`
+- `maxRetries`: 默认 `3`
+- `healthCheckInterval`: 默认 `60000`
+
+现有配置文件无需修改即可继续工作。
+
+---
+
+## 依赖检查
+
+### 需要的 npm 包
+
+当前已安装：
+- `@modelcontextprotocol/sdk`: ^1.17.5 ✅
+- `@anthropic-ai/sdk`: ^0.72.1 ✅
+- `zod`: 需要检查是否已安装
+
+检查命令：
+```bash
+bun pm ls zod
+```
+
+如果未安装，需要添加：
+```bash
+bun add zod
+```
+
+---
+
+## 实施优先级建议
+
+### 高优先级（立即实施）
+1. **阶段 1：MCP 连接管理增强**
+   - 最大的改进点
+   - 解决当前最严重的问题（无重连、无缓存）
+   - 为后续阶段奠定基础
+
+### 中优先级（后续实施）
+2. **阶段 2：Skills 依赖管理增强**
+   - 改进用户体验
+   - 避免依赖冲突问题
+
+3. **阶段 3：配置管理和工具过滤**
+   - 增加灵活性
+   - 参考 OpenAI Codex 的功能
+
+### 低优先级（可选）
+4. **阶段 4：UI 和用户体验改进**
+   - 锦上添花
+   - 不影响核心功能
+
+---
+
+## 预期成果
+
+完成本计划后，项目将具备：
+
+✅ **健壮的连接管理**
+- 自动重连机制，提高可靠性
+- 健康检查，及时发现问题
+- 优雅关闭，避免资源泄漏
+
+✅ **优秀的性能**
+- 工具列表缓存，减少重复加载
+- 可配置的超时，避免长时间等待
+- 高效的依赖解析
+
+✅ **灵活的配置**
+- 工具过滤，按需加载
+- 认证支持，连接私有服务
+- 细粒度控制，满足各种场景
+
+✅ **完善的 Skills 集成**
+- 自动加载 MCP 依赖
+- 冲突检测和解决
+- 依赖图可视化
+
+✅ **良好的用户体验**
+- 清晰的状态反馈
+- 详细的错误消息
+- 完整的文档
+
+---
+
+## 参考资料
+
+- [OpenAI Codex MCP 文档](https://developers.openai.com/codex/mcp/)
+- [Model Context Protocol GitHub](https://github.com/modelcontextprotocol)
+- [MCP SDK 文档](https://github.com/modelcontextprotocol/sdk)
+- [指数退避最佳实践](https://betterstack.com/community/guides/monitoring/exponential-backoff/)
+- [AWS 重试模式](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/retry-backoff.html)
+- [MCP 超时和重试](https://octopus.com/blog/mcp-timeout-retry)