深入剖析 Anthropic Claude Code CLI 的工作原理与核心机制
本仓库基于 2026-03-31 的 Claude Code 源码快照，持续补充中文原理解析文档，帮助开发者理解 AI Agent 的工作机制。快照完整性和已知限制见源码快照状态。
这是一套持续完善的 Claude Code 原理学习资料。通过分析当前源码快照，我们整理了从底层 API 交互到高级特性实现的系列文档。
适合人群
- 想要理解 AI Agent 工作原理的开发者
- 正在构建 AI 编程工具的团队
- 对 Tool Calling 和 Agentic Loop 感兴趣的研究者
- 希望学习大型 TypeScript 项目架构的工程师
Claude Code 展示了 AI Agent 的最佳实践：
- Agentic Loop - 如何让模型通过工具调用实现复杂任务
- 工具系统设计 - 按环境和功能开关动态组装工具，覆盖文件操作、命令执行、代码搜索等场景
- 上下文管理 - 如何在有限的 token 窗口内维持长对话
- 权限控制 - Hook 系统和权限机制的实现
- 动态加载 - 渐进式 Skills 发现和注入
| 文档 | 说明 |
|---|---|
| 总体架构 | 从 CLI 启动到 Query Loop、工具执行和持久化 |
| 整体运行流程 | 从用户输入到模型响应的完整流程 |
| Agentic Loop | 核心循环机制，理解这个就掌握 80% |
| 上下文窗口 | JSONL 存储、会话恢复、分支管理 |
| 文档 | 说明 |
|---|---|
| Compact 机制 | 上下文压缩策略，如何突破 token 限制 |
| System Prompt | 系统提示词的设计与动态组装 |
| 工具系统详解 | 内置工具的作用、参数、启用条件和实现原理 |
| Hook 机制 | 可扩展的拦截器设计 |
| 权限与沙箱 | 权限规则、执行模式和命令隔离 |
| MCP 集成 | 配置、传输、认证、动态工具、资源和生命周期 |
| 插件系统 | Marketplace、安装作用域、组件加载和运行时注入 |
| 会话与记忆 | JSONL、恢复、回退、文件快照和多层记忆 |
| Agents、任务与团队 | 子代理、后台任务、任务列表、团队通信和 Worktree |
| CLI 与配置体系 | 启动参数、设置层级、斜杠命令、环境变量和快捷键 |
| IDE、Remote 与 Handoff | IDE 发现、远程会话、Bridge、Remote Control 和桌面接力 |
| SDK、Headless 与 JSON | Print 模式、NDJSON 消息流、控制协议和 SDK 快照边界 |
| 认证与企业环境 | OAuth/API Key、云 Provider、代理、证书和 Managed Policy |
| 成本、Token 与隐私 | Usage、上下文、成本、Telemetry 和本地数据 |
| 跨平台差异 | Windows、PowerShell、WSL、路径、Sandbox 和终端差异 |
| 故障排查与开发 | 最小复现、Debug、分层排障和当前快照验证状态 |
| 源码快照状态 | 当前仓库的完整性、命令验证结果和适用范围 |
| 文档 | 说明 |
|---|---|
| Skills 设计 | 渐进式工具发现和动态注入 |
| 图片传输 | 如何传递截图和图像给模型 |
| WebSearch vs Fetch | 两个联网工具的区别 |
| TypeScript in Agent | 为什么 TS 适合构建 Agent |
- 阅读「整体运行流程」了解大局
- 深入「Agentic Loop」理解核心循环
- 查看「工具系统详解」了解具体能力
- 学习「上下文管理」掌握状态维护
- 研究「System Prompt 构成」
- 分析「Compact 机制」的压缩策略
- 理解「Hook 机制」的扩展性设计
- 学习「MCP 集成」与「插件系统」的扩展链路
- 理解「会话与记忆」以及「Agents、任务与团队」的状态边界
- 阅读「CLI 与配置体系」掌握不同配置入口和覆盖关系
- 结合「IDE、Remote 与 Handoff」理解本地和远程执行边界
- 通过「SDK、Headless 与 JSON」掌握程序化调用协议
- 用「认证与企业环境」和「成本、Token 与隐私」补齐生产运行边界
- 按「跨平台差异」和「故障排查与开发」验证目标环境
- 探索「Skills 设计」的动态加载
- 阅读源码，结合文档深入理解
while (true) {
const response = await callAPI(messages)
if (response.has_tool_use) {
const results = await executeTools(...)
messages = [...messages, response, results]
continue
}
return response
}关键理解：Claude 模型本身不能读文件、执行命令。Claude Code 代替模型执行工具，然后返回结果。
flowchart TD
A[用户输入] --> B[组装上下文]
B --> C[调用 API]
C --> D{tool_use?}
D -->|否| E[显示答案]
D -->|是| F[校验工具]
F --> G[检查权限]
G --> H[本地执行]
H --> I[返回结果]
I --> B
{"type":"user","content":"读取 package.json","uuid":"a1b2","parentUuid":null}
{"type":"assistant","content":[{"type":"tool_use","name":"Read"}],"uuid":"c3d4","parentUuid":"a1b2"}
{"type":"user","content":[{"type":"tool_result","content":"..."}],"uuid":"e5f6","parentUuid":"c3d4"}通过 parentUuid 形成链式结构，支持会话恢复、时间旅行、分支管理。
src/
├── entrypoints/ # CLI、SDK 和 MCP 入口
├── main.tsx # 参数解析、初始化和模式路由
├── query.ts # Agentic Loop 核心
├── tools/ # 工具实现（按环境和功能开关动态启用）
├── services/ # 模型 API、Compact、MCP 和工具执行服务
├── state/ # 应用状态
├── screens/ # 交互式终端界面
├── bridge/ # 远程服务桥接
└── utils/ # 会话、权限、设置与通用基础设施
- Bun >= 1.1.0（安装依赖或进行诊断时使用）
bun install当前快照适合源码阅读与机制研究，不应按可直接发布的完整工程理解。构建入口文件未包含在仓库中，类型检查和代码检查也存在快照级错误。实际验证结果见源码快照状态。
2026-03-31，@Fried_rice 发现 npm 包中的 .map 文件引用了完整的 TypeScript 源码。
"Claude code source code has been leaked via a map file in their npm registry!"
- 语言: TypeScript (strict)
- 运行时: Bun
- UI: React + Ink
- 架构: 事件驱动 + 工具系统
欢迎：
- 提交错误或改进建议
- 补充更多原理解析
- 分享学习心得
- 翻译成其他语言
- 仅用于教育和学习目的
- 源码版权归 Anthropic 所有
- 请勿用于商业用途
- 文档内容基于源码分析，可能存在偏差
如果这些文档对你有帮助，请给个 Star ⭐