第01章｜登台远望：Claude Code 底层技术全景导览
第01章｜登台远望：Claude Code 底层技术全景导览
学习目标：理解 Claude Code 的整体架构、核心组件及其工作原理，建立全局视野。
1.1 Claude Code 是什么？
Claude Code 是 Anthropic 官方推出的AI 编程助手 CLI 工具，它不是一个简单的代码补全插件，而是一个完整的AI Agent 系统。
传统 AI 编程工具 vs Claude Code
| 维度 | 传统 AI 编程工具（如 Copilot） | Claude Code |
|---|---|---|
| 工作方式 | 被动补全，等待触发 | 主动规划，自主执行 |
| 上下文范围 | 当前文件/光标附近 | 整个项目 + 外部工具 |
| 执行能力 | 只能生成代码 | 可读写文件、执行命令、调用 API |
| 任务复杂度 | 单步补全 | 多步骤复杂任务 |
| 协作模式 | 单一模型 | 多 Agent 协作 |
一句话定义
Claude Code =大语言模型+工具系统+Agent 循环+记忆系统+多智能体协作
1.2 核心架构：五层模型
Claude Code 的架构可以分为五个层次，从上到下依次是：
┌─────────────────────────────────────────────────────┐ │ 入口层 (Entry Layer) │ │ CLI 命令行界面 / VS Code 扩展 │ ├─────────────────────────────────────────────────────┤ │ 编排层 (Orchestration Layer) │ │ 命令系统(Commands) + 技能系统(Skills) │ ├─────────────────────────────────────────────────────┤ │ 查询引擎层 (Query Engine Layer) │ │ Agent Loop 核心循环 + 流式处理 │ ├─────────────────────────────────────────────────────┤ │ 工具层 (Tool Layer) │ │ 文件读写 | Bash执行 | 网络请求 | Agent派生 │ ├─────────────────────────────────────────────────────┤ │ 服务层 (Service Layer) │ │ Anthropic API | MCP服务 | Hooks | 记忆系统 │ └─────────────────────────────────────────────────────┘各层职责详解
🔵 入口层
用户与 Claude Code 交互的界面，支持：
- 终端 CLI：
claude命令直接启动 - VS Code 扩展：编辑器内嵌集成
- JetBrains 插件：IDE 集成
- Headless 模式：
claude -p "任务描述"无交互执行
🟢 编排层
负责解析用户意图，分发到对应的执行单元：
- Commands（命令系统）：内置命令如
/help、/compact，以及自定义斜杠命令 - Skills（技能系统）：可复用的工作流包，通过 SKILL.md 定义
🟡 查询引擎层（核心）
这是 Claude Code 的"大脑"，实现了Agent Loop（代理循环）：
用户输入 ↓ 预处理（注入上下文、记忆、规则） ↓ 调用 Claude API（claude-opus / claude-sonnet） ↓ 解析响应（文本 or 工具调用） ↓ 执行工具（如果有工具调用） ↓ 将工具结果反馈给模型 ↓ 重复直到任务完成 ↓ 输出最终结果🟠 工具层
Claude Code 内置了约 40+ 个工具，核心工具包括：
| 工具名 | 功能 |
|---|---|
Read | 读取文件内容 |
Write | 写入/创建文件 |
Edit | 精确编辑文件片段 |
Bash | 执行 Shell 命令 |
WebFetch | 抓取网页内容 |
WebSearch | 搜索网络信息 |
Agent | 派生子代理执行子任务 |
TodoRead/Write | 任务管理 |
🔴 服务层
底层基础设施：
- Anthropic API：模型推理服务
- MCP（Model Context Protocol）：外部工具扩展协议
- Hooks：生命周期事件系统
- 记忆系统：CLAUDE.md + 会话历史
1.3 Agent Loop 深度解析
Agent Loop 是 Claude Code 最核心的机制，理解它是理解一切的基础。
工作流程图
┌──────────────────────────────────────────────────┐ │ Agent Loop │ │ │ │ ① 接收用户消息 │ │ ↓ │ │ ② 构建完整 Prompt │ │ - System Prompt（规则+记忆+技能） │ │ - 历史对话 │ │ - 当前用户消息 │ │ ↓ │ │ ③ 调用 Claude API（流式） │ │ ↓ │ │ ④ 解析响应 │ │ ├── 纯文本 → 直接输出给用户 │ │ └── 工具调用 → 执行工具 │ │ ↓ │ │ ⑤ 执行工具并获取结果 │ │ ↓ │ │ ⑥ 将工具结果追加到对话历史 │ │ ↓ │ │ ⑦ 回到步骤③，继续循环 │ │ ↓ │ │ ⑧ 模型输出最终文本（无工具调用）→ 结束 │ └──────────────────────────────────────────────────┘实际案例：让 Claude Code 修复一个 Bug
用户输入：
帮我修复 src/auth.py 中的登录验证 bug，用户输入空密码时会崩溃Agent Loop 执行过程：
第1轮： 模型思考 → 决定先读取文件 工具调用：Read("src/auth.py") 工具返回：文件内容（含 bug 代码） 第2轮： 模型分析代码 → 找到 bug（未判断空密码） 工具调用：Edit("src/auth.py", old_code, new_code) 工具返回：编辑成功 第3轮： 模型决定验证修复 工具调用：Bash("python -m pytest tests/test_auth.py") 工具返回：测试通过 第4轮： 模型输出最终文本："已修复 auth.py 中的空密码崩溃问题..." 循环结束1.4 上下文窗口与 Token 管理
什么是上下文窗口？
Claude Code 使用的模型有固定的上下文窗口（Context Window），即模型一次能"看到"的最大 Token 数量。
上下文窗口 = System Prompt + 对话历史 + 工具结果 + 当前输入Claude 3.5 Sonnet / Claude 3 Opus 的上下文窗口约为200K tokens（约15万汉字）。
Token 消耗来源
┌─────────────────────────────────────┐ │ 上下文窗口 200K │ ├──────────────┬──────────────────────┤ │ System Prompt│ ~5K（规则+记忆+技能）│ ├──────────────┼──────────────────────┤ │ 对话历史 │ 随对话增长 │ ├──────────────┼──────────────────────┤ │ 工具结果 │ 文件内容+命令输出 │ ├──────────────┼──────────────────────┤ │ 当前输入 │ 用户消息 │ └──────────────┴──────────────────────┘自动压缩机制
当上下文接近上限时，Claude Code 会自动触发Compaction（压缩）：
- 将早期对话历史总结为摘要
- 保留关键信息，丢弃冗余细节
- 用
/compact命令可手动触发
1.5 Prompt Caching（提示词缓存）
原理
Anthropic API 支持对 System Prompt 进行缓存，相同的 System Prompt 在多次请求中只计算一次，后续请求直接复用缓存。
第1次请求： System Prompt（5K tokens）→ 全量计算 → 缓存 用户消息（100 tokens）→ 计算 第2次请求： System Prompt（5K tokens）→ 命中缓存，费用降低90% 用户消息（100 tokens）→ 计算对工程化的意义
- 降低成本：长 System Prompt 的重复计算费用大幅降低
- 提升速度：缓存命中时响应更快
- 鼓励丰富配置：可以在 CLAUDE.md 中写更详细的规则，不用担心成本
1.6 权限模型
Claude Code 有严格的权限控制，防止 AI 做出危险操作。
权限级别
| 级别 | 名称 | 说明 |
|---|---|---|
| 1 | default | 默认模式，危险操作需确认 |
| 2 | plan | 规划模式，只分析不执行 |
| 3 | auto | 自动模式，低风险操作自动执行 |
| 4 | yolo | 完全自动，所有操作无需确认（慎用） |
危险操作分类
高风险（默认需要确认）： - 删除文件 - 执行 rm -rf 类命令 - 修改系统配置 - 网络请求到外部服务 低风险（自动执行）： - 读取文件 - 运行测试 - 格式化代码 - 查看目录结构实际配置示例
# 以规划模式启动（只分析，不执行任何操作）claude--plan# 以自动模式启动（低风险操作自动执行）claude--auto# Headless 模式 + 自动确认（CI/CD 场景）claude-p"运行所有测试并修复失败的用例"--auto1.7 技术栈全景
Claude Code 本身的实现技术栈：
| 技术 | 用途 |
|---|---|
| TypeScript | 主语言（约1900+ 源文件） |
| Bun | 运行时（比 Node.js 更快） |
| React + Ink | 终端 UI 框架 |
| Yoga | 布局引擎（Flexbox in terminal） |
| Zod | Schema 验证 |
| Commander.js | CLI 参数解析 |
| MCP SDK | Model Context Protocol 客户端 |
| ripgrep | 高性能代码搜索 |
1.8 版本演进
| 版本 | 时间 | 核心变化 |
|---|---|---|
| v1.x | 2024 | 基础 CLI，文件读写，Bash 执行 |
| v2.0 | 2025 Q1 | Sub-Agents，Skills，Hooks，MCP |
| v2.1.x | 2025 Q2+ | Plan Mode，Sandbox 沙箱，自动 Compaction |
| v2.1.7+ | 2026 Q1 | Agent SDK，Plugins，Scheduled Tasks，Slack 集成 |
1.9 本章小结
| 核心概念 | 要点 |
|---|---|
| Claude Code 定位 | 完整 AI Agent 系统，不只是代码补全 |
| 五层架构 | 入口层→编排层→查询引擎层→工具层→服务层 |
| Agent Loop | 核心循环：接收→构建Prompt→调用API→执行工具→循环 |
| 上下文管理 | 200K Token 窗口，自动压缩，Prompt Caching |
| 权限模型 | default/plan/auto/yolo 四级权限 |
🧪 动手练习
安装 Claude Code：
npminstall-g@anthropic-ai/claude-code claude--version查看内置工具列表：
claude# 在交互界面输入：/tools体验 Agent Loop：
# 创建一个测试文件echo"def add(a, b): return a - b # bug: 应该是 +">test_math.py# 让 Claude Code 找到并修复 bugclaude-p"读取 test_math.py，找到其中的 bug 并修复它"观察 Token 使用：
# 开启详细模式，观察每次请求的 token 消耗claude--verbose
⬅️ 上一章：无
➡️ 下一章：第02章 - 记忆系统与 CLAUDE.md