docs: Add comprehensive agentic design documentation (2.5-hour learning session)
新增 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
This commit is contained in:
Claude
parent
0cf2fa2edb
commit
808d5a61b3
8 changed files with 2697 additions and 0 deletions
113
docs/agentic-design/README.md
Normal file
113
docs/agentic-design/README.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
# Claude Code Agentic 设计文档
|
||||
|
||||
> **目标读者**：有一定软件工程背景、希望通过真实项目理解 agentic 系统设计的学习者。
|
||||
> **建议用时**：约 2.5 小时
|
||||
> **阅读语言**：中文正文 + 英文技术术语
|
||||
|
||||
---
|
||||
|
||||
## 这个项目是什么？
|
||||
|
||||
[Claude Code](https://claude.ai/code) 是 Anthropic 开发的 AI 辅助编程 CLI 工具。它不是一个简单的"问答机器人"，而是一个完整的 **agentic system**：
|
||||
|
||||
- 它可以自主执行多轮工具调用（读文件、改代码、运行命令）
|
||||
- 它可以 spawn 子 agent 并行处理复杂任务
|
||||
- 它有 permission 管控、memory 管理、context 压缩等完整的 agent 基础设施
|
||||
|
||||
这套文档通过分析 Claude Code 的源代码，提炼出其中最有价值的 agentic 设计选择，帮助你建立对真实 agent 系统的直觉。
|
||||
|
||||
---
|
||||
|
||||
## 整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 用户 / IDE / SDK │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│ 输入：用户消息
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CLI / Entrypoint Layer │
|
||||
│ entrypoints/cli.tsx │ entrypoints/sdk/ │ entrypoints/mcp/ │
|
||||
└────────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Query Loop Engine │
|
||||
│ QueryEngine.ts ←→ query.ts ←→ query/ │
|
||||
│ (状态机: QUERY → TOOL_USE → RESULT → QUERY → ...) │
|
||||
└──────────────┬────────────────────────────────┬─────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────────────┐ ┌───────────────────────────────┐
|
||||
│ Claude API (Streaming) │ │ Tool Execution Layer │
|
||||
│ services/api/ │ │ services/tools/ │
|
||||
│ • token budget 追踪 │ │ • StreamingToolExecutor │
|
||||
│ • compaction 触发 │ │ • 并发控制 + sibling abort │
|
||||
└──────────────────────────┘ └──────────────┬────────────────┘
|
||||
│
|
||||
┌──────────────────┼──────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌──────────┐ ┌──────────────┐
|
||||
│ File │ │ Bash / │ │ AgentTool │
|
||||
│ Tools │ │ Shell │ │ (子 agent) │
|
||||
└─────────┘ └──────────┘ └──────┬───────┘
|
||||
│
|
||||
┌────────────────────────┘
|
||||
│ spawn
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ 子 Agent / Coordinator│
|
||||
│ coordinator/ │
|
||||
│ tasks/Local|Remote │
|
||||
└────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 横切关注点（Cross-cutting） │
|
||||
│ Permission System │ Context/Memory │ Feature Gating │
|
||||
│ utils/permissions/ │ memdir/ autoDream│ bootstrap/state.ts │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心设计哲学
|
||||
|
||||
**1. Tool 是 Agent 触碰世界的唯一手段**
|
||||
Agent 的所有副作用（写文件、执行命令、发消息）都必须经过 Tool 接口，这使得权限控制、审计日志、测试 mock 都可以在一个地方统一处理。
|
||||
|
||||
**2. Text is the protocol**
|
||||
Agent 之间通过 `<task-notification>` XML 消息通信，memory 以 Markdown 文件存储，permission rules 是 `Bash(git *)` 这样的字符串模式。用文本作为协议，意味着 AI 模型自己也可以读懂并调试这些通信内容。
|
||||
|
||||
**3. Failure modes are first-class**
|
||||
每个长时间运行的操作都有明确的 abort 路径，例如：连续 3 次 permission denial 就回退到手动提示；并行 tool 中一个失败会触发 sibling abort；compaction 失败有 rollback 保护。
|
||||
|
||||
**4. Context window 是最稀缺的资源**
|
||||
整个系统的大量设计决策（system prompt 的静态/动态分割、token budget 追踪、auto-dream 后台压缩）都围绕着"如何最大化利用有限的 context window"展开。
|
||||
|
||||
**5. 编译期与运行期特性隔离**
|
||||
内部功能通过 Bun 的 `feature()` API 在编译时消除，不出现在公开二进制文件中；运行时行为通过 GrowthBook runtime flags 动态控制。
|
||||
|
||||
---
|
||||
|
||||
## 建议阅读顺序
|
||||
|
||||
| 编号 | 文档 | 用时 | 核心问题 |
|
||||
|------|------|------|---------|
|
||||
| [00](./00-codebase-tour.md) | 代码库目录全景 | 30 min | "这个 repo 里有什么？" |
|
||||
| [01](./01-agent-loop.md) | 核心 Query Loop | 20 min | "Agent 是如何循环运作的？" |
|
||||
| [02](./02-tool-system.md) | Tool 系统 | 20 min | "Tool 是怎么被定义和执行的？" |
|
||||
| [03](./03-multi-agent-coordination.md) | 多 Agent 协调 | 25 min | "多个 agent 怎么协作？" |
|
||||
| [04](./04-permission-system.md) | Permission 系统 | 20 min | "Agent 怎么知道自己能做什么？" |
|
||||
| [05](./05-context-and-memory.md) | Context 与 Memory | 20 min | "Context window 满了怎么办？" |
|
||||
| [06](./06-feature-gating.md) | Feature Flag 系统 | 10 min | "内部功能是怎么隐藏的？" |
|
||||
|
||||
---
|
||||
|
||||
## 如何使用这套文档
|
||||
|
||||
- **按顺序读**：00 → 01 → 02 → 03 → 04 → 05 → 06，每篇都假设你已读过前面的内容
|
||||
- **跳读**：如果你已熟悉某个概念，可以直接跳到感兴趣的章节
|
||||
- **对照代码**：每篇文档都标注了关键源文件路径，随时可以打开对照阅读
|
||||
- **关注 Design Decision 专栏**：这些是最有学习价值的地方，解释了"为什么这样设计"而不只是"是什么"
|
||||
Loading…
Add table
Add a link
Reference in a new issue