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 中繼資料，該觀察僅適用於本次課程快照。原始碼片段為教學擷取，不攜帶提交歷史推斷。