# OpenClaude 0.11.0 源码全貌参考 > **本文档定位**：OpenClaude（[Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)，约 26k stars）是 Claude Code 的开源 fork，把单一 Anthropic 客户端改造成 **200+ provider 通用 coding agent**。本文是从源码出发的逐目录架构解构，可作为对照官方 Claude Code 内核的 "对位实现"。 > > **报告生成方式**：从 `https://github.com/Gitlawb/openclaude` clone 最新 main（v0.11.0，2026-05-14 release），共 2451 个 .ts/.tsx/.py/.js 源文件、38 个 src/ 子目录、49 个内置工具。5 个并行 Explore agent 分工扫描后合成本文。 > > **使用方式**：自研 agent 设计时遇到具体子系统（多 provider 路由 / IDE 桥接 / TUI 渲染 / skills 注入）时，回查对应章节。也可作为 Claude Code 2.1.88 内核 ([`claude-code-reference.md`](./claude-code-reference.md)) 的 **多 provider 对照实现**——OpenClaude 在保留 Claude Code 内核（main.tsx / query / Tool / hooks / skills / bridge / coordinator）的同时，新增了 `integrations/`、`grpc/`、`proto/`、`outputStyles/`、`vim/`、独立 `web/`、`vscode-extension/`、`python/` 这 8 块。 --- ## 顶层架构总览 > 一图读 OpenClaude 0.11.0 全貌。从下往上：底层多 provider → 内核引擎 → 扩展能力 → 用户接口；从左往右：CLI/IDE → Web → 移动端。 ``` ╔══════════════════════════════════════════════════════════════════════════════════════════════╗ ║ 用户接入层（Surface） ║ ║ ┌──────────────┐ ┌─────────────────┐ ┌────────────┐ ┌───────────────┐ ┌──────────────┐ ║ ║ │ CLI (Ink TUI)│ │ VSCode Ext │ │ Web UI │ │ gRPC Client │ │ Python SDK │ ║ ║ │ openclaude │ │ vscode-ext/ │ │ web/ │ │ grpc-cli │ │ python/ │ ║ ║ └──────┬───────┘ └────────┬────────┘ └─────┬──────┘ └───────┬───────┘ └──────┬───────┘ ║ ╚═════════│═════════════════════│════════════════│═════════════════│══════════════════│═════════╝ │ │ │ │ │ │ │ HTTP poll │ WS / fetch │ gRPC │ subprocess │ ▼ ▼ ▼ ▼ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ 接口接入层 bridge/ remote/ server/ grpc/+proto/ │ │ │ 统一收敛到 entrypoints/{cli,sdk,mcp} │ │ └────────────────────────┬─────────────────────────────────────────┘ │ │ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │ 内核引擎 Kernel │ │ main.tsx (REPL React) → query.ts / QueryEngine.ts → Tool.ts / tools/ (49 工具) │ │ ├─ coordinator/ (多 agent 协调，fork+resume) │ │ ├─ tasks/ (后台任务框架) │ │ ├─ assistant/ (会话历史) │ │ ├─ buddy/ (AI 伴侣 / 旁观者) │ │ └─ hooks/ (90+ 文件钩子系统：每个生命周期都可插) │ └─────────────────────────────────────────┬───────────────────────────────────────────────────┘ │ ┌──────────────────────────────────┼──────────────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────────┐ ┌─────────────────┐ ┌───────────────────┐ │ 扩展能力 │ │ 渲染与交互 │ │ 配置与状态 │ │ skills/ plugins/│ │ ink/ components/│ │ memdir/ migrations│ │ commands/ │ │ screens/ │ │ state/ context/ │ │ outputStyles/ │ │ keybindings/ vim/│ │ schemas/ types/ │ │ voice/ moreright│ │ │ │ constants/ │ └──────────────────┘ └─────────────────┘ └───────────────────┘ │ ▼ ╔══════════════════════════════════════════════════════════════════════════════════════════════╗ ║ 多 Provider 路由层 integrations/ upstreamproxy/ (★ OpenClaude 核心差异化) ║ ║ ║ ║ Profile (用户配置) ║ ║ ▼ ║ ║ ProfileResolver → Registry (vendors × gateways) → RouteMetadata → Compatibility ║ ║ ▼ ║ ║ Vendor Descriptor (define.ts) + Gateway Adapter ║ ║ ▼ ║ ║ Upstream Proxy (转译 OpenAI ↔ Anthropic / Gemini / 本地协议) ║ ║ ▼ ║ ║ ┌─────────┬──────────┬─────────┬────────┬────────┬────────┬──────────┬───────┬──────────┐ ║ ║ │ Anthr. │ OpenAI │ Google │ DeepS. │ Groq │ Mistral│ Together │ NIM │ Ollama │ ║ ║ │ + 11 家 │ + 18 网关 (OpenRouter / Together / NIM / Venice / MiMo …) + 200+ 模型 │ ║ ║ └─────────┴──────────┴─────────┴────────┴────────┴────────┴──────────┴───────┴──────────┘ ║ ╚══════════════════════════════════════════════════════════════════════════════════════════════╝ ``` --- ## 目录 - **[Part I — 内核与工具层](#part-i--内核与工具层)**：main.tsx / query / Tool / 49 内置工具 / coordinator / tasks / assistant / buddy - **[Part II — 多 Provider 路由系统](#part-ii--多-provider-路由系统-openclaude-核心差异化)** ★：integrations / upstreamproxy / provider scripts - **[Part III — UI 与命令层](#part-iii--ui-与命令层)**：commands / keybindings / ink / components / screens / outputStyles / vim / voice - **[Part IV — 扩展性与接口层](#part-iv--扩展性与接口层)**：skills / plugins / hooks / bridge / remote / server / grpc / web / vscode-extension / python - **[Part V — 基础设施与杂项层](#part-v--基础设施与杂项层)**：cli / entrypoints / bootstrap / state / memdir / schemas / types / constants / migrations / services / utils / 启动脚本 / Android - **[附录 A — 与 Claude Code 2.1.88 的差异点汇总](#附录-a--与-claude-code-2188-的差异点汇总)** - **[附录 B — 自研 Agent 内核可借鉴清单](#附录-b--自研-agent-内核可借鉴清单)** --- # Part I — 内核与工具层 ## 架构流动图 ``` ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ main.tsx (React 根组件) │ │ │ │ [4677 行] — 启动、CLI 解析、REPL 初始化 │ │ │ └────────────────────────┬────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ replLauncher.tsx → ink.ts (终端 UI) │ │ │ │ 渲染消息流、用户输入、工具调用界面 │ │ │ └────────────────────────┬────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ query() —— query.ts [1914 行] │ │ │ │ 用户输入 → 消息准备 → API 调用 → 工具执行循环 │ │ │ │ - 消息构建（用户 / 系统 / 上下文） │ │ │ │ - token 预算跟踪 │ │ │ │ - 自动 compact 触发 │ │ │ │ - 权限检查集成 │ │ │ └────────────────────────┬────────────────────────────────────┘ │ │ │ │ │ ┌────────────┼────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ │ │ query.ts │ │ QueryEngine.ts │ │ 权限系统 │ │ │ │ 消息流机制 │ │ SDK 模式集成 │ │ Tool.ts / 检验 │ │ │ │ (1914 行) │ │ (1430 行) │ │ Permission API │ │ │ └────────────────┘ └─────────────────┘ └──────────────────┘ │ │ │ │ │ ┌────────────┴────────────┐ │ │ ▼ ▼ │ │ ┌───────────────────────┐ ┌─────────────────────────────────┐ │ │ │ API 调用 │ │ Tool 执行引擎 │ │ │ │ /messages │ │ StreamingToolExecutor │ │ │ │ (claude API) │ │ (runTools via │ │ │ │ │ │ toolOrchestration) │ │ │ └───────────────────────┘ └────────────────────────────────┘ │ │ │ │ │ │ └────────────┬────────────┘ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ tools.ts —— 工具池 [386 行] │ │ │ │ getTools() │ │ │ │ - 49 个内置工具（BashTool, FileEditTool, ..., Skill...） │ │ │ │ - MCP 工具集成 (ListMcpResourcesTool, ...) │ │ │ │ - 权限过滤 (filterToolsByDenyRules) │ │ │ │ - 工具池组装 (assembleToolPool) │ │ │ └────────────────────────┬────────────────────────────────────┘ │ │ │ │ │ ┌────────────┴────────────┐ │ │ ▼ ▼ │ │ ┌─────────────────────────┐ ┌────────────────────────────────┐ │ │ │ src/tools/ [49 文件] │ │ MCP 工具 (MCP 服务器) │ │ │ │ │ │ ListMcpResourcesTool │ │ │ │ 核心类： │ │ ReadMcpResourceTool │ │ │ │ - AgentTool │ │ MCPTool │ │ │ │ - BashTool │ │ │ │ │ │ - FileRead/Edit/Write │ └────────────────────────────────┘ │ │ │ - WebSearch/WebFetch │ │ │ │ - TaskCreate/Update │ │ │ │ - SkillTool │ │ │ └─────────────────────────┘ │ │ │ │ │ ┌────────────┴────────────┐ │ │ ▼ ▼ │ │ ┌──────────────────────────────┐ ┌────────────────────────────┐ │ │ │ 工具执行结果 │ │ coordinator/ [387 行] │ │ │ │ - 返回到 query 循环 │ │ 多 Agent 协调 │ │ │ │ - 下一回合准备 │ │ - Worker 生成 (AgentTool) │ │ │ │ - 历史持久化 │ │ - 工具权限分配 │ │ │ └──────────────────────────────┘ │ - 消息路由 │ │ │ └────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` --- ## 一、main.tsx —— React REPL 主组件与状态机 **职责** - 启动入口：CLI 参数解析，配置加载，认证初始化 - React 应用根：useState 管理全局状态，消息队列，UI 事件监听 - 生命周期：工具链接，历史恢复，信号处理，graceful shutdown - 性能监测：启动时间探针，首次 API 调用延迟追踪，成本统计 **关键文件与 LOC** - `src/main.tsx` (4677 行) — 最大的单一文件，包含 React 组件定义、事件处理器、副作用 hooks - `src/replLauncher.tsx` (22 行) — 轻量级启动器，调用 main 中的 `launchRepl()` - `src/ink.ts` (85 行) — ink 库初始化与配置 - `src/interactiveHelpers.tsx` (375 行) — 对话式 UI 辅助（对话框、屏幕、错误展示） **核心数据结构** ```typescript // main.tsx 中的全局状态树（React Context via AppState） type AppState = { messages: Message[] // 对话历史 activeMessageId?: string // 当前选中消息（恢复/编辑） mcp: { tools: Tool[], ... } // MCP 服务器与工具列表 stats: StatsStore // cost / token / API duration 追踪 flags: { // 命令行标志缓存 verbose: boolean debug: boolean model?: string ... } } // 消息流类型（从 types/message.ts） type Message = | UserMessage // 用户输入 + 粘贴内容 | AssistantMessage // Claude 响应 + 工具调用块 | AttachmentMessage // 文件变更、MCP 资源、记忆体 | ProgressMessage // 工具执行进度 | SystemLocalCommandMessage // Bash/本地命令输出 ``` **调用链** 1. `main()` CLI 启动 → `launchRepl()` → React render loop 2. 用户输入 event → `useQueueProcessor()` hook 拦截 → 入队消息 3. `processSlashCommand()` 处理 `/help`, `/config` 等（本地，无 query） 4. 普通提示 → 入队到消息队列 → `query()` 调用（异步） 5. `query()` 返回工具块流 → 执行工具 → 结果作为新消息 append 6. React state 更新 → 屏幕重绘 → 用户看到工具进度与结果 **可借鉴点** - **React 并发友好**：消息队列与 async generator 配合避免阻塞渲染 - **性能优化**：启动时在后台并行化（MDM 读、Keychain 预取、MCP 连接） - **权限与 hooks 整合**：useCanUseTool() 在 query 执行前检查，同时维护 denial tracking - **多模式支持**：SDK、print、REPL 通过功能开关（feature gates）同一代码库实现 --- ## 二、query.ts —— 查询主引擎 [1914 行] **职责** - 消息准备：构建用户 + 系统 + 上下文消息，应用 compaction - API 调用：调度 /messages, 处理流式响应，token budget 跟踪 - 工具循环：从 API 解析工具块，决定并发 vs 顺序执行 - 权限与 hooks：前置 hooks、工具权限检查、后置 hooks 执行 - 自动 compact：检测 token 警告状态，触发消息压缩 **关键文件与 LOC** - `src/query.ts` (1914 行) — 核心 async generator，yield 消息 / 工具进度 - `src/query/*.ts` — 模块化辅助 - `config.ts` — buildQueryConfig() - `deps.ts` — ProductionDeps（注入模式） - `tokenBudget.ts` — token 预算追踪 - `transitions.ts` — 终止条件（Terminal | Continue） - `stopHooks.ts` — 停止时 hooks **核心数据结构** ```typescript // query() 签名 async function* query( userMessage: string, toolUseContext: ToolUseContext, // Tools, commands, permission context querySource: 'repl_main_thread' | 'sdk' | ..., queryDeps?: QueryDeps, ): AsyncGenerator< StreamEvent | Message | ToolUseSummaryMessage, Terminal | Continue, // 最终返回值：停止 or 继续 undefined > // StreamEvent = API 流事件（streaming messages） // Message = 工具结果、附件等 // ToolUseSummaryMessage = 工具执行总结 ``` **调用链** 1. main.tsx / QueryEngine.ts 调用 `query(userMessage, context)` 2. 准备消息： - fetchSystemPromptParts() → 获取 system prompt - prependUserContext() + appendSystemContext() → 注入 git status、claudeMd - createAttachmentMessages() → 粘贴内容、文件变更、MCP 资源 - 内存 prefetch 消费 3. 检查 token 预算： - calculateTokenWarningState() 判断是否触发 auto-compact - 若是，buildPostCompactMessages() 压缩历史 4. 调用 API（via claude.ts）：`messages.create({ model, messages, tools, ... })` 5. 处理流响应（for await of response）： - 累积工具块 → parseToolUseBlocks() - 执行工具：runTools() 并发执行，捕获结果 - 生成工具摘要（optional）：generateToolUseSummary() - 检查结束原因（stop_reason）： - 'end_turn' → 返回 Terminal - 'tool_use' → 下一轮继续 - 'max_tokens' → 检查 budget，可能 continue 6. Yield 结果给 main.tsx → 显示在 UI **可借鉴点** - **迭代器复用**：AsyncGenerator 使多个"轮数"（工具调用循环）流畅表达 - **权限透明性**：Tool 检查 + 前置 hooks（auto-deny for background agents） = 无提示快速路径 - **Streaming 设计**：工具块到达时立即 yield，不等整个响应完成 → 低延迟 UI - **Compaction 集成**：token 预算在循环开始检查，无缝 compact 历史后继续 --- ## 三、QueryEngine.ts —— SDK 与多模式适配 [1430 行] **职责** - SDK 兼容性：规范化 SDK 消息格式（SDKMessage → Message），处理回放、compact 边界 - 多模式网关：REPL / print / SDK 统一入口，特定模式的定制处理 - 会话持久化：加载 / 保存会话，断点恢复（teleport, CCR） - 配置注入：model override、prompt override、permission mode 配置 **关键文件与 LOC** - `src/QueryEngine.ts` (1430 行) — 主类，synchronous wrapper around query.ts - 与 `query.ts` 的关系： - query.ts = 单次 turn 的 async generator - QueryEngine = 会话级别的循环包装器，管理历史与状态 **核心数据结构** ```typescript // SDK 消息映射 type SDKMessage = | { type: 'user', text: string, attachments?: ... } | { type: 'assistant', text: string, tool_use?: { id, name, input } } | { type: 'user_replay', ... } // 恢复时的重放块 // QueryEngine 初始化参数 interface QueryEngineInit { appState: AppState setAppState: (f: AppState => AppState) => void toolUseContext: ToolUseContext permissionContext: ToolPermissionContext modelUsageByModel: Map // cost tracking mcpClients: MCPServerConnection[] // ... 其他上下文 } // 会话状态（持久化到 ~/.claude/sessions/） type SessionSnapshot = { messages: Message[] stats: { cost, tokens, duration } sessionMode: 'normal' | 'coordinator' // SDK 新增 // ... metadata } ``` **调用链** 1. main.tsx 或 SDK entrypoint 创建 QueryEngine 实例 2. `engine.processUserMessage(input)` 入口 3. 规范化输入（若来自 SDK，反序列化 SDKMessage → Message） 4. 调用 `query(input, context)` generator，逐个 yield 处理 5. 会话持久化： - 消息 append 到 ~/.claude/sessions/SESSION_ID.json - cost / token 累积到 cost-tracker.ts - 在 shutdown 时 flush 6. 模式特定处理： - SDK：返回 SDKMessage[], 不显示 REPL UI - Print：纯文本输出，无交互 - REPL：完整 React UI，实时进度 **可借鉴点** - **分层抽象**：query() 处理单次循环逻辑，QueryEngine 处理会话状态 → 关注点分离 - **SDK 适配**：统一代码路径，通过模式开关处理输出格式差异 - **持久化简洁**：JSON 序列化 Message[]，加载时反序列化，无 ORM - **Cost 追踪**：模型使用量字典，支持多模型混用计费 --- ## 四、Tool.ts —— 工具注册与权限框架 [807 行] **职责** - 类型定义：Tool 接口、ToolInputJSONSchema、工具属性（name, description, inputSchema） - 权限模型：ToolPermissionContext（mode, rules 集合），getEmptyToolPermissionContext() - 工具查询：findToolByName(), toolMatchesName()（支持别名与模糊匹配） - 进度与通知：ToolProgressData 联合类型，MCP / Agent / Bash 等专用进度 **关键文件与 LOC** - `src/Tool.ts` (807 行) — 接口 + 权限类型定义 - 与 tools.ts 的关系： - Tool.ts = 接口定义 - tools.ts = 实现与工具池管理 **核心数据结构** ```typescript export type Tool = { name: string description: string inputSchema: ToolInputJSONSchema isEnabled?: () => boolean // Feature gate mcpInfo?: { serverName: string; toolName: string } execute( input: unknown, context: ToolUseContext, ): Promise> } export type ToolPermissionContext = DeepImmutable<{ mode: 'default' | 'bypass' | 'auto' | 'scripted' | 'ask' additionalWorkingDirectories: Map alwaysAllowRules: ToolPermissionRulesBySource // { 'tool_name': { ... } } alwaysDenyRules: ToolPermissionRulesBySource alwaysAskRules: ToolPermissionRulesBySource isBypassPermissionsModeAvailable: boolean awaitAutomatedChecksBeforeDialog?: boolean // Coordinator 用 prePlanMode?: PermissionMode // Plan mode 前的模式备份 }> export type ToolProgressData = | BashProgress // exit_code, stdout_preview, ... | AgentToolProgress // agent_id, output_summary, ... | WebSearchProgress // query, results_count, ... | MCPProgress // server_name, operation, ... | SkillToolProgress // skill_name, status, ... | REPLToolProgress | TaskOutputProgress ``` **调用链** 1. tools.ts 定义 Tool[] 数组 → Anthropic API 的 tools param 2. query() 中解析 API 响应的 tool_use 块 3. findToolByName() 查询工具定义 4. 权限检查（useCanUseTool hook）→ ToolPermissionContext 评估规则 5. tool.execute(input, context) → 异步执行 6. 结果转为 ToolResult → 构建 tool_result message **可借鉴点** - **权限模型清晰**：分离 allow / deny / ask 规则，支持模式级别与工具级别 - **异步 iterator 支持**：工具可流式返回结果 → 大输出不阻塞 - **MCP 集成点**：mcpInfo 字段标记远程工具，与内置工具无缝混合 --- ## 五、tools.ts —— 工具池管理 [386 行] **职责** - 工具注册：getAllBaseTools() 返回 49 个内置工具的完整列表 - 条件启用：feature gates、permission 过滤、mode 判断 - MCP 集成：assembleToolPool() 与 getMergedTools() 组合内置 + MCP 工具 - 工具搜索：isToolSearchEnabledOptimistic() 决定是否启用 Tool Search 工具 **关键文件与 LOC** - `src/tools.ts` (386 行) — 唯一的工具注册清单 **49 个内置工具分类** ### 1. **核心文件操作** (5) - **FileReadTool** — 读取文件内容 - **FileEditTool** — 编辑文本文件（行级别修改） - **FileWriteTool** — 创建或覆盖文件 - **GlobTool** — 文件搜索（glob 模式） - **GrepTool** — 正则搜索文件内容 ### 2. **执行与 Shell** (5) - **BashTool** — 执行 Bash 命令 - **PowerShellTool** — Windows PowerShell（条件启用） - **NotebookEditTool** — Jupyter notebook 编辑 - **LSPTool** — 语言服务器协议（code intelligence） - **REPLTool** — 内部虚拟机（--bare 模式） ### 3. **AI 与 Agent** (6) - **AgentTool** — 生成子 Agent / Worker（coordinator 核心） - **SkillTool** — 调用项目 skills（slash 命令包装） - **AskUserQuestionTool** — 向用户提问（交互式） - **BriefTool** — 生成执行摘要 - **SendMessageTool** — 向 Worker 发送消息（coordinator） - **TaskOutputTool** — 获取后台任务输出 ### 4. **Web 与网络** (4) - **WebSearchTool** — Web 搜索（Brave, Bing, DuckDuckGo 等） - **WebFetchTool** — 获取网页内容 - **ListMcpResourcesTool** — 列出 MCP 资源 - **ReadMcpResourceTool** — 读取 MCP 资源 ### 5. **任务与工作流** (8) - **TaskCreateTool** — 创建后台任务 - **TaskGetTool** — 获取任务详情 - **TaskUpdateTool** — 更新任务 - **TaskListTool** — 列出所有任务 - **TaskStopTool** — 停止任务（同时停止工作的 Agent） - **EnterPlanModeTool** — 进入计划模式 - **ExitPlanModeTool** — 退出计划模式 - **VerifyPlanExecutionTool** — 验证计划执行（条件） ### 6. **团队协作** (2) - **TeamCreateTool** — 创建 Agent 团队（agent swarms） - **TeamDeleteTool** — 删除团队 ### 7. **工作树与隔离** (2) - **EnterWorktreeTool** — 创建 git worktree 分支 - **ExitWorktreeTool** — 删除 worktree ### 8. **IDE 与编程工具** (3) - **TodoWriteTool** — 管理 todo 列表 - **ToolSearchTool** — 搜索可用工具（工具发现） - **MonitorTool** — 后台进程监控（流式输出） ### 9. **特殊与诊断** (8) - **SyntheticOutputTool** — 工具摘要与输出合成 - **ScheduleCronTool (3 个)** — Cron 计划 - CronCreateTool - CronDeleteTool - CronListTool - **RemoteTriggerTool** — 远程触发（条件） - **WorkflowTool** — 工作流脚本（条件） - **SleepTool** — 延迟（内部） - **MCPTool** — 通用 MCP 工具包装 ### 10. **实验与内部** (6) - **WebBrowserTool** — 浏览器自动化（实验） - **OverflowTestTool** — 超限测试（诊断） - **CtxInspectTool** — 上下文检查（实验） - **TerminalCaptureTool** — 终端捕获（实验） - **SnipTool** — 历史片段（实验） - **ListPeersTool** — 列出同行 agents（实验） **调用链** 1. `getTools(permissionContext)` → 返回可用工具列表 - 适用 feature gates（简单模式、REPL 模式等） - 过滤 deny 规则 → filterToolsByDenyRules() - 启用检查 → tool.isEnabled() 2. `assembleToolPool(context, mcpTools)` → 合并内置 + MCP 工具 - 按名称排序 → prompt cache 稳定 - uniqBy 去重（内置优先级更高） 3. tools 传入 API → Anthropic /messages 端点 4. 工具执行时 → findToolByName() 查询 Tool 定义，调用 execute() **可借鉴点** - **Feature Gate 灵活性**：同一代码库支持 10+ 个特性变体（COORDINATOR_MODE, KAIROS, WORKFLOW_SCRIPTS 等） - **MCP 透明集成**：内置 + MCP 工具无缝混合，按名称去重 - **启用检查分阶段**：getAllBaseTools() 返回全集（用于缓存），getTools() 应用过滤 --- ## 六、coordinator/ —— 多 Agent 协调系统 [387 行] **职责** - Coordinator 角色定义：master agent 指挥 worker agents 完成任务 - Worker 工具限制：定义 ASYNC_AGENT_ALLOWED_TOOLS，coordinator 可委派给 worker 的工具 - 系统提示注入：getCoordinatorSystemPrompt() 告知 coordinator 其角色 + 工具 - 用户上下文补充：getCoordinatorUserContext() 告知 worker 可用工具列表 **关键文件与 LOC** - `src/coordinator/coordinatorMode.ts` (369 行) — 核心配置与检查 - `src/coordinator/workerAgent.ts` (18 行) — Worker 类型（轻量级） **核心数据结构** ```typescript // Coordinator 模式检查 export function isCoordinatorMode(): boolean { return feature('COORDINATOR_MODE') && isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE) } // Worker 可用工具列表 const ASYNC_AGENT_ALLOWED_TOOLS = new Set([ 'bash', // 执行 'read', // 文件读 'edit', // 文件编辑 'write', // 文件写 'web_search', // 网络 'web_fetch', 'skill', // 项目 skills 'agent', // 可递归生成子 worker 'task_*', // 任务管理 // ... 约 25 个工具 ]) const INTERNAL_WORKER_TOOLS = new Set([ 'team_create', 'team_delete', 'send_message', 'synthetic_output', ]) // 不对 worker 公开，仅 coordinator 用 ``` **调用链** 1. main.tsx 启动时检查 COORDINATOR_MODE 环境变量 2. 若启用 → matchSessionMode() 检查会话是否一致 3. QueryEngine 调用 getCoordinatorUserContext() → 注入 Worker 工具列表到系统提示 4. API 返回 agent_tool 调用 → query.ts 检查 AgentTool 定义 5. AgentTool.execute() 创建子进程 agent： - 创建独立 AppState 副本 - 创建 subagent ToolUseContext（工具池已过滤为 ASYNC_AGENT_ALLOWED_TOOLS） - 调用 query() 递归，worker 在其范围内工作 - 结果作为 task-notification 消息返回到 coordinator 6. Coordinator 通过 SendMessageTool 继续 worker 工作 7. TaskStopTool 可停止任何 worker **Coordinator 系统提示示例** ``` 你是 Claude Code，一个多 agent 协调器。 - 你的角色：指挥 worker 完成任务，合成结果 - 你的工具： - Agent 工具：生成新 worker - SendMessage：向已有 worker 发送消息 - TaskStop：停止 worker - subscribe_pr_activity / unsubscribe_pr_activity：订阅 GitHub 事件 - Worker 能访问的工具：[Bash, Read, Edit, ..., Skill, Agent, TaskStop, ...] - Worker 也可访问 MCP 服务器：[server1, server2, ...] - Scratchpad 目录：/tmp/claude-code-scratchpad (跨 worker 共享知识) ``` **可借鉴点** - **权限分离清晰**：Coordinator ↔ Worker 工具集合有明确界限，避免 worker 滥用权限 - **Scratchpad 模式**：跨 worker 共享文件系统，用于交换中间结果与知识 - **消息驱动**：Worker 通过 task-notification 消息报告进度，Coordinator 订阅并反应 - **递归能力**：Agent 可生成子 Agent，形成树状 worker 池，支持复杂多层工作 --- ## 七、辅助子系统 ### **history.ts** (464 行) - **职责**：会话历史与粘贴内容管理 - **关键函数**： - addToHistory() — 添加用户提示到 ~/.claude/history - expandPastedTextRefs() — [Pasted text #1] 占位符替换 - formatPastedTextRef() / formatImageRef() — 格式化引用 - **接口**：HistoryEntry (id, timestamp, text), PastedContent (type, content/hash) ### **context.ts** (189 行) - **职责**：全局上下文注入（git 状态、claude.md、当前日期） - **关键函数**： - getSystemContext() — git branch / status / recent commits - getUserContext() — claude.md 文件发现、currentDate - **缓存**：memoize 装饰器，会话期间不重计算 ### **commands.ts** (781 行) - **职责**：斜线命令注册与路由 - **关键**： - 100+ 个命令定义（commit, review, config, help, login, ...） - processSlashCommand() 本地执行（无 query 调用） - getCommands() 返回可用命令列表 - **特性**：Skill 包装（/commit → SkillTool） ### **cost-tracker.ts** (379 行) - **职责**：模型成本与 token 使用统计 - **关键**：getModelUsage(), getTotalCost(), getTotalAPIDuration() - **支持**：多模型计费，cache 命中率统计 ### **Task.ts** (124 行) - **职责**：后台任务类型定义 - **关键**：Task interface，TaskResult, TaskProgressCallback ### **setup.ts** (438 行) - **职责**：启动向导与 onboarding - **关键**：showSetupScreens(), OAuth 认证，repo 选择 ### **dialogLaunchers.tsx** (132 行) - **职责**：交互式对话框启动 - **关键**：launchAssistantInstallWizard(), launchResumeChooser(), launchSnapshotUpdateDialog() ### **interactiveHelpers.tsx** (375 行) - **职责**：REPL 辅助 UI 函数 - **关键**：exitWithError(), getRenderContext(), renderAndRun() ### **costHook.ts** (22 行) - **职责**：React hook 包装，cost-tracker 订阅 ### **projectOnboardingState.ts** (47 行) - **职责**：项目 onboarding 状态管理 --- ## 八、messages.ts 中的关键工具函数 **消息构建** - createUserMessage() — 用户输入 + 粘贴内容 - createSystemMessage() — 系统提示 - createAssistantAPIErrorMessage() — API 错误处理 - createAttachmentMessage() — 文件变更、MCP 资源 - createToolUseSummaryMessage() — 工具执行摘总 **消息处理** - normalizeMessagesForAPI() — 验证 Anthropic API 格式 - getMessagesAfterCompactBoundary() — Compact 后的消息切片 - createUserInterruptionMessage() — 用户中断标记 --- ## 九、main.tsx React 状态机详解 **主要 useState 钩子** ```typescript const [messages, setMessages] = useState([]) // 对话历史 const [isWaitingForResponse, setIsWaitingForResponse] = useState(false) const [activeMessageId, setActiveMessageId] = useState() // 恢复编辑 const [searchQuery, setSearchQuery] = useState('') // 搜索历史 const [selectedToolName, setSelectedToolName] = useState() // 工具详情 // 性能与分析 const [costSummary, setCostSummary] = useState() const [startTime] = useState(Date.now()) // Coordinator 状态 const [agents, setAgents] = useState>() // 所有 worker const [selectedAgentId, setSelectedAgentId] = useState() ``` **事件处理流程** ``` 用户输入 (REPL) ↓ onInputChange() → setInput() → React 重绘 ↓ 用户按 Enter ↓ onSubmit() → 验证、queueCommand(input) ↓ useQueueProcessor() hook 拦截 → query(input) 异步调用 ↓ for await (const event of query(...)) { if (event.type === 'tool_use_block') { → 显示工具执行进度 UI → 执行工具、收集结果 → 作为 tool_result 继续 API 循环 } if (event.type === 'message') { → setMessages([...messages, event]) → 重绘历史区域 } } ↓ turn 完成 → setIsWaitingForResponse(false) ``` **副作用钩子（useEffect）** - 监听 messages 变化 → 保存历史、更新成本 - 监听 resume flag → 加载会话 - 监听 settings → 重新连接 MCP、刷新工具 - Signal handlers → SIGINT/SIGTERM → graceful shutdown --- ## 十、关键算法与模式 ### **1. 消息规范化与 Compaction** ``` 消息序列： [system, user_1, assistant_1, tool_result_1, user_2, assistant_2, ...] auto-compact 触发： → calculateTokenWarningState() 检查 budget → 若超 80% → buildPostCompactMessages() → 压缩中间消息为 "conversation summary + context" → 维持最后 N 条消息完整性 ``` ### **2. 工具执行并发策略** ``` 工具块集合：[tool_use_1, tool_use_2, tool_use_3] 检查是否可并发： → 工具依赖分析（BashTool 与 FileEditTool 有冲突 → 串行） → 若独立 → Promise.all() 并发 → StreamingToolExecutor 处理流式结果 结果收集： → 每个工具返回 ToolResult → 构建 tool_result messages → 返回到 API 继续循环 ``` ### **3. 权限检查两层** ``` 第 1 层：工具定义时 → Tool 注册时检查 isEnabled() → feature gates 第 2 层：工具执行前 → useCanUseTool(toolName, context) hook → 评估 ToolPermissionContext 规则 → 若拒绝 → createPermissionDenialMessage() → 若需要提示 → 显示权限对话框 ``` ### **4. MCP 工具无缝集成** ``` MCP 服务器连接： → main.tsx 启动时 getMcpToolsCommandsAndResources() → mcpTools 数组 += MCP 工具 工具池组装： → assembleToolPool(builtInTools, mcpTools) → 按名称去重（内置优先级更高） → 按名称排序 → prompt cache 稳定 执行： → mcpInfo 字段标记 MCP 工具 → MCPTool 包装器调用 MCP 服务器 ``` --- ## 十一、可借鉴的工程实践 | 实践 | 实现 | 价值 | |------|------|------| | **消息流异步** | AsyncGenerator query() | 低延迟 UI，流式工具结果 | | **权限模型** | ToolPermissionContext + 三层规则 | 细粒度控制，用户友好提示 | | **工具池动态** | feature gates + isEnabled() | 同一代码库支持 10+ 变体 | | **会话持久化** | JSON 序列化 + 增量保存 | 快速恢复，支持断点继续 | | **Cost 追踪** | Map + 实时累积 | 多模型计费透明 | | **Compaction 集成** | token budget + auto-compact | 无缝长对话支持 | | **MCP 集成** | 透明混合 + 名称去重 | 扩展性强，无闭包 | | **React 并发友好** | 消息队列 + useCallback 优化 | 不阻塞 UI 渲染 | | **Coordinator 模式** | 递归 agent + scratchpad | 复杂多步任务自动化 | | **错误处理** | Hook + Catch-all + 重试 | 网络波动自愈 | --- ## 十二、总结 OpenClaude 内核是一个**消息驱动的异步引擎**，其核心： 1. **main.tsx** — React REPL，UI 状态机与事件监听 2. **query.ts** — Async generator，单次 turn 的消息 ↔ API ↔ 工具流程 3. **QueryEngine.ts** — 会话级别包装，SDK 兼容，历史管理 4. **Tool.ts + tools.ts** — 工具注册、权限、MCP 集成 5. **coordinator/** — 多 agent 协调，worker 权限隔离 6. **history.ts, context.ts, commands.ts** — 上下文、命令、历史 其设计精髓： - **分离关注点**：turn 逻辑 vs 会话逻辑 vs UI - **权限透明**：两层检查 + 可配置规则 - **扩展友好**：feature gates、MCP、skills、agents - **性能优化**：启动并行化、token 预算、流式结果 实现了一个**生产级 AI IDE 的核心**，支持 SDK、REPL、print 等多模式，具有会话恢复、成本控制、权限管理、多 agent 协调等企业级特性。 --- # Part II — 多 Provider 路由系统（OpenClaude 核心差异化） ## 架构概览：从用户配置到真实 LLM API ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 用户配置（Profile & Env Vars） │ │ /provider → resolveProfileRoute() → 用户选择的 provider 字符串 │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ ProfileResolver 层（兼容性与路由解析） │ │ isProviderPreset() ─► routeForPreset() │ │ getVendor(id) / getGateway(id) ─► ResolvedProfileRoute │ │ {vendorId, gatewayId?, routeId} │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Registry（注册表 & 发现服务） │ │ ensureIntegrationsLoaded() ─► VENDOR_DESCRIPTORS / GATEWAY_DESCRIPTORS │ │ ├─ registerVendor() / registerGateway() │ │ ├─ getVendor(vendorId) / getGateway(gatewayId) │ │ ├─ getCatalogEntriesForRoute() ─► ModelCatalogEntry[] │ │ └─ getAllModels() ─► ModelDescriptor[] 全模型列表 │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ RouteMetadata 层（路由元数据） │ │ getRouteDescriptor(routeId) ─► RouteDescriptor │ │ getRouteDefaultBaseUrl() / getRouteDefaultModel() │ │ resolveRouteIdFromBaseUrl() ─► 从自定义 baseUrl 反向查询 │ │ getRouteLabel() / getTransportKindForRoute() │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 模型发现 & 缓存 (Discovery Service & Cache) │ │ discoverModelsForRoute(routeId) ─► RouteDiscoveryResult │ │ ├─ 静态目录 (source: 'static') │ │ ├─ 网络发现 (source: 'network' via OpenAI /models API) │ │ ├─ 缓存命中 (source: 'cache' with TTL) │ │ └─ 过期缓存降级 (source: 'stale-cache') │ │ DiscoveryService：ollama、openai-compatible、custom 三种发现模式 │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Compatibility & Runtime Metadata 层（兼容性处理） │ │ compatibility.ts： │ │ ├─ PRESET_ROUTE_MAP (Anthropic v4 → openai/gemini 映射) │ │ └─ routeForPreset() / vendorIdForPreset() │ │ runtimeMetadata.ts： │ │ ├─ 模型到具体 API 名称的映射 (providerModelMap) │ │ ├─ 上下文窗口和 Token 上限查询 │ │ └─ OpenAI Shim 配置 (removeBodyFields, maxTokensField 等) │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenAI Shim / Transport Config（传输适配层） │ │ TransportKind: anthropic-native / gemini-native / openai-compatible / .. │ │ OpenAIShimTransportConfig： │ │ ├─ headers、supportsApiFormatSelection、supportsAuthHeaders │ │ ├─ preserveReasoningContent (DeepSeek R1) │ │ ├─ thinkingRequestFormat (deepseek-compatible) │ │ ├─ removeBodyFields (过滤不支持的 body 字段) │ │ └─ maxTokensField (max_tokens vs max_completion_tokens) │ │ ▌工具调用格式统一化：所有 OpenAI 兼容 API → Claude tool_use format │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Upstream Proxy / Gateway（上游代理） │ │ upstreamproxy.ts / relay.ts： │ │ ├─ CCR (Cloud Code Runtime) 环境支持 │ │ ├─ WebSocket → TCP CONNECT 中继 │ │ ├─ MITM TLS termination（可选的组织凭证注入） │ │ └─ NO_PROXY 例外清单 (anthropic.com, github.com 等) │ │ 网络路由：所有 OpenAI 兼容请求都可过 upstream proxy 到真实 LLM API │ └──────────────────────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 真实 LLM API（200+ 支持的 Provider） │ │ Anthropic 原生（anthropic.ts） │ │ └─ https://api.anthropic.com (x-api-key 认证) │ │ OpenAI 兼容（openai.ts + 任意 OpenAI /v1 端点） │ │ ├─ OpenAI（gpt-5.4） │ │ ├─ DeepSeek（deepseek-v4-pro with reasoning） │ │ ├─ Groq（llama-3.3-70b） │ │ ├─ Mistral（devstral-latest） │ │ ├─ Moonshot/Kimi（8k-latest） │ │ └─ 200+ 其他兼容端点 │ │ Gemini 原生（gemini.ts） │ │ └─ https://generativelanguage.googleapis.com/v1beta/openai │ │ 本地 Ollama（ollama.ts） │ │ └─ http://localhost:11434/v1 (无认证) │ │ 网关/聚合服务 │ │ ├─ OpenRouter（200+ 模型） │ │ ├─ GitLawb OpenGateway（GitLawb 企业集成） │ │ ├─ Hicap（响应模式） │ │ ├─ Together.ai、Atomic Chat、LM Studio 等 │ │ └─ 中国本地（Xiaomi MiMo、MiniMax、Bankr 等） │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 1. 核心子系统：Registry（注册表） ### 职责 Registry 是全局单例模式，存储所有 Provider Descriptor（厂商、网关、模型、品牌），提供按 ID 查询的能力。它是 OpenClaude 多 provider 系统的基础层。 ### 关键文件 - **src/integrations/registry.ts**（390 行）：核心实现 - **src/integrations/index.ts**（129 行）：加载器入口 - **src/integrations/generated/integrationArtifacts.generated.js**：自动生成的 Descriptor 数组 ### 核心数据结构 ```typescript // 五大注册表 Map（私有全局状态） const _brands = new Map() // 品牌（如 Claude、Opus） const _vendors = new Map() // 厂商（如 Anthropic、OpenAI） const _gateways = new Map() // 网关（如 Ollama、OpenRouter） const _anthropicProxies = new Map() // Anthropic 代理 const _models = new Map() // 模型（如 gpt-5、claude-opus） ``` ### 调用链 1. **初始化**：`ensureIntegrationsLoaded()` 逐个 register 所有 Descriptor 2. **查询**：`getVendor(id)`、`getGateway(id)`、`getModel(id)` 都是直接 Map 查询 3. **列表**：`getAllVendors()`、`getAllGateways()` 返回完整列表 4. **目录**：`getCatalogEntriesForRoute(routeId)` 查询路由的模型目录 5. **验证**：`validateIntegrationRegistry()` 检查 Descriptor 完整性 ### 可借鉴点 - **Map-based 注册表**：O(1) 查询，线程安全（Node 单线程） - **Descriptor 不可变**：一旦注册不能修改，防止运行时修改 - **验证逻辑详尽**：检查重复、缺失的引用、冲突的 preset ID、默认模型 - **测试友好**：`_clearRegistryForTesting()` 支持单元测试隔离 --- ## 2. 核心子系统：ProfileResolver（用户配置解析） ### 职责 将用户保存的 profile 字符串（如 "anthropic"、"openrouter"、"ollama"）映射到具体的路由描述符，处理向后兼容性（Anthropic v4 preset 名称等）。 ### 关键文件 - **src/integrations/profileResolver.ts**（48 行）：路由解析算法 - **src/integrations/compatibility.ts**（60 行）：Preset 映射表 ### 核心数据结构 ```typescript export type ResolvedProfileRoute = { vendorId: string // 真实的 vendor（如 'openai', 'anthropic'） gatewayId?: string // 如果是网关，则有这个值（如 'ollama'） routeId: string // 用于查询具体 Descriptor 的 ID } ``` ### 调用链 ```typescript resolveProfileRoute("gpt-4o") → { // 1. 尝试 isProviderPreset("gpt-4o") → false // 2. 尝试 getVendor("gpt-4o") → undefined // 3. 尝试 getGateway("gpt-4o") → undefined // 4. 如果都失败 → 回退到 {vendorId: "openai", routeId: "unknown-fallback"} // 或者若输入 "openai" 是已知 preset： routeForPreset("openai") → { vendorId: "openai", routeId: "openai" } } ``` ### 可借鉴点 - **分层解析**：Preset → Vendor → Gateway → Fallback，清晰的优先级 - **容错设计**：未知 provider 回退到 OpenAI 兼容，不报错 - **向后兼容**：PROVIDER_PRESET_MANIFEST 保存历史 preset 映射 --- ## 3. 核心子系统：DiscoveryService（模型发现） ### 职责 通过网络探测或静态配置发现给定路由上可用的模型列表，支持缓存和降级。是支持动态 provider（Ollama、OpenRouter、网关）的关键。 ### 关键文件 - **src/integrations/discoveryService.ts**（528 行）：主逻辑 - **src/integrations/discoveryCache.ts**（331 行）：缓存层 ### 核心数据结构 ```typescript export type RouteDiscoveryResult = { routeId: string // 路由 ID models: ModelCatalogEntry[] // 发现的模型列表 stale: boolean // 缓存是否过期 error: DiscoveryCacheError | null // 发现时的错误 source: 'network' | 'cache' | 'stale-cache' | 'static' | 'error' } // 模型发现配置（在 Descriptor 中定义） export type ModelDiscoveryConfig = { kind: 'openai-compatible' | 'ollama' | 'custom' requiresAuth?: boolean mapModel?: (raw: unknown) => ModelCatalogEntry | null // 自定义映射器 } ``` ### 调用链 1. **启动探测**：`refreshStartupDiscoveryForActiveRoute()` 在 app 初始化时运行 - 读取 env vars（OPENAI_BASE_URL、OPENAI_API_KEY） - 调用 `refreshStartupDiscoveryForRoute(routeId, {baseUrl, apiKey})` 2. **发现执行**：`discoverModelsForRoute(routeId, options?)` - 检查 static catalog 是否存在 - 若有 discovery config，从缓存或网络获取 - 支持 `forceRefresh` 跳过缓存 3. **缓存管理**：`getDiscoveryCacheKey(routeId, {baseUrl, apiKey, headers})` - 基于 baseUrl、API key 哈希、自定义 headers 生成唯一 key - TTL 可配置（如 Groq 1d） 4. **发现种类**： - **ollama**：调用 `probeOllamaModelCatalog({baseUrl})` → 解析 `/api/tags` - **openai-compatible**：调用 `listOpenAICompatibleModels({baseUrl, apiKey})` → 解析 `/models` 响应 - **custom**：provider 自定义逻辑（如 Atomic Chat） ### 可借鉴点 - **三层缓存**：静态 → 新鲜缓存 → 过期缓存（graceful degradation） - **隐私友好**：`isEssentialTrafficOnly()` 支持禁止非必需 discovery 流量 - **自适应映射**：`discovery.mapModel()` 允许 per-provider 的 model 过滤（如 Groq 去掉 whisper 模型） - **启动友好**：`discoveryRefreshMode: 'startup'` 仅在应用启动时一次发现 --- ## 4. 核心子系统：RouteMetadata（路由元数据查询） ### 职责 提供路由相关的元数据查询（默认 baseUrl、默认模型、auth 信息、transport 种类等），支持从自定义 baseUrl 反向查询到路由 ID。 ### 关键文件 - **src/integrations/routeMetadata.ts**（652 行）：完整实现 ### 核心函数 | 函数 | 作用 | |------|------| | `getRouteDescriptor(routeId)` | 查询任何路由的完整描述符 | | `getRouteDefaultBaseUrl(routeId)` | 查询默认的 API 端点 URL | | `getRouteDefaultModel(routeId)` | 查询默认模型（从 defaultModel 或 catalog[0]） | | `getTransportKindForRoute(routeId)` | 获取 transport 类型（决定如何序列化请求） | | `resolveRouteIdFromBaseUrl(baseUrl, opts?)` | 从 baseUrl 反向查找路由（自定义端点场景） | | `resolveActiveRouteIdFromEnv(processEnv, opts?)` | 从环境变量推断当前活跃路由 | | `resolveRouteCredentialValue({routeId, processEnv})` | 查询该路由的 API key（从 env 变量） | ### 调用链示例 ```typescript // 用户设置自定义 OpenAI-compatible baseUrl resolveRouteIdFromBaseUrl("https://api.minimax.io/v1") → 检查 MiniMax 特定的 host 匹配 → 返回 "minimax"（或基于 classification 返回 openai） // 查询 API key resolveRouteCredentialValue({ routeId: "deepseek", processEnv: process.env }) → 按优先级查询 process.env 中的 credentialEnvVars → 返回第一个非空值或 undefined ``` ### 可借鉴点 - **Host 匹配**：支持特定 provider 的 host 识别（MiniMax、X.ai、Xiaomi MiMo） - **Env 变量层次**：同一 route 支持多个环境变量（优先级排序） - **验证路由**：检查 baseUrl 是否与已知网关/厂商匹配 - **本地路由检测**：自动识别 localhost:11434（Ollama）、localhost:1234（LM Studio） --- ## 5. 核心子系统：Compatibility & Routing（兼容性处理） ### 职责 处理 Claude API 和其他 Provider 之间的协议差异。重点是将任意 OpenAI 兼容 API 的请求/响应适配成 Claude SDK 期望的格式。 ### 关键文件 - **src/integrations/compatibility.ts**（60 行）：Preset 映射 - **src/integrations/runtimeMetadata.ts**（404 行）：运行时适配配置生成 ### 核心概念：OpenAI Shim OpenAI Shim 是 OpenClaude 的核心创新——它将任意 OpenAI /v1 兼容服务适配成 Claude API 格式： ```typescript // OpenAIShimTransportConfig（在 Descriptor 中定义） { headers?: Record // 额外 HTTP 头 supportsApiFormatSelection?: boolean // 是否支持 ?api_format=openai supportsAuthHeaders?: boolean // 是否支持 Authorization: Bearer maxTokensField?: 'max_tokens' | 'max_completion_tokens' // Token 字段名适配 removeBodyFields?: string[] // 删除不支持的 body 字段 preserveReasoningContent?: boolean // 保留思考内容（DeepSeek） requireReasoningContentOnAssistantMessages?: boolean // 强制 assistant 消息包含思考 thinkingRequestFormat?: 'deepseek-compatible' // 思考格式转换 defaultAuthHeader?: OpenAIShimAuthHeaderConfig // auth header 配置 } ``` ### 模型映射算法 ```typescript // src/integrations/runtimeMetadata.ts 中的关键函数 matchesCatalogEntryModel(routeId, entry, modelApiName) { // 1. 直接匹配 entry.apiName if (entry.apiName === modelApiName) return true // 2. 若 entry 有 modelDescriptorId，查询 ModelDescriptor const modelDesc = getModel(entry.modelDescriptorId) // 3. 匹配 modelDesc.defaultModel if (modelDesc.defaultModel === modelApiName) return true // 4. 检查 providerModelMap[routeId] // 例如：同一个"claude-opus-4.6"在不同 provider 有不同名称 return modelDesc.providerModelMap?.[routeId] === modelApiName } ``` **例子**： - 同一个逻辑模型 "claude-opus-4.6" 在： - Anthropic API 中叫 `claude-opus-4.6` - Bankr 中叫 `claude-opus-4.6` - OpenRouter 中可能叫 `anthropic/claude-opus-4.6` - MiniMax 可能不支持 - 通过 `providerModelMap` 映射，Claude SDK 可统一引用 ### 工具调用格式转换 OpenClaude 的关键任务：**任意 OpenAI 兼容 API → Claude tool_use format** 虽然代码中具体的工具转换逻辑在 `src/services/api/openaiShim.ts`（不在 integrations 范围内），但 descriptor 的角色是： ```typescript // Descriptor 声明该 route 的能力 supportsApiFormatSelection: true/false // 是否能切换到 Claude 格式 supportsFunctionCalling: true/false // 是否支持工具调用 ``` Shim 在运行时： 1. 接收用户的 Claude SDK 格式请求（带 tools 数组） 2. 根据 `supportsApiFormatSelection`，决定是否转换为 OpenAI `functions` 格式 3. 接收响应，反向转换回 `tool_use` block 格式 ### 可借鉴点 - **Descriptor-驱动适配**：adapter 配置完全在 Descriptor 中，无硬编码 - **provider 优先级路由**：通过 `validation.routing.fallbackWhenUseOpenAI` 支持有条件回退 - **流式输出适配**：不同 provider 的 streaming 格式有差异（delta vs function_call），Shim 统一处理 - **推理内容保留**：DeepSeek R1 有 `thinking` 字段，Shim 识别并保留给 Claude SDK --- ## 6. Vendors（厂商）— 11 个一级 LLM 提供商 ### 支持的 Vendors | ID | 标签 | 分类 | 默认模型 | 认证 | 特殊功能 | |---|---|---|---|---|---| | **anthropic** | Anthropic | anthropic-native | claude-sonnet-4-6 | x-api-key | 原生 API，支持 vision、tool_use、streaming | | **openai** | OpenAI | openai-compatible | gpt-5.4 | Bearer token | OpenAI /v1 标准实现 | | **gemini** | Google Gemini | gemini-native | gemini-3-flash | API key | Gemini API，支持 vision、multimodal | | **deepseek** | DeepSeek | openai-compatible | deepseek-v4-pro | API key | R1 推理模型，preserveReasoningContent | | **groq** | Groq | openai-compatible | llama-3.3-70b | API key | 低延迟推理，whisper/guard 过滤 | | **mistral** | Mistral AI | openai-compatible | devstral-latest | API key | Mistral 云端服务，支持特定覆盖 | | **moonshot** | Kimi/Moonshot | openai-compatible | 8k-latest | API key | 中文优化，8K 上下文 | | **minimax** | MiniMax | openai-compatible | minimax-m2.7 | API key | 中文模型，支持 MiniMax-Text-01 vision | | **xiaomi-mimo** | Xiaomi MiMo | openai-compatible | mimo-v2.5-pro | API key | 中文，国内部署，支持动态发现 | | **bankr** | Bankr Bot | openai-compatible | claude-opus-4.6 | API key | 聚合网关，支持多个 Claude 模型 | | **zai** | Zai (Zero to AI) | openai-compatible | ? | API key | 可能是小众网关 | | **venice** | Venice.ai | openai-compatible | ? | API key | 开源模型网关 | | **xai** | X.AI (Grok) | openai-compatible | ? | API key | X 公司的 Grok 模型 | ### Vendor Descriptor 结构 ```typescript export interface VendorDescriptor { id: string // 全局唯一 ID label: string // 用户界面显示名称 classification: 'native' | 'openai-compatible' | ... defaultBaseUrl: string // 如 https://api.openai.com/v1 defaultModel: string // 默认推荐模型 requiredEnvVars: string[] // 必需的环境变量（文档用） setup: SetupMetadata // 认证模式（api-key / oauth / adc） transportConfig: TransportConfig // 协议适配配置 catalog: ModelCatalogConfig // 模型目录（静态或发现） preset?: ProviderPresetMetadata // 是否支持 /provider 保存 validation?: { // 认证和路由验证 kind: 'credential-env' | 'gemini-credential' | ... routing?: ValidationRoutingMetadata credentialEnvVars: string[] } isFirstParty?: boolean // Anthropic 一方（用于特殊处理） usage?: UsageMetadata // 额度/使用量查询支持 } ``` ### 每个 Vendor 的关键差异 #### 1. anthropic.ts - Anthropic 原生 ```typescript transportConfig: { kind: 'anthropic-native' } // 不需要 openaiShim preset: { id: 'anthropic', description: 'Native Claude API (x-api-key auth)', apiKeyEnvVars: ['ANTHROPIC_API_KEY'], baseUrlEnvVars: ['ANTHROPIC_BASE_URL'], modelEnvVars: ['ANTHROPIC_MODEL'], } ``` **特点**：一级 provider，直接调用 Anthropic `/v1/messages` 端点。 #### 2. openai.ts - OpenAI 基础 ```typescript transportConfig: { kind: 'openai-compatible', openaiShim: { supportsApiFormatSelection: true, // 可切换格式 supportsAuthHeaders: true, // Authorization header }, } preset: { id: 'openai', description: 'OpenAI API with API key', apiKeyEnvVars: ['OPENAI_API_KEY'], baseUrlEnvVars: ['OPENAI_BASE_URL'], } validation: { routing: { matchDefaultBaseUrl: true, // https://api.openai.com/v1 fallbackWhenUseOpenAI: true, // 当 CLAUDE_CODE_USE_OPENAI=1 }, } ``` **特点**：标准 OpenAI /v1 实现，支持自定义 baseUrl。 #### 3. deepseek.ts - DeepSeek（思考模型） ```typescript transportConfig: { kind: 'openai-compatible', openaiShim: { preserveReasoningContent: true, // ◄── 保留 thinking 内容 requireReasoningContentOnAssistantMessages: true, reasoningContentFallback: '', thinkingRequestFormat: 'deepseek-compatible', maxTokensField: 'max_tokens', removeBodyFields: ['store'], // DeepSeek 不支持 store }, } ``` **特点**：R1 推理模型支持，思考内容映射到 Claude thinking block。 #### 4. gemini.ts - Google Gemini（原生协议） ```typescript transportConfig: { kind: 'gemini-native', // ◄── 不是 OpenAI 兼容 openaiShim: { removeBodyFields: ['store'], // Gemini 也不支持 store }, } defaultBaseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai' ``` **特点**：Google 原生 API，虽然提供 OpenAI 兼容端点但有特殊处理。 #### 5. minimax.ts - MiniMax（中文+特殊配置） ```typescript validation: { routing: { matchBaseUrlHosts: ['api.minimax.io', 'api.minimax.chat'], }, } // 12 个模型，从 M2 到 Vision-01 catalog: { source: 'static', models: [ { id: 'minimax-m2.7', apiName: 'MiniMax-M2.7', label: 'MiniMax M2.7', ... }, // ... Text-01, Vision-01 variants ], } ``` **特点**：完整的中文 LLM 模型列表，host 识别支持多个域名。 ### 可借鉴点 - **分类清晰**：anthropic-native vs openai-compatible，明确的 transport 类型 - **per-vendor 覆盖**：`openaiShim` 可选，允许原生协议与兼容协议共存 - **模型完整性**：每个 vendor 的 catalog 都包含真实支持的模型列表 - **环境变量多元化**：同一 vendor 可支持多套 env var 命名（如 OPENAI_MODEL / BANKR_MODEL） --- ## 7. Gateways（网关/聚合服务）— 18 个网关 ### 支持的 Gateways | ID | 标签 | 类别 | 默认模型 | 模型发现 | 特殊功能 | |---|---|---|---|---|---| | **ollama** | Ollama | local | llama3.1:8b | 动态发现 | 本地推理，无认证 | | **openrouter** | OpenRouter | aggregating | openai/gpt-5-mini | 混合(hybrid) | 200+ 模型聚合，平衡路由 | | **groq** | Groq | aggregating | llama-3.3-70b | 混合 | 低延迟推理 | | **mistral** | Mistral AI | hosted | devstral-latest | 静态 | Mistral 云端网关 | | **lmstudio** | LM Studio | local | (动态) | 动态 | 本地/网络 LM Studio 服务 | | **hicap** | Hicap | hosted | (custom) | 混合 | 响应模式，自定义模型 | | **atomic-chat** | Atomic Chat | local | (动态) | 动态 | 本地模型服务，启动探针 | | **github** | GitHub Models | hosted | (动态) | 动态 | GitHub 免费额度，OAuth | | **together** | Together.ai | aggregating | ? | 混合 | Together 模型网关 | | **azure-openai** | Azure OpenAI | hosted | ? | 静态 | Microsoft Azure 部署 | | **bedrock** | AWS Bedrock | hosted | ? | 静态 | Amazon Bedrock Claude API | | **vertex** | Google Vertex AI | hosted | ? | 静态 | Google Cloud Vertex AI | | **dashscope-cn** | 阿里 DashScope | hosted | ? | 静态 | 中国内地，Qwen 等 | | **dashscope-intl** | DashScope Intl | hosted | ? | 静态 | 国际版 DashScope | | **kimi-code** | Kimi Code | hosted | (custom) | 静态 | 月之暗面，编程优化 | | **nvidia-nim** | NVIDIA NIM | hosted | ? | 静态 | NVIDIA 推理微服务 | | **gitlawb-opengateway** | GitLawb OpenGateway | aggregating | ? | 混合 | GitLawb 企业网关 | | **atomic-chat** | Atomic Chat | local | (动态) | 动态 | 本地模型加载服务 | ### Gateway Descriptor 结构 ```typescript export interface GatewayDescriptor extends RouteMetadata { id: string label: string category: 'local' | 'hosted' | 'aggregating' defaultBaseUrl: string defaultModel: string supportsModelRouting: boolean // 是否支持任意模型选择 setup: SetupMetadata startup?: StartupMetadata // 自动检测、启动探针 transportConfig: TransportConfig catalog: ModelCatalogConfig preset?: ProviderPresetMetadata usage?: UsageMetadata } ``` ### 关键 Gateway 详解 #### 1. ollama.ts - 本地推理 ```typescript id: 'ollama', defaultBaseUrl: 'http://localhost:11434/v1', supportsModelRouting: true, // 支持任意 ollama 模型 setup: { requiresAuth: false, // 无认证 authMode: 'none', }, startup: { autoDetectable: true, // 可自动检测 probeReadiness: 'ollama-generation', // 尝试运行模型测试就绪性 }, catalog: { source: 'dynamic', discovery: { kind: 'ollama' }, // 通过 /api/tags 发现 discoveryCacheTtl: '1d', discoveryRefreshMode: 'background-if-stale', allowManualRefresh: true, }, ``` **特点**：完全本地，无凭证，支持后台自动发现。 #### 2. openrouter.ts - 模型聚合 ```typescript id: 'openrouter', defaultBaseUrl: 'https://openrouter.ai/api/v1', defaultModel: 'openai/gpt-5-mini', supportsModelRouting: true, setup: { requiresAuth: true, authMode: 'api-key', credentialEnvVars: ['OPENROUTER_API_KEY'], }, catalog: { source: 'hybrid', // 静态 + 动态混合 discovery: { kind: 'openai-compatible' }, models: [ { id: 'openrouter-gpt-5-mini', apiName: 'openai/gpt-5-mini', ... }, ], }, ``` **特点**：200+ 模型，混合目录，支持任意 provider 模型路由。 #### 3. atomic-chat.ts - 本地模型服务 ```typescript id: 'atomic-chat', defaultBaseUrl: 'http://localhost:8000/v1', setup: { requiresAuth: false, authMode: 'none', }, startup: { probeReadiness: 'openai-compatible-models', // 探测 /models }, catalog: { source: 'dynamic', discovery: { kind: 'openai-compatible' }, }, ``` **特点**：本地 UI 服务，自动发现，无凭证。 #### 4. groq.ts - 低延迟推理（带模型过滤） ```typescript catalog: { source: 'hybrid', discovery: { kind: 'openai-compatible', mapModel(raw: unknown) { const model = raw as { id?: string; active?: boolean } // 过滤 Groq 的非推理模型 if (/(whisper|distil-whisper|guard)/i.test(model.id)) { return null // ◄── 不包含在结果中 } return { id: model.id, apiName: model.id, label: model.id, } }, }, }, ``` **特点**：自定义 mapModel，可选择性包含模型。 #### 5. github.ts - GitHub Models（OAuth） ```typescript defaultBaseUrl: 'https://models.inference.ai.azure.com', setup: { requiresAuth: true, authMode: 'oauth', // ◄── OAuth，不是 api-key }, catalog: { source: 'hybrid', discovery: { kind: 'openai-compatible' }, }, ``` **特点**：OAuth 认证（GitHub 账号登录），免费额度。 ### 可借鉴点 - **category 分类**：local 不需要凭证，aggregating 聚合多个模型，hosted 第三方服务 - **autoDetectable**：本地 gateway（ollama、lmstudio）标记为可自动检测，支持启动时自动选择 - **hybrid 目录**：既有静态模型列表又支持动态发现，兼顾启动速度和完整性 - **per-gateway 过滤**：Groq 的 `mapModel` 演示了如何筛选不适合的模型 --- ## 8. 核心差异：OpenClaude vs. Claude Code 原版 ### Claude Code 原版（Anthropic 官方） ``` 只支持 3 种 provider： ├─ Anthropic（原生 API） ├─ AWS Bedrock └─ Google Vertex AI ``` **特点**： - 严格的 Anthropic 生态 - 最安全、官方支持最好 - 企业级认证（ADC / IAM） ### OpenClaude（GitLawb Fork） ``` 支持 200+ provider： ├─ 一级厂商（11 个） │ ├─ Anthropic（原生） │ ├─ OpenAI（gpt-5.4） │ ├─ DeepSeek（推理模型） │ ├─ Gemini（Google） │ ├─ Groq、Mistral、Moonshot（各类型） │ └─ 中国本地（MiniMax、Xiaomi、Kimi、etc） ├─ 网关聚合（18 个） │ ├─ 本地（Ollama、LM Studio、Atomic Chat） │ ├─ 聚合服务（OpenRouter、Groq、Together） │ ├─ 企业（Azure、Bedrock、Vertex） │ └─ 中国（DashScope、GitLawb OpenGateway） └─ 动态发现 ├─ 支持任意 OpenAI /v1 兼容端点 └─ 自动发现模型列表 ``` ### 差异对比表 | 维度 | Claude Code | OpenClaude | |------|-------------|-----------| | **支持的 Provider 数** | 3 | 200+ | | **本地推理** | 无 | Ollama、LM Studio、Atomic Chat | | **模型发现** | 无 | OpenAI /models API、Ollama /api/tags | | **中文模型** | 无 | MiniMax、Kimi、DashScope、Xiaomi MiMo | | **推理模型** | 不支持 | DeepSeek R1（preserveReasoningContent） | | **模型路由** | 固定 provider | 动态选择 200+ 模型 | | **自定义端点** | 不支持 | 完全支持（任意 OpenAI 兼容端点） | | **缓存策略** | 固定 | 可配置 TTL（1d、1h、etc） | | **网关聚合** | 无 | OpenRouter、Groq、GitLawb OpenGateway | | **代码** | 单一 provider 路径 | 通用 OpenAI Shim 路径 | ### 迁移路径 ``` Claude Code 用户的迁移： ANTHROPIC_API_KEY=sk-... ─┐ ANTHROPIC_BASE_URL=... ├─ /provider ─► 保存为 "anthropic" preset ANTHROPIC_MODEL=... ─┘ ↓ 可选：尝试其他 provider OPENAI_API_KEY=... ─────► /provider ─► 选 "openai" DeepSeek 推理模型 ──────► /provider ─► 选 "deepseek" 本地 Ollama ────────────► /provider ─► 选 "ollama"（自动发现） ``` --- ## 9. 关键数据流示例 ### 场景 1：用户启动 OpenClaude with OpenAI API Key ``` $ export CLAUDE_CODE_USE_OPENAI=1 $ export OPENAI_API_KEY=sk-... $ export OPENAI_BASE_URL=https://api.openai.com/v1 # 可选 $ openclaude ↓ init.ts / loadPersistedProfile() ↓ resolveActiveRouteIdFromEnv(process.env) ├─ 检查 CLAUDE_CODE_USE_OPENAI=1 ✓ ├─ 返回 routeId = "openai" └─ 如果环境变量不同，可能返回其他 routeId ↓ refreshStartupDiscoveryForActiveRoute() ├─ baseUrl = process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1" ├─ routeId = "openai" ├─ apiKey = resolveRouteCredentialValue({routeId: "openai", processEnv}) │ → 按优先级查询 OPENAI_API_KEY └─ discoverModelsForRoute("openai", {baseUrl, apiKey}) ├─ getRouteCatalog("openai") → 获取静态模型列表 ├─ 如果有 discovery config，发起 GET /models ├─ 缓存结果（默认 1 天或无） └─ 返回 RouteDiscoveryResult { routeId: "openai", models: [gpt-5.4, gpt-5-mini, ...], source: "network" or "cache", error: null } ↓ 运行时（用户在 Claude Code 中输入提示词） ├─ 活跃路由 = "openai" ├─ 获取 routeDescriptor = getRouteDescriptor("openai") ├─ 序列化请求为 OpenAI 格式（带 tool_use 映射） ├─ 发送到 baseUrl + "/v1/chat/completions" │ Authorization: Bearer sk-... ├─ 接收 OpenAI 格式响应 ├─ 解析并映射回 Claude tool_use block 格式 └─ 返回给用户界面 ``` ### 场景 2：用户启动 Ollama + 发现模型 ``` $ export OPENAI_BASE_URL=http://localhost:11434/v1 $ ollama run qwen2.5-coder:7b # 后台启动 Ollama $ openclaude ↓ resolveRouteIdFromBaseUrl("http://localhost:11434/v1") ├─ parseUrl() → hostname = "localhost", port = 11434 ├─ 匹配规则 host.endsWith(':11434') ✓ └─ 返回 routeId = "ollama" ↓ refreshStartupDiscoveryForActiveRoute() ├─ routeId = "ollama" ├─ baseUrl = "http://localhost:11434/v1" ├─ apiKey = undefined（ollama.setup.requiresAuth = false） └─ discoverModelsForRoute("ollama", {baseUrl}) ├─ catalog = getRouteCatalog("ollama") → { source: 'dynamic', discovery: { kind: 'ollama' } } ├─ probeOllamaModelCatalog({baseUrl}) │ └─ GET http://localhost:11434/api/tags → 列出所有加载的模型 │ 返回 [{ name: "qwen2.5-coder:7b" }, { name: "llama3.1:8b" }, ...] ├─ 转换为 ModelCatalogEntry[] 并缓存（TTL 1 天） └─ 返回 RouteDiscoveryResult { routeId: "ollama", models: [{id: "qwen2.5-coder:7b", apiName: "qwen2.5-coder:7b"}, ...], source: "network", error: null } ↓ 运行时（用户在模型列表中选择 qwen2.5-coder:7b） ├─ 序列化为 OpenAI 兼容请求 ├─ POST http://localhost:11434/v1/chat/completions │ { model: "qwen2.5-coder:7b", messages: [...] } ├─ Ollama 处理（无需凭证） └─ 返回 OpenAI 格式响应 ``` ### 场景 3：用户配置 DeepSeek + 思考内容映射 ``` /provider ─► 选择 "deepseek" 输入 API key ↓ getVendor("deepseek") → { id: "deepseek", transportConfig: { kind: 'openai-compatible', openaiShim: { preserveReasoningContent: true, thinkingRequestFormat: 'deepseek-compatible', ... } } } ↓ 运行时（调用 DeepSeek V4 Pro） ├─ 用户请求："理解这段代码" ├─ Claude SDK 封装为标准请求 ├─ Shim 转换为 DeepSeek 格式 │ { model: "deepseek-v4-pro", messages: [...] } ├─ DeepSeek 返回：{ │ reasoning_content: "我来分析这个 Python 代码...", │ content: "这段代码实现了..." │ } ├─ Shim 映射回 Claude thinking block 格式： │ blocks = [ │ { type: "thinking", thinking: "我来分析..." }, │ { type: "text", text: "这段代码..." } │ ] └─ 返回给用户界面（展示思考过程 + 答案） ``` --- ## 10. 模型路由算法（Model Routing） OpenClaude 的模型路由支持两种模式： ### 模式 1：精确模型选择（Model-aware） ```typescript 用户选择模型："gpt-5.4" ↓ runtimeMetadata.getCatalogEntryForModel("openai", "gpt-5.4") ├─ 查找 catalog 中是否有匹配的 entry ├─ 检查 entry.apiName、entry.modelDescriptorId.defaultModel └─ 返回 ModelCatalogEntry { id: "gpt-5.4", apiName: "gpt-5.4" } ↓ 构建请求：{ model: "gpt-5.4", ... } ``` ### 模式 2：通用 OpenAI 兼容（Model-agnostic） ```typescript 用户选择模型："my-custom-model"（自定义模型名） ↓ 如果路由支持 supportsModelRouting = true ├─ 直接使用用户指定的模型名 ├─ 构建请求：{ model: "my-custom-model", ... } └─ 发送到 provider，由 provider 验证 ``` ### 模型提示词生成 当用户在 Claude Code 中调用 AI 时，系统自动： ``` 1. 读取用户选择的 routeId 和 model 2. 查询 getRouteDescriptor(routeId).catalog 3. 查询 ModelDescriptor（如果 entry.modelDescriptorId 存在） 4. 从 ModelDescriptor.providerModelMap[routeId] 获取真实 API 名称 5. 发送给 LLM API 例： routeId = "openrouter" model = "gpt-5-mini"（用户看到的名称） ↓ lookup ModelDescriptor for "gpt-5-mini" ↓ modelDescriptor.providerModelMap["openrouter"] = "openai/gpt-5-mini" ↓ POST /chat/completions { model: "openai/gpt-5-mini", ... } ``` --- ## 11. 支持的 Vendors 和 Gateways 完整清单 ### Vendors（按 classification） **Anthropic 原生（1）** - anthropic **OpenAI 兼容（12）** - openai、deepseek、groq、mistral、moonshot、minimax、xiaomi-mimo、bankr、zai、venice、xai、kimi-code? **Gemini 原生（1）** - gemini ### Gateways（按 category） **本地（3）** - ollama、lmstudio、atomic-chat **聚合/代理（5）** - openrouter、groq、together、github、gitlawb-opengateway **企业/云平台（5）** - azure-openai、bedrock、vertex、dashscope-cn、dashscope-intl **其他（1）** - hicap（响应模式）、kimi-code（Moonshot 编程优化）、nvidia-nim ### Anthropic 代理（Proxy） 可能包括 Bedrock、Vertex 等的专用代理实现。 --- ## 总结 OpenClaude 的多 provider 路由系统通过以下关键创新超越了 Claude Code 原版： 1. **统一的 Descriptor 架构**：所有 provider 用同一套配置模板，无需硬编码 2. **通用 OpenAI Shim**：任意 OpenAI /v1 兼容 API 都能工作 3. **动态模型发现**：支持 Ollama、OpenRouter 等网关的实时模型列表 4. **灵活的 Profile 系统**：用户可保存多个 provider 配置，随时切换 5. **企业友好**：支持自定义 baseUrl、upstream proxy、企业网关 6. **中文生态支持**：MiniMax、Kimi、DashScope 等国内大模型优先 7. **推理模型支持**：DeepSeek R1 的思考内容映射 8. **缓存和降级**：发现服务支持 TTL、过期降级、离线运行 这些特性使 OpenClaude 成为真正的"多 provider fork"，而不仅是简单的 API 多选。 --- # Part III — UI 与命令层 ## 1. Slash 命令系统（Commands） ### 职责 OpenClaude 的命令系统提供了 118 个 slash 命令，分为以下类别： #### 会话管理（Session Management） - `/session` - 会话操作与切换 - `/resume` - 恢复历史会话 - `/context` - 上下文管理（交互和非交互） - `/teleport` - 跨会话传送 - `/tag` - 会话标签 - `/export` - 导出会话内容 - `/share` - 共享会话 #### 模型与配置（Model & Config） - `/model` - 模型选择与配置 - `/provider` - Provider 管理 - `/config` - 系统配置 - `/env` - 环境变量管理 - `/remote-env` - 远程环境配置 - `/theme` - 主题选择 - `/logo` - Logo 定制 - `/output-style` - 输出样式选择（OpenClaude 新增） - `/vim` - Vim 模式切换（OpenClaude 新增） - `/keybindings` - 快捷键定制 #### 调试与分析（Debug & Diagnostics） - `/doctor` - 系统诊断 - `/cost` - 成本跟踪 - `/stats` - 统计信息 - `/debug-tool-call` - 工具调用调试 - `/perf-issue` - 性能问题分析 - `/heap-dump` - 堆转储 - `/cache-probe` - 缓存探测 - `/cache-stats` - 缓存统计 - `/usage` - 使用统计 - `/insights` - 会话分析报告 #### 代码操作（Code Operations） - `/commit` - Git 提交（内部） - `/commit-message` - 提交消息生成 - `/commit-push-pr` - 一键提交推送PR（内部） - `/diff` - 文件差异展示 - `/review` - 代码审查 - `/ultrareview` - 超级审查 - `/security-review` - 安全审查 - `/auto-fix` - 自动修复 - `/autofix-pr` - PR 自动修复（内部） - `/rewind` - 撤销更改 #### 工作流与任务（Workflows & Tasks） - `/tasks` - 任务管理 - `/passes` - Pass 编制 - `/skills` - 技能库管理 - `/knowledge` - 知识库 - `/memory` - 内存管理 - `/plan` - 功能规划 - `/effort` - 工作量估算 - `/summary` - 总结生成 #### 集成与插件（Integrations & Plugins） - `/mcp` - MCP 服务器管理 - `/plugin` - 插件管理 - `/reload-plugins` - 插件重载 - `/buddy` - Buddy 模式（内部条件） - `/agents` - 代理管理 - `/fork` - 子代理创建 - `/peers` - Peer 通信（内部） #### 身份认证与权限（Auth & Permissions） - `/login` - 登录 - `/logout` - 登出 - `/oauth-refresh` - OAuth 刷新（内部） - `/permissions` - 权限管理 - `/trust-dialog` - 信任对话 - `/mcp-approval` - MCP 服务器授权 #### 提示与帮助（Info & Help） - `/help` - 帮助信息 - `/version` - 版本信息（内部） - `/release-notes` - 发版说明 - `/wiki` - Wiki 浏览 - `/feedback` - 反馈提交 - `/onboarding` - 入门教程 - `/desktop` - 桌面应用启动 - `/mobile` - 移动应用启动 #### IDE 与工具（IDE & Tools） - `/ide` - IDE 配置 - `/install-github-app` - GitHub App 安装 - `/install-slack-app` - Slack App 安装 - `/lsp` - LSP 配置 - `/chrome` - Chrome 集成 - `/terminalSetup` - 终端设置 #### 高级功能（Advanced Features） - `/voice` - 语音模式（条件加载） - `/bridge` - Bridge 模式（内部条件） - `/assistant` - 助手模式（Kairos） - `/brief` - Brief 模式（Kairos） - `/proactive` - 前摄模式（内部条件） - `/thinkback` - 思维回放 - `/thinkback-play` - 思维回放播放 - `/workflows` - 工作流脚本（条件加载） - `/torch` - Torch 模式（内部条件） - `/ultraplan` - UltraPlan（内部） #### 其他 - `/clear` - 清空屏幕 - `/color` - 颜色显示 - `/copy` - 复制 - `/exit` - 退出 - `/compact` - 压缩会话 - `/upgrade` - 升级通知 - `/rate-limit-options` - 限流选项 - `/extra-usage` - 额外使用配额 - `/branch` - 分支管理 - `/files` - 文件管理 - `/add-dir` - 添加目录 - `/context-visualization` - 上下文可视化 - `/breaks` - 中断管理 ### 关键文件 ``` /tmp/openclaude-src/src/commands.ts (670 行) - COMMANDS() 数组：所有命令注册 - getSkills()：动态加载技能 - getCommandName()：命令名称解析 - isCommandEnabled()：命令启用检查 /tmp/openclaude-src/src/types/command.ts - PromptCommand：提示型命令（由 Claude 处理） - LocalCommand：本地 JS 命令 - LocalJSXCommand：TUI 组件命令 - CommandResultDisplay：'skip' | 'system' | 'user' - LocalJSXCommandContext：命令上下文 /tmp/openclaude-src/src/commands/*/index.ts|js - 118 个命令目录，每个实现一个 slash 命令 ``` ### 核心数据结构 ```typescript type Command = | PromptCommand // 发送给 Claude 的提示 | LocalCommand // 本地 JS 执行 | LocalJSXCommand // React JSX TUI 渲染 interface PromptCommand { type: 'prompt' name: string description: string contentLength: number // 用于 token 估算 progressMessage: string source: 'builtin' | 'plugin' | 'bundled' | 'mcp' getPromptForCommand(args, context): Promise } interface LocalJSXCommand { type: 'local-jsx' name: string description: string load(): Promise<{ call: LocalJSXCommandCall }> } type LocalJSXCommandCall = ( onDone: LocalJSXCommandOnDone, context: LocalJSXCommandContext, args: string ) => Promise ``` ### 调用链 ``` 用户输入 /command args ↓ commands.ts: parseCommand() ↓ COMMANDS() 数组查找 ↓ ├─ PromptCommand → 转为系统消息发送给 Claude ├─ LocalJSXCommand → 加载并调用 call()，获得 React.ReactNode │ 由 Ink 渲染引擎渲染 └─ LocalCommand → 加载 load()，调用返回的 LocalCommandResult LocalJSXCommand 的渲染流程： call() 返回 React.ReactNode ↓ REPL.tsx 通过 setToolJSX() 设置 ↓ Ink 渲染引擎 ↓ 终端显示 ``` ### 可借鉴点 1. **延迟加载（Lazy Loading）**: 用 `load()` 推迟导入，减少启动时间 2. **功能开关（Feature Flags）**: `feature('FLAG_NAME')` 条件加载命令 3. **双重模式**: 同时支持 prompt（模型驱动）和 JSX（UI 驱动） 4. **Memoize 缓存**: COMMANDS() 用 memoize 避免重复初始化 5. **命令分类方案**: 按职能而非字母序分类，易于维护 --- ## 2. 快捷键系统（Keybindings） ### 职责 提供可配置的快捷键绑定系统，支持： - 上下文感知的键盘映射（13+ 上下文） - Chord 键支持（如 `ctrl+x ctrl+k`） - 平台差异处理（Windows/Mac/Linux） - 用户自定义覆盖 - 快捷键冲突检测 ### 关键文件 ``` /tmp/openclaude-src/src/keybindings/ defaultBindings.ts (274 行) - 系统默认快捷键 types.ts (134 行) - 类型定义 parser.ts - 快捷键语法解析 resolver.ts - 快捷键解析与查找 match.ts - 快捷键匹配算法 KeybindingContext.tsx - React 上下文 useKeybinding.ts - React Hook validate.ts - 快捷键验证 loadUserBindings.ts - 用户快捷键加载 ``` ### 核心数据结构 ```typescript // 快捷键上下文（13 种） type KeybindingContextName = | 'Global' // 全局 | 'Chat' // 聊天输入 | 'Autocomplete' // 自动完成 | 'Confirmation' // 确认对话 | 'Help' // 帮助 | 'Transcript' // 会话记录 | 'HistorySearch' // 历史搜索 | 'Task' // 任务列表 | 'MessageSelector' // 消息选择 | 'Diff' // Diff 视图 | 'Select' // 通用选择 | 'Settings' // 设置 | 'Plugin' // 插件 // 快捷键动作（70+） type KeybindingAction = | 'app:interrupt' // Ctrl+C | 'app:exit' // Ctrl+D | 'chat:submit' // Enter | 'chat:cancel' // Escape | 'chat:killAgents' // Ctrl+X Ctrl+K | 'history:search' // Ctrl+R | 'autocomplete:accept' | 'confirm:yes' | 'command:${string}' // 动态命令 // Chord 键定义（按键序列） type Chord = ParsedKeystroke[] type ParsedKeystroke = { key: string // 键名或字符 ctrl: boolean alt: boolean shift: boolean meta: boolean super: boolean } // 按键绑定块 type KeybindingBlock = { context: KeybindingContextName bindings: Record // 例: 'ctrl+c': 'app:interrupt' } ``` ### 默认快捷键核心 ```typescript // 全局快捷键（Global Context） 'ctrl+c' → 'app:interrupt' // 中断 'ctrl+d' → 'app:exit' // 退出 'ctrl+l' → 'app:redraw' // 重绘 'ctrl+t' → 'app:toggleTodos' // 切换任务 'ctrl+o' → 'app:toggleTranscript' // 切换会话记录 'ctrl+r' → 'history:search' // 历史搜索 // 聊天快捷键（Chat Context） 'enter' → 'chat:submit' // 提交 'escape' → 'chat:cancel' // 取消 'shift+tab' → 'chat:cycleMode' // 循环模式（Fast/Normal/Thinking） 'meta+p' → 'chat:modelPicker' // 模型选择 'meta+t' → 'chat:thinkingToggle' // 切换思考 'ctrl+_' → 'chat:undo' // 撤销（Ctrl+Shift+- on Kitty） 'ctrl+x ctrl+e' → 'chat:externalEditor' // 外部编辑器 'ctrl+s' → 'chat:stash' // 暂存 // Chord 键示例 'ctrl+x ctrl+k' → 'chat:killAgents' // 串联两次按键 ``` ### 平台差异处理 ```typescript // Windows Terminal VT 模式检查（Shift+Tab 支持） const SUPPORTS_TERMINAL_VT_MODE = getPlatform() !== 'windows' || (isRunningWithBun() ? satisfies(process.versions.bun, '>=1.2.23') : satisfies(process.versions.node, '>=22.17.0 <23.0.0 || >=24.2.0')) // 模式循环快捷键 const MODE_CYCLE_KEY = SUPPORTS_TERMINAL_VT_MODE ? 'shift+tab' : 'meta+m' // Windows 降级方案 // 图像粘贴（平台适配） const IMAGE_PASTE_KEY = getPlatform() === 'windows' ? 'alt+v' // Windows: Ctrl+V 被系统保留 : 'ctrl+v' ``` ### 调用链 ``` 终端按键输入 ↓ parse-keypress.ts: 解析 KeyboardEvent ↓ KeybindingContext (React Context) ↓ useKeybinding Hook ↓ resolver.ts: 查询当前上下文的绑定 ↓ match.ts: 精确匹配快捷键 ↓ 执行对应 action（dispatch 或函数调用） ``` ### 快捷键验证 - `reservedShortcuts.ts`: 禁止重绑 `ctrl+c`, `ctrl+d`（内核中断/退出） - 用户 `~/.claude/keybindings.json` 覆盖系统默认 - 冲突检测：同一上下文不允许同键不同值 ### 可借鉴点 1. **上下文分层**: 13 种上下文隔离不同 UI 的快捷键空间 2. **Chord 键支持**: 允许序列键（如 Vim `g c` 风格） 3. **平台适配**: 运行时检测终端能力，动态调整快捷键 4. **保留键位**: Ctrl+C/D 硬编码，防止用户破坏核心中断 5. **用户可配置**: JSON 格式易于编辑，Hot-reload 不需重启 --- ## 3. Ink TUI 渲染引擎（Ink Layer） ### 职责 Ink 是 OpenClaude 的 React-based Terminal UI 渲染引擎，类似于浏览器中的 DOM，但针对终端。 **核心职责：** - React 组件 → 终端 ANSI 输出 - 终端 I/O 管理（stdin/stdout/stderr） - 键盘与鼠标事件处理 - Yoga 布局引擎集成 - 屏幕缓存与差异更新 - 终端能力检测与适配 ### 关键文件（956KB, 14099 行） ``` /tmp/openclaude-src/src/ink/ ├── ink.tsx (最顶层导出) ├── root.ts (Ink 根实例) ├── renderer.ts (React Reconciler) ├── reconciler.ts (DOM 协调) ├── render-to-screen.ts (渲染到屏幕) ├── screen.ts (屏幕缓存) ├── terminal.ts (终端驱动) ├── termio/ │ ├── csi.ts (光标/清屏/字体命令) │ ├── dec.ts (DeC 专有命令) │ └── osc.ts (操作系统命令) ├── components/ (基础组件库) │ ├── Box.tsx (布局容器) │ ├── Text.tsx (文本) │ ├── Button.tsx (按钮) │ ├── Link.tsx (链接) │ ├── ScrollBox.tsx (滚动容器) │ └── AlternateScreen.tsx (备屏模式) ├── hooks/ │ ├── use-input.ts (键盘输入) │ ├── use-app.ts (应用上下文) │ ├── use-selection.ts (文本选择) │ └── use-terminal-*.ts (终端特性) ├── events/ │ ├── keyboard-event.ts │ ├── click-event.ts │ ├── input-event.ts │ └── emitter.ts ├── focus.ts (焦点管理) ├── dom.ts (DOM 树结构) ├── parse-keypress.ts (键盘解析) ├── colorize.ts (ANSI 着色) ├── wrap-text.ts (文本换行) ├── stringWidth.ts (字符宽度计算) ├── measurement/ │ ├── measure-element.ts │ ├── measure-text.ts │ └── get-max-width.ts ├── selection.ts (文本选择状态机) ├── search-highlight.ts (搜索高亮) ├── optimizer.ts (帧优化) └── ...（共 50+ 文件） ``` ### 核心数据结构 ```typescript // Ink 根实例 interface Ink { private terminal: Terminal private renderer: Renderer private screen: Screen private focusManager: FocusManager private frameBuffer: FrameEvent[] render(node: ReactNode): Promise unmount(): Promise } // DOM 节点（与浏览器 DOM 平行） type DOMElement = { type: 'text' | 'box' | 'component' parent: DOMElement | null children: DOMElement[] props: Record } // 屏幕缓存 interface Screen { cells: Cell[][] // 终端字符矩阵 width: number height: number dirty: boolean } // 帧事件（用于差异更新） type FrameEvent = { type: 'stdout' | 'interactive' content: string // ANSI 输出 } // 终端特性检测 interface Terminal { stdout: NodeJS.WriteStream stdin: NodeJS.ReadStream width: number height: number supportsHyperlinks: boolean supportsTabStatus: boolean supportsMouseTracking: boolean } ``` ### 渲染流程 ``` React.render() ↓ useLayoutEffect() ↓ React Reconciler（协调） ↓ Ink Renderer（生成 DOM 树） ↓ Yoga Layout Engine（计算位置/大小） ↓ render-to-screen.ts（DOM → ANSI 文本） ↓ screen.ts（屏幕缓存） ↓ 差异检测（仅输出变更行） ↓ termio/csi.ts（生成终端命令） ↓ stdout 输出（终端显示） ``` ### Ink 组件库 ```typescript // 基础组件 // Flexbox 容器（支持 width/height/flex) // 文本（支持 color/bold/italic) // 换行符 // 空白（flex: 1 用于填充）