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 元數據，該觀察僅適用於本次課程快照。源碼片段為教學截取，不攜帶提交歷史推斷。