深入拆解 Claude Code 源码（八）：7 万行 TypeScript 的收尾拼图 —— 状态管理、技能、Vim 与类型系统

不吃茄子的汪

217人浏览 · 2026-07-03 10:15:20

不吃茄子的汪 · 2026-07-03 10:15:20 发布

深入拆解 Claude Code 源码（八）：7 万行 TypeScript 的收尾拼图 —— 状态管理、技能、Vim 与类型系统

系列：深入拆解 Claude Code 源码 | 第 8 篇 / 共 8 篇（完结篇）
关键词：Claude Code, 状态管理, React Hooks, 技能系统, Vim 模式, 类型系统, 源码分析

开篇：最后一块拼图

前 7 篇我们拆解了 Claude Code 的核心模块：CLI 启动、对话引擎、命令系统、工具系统、服务层、渲染引擎。但还有一个问题没回答：

这些模块是怎么"粘合"在一起的？

答案是：状态管理、React Hooks、技能系统、Vim 模式、任务系统、桥接系统、类型系统…… 这些"基础设施"模块像水泥一样，把所有砖块粘合成一个完整的建筑。

这是系列的最后一篇。让我们把这些剩余模块逐个拆解，然后给出完整的架构总结。

一、状态管理：极简的 34 行 Store

Claude Code 的状态管理出乎意料地简单。它没有用 Zustand（虽然文档中提到过），而是实现了一个 34 行的极简 Store。让我们逐行读完整源码：

// src/state/store.ts — 完整 34 行核心代码
function createStore<T>(initialState: T, onChange?: (next: T, prev: T) => void) {
  let state = initialState                          // 模块级闭包，非 React state
  const listeners = new Set<() => void>()           // Set 而非数组，O(1) 删除

  return {
    getState: () => state,                          // 零拷贝直接返回引用

    setState: (updater: T | ((prev: T) => T)) => {
      const prev = state                            // 保存旧引用
      state = typeof updater === 'function'         // 支持函数式更新
        ? (updater as (prev: T) => T)(prev)
        : updater
      if (Object.is(state, prev)) return            // 浅比较：同一引用直接跳过
      onChange?.(state, prev)                       // 副作用先于 UI 通知
      listeners.forEach(l => l())                   // 批量通知所有订阅者
    },

    subscribe: (listener: () => void) => {
      listeners.add(listener)                       // 添加订阅
      return () => { listeners.delete(listener) }   // 返回取消订阅函数
    },
  }
}

5 个关键设计决策：

闭包而非类：state 是模块级变量，通过闭包捕获，没有 this 绑定问题
Object.is 浅比较：如果 setState 传入的值与当前值是同一引用，直接 return，不触发任何通知。这避免了 setState({}) 这种"创建新对象但内容相同"导致的无意义重渲染
onChange 先于 listeners：副作用回调在 UI 订阅者之前执行。这确保了当 React 组件重渲染时，AppState 已经是最新状态，不会出现"UI 先更新、状态后更新"的时序问题
Set 而非数组：Set.delete() 是 O(1)，而数组的 splice 是 O(n)。在频繁订阅/取消的场景下性能更好
updater 函数模式：setState(prev => newState) 避免了闭包捕获旧值的经典 React 陷阱

AppState：全局状态结构

AppStateStore.ts 定义了应用的全局状态，使用 DeepImmutable<T> 包装确保不可变性：

// DeepImmutable<T> — 递归冻结所有属性为 readonly
type DeepImmutable<T> = T extends (infer U)[]
  ? ReadonlyArray<DeepImmutable<U>>
  : T extends Map<infer K, infer V>
    ? ReadonlyMap<DeepImmutable<K>, DeepImmutable<V>>
    : T extends Set<infer U>
      ? ReadonlySet<DeepImmutable<U>>
      : T extends object
        ? { readonly [K in keyof T]: DeepImmutable<T[K]> }
        : T

完整的 AppState 类型包含以下字段：

字段	类型	说明
`settings`	`DeepImmutable<SettingsJson>`	用户/项目/策略设置（5 源合并）
`mainLoopModel`	`string \| null`	当前使用的 AI 模型（如 `claude-sonnet-4-20250514`）
`tasks`	`TaskState[]`	后台任务列表（7 种任务类型联合）
`speculationState`	`SpeculationState`	推测执行状态（`idle` / `active` + abort 控制器）
`mcpClients`	`MCPServerConnection[]`	MCP 连接列表（动态发现的外部工具）
`activeOverlays`	`Set<string>`	活跃覆盖层集合（Escape 键逐个关闭）
`toolPermissionContext`	`ToolPermissionContext`	工具权限上下文（当前权限模式 + 规则）
`footerItems`	`FooterItem[]`	底部栏项目（tasks/tmux/bagel/teams/bridge/companion）
`verbose`	`boolean`	详细输出模式
`statusLineText`	`string`	状态栏文本
`expandedView`	`boolean`	展开视图
`isBriefOnly`	`boolean`	仅简要模式
`promptSuggestion`	`PromptSuggestion`	提示建议（Ghost text）

关键枚举：

// 推测执行边界 — 决定何时可以"猜"下一步
type CompletionBoundary = 'complete' | 'bash' | 'edit' | 'denied_tool'

// 推测状态 — active 时包含中止控制器
type SpeculationState = { state: 'idle' } | {
  state: 'active'
  id: string
  abort: AbortController
  startTime: number
}

// 底部栏项目类型
type FooterItem = 'tasks' | 'tmux' | 'bagel' | 'teams' | 'bridge' | 'companion'

React 集成：useSyncExternalStore 桥接

AppState.tsx 是 Provider 层级的入口，它做了三件关键的事：

// AppState.tsx — Provider 嵌套顺序
<HasAppStateContext>        // 标记"AppState 已初始化"
  <AppStoreContext>         // 暴露 store 实例
    <MailboxProvider>       // 团队通信邮箱（useMemo 单例）
      <VoiceProvider>       // 语音状态（feature('VOICE_MODE') 条件加载）
        {children}
      </VoiceProvider>
    </MailboxProvider>
  </AppStoreContext>
</HasAppStateContext>

关键实现细节：

// 创建 store，onChange 回调处理副作用
const store = createStore(initialState, (next, prev) => {
  // 1. 设置文件变化时重新加载
  // 2. Bypass permissions mode 检查
  // 3. 推测状态变更通知
})

// 桥接到 React — 这是整个状态系统的核心
function useAppState<T>(selector: (state: AppState) => T): T {
  return useSyncExternalStore(
    store.subscribe,                    // 订阅函数
    () => selector(store.getState())    // 快照函数
  )
}

function useSetAppState() {
  return store.setState                 // 直接返回 setState 引用
}

function useAppStateStore() {
  return store                          // 返回原始 store 实例
}

useSyncExternalStore 是 React 18 提供的 API，专门用于将外部 store 桥接到 React。它保证了并发模式下的撕裂一致性（tear-free）。

二、Context 模块：6 个独立的上下文系统

除了核心 AppState，Claude Code 还有 6 个独立的 Context 模块，各自管理一个维度的状态：

模块	路径	说明
fpsMetrics	`context/fpsMetrics.tsx`	FPS 追踪，监控渲染性能，通过 `useFpsMetrics()` 获取
mailbox	`context/mailbox.tsx`	团队通信邮箱，Leader 和 Teammate 之间的消息传递，`useMemo` 单例
overlay	`context/overlayContext.tsx`	覆盖层协调，`useRegisterOverlay(id, enabled?)` 自动注册/卸载，Escape 按注册顺序逐个关闭
voice	`context/voice.tsx`	语音状态（`feature('VOICE_MODE')` 条件加载），管理 idle/recording/processing 三态
modal	`context/modalContext.tsx`	模态对话框，提供 `useIsInsideModal()`、`useModalOrTerminalSize(fallback)`、`useModalScrollRef()`
notifications	`context/notifications.tsx`	优先级通知队列，4 级优先级（immediate/high/medium/low），immediate 可抢占当前显示

通知系统核心类型：

// src/context/notifications.tsx
const PRIORITIES = { immediate: 0, high: 1, medium: 2, low: 3 }
const DEFAULT_TIMEOUT_MS = 8000  // 8 秒自动消失

type BaseNotification = {
  key: string                    // 去重 key
  invalidates?: string[]         // 使其他通知失效
  priority: Priority
  timeoutMs?: number
  fold?: boolean                 // 合并同 key 通知
}

三、selectors.ts：状态选择器

// src/state/selectors.ts

// 获取当前查看的队友任务
function getViewedTeammateTask(appState: AppState)
  -> InProcessTeammateTaskState | undefined

// 输入路由 — 决定用户的输入发送给谁
function getActiveAgentForInput(appState)
  -> { type: 'leader' }                          // 默认发给 leader
  | { type: 'viewed', taskId: string }            // 查看队友时发给队友
  | { type: 'named_agent', agentName: string }    // local_agent 任务发给指定 agent

输入路由逻辑是多 Agent 模式的关键：当你正在查看某个 Teammate 的输出时，你的输入会自动路由到那个 Teammate，而不是 Leader。

四、80+ React Hooks：UI 的"神经系统"

src/hooks/ 目录包含 80+ 个自定义 Hooks。让我们深入几个最核心的：

useTextInput：终端文本输入的瑞士军刀

// src/hooks/useTextInput.ts
type UseTextInputProps = {
  value: string
  onChange: (value: string) => void
  onSubmit: () => void
  onExit: () => void
  onExitMessage: string
  onHistoryUp: () => void
  onHistoryDown: () => void
  multiline: boolean
  columns: number
  onImagePaste: (data: ImageData) => void
  inputFilter: (input: string) => string | null
  inlineGhostText: string           // Ghost text（灰色提示）
}

4 大核心特性：

Kill Ring（剪切环）：类似 Emacs 的剪切/粘贴系统

KILL_RING_MAX_SIZE = 10
pushToKillRing(text, direction)  // 连续同方向剪切会累积
getLastKill()                    // 获取最后剪切
yankPop()                        // 循环粘贴（Ctrl+Y 后连续 yank）

Grapheme 感知：正确处理 Unicode 字素簇（如 emoji 👨‍👩‍👧‍👦、CJK 字符）
```
// 光标移动基于字素而非 UTF-16 码元
// "你好"[0] 是 "你"，不是半个字符
```
双击检测：useDoublePress hook 检测快速双击
```
// 双击 Enter 提交，双击 Escape 退出
```
修饰键检测：isModifierPressed 区分 Ctrl/Meta/Alt/Shift

useVimInput：Vim 状态机的 React 桥梁

// src/hooks/useVimInput.ts — 在 useTextInput 之上
type VimMode = 'INSERT' | 'NORMAL'

type VimState =
  | { mode: 'INSERT'; insertedText: string }    // 跟踪插入的文本（用于 . 重复）
  | { mode: 'NORMAL'; command: VimCommand }      // 当前正在构建的命令

// PersistentState — 跨模式切换保持的状态
type PersistentState = {
  register: string           // 寄存器（剪贴板）
  lastChange: ChangeRecord   // 上次修改记录（用于 `.` 重复）
  lastFind: FindRecord       // 上次查找（用于 `;` 和 `,`）
}

useCanUseTool：工具权限门控

这是 Claude Code 中最复杂的 Hook。它决定每个工具调用是否被允许：

// src/hooks/useCanUseTool.tsx
// 流程：
// 1. 检查 PermissionMode（plan/auto/bypass/default）
// 2. 检查权限规则（用户/项目/策略设置）
// 3. 如果需要审批 → 交互式确认 / Hook 审批 / 分类器自动审批
// 4. 记录决策日志
// 5. 返回 allow/deny + 可选的用户消息

useSettings：响应式设置读取

// src/hooks/useSettings.ts
// 一行代码，但背后是 5 层设置合并
function useSettings() {
  return useAppState(s => s.settings)
  // 返回 ReadonlySettings（DeepImmutable 包装）
}

useSettingsChange：磁盘文件变化监听

// src/hooks/useSettingsChange.ts
// 订阅 settingsChangeDetector
// 变化时调用 getSettings_DEPRECATED() 获取新设置
// 缓存已由 notifier 重置，避免 N 路抖动

useMergedTools：工具池合并

// src/hooks/useMergedTools.ts
function useMergedTools(initialTools, mcpTools, toolPermissionContext) {
  return useMemo(() => {
    const assembled = assembleToolPool(initialTools, mcpTools)
    return mergeAndFilterTools(initialTools, assembled, mode)
  }, [initialTools, mcpTools, toolPermissionContext])
}
// 合并内置工具 + 启动时 MCP 工具 + 动态发现的 MCP 工具
// 去重、协调器过滤、权限上下文绑定

useArrowKeyHistory：箭头键历史浏览

// src/hooks/useArrowKeyHistory.tsx
// 上下箭头键浏览命令历史
// 与 useTextInput 的 onHistoryUp/onHistoryDown 配合

useSearchInput：搜索输入

// src/hooks/useSearchInput.ts
// 处理搜索模式下的键盘输入
// 支持增量搜索、高亮匹配

权限系统 Hooks：PermissionContext 工厂

// src/hooks/toolPermission/PermissionContext.ts
function createPermissionContext(
  tool, input, toolUseContext, assistantMessage,
  toolUseID, setToolPermissionContext, queueOps?
) {
  return {
    // 日志记录
    logDecision(),           // 记录权限决策日志
    logCancelled(),          // 记录取消事件

    // 权限持久化
    persistPermissions(),    // 持久化权限更新到设置文件

    // 自动审批
    tryClassifier(),         // AI 分类器自动审批（BASH_CLASSIFIER feature flag）
    runHooks(),              // 执行权限请求 hooks（用户自定义 shell 脚本）

    // 决策构建
    buildAllow() / buildDeny(),  // 构建允许/拒绝决策

    // 用户交互
    handleUserAllow(),       // 处理用户允许（可设为 permanent）
    handleHookAllow(),       // 处理 hook 允许

    // 队列操作
    pushToQueue() / removeFromQueue() / updateQueueItem(),
  }
}

三种审批来源：

// 审批来源
type ApprovalSource =
  | { type: 'hook'; permanent?: boolean }      // Hook 程序化审批
  | { type: 'user'; permanent: boolean }        // 用户手动审批（permanent 写入设置）
  | { type: 'classifier' }                      // AI 分类器自动审批

// 拒绝来源
type DenialSource =
  | { type: 'hook' }                            // Hook 拒绝
  | { type: 'user_abort' }                      // 用户中止（Ctrl+C）
  | { type: 'user_reject'; hasFeedback: boolean } // 用户拒绝（可带反馈）

三种权限处理器：

interactiveHandler.ts — 主 Agent 的交互式权限流程（推送确认队列 + hooks/分类器竞速）
coordinatorHandler.ts — 协调器模式的权限处理
swarmWorkerHandler.ts — 蜂群工作者模式的权限处理

统一建议系统：generateUnifiedSuggestions

当你在输入框里输入 @ 时，会弹出一个建议列表，包含文件、MCP 资源、Agent。这由 unifiedSuggestions.ts 处理：

// src/hooks/unifiedSuggestions.ts
const MAX_UNIFIED_SUGGESTIONS = 15
const DESCRIPTION_MAX_LENGTH = 60

function generateUnifiedSuggestions(
  query: string,
  mcpResources: McpResourceSuggestionSource[],
  agents: AgentSuggestionSource[],
  showOnEmpty?: boolean
) {
  // 1. 文件建议 — 使用 Rust/nucleo 评分引擎
  //    nucleo 是一个高性能模糊匹配库（Rust 编写，编译为 WASM）
  //    评分 0-1，越低越好
  const fileSuggestions = nucleoScore(query)

  // 2. MCP 资源建议 — 使用 Fuse.js 模糊匹配
  const mcpSuggestions = fuseScore(mcpResources)

  // 3. Agent 建议 — 同样使用 Fuse.js
  const agentSuggestions = fuseScore(agents)

  // 4. 合并、排序、截断
  return mergeAndSort([
    ...fileSuggestions,
    ...mcpSuggestions,
    ...agentSuggestions
  ]).slice(0, MAX_UNIFIED_SUGGESTIONS)  // 最多 15 个
}

评分机制的两套引擎：

nucleo（Rust/WASM）：用于文件路径匹配，性能极高，适合大量文件的实时过滤
Fuse.js（JavaScript）：用于 MCP 资源和 Agent 的模糊匹配，支持更灵活的匹配策略

五、技能系统：用户自定义的"超能力"

技能（Skills）是 Claude Code 的扩展机制之一。它让用户可以通过 Markdown 文件定义自己的斜杠命令。

两类技能

类型	来源	加载时机
内置技能	编译进二进制	启动时
磁盘技能	文件系统扫描	运行时

技能定义格式

# .claude/skills/my-skill.md
---
name: my-skill
description: 这是一个自定义技能
whenToUse: 当用户需要做 X 时使用
allowedTools: [Read, Edit, Bash]
model: sonnet
context: fork              # fork = 独立上下文，inline = 嵌入当前对话
---

## 指令

你是一个专门做 X 的专家。请按照以下步骤：
1. 先分析...
2. 然后执行...

内置技能的完整类型：

// src/skills/bundledSkills.ts
type BundledSkillDefinition = {
  name: string
  description: string
  aliases: string[]           // 别名（如 /compact 的别名 /c）
  whenToUse: string           // AI 判断何时使用此技能
  allowedTools?: string[]     // 限制可用工具
  model?: string              // 指定模型
  hooks?: HookDefinition[]    // 技能级别的 hooks
  context: 'inline' | 'fork' // inline 嵌入当前对话，fork 创建新对话
  files?: Record<string, string>  // 附带文件（解压到临时目录）
}

技能来源（6 种）

commands_DEPRECATED → 旧版命令目录（向后兼容）
skills              → 技能目录（.claude/skills/）
plugin              → 插件技能（npm 包）
managed             → 托管技能（远程配置）
bundled             → 内置技能（编译进二进制）
mcp                 → MCP 服务器技能（动态注册）

MCP 技能构建器：打破循环依赖

MCP 技能通过一个巧妙的"写入一次注册"模式打破循环依赖：

// src/skills/mcpSkillBuilders.ts
// 问题：MCP 服务层需要创建技能，但技能系统需要 MCP 工具
// 解决：写入一次注册模式（Write-once Registry）

// 注册端（MCP 服务层初始化时调用）
registerMCPSkillBuilders(builder)

// 读取端（技能加载时调用）
const builders = getMCPSkillBuilders()

// 这避免了 Bun 打包二进制文件的循环导入问题
// 因为 register 和 get 之间没有直接的 import 关系

六、Vim 模式：完整的状态机实现

Claude Code 的 Vim 模式不是简单的按键映射，而是一个 完整的 Vim 状态机。

状态图

INSERT ←→ NORMAL
              ↓
         CommandState 状态机:
         ┌─────────────────────────────────────────┐
         │  idle ──→ count ──→ operator            │
         │    │                  │                  │
         │    ├──→ find          ├──→ count         │
         │    │                  │                  │
         │    ├──→ g ──→ ...    ├──→ find           │
         │    │                  │                  │
         │    ├──→ replace      ├──→ textObj        │
         │    │                  │                  │
         │    └──→ indent       └──→ (execute)      │
         └─────────────────────────────────────────┘

操作符子状态与动作：

当进入 operator 状态后，还可以继续输入数字前缀（d3w）、查找动作（df"）、文本对象（diw）。

动作解析：resolveMotion(key, cursor, count) → Position，支持 h/j/k/l、w/b/e、W/B/E、0/^/$、f/F/t/T、gg/G 共 15+ 种动作。

8 种操作符：d（删除，如 dw/dd/diw）、c（修改，如 cw/cc/ci"）、y（复制）、>/<（缩进）、~（大小写切换）、r（替换字符）、J（合并行）。

// src/vim/operators.ts
type OperatorContext = {
  cursor: Position; text: string
  setText: Function; setOffset: Function; enterInsert: Function
  getRegister: Function; setRegister: Function
  getLastFind: Function; setLastFind: Function
  recordChange: Function   // 记录修改（用于 . 重复）
}

// 操作符 + 动作组合：executeOperatorMotion(op, motion, count, ctx)
// 1. 解析动作得到范围 [start, end]  2. 应用操作符  3. 记录到 lastChange
// 操作符 + 查找：executeOperatorFind(op, findType, char, count, ctx)

持久化状态

// src/vim/types.ts
type PersistentState = {
  register: string            // 寄存器（剪贴板内容）
  lastChange: ChangeRecord    // 上次修改记录（用于 `.` 重复命令）
  lastFind: FindRecord        // 上次查找（用于 `;` 重复、`,` 反向）
}

// INSERT 模式跟踪 insertedText
// 当用户在 INSERT 模式输入 "hello" 然后按 Escape
// insertedText = "hello"
// 按 . 会重新插入 "hello"

七、任务系统：7 种后台任务

src/tasks/ 定义了 7 种后台任务类型，共享停止/注册/更新框架。

// src/tasks/types.ts
type TaskState =
  | LocalShellTaskState
  | LocalAgentTaskState
  | RemoteAgentTaskState
  | InProcessTeammateTaskState
  | LocalWorkflowTaskState
  | MonitorMcpTaskState
  | DreamTaskState

type BackgroundTaskState = TaskState  // 同类型联合

各任务类型详解

任务类型	说明	典型场景
`LocalShellTask`	本地 Shell 命令	`run_in_background`，kind 为 `bash` 或 `monitor`
`LocalAgentTask`	本地子 Agent	`src/tools/AgentTool` 创建的子任务
`RemoteAgentTask`	远程 Agent	通过基础设施运行的 Agent
`InProcessTeammateTask`	进程内队友	蜂群模式中的 Teammate
`LocalWorkflowTask`	本地工作流	多步骤工作流
`MonitorMcpTask`	MCP 监控	监听 MCP 服务器事件
`DreamTask`	梦境任务	后台记忆整合（KAIROS feature flag），跟踪 `sessionsReviewing`、`filesTouched`、`turns`

共享框架

// src/tasks/stopTask.ts — 查找 → 验证运行中 → 通过任务实现 kill
function stopTask(taskId: string, context): void
class StopTaskError { code: 'not_found' | 'not_running' | 'unsupported_type' }

// src/tasks/pillLabel.ts — 底部 Pill 标签
function getPillLabel(tasks: TaskState[]): string
// → "1 shell" / "1 team" / "1 cloud session" / "2 shells, 1 agent"
// ultraplan 状态使用 DIAMOND_FILLED / DIAMOND_OPEN 指示器

八、桥接系统：远程控制基础设施

src/bridge/ 实现了 Claude Code 的远程控制能力（Claude Code on the web）。

核心组件（6 个文件）

文件	说明
`bridgeMain.ts`	主桥接循环（API 客户端 + 容量唤醒 + 会话生成 + Token 刷新）
`bridgeSession.ts`	会话生命周期管理
`bridgeAuth.ts`	JWT 认证和 Token 管理
`bridgeCapacity.ts`	容量唤醒和资源管理
`bridgePolling.ts`	指数退避轮询
`replBridge.ts`	REPL 桥接句柄

退避配置与会话模式

// src/bridge/bridgeMain.ts — 指数退避配置
DEFAULT_BACKOFF = {
  connInitialMs: 2000,             // 初始 2 秒
  connCapMs: 120000,               // 最大 2 分钟（指数退避上限）
  connGiveUpMs: 600000,            // 10 分钟后放弃重试
}

// 会话模式
type SpawnMode = 'single-session' | 'worktree' | 'same-dir'

// src/bridge/replBridge.ts — REPL 桥接句柄（7 个方法）
type ReplBridgeHandle = {
  writeMessages: Function; writeSdkMessages: Function
  sendControlRequest: Function; sendControlResponse: Function
  sendControlCancelRequest: Function; sendResult: Function; teardown: Function
}
// 内部组件：HybridTransport（混合传输层）、FlushGate（刷新门控）、BoundedUUIDSet（去重）

九、按键绑定系统：18 个上下文

src/keybindings/ 实现了完整的按键绑定系统。

18 个上下文

Global, Chat, Autocomplete, Confirmation, Help, Transcript,
HistorySearch, Task, ThemePicker, Settings, Tabs, Attachments,
Footer, MessageSelector, DiffDialog, ModelPicker, Select, Plugin

每个上下文都有独立的按键映射。例如 Chat 上下文中的 Enter 是提交，而 Autocomplete 上下文中的 Enter 是选择补全项。

和弦按键支持

支持 Ctrl+K Ctrl+U 这样的和弦按键（Chord），带 pending 状态：

// src/keybindings/resolver.ts
function resolveKey(input, key, activeContexts, bindings)
  -> ResolveResult: 'match' | 'none' | 'unbound'

function resolveChord(key, pendingChord, activeContexts, bindings)
  -> ChordResolveResult: 'chord_started' | 'chord_cancelled' | 'match'

// 和弦按键流程：
// 1. 用户按下 Ctrl+K → resolveChord 返回 'chord_started'
// 2. 系统进入 pending 状态，等待下一个按键
// 3. 用户按下 Ctrl+U → resolveChord 返回 'match'，执行对应动作
// 4. 如果用户按下其他键 → 'chord_cancelled'，取消和弦

function getBindingDisplayText(action, context, bindings) -> string
// 返回按键绑定的显示文本（用于帮助页面）

十、常量系统：21 个文件

src/constants/ 包含系统提示词、工具权限集、输出样式等核心常量。

系统提示词构建

// src/constants/system.ts
function getCLISyspromptPrefix() {
  // 三种预设：Default（交互式标准 CLI）、AgentSDK preset（非交互式+append）、AgentSDK（非交互式）
}

function getAttributionHeader(fingerprint) {
  // 归因头：cc_version=2.1.88, cc_entrypoint=cli, cch=00000（原生证明占位符）
}

工具权限集与输出样式

// src/constants/tools.ts
ALL_AGENT_DISALLOWED_TOOLS = ['TASK_OUTPUT', 'EXIT_PLAN_MODE', 'ENTER_PLAN_MODE', 'ASK_USER_QUESTION', 'TASK_STOP']
ASYNC_AGENT_ALLOWED_TOOLS = ['FILE_READ', 'WEB_SEARCH', 'GREP', 'FILE_EDIT', 'FILE_WRITE', 'GLOB', 'SHELL_TOOLS', 'SKILL', ...]
IN_PROCESS_TEAMMATE_ALLOWED_TOOLS = ['TASK_CREATE', 'TASK_GET', 'TASK_LIST', 'TASK_UPDATE', 'SEND_MESSAGE']

// src/constants/outputStyles.ts — 三种内置样式：default / Explanatory（解释"为什么"）/ Learning（引导思考）
// src/constants/common.ts — getSessionStartDate = memoize(getLocalISODate)，memoized 用于 prompt-cache 稳定性

十一、类型系统：11 个核心类型文件

src/types/ 定义了整个应用的类型基础。

文件	核心类型	说明
`message.ts`	`UserMessage`, `AssistantMessage`, `ContentBlock`, `ToolUseBlock`	消息协议
`command.ts`	`PromptCommand`, `LocalCommandCall`, `LocalJSXCommandContext`	命令定义
`permissions.ts`	`PermissionMode`, `PermissionBehavior`, `PermissionRuleSource`	权限系统
`hooks.ts`	`HookEvent`, `SyncHookResponse`	Hook 协议
`plugin.ts`	`BuiltinPluginDefinition`, `LoadedPlugin`	插件系统
`tool.ts`	`Tool` 接口	工具定义
`agent.ts`	`Agent` 类型	Agent 定义
`session.ts`	会话类型	会话管理
`settings.ts`	设置类型	设置 Schema
`mcp.ts`	MCP 类型	MCP 协议
`hook.ts`	Hook 类型	Hook 定义

PromptCommand 与权限类型

// src/types/command.ts — PromptCommand 包含 14 个字段
type PromptCommand = {
  type: 'prompt'; progressMessage: string; contentLength: number
  argNames: string[]; allowedTools: string[]; model: string
  source: 'builtin' | 'plugin'; hooks: HookDefinition[]
  skillRoot: string; context: 'inline' | 'fork'
  agent: AgentConfig; effort: string; paths: string[]
  getPromptForCommand: Function
}

// src/types/permissions.ts — 7 种权限模式
EXTERNAL_PERMISSION_MODES = ['acceptEdits', 'bypassPermissions', 'default', 'dontAsk', 'plan']
// 内部模式额外：'auto'（TRANSCRIPT_CLASSIFIER 门控）、'bubble'（向上冒泡到父 Agent）
type PermissionBehavior = 'allow' | 'deny' | 'ask'
type PermissionRuleSource = 'policySettings' | 'userSettings' | 'projectSettings' | 'localSettings' | 'cliArg' | 'managedSettings'

// src/types/hooks.ts — Hook 协议
// syncHookResponseSchema: { continue, suppressOutput, stopReason, decision: 'approve'|'block', reason, systemMessage }

十二、完整架构总结

经过 8 篇文章的深入拆解，让我们用一张图串联起 Claude Code 的所有模块：

┌─────────────────────────────────────────────────────────────┐
│                      用户终端 (Terminal)                      │
│  ┌─────────────────────────────────────────────────────────┐│
│  │          React + Ink 渲染层 (389 组件 + 76 Ink 文件)      ││
│  │  design-system/ │ messages/ │ permissions/ │ mcp/       ││
│  │  agents/        │ tasks/    │ diff/        │ ...        ││
│  └────────────────────────────┬────────────────────────────┘│
│                               │                              │
│  ┌────────────────────────────▼────────────────────────────┐│
│  │              REPL 主循环 + 状态管理                       ││
│  │  screens/REPL.tsx │ QueryEngine.ts │ store.ts (34行)    ││
│  │  80+ Hooks        │ 6 Context Providers                 ││
│  │  AppState         │ selectors.ts │ unifiedSuggestions   ││
│  └────────┬──────────────┬──────────────┬──────────────────┘│
│           │              │              │                    │
│  ┌────────▼───────┐ ┌───▼──────────┐ ┌▼──────────────────┐│
│  │  命令系统       │ │  工具系统     │ │  服务层            ││
│  │ 77 commands    │ │ 35+ tools    │ │ 20+ services      ││
│  │ prompt/local   │ │ buildTool    │ │ MCP/OAuth/插件    ││
│  │ local-jsx      │ │ 并发安全     │ │ 推测/记忆/梦境    ││
│  └────────────────┘ └──────────────┘ └───────────────────┘│
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  支撑系统                                              │  │
│  │  Skills (19) │ Tasks (7类) │ Bridge (31) │ Vim (5)    │  │
│  │  Keybindings(12) │ Memdir(8) │ Constants(21)          │  │
│  │  Types (11) │ Buddy(4) │ Bootstrap │ Ink(76+)         │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
              │                          │
              ▼                          ▼
       Anthropic Messages API      MCP Servers
       (流式对话)                  (外部工具扩展)

关键数字

统计项	数值
总代码量	~70,000 行 TypeScript
文件总数	1,884
组件文件	389
Ink 定制文件	76+
斜杠命令	77
内置工具	35+
服务子系统	20+
React Hooks	80+
Context 模块	6
Feature Flags	10+
权限模式	7 种（5 外部 + 2 内部）
设置源	5 种（user/project/local/flag/policy）
后台任务类型	7 种
Vim 动作	15+
Vim 操作符	8 种
按键绑定上下文	18
技能来源	6 种
通知优先级	4 级
命令队列优先级	3 级
Kill Ring 大小	10
统一建议上限	15
蓄水池采样大小	1,024
桥接退避上限	2 分钟
桥接放弃阈值	10 分钟

条件加载汇总

模块	条件
Voice context	`feature('VOICE_MODE')`
Bash classifier	`feature('BASH_CLASSIFIER')`
Transcript classifier	`feature('TRANSCRIPT_CLASSIFIER')`
Coordinator mode	`CLAUDE_CODE_COORDINATOR_MODE` + `COORDINATOR_MODE` flag
Swarm initialization	`isAgentSwarmsEnabled()`
Scheduled tasks	`isKairosCronEnabled()`
Dream task	KAIROS feature flag
Team memory paths	`feature('TEAMMEM')`
Scratchpad	Statsig `isScratchpadGateEnabled()`
REPL bridge	动态检测

系列回顾

篇	核心收获
1	全局鸟瞰：React + Ink 终端应用，通过 Messages API 流式对话，35+ 工具操作文件系统
2	启动优化：快速路径分发 + 动态导入 + API 预连接，100ms 内启动
3	对话引擎：AsyncGenerator 循环，7 步工具执行流水线，自动压缩
4	命令系统：prompt/local/local-jsx 三种类型，插件迁移模式
5	工具系统：buildTool 工厂，并发安全分区，权限检查链
6	服务层：推测执行（Copy-on-Write overlay），团队记忆同步（35+ 秘密规则）
7	渲染引擎：Ink fork，双缓冲渲染，字素感知，CharPool 复用
8	收尾拼图：34 行 Store，6 Context 模块，完整 Vim 状态机，7 种任务类型，18 按键上下文