本集对应课程章节：CHAPTER 12（Grok Build 与 Claude Code 证据化对照 / 工程复盘与证据边界 / Coding Agent 设计工作台）
内容来源：xueai.miyang.cn（小山学堂 · 洛小山《学 AI 产品，从入门到精通》），本页为二次演绎的解读与音频稿件版本。
本集处理两个不同层级、但共享同一方法的问题：
共同点：两者都在对抗同一件事——用推断冒充事实。Coding Agent 领域信息噪声极大，「生态最强」「体验最好」「架构更先进」这类句子无法由材料证明，而它们恰恰最容易进入选型文档和汇报材料。
本集给出的解法是先建立证据等级，再谈取舍：把实现事实、产品行为、推断、未知项分成四堆，分别标注来源。
| 维度 | 读完本集你能做到 | 对应证据 |
|---|---|---|
| 证据分级 | 区分源码、仓库文档、官方公开文档、本地快照四类来源 | 课程证据索引表 |
| 对照读法 | 读懂十二行多维对照，知道空白项为何保留空白 | 完整证据化对照矩阵 |
| 机制 vs 行为 | 判断一行描述属于「机制」还是「用户可见行为」 | Grok 源码路径 vs Claude 官方页面 |
| 源码锚点 | 用一句编译期断言证明「新增工具必须重做权限决策」 | capability.rs 常量断言 |
| 失败默认值 | 说明路径解析失败为何映射为「不信任」 | plugins/trust.rs 的 canonicalize 分支 |
| 优点复盘 | 为每个优点给出源码路径 + 关键分支 + 相关测试 | 五条工程优点清单 |
| 限制分类 | 把限制归入产品 / 仓库 / 构建 / 本地快照四类边界 | 五条限制 + 四条快照边界 |
| 系统设计 | 按九个维度输出架构决定、故障路径与验证方式 | 九维决策卡 |
| 级别 | 名称 | 说明力 | 典型材料 |
|---|---|---|---|
| 源码证据 | Source | 最强，能证明机制 | 结构体定义、枚举、断言、错误分支、测试 |
| 仓库文档证据 | README / 指南 | 证明发布方式和维护政策，不证明运行时行为 | README.md、CONTRIBUTING.md、根 Cargo.toml 说明 |
| 官方公开产品文档 | Public Docs | 证明用户可见行为，不证明内部实现 | Overview、Hooks reference、MCP、Memory、Subagents、Permissions、Plugins |
| 本地快照观察 | Snapshot | 最弱，仅对本次快照成立 | 本地 grok-build-main 目录扫描结果 |
关键纪律：两列证据分辨率本就不同——Grok 一侧可下钻源码，Claude 一侧只记录官方公开行为。因此空白项保留空白，不用推测补齐。一份处处填满的对照表，反而应当被怀疑是否用架构猜测补了空。
| 维度 | Grok Build（源码 / 仓库文档） | Claude Code（官方公开行为） |
|---|---|---|
| 实现与分发 | Rust Cargo workspace，功能拆成多个 crate | 终端 CLI、IDE、Desktop、Web 四类入口；内部语言与模块边界不在本课范围 |
| 状态与并发 | SessionActor 持有会话历史与工具上下文，运行在 Tokio LocalSet；后台任务可独立回传 | 公开文档描述会话、后台任务、subagent、agent teams 行为；不推断内部并发模型 |
| 工具合约 | ToolKind 枚举进入 capability 过滤；新增 variant 有编译期同步断言；MCP 工具映射为 Other | 权限规则按 Read、Edit、Write、Bash、WebFetch、MCP 等工具名与参数模式控制 allow / ask / deny |
| 工具发现 | 内建工具静态注册；MCP 元数据进快照与 BM25 索引，靠 search_tool / use_tool 延迟发现 | Tool Search 可按需加载 MCP 工具，支持延迟连接等待与失败信息反馈 |
| 上下文压缩 | compaction 配置、分段、two-pass、full-replace 与 recap 辅助路径，可测试自动压缩与恢复 | 自动压缩、/compact、compact instructions；不描述内部算法 |
| 长期记忆 | xai-grok-memory 实现 SQLite 存储、FTS、embedding、MMR 与 Dream 整理流程，由 session memory state 集成 | 分层 CLAUDE.md 指令与 auto memory，作用域与加载规则由官方文档说明 |
| Hooks | 源码枚举 15 个事件；PreToolUse 可阻断；deny 明确阻断；Hook 崩溃 / 超时 / 失败输出走 fail-open；配置用 JSON | Hooks reference 公开多类事件、matcher、if 条件及 command、HTTP、MCP tool、prompt、agent 处理器；PreToolUse 可返回拒绝 |
| MCP | 确认客户端角色；支持 stdio 与 Streamable HTTP、OAuth、server__tool、动态能力刷新、状态合并与重启；未确认通用 MCP Server 入口 | 远程 HTTP、本地 stdio、WebSocket、OAuth、动态 list_changed、Tool Search 与连接管理 |
| 权限与沙箱 | ToolKind capability 过滤 + 权限提示 + 平台沙箱代码多层控制；Hook 失败策略不承担强制安全保证 | allow / ask / deny 规则、managed settings、sandboxed Bash 与文件系统、网络隔离配置 |
| Subagent | fork、任务、工作树池与 completed subagent worktree snapshot 配置，分支任务可放隔离工作树 | 独立上下文、工具与权限；可前台或后台运行；可按配置使用 worktree isolation |
| 插件生态 | Marketplace 支持索引与目录回退；安装 registry 保存来源；运行时按 scope、enabled、plugin-root trust 控制 | 官方插件与 marketplace 文档公开 skills、agents、hooks、MCP servers、LSP servers 与安装作用域 |
| 恢复与可观测 | 会话持久化、MCP 状态通知、50 ms 事件合并、重启退避、telemetry enums 与结构化事件 | session resume、verbose / debug、Hooks 状态、MCP 面板与权限诊断；内部持久化拓扑不作推断 |
读法规律：有源码的一侧描述机制，只有文档的一侧描述行为。这个规律本身就是对照表的结论——不要拿机制的强度去比行为的丰富度。
把每一行的两列都打上来源标签：源码 / 仓库文档 / 官方公开文档 / 本地快照。凡是你标不出来源的句子，一律删掉或移入「未知项」小节。空白项比填满的表格更可信——看到空白，是作者在告诉你这里没有证据。
锚点一：编译期同步断言
const _: () = assert!(
ALL_TOOL_KINDS.len() == ToolKind::VARIANT_COUNT,
"ALL_TOOL_KINDS is out of sync"
);
位置：crates/codegen/xai-grok-workspace/src/capability.rs
它把「新增工具后补权限决策」这件靠自觉的事，变成了编译期约束。新增工具类别时，维护者必须在编译通过前重新作出保留或过滤的决策。代码评审里说「建议加个检查」是建议；这句断言是已经发生的事实，任何人都能去该路径验证。
锚点二：失败默认值
match dunce::canonicalize(plugin_root) {
Ok(canonical) => self.trusted.contains(&canonical),
Err(_) => false,
}
位置：crates/codegen/xai-grok-agent/src/plugins/trust.rs
它把「无法判断」明确映射为不信任。很多系统的默认值是宽松的——路径读不出来就先放行；这里反过来，读不出来就不给信任。
证明一个系统好，需要三件套：一条源码路径 + 一个关键分支 + 一条相关测试。凑不齐就说明这个结论还只是印象。同时删掉「生态大、社区强、体验最好」这类无法由当前材料证明的句子。
| 优点 | 机制 | 源码落点 |
|---|---|---|
| 类型引导策略 | ToolKind 完整列表有编译期数量断言，capability filter 使用穷尽匹配 | capability.rs、tool.rs |
| 失败即状态 | MCP dispatcher 合并高频状态，移除客户端前核对 client_id，旧连接的迟到断线不会误删替换后的健康客户端 | mcp_dispatcher.rs、mcp_restart.rs |
| 信任边界 | 插件发现与执行拆开；未信任插件可提供元数据，但 hooks、MCP servers、scripts 被阻断；路径解析失败默认未信任 | plugins/trust.rs、discovery.rs |
| 可恢复的记忆 | xai-grok-memory 将 schema、storage、FTS、embedding、MMR、Dream、lock 拆成明确模块，会话侧经独立 memory state 接入 | xai-grok-memory、session/memory_state.rs |
| 多入口覆盖 | 同一运行时覆盖全屏 TUI、headless scripting / CI、ACP 编辑器嵌入；仓库布局把 pager、shell runtime、tools、workspace 分开说明 | README.md: 13-17, 83-94 |
「失败即状态」这一条尤其能体现工程成熟度：它说明作者想过时序问题，而不只想过高可用。
| 限制 | 内容 | 边界类别 |
|---|---|---|
| 镜像边界 | 仓库定期从 SpaceXAI monorepo 同步；当前树可用于源码透明与本地构建，不能代表内部主干的即时状态 | 仓库（README.md: 31-32） |
| 贡献边界 | 明确不接收外部 pull request 或 unsolicited patch；Apache 2.0 提供使用与构建空间，贡献通道由发布政策单独约束 | 仓库（CONTRIBUTING.md: 3-8） |
| 生成根 | 根 Cargo.toml 标为 generated / read-only，建议改各 crate 清单；脱离生成源直接改根配置可能被同步覆盖 | 仓库（README.md: 96-99） |
| 构建主机 | macOS 与 Linux 为受支持构建主机；Windows 构建属 best-effort，且当前未从此源码树测试 | 构建（README.md: 51-61） |
| 策略取舍 | Hook crash、timeout、bad output 采用 fail-open：减少误阻断，代价是强制安全规则需由权限层或沙箱共同承担 | 产品（xai-grok-hooks/src/result.rs、dispatcher.rs） |
本次快照四条适用边界
grok-build-main 快照未携带 .git 目录，无法在快照内核对 commit、tag、blame 与提交时间线。B1–B3 有仓库文档支持，B4 是本地文件观察。课程引用路径与行为，不把无法定位的提交哈希写成证据。
判断标准只有一句：如果这个钩子静默失败，最坏会发生什么？
| 维度 | 要回答的问题 | 提交成果 |
|---|---|---|
| ENTRY 运行入口 | 谁启动 Agent？交互、CI、IDE 是否共享同一核心？ | 入口矩阵 + CLI 参数草案 + 端到端启动时序图 |
| STATE 状态 / 并发 | 谁拥有会话状态？模型流与工具任务如何取消、排队、回传？ | 状态所有权图 + 并发时序 + 竞态测试清单 |
| MODEL LOOP 模型流 | 提示词、流式输出、工具调用、重试、停止与模型切换如何闭环？ | 模型循环状态机 + 停止条件 + 三类 API 错误策略 |
| TOOLS 工具合约 | 输入 Schema、返回值、错误、超时、幂等、权限类别如何标准化？ | 两个 JSON Schema + 错误分类表 + 合约测试 |
| CONTEXT 上下文 / 记忆 | 短期上下文何时压缩？长期记忆写什么、何时检索、如何删除？ | Token 预算表 + 压缩算法 + 召回与遗忘测试 |
| SECURITY 安全 | 权限、沙箱、Hook、网络、插件信任分别承担哪一层保证？ | 威胁模型 + 权限矩阵 + 5 条攻击用例 |
| RECOVERY 持久化 / 恢复 | 消息、工具结果、文件 checkpoint、外部连接状态如何持久化与重放？ | 存储 Schema + 崩溃注入脚本 + RPO / RTO 声明 |
| OBSERVABILITY 可观测 / 隐私 | 哪些事件进日志与指标？哪些必须脱敏、采样或禁止离开本机？ | 事件字典 + 脱敏表 + 3 个 SLO 与诊断查询 |
| EXTENSIONS 扩展生态 | MCP、Plugin、Hook 的发现、版本、启用、信任、卸载如何治理？ | 插件 manifest + 信任生命周期 + 兼容性策略 |
评分权重：边界与 ADR 20 分 · 合约与状态机 20 分 · 安全与恢复 25 分 · 测试与可观测 20 分 · 演示与证据 15 分。安全与恢复占比最高，权重本身即是态度。
四条否决项
拿到一份 Agent 源码复盘或对照报告，逐条自查：
不要写「这个更安全 / 更先进 / 生态更强」，改写成：
改完之后，别人能去复核，你自己也能去复核。
grok-build-main 快照；Claude 一侧依据 2026 年 7 月可访问的官方公开文档，仅陈述用户可见行为。Cargo.toml 为生成产物。工程判断的价值，不在于结论有多肯定，而在于结论能被多便宜地验证。 证据等级清楚之后，架构取舍才有可复核的基础。
来源：xueai.miyang.cn（小山学堂 · 洛小山《学 AI 产品，从入门到精通》）
本页为二次演绎的解读与音频稿件版本，音频与本页配套发布。