diff --git a/docs/agent/coordinator-and-swarm.mdx b/docs/agent/coordinator-and-swarm.mdx
new file mode 100644
index 000000000..66249da0c
--- /dev/null
+++ b/docs/agent/coordinator-and-swarm.mdx
@@ -0,0 +1,58 @@
+---
+title: "协调者与蜂群"
+description: "从单兵作战到团队协作——多 Agent 的高级编排模式"
+---
+
+{/* 本章目标：介绍 Coordinator Mode 和 Agent Swarms */}
+
+## 两种协作模式
+
+子 Agent 是"临时帮手"——主 Agent 派出去做一件事就回来。对于更复杂的协作需求，Claude Code 提供了两种高级模式：
+
+## Coordinator Mode：一个指挥，多个执行
+
+就像一个团队 leader 带着几个开发者：
+
+- **Coordinator**（协调者）：负责理解需求、拆解任务、分配工作、汇总结果
+- **Workers**（执行者）：各自领取任务独立执行，通过邮箱向 Coordinator 汇报
+
+```
+ ┌─── Worker A (重构 API)
+ │
+Coordinator ──┼─── Worker B (更新测试)
+ │
+ └─── Worker C (更新文档)
+```
+
+Coordinator 不自己写代码，它的职责是**编排**——确保所有 Worker 的工作能拼合在一起。
+
+## Agent Swarms：蜂群式协作
+
+比 Coordinator 更松散的协作模式：
+
+- 多个 Agent 以对等身份同时工作
+- 没有中心化的指挥者
+- 通过消息邮箱互相通信和协调
+- 适合"各自负责一块、偶尔需要沟通"的场景
+
+## Teammate 机制
+
+进程内的"队友"——一种更轻量的协作方式：
+
+- 在同一个进程内运行，共享部分基础设施状态
+- 有独立的对话上下文和工具权限
+- 适合"我需要一个搭档帮忙看看这段代码"的场景
+
+## 任务类型
+
+支撑多 Agent 协作的是丰富的任务类型：
+
+| 任务类型 | 用途 |
+|----------|------|
+| **LocalAgentTask** | 本地子 Agent 任务 |
+| **LocalShellTask** | 后台 shell 命令 |
+| **InProcessTeammateTask** | 进程内队友 |
+| **RemoteAgentTask** | 远程 Agent |
+| **DreamTask** | 后台自主任务 |
+
+每种任务类型都有自己的生命周期管理、状态追踪和通信方式。
diff --git a/docs/agent/sub-agents.mdx b/docs/agent/sub-agents.mdx
new file mode 100644
index 000000000..b1b49c3c5
--- /dev/null
+++ b/docs/agent/sub-agents.mdx
@@ -0,0 +1,69 @@
+---
+title: "子 Agent：分身术"
+description: "当一个 AI 不够用时，它会召唤更多的自己"
+---
+
+{/* 本章目标：解释子 Agent 机制的设计和应用场景 */}
+
+## 为什么需要子 Agent
+
+有些任务太大，一个 AI 实例忙不过来：
+
+- "在 5 个不同的文件中分别找到并修复同类 bug"
+- "一边重构后端 API，一边更新前端调用"
+- "研究这个库的用法，同时修改我们的代码"
+
+## 分身术的运作方式
+
+Claude Code 中的 Agent 工具让 AI 能够**启动另一个 AI 实例**来处理子任务：
+
+
+
+ 主 Agent 判断任务可以被拆解为独立的子任务
+
+
+ 通过 Agent 工具创建一个或多个子 Agent，每个子 Agent 收到一个清晰的子任务描述
+
+
+ 多个子 Agent 可以同时工作，互不干扰
+
+
+ 子 Agent 完成后，结果返回给主 Agent，主 Agent 汇总并呈现给用户
+
+
+
+## 子 Agent 的边界
+
+子 Agent 不是和主 Agent 完全一样的——它有明确的能力边界：
+
+| 特性 | 主 Agent | 子 Agent |
+|------|---------|---------|
+| 可用工具 | 全部工具 | 受限子集（不能再启动子 Agent 等） |
+| 上下文 | 完整的会话历史 | 只有主 Agent 给的任务描述 |
+| 权限 | 用户设定 | 继承主 Agent 的权限，或更严格 |
+| 状态 | 可修改全局状态 | 隔离的状态空间 |
+
+## 通信方式
+
+主 Agent 和子 Agent 之间通过**消息邮箱**通信：
+
+- 主 Agent 通过 `Agent` 工具启动子 Agent
+- 子 Agent 通过 `SendMessage` 工具向主 Agent 报告进度
+- 这种松耦合的通信方式让 Agent 可以异步协作
+
+## 适用场景
+
+
+
+ 多个子 Agent 同时搜索不同方向的信息
+
+
+ 把大规模修改拆分到多个子 Agent 并行执行
+
+
+ 一个子 Agent 在后台运行测试，主 Agent 继续写代码
+
+
+ 在 worktree 中启动子 Agent 尝试一个方案，不影响主分支
+
+
diff --git a/docs/agent/worktree-isolation.mdx b/docs/agent/worktree-isolation.mdx
new file mode 100644
index 000000000..921134944
--- /dev/null
+++ b/docs/agent/worktree-isolation.mdx
@@ -0,0 +1,55 @@
+---
+title: "Worktree 隔离"
+description: "给子 Agent 一个独立的工作空间，互不污染"
+---
+
+{/* 本章目标：解释 git worktree 在多 Agent 协作中的作用 */}
+
+## 问题：多个 Agent 改同一份代码
+
+当多个 Agent 同时修改项目文件时，冲突在所难免：
+
+- Agent A 修改了 `config.ts`，Agent B 也在改同一个文件
+- Agent A 的测试需要某个状态，Agent B 的修改破坏了它
+- 半完成的修改混在一起，无法分辨哪些是哪个 Agent 做的
+
+## 解决方案：Git Worktree
+
+Git 原生支持 **worktree**（工作树）——在同一个仓库中创建多个独立的工作目录，每个目录在自己的分支上独立工作。
+
+Claude Code 利用这个特性为子 Agent 提供隔离的工作空间：
+
+| | 共享工作目录 | Worktree 隔离 |
+|---|---|---|
+| 文件冲突 | 多个 Agent 可能互相覆盖 | 每个 Agent 在自己的目录中工作 |
+| 分支 | 都在同一个分支上 | 每个 Agent 有自己的分支 |
+| 测试 | 互相干扰 | 完全独立 |
+| 合并 | 需要手动处理冲突 | 通过 git merge 有序合并 |
+
+## 工作流程
+
+
+
+ AI 启动带隔离模式的子 Agent，系统自动在 `.claude/worktrees/` 下创建新的工作目录
+
+
+ 子 Agent 在自己的 worktree 中自由修改文件、执行命令
+
+
+ 子 Agent 完成后，变更留在 worktree 的分支上
+
+
+ 主 Agent（或用户）决定：合并这些变更到主分支，还是丢弃
+
+
+ 不再需要的 worktree 会被自动清理
+
+
+
+## 安全网
+
+Worktree 还充当了一个安全网：
+
+- 子 Agent 的实验性修改不会影响主分支
+- 如果方案不可行，整个 worktree 可以直接丢弃
+- 多个方案可以在不同 worktree 中并行尝试，最后选最好的
diff --git a/docs/context/compaction.mdx b/docs/context/compaction.mdx
new file mode 100644
index 000000000..6ce3a7bfc
--- /dev/null
+++ b/docs/context/compaction.mdx
@@ -0,0 +1,63 @@
+---
+title: "上下文压缩"
+description: "对话太长怎么办——优雅地'遗忘'不重要的信息"
+---
+
+{/* 本章目标：解释 Compaction 机制的设计和策略 */}
+
+## 为什么需要压缩
+
+每次 API 调用的 token 有上限（通常 200K）。一场长时间的编程对话可能产生：
+
+- 大量的文件内容（AI 读了几十个文件）
+- 长篇的命令输出（构建日志、测试结果）
+- 往返的对话历史
+
+不压缩的话，很快就会撞到 token 上限，对话被迫终止。
+
+## 压缩的策略
+
+Claude Code 提供了多层压缩机制：
+
+
+
+ 当 token 接近上限时，系统自动触发压缩。AI 生成一份当前对话的**摘要**，替换掉早期的详细消息。效果就像人类的"记忆"——记住要点，忘记细节。
+
+
+ 用户可以随时通过 `/compact` 命令主动触发压缩。可以附带提示语（如 `/compact 聚焦在认证模块的修改上`），引导 AI 保留特定信息。
+
+
+ 更细粒度的局部压缩——不是压缩整个对话，而是压缩某些特别长的工具输出（比如一个 5000 行的测试日志）。
+
+
+
+## 压缩边界
+
+压缩后，系统在消息历史中插入一个"边界标记"。后续的 API 调用只发送边界之后的消息：
+
+```
+[早期的 50 条消息] ← 被压缩
+[压缩摘要边界] ← 一段浓缩的摘要
+[后续的 10 条消息] ← 正常发送
+```
+
+这个设计保证了：
+- 压缩后的摘要为 AI 提供了历史上下文
+- 新的对话不受旧消息的 token 负担
+- 用户无感知——对话继续自然进行
+
+## 压缩前后的 Hooks
+
+压缩是一个可能丢失信息的操作，因此系统允许用户在压缩前后执行自定义脚本：
+
+- **Pre-compact Hook**：压缩前执行，可以标记"这些信息不能丢"
+- **Post-compact Hook**：压缩后执行，可以验证关键信息是否保留
+
+## 什么信息会被保留
+
+压缩不是简单的截断，AI 会智能地决定保留什么：
+
+- 用户的核心需求和目标
+- 重要的决策和原因
+- 当前工作的状态（改了哪些文件、做到哪一步）
+- 之前犯过的错误（避免重蹈覆辙）
diff --git a/docs/context/project-memory.mdx b/docs/context/project-memory.mdx
new file mode 100644
index 000000000..a53a87398
--- /dev/null
+++ b/docs/context/project-memory.mdx
@@ -0,0 +1,58 @@
+---
+title: "项目记忆"
+description: "让 AI 跨对话记住你的偏好和项目上下文"
+---
+
+{/* 本章目标：解释记忆系统如何让 AI 变得'有记忆' */}
+
+## AI 的记忆困境
+
+大语言模型没有真正的记忆。每次新对话，它都是一张白纸。用户不得不反复解释"我的项目用 Bun 不用 Node"、"commit 消息用中文"。
+
+## 记忆系统的解决方案
+
+Claude Code 通过一个基于文件的持久化记忆系统来模拟"跨会话记忆"：
+
+
+
+ 关于用户的信息：角色、偏好、技术背景
+
+
+ 用户对 AI 行为的纠正和肯定
+
+
+ 项目中的非代码信息：谁负责什么、截止日期
+
+
+ 外部资源的位置：Issue tracker、Dashboard URL
+
+
+
+## 记忆的读写时机
+
+| 时机 | 动作 |
+|------|------|
+| 每次对话开始 | 加载记忆索引（MEMORY.md），相关记忆注入 System Prompt |
+| 用户纠正 AI | AI 自动判断是否值得记住，写入反馈记忆 |
+| 用户说"记住这个" | 立即保存到对应类型的记忆文件 |
+| 用户说"忘掉这个" | 找到并删除对应的记忆条目 |
+| 记忆可能过期时 | 使用前先验证（文件还在？函数还存在？），过期则更新或删除 |
+
+## 记忆 vs 代码注释 vs CLAUDE.md
+
+| | 记忆 | 代码注释 | CLAUDE.md |
+|---|---|---|---|
+| 存储位置 | `~/.claude/` 目录 | 代码文件中 | 项目目录中 |
+| 谁能看到 | 只有当前用户 | 所有开发者 | 所有使用 Claude Code 的人 |
+| 适合存什么 | 个人偏好、非公开的上下文 | 代码逻辑解释 | 项目约定、开发指南 |
+| 跨项目 | 是 | 否 | 否 |
+
+## 不该存什么
+
+记忆系统明确规定了不应存储的内容：
+
+- 代码结构和架构（读代码就知道）
+- git 历史（`git log` 就能查）
+- 调试方案（修复已在代码中）
+- CLAUDE.md 里已有的内容（避免重复）
+- 临时性任务状态（用任务系统）
diff --git a/docs/context/system-prompt.mdx b/docs/context/system-prompt.mdx
new file mode 100644
index 000000000..b0038b3e2
--- /dev/null
+++ b/docs/context/system-prompt.mdx
@@ -0,0 +1,53 @@
+---
+title: "System Prompt 的动态组装"
+description: "AI 的'工作记忆'是如何在每次对话前被精心拼装的"
+---
+
+{/* 本章目标：解释 System Prompt 的组装过程和设计思想 */}
+
+## 什么是 System Prompt
+
+每次调用 AI API 时，都需要发送一个 System Prompt——它是 AI 的"人设说明书"，告诉 AI：
+
+- 你是谁（Claude Code，一个编程助手）
+- 你能做什么（可用工具列表）
+- 你在什么环境（操作系统、当前目录、git 状态）
+- 你需要遵守什么规则（安全规范、输出格式）
+
+## 不是静态模板，而是动态组装
+
+Claude Code 的 System Prompt 不是一段写死的文本，而是根据当前环境**实时组装**的：
+
+| 组成部分 | 内容 | 来源 |
+|----------|------|------|
+| 基础人设 | 角色定义、行为准则 | 内置模板 |
+| 环境信息 | 操作系统、shell 类型、当前日期 | 运行时检测 |
+| Git 状态 | 当前分支、最近提交、工作区状态 | `git` 命令输出 |
+| 项目知识 | CLAUDE.md 文件内容 | 项目目录层级扫描 |
+| 记忆文件 | 用户偏好、项目约定 | 持久化记忆系统 |
+| 工具说明 | 每个可用工具的描述和参数 | 工具注册表 |
+
+## CLAUDE.md：项目级知识注入
+
+这是 Claude Code 最巧妙的设计之一。在项目根目录放一个 `CLAUDE.md` 文件，就能让 AI "理解" 你的项目：
+
+- **项目概述**：这个项目做什么、用了什么技术栈
+- **开发约定**：代码风格、命名规范、分支策略
+- **常用命令**：怎么构建、怎么测试、怎么部署
+- **注意事项**：已知的坑、特殊的配置
+
+系统会自动发现并合并多级 CLAUDE.md：
+
+```
+~/.claude/CLAUDE.md ← 用户全局（个人偏好）
+ └── /project/CLAUDE.md ← 项目根目录（团队共享）
+ └── /project/src/CLAUDE.md ← 子目录（模块特定）
+```
+
+## 缓存策略
+
+System Prompt 的 token 消耗不小（可能占总量的 30%+）。为了降低成本，系统使用了缓存机制：
+
+- 不变的部分（基础人设、工具说明）可以跨请求复用
+- 变化的部分（git 状态、记忆文件）每次重新生成
+- 缓存节点的位置经过精心设计，最大化缓存命中率
diff --git a/docs/context/token-budget.mdx b/docs/context/token-budget.mdx
new file mode 100644
index 000000000..768bf092b
--- /dev/null
+++ b/docs/context/token-budget.mdx
@@ -0,0 +1,55 @@
+---
+title: "Token 预算管理"
+description: "精打细算每一个 token——AI 的'注意力'是有限资源"
+---
+
+{/* 本章目标：解释 token 预算管理的思路 */}
+
+## Token 是什么
+
+简单理解：token 约等于一个英文单词或半个中文字。AI 处理的所有输入和输出都按 token 计费。
+
+| 类型 | 说明 | 谁付费 |
+|------|------|--------|
+| 输入 token | 发给 AI 的所有内容（System Prompt + 对话历史 + 工具结果） | 用户 |
+| 输出 token | AI 生成的回复和工具调用 | 用户 |
+| 缓存 token | 重复发送的内容如果命中缓存，价格更低 | 部分用户 |
+
+## 预算控制的三个层面
+
+
+
+ 每次 API 调用的最大输入/输出 token
+
+
+ 一个 Agentic Loop 内的累计 token 消耗
+
+
+ 全部对话轮次的累计花费（美元）
+
+
+
+## 工具输出的预算控制
+
+工具返回的内容可能非常长（一个大文件、一段长日志），直接全部塞给 AI 会浪费大量 token。系统对此有专门的控制：
+
+- **结果截断**：超过长度限制的工具输出自动截断
+- **结果替换**：已经被 AI"消化"过的旧工具结果，可以被替换为简短的摘要
+- **按需读取**：大文件不一次性读完，AI 可以指定读取范围
+
+## 缓存的经济学
+
+System Prompt 每次都要发送，但大部分内容不变。缓存机制让这部分"免费"（或大幅降价）：
+
+- 首次发送：全价
+- 后续请求命中缓存：约 1/10 的价格
+- 这就是为什么 System Prompt 的结构被精心设计——不变的部分放前面，变化的部分放后面
+
+## token 警告与自动压缩
+
+| token 使用率 | 系统行为 |
+|-------------|---------|
+| < 70% | 正常运行 |
+| 70% ~ 90% | 显示警告，提示用户可以手动压缩 |
+| > 90% | 自动触发压缩 |
+| 接近 100% | 强制压缩或终止当前轮次 |
diff --git a/docs/conversation/multi-turn.mdx b/docs/conversation/multi-turn.mdx
new file mode 100644
index 000000000..c90c9f757
--- /dev/null
+++ b/docs/conversation/multi-turn.mdx
@@ -0,0 +1,59 @@
+---
+title: "多轮对话管理"
+description: "一场跨越数小时的编程对话是如何被管理的"
+---
+
+{/* 本章目标：解释会话编排、持久化、成本追踪 */}
+
+## 单轮 vs 多轮
+
+- **单轮**（一次 Agentic Loop）：用户说一句 → AI 执行一系列操作 → 回答
+- **多轮**（一个 Session）：用户和 AI 来回对话几十轮，持续数小时
+
+多轮对话带来的挑战远超单轮：消息越来越多、token 不断累积、上下文逐渐模糊。
+
+## 会话编排器的职责
+
+在单轮 Agentic Loop 之上，有一个编排器负责管理整个会话生命周期：
+
+
+
+ 维护完整的消息历史，包括用户消息、AI 回复、工具调用结果
+
+
+ 自动保存对话记录到磁盘，支持断线重连、历史回顾
+
+
+ 在 AI 修改文件前自动保存快照，支持回滚
+
+
+ 精确记录每轮的 token 消耗和 API 费用
+
+
+
+## 会话恢复
+
+意外退出？网络断了？没关系：
+
+- 每轮对话结束后，完整的 transcript 会被写入磁盘
+- 下次启动时，可以选择恢复之前的对话
+- 恢复时，系统重建消息历史和上下文状态
+
+## 成本感知
+
+AI 编程助手的一个现实问题是**费用可能失控**。Claude Code 内建了多层成本控制：
+
+| 机制 | 作用 |
+|------|------|
+| Token 计数器 | 实时显示本次会话已消耗的输入/输出 token |
+| 费用估算 | 根据模型定价计算累计美元花费 |
+| 预算上限 | 用户可设定最大花费，到达后自动停止 |
+| 压缩提醒 | Token 接近上限时提示用户触发压缩 |
+
+## 模型切换
+
+在一个会话中，用户可以随时切换模型或调整参数：
+
+- `/model` 切换到不同的模型（Sonnet / Opus / Haiku）
+- `/fast` 切换快速模式
+- 模型切换不会丢失对话历史
diff --git a/docs/conversation/streaming.mdx b/docs/conversation/streaming.mdx
new file mode 100644
index 000000000..c592ab556
--- /dev/null
+++ b/docs/conversation/streaming.mdx
@@ -0,0 +1,50 @@
+---
+title: "流式响应：逐字呈现"
+description: "为什么 Claude Code 的回答是'打字机效果'而不是一整块弹出"
+---
+
+{/* 本章目标：解释流式通信的意义和它如何与工具执行交织 */}
+
+## 为什么需要流式
+
+想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
+
+流式响应让用户**实时看到 AI 的思考过程**：
+- 文字逐字出现，用户能提前判断方向是否正确
+- 工具调用的参数在生成过程中就能预览
+- 长时间任务不会让用户觉得"卡死了"
+
+## 流式与工具调用的交织
+
+一次 AI 响应中可能同时包含文字和工具调用。流式系统需要处理这种交织：
+
+```
+AI 开始输出文字 → "我来看看这个文件的内容..."
+AI 发出工具调用 → [FileRead: src/main.ts]
+ ↓ 暂停流式输出
+ 工具执行中...
+ 结果返回给 AI
+ ↓ 恢复流式输出
+AI 继续输出 → "这个文件里有一个 bug，第 42 行..."
+AI 发出下一个工具调用 → [FileEdit: src/main.ts]
+```
+
+## 流式工具执行
+
+更进阶的是，**工具本身的执行也可以是流式的**：
+
+- 运行一个长命令（比如 `npm install`），输出逐行显示
+- 搜索大型项目时，匹配结果逐条呈现
+- AI 在等待工具结果的同时，已经开始规划下一步
+
+## 多 Provider 适配
+
+Claude Code 支持多个 AI 服务提供商，每个提供商的流式协议略有不同：
+
+| Provider | 特点 |
+|----------|------|
+| Anthropic Direct | 原生 SSE 流，延迟最低 |
+| AWS Bedrock | 通过 AWS SDK 包装的流式接口 |
+| Google Vertex | gRPC 流转换为事件流 |
+
+系统通过统一的事件抽象层屏蔽这些差异——上层代码不需要关心底层用的是哪个 Provider。
diff --git a/docs/conversation/the-loop.mdx b/docs/conversation/the-loop.mdx
new file mode 100644
index 000000000..4b09ff503
--- /dev/null
+++ b/docs/conversation/the-loop.mdx
@@ -0,0 +1,66 @@
+---
+title: "Agentic Loop：对话的心跳"
+description: "AI 不只回答问题，它会反复思考-行动-观察，直到任务完成"
+---
+
+{/* 本章目标：解释 Agentic Loop 这个核心机制 */}
+
+## 什么是 Agentic Loop
+
+传统聊天机器人：你问一句，它答一句。
+Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
+
+这背后的机制叫做 **Agentic Loop**（智能体循环）：
+
+{/* TODO: 插入 Loop 示意图 */}
+
+
+
+ AI 分析当前上下文，决定下一步该做什么
+
+
+ AI 发出工具调用请求（比如"读取这个文件"、"执行这条命令"）
+
+
+ 工具执行完毕，结果回传给 AI
+
+
+ AI 根据观察结果决定：继续下一步操作，还是任务已完成、直接回答用户
+
+
+
+## 一个真实的例子
+
+> 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
+
+AI 的内部过程：
+
+1. **思考**：我需要先了解项目结构 → **行动**：调用 Glob 工具扫描所有源文件
+2. **观察**：拿到文件列表 → **思考**：逐个检查 → **行动**：调用 Grep 搜索 import 语句
+3. **观察**：发现 3 个文件有未使用导入 → **行动**：调用 FileEdit 逐个删除
+4. **观察**：编辑成功 → **结束**：告诉用户"已清理 3 个文件中的 5 条未使用导入"
+
+整个过程可能涉及 10+ 次工具调用，但用户只需要说一句话。
+
+## 为什么不是"一次规划，批量执行"
+
+
+一个常见的替代方案是：AI 先生成一个完整的计划，然后一次性执行所有步骤。Claude Code 选择了逐步循环，原因是：
+
+
+- **每一步都能看到真实结果**：文件内容、命令输出、错误信息——这些只有执行后才知道
+- **动态调整**：如果第 3 步发现了意外情况，AI 可以立刻改变策略
+- **错误恢复**：某步失败了，AI 可以当场诊断和修复，不需要推倒重来
+- **用户可控**：用户可以在任何一步中断，AI 的循环不会失控
+
+## 循环的终止条件
+
+Agentic Loop 不会无限运行，以下情况会让循环停止：
+
+| 条件 | 说明 |
+|------|------|
+| AI 主动结束 | AI 判断任务完成，返回纯文本回答（不再调用工具） |
+| 用户中断 | 用户按 Ctrl+C 或 ESC 打断当前操作 |
+| Token 预算耗尽 | 单轮对话的 token 用量达到上限 |
+| 输出过长自动续写 | AI 回复被截断时，系统自动发起续写请求（有次数上限） |
+| 成本上限 | 累计 API 花费超过用户设定的预算 |
diff --git a/docs/extensibility/custom-agents.mdx b/docs/extensibility/custom-agents.mdx
new file mode 100644
index 000000000..6c865a63f
--- /dev/null
+++ b/docs/extensibility/custom-agents.mdx
@@ -0,0 +1,56 @@
+---
+title: "自定义 Agent"
+description: "定义你自己的 AI 角色——不同的人格、能力和边界"
+---
+
+{/* 本章目标：解释自定义 Agent 定义的设计 */}
+
+## 为什么需要自定义 Agent
+
+默认的 Claude Code 是一个"全能型"助手。但有些场景需要更专门化的角色：
+
+- 一个只负责代码审查、不会修改代码的 Agent
+- 一个专门处理 DevOps 任务的 Agent
+- 一个面向初学者、回答更详细的 Agent
+
+## Agent 定义
+
+自定义 Agent 通过 Markdown 文件定义，放在 `.claude/agents/` 目录：
+
+| 配置项 | 说明 |
+|--------|------|
+| **名称** | Agent 的标识和显示名 |
+| **描述** | 这个 Agent 的职责说明 |
+| **System Prompt** | 自定义的角色指令——替换或追加到默认 System Prompt |
+| **允许的工具** | 这个 Agent 可以使用哪些工具 |
+| **模型** | 使用哪个 AI 模型 |
+
+## 与子 Agent 的关系
+
+自定义 Agent 可以作为子 Agent 被启动：
+
+- 主 Agent 说"这个任务需要安全审查"
+- 系统启动一个自定义的"安全审查 Agent"
+- 该 Agent 只有阅读权限，使用专门的安全审查 Prompt
+
+这实现了**角色分离**——不同的任务由不同"人格"的 Agent 处理。
+
+## 复用与共享
+
+
+
+ 放在项目的 `.claude/agents/` 目录，团队所有人可用
+
+
+ 放在 `~/.claude/agents/` 目录，跨项目可用
+
+
+
+## 实际应用
+
+| Agent | 角色 | 工具限制 |
+|-------|------|---------|
+| `reviewer` | 代码审查员 | 只允许 Read、Glob、Grep |
+| `devops` | DevOps 工程师 | 允许 Bash，限制在 infra/ 目录 |
+| `tutor` | 编程导师 | 全部工具，但 Prompt 强调教学 |
+| `security` | 安全审计员 | 只允许搜索和阅读，输出安全报告 |
diff --git a/docs/extensibility/hooks.mdx b/docs/extensibility/hooks.mdx
new file mode 100644
index 000000000..24ce17c60
--- /dev/null
+++ b/docs/extensibility/hooks.mdx
@@ -0,0 +1,72 @@
+---
+title: "Hooks：生命周期钩子"
+description: "在 AI 的关键行为节点插入你自己的逻辑"
+---
+
+{/* 本章目标：解释 Hooks 系统的设计和应用场景 */}
+
+## 什么是 Hooks
+
+Hooks 是用户定义的 shell 命令，在 Claude Code 生命周期的特定时刻自动执行。
+
+类比：React 的 `useEffect` 让你在组件渲染后执行自定义逻辑。Claude Code 的 Hooks 让你在 AI 的关键行为前后执行自定义脚本。
+
+## 可用的 Hook 事件
+
+| 事件 | 触发时机 | 典型用途 |
+|------|---------|---------|
+| **PreToolUse** | 工具调用前 | 拦截危险操作、自定义审批逻辑 |
+| **PostToolUse** | 工具调用后 | 记录日志、触发通知、自动格式化 |
+| **PreCompact** | 上下文压缩前 | 标记不可丢失的信息 |
+| **PostCompact** | 上下文压缩后 | 验证关键信息是否保留 |
+| **Notification** | AI 发出通知时 | 自定义通知渠道（Slack、邮件等） |
+| **StopFailure** | AI 循环异常停止时 | 自定义错误处理 |
+
+## Hook 的能力
+
+Hook 脚本不仅能"观察"，还能"干预"：
+
+
+
+ 返回特定信号可以阻止工具调用执行
+
+
+ 返回结构化的 JSON 输出，影响 Claude Code 的后续行为
+
+
+ 向 AI 的对话中注入额外信息
+
+
+ 调用 CI/CD、发送通知、更新 Issue tracker
+
+
+
+## 配置方式
+
+Hooks 在 `settings.json` 中配置：
+
+```json
+{
+ "hooks": {
+ "PostToolUse": [
+ {
+ "matcher": { "tool_name": "Write" },
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx prettier --write $CLAUDE_FILE_PATH"
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+这个例子：每当 AI 写入一个文件后，自动用 Prettier 格式化。
+
+## 安全控制
+
+- 托管设置（企业管理员）的 Hooks 优先级最高，用户不能覆盖
+- Hook 执行有超时限制
+- Hook 的输出会被解析和验证，防止注入攻击
diff --git a/docs/extensibility/mcp-protocol.mdx b/docs/extensibility/mcp-protocol.mdx
new file mode 100644
index 000000000..20e432681
--- /dev/null
+++ b/docs/extensibility/mcp-protocol.mdx
@@ -0,0 +1,75 @@
+---
+title: "MCP：开放的工具生态"
+description: "通过标准协议对接任何外部能力——数据库、API、自定义服务"
+---
+
+{/* 本章目标：解释 MCP 协议如何扩展 AI 的能力边界 */}
+
+## 内置工具的局限
+
+Claude Code 内置了 50+ 工具，覆盖了通用的软件开发需求。但每个团队都有特殊需求：
+
+- 连接内部数据库查询数据
+- 调用公司内部 API
+- 操作特定的 DevOps 工具
+- 访问私有的知识库
+
+不可能把所有人的需求都内置进去。
+
+## MCP：一个标准的"插头"
+
+**Model Context Protocol**（模型上下文协议）是 Anthropic 提出的开放标准，定义了 AI 与外部工具之间的通信方式。
+
+类比：USB 是电脑连接外设的标准接口。MCP 是 AI 连接外部能力的标准接口。
+
+## 工作原理
+
+
+
+ 开发者编写一个 MCP Server，暴露自定义工具（比如"查询数据库"、"发送 Slack 消息"）
+
+
+ 在配置文件中声明要连接的 MCP Server
+
+
+ 连接后，MCP Server 提供的工具自动出现在 AI 的可用工具列表中
+
+
+ AI 像使用内置工具一样使用 MCP 工具——无需知道底层实现
+
+
+
+## 三种连接方式
+
+| 方式 | 适用场景 |
+|------|---------|
+| **stdio** | MCP Server 作为子进程运行，通过标准输入/输出通信。最简单 |
+| **SSE** | 通过 HTTP Server-Sent Events 通信。适合远程服务 |
+| **StreamableHTTP** | 基于 HTTP 流的双向通信。适合复杂的交互场景 |
+
+## 权限一视同仁
+
+MCP 提供的工具和内置工具一样受权限系统管控：
+
+- 需要用户确认才能调用
+- 可以设置 allow/deny 规则
+- 支持沙箱限制
+
+这确保了第三方工具不会绕过安全边界。
+
+## 实际例子
+
+```json
+// settings.json 中的 MCP 配置
+{
+ "mcpServers": {
+ "my-database": {
+ "command": "npx",
+ "args": ["@my-org/db-mcp-server"],
+ "env": { "DB_URL": "postgres://..." }
+ }
+ }
+}
+```
+
+配置后，AI 就多了"查询数据库"这个能力——用自然语言描述需求，AI 自动生成查询并执行。
diff --git a/docs/extensibility/skills.mdx b/docs/extensibility/skills.mdx
new file mode 100644
index 000000000..3b13c0258
--- /dev/null
+++ b/docs/extensibility/skills.mdx
@@ -0,0 +1,60 @@
+---
+title: "Skills：预制的能力包"
+description: "把常用的工作流封装成可复用的技能"
+---
+
+{/* 本章目标：解释 Skills 系统的设计思想 */}
+
+## Tool vs Skill
+
+| | Tool | Skill |
+|---|---|---|
+| 粒度 | 单个原子操作（读文件、执行命令） | 一套完整的工作流（代码审查、创建 PR） |
+| 触发方式 | AI 自主选择 | 用户主动调用（`/skill-name`）或 AI 根据场景推荐 |
+| 本质 | 执行逻辑 | 预制的 Prompt + 工具权限配置 |
+
+## Skill 的三个来源
+
+
+
+ 编译进 CLI 的技能包。如 `/commit`、`/review`、`/debug`
+
+
+ 项目 `.claude/skills/` 目录中的 Markdown 文件。团队共享
+
+
+ 通过 MCP Server 提供的技能。动态发现
+
+
+
+## 一个 Skill 包含什么
+
+每个 Skill 本质上是一个"AI 行为的预设"：
+
+| 组成部分 | 作用 |
+|----------|------|
+| **名称和描述** | 告诉 AI 和用户这个技能做什么 |
+| **whenToUse** | 什么场景下应该使用这个技能（AI 据此自动推荐） |
+| **Prompt 模板** | 注入给 AI 的详细指令——相当于"操作手册" |
+| **allowedTools** | 这个技能允许使用哪些工具（能力边界） |
+| **model** | 可选指定使用的模型 |
+
+## 设计精妙之处
+
+Skill 的核心洞见是：**很多复杂任务的关键不在于代码逻辑，而在于 Prompt 的质量**。
+
+一个好的代码审查，不是写了什么代码来审查，而是：
+- 告诉 AI 审查的标准是什么
+- 告诉 AI 按什么顺序审查
+- 告诉 AI 输出什么格式的报告
+- 限制 AI 只能用读取类工具（不要边审查边改代码）
+
+Skill 把这些"经验"封装起来，任何人都能一键调用。
+
+## 技能发现
+
+当可用技能很多时，AI 可以通过 **SkillTool** 搜索匹配的技能：
+
+- 用户说"帮我做代码审查"
+- AI 搜索已注册的技能，发现 `code-review` 匹配
+- AI 调用该技能，按预设的流程执行
diff --git a/docs/introduction/architecture-overview.mdx b/docs/introduction/architecture-overview.mdx
new file mode 100644
index 000000000..a2e34a485
--- /dev/null
+++ b/docs/introduction/architecture-overview.mdx
@@ -0,0 +1,59 @@
+---
+title: "架构全景"
+description: "五层架构，一条数据流"
+---
+
+{/* 本章目标：一张图讲清楚整体架构，为后续章节建立坐标系 */}
+
+## 五层架构
+
+Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
+
+| 层次 | 职责 | 关键词 |
+|------|------|--------|
+| **交互层** | 终端 UI、用户输入、消息展示 | React/Ink、REPL |
+| **编排层** | 管理多轮对话、会话生命周期、成本追踪 | QueryEngine、会话持久化 |
+| **核心循环层** | 单轮对话：发请求 → 拿响应 → 执行工具 → 再发请求 | Agentic Loop |
+| **工具层** | AI 的"双手"——读写文件、执行命令、搜索代码 | Tool System、MCP |
+| **通信层** | 与 Claude API 的流式通信、多云 Provider 适配 | Streaming、Bedrock/Vertex |
+
+## 一条主数据流
+
+{/* TODO: 插入数据流序列图 */}
+
+整个系统的运转可以浓缩为一条核心数据流：
+
+
+
+ 用户在终端键入自然语言需求
+
+
+ 系统自动拼接项目信息、git 状态、配置文件、记忆，形成完整的 System Prompt
+
+
+ 将 System Prompt + 对话历史发送给 Claude API，流式接收响应
+
+
+ 若 AI 返回工具调用请求 → 权限检查 → 执行工具 → 结果回传 → AI 继续思考 → 循环
+
+
+ AI 不再调用工具，输出最终回答，等待用户下一条输入
+
+
+
+## 四个核心设计原则
+
+
+
+ 所有 API 通信都是流式的——用户看到 AI "逐字打出"回答，而不是等待完整响应。工具执行结果也实时反馈。这不仅提升体验，更是处理长时间任务的工程必需。
+
+
+ AI 的每一项"动手能力"都被抽象为一个 Tool。想让 AI 能做新事情？注册一个新 Tool 就好。统一的接口让能力可插拔、可组合。
+
+
+ AI 能操作真实环境是强大的，也是危险的。每个工具调用都经过权限系统的裁决——该放行的自动放行，该拦截的坚决拦截。
+
+
+ AI 没有真正的记忆，但通过精心的 System Prompt 组装、对话压缩、持久化记忆文件，系统营造出"AI 理解你的项目"的效果。这是上下文工程的核心。
+
+
diff --git a/docs/introduction/what-is-claude-code.mdx b/docs/introduction/what-is-claude-code.mdx
new file mode 100644
index 000000000..e89c46481
--- /dev/null
+++ b/docs/introduction/what-is-claude-code.mdx
@@ -0,0 +1,37 @@
+---
+title: "什么是 Claude Code"
+description: "一个住在终端里的 AI 编程搭档"
+---
+
+{/* 本章目标：让完全不了解 Claude Code 的读者在 3 分钟内建立直觉 */}
+
+## 一句话定义
+
+Claude Code 是一个运行在命令行终端里的 AI 编程助手。你用自然语言描述需求，它直接帮你读代码、改文件、跑命令、搜索项目——全部在你的本地环境中完成。
+
+## 它能做什么
+
+- **对话式编程**：像和同事聊天一样描述需求，AI 直接动手实现
+- **理解整个项目**：自动读取项目结构、git 历史、配置文件，建立项目全景认知
+- **操作你的电脑**：读写文件、执行 shell 命令、搜索代码——不只是给建议，而是真正动手
+- **保护你的安全**：每个敏感操作都需要你确认，有沙箱、有权限管控
+
+## 它和 ChatGPT / 普通聊天机器人的区别
+
+| | 普通聊天 AI | Claude Code |
+|---|---|---|
+| 运行环境 | 云端网页 | 你的本地终端 |
+| 能做什么 | 回答问题、生成文本 | 直接操作你的项目文件和命令行 |
+| 项目理解 | 你需要手动粘贴代码 | 自动读取整个项目上下文 |
+| 安全性 | 无需考虑 | 多层权限保护 |
+
+## 一次典型的交互流程
+
+{/* TODO: 插入一张交互流程示意图 */}
+
+1. 你在终端输入自然语言需求
+2. Claude Code 分析你的项目上下文
+3. 它决定使用哪些工具（读文件？执行命令？）
+4. 每个操作请求你确认（或根据规则自动放行）
+5. 执行完成后，把结果反馈给 AI，AI 决定下一步
+6. 循环，直到任务完成
diff --git a/docs/introduction/why-this-whitepaper.mdx b/docs/introduction/why-this-whitepaper.mdx
new file mode 100644
index 000000000..cf92e6473
--- /dev/null
+++ b/docs/introduction/why-this-whitepaper.mdx
@@ -0,0 +1,40 @@
+---
+title: "为什么写这份白皮书"
+description: "将 LLM 能力落地到真实工作流的工程范本"
+---
+
+{/* 本章目标：解释为什么这个项目的架构值得深入研究 */}
+
+## 不只是一个聊天工具
+
+Claude Code 解决的核心问题是：**如何让大语言模型从"能说会道"变成"能说会做"**。
+
+这不是简单地给 AI 套一个 shell。它涉及一系列精巧的工程决策：
+
+- AI 说"我要编辑这个文件"时，如何确保安全？
+- 对话越来越长，token 快爆了怎么办？
+- AI 需要并行处理多个子任务时，如何隔离和协调？
+- 用户想扩展 AI 的能力（接数据库、连 API），如何设计插拔机制？
+
+## 这份白皮书关注什么
+
+
+
+ 不堆代码，从"用户能做什么、AI 如何决策"出发
+
+
+ 每个功能背后的"为什么这样设计"
+
+
+ 可复用的模式：Agentic Loop、工具抽象、上下文工程
+
+
+ AI 操作真实环境时的信任与控制平衡
+
+
+
+## 适合谁读
+
+- 想理解 AI Agent 产品架构的开发者
+- 正在构建类似工具的团队
+- 对 LLM 应用工程化感兴趣的任何人
diff --git a/docs/mint.json b/docs/mint.json
new file mode 100644
index 000000000..cd66406b6
--- /dev/null
+++ b/docs/mint.json
@@ -0,0 +1,84 @@
+{
+ "$schema": "https://mintlify.com/schema.json",
+ "name": "Claude Code Architecture",
+ "logo": {
+ "dark": "/logo/dark.svg",
+ "light": "/logo/light.svg"
+ },
+ "favicon": "/favicon.svg",
+ "colors": {
+ "primary": "#D97706",
+ "light": "#F59E0B",
+ "dark": "#B45309",
+ "background": {
+ "dark": "#0F172A",
+ "light": "#FFFFFF"
+ }
+ },
+ "navigation": [
+ {
+ "group": "开始",
+ "pages": [
+ "introduction/what-is-claude-code",
+ "introduction/why-this-whitepaper",
+ "introduction/architecture-overview"
+ ]
+ },
+ {
+ "group": "对话是如何运转的",
+ "pages": [
+ "conversation/the-loop",
+ "conversation/streaming",
+ "conversation/multi-turn"
+ ]
+ },
+ {
+ "group": "工具：AI 的双手",
+ "pages": [
+ "tools/what-are-tools",
+ "tools/file-operations",
+ "tools/shell-execution",
+ "tools/search-and-navigation",
+ "tools/task-management"
+ ]
+ },
+ {
+ "group": "安全与权限",
+ "pages": [
+ "safety/why-safety-matters",
+ "safety/permission-model",
+ "safety/sandbox",
+ "safety/plan-mode"
+ ]
+ },
+ {
+ "group": "上下文工程",
+ "pages": [
+ "context/system-prompt",
+ "context/project-memory",
+ "context/compaction",
+ "context/token-budget"
+ ]
+ },
+ {
+ "group": "多 Agent 协作",
+ "pages": [
+ "agent/sub-agents",
+ "agent/worktree-isolation",
+ "agent/coordinator-and-swarm"
+ ]
+ },
+ {
+ "group": "可扩展性",
+ "pages": [
+ "extensibility/mcp-protocol",
+ "extensibility/hooks",
+ "extensibility/skills",
+ "extensibility/custom-agents"
+ ]
+ }
+ ],
+ "footerSocials": {
+ "github": "https://github.com/anthropics/claude-code"
+ }
+}
diff --git a/docs/safety/permission-model.mdx b/docs/safety/permission-model.mdx
new file mode 100644
index 000000000..7308a6054
--- /dev/null
+++ b/docs/safety/permission-model.mdx
@@ -0,0 +1,64 @@
+---
+title: "权限模型"
+description: "三种行为 x 多级来源 = 灵活而严谨的权限体系"
+---
+
+{/* 本章目标：详解权限系统的设计 */}
+
+## 三种权限行为
+
+每一次工具调用，系统都会做出三种裁决之一：
+
+| 行为 | 含义 | 典型场景 |
+|------|------|---------|
+| **Allow** | 自动放行，用户无感知 | Read 工具读取项目内的文件 |
+| **Ask** | 弹出确认对话框，等待用户决定 | Bash 执行一条未知命令 |
+| **Deny** | 直接拒绝，AI 收到"权限被拒"的反馈 | 尝试执行被禁止的命令 |
+
+## 权限规则的层级
+
+规则可以来自多个来源，优先级从高到低：
+
+
+
+ 用户在当前对话中手动授权的（"对这个工具始终允许"）
+
+
+ 项目目录中的 `.claude/settings.json`，团队共享
+
+
+ `~/.claude/settings.json`，跨项目生效
+
+
+ 企业管理员下发的策略，用户不可覆盖
+
+
+ 系统内置的基线规则
+
+
+
+## 规则的匹配方式
+
+权限规则不是简单的"允许/禁止某个工具"，它支持丰富的匹配条件：
+
+- **工具名匹配**：`"tool": "Bash"` → 针对所有 Bash 命令
+- **命令模式匹配**：`"command": "git *"` → 只针对 git 开头的命令
+- **路径匹配**：`"path": "src/**"` → 只允许操作 src 目录下的文件
+- **组合条件**：以上条件可以组合使用
+
+## 权限模式
+
+系统提供几种预设的权限模式，适应不同信任级别：
+
+| 模式 | 适用场景 |
+|------|---------|
+| **Default** | 日常使用，敏感操作逐一确认 |
+| **Plan Mode** | 探索阶段，AI 只能读不能写 |
+| **Bypass** | 完全信任 AI，所有操作自动放行（需显式开启） |
+
+## Denial Tracking
+
+系统不仅记录"允许了什么"，还追踪"拒绝了什么"：
+
+- 如果 AI 被连续拒绝多次同一类操作，系统会调整策略
+- 这防止 AI 陷入"反复请求同一个被拒操作"的死循环
diff --git a/docs/safety/plan-mode.mdx b/docs/safety/plan-mode.mdx
new file mode 100644
index 000000000..2a4af81bd
--- /dev/null
+++ b/docs/safety/plan-mode.mdx
@@ -0,0 +1,60 @@
+---
+title: "计划模式"
+description: "先看后做——给 AI 一个只读的探索阶段"
+---
+
+{/* 本章目标：解释 Plan Mode 的设计理念 */}
+
+## 问题场景
+
+你说"重构这个模块"，AI 立刻开始改代码——但你还没搞清楚它打算怎么改。等改了一半发现方向不对，已经来不及了。
+
+## Plan Mode 的解决方案
+
+计划模式给对话加了一个"只读阶段"：
+
+
+
+ AI 自主判断任务需要规划（或用户主动触发），进入计划模式
+
+
+ 在这个阶段，AI 只能使用读取和搜索类工具——不能编辑文件、不能执行命令
+
+
+ AI 把理解和方案写入计划文件，提交给用户审阅
+
+
+ 用户阅读计划，提出修改意见或直接批准
+
+
+ 计划被批准后，AI 恢复全部工具权限，按计划执行
+
+
+
+## 权限的自动收窄与恢复
+
+计划模式的精妙之处在于**自动改变权限上下文**：
+
+- 进入时：系统自动保存当前权限模式，切换为"只读"
+- 退出时：系统自动恢复之前的权限模式
+
+AI 和用户都不需要手动调整权限设置。
+
+## 什么时候该用计划模式
+
+| 场景 | 是否需要计划 |
+|------|-------------|
+| 修复一个明确的 typo | 不需要，直接修 |
+| 添加一个简单的函数 | 不需要 |
+| 重构一个大模块 | 需要——先搞清楚影响范围 |
+| 涉及多个文件的 feature | 需要——先统一方案 |
+| 不确定该怎么做 | 需要——让 AI 先调研 |
+
+## 计划模式 + 任务系统
+
+计划模式通常与任务系统配合使用：
+
+1. 在计划模式中，AI 把实施步骤创建为任务列表
+2. 用户审批计划（包含任务列表）
+3. 退出计划模式后，AI 按任务列表逐项执行
+4. 用户可以通过任务列表追踪进度
diff --git a/docs/safety/sandbox.mdx b/docs/safety/sandbox.mdx
new file mode 100644
index 000000000..af51068f3
--- /dev/null
+++ b/docs/safety/sandbox.mdx
@@ -0,0 +1,35 @@
+---
+title: "沙箱机制"
+description: "即使命令被允许执行，也不意味着它可以为所欲为"
+---
+
+{/* 本章目标：解释沙箱的作用和原理 */}
+
+## 权限之外的第二道防线
+
+权限系统决定"这条命令能不能执行"，沙箱决定"执行时能做到什么程度"。
+
+即使一条命令通过了权限审批，沙箱仍然可以限制它的行为：
+
+| 限制维度 | 说明 |
+|----------|------|
+| **文件系统** | 只能访问项目目录及其子目录 |
+| **网络** | 可以禁止或限制网络访问 |
+| **进程** | 限制可启动的子进程 |
+| **时间** | 超时自动终止 |
+
+## 何时启用沙箱
+
+沙箱不是默认对所有命令生效——它根据风险评估动态决定：
+
+- 用户显式请求禁用沙箱的命令（`dangerouslyDisableSandbox`）不走沙箱
+- 已通过安全规则白名单的命令可以跳过沙箱
+- 未知命令或高风险命令强制进入沙箱
+
+## 沙箱的实现思路
+
+不同平台使用不同的沙箱技术：
+
+- **macOS**：利用系统级沙箱机制限制文件和网络访问
+- **Linux**：基于命名空间和 cgroup 的进程隔离
+- 沙箱策略由系统自动选择，用户不需要手动配置
diff --git a/docs/safety/why-safety-matters.mdx b/docs/safety/why-safety-matters.mdx
new file mode 100644
index 000000000..b8fb9caac
--- /dev/null
+++ b/docs/safety/why-safety-matters.mdx
@@ -0,0 +1,40 @@
+---
+title: "为什么安全至关重要"
+description: "当 AI 能操作你的电脑，信任的边界在哪里"
+---
+
+{/* 本章目标：建立安全意识，解释为什么需要这么多安全机制 */}
+
+## AI 动手的代价
+
+Claude Code 不是在沙盒里回答问题——它在你的真实项目中修改文件、执行命令。一个失误可能意味着：
+
+- 覆盖了你还没提交的工作
+- 执行了危险的 `rm -rf` 命令
+- 推送了包含 bug 的代码到远程仓库
+- 泄露了 `.env` 文件中的密钥
+
+## 安全设计的核心理念
+
+
+
+ AI 默认没有任何"动手"权限，每项能力都需要显式授予
+
+
+ 优先执行可逆操作（读文件、搜索），对不可逆操作（删除、推送）严格审批
+
+
+ 关键操作必须经过人类确认，AI 不能绕过用户自行决定
+
+
+ 多层安全机制叠加——权限规则、沙箱、计划模式、预算上限——任何一层都能阻止危险操作
+
+
+
+## 安全 vs 效率的平衡
+
+如果每个操作都要确认，AI 就变成了一个不停弹窗的烦人助手。Claude Code 的设计在安全和效率之间找到了平衡：
+
+- **低风险操作自动放行**：读取文件、搜索代码——这些不会改变任何东西
+- **中风险操作规则放行**：编辑指定目录的文件——用户可以预设"允许"规则
+- **高风险操作人工确认**：删除文件、执行未知命令——必须手动审批
diff --git a/docs/tools/file-operations.mdx b/docs/tools/file-operations.mdx
new file mode 100644
index 000000000..f5d4007d0
--- /dev/null
+++ b/docs/tools/file-operations.mdx
@@ -0,0 +1,54 @@
+---
+title: "文件操作"
+description: "AI 如何安全、高效地读写你的代码"
+---
+
+{/* 本章目标：介绍文件类工具的设计理念 */}
+
+## 读、写、改——三种操作模式
+
+Claude Code 把文件操作拆分为三个独立工具，而不是一个万能的"文件工具"：
+
+| 工具 | 功能 | 设计考量 |
+|------|------|---------|
+| **Read** | 读取文件内容 | 只读操作，权限最低，AI 可以随意使用 |
+| **Write** | 创建新文件或完全重写 | 高风险操作，需要确认 |
+| **Edit** | 精确替换文件中的特定片段 | 中等风险，但比 Write 安全——只改你指定的部分 |
+
+
+为什么 Edit 和 Write 要分开？因为"编辑一行"和"重写整个文件"的风险完全不同。分离后，权限系统可以对它们施加不同的控制策略。
+
+
+## 文件读取的智慧
+
+Read 工具不是简单的 `cat` 命令，它有很多精细的设计：
+
+- **分页读取**：超大文件不会一次性全部读入，支持 offset + limit 指定范围
+- **多格式支持**：除了文本文件，还能读取图片（多模态展示）、PDF、Jupyter Notebook
+- **文件状态缓存**：记住已读过的文件内容，避免重复读取浪费 token
+- **Token 感知**：文件内容计入 token 预算，系统会自动评估是否"读得起"
+
+## 精确编辑 vs 全量重写
+
+Edit 工具的核心设计是**精确字符串替换**：
+
+- AI 指定 `old_string`（要被替换的原文）和 `new_string`（替换后的新文）
+- 系统确保 `old_string` 在文件中**唯一匹配**——如果匹配到多处或零处，操作失败
+- 这个设计确保 AI 不会"改错地方"
+
+## 搜索与导航
+
+在动手修改之前，AI 通常需要先"找到目标"。两个搜索工具分工明确：
+
+- **Glob**：按文件名模式搜索（"找到所有 `.ts` 文件"），替代 `find` 命令
+- **Grep**：按文件内容搜索（"找到所有包含 `TODO` 的行"），替代 `grep/rg` 命令
+
+两者都经过优化，能在大型项目中快速返回结果，并自动截断过长的输出。
+
+## 文件历史快照
+
+每当 AI 准备修改文件时，系统会自动保存一份快照。这意味着：
+
+- 用户可以随时回滚到 AI 修改前的状态
+- 即使 AI 做了错误的编辑，原始内容不会丢失
+- 快照与 git 互补——git 追踪已提交的变更，快照保护未提交的工作
diff --git a/docs/tools/search-and-navigation.mdx b/docs/tools/search-and-navigation.mdx
new file mode 100644
index 000000000..469c21314
--- /dev/null
+++ b/docs/tools/search-and-navigation.mdx
@@ -0,0 +1,43 @@
+---
+title: "搜索与导航"
+description: "AI 如何在百万行代码中精准定位目标"
+---
+
+{/* 本章目标：介绍搜索类工具和工具搜索机制 */}
+
+## 两种搜索维度
+
+| 维度 | 工具 | 适用场景 |
+|------|------|---------|
+| **按名称找文件** | Glob | "找到所有测试文件"、"找 config 开头的文件" |
+| **按内容找代码** | Grep | "哪里定义了这个函数"、"谁在调用这个 API" |
+
+两者组合使用，AI 就拥有了在大型项目中"导航"的能力。
+
+## 搜索结果的智能处理
+
+大型项目的搜索结果可能有成千上万条，直接全部返回不现实：
+
+- **结果数量限制**：默认最多返回 250 条匹配
+- **上下文行**：Grep 支持显示匹配行前后的上下文（类似 `grep -C`）
+- **按修改时间排序**：Glob 默认把最近修改的文件排在前面
+- **文件类型过滤**：按语言类型过滤（只搜 `.ts` 文件、只搜 `.py` 文件）
+
+## 工具发现机制
+
+当可用工具超过 50 个时，AI 可能不知道该用哪个。系统提供了 **ToolSearch** 机制：
+
+- AI 可以用自然语言描述需求（"我需要连接数据库"）
+- 系统在所有已注册工具（包括 MCP 提供的）中搜索匹配
+- 返回最相关的工具列表及使用说明
+
+这让 AI 在面对庞大的工具库时不会迷路。
+
+## Web 搜索与抓取
+
+AI 的信息获取不局限于本地代码：
+
+- **WebSearch**：搜索互联网获取最新信息
+- **WebFetch**：抓取特定网页内容，转换为 Markdown 供 AI 阅读
+
+这让 AI 可以查阅文档、搜索 Stack Overflow、阅读 GitHub issue——和人类开发者的工作方式一致。
diff --git a/docs/tools/shell-execution.mdx b/docs/tools/shell-execution.mdx
new file mode 100644
index 000000000..acc8279d5
--- /dev/null
+++ b/docs/tools/shell-execution.mdx
@@ -0,0 +1,53 @@
+---
+title: "命令执行"
+description: "让 AI 在你的终端里运行命令——安全地"
+---
+
+{/* 本章目标：介绍 Bash 工具的能力与安全设计 */}
+
+## AI 能执行命令意味着什么
+
+这是 Claude Code 最强大也最敏感的能力。AI 可以：
+
+- 运行构建命令（`npm run build`、`cargo build`）
+- 执行测试（`pytest`、`jest`）
+- 使用 git（`git status`、`git commit`）
+- 调用系统工具（`curl`、`docker`、`kubectl`）
+
+几乎你在终端里能做的事，AI 都能做。
+
+## 安全设计
+
+强大的能力需要严格的控制：
+
+
+
+ 默认情况下，每条命令执行前都需要用户手动确认。用户可以设置白名单规则，让特定命令自动放行。
+
+
+ 在支持的平台上，命令可以运行在沙箱环境中——限制文件系统访问范围、禁止网络请求、阻止危险操作。
+
+
+ 每条命令都有超时限制（默认 2 分钟，最长 10 分钟），防止 AI 启动一个永远不会结束的进程。
+
+
+ 命令输出过长时自动截断，避免把海量日志全部塞进 AI 的上下文。
+
+
+
+## 前台与后台
+
+有些命令需要等待结果（比如 `git status`），有些适合在后台运行（比如 `npm install`）：
+
+- **前台执行**：AI 等待命令完成，拿到输出后继续思考
+- **后台执行**：命令在后台运行，AI 可以继续做其他事，稍后再检查结果
+
+## 为什么用专用工具而不是直接调 shell
+
+
+Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。原因有三：
+
+
+1. **权限粒度更细**：`Read` 是只读操作可以自动放行，但 `Bash: cat file` 需要审批整条命令
+2. **输出结构化**：专用工具的返回值是结构化的，方便 UI 渲染（高亮、diff 视图等）
+3. **性能优化**：专用工具可以做缓存、分页、token 预算控制，shell 命令做不到
diff --git a/docs/tools/task-management.mdx b/docs/tools/task-management.mdx
new file mode 100644
index 000000000..72bb229e8
--- /dev/null
+++ b/docs/tools/task-management.mdx
@@ -0,0 +1,50 @@
+---
+title: "任务管理"
+description: "让 AI 的工作有条理、可追踪"
+---
+
+{/* 本章目标：介绍任务系统如何帮助 AI 和用户保持同步 */}
+
+## 为什么需要任务管理
+
+当你给 AI 一个复杂需求（比如"重构整个认证模块"），它可能需要执行几十个步骤。没有任务管理，用户只能被动等待，不知道 AI 做到哪了、还要做什么。
+
+## 任务系统的运作方式
+
+AI 可以自主创建和管理任务列表：
+
+
+
+ AI 把大需求拆解为多个小任务，创建到任务列表
+
+
+ 开始某个任务时标记为"进行中"，完成后标记为"已完成"
+
+
+ 任务之间可以设定依赖关系——"任务 B 必须等任务 A 完成后才能开始"
+
+
+ 用户随时可以查看任务列表，了解整体进度
+
+
+
+## 任务与 Plan Mode 的配合
+
+面对复杂任务，AI 可以先进入**计划模式**：
+
+1. AI 进入计划模式 → 只允许使用搜索和阅读类工具（不能修改文件）
+2. AI 探索代码库、理解现有架构
+3. AI 制定实施计划，创建任务列表
+4. 用户审批计划
+5. AI 退出计划模式，按计划逐项执行
+
+这种"先规划、后执行"的方式避免了 AI 盲目行动造成的返工。
+
+## 状态展示
+
+终端 UI 中，任务列表会实时更新：
+
+- 待办任务灰色显示
+- 进行中的任务有旋转动画
+- 已完成的任务打勾标记
+- 被阻塞的任务标注依赖项
diff --git a/docs/tools/what-are-tools.mdx b/docs/tools/what-are-tools.mdx
new file mode 100644
index 000000000..0f0873405
--- /dev/null
+++ b/docs/tools/what-are-tools.mdx
@@ -0,0 +1,74 @@
+---
+title: "工具：AI 的双手"
+description: "理解 Tool 这个核心抽象——AI 是怎么从'说'变成'做'的"
+---
+
+{/* 本章目标：让读者理解 Tool 抽象的设计思想 */}
+
+## AI 为什么需要工具
+
+大语言模型本质上只能做一件事：**根据输入文本，生成输出文本**。
+
+它不能读文件、不能执行命令、不能搜索代码。要让 AI 真正"动手"，需要一个桥梁——这就是 **Tool**（工具）。
+
+工具是 AI 的双手。AI 说"我想读这个文件"，工具系统替它真正去读；AI 说"我想执行这条命令"，工具系统替它真正去跑。
+
+## 一个工具长什么样
+
+每个工具都是一个标准化的"能力单元"，包含四个要素：
+
+| 要素 | 说明 | 示例（FileRead 工具） |
+|------|------|----------------------|
+| **名称** | 工具的唯一标识 | `Read` |
+| **描述** | 告诉 AI 这个工具能做什么（AI 据此决定是否使用） | "读取本地文件系统中的文件" |
+| **参数定义** | 工具接受什么输入 | `file_path`（必填）、`offset`、`limit` |
+| **执行逻辑** | 工具被调用时实际做什么 | 读取文件内容并返回 |
+
+## AI 如何选择工具
+
+AI 不是从下拉菜单里选工具——它是根据**工具描述**和**当前任务**自主决策的：
+
+1. 系统把所有可用工具的名称、描述、参数告诉 AI
+2. AI 在思考过程中决定"我需要用某个工具"
+3. AI 生成一个结构化的工具调用请求（工具名 + 参数）
+4. 系统执行工具，将结果返回给 AI
+
+
+工具描述的质量直接影响 AI 的决策准确性。一段好的描述不仅说明"能做什么"，还说明"什么时候该用、什么时候不该用"。
+
+
+## 50+ 内置工具
+
+Claude Code 内置了覆盖软件开发全流程的工具集：
+
+
+
+ Read / Write / Edit / Glob / Grep / NotebookEdit
+
+
+ Bash / PowerShell
+
+
+ Agent / SendMessage / AskUserQuestion
+
+
+ TaskCreate / TaskUpdate / TaskList / TaskGet
+
+
+ WebFetch / WebSearch
+
+
+ EnterPlanMode / Worktree / TodoWrite
+
+
+
+## 工具的可视化渲染
+
+工具不仅能"做事"，还能"展示"。每个工具可以定义自己的 UI 渲染方式：
+
+- **FileEdit** → 在终端里展示语法高亮的 diff 视图
+- **Bash** → 实时显示命令输出，带进度指示
+- **Grep** → 高亮匹配结果，显示文件路径和行号链接
+- **Agent** → 显示子 Agent 的进度条和状态
+
+这让用户能直观地看到"AI 在做什么、做到哪了"。