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 的官方架构模板。学员方案可以采用其他技术栈，但每项决策都要提供同等级证据。