Grok Build Source Course · 12 / 23

工程复盘：能力与边界一起读

公开源码能证明实现机制，也有明确的解释边界。优点从类型、状态机和测试中找证据，限制从 README、贡献政策、生成流程与本地快照条件中找证据。

Source-backedREADME-backedSnapshot BoundaryNo Popularity Guess
01 / OBJECTIVES

课程目标

从机制提炼优点

用类型、错误分支、状态机和测试证明工程特征。

从边界识别限制

区分产品限制、公开树限制与本地快照限制。

形成适用判断

说明哪些研究结论可复核，哪些问题仍需产品实测。

02 / CORE VISUAL

四层证据地图

03 / STRENGTHS

源码支持的工程优点

TYPE-GUIDED POLICY

工具能力变更会触发权限分流

ToolKind 的完整列表有编译期数量断言，capability filter 使用穷尽匹配。新增工具类别时，维护者必须重新作出保留或过滤决策。

capability.rs · tool.rs
FAILURE IS STATE

连接恢复考虑陈旧事件

MCP dispatcher 合并高频状态，移除客户端前核对 client_id，旧连接的迟到断线不会把替换后的健康客户端误删。

mcp_dispatcher.rs · mcp_restart.rs
TRUST BOUNDARY

插件发现与执行被拆开

项目插件按 canonical root 授权。未信任插件可提供元数据，但 hooks、MCP servers 与 scripts 被阻断，路径解析失败默认未信任。

plugins/trust.rs · discovery.rs
RECOVERABLE MEMORY

记忆拥有独立存储与检索模块

xai-grok-memory 将 schema、storage、FTS、embedding、MMR、Dream 与 lock 拆成明确模块，Session Actor 通过独立 memory state 接入。

xai-grok-memory · session/memory_state.rs
MULTIPLE ENTRY SURFACES

同一运行时覆盖交互、自动化与编辑器接入

README 明确列出 full-screen TUI、headless scripting/CI 与 ACP editor embedding。仓库布局将 pager、shell runtime、tools 与 workspace 分开说明，便于按入口定位责任。

README.md: 13-17, 83-94
04 / LIMITS

源码与文档支持的限制

MIRROR BOUNDARY

公开树是周期同步结果

README 写明仓库定期从 SpaceXAI monorepo 同步。因而当前树可用于源码透明和本地构建，不能自动代表内部主干的即时状态。

README.md: 31-32
CONTRIBUTION BOUNDARY

外部补丁不进入此仓库流程

CONTRIBUTING.md 明确不接收外部 pull request 或 unsolicited patch。Apache 2.0 许可提供使用与构建空间，贡献通道仍由发布政策单独约束。

CONTRIBUTING.md: 3-8
GENERATED ROOT

根 Cargo 不能按普通 workspace 维护

README 将根 Cargo.toml 标为 generated 与 read-only，建议修改各 crate 清单。脱离生成源直接改根配置，后续同步可能覆盖。

README.md: 96-99
BUILD HOST

源码树的 Windows 构建缺少当前测试保证

README 声明 macOS 与 Linux 是受支持构建主机，Windows 构建属于 best-effort，并且当前未从此源码树测试。

README.md: 51-61
POLICY TRADE-OFF

Hook 故障时优先工具可用性

Hook crash、timeout 与 bad output 采用 fail-open。这个选择减少误阻断，也意味着强制安全规则需要权限层或沙箱共同承担。

xai-grok-hooks/src/result.rs · dispatcher.rs
05 / SNAPSHOT

本次课程的四条适用边界

B1

周期同步

结论对应公开快照，不能给内部 monorepo 的实时版本作证明。

B2

无外部贡献

可以阅读、构建与按许可证使用，不能把公开仓库视为常规社区 PR 入口。

B3

根 Cargo 生成

依赖与 workspace 拓扑可能受生成流程控制，源码研究要追踪 per-crate 清单。

B4

缺少 Git 元数据

本地 grok-build-main 快照未携带 .git 目录，无法在该快照内核对 commit、tag、blame 与提交时间线。

结论口径：B4 是本地文件观察，B1 至 B3 有仓库文档支持。课程引用路径与行为，不把无法定位的提交哈希写成证据。

06 / SOURCE

把「好」改写成可检查约束

COMPILE-TIME CHECK

工具类别完整性

const _: () = assert!(
    ALL_TOOL_KINDS.len() == ToolKind::VARIANT_COUNT,
    "ALL_TOOL_KINDS is out of sync"
);
crates/codegen/xai-grok-workspace/src/capability.rs
FAIL-CLOSED TRUST

路径错误不会获得信任

match dunce::canonicalize(plugin_root) {
    Ok(canonical) => self.trusted.contains(&canonical),
    Err(_) => false,
}
crates/codegen/xai-grok-agent/src/plugins/trust.rs
07 / LAB

课堂练习：源码复盘审计

35 MIN

提交物
证据账本

  1. 选择三个优点，每项附一条源码路径、一个关键分支和一条相关测试。
  2. 选择三个限制，标注其属于产品、仓库、构建还是本地快照边界。
  3. 删除「生态大、社区强、体验最好」等无法由当前材料证明的句子。
  4. 为 fail-open Hook 写一个适用场景和一个不适用场景。
  5. 列出需要 release notes、线上文档或产品 PoC 才能回答的五个未知项。
Takeaway

高质量源码复盘要同时回答三件事：实现提供了什么约束，仓库以什么方式发布，当前材料缺少什么证据。限制写清楚，优点才更可信。

源码快照说明：本页依据本地 grok-build-main 的 README、CONTRIBUTING 与相关 Rust 源码整理。本地目录扫描未发现 .git 元数据，该观察仅适用于本次课程快照。源码片段为教学截取，不携带提交历史推断。