# Rust workspace 全景 · 96 个 crate 怎么分层

> Grok Build 是一个 96 个 crate 的 Cargo workspace。这一章不逐个念名字，而是把它们归到「组合根 / TUI / Agent 运行时 / 模型接入 / 工具能力 / 工作区 / 扩展 / 基础设施」几层，给你一张能按图索骥的分层地图。

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

# 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 摞成一张分层图（越上层越靠近用户，越下层越靠近底座）：

```mermaid
flowchart TB
  BIN["组合根: xai-grok-pager-bin"]
  subgraph TUI[TUI 层]
    P1[xai-grok-pager]
    P2[xai-grok-pager-render]
    P3[xai-grok-markdown]
  end
  subgraph RT[Agent 运行时]
    A0[xai-grok-shell]
    A1[xai-grok-agent]
    A2[xai-chat-state]
    A3[xai-grok-compaction]
    A4[xai-grok-memory]
  end
  subgraph MODEL[模型接入]
    M1[xai-grok-sampler]
    M2[xai-grok-sampling-types]
  end
  subgraph CAP[工具与能力]
    C1[xai-grok-tools]
    C2[xai-grok-shell-terminal]
    C3[xai-grok-sandbox]
  end
  subgraph WS[工作区与 Git]
    W1[xai-grok-workspace]
    W2[xai-codebase-graph]
    W3[xai-fast-worktree]
    W4[xai-hunk-tracker]
  end
  subgraph EXT[扩展机制]
    E1[xai-grok-mcp]
    E2[xai-grok-hooks]
    E3[xai-grok-plugin-marketplace]
  end
  subgraph BASE[基础设施]
    B1[xai-grok-config]
    B2[xai-grok-telemetry]
    B3[xai-tool-protocol]
  end
  BIN --> TUI --> RT --> MODEL
  RT --> CAP --> WS
  RT --> EXT
  RT --> BASE
```

各层一句话：

| 层 | 代表 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` 的物理行数算（括号里是剔除测试后的行数，口径见[专栏首页](https://daiw.org/manual/grok-build)的「源码基准」），最大的几个是：

- `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 转写）。

## 怎么按图索骥

以后想搞清某个功能，套路是固定的：

1. 先想它属于哪一层（改文件 → 工具能力层；主题 → TUI 层；MCP → 扩展层）；
2. 到对应 crate 的 `src/lib.rs` 看它导出了什么；
3. 顺着模块名往下钻。

<Callout type="info">
  一个实用习惯：`cargo check -p <crate 名>` 能只编译某个 crate 快速验证；`cargo doc -p <crate 名> --open` 能生成它的 API 文档。读大型 Rust 项目时，先看 crate 边界和 `lib.rs` 的导出，比一头扎进某个 `.rs` 文件高效得多。
</Callout>

到这里，Part 0 的骨架就立起来了：你知道了 grok 是什么、怎么跑、代码怎么分层。接下来（第 1 部分起）我们钻进 **Agent 运行时**——从那个把一切转起来的主循环开始。

---

上一篇：[装上就跑](https://daiw.org/manual/grok-build/install-and-run)