Topic ｜ `src/` 完整目录树逐个注释¶

重要性：⭐⭐⭐⭐（看源码时随时参考的"地图"）覆盖：1902 个文件的 src/ 全部 60+ 个一级目录 + 200+ 二级目录关联：reference/file-index.md 的 1 句话索引

1. `src/` 60+ 个一级目录逐个解释¶

顺序按字母

1.1 `src/assistant/`¶

LLM 助手相关。推测是"代码助手"专用的 prompt 模板 + 工具集。

1.2 `src/bootstrap/`¶

Bootstrap 状态。bootstrap/state.ts 包含全局模块级状态（sessionId、getCwd、getProjectRoot 等）。

// src/bootstrap/state.ts
export function getSessionId(): string { ... }
export function getProjectRoot(): string { ... }
export function getOriginalCwd(): string { ... }
export function setCostStateForRestore(...): void { ... }

为什么独立：这些是"启动前就需要"的全局状态，独立于 React store。

1.3 `src/bridge/` (20+ 文件)¶

IDE / Remote 桥接。详见 phase-07-advanced.md 的 Bridge 专题。

1.4 `src/buddy/`¶

Buddy 模式。DCE：feature('BUDDY')。多 agent 协作的另一种模式。

1.5 `src/cli/`¶

CLI 子系统。cli/print.ts 是 5594 行的输出格式化巨兽。

src/cli/
├── print.ts (5594 行)
├── handlers/         CLI 子处理器
└── transports/       CLI 传输（stdio、HTTP）

1.6 `src/commands/` (100+ 子目录)¶

斜杠命令系统。每个子目录是一个 /xxx 命令。 - /commit → src/commands/commit.js - /config → src/commands/config/index.js - /mcp → src/commands/mcp/index.js - /compact → src/commands/compact/index.js - ...

100+ 子命令 对应 100+ 子目录。

1.7 `src/commands.ts`¶

斜杠命令注册表。和 tools.ts 类似，是所有命令的"中央集线器"。

1.8 `src/components/` (150+ 文件)¶

业务组件。components/design-system/ 是基础，components/messages/ 是消息渲染。详见 phase-04-components.md。

1.9 `src/constants/`¶

常量定义。OAuth、product、system prompt 前缀、permission mode 等。

src/constants/
├── oauth.ts          OAuth 配置
├── product.ts        产品信息（version、URL）
├── prompts.ts        system prompt 模板
├── system.ts         attribution header、sysprompt prefix
├── xml.ts            XML tag（local command stdout/stderr）
└── ...

1.10 `src/context.ts` + `src/context/`¶

Context 集合。

src/context/
├── notifications.js    通知 context
├── modalContext.tsx    模态 context
├── fpsMetrics.tsx      FPS 监控 context
└── ...

1.11 `src/coordinator/`¶

多 agent 协调器。DCE：feature('COORDINATOR_MODE')。 - coordinatorMode.ts —— 主控

1.12 `src/cost-tracker.ts` + `src/costHook.ts`¶

费用追踪。 - cost-tracker.ts —— 累计 API 调用费用 - costHook.ts —— useCostSummary hook

1.13 `src/dialogLaunchers.tsx`¶

Dialog 启动器。推测是"按需弹 dialog"的高阶函数。

1.14 `src/entrypoints/`¶

入口点集合。

src/entrypoints/
├── cli.tsx               二级 fast-path 入口
├── init.ts               初始化
├── mcp.ts                MCP server 模式入口
├── sandboxTypes.ts       沙箱类型
├── agentSdkTypes.ts      SDK 类型
└── sdk/                  Claude Code SDK 入口

1.15 `src/history.ts`¶

命令历史。addToHistory、removeLastFromHistory、expandPastedTextRefs、parseReferences。

1.16 `src/hooks/` (85 个文件)¶

自定义 hooks。详见 phase-02-repl.md 的 hooks 层。

1.17 `src/ink.ts` + `src/ink/` (50+ 文件)¶

Ink 框架的导出 + fork。 - ink.ts 是 barrel re-export - ink/ 是 fork 内部

1.18 `src/interactiveHelpers.tsx`¶

交互助手。推测是"用户操作引导"的辅助函数。

1.19 `src/keybindings/` (10 文件)¶

键位系统。详见 topics/keybindings-system.md。

1.20 `src/main.tsx` (4683 行)¶

主入口。详见 phase-01-entry.md。

1.21 `src/memdir/`¶

Memory directory。memdir/ 管理"长期记忆"（跨会话的用户偏好、项目约定）。 - memdir.ts —— 读 / 写 / 索引记忆文件 - paths.ts —— 路径解析

1.22 `src/migrations/`¶

数据迁移。~/.claude/ 旧版本数据 → 新版本。

1.23 `src/moreright/`¶

"More Right" 模式。推测是"扩展右侧"的功能。

1.24 `src/native-ts/` (3 模块)¶

N-API TypeScript 绑定。

src/native-ts/
├── color-diff/        颜色差异
├── file-index/        文件索引
└── yoga-layout/       Yoga 布局

1.25 `src/outputStyles/`¶

输出样式。"简洁 / 详细 / 自定义"等输出风格。

1.26 `src/plugins/`¶

插件系统。 - builtinPlugins.ts —— 内置插件清单 - bundled/ —— 内置插件实现

1.27 `src/projectOnboardingState.ts`¶

项目引导状态。用户首次在某项目用 Claude Code 时的引导。

1.28 `src/query.ts` + `src/query/` + `src/QueryEngine.ts`¶

核心 agent 循环。详见 phase-06-agent-loop.md。 - query.ts (1729 行) —— 主循环 - QueryEngine.ts (1295 行) —— 状态机 - query/ —— 子目录

1.29 `src/remote/`¶

远程会话。详见 phase-07-advanced.md 的 Remote 章节。

src/remote/
├── RemoteSessionManager.ts
├── SessionsWebSocket.ts
├── sdkMessageAdapter.ts
└── remotePermissionBridge.ts

1.30 `src/replLauncher.tsx`¶

REPL 启动器。从 main.tsx 跳到 REPL 的最后一跳。

1.31 `src/schemas/`¶

Zod schemas。所有 z.object(...) 定义集中地（按业务划分）。

1.32 `src/screens/` (3 文件)¶

屏幕。REPL、Doctor、ResumeConversation。

1.33 `src/server/` (3 文件)¶

本地 HTTP server。Direct Connect 模式。

src/server/
├── createDirectConnectSession.ts
├── directConnectManager.ts
└── types.ts

1.34 `src/services/` (100+ 文件)¶

业务服务。

src/services/
├── api/                 API 客户端
├── mcp/                 MCP
├── analytics/           遥测
├── auth (在 utils/)     鉴权
├── tools/               工具相关服务
├── compact/             压缩
├── prompts/             prompt 服务
├── settings/            设置服务
└── ...

1.35 `src/setup.ts`¶

全局 setup。main.tsx 之前的一次性设置。

1.36 `src/skills/`¶

技能系统。 - bundledSkills.ts —— 内置 skills - loadSkillsDir.ts —— 扫描加载 - mcpSkillBuilders.ts —— 把 MCP 工具包成 skill

1.37 `src/state/` (6 文件)¶

状态管理。详见 phase-03-state.md。 - store.ts (60 行) —— 核心 - AppStateStore.ts (569 行) —— 类型 - AppState.tsx (199 行) —— Provider - selectors.ts —— 选择器 - onChangeAppState.ts —— 副作用 - teammateViewHelpers.ts —— 队友视图

1.38 `src/Task.ts` + `src/tasks.ts` + `src/tasks/`¶

任务系统。详见 phase-06-agent-loop.md 的 Task 抽象。

1.39 `src/Tool.ts` + `src/tools.ts` + `src/tools/`¶

工具系统。详见 phase-05-tools.md。 - Tool.ts (792 行) —— 抽象 - tools.ts (389 行) —— 注册表 - tools/<ToolName>/ (43 个) —— 实现

1.40 `src/types/`¶

TypeScript 类型。所有 interface / type 集中地。

1.41 `src/upstreamproxy/`¶

上游代理。推测是"代理到上游 API"的网络层。

1.42 `src/utils/` (100+ 文件)¶

工具函数。Claude Code 最大的目录之一。 - attachments.ts (3997 行) - bash/ —— bash 相关 - hooks.ts (5022 行) - messages.ts (5512 行) - permissions/ —— 权限 - sessionStorage.ts (5105 行) - settings/ —— 设置 - startupProfiler.ts —— 启动打点 - ...

1.43 `src/vim/` (5 文件)¶

Vim 模式。详见 phase-07-advanced.md 的 Vim 模式。

1.44 `src/voice/`¶

语音模式。 - voiceModeEnabled.ts —— 功能标志 - voiceStreamSTT.ts —— 流式 STT - 其他

2. 重要二级目录¶

2.1 `src/services/api/`¶

API 客户端。 - claude.ts (3419 行) —— Anthropic SDK 包装 - client.ts —— 客户端构造 - withRetry.ts —— 重试 - errors.ts + errorUtils.ts —— 错误 - usage.ts + logging.ts + emptyUsage.ts —— usage 统计 - bootstrap.ts —— 启动数据 - filesApi.ts —— 文件 API - metricsOptOut.ts —— 遥测 opt-out - promptCacheBreakDetection.ts —— prompt cache 失效检测 - dumpPrompts.ts —— debug 工具 - firstTokenDate.ts —— 首次 token 时间 - grove.ts —— 内部名字（推测是 search/grove 服务） - overageCreditGrant.ts —— 超额信用 - referral.ts —— 推荐 - sessionIngress.ts —— session 接入 - ultrareviewQuota.ts —— ultrareview 配额

2.2 `src/utils/bash/`¶

bash 工具集。 - bashParser.ts (4436 行) —— Tree-sitter parser - ast.ts (2679 行) —— AST 工具

2.3 `src/utils/plugins/`¶

plugin 工具。 - pluginLoader.ts (3302 行) —— 加载器 - marketplaceManager.ts (2643 行) —— 市场

2.4 `src/utils/permissions/`¶

权限。 - PermissionMode.ts —— 模式定义 - PermissionResult.ts —— 决策结果 - denialTracking.ts —— 拒绝追踪 - shellRuleMatching.ts —— 通配符匹配 - filesystem.ts —— 文件权限 - ...

2.5 `src/utils/settings/`¶

设置。 - settings.ts + types.ts —— 设置定义 - mdm/rawRead.ts —— macOS MDM - secureStorage/keychainPrefetch.ts —— keychain - ...

2.6 `src/tasks/`¶

任务类型。 - LocalMainSessionTask.ts —— 主会话 - LocalAgentTask/ —— 本地 agent - RemoteAgentTask/ —— 远程 agent - InProcessTeammateTask/ —— 进程内队友 - LocalShellTask/ —— 本地 shell - DreamTask/ —— dream 任务 - stopTask.ts —— 停止任务 - types.ts —— 联合类型 - pillLabel.ts —— UI 标签

2.7 `src/skills/bundled/`¶

内置 skills（具体每个 skill 一个子目录）。

2.8 `src/plugins/bundled/`¶

内置 plugins。

2.9 `src/hooks/notifs/`¶

通知 hooks（推测）。

2.10 `src/hooks/toolPermission/`¶

工具权限 hooks。

2.11 `src/hooks/renderPlaceholder.ts`¶

渲染占位。

2.12 `src/memdir/`¶

长期记忆。

3. 顶级文件（非目录）¶

文件	角色
`src/main.tsx`	主入口（4683 行）
`src/QueryEngine.ts`	agent 状态机（1295 行）
`src/Tool.ts`	工具抽象（792 行）
`src/Task.ts`	任务抽象（推测 200 行）
`src/commands.ts`	命令注册表（200+ 行）
`src/query.ts`	agent 循环（1729 行）
`src/tools.ts`	工具注册表（389 行）
`src/tasks.ts`	任务注册表（推测 200 行）
`src/state/store.ts`	store 工厂（60 行）
`src/state/AppStateStore.ts`	state 类型（569 行）
`src/state/AppState.tsx`	Provider（199 行）
`src/state/selectors.ts`	选择器
`src/state/onChangeAppState.ts`	副作用
`src/state/teammateViewHelpers.ts`	队友视图
`src/cost-tracker.ts`	费用追踪
`src/costHook.ts`	费用 hook
`src/dialogLaunchers.tsx`	dialog 启动器
`src/history.ts`	命令历史
`src/ink.ts`	Ink barrel export
`src/context.ts`	Context barrel
`src/interactiveHelpers.tsx`	交互助手
`src/projectOnboardingState.ts`	引导状态
`src/replLauncher.tsx`	REPL 启动器
`src/setup.ts`	全局 setup

4. 关键洞察¶

4.1 目录树是"领域地图"¶

60+ 一级目录 = 60+ 业务领域。看到目录名就能猜出功能。

巨大目录（>50 文件）：utils/、components/、services/、hooks/、commands/、tasks/
中等目录（10-50）：tools/、bridge/、mcp/（在 services/）、ink/
小目录（1-9）：其余

巨大目录通常是"业务大类"。小目录是"专门子系统"。

4.3 DCE/Ant-only 散落各处¶

很多目录里都有 feature() 门控或 process.env.USER_TYPE === 'ant' 检查。
目录名 = 功能名 ≠ 外部用户可见。

5. 阅读清单¶

✅ ls src/ 通读目录
✅ find src -mindepth 2 -maxdepth 2 -type d | sort 看二级目录
📌 选 5 个陌生目录，逐个 ls 看里面有啥
📌 跑 find src -type f | wc -l 验证 1902 个文件

6. 练习任务¶

画 60+ 目录的依赖图 —— 谁 import 谁
统计每个目录的文件数 —— find src/<dir> -type f | wc -l，画一个分布图
找出所有 DCE 集中的目录 —— grep -l "feature(" src/<dir>/*
思考：如果有新功能要加，你会建新目录还是放到现有目录？判断标准是什么？

Topic ｜ src/ 完整目录树逐个注释¶

1. src/ 60+ 个一级目录逐个解释¶

1.1 src/assistant/¶

1.2 src/bootstrap/¶

1.3 src/bridge/ (20+ 文件)¶

1.4 src/buddy/¶

1.5 src/cli/¶

1.6 src/commands/ (100+ 子目录)¶

1.7 src/commands.ts¶

1.8 src/components/ (150+ 文件)¶

1.9 src/constants/¶

1.10 src/context.ts + src/context/¶

1.11 src/coordinator/¶

1.12 src/cost-tracker.ts + src/costHook.ts¶

1.13 src/dialogLaunchers.tsx¶

1.14 src/entrypoints/¶

1.15 src/history.ts¶

1.16 src/hooks/ (85 个文件)¶

1.17 src/ink.ts + src/ink/ (50+ 文件)¶

1.18 src/interactiveHelpers.tsx¶

1.19 src/keybindings/ (10 文件)¶

1.20 src/main.tsx (4683 行)¶

1.21 src/memdir/¶

1.22 src/migrations/¶

1.23 src/moreright/¶

1.24 src/native-ts/ (3 模块)¶

1.25 src/outputStyles/¶

1.26 src/plugins/¶

1.27 src/projectOnboardingState.ts¶

1.28 src/query.ts + src/query/ + src/QueryEngine.ts¶

1.29 src/remote/¶

1.30 src/replLauncher.tsx¶

1.31 src/schemas/¶

1.32 src/screens/ (3 文件)¶

1.33 src/server/ (3 文件)¶

1.34 src/services/ (100+ 文件)¶

1.35 src/setup.ts¶

1.36 src/skills/¶

1.37 src/state/ (6 文件)¶

1.38 src/Task.ts + src/tasks.ts + src/tasks/¶

1.39 src/Tool.ts + src/tools.ts + src/tools/¶

1.40 src/types/¶

1.41 src/upstreamproxy/¶

1.42 src/utils/ (100+ 文件)¶

1.43 src/vim/ (5 文件)¶

1.44 src/voice/¶