808d5a61b3
新增 docs/agentic-design/ 教育文档，全中文+英文技术术语，覆盖： - README.md: 总索引，整体架构图，阅读指南 - 00-codebase-tour.md: 代码库全景，递归覆盖所有重要目录 - 01-agent-loop.md: Query loop 状态机，token budget，compaction - 02-tool-system.md: Tool interface，权限检查，并发执行，sibling abort - 03-multi-agent-coordination.md: Agent 类型，coordinator 4 阶段，XML 通信 - 04-permission-system.md: Permission mode，rule system，YOLO 分类器，denial tracking - 05-context-and-memory.md: System prompt 分层，compaction，auto-dream 后台巩固 - 06-feature-gating.md: Compile-time feature，runtime flags，Bun dead-code elimination 总计 ~2.5 小时阅读，每篇含 Design Decision 专栏和常见误解纠正 https://claude.ai/code/session_017Vdqo9B8eTXiEDcqnv9DxM
486 lines
15 KiB
Markdown
486 lines
15 KiB
Markdown
# 代码库全景：从顶层到最深处
|
||
|
||
> 这篇文档是一个**递归的导游**。我们从顶层文件开始，逐层深入每个重要的目录，直到粒度太细而没有学习价值为止。每个章节都注明关键文件，你可以随时打开源代码对照。
|
||
|
||
---
|
||
|
||
## 顶层：核心文件
|
||
|
||
在 `/home/user/claude-code/` 的根目录下，以下文件是系统的脊梁：
|
||
|
||
| 文件 | 行数 | 用途 |
|
||
|------|------|------|
|
||
| `main.tsx` | ~4700 | CLI 入口，React + Ink 终端渲染器 |
|
||
| `query.ts` | ~1700 | Query loop 状态机的完整实现 |
|
||
| `QueryEngine.ts` | 核心 | Query 执行的编排引擎 |
|
||
| `Tool.ts` | 核心 | Tool 的类型定义和接口规范 |
|
||
| `tools.ts` | 核心 | Tool 注册与初始化 |
|
||
| `context.ts` | 核心 | System prompt 和 context 的组装 |
|
||
| `commands.ts` | ~700 | 所有 slash command 的中央路由 |
|
||
|
||
**学习路线**：`main.tsx` → `query.ts` → `Tool.ts` 可以了解 agent loop 的完整流程。
|
||
|
||
---
|
||
|
||
## `entrypoints/` — 入口层
|
||
|
||
系统支持多种启动方式：
|
||
|
||
| 子目录/文件 | 用途 |
|
||
|-----------|------|
|
||
| `cli.tsx` | 标准 CLI 入口，React 组件树的根，feature detection |
|
||
| `sdk/` | Anthropic SDK 集成（给程序员用） |
|
||
| `mcp.ts` | MCP (Model Context Protocol) 服务器 |
|
||
| `init.ts` | 初始化逻辑，首次运行配置 |
|
||
| `sandboxTypes.ts` | 沙箱相关的类型定义 |
|
||
|
||
**关键点**：`cli.tsx` 做 feature flag 检测，决定如何初始化全局状态。
|
||
|
||
---
|
||
|
||
## `query/` — Query Loop 配置和支撑
|
||
|
||
这个目录下的文件都是 `query.ts` 的辅助组件：
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `config.ts` | Query 配置构建器，参数组合 |
|
||
| `tokenBudget.ts` | Token budget 追踪和强制执行 |
|
||
| `stopHooks.ts` | Stop/interrupt 处理 |
|
||
| `deps.ts` | Query 依赖注入 |
|
||
|
||
**最重要的**：`tokenBudget.ts` 控制着"超限时触发 compaction"的逻辑。
|
||
|
||
---
|
||
|
||
## `tools/` — 所有 Tool 实现（40+ 个）
|
||
|
||
这个目录有 40 多个子目录，每个代表一个 Tool。核心的几个：
|
||
|
||
### 必读：
|
||
|
||
| Tool | 文件 | 用途 |
|
||
|------|------|------|
|
||
| `AgentTool/` | 子 agent 的产卵和管理 | 核心，递归往下 |
|
||
| `FileReadTool/` | 读文件 | 基础 |
|
||
| `FileEditTool/` | 编辑文件 | 基础 |
|
||
| `FileWriteTool/` | 写文件 | 基础 |
|
||
| `BashTool/` | 执行 shell 命令 | 基础 |
|
||
| `GlobTool/` | 文件匹配 | 基础 |
|
||
| `GrepTool/` | 内容搜索 | 基础 |
|
||
| `WebFetchTool/` | 获取网页 | 基础 |
|
||
| `AskUserQuestionTool/` | 询问用户 | 权限边界 |
|
||
| `TodoWriteTool/` | 写 todo list | 后台任务 |
|
||
|
||
### `AgentTool/` — 深递归
|
||
|
||
这是最复杂的 Tool，用来 spawn 子 agent：
|
||
|
||
```
|
||
AgentTool/
|
||
├── AgentTool.tsx [233 KB] 主逻辑，agent 生命周期
|
||
├── runAgent.ts 执行 agent 的主函数
|
||
├── forkSubagent.ts fork 一个新 agent
|
||
├── resumeAgent.ts 恢复之前的 agent
|
||
├── loadAgentsDir.ts 从 ~/.agents/ 加载 agent 定义
|
||
├── built-in/ 内置 agent
|
||
│ ├── generalPurposeAgent.ts
|
||
│ ├── planAgent.ts
|
||
│ ├── exploreAgent.ts
|
||
│ └── ... (其他 5 个)
|
||
├── agentMemory.ts Agent 记忆快照
|
||
├── agentColorManager.ts Agent 的颜色分配（便于输出区分）
|
||
└── ... (其他支撑文件)
|
||
```
|
||
|
||
**关键概念**：Agent 可以是 local (in-process) 或 remote (CCR)，使用 `AsyncLocalStorage` 隔离上下文。
|
||
|
||
---
|
||
|
||
## `services/` — 业务逻辑服务
|
||
|
||
这个目录是 Claude Code 的"心脏"：
|
||
|
||
### `tools/` — Tool 执行编排
|
||
|
||
```
|
||
services/tools/
|
||
├── StreamingToolExecutor.ts [核心] 并发 tool 执行，结果缓冲
|
||
├── toolOrchestration.ts Tool 调度和权限检查
|
||
├── toolExecution.ts 单个 tool 调用的执行
|
||
├── toolHooks.ts Tool 执行前/后的 hook
|
||
└── ...
|
||
```
|
||
|
||
**最重要**：`StreamingToolExecutor.ts` 实现了"并发执行但顺序输出结果"的逻辑。
|
||
|
||
### `autoDream/` — 自动记忆压缩
|
||
|
||
```
|
||
services/autoDream/
|
||
├── autoDream.ts [11 KB] Dream 流程：3 个触发门 + 4 个阶段
|
||
├── consolidationPrompt.ts [核心] 告诉 Claude 怎么压缩 memory
|
||
├── consolidationLock.ts 防并发的 lock 机制
|
||
└── config.ts Dream 参数配置
|
||
```
|
||
|
||
**关键点**：Dream 有三个触发条件门：24h 时间 + 5+ 个 session + 拿到 lock。
|
||
|
||
### 其他重要服务
|
||
|
||
| 目录 | 用途 |
|
||
|------|------|
|
||
| `api/` | Claude API 调用，token 计算，usage 追踪 |
|
||
| `mcp/` | MCP 协议服务器的实现 |
|
||
| `analytics/` | 事件上报、GrowthBook feature flags |
|
||
| `plugins/` | 插件系统 |
|
||
|
||
---
|
||
|
||
## `utils/permissions/` — 权限系统（深递归）
|
||
|
||
这是整个 agent sandbox 的防线，共 20+ 个文件，总计 300+ KB：
|
||
|
||
```
|
||
utils/permissions/
|
||
├── permissions.ts [52 KB] 核心决策逻辑
|
||
├── yoloClassifier.ts [52 KB] ML 自动审批分类器
|
||
├── filesystem.ts [62 KB] 文件系统安全规则
|
||
├── PermissionMode.ts Permission mode 枚举
|
||
├── denialTracking.ts 追踪拒绝次数，circuit breaker
|
||
├── pathValidation.ts 路径安全（Unicode normalization 等）
|
||
├── permissionRuleParser.ts 解析 "Bash(git *)" 这样的规则
|
||
├── classifierDecision.ts 分类器决策包装
|
||
├── bashClassifier.ts Bash 命令的特殊规则
|
||
├── permissionExplainer.ts 用 LLM 解释权限决定
|
||
└── ... (其他辅助)
|
||
```
|
||
|
||
**核心 pipeline**：mode → rules → YOLO classifier → prompt user
|
||
|
||
---
|
||
|
||
## `utils/` — 其他公用工具（部分列举）
|
||
|
||
```
|
||
utils/
|
||
├── permissions/ [见上面的深递归]
|
||
├── messages/
|
||
│ ├── mappers.ts SDK 消息格式转换
|
||
│ ├── systemInit.ts 系统初始化消息构建
|
||
│ └── ...
|
||
├── settings/ 设置加载和应用
|
||
├── queryHelpers.ts Query 辅助函数
|
||
├── undercover.ts 隐藏内部代号（Capybara, Tengu 等）
|
||
├── abortController.ts Abort signal 管理
|
||
├── agentContext.ts Agent 上下文 getter
|
||
├── api.ts API 工具函数
|
||
├── hooks/ React hooks （不是本目录）
|
||
├── ... (数十个其他)
|
||
```
|
||
|
||
**学习重点**：`permissions/` 最复杂，其次是 `messages/` 和 `settings/`。
|
||
|
||
---
|
||
|
||
## `coordinator/` — 多 Agent 协调
|
||
|
||
```
|
||
coordinator/
|
||
└── coordinatorMode.ts [19 KB] 唯一的文件，包含完整 coordinator 系统提示
|
||
|
||
功能：启用 CLAUDE_CODE_COORDINATOR_MODE=1 时激活，引入 4 个阶段：
|
||
research → synthesis → implementation → verification
|
||
```
|
||
|
||
**关键点**：Worker 通过 `<task-notification>` XML 向 coordinator 报告进度。
|
||
|
||
---
|
||
|
||
## `tasks/` — 后台任务管理
|
||
|
||
```
|
||
tasks/
|
||
├── LocalAgentTask/ 本地 agent 任务追踪
|
||
├── RemoteAgentTask/ 远程 agent 任务追踪（CCR）
|
||
├── LocalMainSessionTask.ts 主 session 的任务
|
||
├── LocalShellTask/ Shell 任务（tmux/iTerm2）
|
||
├── InProcessTeammateTask/ In-process teammate 任务
|
||
├── DreamTask/ Memory dream 任务
|
||
├── stopTask.ts 停止任务的逻辑
|
||
├── types.ts Task 的类型定义
|
||
└── pillLabel.ts 任务标签（UI 展示）
|
||
```
|
||
|
||
**核心概念**：每个后台任务都有生命周期追踪。
|
||
|
||
---
|
||
|
||
## `state/` — React 状态管理
|
||
|
||
```
|
||
state/
|
||
├── AppState.tsx React 状态类型定义
|
||
├── AppStateStore.ts [21 KB] Zustand-like 状态存储
|
||
├── onChangeAppState.ts 状态变化的 handler
|
||
├── selectors.ts 状态选择器
|
||
├── store.ts 存储初始化
|
||
└── teammateViewHelpers.ts Teammate 视图辅助
|
||
```
|
||
|
||
**模式**：这是 Claude Code 的全局状态树，UI 所有数据都来自这里。
|
||
|
||
---
|
||
|
||
## `hooks/` — 80+ 个 React Hook
|
||
|
||
重要的：
|
||
|
||
| Hook | 用途 |
|
||
|------|------|
|
||
| `useCanUseTool.tsx` | [40 KB] 权限检查 Hook（频繁调用） |
|
||
| `useGlobalKeybindings.tsx` | [31 KB] 全局键盘快捷键 |
|
||
| `useTypeahead.tsx` | [212 KB] 自动补全建议 |
|
||
| `useVoice.ts` | [45 KB] 语音输入集成 |
|
||
| `useInboxPoller.ts` | [34 KB] 后台轮询消息 |
|
||
| `useArrowKeyHistory.tsx` | [34 KB] 历史导航（上/下箭头） |
|
||
| `useReplBridge.ts` | [115 KB] REPL 集成 |
|
||
|
||
**学习策略**：跳过大部分 hook，只深入 `useCanUseTool` 和 `useTypeahead`。
|
||
|
||
---
|
||
|
||
## `bootstrap/state.ts` — 全局启动状态
|
||
|
||
```
|
||
bootstrap/
|
||
└── state.ts [56 KB]
|
||
```
|
||
|
||
内容：
|
||
- 当前 session ID 和持久化 flag
|
||
- 用户类型（ant/public）
|
||
- Feature flag 缓存
|
||
- KAIROS mode 检测
|
||
- 全局配置状态
|
||
|
||
**作用**：在 App 启动的最早时刻初始化所有全局状态。
|
||
|
||
---
|
||
|
||
## `cli/` — 终端输出和格式化
|
||
|
||
```
|
||
cli/
|
||
├── print.ts [212 KB] 终端渲染引擎
|
||
├── structuredIO.ts NDJSON 和结构化输出
|
||
├── handlers/ 命令特定的输出 handler
|
||
├── transports/ 多种输出后端（stdout, HTTP 等）
|
||
├── remoteIO.ts 远程 IO
|
||
└── ... (其他)
|
||
```
|
||
|
||
**关键**：`print.ts` 是整个 Claude Code 的"输出黑洞"，所有文本最终都通过这里。
|
||
|
||
---
|
||
|
||
## `context/` — React Context Provider
|
||
|
||
```
|
||
context/
|
||
├── QueuedMessageContext.tsx 消息队列
|
||
├── mailbox.tsx Agent 邮箱（inter-agent 消息）
|
||
├── modalContext.tsx Modal 对话框
|
||
├── notifications.tsx 通知系统
|
||
├── overlayContext.tsx 浮层上下文
|
||
├── promptOverlayContext.tsx 提示浮层
|
||
├── stats.tsx 统计数据
|
||
└── voice.tsx 语音上下文
|
||
```
|
||
|
||
**作用**：提供 React component tree 范围内的全局上下文。
|
||
|
||
---
|
||
|
||
## `memdir/` — 用户 Memory 管理
|
||
|
||
```
|
||
memdir/
|
||
├── memdir.ts [21 KB] 核心 memory 目录管理
|
||
├── memoryScan.ts 扫描 memory 文件
|
||
├── memoryTypes.ts Memory 文件的类型
|
||
├── memoryAge.ts Memory 的年龄计算
|
||
├── paths.ts Memory 文件路径管理
|
||
├── teamMemPaths.ts Team memory 路径（multi-agent）
|
||
└── findRelevantMemories.ts 查找相关 memory
|
||
```
|
||
|
||
**用途**：管理 `~/.claude/memory/` 目录，存储用户的持久化知识。
|
||
|
||
---
|
||
|
||
## `constant/` — 常量和系统提示
|
||
|
||
```
|
||
constant/ (也被称为 constants/)
|
||
├── system.ts Base system prompt
|
||
├── systemPromptSections.ts System prompt 的可组装部分
|
||
├── cyberRiskInstruction.ts 安全指导（Safeguards team 维护）
|
||
├── betas.ts API beta features 列表
|
||
├── messages.ts 常见消息文本
|
||
├── prompts.ts 各种 prompt 模板
|
||
└── ... (其他常量)
|
||
```
|
||
|
||
**关键**：System prompt 是模块化的，不同 feature 会添加不同的部分。
|
||
|
||
---
|
||
|
||
## `bridge/` — 与 claude.ai 的 JWT 连接
|
||
|
||
```
|
||
bridge/
|
||
├── bridgeApi.ts 与 claude.ai 的通信
|
||
├── bridgeMessaging.ts 消息协议
|
||
├── remoteBridgeCore.ts 远程 bridge 核心
|
||
├── createSession.ts 创建远程 session
|
||
├── jwtUtils.ts JWT 令牌工具
|
||
├── trustedDevice.ts 受信设备管理
|
||
└── ... (10+ 个其他)
|
||
```
|
||
|
||
**用途**：BRIDGE_MODE 时，CLI 可以通过 claude.ai 的 WebUI 远程控制。
|
||
|
||
---
|
||
|
||
## `remote/` — 远程 Session 管理
|
||
|
||
```
|
||
remote/
|
||
├── RemoteSessionManager.ts 远程 session 生命周期
|
||
├── SessionsWebSocket.ts WebSocket 连接管理
|
||
├── remotePermissionBridge.ts 权限同步
|
||
├── sdkMessageAdapter.ts SDK 消息适配
|
||
└── ... (其他)
|
||
```
|
||
|
||
**用途**：支持多个远程客户端同时连接到同一个服务。
|
||
|
||
---
|
||
|
||
## `entrypoints/sdk/` — SDK 集成
|
||
|
||
```
|
||
entrypoints/sdk/
|
||
├── agentSdkTypes.ts 给外部程序使用的类型
|
||
└── (其他 SDK 特定代码)
|
||
```
|
||
|
||
**用途**：让程序员可以用代码调用 Claude Code，而不只是 CLI。
|
||
|
||
---
|
||
|
||
## `components/` — React UI 组件
|
||
|
||
```
|
||
components/
|
||
├── App.tsx 顶层 app 组件
|
||
├── AgentProgressLine.tsx Agent 进度显示
|
||
├── BaseTextInput.tsx 文本输入基础
|
||
├── ... (100+ 个其他组件)
|
||
```
|
||
|
||
**特点**：使用 Ink 库在终端中渲染 React 组件。
|
||
|
||
---
|
||
|
||
## `commands/` — Slash 命令（88 个）
|
||
|
||
```
|
||
commands/
|
||
├── commit.ts / commit-push-pr.ts Git 相关命令
|
||
├── agent.ts Agent 管理命令
|
||
├── task.ts, tasks.ts 任务管理
|
||
├── config.ts 配置命令
|
||
├── memory.ts, memory-dream.ts Memory 管理
|
||
├── session.ts Session 管理
|
||
├── autofix-pr.ts PR 自动修复
|
||
├── ... (80+ 个其他)
|
||
```
|
||
|
||
**特点**：每个 command 都可以定制输出格式，支持 structured output (NDJSON)。
|
||
|
||
---
|
||
|
||
## 递归粒度停止条件
|
||
|
||
以下类型的文件不再递归深入：
|
||
|
||
- **单功能工具函数** (<100 行，做一件明确的事)：如 `array.ts`, `api.ts` 的某些导出
|
||
- **简单 enum/type 定义**：如 `types.ts`, `*.d.ts`
|
||
- **单个小的 React Hook**：如 `useAfterFirstRender.ts`
|
||
- **Utility 映射和适配器**：如 message format converter
|
||
|
||
这些文件的学习价值在于"知道它存在"，而不是理解其内部细节。
|
||
|
||
---
|
||
|
||
## 学习路线建议
|
||
|
||
1. **快速扫描**：从 README 开始，看一眼这个全景。
|
||
2. **焦点学习**：根据你的兴趣选择深入：
|
||
- 想理解 agent loop? → `query.ts`, `QueryEngine.ts`
|
||
- 想理解 tool 系统? → `Tool.ts`, `tools/`, `services/tools/`
|
||
- 想理解权限? → `utils/permissions/`
|
||
- 想理解多 agent? → `tools/AgentTool/`, `coordinator/`
|
||
3. **对照原文**：打开相应的源文件，参照本文的路线图逐个浏览。
|
||
|
||
---
|
||
|
||
## 核心数据流
|
||
|
||
```
|
||
User Input
|
||
↓
|
||
entrypoints/cli.tsx (React 初始化)
|
||
↓
|
||
query.ts (Query Loop: QUERY → TOOL_USE → RESULT)
|
||
↓
|
||
Tool.ts & services/tools/ (Tool 执行)
|
||
↓
|
||
utils/permissions/ (权限检查) + BashTool/FileEditTool/... (实际执行)
|
||
↓
|
||
queryHelpers + messages (结果处理)
|
||
↓
|
||
state/ (状态更新)
|
||
↓
|
||
components/ + cli/print.ts (UI 渲染)
|
||
↓
|
||
User sees output
|
||
```
|
||
|
||
---
|
||
|
||
## 关键文件大小排名
|
||
|
||
```
|
||
Top 15 largest files (最值得读):
|
||
|
||
1. query.ts ~1700 行
|
||
2. services/tools/StreamingToolExecutor.ts
|
||
3. utils/permissions/permissions.ts ~52 KB
|
||
4. utils/permissions/yoloClassifier.ts ~52 KB
|
||
5. utils/permissions/filesystem.ts ~62 KB
|
||
6. hooks/useTypeahead.tsx ~212 KB
|
||
7. cli/print.ts ~212 KB
|
||
8. tools/AgentTool/AgentTool.tsx ~233 KB
|
||
9. bootstrap/state.ts ~56 KB
|
||
10. state/AppStateStore.ts ~21 KB
|
||
11. services/autoDream/autoDream.ts ~11 KB
|
||
12. coordinator/coordinatorMode.ts ~19 KB
|
||
13. hooks/useCanUseTool.tsx ~40 KB
|
||
14. hooks/useGlobalKeybindings.tsx ~31 KB
|
||
15. hooks/useInboxPoller.ts ~34 KB
|
||
```
|
||
|
||
先读前 5 个，会 cover 80% 的系统复杂性。
|