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 的官方架構模板。學員方案可以採用其他技術棧，但每項決策都要提供同等級證據。