# grok-build 源码分析：xAI 的终端 AI 编程 Agent 是怎样炼成的

> **分析对象**：grok-build（`xai-org/grok-build`），官方发行版 CLI 名 `grok`
> **基于 commit**：main 分支（SOURCE_REV 文件记录同步自 xAI 内部 monorepo 的源 commit SHA）
> **分析日期**：2026-07-24
> **代码规模**：Rust monorepo，60+ crates，核心 crate 包含 xai-grok-shell（主入口）、xai-grok-agent、xai-grok-tools、xai-grok-workspace、xai-grok-pager（TUI）等
> **读者对象**：计算机初学者。本文会用大量比喻，并给出真实源码位置（`文件:行号`/`crate/模块`），你可以按图索骥。
> **说明**：本仓库是 xAI 内部 monorepo 的定期同步副本，不接受外部贡献（见 `CONTRIBUTING.md`）。

---

> 🗺️ **配套架构图**：本项目在[**七大 Agent 架构图库**](../架构图库.html#ch6)里有一张专门的图——**Goal Mode 四阶段状态机（含失败恢复路径）**。
> 图库的每张图都先写清「回答什么问题」和「承重墙论点」，并经三轮审阅与渲染验收。

## 第 1 章 项目概览

**grok-build 是什么？** 官方 README 说：" a terminal-based AI coding agent that runs as a full-screen TUI that understands your codebase, edits files, executes shell commands, searches the web, and manages long-running tasks"（一个在终端全屏运行的 AI 编程代理，能理解你的代码库、编辑文件、执行 shell 命令、搜索网络、管理长期任务）。安装后命令叫 `grok`，二进制本名 `xai-grok-pager`。

**谁在做？** xAI（马斯克创立的 AI 公司，Grok 系列模型的母公司）。仓库从 xAI 内部 monorepo 定期同步（根目录 `SOURCE_REV` 文件追踪每次同步的内部 commit SHA）。**22.2k stars、4.2k forks**，Apache 2.0 许可证（第三方依赖原许可证见 `THIRD-PARTY-NOTICES`）。

**定位与卖点**：

- **xAI 官方 CLI**：与 Grok 模型深度绑定（也支持 OIDC/外部 auth 接入其他端点），是官方推荐的"和 Grok 模型协作写代码"的方式；
- **Rust 单二进制**：整个 agent 编译成一个原生二进制（用 DotSlash 做工具链版本锁定），启动极快，无需 Node/Python 运行时；
- **Goal Mode（目标模式）**：这是 grok 最独特的功能——一种多阶段自主执行框架：你给出一个目标，grok 自动规划、执行、验证，卡住了还有"战略师"帮它恢复，完成后才停下来；
- **ACP（Agent Client Protocol）**：标准化的编辑器嵌入协议，已集成 Zed 编辑器，通过相同协议连接 TUI/无头模式/IDE；
- **企业级扩展**：OIDC 认证、公司代理、遥测配置、Marketplace 插件、MCP 服务器管理。

**技术栈**：**Rust**（Tokio 异步运行时），**Ratatui**（TUI 渲染库），**tree-sitter**（bash 命令语法树解析），**gix**（Git 操作），**JSONL**（会话持久化）。构建工具：Cargo，工具链版本锁在 `rust-toolchain.toml`，`protoc` 用于代码生成，DotSlash 做工具版本管理。

**与 Claude Code 的异同（一句话版）**：两者都是"终端 agent 循环 + 工具调用 + 权限门控"，但 Claude Code 绑定 Anthropic/Claude；grok 绑定 xAI/Grok，并以 Rust 单二进制、Goal Mode 自主执行、ACP 协议开放集成三件事与众不同。而且 grok 的发现路径同时支持 `.grok/agents/` 和 `.claude/agents/`——它有意兼容部分 Claude Code 用户习惯。

```mermaid
flowchart LR
    subgraph 用户感知
        A["grok<br/>xAI 官方编程 agent"]
    end
    A --> B["Goal Mode<br/>规划→执行→验证的多阶段自主循环"]
    A --> C["Rust 单二进制<br/>无运行时依赖，启动极快"]
    A --> D["ACP 协议<br/>TUI/无头/Zed 统一接口"]
    A --> E["Grok 模型深绑<br/>支持 OIDC/外部端点"]
    F["Claude Code"] -.对比.-> A
    F -.-> G["Anthropic 官方，TypeScript，绑 Claude 模型"]
```

---

## 第 2 章 全景架构

如果把 grok 比作一家公司：**TUI（xai-grok-pager）是前台接待**，**session actor（xai-grok-shell/src/session）是各个项目组**，**WorkflowManager 是项目管理中台**，**Agent（xai-grok-agent）是每个员工的岗位说明书 + 工具箱**，**ToolBridge（xai-grok-tools）是所有工具的统一货架**，**权限系统（xai-grok-workspace/src/permission）是公司合规部**，**Grok 模型 API 是外包给 xAI 的"决策大脑"**。

关键 crate 地图（全在 `crates/codegen/` 下）：

| crate | 职责 | 类比 |
| --- | --- | --- |
| `xai-grok-shell` | 主入口：CLI 解析、session 管理、扩展系统 | 公司主楼 |
| `xai-grok-pager` | TUI 渲染（Ratatui），含 bin/pager/render/pty-harness | 前台大厅 |
| `xai-grok-agent` | Agent 定义解析、构建器、发现、提示词渲染 | 岗位说明书 |
| `xai-grok-tools` | 所有工具实现（~25 个）+ ToolBridge 注册表 | 工具货架 |
| `xai-grok-workspace` | 文件系统操作、VCS、权限系统、worktree | 合规部 + 文件室 |
| `xai-acp-lib` | Agent Client Protocol（ACP），编辑器集成 | 对外接口协议 |
| `xai-grok-mcp` | MCP（Model Context Protocol）客户端 | 第三方工具插座 |
| `xai-grok-auth` | 认证中间件（credential provider + retry） | 门禁系统 |
| `xai-grok-config` / `xai-grok-config-types` | 配置读写（~/.grok/config.toml） | 公司规章 |
| `xai-chat-state` | 会话消息状态管理 | 会议纪要 |
| `xai-codebase-graph` | 代码库索引与代码导航 | 图书馆索引 |
| `xai-gix-status` / `xai-fast-worktree` | Git 状态与 worktree 操作 | 版本控制 |
| `ptyctl` / `ptyctl-cli` | PTY 控制（伪终端） | 终端设备 |
| `xai-grok-markdown` / `xai-grok-mermaid` | Markdown/Mermaid 渲染 | 排版室 |

整体数据流：

```mermaid
flowchart TB
    subgraph 接入层
        TUI["xai-grok-pager<br/>全屏 TUI (Ratatui)"]
        HEADLESS["grok -p<br/>无头/CI 模式"]
        ACP["ACP 客户端<br/>Zed / 其他 IDE"]
    end
    subgraph 会话层 ["xai-grok-shell / session"]
        SA["SessionActor<br/>actor 任务，持有 ChatState + MCP"]
        WFM["WorkflowManager<br/>最多 4 路并发 workflow"]
        GT["GoalTracker<br/>规划→执行→验证 状态机"]
        PM["PermissionManager<br/>ask / auto / YOLO"]
    end
    subgraph Agent层 ["xai-grok-agent"]
        AG["Agent<br/>定义 + 系统提示词 + ToolBridge"]
        CP["CompactionPolicy<br/>85% 阈值 + 二阶段可选"]
    end
    subgraph 工具层 ["xai-grok-tools"]
        TB["ToolBridge / 注册表<br/>~25 内置工具"]
        MCP["McpDispatcher<br/>外部 MCP 服务器"]
    end
    subgraph 外部
        LLM["Grok 模型 API<br/>xAI / OIDC 端点"]
        FS["文件系统 / Git"]
    end
    TUI --> SA
    HEADLESS --> SA
    ACP --> SA
    SA --> WFM --> GT
    SA --> AG --> TB
    TB --> PM
    TB --> MCP
    AG --> CP
    SA -->|采样请求| LLM
    TB --> FS
```

特别需要注意的是：grok 没有像 opencode 那样把"TUI 是独立客户端、服务器是 HTTP Worker"——grok 的 TUI（xai-grok-pager）与 shell 层运行在同一个进程内，通过 ACP 协议通信；但它的 ACP 层设计使得将来也可以支持远程连接。

---

## 第 3 章 启动流程

你在终端敲 `grok` 之后发生了什么？

**第一步：CLI 入口**。`crates/codegen/xai-grok-pager/src/bin/` 是二进制入口。启动参数支持三大模式：
- **交互 TUI**（默认）：全屏终端界面；
- **无头模式**：`grok -p "prompt"` 直接执行并退出；
- **ACP 模式**：`grok --acp` 暴露 Agent Client Protocol 供 IDE 连接。

**第二步：工作区发现**。启动时发现并信任当前工作区（`xai-grok-workspace/src/folder_trust.rs`，`trust.rs`）——这一步与 Claude Code 的"workspace trust"类似，但 grok 的实现更底层：它用 `xai-grok-workspace/src/discovery.rs` 扫描项目根目录（git repo 根）、加载 `.grok/config.toml`（项目级配置）和 `~/.grok/config.toml`（用户全局配置）。

**第三步：session actor 初始化**。`xai-grok-shell/src/session/acp_session.rs` 创建 **SessionActor**——它是一个 Tokio 任务，持有：
- `ChatStateHandle`：对话历史与 token 统计；
- `PermissionManager`（`xai-grok-workspace/src/permission/manager.rs`）：权限仲裁器；
- `McpState`：已连接的 MCP 服务器集合；
- `GoalTracker`：目标模式状态机；
- `State`（`TokioMutex` 保护）：当前活跃任务队列 + 排队输入。

**第四步：Agent 构建**。`xai-grok-agent/src/builder.rs` 的 `AgentBuilder.build()` 跑 10 步流程（详见第 5 章）：读 AgentDefinition → 发现 skills → 注入工具 → 过滤 allowlist/denylist → 创建 ToolBridge → 渲染系统提示词。默认 Agent 是 general-purpose（从 `discovery.rs` 的内置列表加载）。

**第五步：MCP 服务器后台初始化**。所有在 `~/.grok/config.toml` 里声明的 MCP 服务器异步并发初始化（`session/mcp_servers.rs`）。TUI 里可以看到每个服务器从 Initializing → Ready（或 NeedsAuth / Unavailable）的状态变迁。

**第六步：TUI 渲染启动**。`xai-grok-pager` 初始化 Ratatui 的全屏 alternate screen，首先显示欢迎页（AppView），用户发第一条消息后切换到 AgentView（第 4 章详述）。

```mermaid
sequenceDiagram
    participant U as 用户 (终端)
    participant CLI as xai-grok-pager/bin
    participant WS as xai-grok-workspace<br/>(工作区发现)
    participant SA as SessionActor
    participant AB as AgentBuilder
    participant MCP as McpState (后台)
    participant TUI as Ratatui TUI
    U->>CLI: grok
    CLI->>WS: 发现 git root, 加载 config.toml
    WS->>SA: 初始化 SessionActor + PermissionManager
    SA->>AB: build Agent (default: general-purpose)
    AB-->>SA: Agent(ToolBridge + 系统提示词)
    SA->>MCP: 后台并发初始化 MCP 服务器
    SA->>TUI: AppView (欢迎页)
    TUI-->>U: 全屏 TUI 就绪
    MCP-->>SA: Ready / NeedsAuth / Unavailable
```

---

## 第 4 章 输入捕获与分流

**TUI 怎么收输入？** `xai-grok-pager` 的 PromptWidget 是一个功能丰富的多行文本框（基于 `xai-ratatui-textarea`），支持：`@`触发文件搜索补全、`/`触发斜杠命令补全、`!`切换 bash 模式、Ctrl+P 打开命令面板（命令中控台）、多行切换、粘贴图片。键位绑定走 Elm 式架构：**用户按键 → Action → Effect → 更新 AppState**。

**回车后如何分流？** SessionActor 的输入队列（`State` 里的 `InputItem`）收到用户消息后，按以下规则分流：

| 输入类型 | 触发条件 | 去向 |
| --- | --- | --- |
| **Shell 模式** | 按 `!` 进入，输入任意命令 | 直接发给 BashTool 执行，不过模型 |
| **斜杠命令** | `/` 开头 + 已注册命令名 | 命令处理器展开模板，转普通提示词 |
| **Goal 模式触发** | `/goal "目标描述"` 或 UpdateGoalTool | 进入 GoalTracker 状态机（第 6 章） |
| **普通提示词** | 其他输入 | InputItem 进队，SessionActor 处理 |
| **排队** | agent 正忙时发消息 | "send_now" 优先级 FIFO 队列 |

**优先队列设计**：`State` 里维护"活跃任务"和"排队输入"两条线（`TokioMutex` 保护）。`send_now` 标志能让某些输入（比如紧急中断或合成 turn）绕队直接排到队首——这是 grok 的"可注入 turn"（injectable turn）设计，允许系统在 agent 循环安全点插入消息。

```mermaid
flowchart TD
    A["用户在 PromptWidget 输入并回车"] --> B{"输入类型?"}
    B -->|"! 开头 (bash 模式)"| C["BashTool 直接执行<br/>不经过模型"]
    B -->|"/ 开头 + 已注册命令"| D["命令模板展开<br/>转普通提示词"]
    B -->|"/goal ... 或 UpdateGoalTool"| E["GoalTracker<br/>进入自主目标循环"]
    B -->|"其他"| F{"agent 忙?"}
    F -->|闲| G["InputItem 进队<br/>SessionActor 立即处理"]
    F -->|忙| H["排到 send_now 队列<br/>等循环安全点接管"]
    C --> I["结果写入对话历史<br/>模型后续可见"]
    D --> G
    E --> J["Planning → Executing → Verifying<br/>多阶段自主循环"]
```

---

## 第 5 章 上下文组装

给模型发请求前，grok 要"组装一份完整的工作包"。这个过程由 `xai-grok-agent/src/builder.rs` 的 **10 步 build 流程**完成，每次会话开始或切换 Agent 时重新执行：

**Agent 定义文件**（`AgentDefinition`，`xai-grok-agent/src/config.rs`）：Markdown 文件，YAML frontmatter 是配置，正文是系统提示词内容。frontmatter 支持的字段极其丰富（摘录关键字段）：

```yaml
name: "my-agent"
permissionMode: default        # default / acceptEdits / auto / dontAsk / bypassPermissions / plan
tools: ["read_file", "grep"]   # 工具白名单（空则全部启用）
disallowedTools: []            # 工具黑名单
skills: ["rust", "git"]        # 注入的 skills 名单
discoverSkills: true           # 是否自动发现 skills
agentsMd: true                 # 是否加载 AGENTS.md
effort: high                   # 推理档位
maxTurns: 20                   # 最大 turn 数
model: "grok-4"                # 覆盖默认模型
completionRequirement:         # 完成要求（工具名 + 兜底 reminder）
  tool: "update_goal"
  reminder: "Call update_goal when done"
mcpServers: [...]              # 本 agent 专属 MCP 服务器
memory: session                # 记忆范围
```

**10 步 build 流程**（`AgentBuilder.build()`）：

1. **Resolve definition**：合并 builder 字段和 AgentDefinition；
2. **Discover skills**：从文件系统或预加载快照加载技能说明书；
3. **Inject skill prompts**：把技能内容前置拼进 `prompt_body`；
4. **Initialize tool config**：克隆 definition 的 tool 配置；
5. **Inject default tools**：按 feature flags 注入记忆、网络搜索、图片生成等工具；
6. **Filter tools**：移除禁用工具（记忆/ask_user_question/workflow 等可按 flag 关闭）；
7. **Apply allowlists/denylists**：执行 `tools`（白名单）和 `disallowedTools`（黑名单）过滤；
8. **Parse task directives**：从 `@agent(...)` 注解提取子 agent 类型约束；
9. **Merge parameters**：应用 bash、ask_user_question 参数覆盖；
10. **Finalize via ToolBridge**：创建 Agent，渲染系统提示词（`agent.finalize_prompt().await`）。

**系统提示词渲染**：`xai-grok-agent/src/prompt/context.rs` 的 `PromptContext.render()` 用 **MiniJinja** 模板引擎渲染（AgentDefinition 的 `prompt_mode` 决定模板选择：`extend` = 追加到基础模板、`full` = 完全自定义）。两种提示词模式：

- **extend**（默认）：grok 官方基础提示词 + 用户 frontmatter 正文；
- **full**：用户完全控制，MiniJinja 变量注入（可引用工具列表、当前模型名、日期等）。

**AGENTS.md / agents_md_files 收集**（`xai-grok-agent/src/agent.rs` 的 `agents_md_section()`）：读取 `.grok/AGENTS.md`、`.claude/AGENTS.md`（兼容 Claude Code）；中途发现新文件也会触发 `agents_md_user_reminder()` 提醒。

**系统 reminder 机制**（`xai-grok-agent/src/system_reminder.rs`）：两套独立的 reminder：
- **TodoNudge**：3 轮没写 todo_write 就提醒，两次提醒间至少间隔 5 轮（防止刷屏）；
- **TodoGate**：turn 结束时检查是否有待办未完成（默认**关闭**，需显式开启），每个 prompt 最多触发 2 次（`DEFAULT_TODO_GATE_MAX_FIRES = 2`，`system_reminder.rs`），防止计费爆炸。

```mermaid
flowchart TB
    subgraph AgentDefinition["AgentDefinition (Markdown + YAML frontmatter)"]
        D1["permissionMode / tools / skills<br/>model / effort / maxTurns"]
        D2["prompt_mode: extend / full<br/>MiniJinja 模板正文"]
    end
    subgraph Build["AgentBuilder.build() 10步"]
        S1["1-2 Resolve + Skills 发现"]
        S2["3 Inject skill prompts"]
        S3["4-7 工具注入/过滤/白名单/黑名单"]
        S4["8-9 task 指令 + 参数覆盖"]
        S5["10 ToolBridge 创建 + finalize_prompt"]
    end
    subgraph Prompt["系统提示词 (MiniJinja 渲染)"]
        P1["基础人格提示词<br/>(extend = 官方模板)"]
        P2["AGENTS.md / .claude/AGENTS.md"]
        P3["skills 清单前置"]
        P4["工具列表 / 日期 / 模型 / 工作区"]
    end
    D1 --> S1 --> S2 --> S3 --> S4 --> S5
    D2 --> S5
    S5 --> P1
    S5 --> P2
    S5 --> P3
    S5 --> P4
    P1 & P2 & P3 & P4 --> FINAL["最终系统提示词<br/>Agent.system_prompt"]
```

---

## 第 6 章 Agent 主循环（心脏）

grok 的"心脏"分**两个层次**：普通 turn 循环（类似所有 agent 的标准模式）和独特的 **Goal Mode 循环**。

### 6.1 普通 Turn 循环

普通会话的主循环在 `xai-grok-shell/src/session/acp_session.rs`（SessionActor 的 turn 处理流程）：

1. **从 InputItem 队列取输入**（支持 send_now 优先级排序）；
2. **判断是否可注入**："session is idle and safe to inject"断言防止在活跃 turn 中插入合成消息；
3. **Prompt 组装**：拼系统提示词 + 历史消息（`ChatStateHandle`）+ 工具定义（`ToolBridge`）；
4. **发起采样（sampler invocation）**：流式请求 Grok 模型 API，边收流边处理事件；
5. **工具调用分发**：收到 tool_call → ToolBridge 查找工具实现 → 走权限门控（第 7 章）→ 执行 → 结果追加历史；
6. **Turn 终止判断**：模型 finish 不含 tool_calls，且无待处理工具结果 → break；
7. **遥测 + 持久化**：token 统计写入 ChatState，对话历史写 JSONL（`session/storage/`）。

**Doom-loop 防御**（`acp_session.rs`）：连续相同工具调用触发 doom-loop recovery policy，类似 opencode 的 `DOOM_LOOP_THRESHOLD`。

**Rewindability 追踪**：turn 开始时标记"可回退"，一旦有第一个出站事件就清除——这让系统能区分"失败前还没产生副作用"和"已有副作用"两种情形。

### 6.2 Goal Mode 循环（grok 的核心差异）

这是 grok 最独特的地方。Goal Mode 是一个**多阶段自主执行框架**，由 5 个核心模块 + 1 个协调器（GoalOrchestrator）驱动，外加独立的 Stall 检测：

**GoalTracker**（`goal_tracker.rs`）：纯状态机（无异步 I/O），维护目标的完整生命周期：

- **阶段（GoalPhase）**：`Idle → Planning → Executing`
- **状态（GoalStatus）**：`Active / UserPaused / BackOffPaused / NoProgressPaused / InfraPaused / Blocked / BudgetLimited / Complete`
- 历史事件日志（最多 64 条，含时间戳）、token 预算追踪、**Per-goal scratch 目录**（带 symlink 攻击防护）

**GoalPlanner**（`goal_planner.rs`）：**Fail-closed 规划器**。接收目标描述，派生一个子 agent，要求它把完整计划写到 `plan.md`（而不是在对话里随便说说）。成功条件：plan 文件存在 + 非空 + 子 agent 最终响应是字面量 `"Done"`；任何一个条件不满足 → `FailClosed`（目标暂停），绝不允许破损的计划悄悄继续。有两条派生路径：
- **inherit 路径**：沿用当前模型/工具集，单次尝试；
- **override 路径**：使用配置指定的模型/工具集，非取消错误时重试一次（换回默认工具集）；
- 取消信号（用户 Ctrl+C）原样传播，不触发重试。

**GoalStrategist**（`goal_strategist.rs`）：**Fail-open 战略师**。N 次连续验证失败后触发（不是暂停，而是"最后努力"）：
- 读取工作区 artifacts 和 trace 文件，分析卡壳原因；
- 把补救建议写入 strategy note 文件（不写回 plan.md！）；
- **PlanGuard RAII**：派生前快照 plan.md 字节，执行后无论成败都恢复——防止战略师意外污染规划师的合同文件；
- 战略师失败 → 记录遥测，主循环继续（fail-open，不因战略师报错而中止目标）。

**GoalStopDetector**（`goal_stop_detector.rs`）：**提前放弃检测器**。扫描模型 turn 的**最后一段非空段落**，用 `^` 锚点正则匹配 9 类"放弃信号"：

| 类别 | 示例模式 |
| --- | --- |
| 无法继续 | "I can't proceed", "I cannot continue" |
| 放弃 | "Giving up", "task is not actionable" |
| 停在这里 | "Stopping here", "Paused here" |
| 飞行中的子 agent | "3 agents in flight", "Loop active" |
| 待你回来 | "I'll retry when X"（非用户指示的延迟） |
| 裁定行 | "VERDICT: PASS/FAIL" |
| 提交/PR | "Pushed to", "Opened PR" |
| 待审查 | "Ready to merge", "Ready to ship" |
| Please 推脱 | "Please provide", "Please configure" |

**GoalOrchestrator**（`goal_orchestrator.rs`）：通知发送器，把 GoalTracker 快照转换成 ACP wire 格式的 `GoalUpdated` 事件，区分"持久化"和"仅广播"两种发送（高频 live-token tick 只广播不落 JSONL，防止日志无限增长）。

**GoalClassifier**：验证目标是否真正完成。运行上限是 `classifier_max_runs`，超出限制则触发 `BackOffPaused`。`last_classifier_verdict` 记录最近一次判断结果（`Achieved` / `NotAchieved`）。

**Stall 检测**：相同的 gap fingerprint 出现两次 → 触发 early-exit（NoProgressPaused），防止目标在死胡同打转而不自知。

**token 预算**：`GoalOrchestration` 里 `token_budget / tokens_used / token_baseline` 三字段精密追踪。`live_subagent_tokens` 字段仅在活跃子 agent 运行时有值；两个以上不同模型才发送 `live_tokens_by_model` 分解（单模型情况合并，防止 1 元素 vec 扰乱 UI）。

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Planning : /goal 命令 / UpdateGoalTool
    Planning --> Executing : GoalPlanner.Planned
    Planning --> UserPaused : FailClosed / 用户中断
    Executing --> Executing : GoalStrategist (fail-open)<br/>战略师建议后继续
    Executing --> UserPaused : Ctrl+C / GoalStopDetector 检测到提前放弃
    Executing --> BackOffPaused : classifier 超限
    Executing --> NoProgressPaused : stall 检测（相同 gap fingerprint）
    Executing --> InfraPaused : 基础设施错误
    Executing --> BudgetLimited : token 预算耗尽
    Executing --> Blocked : 目标不可达
    Executing --> Complete : GoalClassifier 确认完成
    UserPaused --> Executing : 用户 Resume
    BackOffPaused --> Executing : 间隔后 Resume
```

---

## 第 7 章 工具系统与权限

### 7.1 工具全清单

`xai-grok-tools/src/implementations/grok_build/mod.rs` 是新架构工具的注册入口（`NewTool` trait）：

| 分组 | 工具名 | 功能摘要 |
| --- | --- | --- |
| 文件读取 | `ReadFileTool` | 读文件，支持偏移量和行数限制 |
| 文件读取 | `GrepTool` | 正则搜索（底层 ripgrep） |
| 文件读取 | `ListDirTool` | 列目录 |
| 文件修改 | `SearchReplaceTool` | 精确字符串替换（须先 Read） |
| 执行 | `BashTool` | 执行 shell 命令（带权限门控） |
| 执行 | `TaskTool` | 派生后台任务 |
| 执行 | `KillTaskTool` / `KillTerminalCommandTool` | 终止任务 |
| 任务输出 | `TaskOutputTool` / `WaitTasksTool` / `GetTerminalCommandOutputTool` | 读后台任务输出/等待完成 |
| 计划 | `TodoWriteTool` | 维护待办清单 |
| 目标 | `UpdateGoalTool` | 更新/完成 Goal Mode 目标 |
| 计划模式 | `EnterPlanModeTool` / `ExitPlanModeTool` | 进入/退出只读计划模式 |
| 调度 | `SchedulerCreateTool` / `SchedulerDeleteTool` / `SchedulerListTool` | 创建/删除/列出定时任务 |
| 网络 | `WebFetchTool` | 抓取 URL 转 Markdown |
| 网络 | `WebSearchTool` | 联网搜索 |
| 监控 | `MonitorTool` | 监控后台任务流式输出 |
| 用户交互 | `AskUserQuestionTool` | 向用户提问（可 feature-flag 关闭） |
| 多模态 | `ImageEditTool` / `ImageGenTool` | 图片编辑/生成 |
| 多模态 | `ImageToVideoTool` / `ReferenceToVideoTool` | 图转视频/参考图生成视频 |
| LSP | `LspTool` | 语言服务器集成（定义/引用/诊断等） |
| 工作流 | `WorkflowTool` | 触发预定义工作流 |
| 部署 | `DeployAppTool` | 应用部署 |
| 记忆 | （见 `implementations/memory/`） | 跨会话记忆读写 |
| Skills | （见 `implementations/skills/`） | 按需加载 skill 说明书 |

**与其他 agent 的显著差异**：grok 有多媒体生成工具（ImageGenTool/ImageEditTool/ImageToVideoTool/ReferenceToVideoTool），这直接体现了 xAI 的多模态布局；`SchedulerCreateTool` 系列实现了定时任务（cron-style）；`WorkflowTool` 支持触发预定义的工作流脚本。

**工具注册架构**：旧 `Tool` trait 和新 `NewTool` trait 并存（mod.rs 注释里有"new-architecture"说明）；`ToolBridge` 是统一的访问门面（`xai-grok-tools/src/bridge.rs`），`tool_definitions()` 和 `tool_definitions_builtins_only()` 分别返回含/不含 MCP 工具的定义列表。`ToolBridge` 内部有锁（Arc<内部锁>），工具状态变更（MCP 注册、completion tracking、retry 配置）通过锁安全更新。

### 7.2 Bash 工具的特殊处理

`BashTool` 在执行前必须经过 **PermissionManager** 的 bash 命令分类（`xai-grok-workspace/src/permission/bash_command_splitting.rs`）——用 **tree-sitter** 解析 bash AST，多维度风险评估：

- **安全命令白名单**：ls、cat、git read-only 操作、kubectl get 等直接放行；
- **危险命令检测**：rm、chmod、git push、`dd`、`mkfs` 等触发提示或拒绝；
- **rg --pre 风险**：`rg --pre` 会把文件内容喂给一个预处理命令执行，等于任意代码执行，单独检测；
- **kubectl 注入向量**：`--kubeconfig`、auth 注入 flag 单独拦截；
- **BSD ps 环境泄露**：BSD 风格 `ps -eE` 等 flag 能打印所有进程环境变量，单独标记；
- **不透明 shell 结构**：动态 `eval`、heredoc 无法静态分析，保守提示而非静默放行（"fail-safe"原则）。

### 7.3 权限仲裁器

`xai-grok-workspace/src/permission/manager.rs`（**8759 行**，权限系统最大单文件）实现了三种决策模式：

```
YOLO（总是批准）→ 用于 --yolo / bypassPermissions 模式
Auto（LLM 分类器）→ 用于 auto 模式，LLM 给出 allow/deny 判断
Ask（提示用户）→ 默认，弹出询问
```

**Auto 模式的安全限制**：
- 连续自动拒绝超过 3 次 → 强制回落到 Ask
- 总自动拒绝超过 20 次 → 强制回落到 Ask
- 防止分类器在错误模式下无限拒绝导致 agent 卡死。

**用户授权持久化**：用户的批准决定落盘（`exec_risk.rs` + `state.rs`），下次同类操作不再重问。

**gate_preflight.rs**：工具执行前的预飞检查，在进入 LLM 分类器或弹窗之前做快速规则匹配（提升响应速度）。

```mermaid
flowchart TD
    A["工具 execute() 被调用"] --> B["gate_preflight<br/>快速规则匹配"]
    B --> C{"permission_mode"}
    C -->|bypassPermissions / YOLO| D["直接放行"]
    C -->|plan| E["编辑工具? → deny<br/>读取工具 → allow"]
    C -->|auto| F["bash_command_splitting<br/>tree-sitter 解析"]
    F --> G{"风险级别"}
    G -->|安全白名单| D
    G -->|危险| H["LLM 分类器"]
    H --> I{"分类结果"}
    I -->|allow| D
    I -->|deny| J["拒绝 + 记录<br/>连续3次/总计20次 → 回落 Ask"]
    C -->|default / acceptEdits| K{"是否首次或未记忆?"}
    K -->|已批准| D
    K -->|未知| L["弹窗询问用户<br/>(Once / Always / Deny)"]
    L -->|Once| D
    L -->|Always| M["持久化批准决定<br/>以后不再问"]
    L -->|Deny| N["DeniedError → 模型收到错误"]
    M --> D
```

---

## 第 8 章 上下文压缩与记忆

### 8.1 CompactionPolicy

`xai-grok-agent/src/compaction.rs` 定义压缩策略（默认值）：

```rust
pub struct CompactionPolicy {
    pub auto_compact_threshold_percent: u32,  // 默认 85%
    pub compact_model: Option<String>,         // None = 用会话当前模型
    pub memory_flush_enabled: bool,            // 默认 false
    pub wall_clock_budget_secs: u64,           // 默认 300 秒
    pub two_pass_enabled: bool,                // 默认 false
}
```

**触发条件**：`Agent.should_auto_compact()` 调用 `xai_token_estimation::exceeds_threshold(total_tokens, cw, threshold_percent)`（`agent.rs`）：总 token 数达到上下文窗口的 85%（可配置）时返回 `true`，主循环下一轮触发压缩。

### 8.2 两阶段压缩（two_pass_enabled）

这是 grok 相比其他 agent 最复杂的压缩机制（`session/helpers/session_compact.rs`，`full_replace_compaction.rs`）：

- **单阶段（默认）**：接近阈值时，压缩 agent 对历史前段生成摘要，保留尾部（保证连贯性），摘要替换旧历史；
- **两阶段（two_pass_enabled = true）**：
  1. **预触发（Pass 1，后台投机）**：用量接近阈值时，提前在后台对历史前段生成 NOTE₁（摘要草稿），**不等到真正达到阈值**；
  2. **真正压缩（Pass 2，在阈值触发时）**：对 NOTE₁ + 近期尾段再生成最终摘要。
  
  这样摘要质量更高（两次压缩减少信息损失），且真正触发时 Pass 1 的结果已就绪，延迟更低。

**wall_clock_budget_secs = 300**：单次压缩生成最多跑 300 秒，超时截断并重试——这是针对"reasoning 模型思考过长"的专项防御（注释原文："`a generation exceeding it is cut and retried — the backstop for reasoning runaways token limits miss`"）。

**memory_flush_enabled = false**：开启后，每次压缩前先跑一轮 memory flush turn——让模型从当前对话摘出要长期记住的信息，写入记忆系统，再压缩历史。默认关闭，因为会额外消耗 token 和时间。

**session_recap.rs / session_summary.rs**：生成会话摘要（用于会话列表展示和搜索索引），独立于压缩流程。

**compaction_context.rs / memory_context.rs**：准备压缩/记忆 flush 时需要的上下文（历史切片、保护段落选择等）。

### 8.3 记忆系统

`xai-grok-shell/src/session/memory/` 只有 `mod.rs` 和 `hooks.rs` 两个文件，说明记忆系统是**钩子式集成**而非独立模块：

- **AgentDefinition.memory 字段**：每个 agent 可以声明自己的记忆范围（`MemoryScope`），可以是 `session`（会话级）或更持久的范围；
- **memory_flush_enabled = true 时**：memory hooks 在压缩前触发，让模型主动提炼和存储重要信息；
- **UpdateGoalTool**：Goal Mode 结束时调用此工具，可以将目标完成情况写入记忆；
- `implementations/memory/`：具体的记忆工具实现（读、写、检索）。

相比 opencode 完全依赖 `AGENTS.md` 人工维护、Claude Code 有自动记忆机制，grok 的记忆系统是**选配式**：默认轻量（会话级），需要时开启 memory_flush 或用 UpdateGoalTool 主动写入。

```mermaid
flowchart TD
    A["每轮 turn 结束统计 token"] --> B{"总 token ≥ 上下文窗口的 85%?"}
    B -->|否| C["继续"]
    B -->|是| D{"two_pass_enabled?"}
    D -->|是| E["Pass 1 已在后台生成 NOTE₁"]
    D -->|否| F["直接进入单阶段压缩"]
    E --> G["Pass 2: NOTE₁ + 尾段 → 最终摘要<br/>wall_clock 超 300s → 截断重试"]
    F --> G
    G --> H{"memory_flush_enabled?"}
    H -->|是| I["memory flush turn<br/>模型摘出重要信息 → 记忆系统"]
    H -->|否| J["摘要替换历史前段<br/>保留尾部保证连贯"]
    I --> J
    J --> K["从新的历史基线继续"]
```

---

## 第 9 章 子 Agent 与多 Agent

**工作流管理器**（`session/workflow/manager.rs`）：grok 的多 agent 并发管理核心，关键约束：**最多 4 路 workflow 并发运行**（`WorkflowManager` 硬上限）。每条 workflow 有：
- 唯一 run ID + journal 文件（支持 resume 恢复）；
- CancellationToken（可独立取消）；
- 暂停（pause）时先设 pause 标志再发取消信号——区分"主动暂停"和"真正取消"，防止状态误判；
- `cancel_all_and_drain()`：关闭时的优雅清场（含超时）。

**子 agent 派生**（`TaskTool`）：模型调用 `TaskTool` → 后台启动新的 session actor（子 agent）→ 主 agent 可等待结果（同步）或立即返回（异步后台）。

**AgentDefinition 级约束**：
- `allowed_subagent_types`：白名单，只允许派生特定类型子 agent；
- `session_tools_allowlist` / `session_tools_denylist`：子 agent 的工具可见性控制；
- `inject_default_tools`：子 agent 默认工具注入的总开关；
- `capability_mode`：`SubagentCapabilityMode`（来自 `xai-tool-types`），控制子 agent 的能力集合。

**Agent 发现与优先级**（`xai-grok-agent/src/discovery.rs`）：

```
项目级 (.grok/agents/ 或 .claude/agents/)
  优先覆盖
用户级 (~/.grok/agents/ 或 ~/.claude/agents/)
  优先于
打包级 (~/.grok/bundled/agents/)
  优先于
内置（general-purpose / explore / plan）
```

注意：**用户级 agent 不能遮蔽内置 subagent**（`all_subagents()` 的 `merge_subagents()` 有此限制）——这保证了内置子 agent 的行为稳定性，而只有项目级定义能真正覆盖内置行为。

**Plugin agent**：通过 `by_name_in_cwd_with_plugins()` 支持 `plugin-name:agent-name` 的限定名寻址；有模糊检测（多个插件提供同名 agent 时报错）。

**Goal Mode 的子 agent 架构**：Goal Mode 本身就是一个多 agent 协作流：
- **GoalPlanner**：独立子 agent，专门写 plan.md；
- **GoalStrategist**：独立子 agent，专门分析卡壳；
- **GoalClassifier**：独立子 agent，专门验证目标完成；
- **GoalWorker**：执行阶段的主 agent（即当前 session actor 自身的 turn）；
这些模块轮番上阵，完成"规划→执行→验证→恢复"完整闭环，而不是一个 agent 全包。

```mermaid
sequenceDiagram
    participant User as 用户
    participant Main as 主 SessionActor
    participant WFM as WorkflowManager
    participant GP as GoalPlanner (子 agent)
    participant GW as Goal 执行 agent
    participant GS as GoalStrategist (子 agent)
    participant GC as GoalClassifier (子 agent)
    User->>Main: /goal "重构认证模块"
    Main->>WFM: 新建 workflow run (≤4 并发)
    WFM->>GP: spawn GoalPlanner
    GP-->>WFM: plan.md 写成 (Planned) / 失败 (FailClosed)
    WFM->>GW: 开始 Executing 阶段
    loop 执行循环
        GW->>GW: 读 plan.md, 按步骤执行工具
        GW->>GC: 每轮验证 (GoalClassifier)
        GC-->>GW: Achieved / NotAchieved
        alt N 次连续失败
            GW->>GS: spawn GoalStrategist
            GS-->>GW: strategy_note.md (PlanGuard 保护 plan.md)
        end
        alt stall 检测 / budget 超限
            GW-->>WFM: NoProgressPaused / BudgetLimited
        end
    end
    GC-->>WFM: Achieved → Complete
    WFM-->>User: 目标完成通知
```

---

## 第 10 章 生态

### 10.1 斜杠命令

grok 的命令分两类：TUI 应用层命令（操作界面）和服务端命令（操控 agent 行为）。关键服务端命令（`session/commands.rs`）：

| 命令 | 功能 |
| --- | --- |
| `/goal <描述>` | 启动 Goal Mode 自主任务循环 |
| `/compact` | 手动触发上下文压缩 |
| `/recap` | 生成当前会话摘要 |
| `/skills` | 列出可用 skills |
| `/agents` | 列出可用 agent 定义 |
| `/model <名>` | 切换模型 |
| `/effort <级>` | 切换推理档位 |
| `/memory` | 查看/管理记忆 |

TUI 应用层常见命令（通过 Ctrl+P 命令面板访问）：

- 会话管理：新建、搜索历史会话（FTS）；
- 工作区：切换工作目录、git 状态；
- 设置：主题、键位、遥测开关。

### 10.2 Skills（技能说明书）

Skills 是 grok 的轻量扩展机制（`xai-grok-tools/src/implementations/skills/`）：把某项知识（比如如何用 Rust 的某个库、某个公司内部 API 规范）写成 Markdown，放到指定目录，agent 需要时按名加载进上下文。

发现路径（按优先级）：
1. `.grok/skills/` 或 `.grok/skill/`（项目级）
2. `~/.grok/skills/`（用户级）
3. `~/.claude/skills/`（兼容 Claude Code）
4. `.agents/` 等其他约定目录

AgentDefinition 的 `discover_skills: true`（默认）自动扫描；`inherit_skills: true` 从父 agent 继承 skills 列表。系统提示词里只放 skills 名单，正文按需加载——"用到才翻说明书"，省 token。

### 10.3 MCP（Model Context Protocol）

`xai-grok-mcp` crate + `session/mcp_dispatcher.rs` + `session/mcp_servers.rs`：

**MCP Dispatcher**（`mcp_dispatcher.rs`）的核心设计：**50ms 滚动窗口**——把频繁的 MCP 客户端事件（连接/断开/状态变化）合并成批次，再发 ACP 通知，防止状态抖动刷屏。`last-write-wins` 策略：同一 (server, kind) 对在窗口内只保留最新状态。

**McpServerStatus**：`Ready / Initializing / Unavailable / NeedsAuth`。NeedsAuth 状态会在 TUI 里提示用户去配置认证。

**ShutdownState**：追踪"主动删除"的服务器（ConfigRemoved）和"有重启任务在飞"的服务器，防止把主动删除的服务器当成意外掉线而触发自动重启。

**auto-restart 策略**：stdio 服务器意外断开 → spawn 重启任务；HTTP 服务器断开 → in-place 恢复（不重新 spawn 进程）。

**MCP 工具命名**：服务器名_工具名（sanitize 处理），与 opencode 的规则类似。

**AgentDefinition.mcp_servers**：每个 agent 可以声明自己专属的 MCP 服务器（`McpServerRef` 列表），通过 `mcp_inheritance` 控制是否从父 agent 继承全局 MCP 配置。

### 10.4 Hooks 系统

`xai-grok-shell/src/session/extensions/` 目录下有 `hooks.rs`，以及 `xai-grok-hooks` 独立 crate。Hooks 允许用户在关键事件节点（before/after 工具执行、session 启动/结束、turn 开始/结束等）注入自定义 shell 命令或脚本——这是 grok 的自动化扩展接口。

### 10.5 Plugin Marketplace

`xai-grok-shell/src/plugin.rs` 实现了完整的插件生命周期管理：

**安装来源**：
- Git 仓库（含 GitHub 快捷方式 `owner/repo`）；
- 本地目录（symlink，开发时用）；
- Marketplace（qualified name 解析，含 `owner/repo` qualifier）。

**安全控制**：受限环境下的 allowlist 过滤——企业内部部署可以只允许白名单里的插件来源，防止随意拉取外部代码。

**InstallRegistry**：持久化追踪每个已安装的 plugin repo（含 git commit hash、plugin 名、marketplace 来源），支持精确到提交的版本回溯。

**歧义检测**：多个 marketplace 提供同名插件时，报错要求用 qualified 名称——不允许"谁先装谁生效"的模糊行为。

```mermaid
flowchart TB
    subgraph 命令来源
        A["/goal / /compact / /recap"]
        B["TUI Ctrl+P 命令面板"]
    end
    subgraph Skills
        C[".grok/skills/ → ~/.grok/skills/<br/>~/.claude/skills/ (兼容)"]
    end
    subgraph MCP
        D["mcp_dispatcher<br/>50ms 窗口合并 + last-write-wins"]
        E["stdio auto-restart<br/>HTTP in-place 恢复"]
    end
    subgraph Plugin
        F["Git 仓库 / 本地目录 / Marketplace"]
        G["InstallRegistry (commit hash 版本追踪)"]
        H["allowlist 安全过滤 (企业级)"]
    end
    A --> LOOP["SessionActor 主循环"]
    B --> LOOP
    C --> AB["AgentBuilder<br/>(discover_skills + inject)"]
    D --> ACP_GW["ACP Gateway<br/>x.ai/mcp/server_status"]
    E --> D
    F --> G --> LOOP
    H --> G
    AB --> LOOP
```

---

## 第 11 章 功能特性

**认证体系**：`xai-grok-auth`（auth-provider + retry-middleware 两模块）。支持方式：
- xAI 账号（浏览器 OAuth 流程）；
- API key（直接配置）；
- OIDC（企业身份提供商，`hub_auth.rs`）；
- 外部 auth 提供商（通过 `xai-grok-config` 配置自定义端点）。
`AuthRetryMiddleware`（feature-gated）：token 过期自动刷新，失败后重试——保证长期运行的 Goal Mode 不会因 token 过期中断。

**模型与推理档位**：`xai-grok-config` 配置默认模型（`~/.grok/config.toml`）；AgentDefinition 可覆盖（`model` / `effort` 字段）；`/model` 和 `/effort` 命令运行时切换。不同 agent 可用不同模型，Goal Mode 的规划/验证子 agent 可以指定更高性能的模型。

**三种运行模式**：
- **交互 TUI**：默认，全屏 Ratatui 界面，鼠标支持，Elm 式架构；
- **无头（headless）**：`grok -p "prompt"` 直接执行，标准输出结果，适合 CI/脚本；
- **ACP 模式**：`grok --acp` 暴露 Agent Client Protocol，Zed 等 IDE 通过此协议嵌入 grok。

**JJ（Jujutsu）VCS 支持**（`session/extensions/jj.rs`）：不只支持 Git，也支持 Jujutsu——这是 xAI 内部工程实践的直接体现（xAI 工程团队使用 Jujutsu 作为主要 VCS 工具）。

**遥测**（`session/telemetry.rs`，`extensions/`）：详细记录每次工具调用的延迟、分类器来源、token 消耗、压缩用量等，支持企业级遥测配置和本地关闭。

**PR 集成**（`session/extensions/pr.rs`）：内置拉取请求工作流支持（创建/查看 PR），类似 opencode 的 GitHub Action 集成但更深度集成。

**代码导航**（`session/extensions/code_nav.rs`）：配合 `xai-codebase-graph` 的代码库索引能力，支持定义跳转、引用查找等代码导航操作（LSPTool 的对外接口）。

**Worktree 隔离**（`xai-fast-worktree`，`session/extensions/worktree.rs`）：Goal Mode 可以在独立的 git worktree 里运行，避免目标执行期间的代码变更污染主工作区。`AgentDefinition.isolation` 字段控制是否启用。

**崩溃处理**（`xai-crash-handler`）：捕获 panic，生成结构化崩溃报告，支持上报遥测，保证长期运行的 Goal Mode 在崩溃后有现场信息可供排查。

**公告系统**（`xai-grok-announcements`）：定期从 xAI 服务器拉取新版本通知、政策变更等公告，在 TUI 里展示。

**会话搜索**（`session/storage/search_fts.rs`）：本地全文搜索（FTS），在历史会话里快速检索；`search_remote_sync.rs` 支持同步到远程索引。

```mermaid
flowchart LR
    subgraph 接入
        TUI["交互 TUI<br/>Ratatui 全屏"]
        HL["无头模式<br/>grok -p"]
        ACP["ACP 模式<br/>grok --acp (Zed 等)"]
    end
    subgraph 认证
        OAUTH["xAI OAuth"]
        APIKEY["API Key"]
        OIDC["OIDC 企业 SSO"]
        EXT["自定义端点"]
    end
    subgraph 特色
        GOAL["Goal Mode<br/>规划→执行→验证"]
        JJ["JJ (Jujutsu) VCS"]
        WT["Worktree 隔离"]
        MEDIA["多媒体工具<br/>图片/视频生成编辑"]
        SCHED["定时任务<br/>SchedulerCreateTool"]
    end
    TUI & HL & ACP --> SA["SessionActor"]
    OAUTH & APIKEY & OIDC & EXT --> SA
    SA --> GOAL & JJ & WT & MEDIA & SCHED
```

---

## 第 12 章 总结：设计哲学与取舍

通读源码后，grok-build 给我的感觉是：**一个把"自主执行"和"企业级可靠性"放在同等位置的 Rust 原生 agent**。它的独特想法与亮点：

**① Goal Mode 是 grok 的核心赌注。** 大多数 agent（Claude Code、opencode、Raven……）把自主性交给"模型自己判断何时停止"——只有 grok 建立了一套独立的、显式的自主执行状态机（GoalTracker + GoalPlanner + GoalStrategist + GoalClassifier + GoalStopDetector）。模型不需要自己知道"我是否完成了"——Classifier 来判断。模型容易卡壳——Strategist 来救援（而且有 PlanGuard 保护，救援失败也不会破坏原有计划）。模型提前放弃——StopDetector 的 9 类模式识别来发现。这套机制让 grok 在处理需要数小时、多 token 的长期任务时，比其他 agent 更能自主坚持而不是半途而废或悄悄撒谎说"我完成了"。

**② Rust 单二进制是个工程信仰声明。** 选择 Rust 不只是性能，更是表态："我们认为 agent 应该像系统软件一样可靠。"没有运行时依赖意味着在 CI、嵌入式 Linux、离线企业环境里的安装和运行永远可预期。60+ crates 的模块化说明团队在认真管理依赖边界，而不是把所有东西堆在一个大包里。DotSlash 锁工具链版本，连"构建这个二进制所需的工具"都做到可重现。这是 CodeWhale（也是 Rust）之外唯一用 Rust 构建的主流编程 agent。

**③ bash 权限系统是行业最严谨的之一。** tree-sitter 解析 bash AST（与 opencode 一样），但 grok 的危险模式检测面更广：rg --pre 的预处理命令注入、kubectl 的 kubeconfig 注入、BSD ps 的环境泄露、heredoc 静态不可分析性——这些都有专项检测。8759 行的 `manager.rs` 加上 `auto / YOLO / ask` 三档 + 分类器防护上限（连续 3/总计 20 次 auto-deny 上限），是对"权限系统应该宁可烦人也别出事"这一哲学的极端落实。

**④ ACP 协议是 grok 的"外向性"设计。** 与 opencode 的"服务器即本体"类似，grok 用 ACP 把 agent 能力从终端解放出来——但 ACP 更进一步：它是一个正式的协议规范（有独立 crate `xai-acp-lib`），而不只是 HTTP API。现已集成 Zed 编辑器，意味着 xAI 在认真推动"agent 协作协议标准化"。

**明显的取舍**：

- **不接受外部贡献**：仓库只是 xAI 内部 monorepo 的快照。这换来了极高的内部决策效率，但牺牲了开源社区的参与感。代码质量和架构设计体现了内部专业团队的水准，但你在 GitHub 上提的 PR 没有意义。
- **Goal Mode 的学习曲线**：GoalTracker + GoalPlanner + GoalStrategist + GoalClassifier + GoalStopDetector 五个协作组件，比任何其他 agent 的主循环复杂 3-4 倍。对于简单任务（改一行代码、解释一个函数），这套机制是 overkill，普通 turn 循环效率反而更高。grok 的设计假设是"你会有真正的长期任务需求"——如果你没有，这部分复杂度是白给的。
- **Grok 模型绑定**：虽然 auth 层支持 OIDC 和自定义端点，但工具实现（特别是多媒体工具：ImageGenTool / VideoTool）是为 xAI 模型能力量身打造的。多媒体生成类工具在接入其他模型时能力大幅缩水。
- **无横向对比的 benchmark**：grok 没有对外发布与 Claude Code 或 opencode 的客观性能对比。22k stars 说明市场关注度高，但缺乏独立基准测试让"Goal Mode 到底好多少"这个问题存疑。
- **记忆系统轻量**：相比 Raven 的双轨记忆（EverOS + Curator）、hermes-agent 的 RAG 记忆，grok 的记忆是选配式（默认 session 级，memory_flush 默认关）。这是刻意的克制——"不要为用户自动记住太多"——但也意味着长期个性化需要用户自己通过 skills 和 AGENTS.md 维护。

一句话总结：Claude Code 是"Anthropic 为 Claude 打造的最佳终端代言人"，opencode 是"为所有模型和所有客户端打造的开放 agent 平台"，而 grok 是"xAI 用 Rust 打造的、以 Goal Mode 自主执行为核心差异点的企业级 agent"——它的 Rust 单二进制保证了可靠性基础，Goal Mode 把自主能力推到同类产品的最高点，ACP 协议让它有成为 IDE 标准集成协议的野心。

```mermaid
mindmap
  root((grok-build<br/>设计哲学))
    自主执行
      Goal Mode 多阶段状态机
      GoalPlanner Fail-Closed 规划
      GoalStrategist Fail-Open 恢复
      GoalClassifier 验证完成
      GoalStopDetector 防提前放弃
    系统可靠性
      Rust 单二进制(DotSlash 锁工具链)
      wall_clock_budget 超时防护
      two_pass 压缩减信息损失
      8759行权限系统(最严谨之一)
    企业级扩展
      OIDC / 外部 auth / 公司代理
      Plugin Marketplace(安全 allowlist)
      遥测配置 + 崩溃报告
      MCP 50ms窗口 + 自动重启
    协议开放
      ACP(Agent Client Protocol)
      Zed 编辑器集成
      .claude/agents/ 兼容 Claude Code
      JJ VCS 支持
    明显取舍
      不接受外部贡献(内部快照)
      Goal Mode 对简单任务 overkill
      多媒体工具深绑 xAI 模型
      记忆系统默认轻量(选配 flush)
```

---

*（全文完。文中所有 `crate/模块` 引用均可在 https://github.com/xai-org/grok-build 的 `crates/codegen/` 目录下直接核对；标注"默认关闭"的特性需在 `~/.grok/config.toml` 或 AgentDefinition frontmatter 中显式开启。SOURCE_REV 文件追踪本仓库与 xAI 内部 monorepo 的同步点。）*