第 0 章：如何阅读这套 Zed 拆解
目标不是记住 241 个 crate，而是获得一张可以反复定位问题的地图：一个按键如何进入 GPUI，一个编辑如何变成可协作操作，一个 LSP 请求如何跨越本地与远程边界，一个 Agent 工具调用又怎样落到 Project 和 Buffer。
1. 本教程的拆解方法
参考项目 dg-ai-notes 最有价值的不是章节名称，而是三层提问法：
- 是什么：这一层解决什么工程问题，边界在哪里。
- 怎么做：从公开入口跟到核心状态、事件和异步任务。
- 为什么：设计换来了什么，又付出了什么复杂度。
对 Zed 这种百万行级 Rust 工程，必须再加两条规则。
1.1 沿数据旅程读，不按目录读
如果从 crates/acp_thread 一路按字母读到 crates/worktree，很快就会失去主线。 本教程选择五条真实旅程：
启动：main → Application → 全局服务 → Workspace
输入：平台事件 → GPUI Action → Editor → Buffer operation
显示：BufferSnapshot → DisplayMap → EditorElement → Scene → GPU
语义：Worktree → Project → LspStore → LanguageServer → Buffer diagnostics
智能：Agent UI → Thread → LanguageModel stream → Tool → Project/Terminal每一条旅程都跨越多个 crate。crate 是编译和依赖边界，不等于用户动作的边界。
1.2 区分四类“状态”
Zed 中同一个名词经常同时存在可变实体、不可变快照、协议消息和 UI 投影。阅读时先问：
| 状态形态 | 常见类型 | 适合做什么 |
|---|---|---|
| 可变实体 | Entity<T>、Context<T> | 接收事件、修改模型、启动任务 |
| 不可变快照 | BufferSnapshot、MultiBufferSnapshot | 跨线程计算、稳定坐标、增量同步 |
| 协议表示 | proto::*、ACP 类型 | 进程/网络边界传输 |
| 显示投影 | DisplaySnapshot、Scene | 布局、命中测试、批量绘制 |
很多“为什么不直接传某个对象”的答案，都藏在这四种形态的边界里。
2. 版本与证据约定
本教程基于工作区中的 zed-main 快照：
crates/zed/Cargo.toml中应用版本是1.15.0；crates/下有 241 个一级目录；- 约 1,852 个
.rs文件、152 万行 Rust 文本； - 行数包含测试、fixture 和条件编译实现，不应当解读为“152 万行业务代码”。
正文使用下面的证据格式：
crates/text/src/text.rs:59-126 Buffer 与 BufferSnapshot 的核心字段路径和行号指本地快照。上游链接指向 zed-industries/zed 的 main 分支，随着上游变化， 链接行号可能漂移。遇到差异时，以“路径 + 类型/函数名”重新搜索。
3. 三种阅读路线
路线 A：第一次理解 Zed
按章节顺序阅读：
01 全景 → 03 启动 → 04 GPUI → 06 数据结构
→ 07 Buffer → 08 Editor → 09 Project → 10 LSP
→ 14 协作 → 15 Agent → 19 复盘这条路线优先建立“对象如何协作”，不会在 UI 细节里过早迷路。
路线 B：编辑器内核
阅读 04、05、06、07、08、10。你会得到三组关键模型：
Entity<T>管生命周期，Snapshot 管稳定读取；SumTree提供多维度可跳转的持久化序列；- Buffer 坐标经过 MultiBuffer 和 DisplayMap 多层变换才变成屏幕位置。
路线 C：AI 编程工具
阅读 09、10、12、15、16、17。重点不是聊天 UI，而是：
- Agent 工具为什么依赖
Project而不是直接操作文件； - 模型事件如何在输入 JSON 尚未结束时就启动流式工具；
- 权限、沙箱、checkpoint 与 undo 如何把副作用约束在可解释范围；
- ACP 如何把内置 Agent 和外部 Agent 收敛到同一会话界面。
4. 看到这些类型时要停下来
Entity<T> / WeakEntity<T>
它们不是普通的 Arc<Mutex<T>>。实体的读写被 App 上下文调度，通知、事件、窗口和异步 任务都围绕实体身份组织。详见第 4 章。
Snapshot
Snapshot 通常意味着“这个对象接下来还会变，但本次计算需要一个不会动的观察点”。 它也是把 UI 主线程状态安全送往后台计算的重要手段。
Anchor
Anchor 不是当前字节偏移，而是携带时间戳和偏向的逻辑位置。别人在它左边插入内容后， 它仍能解析到合理位置。详见第 7 章。
Operation
Operation 是可复制、可排序、可重放的状态变化。文本、诊断、选择和行尾变化都有自己的 operation。不要把它和 UI action 混为一谈。
Task<T>
GPUI 的任务必须被持有或显式 detach。任务所有权经常就是取消语义：丢弃句柄可以阻止 结果继续影响已经消失的视图。
5. 每章的固定问题
你可以用下面的清单检验是否真正理解一个子系统：
- 组合根在哪里创建它？
- 谁拥有它，谁只拿弱引用？
- 它的可变状态和 Snapshot 如何分工？
- 输入通过函数调用、事件还是消息进入？
- 输出如何通知上层？
- 哪些工作必须在前台，哪些可以放到后台？
- 本地、协作和远程路径是否共用同一接口？
- 取消、断线、乱序、过期快照时怎么办？
- 热路径依赖哪种增量数据结构？
- 测试用 fake 是否暴露了真正的抽象边界？
6. 本教程刻意不做什么
- 不逐个解释全部 241 个 crate；源码索引提供定位地图。
- 不复述 Zed 用户手册；这里关注实现结构，不是功能操作说明。
- 不把“用了 Rust”当成性能答案；具体看快照、增量失效、批处理和线程边界。
- 不把
main分支当前行为误写成永恒架构；每章都会指出容易演进的边界。
下一章先建立一张足够小、但能解释大多数代码的全景图。