Grok Build Source Course · 12 / 24

Coding Agent 設計工作台

結課任務從功能清單升級為可運行的系統設計。你要為九個維度作出明確決定，每個決定都要附合約、故障路徑、驗證方式和可提交成果。

9 Decisions9 DeliverablesArchitecture + PoCEvidence Review
01 / OBJECTIVES

課程目標

完成系統邊界

定義入口、狀態所有權、模型循環與外部擴展的責任邊界。

補齊失敗設計

為工具、安全、持久化、恢復和狀態通知畫出失敗路徑。

產出可評審成果

提交 ADR、合約、威脅模型、測試與最小演示，不停留在概念圖。

02 / CORE VISUAL

一張圖看完整 Agent 系統

03 / BRIEF

結課項目簡報

任務

為一個真實團隊設計「倉庫級 Coding Agent」。它至少能讀取程式碼、提出計劃、修改檔案、執行驗證並恢復中斷會話。你可以實現最小 PoC，架構文檔必須覆蓋全部九維。

硬約束
  • 預設最小權限
  • 每個外部動作可追蹤
  • 崩潰後可解釋恢復
  • 敏感數據有明確落點
  • 擴展程式碼有信任邊界
04 / WORKBENCH

九維決策卡

ENTRY

運行入口

邊個啟動 Agent，交互、CI 同 IDE 係咪共用同一個核心？

源碼錨點：pager-bin composition root、shell headless/stdio、ACP gateway。

提交成果入口矩陣 + CLI 參數草案 + 一條端到端啓動時序圖。
STATE

狀態 / 併發

邊個擁有會話狀態，模型流同工具任務點樣取消、排隊同回傳？

源碼錨點：SessionActor、LocalSet、後台 summary/persistence actor。

提交成果狀態所有權圖 + 併發時序 + 競態測試清單。
MODEL LOOP

模型流

提示詞、流式輸出、工具調用、重試、停止同模型切換點樣閉環？

源碼錨點：run_loop、turn、tool_dispatch、model_switch、two_pass。

提交成果模型循環狀態機 + 停止條件 + 三類 API 錯誤策略。
TOOLS

工具合約

輸入 Schema、返回值、錯誤、超時、冪等性同權限類別點樣標準化？

源碼錨點：ToolKind、Tool Bridge、server__tool、capability filter。

提交成果兩個 JSON Schema + 錯誤分類表 + 合約測試。
CONTEXT

上下文 / 記憶

短期上下文幾時壓縮，長期記憶寫咩、幾時檢索、點樣刪除？

源碼錨點：compaction segments、two-pass、memory FTS/embedding/MMR/Dream。

提交成果Token 預算表 + 壓縮算法 + 記憶召回與遺忘測試。
SECURITY

安全

權限、沙箱、Hook、網絡同插件信任分別承擔邊一層保證？

源碼錨點：capability、sandbox、Hooks fail-open、plugin-root trust。

提交成果威脅模型 + 權限矩陣 + 5 條攻擊用例。
RECOVERY

持久化 / 恢復

消息、工具結果、檔案 checkpoint 同外部連接狀態點樣持久化同重放？

源碼錨點：session persistence、chat persistence、rewind、MCP restart。

提交成果存儲 Schema + 崩潰注入腳本 + RPO/RTO 聲明。
OBSERVABILITY

可觀測 / 隱私

邊啲事件入日誌同指標，邊啲內容必須脫敏、採樣或者禁止離開本機？

源碼錨點：file-utils events、telemetry enums、MCP status payload。

提交成果事件字典 + 脫敏表 + 3 個 SLO 與診斷查詢。
EXTENSIONS

擴展生態

MCP、Plugin 同 Hook 嘅發現、版本、啓用、信任同卸載點樣治理？

源碼錨點：marketplace index、manifest、install registry、trust store。

提交成果插件 manifest + 信任生命週期 + 兼容性策略。
05 / SOURCE MAP

真實源碼證據導航

入口與會話xai-grok-pager-bin/src/main.rs
xai-grok-shell/src/session/acp_session.rs
模型與工具session/acp_session_impl/run_loop.rs
xai-grok-workspace/src/capability.rs
上下文與記憶session/compaction.rs · two_pass.rs
xai-grok-memory/src/
安全與 Hooksxai-grok-sandbox
xai-grok-hooks/src/dispatcher.rs
恢復與狀態session/persistence.rs
mcp_dispatcher.rs · mcp_restart.rs
擴展xai-grok-plugin-marketplace/src/
xai-grok-agent/src/plugins/
EVIDENCE EXAMPLE

設計決定要能回到一個真實分支

// 插件根目錄無法 canonicalize 時，不授予信任
match dunce::canonicalize(plugin_root) {
    Ok(canonical) => self.trusted.contains(&canonical),
    Err(_) => false,
}

你的方案也要寫清失敗預設值。無法讀取策略、無法解析工具結果、無法恢復 checkpoint 時，系統分別應當停止、降級或請求用戶。

crates/codegen/xai-grok-agent/src/plugins/trust.rs
06 / RUBRIC

100 分評審量表

20邊界與 ADR
20合約與狀態機
25安全與恢復
20測試與可觀測
15演示與證據

否決項：提交物未説明敏感數據落點；高風險工具缺少權限路徑；崩潰後聲稱可恢復但沒有測試；引用源碼時無法給出檔案路徑。

07 / FINAL LAB

課堂練習：90 分鐘設計衝刺

90 MIN

最終提交包
可評審設計檔案

  1. 15 分鐘：定義用戶、倉庫、可執行權限和成功標準。
  2. 20 分鐘：完成核心視覺與九維決策卡，標出所有狀態所有者。
  3. 20 分鐘：實現一個工具合約與一條模型到工具的最小調用鏈。
  4. 15 分鐘：注入超時、權限拒絕和進程崩潰，記錄恢復結果。
  5. 10 分鐘：完成數據流、脫敏與插件信任檢查。
  6. 10 分鐘：用評審量表自評，提交 3 條 ADR、測試記錄和 5 分鐘演示腳本。
Takeaway

Coding Agent 的完成度體現在邊界與故障路徑。九維工作台幫助你把模型能力轉成可運行、可恢復、可審計、可擴展的工程系統。

源碼快照説明：本頁以本地 grok-build-main 作為設計案例庫，路徑錨點來自真實源碼。工作台中的交付格式屬於課程設計，不聲稱是 Grok Build 的官方架構模板。學員方案可以採用其他技術棧，但每項決策都要提供同等級證據。