# Grok Build 源码解读

> 逐层拆读 xAI 开源的终端编码 Agent「Grok Build」的 Rust 源码——一边讲怎么用，一边讲怎么实现，与《从 LLM 到 Coding Agent》互为印证。

- 作者：David（道雾轩）
- 最后更新：2026-09-15
- 原文：https://daiw.org/manual/grok-build
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

# Grok Build 源码解读

[Grok Build](https://github.com/xai-org/grok-build)（命令行叫 `grok`）是 xAI 开源的**终端编码 Agent**：一个跑在终端里的全屏 TUI，能读懂你的代码库、改文件、跑 shell、搜网页、管理长任务，可交互使用、可 headless 进 CI、也可通过 ACP 嵌进编辑器。整个东西用 **Rust** 写成，一个 96 个 crate 的 Cargo workspace，源码 175 万行级（剔除测试约 85 万行，口径见下文「源码基准」）。

这个专栏把它**逐层拆开读**。

## 这个专栏怎么读

每一章尽量走**两条线**：

- **怎么用** —— grok 仓库里自带 27 篇官方 user-guide（`crates/codegen/xai-grok-pager/docs/user-guide/`），我们从「一个功能你怎么用」讲起；
- **怎么实现** —— 再翻到对应 crate 的源码，看它在底层到底怎么做。

侧重**结构与数据流**：讲清「一件事经过哪些 crate、数据怎么流」，而不是逐行贴大段代码——关键处才引一小段源码点睛。

## 和《从 LLM 到 Coding Agent》配对

站里已有一本 [《从 LLM 到 Coding Agent》](https://daiw.org/manual/llm-to-agent)：它讲「一个 Coding Agent 在裸 LLM API 之上该做哪些事」，并配了一个从零手搓、可运行的**教学最小实现**。

这本正好是它的**另一面**：同样这些事（agent loop、工具、上下文、扩展……），换成一份**真实的生产实现**来看——教学最小实现 vs 生产实现，两边对照着读，收获最大。两本都放在站点的「Agent 教程」一组。

<Callout type="info">
  **读者预设**：默认你懂一点 Rust（读得下 `async`、trait、workspace 分层），不熟的语言点我们会在关键处就地补一句，但不系统教 Rust。并读过 [《从 LLM 到 Coding Agent》](https://daiw.org/manual/llm-to-agent) 会更顺，但不是硬前提。
</Callout>

## 源码基准

- 仓库：[github.com/xai-org/grok-build](https://github.com/xai-org/grok-build)（从 SpaceXAI monorepo 周期性同步，只有 `main` 分支、不打 tag；根目录 `SOURCE_REV` 记录了对应的 monorepo commit）。
- 对照版本：提交 `37949780`（2026-09-09，「Synced from monorepo」），其 `SOURCE_REV` 为 `c4ea71cfdbcdb21e32e41bc25a0043d7d4836714`。专栏初稿对照的是 2026-07-18 的 `7cfcb20d`，之后按上面这个提交逐篇复核更新。
- crate 数：根 `Cargo.toml` 的 workspace `members` 共 101 个，其中 `crates/` 下 96 个（`codegen` 83、`common` 12、`build` 1；初稿时是 74 个），另有 `third_party/` 4 个、`prod/mc/` 1 个。本专栏说「96 个 crate」即指 `crates/` 下这些。
- 代码量：统计 `crates/` 下全部 `.rs` 文件的物理行（含注释与空行），共约 175 万行（3,042 个文件）；「剔除测试」指去掉 `tests.rs`、`*_tests.rs`、`tests/` 目录，并按花括号剔除 `#[cfg(test)]` 项，剩下约 85 万行。
- 本专栏所有路径都相对仓库根，例如 `crates/codegen/xai-grok-agent/src/agent.rs`。
- 二进制产物叫 `xai-grok-pager`，官方安装包装成 `grok`。

## 路线图

- **第 0 部分 · 导论与全景** —— grok 是什么、装上就跑、Rust workspace 全景、与 llm-to-agent 的对照总表、读源码的准备、一条消息的生命周期。
- **第 1 部分 · Agent 运行时内核** —— 主循环、采样器、会话状态、system prompt 组装、上下文压缩与记忆、打断与防失控。
- **第 2 部分 · 工具系统** —— 工具契约与注册、文件编辑与 diff 追踪、Shell/PTY、沙箱权限、LSP、Web/computer use、与其它 agent 互通。
- **第 3 部分 · 工作区与 Git** —— workspace 抽象、文件监听、Git 集成、代码库图谱、并行 worktree。
- **第 4 部分 · 扩展机制** —— AGENTS.md、Skills、MCP、Hooks、Plugins/marketplace、Subagents、自定义模型。
- **第 5 部分 · 终端 UI 深潜** —— TUI 架构、渲染管线、markdown 实时渲染、输入与补全、可视化、主题与终端适配。
- **第 6 部分 · 运行形态与工程** —— slash 命令、sessions、plan mode、headless、ACP、后台任务、认证配置、遥测、Rust 工程。
- **第 7 部分 · 收尾** —— 拿 llm-to-agent 全表复盘、grok vs Claude Code、读完之后怎么继续。

准备好了，就从 [grok 到底是什么](https://daiw.org/manual/grok-build/what-is-grok-build) 开始。

## 本专栏篇目

- [Grok Build 源码解读](https://daiw.org/manual/grok-build.md): 逐层拆读 xAI 开源的终端编码 Agent「Grok Build」的 Rust 源码——一边讲怎么用，一边讲怎么实现，与《从 LLM 到 Coding Agent》互为印证。

### 第 0 部分 · 导论与全景

- [grok 到底是什么 · 一个开源的终端编码 Agent](https://daiw.org/manual/grok-build/what-is-grok-build.md): Grok Build 是 xAI 开源的终端编码 Agent（TUI，Rust 写成）。这一章讲清它是什么、能做什么、三种运行形态，以及它在「Claude Code」与「手搓最小 Agent」之间的坐标——为什么值得逐行读它的源码。
- [装上就跑 · 第一次对话发生了什么](https://daiw.org/manual/grok-build/install-and-run.md): 先把 grok 装起来跑一遍——预编译二进制或从源码 cargo run——再顺着「你按下回车之后」这条线，把第一次对话经过的组件走一遍，为后面逐层深入建立实感。
- [Rust workspace 全景 · 96 个 crate 怎么分层](https://daiw.org/manual/grok-build/workspace-map.md): Grok Build 是一个 96 个 crate 的 Cargo workspace。这一章不逐个念名字，而是把它们归到「组合根 / TUI / Agent 运行时 / 模型接入 / 工具能力 / 工作区 / 扩展 / 基础设施」几层，给你一张能按图索骥的分层地图。
- [与《从 LLM 到 Coding Agent》对照总表](https://daiw.org/manual/grok-build/pairing-map.md): 把《从 LLM 到 Coding Agent》里讲过的每个概念，对到 Grok Build 的具体 crate 与本专栏对应章节——一张「教学最小实现 ↔ 生产实现」的索引表，两本配对着读用它当地图。
- [读源码前的准备 · 怎么在百万行代码里找到路](https://daiw.org/manual/grok-build/reading-the-source.md): 一份读 Grok Build 源码的「导航手册」：cargo 与 workspace 的基本操作、proto 代码生成、怎么把一个功能定位到 crate，以及你会反复遇到的几个 Rust 惯用法。
- [一条消息的生命周期 · 全景地图](https://daiw.org/manual/grok-build/message-lifecycle.md): 把「你敲一句话 → grok 改完代码回你话」这条端到端链路完整走一遍，标出每一步落在哪个 crate、由后面哪一部分放大讲。这是进入内核前的最后一张全景图。

### 第 1 部分 · Agent 运行时内核

- [Agent loop 主循环 · 一轮对话是怎么转起来的](https://daiw.org/manual/grok-build/agent-loop.md): grok 的主循环不在「Agent 对象」里，而在 shell 的 SessionActor。这一章讲清「Agent 对象」与「会话 actor」的分工，以及 process_conversation_turn 那个核心 loop：一次用户输入如何驱动模型与工具来回多轮，直到收敛。
- [采样器 · 用 actor 模型管住并发的模型请求](https://daiw.org/manual/grok-build/sampler-actor.md): grok 和模型对话这一侧叫「采样器」。它用一个 actor 把「并发、取消、重试」收在一处，无锁地管理多个同时进行的模型请求。这一章看它的三层设计与 actor 骨架。
- [三种 API 流 · 一套词汇统一三家后端](https://daiw.org/manual/grok-build/api-streams.md): grok 同时支持 OpenAI Chat Completions、Anthropic Messages、OpenAI Responses 三种 API 格式。这一章看它怎么把三种迥异的流，归一成同一套 SamplingEvent 与中立会话模型——这正是「换个模型就能跑」的底层原因。
- [流式解析与事件 · 从 SSE 字节到屏幕](https://daiw.org/manual/grok-build/streaming-events.md): 从模型吐出的第一个字节，到你屏幕上跳动的文字，中间是一条 SSE 解析流水线加一套事件词汇。这一章看 grok 怎么把原始字节变成 SamplingEvent，以及贯穿其中的「错误保真」与两套重试预算。
- [会话状态 · chat-state 怎么存这盘对话](https://daiw.org/manual/grok-build/chat-state.md): 一整盘对话——用户消息、助手回复、工具调用与结果、推理块——怎么建模、怎么存、怎么在压缩与回退时安全改写。这一章拆 xai-chat-state：又一个无锁 actor，加一套「写时修复 + 惰性剪枝 + 双文件持久化」的历史管理。
- [system prompt 怎么组装 · 一个会随工具集变形的模板](https://daiw.org/manual/grok-build/system-prompt.md): grok 的 system prompt 不是一段死字符串，而是每次会话按「有哪些工具、是否交互、什么受众」现场渲染出来的。这一章拆它的模板引擎、按 kind 间接引用工具、以及 AGENTS.md 为什么不进 system prompt 而是当用户消息注入。
- [上下文压缩 · 满了怎么办](https://daiw.org/manual/grok-build/compaction.md): 上下文窗口会满。grok 的压缩不是「留个尾巴」，而是把整盘对话总结成一份九段式结构化摘要、再重建一份全新历史。这一章看它的触发、摘要提示、清洗、重组，以及那道防「压不动」的输入梯子。
- [记忆 · 跨会话记住东西](https://daiw.org/manual/grok-build/memory.md): grok 的记忆系统把「这个项目的经验」跨会话持久化：markdown 文件存事实，SQLite 的 FTS5 + 向量做混合检索，/flush 把当前会话总结进盘，/dream 把多次会话合并进长期记忆。这一章拆它的存储、检索与两个反思动作。
- [打断与防失控 · 两种「叫停」的哲学](https://daiw.org/manual/grok-build/interjection-doom-loop.md): agent 正忙时，你怎么插话？模型自己陷入复读机怎么办？这一章看 grok 的两套「叫停」机制——协作式打断（buffer 合并，不抢占）与硬取消，以及服务端 doom-loop 检测如何中途掐断失控生成、在独立预算上重采样。

### 第 2 部分 · 工具系统

- [一个工具的完整契约 · 两个 trait 一个 struct](https://daiw.org/manual/grok-build/tool-contract.md): 进 grok 那近 15 万行的工具系统。这一章先立地基：在 grok 里「一个工具」到底是什么——一个类型上挂两个 trait（运行时契约 Tool + grok 元数据 ToolMetadata），它怎么声明 schema、怎么校验参数与配置、怎么以流的形式执行。
- [工具注册与分发 · 从 model 请求到工具执行](https://daiw.org/manual/grok-build/tool-registry.md): 一堆异质的工具怎么装进一个集合、按什么顺序摆给模型、一次工具调用又怎么从名字走到执行。这一章拆 ToolBridge 与 FinalizedToolset：注册期的类型擦除、finalize 的定序、以及一次 call 的完整数据流。
- [工具协议 · 进程内与跨进程一套契约](https://daiw.org/manual/grok-build/tool-protocol.md): grok 的工具默认在进程内跑，但同一套 ToolHandle/流式契约能无缝跨进程。这一章拆三层协议栈（types/runtime/protocol）、一个 object-safe 的 ToolHandle 如何同时套住本地工具与远程代理，以及那套 JSON-RPC「Computer Hub」线协议。
- [读与搜 · read_file 与 grep 的门道](https://daiw.org/manual/grok-build/read-and-search.md): 看似最简单的两个工具——读文件、搜代码——在 grok 里藏着不少门道：行号投影、多模态（PDF/图片/PPTX）、字符对齐的流式、包 ripgrep 的预算早停。这一章顺带澄清一个易混点：search_tool 搜的是「工具」不是代码。
- [三种编辑格式 · 为什么改文件要三套协议](https://daiw.org/manual/grok-build/edit-formats.md): 同样是「让模型改文件」，grok 提供三种模型协议：精确的 search/replace、省 token 的 concise 版、以及基于行锚点的 hashline。这一章讲清三者的格式差异、各自防的失败模式，以及 editor_infra 里那把设计好却还没接线的文件锁。
- [hunk 追踪 · 怎么改文件而不踩掉你的改动](https://daiw.org/manual/grok-build/hunk-tracker.md): agent 在改文件，你可能同时也在改。grok 用 xai-hunk-tracker 做「行级、带归因」的改动追踪：把每处改动记成一个带作者标签的 hunk，拒绝时只回滚那几行、绝不用整份旧快照覆盖你的编辑。这一章拆它的 actor、归因与防覆盖。
- [Shell 执行与 PTY · 在伪终端里跑命令](https://daiw.org/manual/grok-build/shell-and-pty.md): 让 agent 跑 shell 命令，远不止 spawn 一下。grok 有非流式与流式两条执行路径、跨平台的进程树 kill、边跑边写盘的日志，还有一个基于 portable-pty + alacritty 网格模拟的完整 PTY 控制器。这一章拆执行、流式、后台任务与 PTY。
- [沙箱与权限 · 把 agent 关进操作系统级的笼子](https://daiw.org/manual/grok-build/sandbox-permissions.md): 光靠「问一句要不要执行」不够。grok 用 xai-grok-sandbox 在操作系统层面把 agent 关进笼子：Linux 用 Landlock + bubblewrap，macOS 用 Seatbelt，子进程网络用 seccomp 逐个封。这一章拆它的 profile、平台差异、fail-closed，以及沙箱如何让权限层敢少问。
- [LSP 代码智能 · 让模型用上语言服务器](https://daiw.org/manual/grok-build/lsp.md): grep 只能按文本找，理解代码得靠语言服务器。grok 的 lsp 工具把 LSP（跳转定义、找引用、悬停、符号）接给模型，背后是一套用 async_lsp 管理多语言服务器进程、按扩展名路由、崩溃自动重启的引擎。
- [Web 工具 · 搜网页与抓网页](https://daiw.org/manual/grok-build/web-tools.md): grok 伸到代码库之外靠两个工具：web_search 走服务端（xAI Responses API 的搜索能力），web_fetch 走客户端（reqwest 抓页面、htmd 转 markdown、还带 SSRF 防护）。这一章讲清两者的分工与那些安全细节。
- [与别家 agent 互通 · grok 怎么「假装」成 Codex/Cursor/Claude](https://daiw.org/manual/grok-build/agent-interop.md): grok 工具系统最有意思的设计：一种行为、多套 wire 格式。它内置了 Codex 的 apply_patch、opencode 的工具名、Cursor 的 .mdc 规则、Claude 的工具别名——好让你把现成的 CLAUDE.md / .cursor/rules / codex 配置直接搬过来就能用。

### 第 3 部分 · 工作区与 Git

- [workspace 抽象 · 工具怎么触达文件、又怎么被放行](https://daiw.org/manual/grok-build/workspace-abstraction.md): 进 Part 3。一次工具调用从主循环出来，经过 WorkspaceOps 派发、AsyncFileSystem 触达文件，中间还要过权限管理器那道「判定瀑布」。这一章拆 workspace 的三件事：派发缝、文件系统抽象、以及决定放行/询问/拒绝的顺序。
- [文件监听 · 一条因果有序的语义事件流](https://daiw.org/manual/grok-build/fsnotify.md): agent 得知道文件被改了——不管是它自己改的还是你改的。grok 的 xai-fsnotify 把 OS 的原始文件事件，整理成一条因果有序的语义流，还专门识别「git 正在操作」的窗口。这一章拆它的双监听策略、git 锁状态机与事件桥接。
- [Git 集成 · 一个 agent 为什么用了三套 git](https://daiw.org/manual/grok-build/git-integration.md): git 在编码 agent 里无处不在。grok 同时用了三套：git CLI（给模型看的状态）、gix（纯 Rust 的脏文件扫描）、git2（图谱的文件收集）。这一章看它们各自的活，重点讲一个精彩的坑：在 panic=abort + 紧 RLIMIT_NPROC 下，gix 并行扫描怎么把整个进程搞崩、又怎么救回来。
- [代码库图谱 · 用 tree-sitter 建一张符号索引](https://daiw.org/manual/grok-build/codebase-graph-build.md): grok 用 tree-sitter 给五种语言建了一张作用域符号图（Bloop 风格），支撑跳转定义、查引用。这一章看它怎么解析、建什么节点与边、以及那个专为省内存设计的字符串驻留器。
- [图谱的真实用途 · 一个诚实的「模型 vs 客户端」之辨](https://daiw.org/manual/grok-build/codebase-graph-use.md): 建好的代码库图谱怎么被用？一个反直觉的真相：它不喂给模型，而是给 grok-web 编辑器做 IDE 级的跳转导航。这一章看图谱的增量 actor 与语言感知排序，更重要的是——教你别假设「凡索引皆为 LLM」。
- [并行 worktree · 让子任务在隔离副本里跑](https://daiw.org/manual/grok-build/fast-worktree.md): 多个 subagent 并行改代码，怎么不互相踩？grok 用 xai-fast-worktree 给每个隔离出一个 git worktree。这一章拆它「快」的几层手段——CoW 反射链接、并行分片拷贝、--no-checkout、以及那个让 git status 瞬间清白的索引 stat-cache 补丁。

### 第 4 部分 · 扩展机制

- [AGENTS.md 项目规则 · 逐目录的指令，深者优先](https://daiw.org/manual/grok-build/agents-md.md): 怎么把「这个项目的约定」喂给模型？grok 沿目录树收集 AGENTS.md（兼容 CLAUDE.md、.cursor/rules），拼成一条 system-reminder。这一章看它的发现顺序、深者优先、尊重 gitignore、目录信任门槛，以及为什么它不进 system prompt。
- [Skills · 可复用的 prompt 包，还能按文件门控](https://daiw.org/manual/grok-build/skills.md): Skills 是 grok 复用 prompt 的一等公民：SKILL.md（frontmatter + 正文）。这一章看它的作用域优先级、防御式 frontmatter 解析、从不改 system prompt 的几条注入路径，以及一个精巧设计——glob 门控的技能，直到你碰到匹配文件才现身。
- [MCP 客户端 · 连上外部工具服务器](https://daiw.org/manual/grok-build/mcp-client.md): MCP（Model Context Protocol）让 grok 接入外部工具服务器。这一章看 xai-grok-mcp 的三种传输、单飞握手状态机、韧性传输、远程 MCP 的 OAuth 流程，以及新版协议的协商。
- [MCP 工具进注册表 · 远程工具怎么变成本地工具](https://daiw.org/manual/grok-build/mcp-registry.md): 连上 MCP 服务器后，它的远程工具怎么进 grok 的工具注册表、怎么和内置工具并存、又怎么在成千上万个工具面前不撑爆上下文。这一章看工具限定名、动态注册，以及 search_tool/use_tool 的规模化解法。
- [Hooks · 在生命周期事件上挂确定性逻辑](https://daiw.org/manual/grok-build/hooks.md): Hooks 让你在「调工具前/后、会话开始/结束」这些生命周期点上挂脚本或 HTTP 回调——用确定性代码补模型「只靠自觉」的不足。这一章看事件、两种 handler、各事件能拦什么（工具调用、用户 prompt、停止）、fail-open 取向，以及那些安全设计。
- [插件 · 清单、发现与信任模型](https://daiw.org/manual/grok-build/plugins-manifest.md): grok 的插件把 skills/commands/agents/hooks/MCP/LSP 打成一个可分发的目录。这一章看它的清单 schema、按作用域的发现优先级，以及那个关键的信任模型——信任按作用域判定，未受信插件只露出 agent 的元数据，技能、hooks 与 MCP 一律不加载。
- [插件市场 · 从哪装、怎么装才安全](https://daiw.org/manual/grok-build/plugins-marketplace.md): 插件从哪来？grok 有两层 marketplace：兼容 Claude 的 extraKnownMarketplaces，和原生的 xai-grok-plugin-marketplace。这一章看它怎么发现、拉取、安装插件，以及那些防坑的安全设计——SHA 钉版、路径穿越防护、快照而非软链。
- [Subagents 与 personas · 并行的隔离子任务](https://daiw.org/manual/grok-build/subagents.md): grok 能派生并行的 subagent 各自干活。这一章看它的解析（内置 general-purpose/explore/plan + 角色 + persona 的优先级）、能力模式如何真的裁掉工具、fork 上下文怎么塑形，以及协调器怎么在独立线程上并行跑、后台轮询。
- [自定义模型 · BYOK、Ollama 与 OpenAI 兼容端点](https://daiw.org/manual/grok-build/custom-models.md): grok 不绑死 xAI 模型——能接自带 key、Ollama、OpenAI 兼容、Anthropic。这一章看模型目录怎么分层合并、凭据怎么逐级解析、协议（api_backend）与鉴权（auth_scheme）为什么在采样器里是正交的两个字段，以及采样器为什么刻意「不认 URL」。

### 第 5 部分 · 终端 UI 深潜

- [TUI 架构 · 一个 Elm 式的终端界面](https://daiw.org/manual/grok-build/tui-architecture.md): 进 Part 5，钻进那个约 55 万行（含测试）的终端 UI。这一章看 grok-pager 的整体架构：Elm 式的 Action→dispatch→Effect 三段式、一个精心排序的 biased 事件循环、专用读写线程，以及为什么「派发层不碰终端/网络/文件」是它最值得学的决定。
- [渲染管线与 scrollback · 让长会话也跑得动](https://daiw.org/manual/grok-build/render-pipeline.md): 一个保留全部历史、还要流式刷新的滚动区，怎么不卡？grok 靠零字节空帧、估算-落定的懒布局、增量 virtual_y 补丁，以及一个专门改造过的 ratatui Terminal 分叉。这一章看它渲染快的几个核心手段。
- [终端里实时渲染 markdown · 把 O(N²) 压成 O(N)](https://daiw.org/manual/grok-build/markdown-render.md): 模型的回复是流式 markdown——一个字一个字来。每来一段就重渲染整篇是 O(N²)，会越来越卡。grok 用「检查点冻结」把它压到近似 O(N)，还让流式代码块的每一行只高亮一次、且和批量渲染逐字节一致。这一章拆这套流式 markdown 引擎。
- [输入、slash 命令与补全 · 每次按键背后](https://daiw.org/manual/grok-build/input-and-completions.md): 从一次按键到一条 slash 命令被识别、补全、执行，中间是一套动作注册表 + 模糊补全 + 两级命令查找。这一章看 grok-pager 的键位冒泡、slash 补全的即时重算与内联 ghost，以及命令的可见性门控。
- [diff 与工具调用可视化 · 看见 agent 在干什么](https://daiw.org/manual/grok-build/diff-visualization.md): agent 改一个文件、跑一条命令，你在 scrollback 里看到的那块彩色 diff、那个带计时的工具卡片，是怎么从 ACP 流式事件画出来的。这一章看 grok 的 diff 引擎、工具块类型、渐进式语法高亮，以及流式工具调用如何变成滚动区里的块。
- [主题与终端适配 · 在五花八门的终端里都好看](https://daiw.org/manual/grok-build/theming-terminal.md): 从 truecolor 到 16 色、从 iTerm 到 ConHost、从跟随系统明暗到 OSC 11 探测——让配色在任意终端里都不崩，是一大堆不起眼的适配。这一章看 grok 的语义主题、颜色能力探测与降级、终端品牌识别。
- [PTY 包装与内联媒体 · 让复制穿透 SSH、让图片进终端](https://daiw.org/manual/grok-build/pty-wrap-media.md): Part 5 收官，两个「终端里居然能做到」的把戏：grok wrap 用 PTY 拦截 OSC 52 让复制穿透 SSH/容器；内联图片用 Kitty 图形协议在滚动区里显示、还能随滚动裁切滑入滑出。这一章拆这两套机制。

### 第 6 部分 · 运行形态与工程

- [Sessions · 会话怎么存、怎么回退、怎么 fork](https://daiw.org/manual/grok-build/sessions.md): 进 Part 6。一盘对话怎么落盘、怎么恢复、怎么回退到某一步、怎么 fork 出一个分支。这一章拆 grok 的会话持久化：JSONL 双文件、UUIDv7、两阶段 rewind、跨压缩回放这个硬骨头，以及会话搜索与跨工具接续。
- [Plan mode · 先出计划，批准了再动手](https://daiw.org/manual/grok-build/plan-mode.md): 让 agent 先谋后动——plan mode 里它只能读、不能改，把计划写进 plan.md，你批准后才开工。这一章看它的状态机、如何在工具层硬拦编辑、以及 exit_plan_mode 的批准往返。
- [Headless 模式 · 同一个 agent，脱掉 TUI](https://daiw.org/manual/grok-build/headless.md): grok -p 让同一个 agent 内核脱掉终端界面，在脚本和 CI 里跑。这一章看 headless 怎么复用 TUI 那套会话启动与 SessionActor（「TUI 减去渲染」）、四种输出格式，以及给 CI 的退出码与鉴权。
- [ACP · 让 grok 当编辑器的后端](https://daiw.org/manual/grok-build/acp.md): 同一个 agent 内核，除了 TUI，还能被 Zed、Neovim 等编辑器当后端驱动——靠 ACP（Agent Client Protocol）。这一章看 xai-acp-lib 的类型化封装、四种传输如何汇入同一个 MvpAgent，以及 leader 模式怎么让多客户端共享一个后端、崩了还能重放恢复。
- [后台任务、loop 与 monitor · 让 agent 边等边干](https://daiw.org/manual/grok-build/background-tasks.md): 长命令、定时任务、盯日志——agent 怎么不被它们卡住？这一章看 grok 的后台任务：monitor 把日志流成通知、/loop 交给调度器、后台命令完成后用一条合成 prompt「叫醒」模型。
- [CLI 与启动 · grok 二进制怎么开机](https://daiw.org/manual/grok-build/cli-surface.md): grok 一个二进制，既是 TUI，又是 headless，又是一堆子命令，还能当 agent 后端。这一章看组合根怎么开机、clap 怎么解析、以及 async_main 怎么把你敲的命令派往 TUI / headless / 子命令 / agent 模式。
- [认证 · 令牌刷新为什么这么难](https://daiw.org/manual/grok-build/auth-config.md): grok login 背后是一套比想象中复杂得多的鉴权：OIDC/OAuth2/device-code/外部命令四条路，令牌刷新的单点变更与双花防护，以及一个依赖倒置的 seam。这一章看它为什么难、又怎么做对——实现如今已拆成独立的 xai-grok-login crate。
- [遥测与用量 · 收什么、不收什么、怎么关](https://daiw.org/manual/grok-build/telemetry-usage.md): 一个开源 agent 收哪些数据、怎么保护隐私、企业怎么接自己的 collector？这一章看 grok 的三档遥测模式、内外两套 OTel 管道、外部遥测那三层 fail-closed 隐私防护，以及 /usage 用量视图。
- [Rust 工程底座 · 撑起这一切的不起眼零件](https://daiw.org/manual/grok-build/rust-engineering.md): Part 6 收官，看那些不产生「功能」、却决定产品稳不稳的 Rust 底座：proto 代码生成、熔断器、分布式追踪、信号安全的崩溃处理，以及原子的自更新。这一章串起 grok 反复出现的几个 Rust 工程范式。

### 第 7 部分 · 收尾

- [全表复盘 · 教学最小实现 vs grok 生产实现](https://daiw.org/manual/grok-build/recap-comparison.md): 读完全书，回到起点那张对照表，逐概念填上「grok 到底怎么做的」，把《从 LLM 到 Coding Agent》的每个教学点和 grok 的生产实现并排放。这一章是整本书的索引与提炼。
- [grok Build vs Claude Code · 两个编码 Agent 对照](https://daiw.org/manual/grok-build/grok-vs-claude-code.md): 你在本站另一本手册里熟悉了 Claude Code。这一章把它和 grok Build 摆在一起比：能力谱几乎重合，架构各有取舍，而 grok 有意兼容 Claude 生态——读 grok 的源码，某种意义上也在照见 Claude Code 的内部。
- [读完之后 · 继续读源码、动手改、用到你自己的 agent](https://daiw.org/manual/grok-build/whats-next.md): 全书收官。这一章不讲新代码，而是把方法论、几条最该记住的教训、以及「往哪走」交给你——怎么自己继续读 grok 的源码、怎么在本地动手改(上游不收外部 PR)、以及把这套工程智慧用到你自己的 agent 上。