---

目录

• 1. 项目概览
• 2. 技术栈
• 3. 架构分层
• 4. 启动流程
• 5. 核心模块详解
  • 5.1 入口层 (Entrypoints)
  • 5.2 查询引擎 (Query Engine)
  • 5.3 工具系统 (Tools)
  • 5.4 命令系统 (Commands)
  • 5.5 服务层 (Services)
  • 5.6 状态管理 (State)
  • 5.7 权限系统 (Permissions)
  • 5.8 UI 层 (Components / Hooks / Screens)
  • 5.9 Ink 终端渲染器
• 6. 特色子系统
• 7. 关键数据流
• 8. 核心类型定义
• 9. 模块依赖关系
• 10. 学习路线图
• 附录 A: 目录结构速查表
• 附录 B: 关键文件体积排行

---

1. 项目概览

Claude Code 是 Anthropic 官方的命令行 AI 编程助手。用户在终端中与 Claude 对话，Claude 通过调用各种工具（读写文件、执行 shell 命令、搜索代码、访问网络等）来完成软件工程任务。

核心理念：

LLM（推理引擎） + Tools（执行引擎） + Terminal UI（交互界面）

这不是一个简单的 API 封装，而是一个完整的、具有丰富交互体验的终端应用程序。它包含：

• 自定义的 React 终端渲染引擎（Ink fork）
• 完整的权限控制系统
• 多 Agent 协作能力
• MCP（Model Context Protocol）集成
• 持久化记忆系统
• 插件/技能扩展机制
• 语音输入输出
• 远程控制桥接

---

2. 技术栈

技术	用途
TypeScript	主要开发语言
Bun	运行时和构建工具
React + Ink	终端 UI 框架（自定义 fork）
Commander.js	CLI 参数解析
Zod	运行时类型校验
GrowthBook	特性开关 (Feature Flags)
OpenTelemetry	遥测和可观测性
Yoga	Flexbox 布局引擎（终端 UI）
Anthropic SDK	Claude API 调用
MCP SDK	Model Context Protocol 集成

---

3. 架构分层

项目采用 10 层架构，从底层基础设施到顶层用户界面：

┌──────────────────────────────────────────────────────┐ │ Layer 10: Entrypoints │ │ cli.tsx / mcp.ts / sdk/ │ │ 应用启动入口，不同运行模式的引导程序 │ ├──────────────────────────────────────────────────────┤ │ Layer 9: Screens │ │ REPL.tsx / Doctor.tsx / ResumeConversation.tsx │ │ 顶层页面，组装组件和 hooks │ ├──────────────────────────────────────────────────────┤ │ Layer 8: Components (140+ 文件) │ │ Messages / TextInput / StatusLine / Diff / ... │ │ React (Ink) 终端 UI 组件 │ ├──────────────────────────────────────────────────────┤ │ Layer 7: Hooks (85+ 文件) │ │ useTypeahead / useVoice / useVirtualScroll / ... │ │ React hooks，封装 UI 逻辑 │ ├──────────────────────────────────────────────────────┤ │ Layer 6: Commands (60+ 命令) │ │ /init /commit /review /compact /memory / ... │ │ 斜杠命令，用户可直接触发的操作 │ ├──────────────────────────────────────────────────────┤ │ Layer 5: Tools (40+ 工具) │ │ BashTool / FileEdit / Agent / WebSearch / ... │ │ Claude 可调用的工具，实现 Tool 接口 │ ├──────────────────────────────────────────────────────┤ │ Layer 4: Services │ │ API Client / MCP / Compact / OAuth / LSP / ... │ │ 后端服务能力 │ ├──────────────────────────────────────────────────────┤ │ Layer 3: Types │ │ Command / Permission / Plugin / Hook / Id 类型 │ │ 纯类型定义，无运行时依赖 │ ├──────────────────────────────────────────────────────┤ │ Layer 2: Utils (300+ 文件) │ │ permissions / settings / model / hooks / plugins │ │ 通用工具函数，按领域组织子目录 │ ├──────────────────────────────────────────────────────┤ │ Layer 1: Bootstrap │ │ bootstrap/state.ts │ │ 全局单例状态，最先初始化 │ └──────────────────────────────────────────────────────┘

依赖方向：上层依赖下层，下层不依赖上层（单向依赖）。

---

4. 启动流程

用户执行 `claude` 命令 │ ▼ ┌─ entrypoints/cli.tsx ─────────────────────────┐ │ 1. 处理快速路径 (--version 等，零模块加载) │ │ 2. 设置环境变量 │ │ 3. 动态 import 主程序 │ └───────────────────────────────────────────────┘ │ ▼ ┌─ entrypoints/init.ts ─────────────────────────┐ │ 初始化（只执行一次，memoized）： │ │ - 配置 (settings) │ │ - 遥测 (telemetry) │ │ - TLS / 代理 │ │ - 策略限制 (policy limits) │ │ - OAuth 认证 │ │ - LSP 服务器管理器 │ │ - 优雅关闭处理 │ └───────────────────────────────────────────────┘ │ ▼ ┌─ main.tsx (803KB) ───────────────────────────┐ │ 1. Commander.js 解析命令行参数 │ │ 2. 认证 (auth) │ │ 3. 会话设置 (setup.ts) │ │ 4. 注册工具 (tools.ts → getAllBaseTools()) │ │ 5. 注册命令 (commands.ts) │ │ 6. GrowthBook 特性开关初始化 │ │ 7. 创建 worktree（如果需要） │ │ 8. 恢复历史会话（如果指定） │ │ 9. 启动 REPL │ └───────────────────────────────────────────────┘ │ ▼ ┌─ replLauncher.tsx ───────────────────────────┐ │ 动态导入 App 和 REPL 组件 │ │ 通过 Ink 渲染到终端 │ └───────────────────────────────────────────────┘ │ ▼ ┌─ screens/REPL.tsx (895KB) ──────────────────┐ │ 主 REPL 界面： │ │ - 消息输入/显示 │ │ - 工具调用 UI │ │ - 状态栏 │ │ - 快捷键处理 │ │ - 对话循环 │ └───────────────────────────────────────────────┘

---

5. 核心模块详解

5.1 入口层 (Entrypoints)

目录： entrypoints/

文件	作用
cli.tsx	Bootstrap 入口，处理快速路径后动态导入主程序
init.ts	一次性初始化：配置、遥测、TLS、代理、OAuth、LSP、优雅关闭
mcp.ts	MCP Server 模式入口，通过 stdio 暴露工具
agentSdkTypes.ts	Agent SDK 类型定义 (13KB)
sandboxTypes.ts	沙盒模式类型定义
sdk/	SDK 集成变体（events_mono/, google/）

设计亮点： cli.tsx 实现了零模块加载的快速路径——--version 等简单操作不需要加载完整的模块图，极大提升了启动速度。

---

5.2 查询引擎 (Query Engine)

这是整个系统的大脑，负责与 Claude API 交互并驱动对话循环。

文件	大小	职责
QueryEngine.ts	46KB	高层编排：system prompt 构建、消息规范化、工具上下文设置、会话存储、成本追踪、文件历史
query.ts	68KB	底层执行：发送消息到 API、处理流式响应、执行工具调用、auto-compact、中断处理

查询循环（核心工作流）：

┌──────────────────────┐ │ 用户输入消息 │ └──────────┬───────────┘ │ ▼ ┌─────────────────────────┐ │ QueryEngine 构建请求 │ │ - System prompt │ │ - 消息历史 │ │ - 工具定义 │ │ - CLAUDE.md 上下文 │ └────────────┬────────────┘ │ ▼ ┌─────────────────────────┐ │ query.ts 发送到 API │ │ (streaming) │ └────────────┬────────────┘ │ ┌─────────┴─────────┐ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ 文本响应 │ │ 工具调用 │ │ → 显示给用户 │ │ → 执行工具 │ └──────────────┘ └──────┬───────┘ │ ▼ ┌──────────────┐ │ 工具结果 │ │ → 反馈给 API │ │ → 继续循环 │ └──────────────┘

Auto-compact 机制： 当上下文窗口接近上限时，自动压缩历史消息，保留关键信息，丢弃冗余细节。相关代码在 services/compact/ 中，支持四种策略：

• autoCompact — 自动触发
• microCompact — 微量压缩
• reactiveCompact — 响应式压缩
• sessionMemoryCompact — 会话记忆压缩

---

5.3 工具系统 (Tools)

核心文件： Tool.ts (29KB) — 定义了最重要的接口

核心抽象 Tool<Input, Output, P>：

type Tool<Input, Output, P> = { // 标识 aliases?: string[] // 别名 searchHint?: string // 搜索提示 userFacingName(): string // 用户可见名称 // 核心方法 call(args, context, canUseTool, parentMessage, onProgress?) : Promise<ToolResult<Output>> // 执行工具 description(input, options) : Promise<string> // 给 Claude 的工具描述 // Schema readonly inputSchema: Input // JSON Schema 输入定义 // 状态 isEnabled(): boolean // 是否启用 isReadOnly(): boolean // 是否只读 needsPermissions(input): boolean // 是否需要权限确认 }

ToolUseContext — 工具执行上下文：

每次工具调用时传入，包含：

• commands — 可用命令列表
• model — 当前模型信息
• tools — 所有可用工具
• mcpClients — MCP 客户端连接
• abortController — 中断控制器
• fileStateCache — 文件状态缓存
• appState — 应用状态 getter/setter
• notification — 通知处理器
• fileHistoryState — 文件变更历史
• agentIdentity — Agent 身份信息

工具注册表 tools.ts：

getAllBaseTools() → Tool[] // 返回所有工具的主列表

通过 import 汇集 40+ 工具，特性开关的工具使用条件 require() 实现死代码消除。

工具分类：

类别	工具	说明
文件操作	FileReadTool, FileWriteTool, FileEditTool, GlobTool, GrepTool	读写搜索文件
Shell 执行	BashTool, PowerShellTool	执行 shell/PowerShell 命令
Web 访问	WebFetchTool, WebSearchTool	网络请求和搜索
任务管理	TaskCreateTool, TaskGetTool, TaskListTool, TaskUpdateTool, TaskStopTool, TaskOutputTool	后台任务生命周期
Agent 协作	AgentTool, SendMessageTool, TeamCreateTool, TeamDeleteTool	子 Agent 生成与通信
Git	EnterWorktreeTool, ExitWorktreeTool	Git worktree 管理
规划	EnterPlanModeTool, ExitPlanModeTool	计划模式切换
MCP	MCPTool	调用 MCP 服务器提供的外部工具
LSP	LSPTool	语言服务器协议集成
Jupyter	NotebookEditTool	Jupyter notebook 编辑
定时	ScheduleCronTool (CronCreate/Delete/List)	Cron 定时任务
技能	SkillTool	技能调用
配置	ConfigTool	配置管理
其他	TodoWriteTool, BriefTool, REPLTool, TungstenTool, ToolSearchTool	待办、摘要、REPL 等

每个工具的目录结构（以 BashTool 为例）：

tools/BashTool/ ├── index.ts # 工具实现（Tool 接口） ├── bashPermissions.ts # Bash 权限检查 ├── bashSecurity.ts # 安全策略 ├── pathValidation.ts # 路径校验 ├── readOnlyValidation.ts # 只读校验 └── sedValidation.ts # sed 命令校验

---

5.4 命令系统 (Commands)

注册表： commands.ts (25KB) — 导入 60+ 命令

命令类型：

type Command = PromptCommand | LocalCommand // PromptCommand: 生成 prompt 发给 Claude // LocalCommand: 本地直接执行，返回结果

关键命令一览：

命令	类型	说明
/init	Local	初始化项目（创建 CLAUDE.md）
/commit	Prompt	Git 提交
/commit-push-pr	Prompt	提交 + 推送 + 创建 PR
/review	Prompt	代码审查
/security-review	Prompt	安全审查
/compact	Local	上下文压缩
/config	Local	配置管理
/memory	Local	记忆文件管理
/mcp	Local	MCP 服务器管理
/plugin	Local	插件管理
/skills	Local	技能管理
/vim	Local	Vim 模式切换
/voice	Local	语音模式
/bridge	Local	远程控制桥
/tasks	Local	任务管理
/doctor	Local	诊断检查
/teleport	Local	会话传送
/ultraplan	Prompt	高级规划 (66KB)
/insights	Local	使用洞察 (115KB)
/install	Local	安装向导
/diff	Local	差异查看
/export	Local	会话导出

---

5.5 服务层 (Services)

目录： services/ — 36 个服务目录/文件

服务	核心文件	说明
API Client	api/claude.ts (125KB)	Anthropic API 客户端，消息发送、流式响应处理
MCP	mcp/client.ts (119KB), mcp/config.ts (51KB), mcp/auth.ts (88KB)	MCP 协议客户端，连接外部工具服务器，管理认证和权限
Compact	compact/compact.ts (60KB)	上下文压缩引擎，四种压缩策略
Analytics	analytics/	GrowthBook 特性开关 + 遥测数据收集
LSP	lsp/LSPClient.ts, lsp/LSPServerManager.ts	语言服务器协议集成，提供代码智能提示
OAuth	oauth/	OAuth 认证流程
Plugins	plugins/	插件加载和管理
Policy Limits	policyLimits/	基于策略的使用限制
Session Memory	SessionMemory/	会话记忆管理
Memory Extraction	extractMemories/	从对话中提取记忆
Team Memory Sync	teamMemorySync/	团队记忆同步
Settings Sync	settingsSync/	设置同步
Voice	voice.ts (17KB), voiceStreamSTT.ts (21KB)	语音输入输出、语音转文字
Token Estimation	tokenEstimation.ts	Token 计数估算
VCR	vcr.ts	录制/回放用于调试
Notifier	notifier.ts	系统通知
Tips	tips/	上下文提示
Prompt Suggestion	PromptSuggestion/	提示建议
Magic Docs	MagicDocs/	文档集成
Auto Dream	autoDream/	自动处理/梦境
Agent Summary	AgentSummary/	Agent 摘要生成

---

5.6 状态管理 (State)

目录： state/ — 6 个文件

state/ ├── AppStateStore.ts # 核心状态定义 + store 创建 ├── AppState.tsx # React Context Provider ├── store.ts # 简单的发布-订阅 store ├── onChangeAppState.ts # 状态变更副作用 ├── selectors.ts # 状态选择器 └── teammateViewHelpers.ts

AppState 核心状态字段：

interface AppState { messages: Message[] // 对话消息 toolPermissionContext // 工具权限上下文 models: ModelConfig[] // 可用模型 mcpClients: MCPClient[] // MCP 连接 agentDefinitions // Agent 定义 speculationState // 推测状态 taskStates: TaskState[] // 任务状态 fileHistoryState // 文件变更历史 attribution // 归属信息 settings // 设置 // ... 更多字段 }

状态管理方式：

┌─────────────────┐ ┌──────────────────┐ │ store.ts │◄────│ AppStateStore.ts │ │ createStore() │ │ 创建 store │ │ subscribe() │ │ 定义 AppState │ │ getState() │ └──────────────────┘ │ setState() │ └────────┬────────┘ │ useSyncExternalStore ▼ ┌─────────────────┐ │ AppState.tsx │ │ React Context │ │ Provider │ └─────────────────┘

---

5.7 权限系统 (Permissions)

核心目录： utils/permissions/ (26 个文件)

7 种权限模式：

模式	说明
default	每个工具调用都需用户确认
acceptEdits	自动接受文件编辑，其他仍需确认
bypassPermissions	跳过所有权限确认（危险模式）
plan	只读模式，不允许任何修改操作
dontAsk	不询问，直接拒绝需要权限的操作
auto	自动判断是否需要确认
bubble	向上冒泡到父 Agent 确认

核心文件：

文件	大小	说明
permissions.ts	52KB	权限检查逻辑
permissionSetup.ts	53KB	权限初始化和配置
filesystem.ts	62KB	文件系统权限（路径白名单/黑名单）
yoloClassifier.ts	52KB	"YOLO" 分类器——判断操作是否可以自动放行

权限检查流程：

工具调用请求 │ ▼ needsPermissions(input)? ──No──→ 直接执行 │ Yes │ ▼ 检查 PermissionMode ──bypassPermissions──→ 直接执行 │ ├──plan──→ 拒绝（只读模式） │ ├──dontAsk──→ 拒绝 │ ├──auto──→ YOLO 分类器判断 │ └──default/acceptEdits──→ 弹出确认 UI

---

5.8 UI 层

基于 Ink（React 终端渲染框架）的自定义 fork 构建。

Screens（顶层页面）

文件	大小	说明
REPL.tsx	895KB	主 REPL 界面（项目最大单文件）
Doctor.tsx	73KB	诊断页面
ResumeConversation.tsx	59KB	会话恢复页面

Components（140+ 组件）

关键组件：

组件	大小	说明
App.tsx	-	根组件
Messages.tsx	147KB	消息列表渲染
VirtualMessageList.tsx	148KB	虚拟滚动消息列表
MessageSelector.tsx	115KB	消息选择器
FullscreenLayout.tsx	84KB	全屏布局
Spinner.tsx	87KB	加载动画
Stats.tsx	152KB	统计信息展示
StatusLine.tsx	49KB	状态栏
LogSelector.tsx	200KB	日志选择器
TextInput.tsx	-	文本输入框
VimTextInput.tsx	-	Vim 模式输入框
Markdown.tsx	-	Markdown 渲染
Feedback.tsx	87KB	反馈 UI
ConsoleOAuthFlow.tsx	79KB	OAuth 认证流程 UI
ContextVisualization.tsx	76KB	上下文窗口可视化
StructuredDiff.tsx	-	Diff 可视化

组件子目录：agents/, design-system/, diff/, messages/, mcp/, permissions/, PromptInput/, Settings/, Spinner/, tasks/, teams/, wizard/

Hooks（85+ hooks）

Hook	大小	说明
useTypeahead	212KB	自动补全/类型提示系统
useReplBridge	115KB	远程 REPL 桥接
useVoiceIntegration	99KB	语音模式集成
useVoice	45KB	语音捕获/播放
useVirtualScroll	35KB	虚拟滚动
useCanUseTool	40KB	工具权限检查
useArrowKeyHistory	34KB	命令历史导航
useGlobalKeybindings	31KB	全局快捷键
useTextInput	17KB	文本输入处理
useVimInput	9.7KB	Vim 模式输入
usePasteHandler	10KB	粘贴处理
useRemoteSession	23KB	远程会话管理
useInboxPoller	34KB	消息收件箱轮询
useSwarmInitialization	-	多 Agent 初始化
useSwarmPermissionPoller	-	多 Agent 权限轮询

---

5.9 Ink 终端渲染器

目录： ink/ — 48 个文件（Ink 的自定义 fork）

文件	大小	说明
ink.tsx	251KB	主渲染器
render-node-to-output.ts	63KB	节点渲染到输出
screen.ts	49KB	屏幕管理
output.ts	26KB	输出处理
reconciler.ts	14KB	React reconciler
dom.ts	15KB	DOM 抽象层
selection.ts	34KB	文本选择
parse-keypress.ts	23KB	按键解析
styles.ts	20KB	样式系统
log-update.ts	27KB	增量日志更新

子目录：components/（Box, Text 等内置组件）、hooks/、layout/（Yoga 布局引擎）、events/、termio/（终端 I/O）

---

6. 特色子系统

6.1 Bridge — 远程控制桥

目录： bridge/ (31 文件)

将 Claude Code 连接到 claude.ai，实现远程控制：

文件	大小	说明
bridgeMain.ts	115KB	主桥接逻辑
replBridge.ts	100KB	REPL 桥接实现
remoteBridgeCore.ts	39KB	远程桥接核心
bridgeApi.ts	-	桥接 API
bridgeMessaging.ts	-	消息传输
sessionRunner.ts	-	会话执行器
types.ts	-	协议类型（WorkData, WorkResponse, SpawnMode）
jwtUtils.ts	-	JWT 认证
trustedDevice.ts	-	设备信任管理

SpawnMode（生成模式）：

• single-session — 单会话
• worktree — Git worktree 隔离
• same-dir — 同目录

6.2 Skills — 技能系统

目录： skills/

skills/ ├── loadSkillsDir.ts # 从目录加载技能 (34KB) ├── bundledSkills.ts # 内置技能定义 ├── mcpSkillBuilders.ts # MCP 技能构建器 └── bundled/ # 17 个内置技能 ├── batch.ts # 批量操作 ├── claudeApi.ts # Claude API 技能 ├── keybindings.ts # 快捷键配置 ├── loop.ts # 循环执行 ├── remember.ts # 记忆保存 ├── scheduleRemoteAgents.ts # 远程 Agent 调度 ├── simplify.ts # 简化 ├── skillify.ts # 技能化 ├── stuck.ts # 卡住时帮助 ├── updateConfig.ts # 配置更新 ├── verify.ts # 验证 ├── debug.ts # 调试 └── ...

6.3 Memory — 记忆系统

目录： memdir/

memdir/ ├── memdir.ts # 记忆目录管理 (21KB) ├── memoryTypes.ts # 记忆类型定义 (22KB) ├── paths.ts # 记忆文件路径 ├── teamMemPaths.ts # 团队记忆路径 ├── teamMemPrompts.ts # 团队记忆提示 ├── findRelevantMemories.ts # 记忆检索 ├── memoryScan.ts # 记忆扫描 └── memoryAge.ts # 记忆老化

记忆类型：

• user — 用户信息（角色、偏好、知识水平）
• feedback — 行为反馈（纠偏和确认）
• project — 项目上下文（进行中的工作、目标、截止日期）
• reference — 外部资源指针（Linear 项目、Grafana 看板等）

6.4 Vim 模式

目录： vim/

vim/ ├── motions.ts # 光标移动 (w, b, e, 0, $, etc.) ├── operators.ts # 操作符 (d, c, y, etc.) ├── textObjects.ts # 文本对象 (iw, aw, i", etc.) ├── transitions.ts # 模式转换 └── types.ts # 类型定义

6.5 Swarm — 多 Agent 协作

目录： utils/swarm/ (16 文件)

swarm/ ├── inProcessRunner.ts # 进程内运行器 (53KB) ├── permissionSync.ts # 权限同步 (26KB) ├── backends/ # 后端实现 └── teammate management # 队友管理

6.6 Coordinator — 多 Agent 编排

目录： coordinator/

coordinatorMode.ts (19KB) — 编排模式，协调多个 Agent 协同工作。

6.7 Plugins — 插件系统

目录： plugins/ + utils/plugins/ (46 文件)

plugins/ ├── builtinPlugins.ts # 内置插件定义 └── bundled/ # 内置插件实现 utils/plugins/ ├── plugin loader # 插件加载器 ├── schemas # 插件 schema ├── CLI commands # 插件 CLI 命令 └── marketplace # 插件市场

6.8 Keybindings — 快捷键系统

目录： keybindings/ (14 文件)

keybindings/ ├── KeybindingContext.tsx # React Context (26KB) ├── KeybindingProviderSetup.tsx # Provider 设置 (41KB) ├── defaultBindings.ts # 默认绑定 ├── loadUserBindings.ts # 用户自定义绑定 ├── schema.ts # Schema 校验 ├── parser.ts # 按键组合解析 ├── match.ts # 按键匹配 ├── resolver.ts # 冲突解决 └── validate.ts # 校验

6.9 Buddy — 伴侣精灵

目录： buddy/

buddy/ ├── CompanionSprite.tsx # 精灵组件 (45KB) ├── sprites.ts # 精灵定义 └── types.ts # 类型

6.10 Voice — 语音模式

voice/ └── voiceModeEnabled.ts # 语音模式开关 services/ ├── voice.ts # 语音服务 (17KB) ├── voiceStreamSTT.ts # 流式语音转文字 (21KB) └── voiceKeyterms.ts # 关键词

---

7. 关键数据流

7.1 用户输入 → 响应输出

用户在终端输入 │ ▼ TextInput 组件 (components/TextInput.tsx) │ ▼ useTextInput hook (hooks/useTextInput.ts) │ ▼ useTypeahead hook (hooks/useTypeahead.tsx) ← 自动补全 │ ▼ REPL.tsx 处理输入 │ ▼ QueryEngine.ts 构建查询 │ - 构建 system prompt (constants/prompts.ts) │ - 加载消息历史 │ - 注入 CLAUDE.md 上下文 (utils/claudemd.ts) │ - 设置工具列表 │ ▼ query.ts 执行查询 │ - 调用 services/api/claude.ts → Anthropic API │ - 处理流式响应 │ ├─→ 文本响应 → Messages.tsx 渲染 │ └─→ 工具调用 │ ▼ 权限检查 (utils/permissions/) │ ▼ Tool.call() 执行 │ ▼ 工具结果 → 反馈给 API → 继续循环

7.2 启动初始化流

cli.tsx → init.ts (配置/遥测/认证) → main.tsx (参数解析) → setup.ts (会话初始化) → bootstrap/state.ts (全局状态) → tools.ts (注册工具) → commands.ts (注册命令) → replLauncher.tsx (启动 UI) → App.tsx → REPL.tsx

7.3 MCP 工具集成流

MCP 配置 (settings.json) │ ▼ services/mcp/config.ts 解析配置 │ ▼ services/mcp/client.ts 连接 MCP 服务器 │ ▼ MCP 工具注册到工具列表 │ ▼ Claude 可通过 MCPTool 调用外部工具

---

8. 核心类型定义

Tool (Tool.ts)

type Tool<Input, Output, P> = { aliases?: string[] searchHint?: string call(args, context, canUseTool, parentMessage, onProgress?) : Promise<ToolResult<Output>> description(input, options): Promise<string> readonly inputSchema: Input isEnabled(): boolean isReadOnly(): boolean userFacingName(): string needsPermissions(input): boolean }

PermissionMode (types/permissions.ts)

type PermissionMode = | 'acceptEdits' | 'bypassPermissions' | 'default' | 'dontAsk' | 'plan' | 'auto' | 'bubble'

Command (types/command.ts)

type Command = PromptCommand | LocalCommand // PromptCommand: 基于技能，生成 prompt // LocalCommand: 本地执行，有 call() 方法

TaskState (tasks/types.ts)

type TaskState = | LocalShellTaskState | LocalAgentTaskState | RemoteAgentTaskState | InProcessTeammateTaskState | LocalWorkflowTaskState | MonitorMcpTaskState | DreamTaskState

SessionId / AgentId (types/ids.ts)

// 品牌类型，防止混用 type SessionId = string & { __brand: 'SessionId' } type AgentId = string & { __brand: 'AgentId' }

Bridge Types (bridge/types.ts)

type SpawnMode = 'single-session' | 'worktree' | 'same-dir' interface WorkData { /* 工作数据 */ } interface WorkResponse { /* 工作响应 */ } interface WorkSecret { /* 工作密钥 */ }

---

9. 模块依赖关系

┌──────────┐ │ Entrypoints │ └─────┬────┘ │ ┌─────▼────┐ │ Screens │ └─────┬────┘ │ ┌───────────┼───────────┐ │ │ │ ┌─────▼────┐ ┌───▼───┐ ┌─────▼────┐ │ Components│ │ Hooks │ │ Commands │ └─────┬────┘ └───┬───┘ └─────┬────┘ │ │ │ └──────────┼───────────┘ │ ┌──────────▼──────────┐ │ Tools + Commands │ └──────────┬──────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ┌─────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ Services │ │ State │ │ Constants │ └─────┬─────┘ └──────┬──────┘ └─────────────┘ │ │ └───────┬───────┘ │ ┌───────▼───────┐ │ Utils │ └───────┬───────┘ │ ┌───────▼───────┐ │ Types │ └───────┬───────┘ │ ┌───────▼───────┐ │ Bootstrap │ └───────────────┘

关键依赖链：

• bootstrap/state.ts → 被几乎所有模块依赖（全局单例）
• utils/permissions/ → 被 Tools（检查权限）和 Components（UI 展示）共同依赖
• services/api/claude.ts → 被 QueryEngine 和 Tools 依赖
• services/mcp/ → 连接外部 MCP 服务器，工具列表动态扩展
• Tool.ts → 被所有 40+ 工具实现依赖
• constants/prompts.ts → 被 QueryEngine 依赖（构建 system prompt）

特性开关机制：

使用 bun:bundle 的 feature() 函数进行编译时特性开关，支持死代码消除：

• COORDINATOR_MODE — 多 Agent 编排
• KAIROS — Kairos 助手模式
• VOICE_MODE — 语音模式
• BRIDGE_MODE — 远程桥接模式
• 内部/外部构建的差异化

---

10. 学习路线图

第一阶段：理解核心概念

步骤	文件	学习目标
1	entrypoints/cli.tsx	理解启动流程，快速路径设计
2	Tool.ts	最重要的接口，理解工具抽象
3	tools.ts	工具注册表，了解有哪些工具
4	types/permissions.ts	权限模型

第二阶段：理解核心循环

步骤	文件	学习目标
5	QueryEngine.ts	查询编排——如何组装请求
6	query.ts	查询执行——如何与 API 交互
7	services/api/claude.ts	API 客户端实现
8	constants/prompts.ts	System prompt 构建（Claude Code 的"性格"）

第三阶段：深入工具实现

步骤	文件	学习目标
9	tools/FileReadTool/	最简单的工具之一，理解 Tool 接口实现
10	tools/BashTool/	最复杂的工具之一，理解安全策略
11	tools/AgentTool/	子 Agent 生成，理解多 Agent 架构
12	tools/MCPTool/	MCP 集成

第四阶段：理解 UI 架构

步骤	文件	学习目标
13	state/AppStateStore.ts	全局状态结构
14	screens/REPL.tsx (前 200 行)	主界面如何组装
15	components/Messages.tsx	消息如何渲染
16	ink/ink.tsx (前 100 行)	自定义 Ink 渲染器

第五阶段：探索子系统

根据兴趣选择深入：

• 权限系统 → utils/permissions/
• MCP → services/mcp/
• 技能系统 → skills/
• 记忆系统 → memdir/
• 多 Agent → utils/swarm/, coordinator/
• 插件系统 → plugins/, utils/plugins/
• Bridge → bridge/
• Voice → voice/, services/voice.ts

---

附录 A: 目录结构速查表

src/ ├── entrypoints/ # 启动入口 (cli, init, mcp, sdk) ├── screens/ # 顶层页面 (REPL, Doctor, Resume) ├── components/ # UI 组件 (140+) ├── hooks/ # React hooks (85+) ├── commands/ # 斜杠命令 (60+) ├── tools/ # Claude 工具 (40+) ├── services/ # 后端服务 (36) ├── state/ # 状态管理 ├── types/ # 类型定义 ├── utils/ # 工具函数 (300+) ├── constants/ # 常量定义 ├── ink/ # 自定义 Ink 渲染器 ├── bridge/ # 远程控制桥 ├── skills/ # 技能系统 ├── memdir/ # 记忆系统 ├── vim/ # Vim 模式 ├── voice/ # 语音模式 ├── remote/ # 远程会话 ├── server/ # 直连服务器 ├── cli/ # CLI 非交互模式 ├── coordinator/ # 多 Agent 编排 ├── assistant/ # Kairos 助手 ├── buddy/ # 伴侣精灵 ├── tasks/ # 后台任务 ├── plugins/ # 插件系统 ├── keybindings/ # 快捷键系统 ├── query/ # 查询 hooks ├── schemas/ # JSON Schema ├── migrations/ # 数据迁移 ├── bootstrap/ # 全局启动状态 ├── native-ts/ # 原生 TS 绑定 ├── upstreamproxy/ # 上游代理 ├── outputStyles/ # 输出样式 ├── moreright/ # 右侧面板 │ ├── main.tsx # 主启动模块 (803KB) ├── query.ts # 查询执行引擎 (68KB) ├── QueryEngine.ts # 查询编排引擎 (46KB) ├── Tool.ts # 核心 Tool 接口 (29KB) ├── tools.ts # 工具注册表 (17KB) ├── commands.ts # 命令注册表 (25KB) ├── context.ts # 上下文构建 ├── setup.ts # 会话设置 ├── history.ts # 对话历史 ├── cost-tracker.ts # 成本追踪 ├── replLauncher.tsx # REPL 启动器 ├── interactiveHelpers.tsx # 交互辅助 ├── dialogLaunchers.tsx # 对话框启动器 └── ink.ts # Ink 根管理

---

附录 B: 关键文件体积排行

排名	文件	大小	说明
1	screens/REPL.tsx	895KB	主 REPL 界面
2	main.tsx	803KB	主启动模块
3	tools/AgentTool/index.ts	233KB	Agent 工具
4	ink/ink.tsx	251KB	Ink 渲染器
5	hooks/useTypeahead.tsx	212KB	自动补全
6	cli/print.ts	212KB	CLI 输出
7	components/LogSelector.tsx	200KB	日志选择器
8	utils/messages.ts	193KB	消息处理
9	utils/sessionStorage.ts	180KB	会话存储
10	utils/teleport.tsx	175KB	会话传送
11	utils/hooks.ts	159KB	Hook 引擎
12	components/Stats.tsx	152KB	统计展示
13	components/VirtualMessageList.tsx	148KB	虚拟消息列表
14	components/Messages.tsx	147KB	消息渲染
15	services/api/claude.ts	125KB	API 客户端
16	services/mcp/client.ts	119KB	MCP 客户端
17	commands/insights.ts	115KB	使用洞察
18	hooks/useReplBridge.tsx	115KB	REPL 桥接
19	components/MessageSelector.tsx	115KB	消息选择器
20	bridge/bridgeMain.ts	115KB	桥接主逻辑

这些大文件通常是功能最丰富、最值得深入研究的模块。