Reference ｜关键文件 1 句话索引¶

目的：当你想找"某类功能在哪个文件"时来这里查。覆盖：Claude Code 200+ 关键文件，每个一行简介 + 行数。 不覆盖：组件库 100+ 个业务组件（用 ls src/components/ 自查）。

1. 顶层核心文件¶

文件	行数	作用
`src/main.tsx`	4683	二级入口；启动期 prefetch；主 `main()` 函数
`src/screens/REPL.tsx`	5005	主屏幕；5000 行 React + 85 个 hook 编排
`src/QueryEngine.ts`	1295	单次对话状态机 class；含 `ask()` 方法
`src/Tool.ts`	792	工具抽象；`buildTool` 工厂；Tool/InputSchema 类型
`src/tools.ts`	389	工具注册表；43 个工具的中央集线器
`src/commands.ts`	~200	命令注册表；100+ `/xxx` 命令的中央集线器
`src/query.ts`	1729	agent 循环；`query()` 主循环；流式 API 解析
`src/Task.ts`	~200	任务抽象；TaskType / TaskStatus 类型
`src/tasks.ts`	~200	任务注册表
`src/entrypoints/cli.tsx`	~400	启动 fast-path；`--version` 等快速分支
`src/entrypoints/init.ts`	~200	全局初始化；telemetry / config / MCP
`src/replLauncher.tsx`	~150	REPL 启动器；`launchRepl()`
`src/setup.ts`	~100	全局 setup；早于 main.tsx 的初始化
`src/cost-tracker.ts`	~200	API 费用累计
`src/costHook.ts`	~50	`useCostSummary` hook
`src/history.ts`	~150	命令历史；`addToHistory`、`parseReferences`
`src/context.ts`	~50	Context barrel 导出
`src/ink.ts`	~10	Ink barrel 导出
`src/dialogLaunchers.tsx`	~100	Dialog 启动器
`src/interactiveHelpers.tsx`	~100	交互助手
`src/projectOnboardingState.ts`	~50	项目引导状态

2. state/ 状态管理（6 文件）¶

文件	行数	作用
`src/state/store.ts`	60	通用 store 工厂；getState/setState/subscribe
`src/state/AppStateStore.ts`	569	AppState 类型 + 工厂方法
`src/state/AppState.tsx`	199	React Context Provider + useAppState hook
`src/state/selectors.ts`	~100	纯函数选择器
`src/state/onChangeAppState.ts`	~80	变更时副作用（持久化、通知）
`src/state/teammateViewHelpers.ts`	~30	多 agent 模式辅助

3. ink/ Ink 框架 fork（50+ 文件，13306 行）¶

文件	行数	作用
`src/ink/ink.tsx`	1722	Ink class 入口；React reconciler 适配
`src/ink/reconciler.ts`	~500	React reconciler host config
`src/ink/renderer.ts`	~300	帧渲染
`src/ink/render-to-screen.ts`	~200	帧 → 屏幕
`src/ink/render-node-to-output.ts`	~200	node tree → Y 输出
`src/ink/dom.ts`	~400	虚拟 DOM
`src/ink/node.ts`	~300	节点类型
`src/ink/Ansi.tsx`	291	ANSI 颜色组件
`src/ink/parse-keypress.ts`	~300	按键解析（CSI u / ANSI / legacy）
`src/ink/stringWidth.ts`	~400	字符宽度（CJK / Emoji / ZWJ）
`src/ink/widest-line.ts`	~50	最宽行计算
`src/ink/wrap-text.ts`	74	文本换行
`src/ink/wrapAnsi.ts`	20	ANSI 换行
`src/ink/optimizer.ts`	~200	渲染优化（跳过未变子树）
`src/ink/squash-text-nodes.ts`	~100	Text 节点合并
`src/ink/node-cache.ts`	~80	节点缓存
`src/ink/line-width-cache.ts`	~50	行宽缓存
`src/ink/measure-element.ts`	~150	元素测量
`src/ink/measure-text.ts`	~150	文本测量
`src/ink/hit-test.ts`	~200	命中测试（鼠标）
`src/ink/selection.ts`	~200	文本选择
`src/ink/searchHighlight.ts`	~150	搜索高亮
`src/ink/log-update.ts`	~100	日志更新
`src/ink/bidi.ts`	~100	双向文字
`src/ink/render-border.ts`	~100	边框渲染
`src/ink/get-max-width.ts`	~50	最大宽度
`src/ink/clearTerminal.ts`	~30	清屏
`src/ink/frame.ts`	~150	帧管理
`src/ink/screen.ts`	~200	屏幕缓冲
`src/ink/output.ts`	~100	输出

3.1 ink/events/¶

文件	作用
`click-event.ts`	鼠标点击事件
`dispatcher.ts`	事件分发
`emitter.ts`	事件发射器
`event.ts`	事件基类
`event-handlers.ts`	事件处理
`focus-event.ts`	焦点事件
`input-event.ts`	输入事件
`keyboard-event.ts`	键盘事件
`terminal-event.ts`	终端事件
`terminal-focus-event.ts`	终端焦点事件

3.2 ink/hooks/¶

文件	作用
`use-animation-frame.ts`	requestAnimationFrame 包装
`use-app.ts`	App context
`use-declared-cursor.ts`	声明的光标位置
`use-input.ts`	键盘输入
`use-interval.ts`	setInterval hook
`use-search-highlight.ts`	搜索高亮
`use-selection.ts`	文本选择
`use-stdin.ts`	原始 stdin
`use-tab-status.ts`	Tab 状态
`use-terminal-focus.ts`	终端焦点
`use-terminal-title.ts`	终端标题
`use-terminal-viewport.ts`	视口

3.3 ink/layout/¶

文件	作用
`engine.ts`	布局引擎
`geometry.ts`	几何计算
`node.ts`	节点类型
`yoga.ts`	Yoga 绑定

3.4 ink/components/¶

文件	作用
`AlternateScreen.tsx`	备用屏幕
`App.tsx`	App 根组件
`AppContext.ts`	App context
`Box.tsx`	容器（flexbox）
`Button.tsx`	按钮
`ClockContext.tsx`	时钟 context
`CursorDeclarationContext.ts`	光标 context
`ErrorOverview.tsx`	错误总览
`Link.tsx`	超链接
`Newline.tsx`	换行
`NoSelect.tsx`	不可选
`RawAnsi.tsx`	原始 ANSI
`ScrollBox.tsx`	可滚动容器
`Spacer.tsx`	间距
`StdinContext.ts`	stdin context
`TerminalFocusContext.tsx`	终端焦点 context
`TerminalSizeContext.tsx`	终端尺寸 context
`Text.tsx`	文本

3.5 ink/termio/ (推测)¶

文件	作用
`termio.ts`	终端 IO 入口
`termio/*`	终端 IO 内部

4. services/ 业务服务（100+ 文件）¶

4.1 services/api/¶

文件	行数	作用
`claude.ts`	3419	Anthropic SDK 包装；流式响应解析
`client.ts`	~400	SDK 客户端构造（4 种 provider）
`withRetry.ts`	~200	重试
`errors.ts`	~200	错误定义
`errorUtils.ts`	~150	错误工具
`logging.ts`	~150	usage 日志
`usage.ts`	~100	usage 统计
`emptyUsage.ts`	~30	零 usage
`bootstrap.ts`	~150	启动数据
`filesApi.ts`	~200	文件 API
`dumpPrompts.ts`	~80	prompt debug
`firstTokenDate.ts`	~30	首次 token 时间
`grove.ts`	~150	内部服务（推测）
`metricsOptOut.ts`	~50	遥测 opt-out
`overageCreditGrant.ts`	~50	超额信用
`promptCacheBreakDetection.ts`	~80	prompt cache 失效
`referral.ts`	~100	推荐
`sessionIngress.ts`	~150	session 接入
`ultrareviewQuota.ts`	~50	ultrareview 配额

4.2 services/mcp/ (23 文件)¶

文件	作用
`MCPConnectionManager.tsx`	连接管理核心
`client.ts` (3348 行)	MCP client 实现
`types.ts`	协议类型
`config.ts`	MCP 配置
`auth.ts` (2465 行)	OAuth / API key
`elicitationHandler.ts`	Elicit 请求处理
`oauthPort.ts`	OAuth 回调端口
`xaa.ts`	Cross-App Access
`xaaIdpLogin.ts`	XAA IdP
`officialRegistry.ts`	官方 MCP registry
`vscodeSdkMcp.ts`	VSCode SDK
`claudeai.ts`	claude.ai MCP
`InProcessTransport.ts`	进程内 transport
`SdkControlTransport.ts`	SDK 控制 transport
`normalization.ts`	消息规范化
`channelPermissions.ts`	Channel 权限
`channelAllowlist.ts`	Channel 白名单
`channelNotification.ts`	Channel 通知
`useManageMCPConnections.ts`	React hook
`headersHelper.ts`	HTTP headers
`envExpansion.ts`	env 变量展开
`mcpStringUtils.ts`	字符串工具
`utils.ts`	杂项

4.3 services/compact/ (12 文件)¶

详见 topics/context-compaction.md。

4.4 services/analytics/、services/api/、services/auth (在 utils/) 等¶

不再展开。

5. utils/ 工具函数（100+ 文件）¶

5.1 巨型工具¶

文件	行数	作用
`messages.ts`	5512	消息工具（创建、转换、规范化）
`sessionStorage.ts`	5105	会话存储
`hooks.ts`	5022	hooks 工具
`bash/bashParser.ts`	4436	Tree-sitter bash parser
`attachments.ts`	3997	附件处理
`bash/ast.ts`	2679	bash AST 工具
`plugins/pluginLoader.ts`	3302	plugin 加载
`plugins/marketplaceManager.ts`	2643	plugin 市场
`print.ts` (实际在 `src/cli/print.ts`)	5594	CLI 输出

5.2 中型工具（500-2000 行）¶

utils/ 目录下约 50+ 个 500-2000 行的文件。ls src/utils/ 自查。

5.3 小型工具¶

utils/array.ts、utils/format.ts、utils/errors.ts、utils/log.ts 等基础工具。

6. hooks/ 自定义 hooks (85 个文件)¶

详见 phase-02-repl.md 的 hooks 列表。

按主题分类： - 输入类：useInputBuffer.ts、useHistorySearch.ts、useArrowKeyHistory.tsx、useCommandQueue.ts ... - 生命周期：useAfterFirstRender.ts、useExitOnCtrlCD.ts、useExitOnCtrlCDWithKeybindings.ts ... - 状态订阅：useLogMessages.ts、useMergedClients.ts、useMergedCommands.ts、useMergedTools.ts ... - 网络：useRemoteSession.ts、useDirectConnect.ts、useApiKeyVerification.ts、useSSHSession.ts ... - MCP / Bridge：useMailboxBridge.ts、useSwarmPermissionPoller.ts、useReplBridge.ts ... - 后台任务：useBackgroundTaskNavigation.ts、useInboxPoller.ts ... - UI：useBlink.ts、useMinDisplayTime.ts、useFpsMetrics.ts（在 context/）... - 分析：useElapsedTime.ts、useMemoryUsage.ts、useIdeLogging.ts ...

7. keybindings/ 键位系统（10 文件）¶

文件	作用
`KeybindingProviderSetup.tsx`	全局 Provider
`useKeybinding.ts`	单 binding 注册
`useKeybindings.ts`	多 bindings
`useShortcutDisplay.ts`	快捷键显示
`shortcutFormat.ts`	跨平台格式化

8. native-ts/ N-API 绑定（3 模块）¶

模块	作用
`color-diff/`	颜色差异计算
`file-index/`	文件索引（glob 加速）
`yoga-layout/`	Yoga flexbox 布局

9. vendor/ 外部 N-API（4 模块）¶

模块	作用
`audio-capture-src/`	macOS AVFoundation 音频
`image-processor-src/`	剪贴板图像
`modifiers-napi-src/`	键盘修饰键
`url-handler-src/`	URL scheme handler

10. 其他重要目录¶

目录	文件数	作用
`src/commands/`	100+	100+ 斜杠命令
`src/tools/`	43	43 个工具
`src/components/`	150+	业务组件
`src/components/messages/`	21	消息渲染器
`src/components/design-system/`	14	设计系统
`src/tasks/`	8	任务类型
`src/services/`	100+	业务服务
`src/cli/`	5	CLI 子系统
`src/bridge/`	20+	Bridge 桥接
`src/skills/`	4	技能
`src/plugins/`	2+	插件

11. 用法¶

# 列某个目录所有文件 + 行数
ls src/state/ | xargs wc -l

# 找包含某关键词的文件
grep -rl "ToolPermission" src/

# 看哪个文件最大
find src -type f -name "*.ts" -exec wc -l {} + | sort -rn | head -20

12. 关键洞察¶

12.1 "关键文件" 不到 5%¶

1902 个文件里，真正"必读"的不超过 100 个。其余是配置 / 测试 / 工具。

12.2 "巨型文件" 占了一半行数¶

5594 + 5512 + 5105 + 5022 + 5005 + 4683 + 4436 + 3997 + 3419 + 3348 + 3302 + 3200 + 2999 + 2679 + 2643 + 2621 + 2592 + 2578 + 2465 + 2406 = 75,608 行，占 512,664 行的 14.7%。

Top 20 文件 = 15% 的代码。这是典型的"长尾分布"。

12.3 按"行数"判断重要度是经验法则¶

但不是绝对的。比如 state/store.ts 60 行极其重要（核心抽象），而 state/teammateViewHelpers.ts 30 行不太重要。

关键："行数 × 调用频率" 才是真正的"重要性指标"。

Reference ｜ 关键文件 1 句话索引¶