Rust workspace 全景 · 96 个 crate 怎么分层
Grok Build 是一个 96 个 crate 的 Cargo workspace。这一章不逐个念名字，而是把它们归到「组合根 / TUI / Agent 运行时 / 模型接入 / 工具能力 / 工作区 / 扩展 / 基础设施」几层，给你一张能按图索骥的分层地图。
Rust workspace 全景 · 96 个 crate 怎么分层
打开根 Cargo.toml，members 列了 101 项（其中 96 个在 crates/ 下），第一次看会晕。但它们不是平的——按职责能归成几层，理清这张图，后面找任何一个功能都能一步定位到 crate。
三个大目录
workspace 的 crate 主要放在三处：
crates/codegen/—— 绝大多数业务 crate（83 个），名字多为xai-grok-*；crates/common/—— 更通用、可跨项目复用的基础件（12 个，如xai-tool-protocol、xai-circuit-breaker、xai-tracing、xai-grok-compaction）；crates/build/—— 构建期用的xai-proto-build（proto 代码生成）。
另有 5 个成员不在 crates/ 下：prod/mc/ 里一个共享类型的小 crate，以及 third_party/ 里 vendored 的 Mermaid 渲染栈（4 个）。
命名上记两条：xai-grok-* 是 grok 产品自己的 crate，xai-*（不带 grok）通常是更底层、更通用的件。
按职责分层
把重要 crate 摞成一张分层图（越上层越靠近用户，越下层越靠近底座）：
各层一句话：
| 层 | 代表 crate | 职责 |
|---|---|---|
| 组合根 | xai-grok-pager-bin | 拼装一切、产出 grok 二进制 |
| TUI | xai-grok-pager、-render、-markdown | 终端界面：滚动缓冲、输入、渲染、实时 markdown（第 5 部分） |
| Agent 运行时 | xai-grok-shell、xai-grok-agent、xai-chat-state、xai-grok-compaction、xai-grok-memory | 会话 actor 与主循环、Agent 对象与 prompt、会话状态、上下文压缩与记忆（第 1 部分） |
| 模型接入 | xai-grok-sampler、xai-grok-sampling-types | 以 actor 发起流式请求、统一多种 API 格式（第 1 部分） |
| 工具与能力 | xai-grok-tools（近 15 万行）、xai-grok-shell-terminal、xai-grok-sandbox | 编辑、搜索、执行、沙箱（第 2 部分） |
| 工作区与 Git | xai-grok-workspace、xai-codebase-graph、xai-fast-worktree、xai-hunk-tracker | 工作区抽象、代码库图谱、worktree、diff 追踪（第 3 部分） |
| 扩展机制 | xai-grok-mcp、xai-grok-hooks、xai-grok-plugin-marketplace、xai-grok-subagent-resolution | MCP、hooks、插件、subagent（第 4 部分） |
| 基础设施 | xai-grok-config、xai-grok-telemetry、xai-tool-protocol、xai-circuit-breaker | 配置、遥测、工具协议、熔断（贯穿全书） |
体量透露的重点
crate 的代码量本身就是一张「重点提示图」。按各 crate src/ 下 .rs 的物理行数算（括号里是剔除测试后的行数，口径见专栏首页的「源码基准」），最大的几个是：
xai-grok-pager+-render：50 万行级（非测试约 26 万）—— TUI 是全仓最大的一块，远不是薄壳，第 5 部分。xai-grok-shell：约 39 万行（非测试约 19 万）—— 会话 actor、主循环以及 ACP / headless 等入口都在这里，第 1、6 部分。xai-grok-tools：近 15 万行（非测试约 7 万）—— 工具系统是重头，单独一部（第 2 部分）。xai-grok-workspace：约 11 万行（非测试约 5 万）—— 工作区/代码库理解，第 3 部分。xai-grok-agent：约 2.2 万行（非测试约 1 万）—— 体量不大，负责造出 Agent 对象、组装 system prompt，第 1 部分开讲。
2026 年 7 月以来，crates/ 下净增了 22 个 crate，多半是从大 crate 里拆出来、或给新功能安家，例如 xai-grok-login（登录与凭证）、xai-grok-shell-terminal（本地 / ACP / PTY 终端 runner）、xai-grok-otel（OpenTelemetry）、xai-grok-workspace-daemon（workspace-server 守护进程）、xai-grok-session-search（本地会话全文检索）、xai-grok-status-line（状态栏）、xai-workflow（Rhai 脚本编排的工作流）、xai-compaction-transcript（压缩分段的 markdown 转写）。
怎么按图索骥
以后想搞清某个功能，套路是固定的：
- 先想它属于哪一层（改文件 → 工具能力层；主题 → TUI 层；MCP → 扩展层）；
- 到对应 crate 的
src/lib.rs看它导出了什么； - 顺着模块名往下钻。
一个实用习惯：cargo check -p <crate 名> 能只编译某个 crate 快速验证；cargo doc -p <crate 名> --open 能生成它的 API 文档。读大型 Rust 项目时，先看 crate 边界和 lib.rs 的导出，比一头扎进某个 .rs 文件高效得多。
到这里，Part 0 的骨架就立起来了：你知道了 grok 是什么、怎么跑、代码怎么分层。接下来（第 1 部分起）我们钻进 Agent 运行时——从那个把一切转起来的主循环开始。
上一篇：装上就跑