Grok Bot 架构总览

2026-08-26 Grok-Bot Architecture

Grok Bot 架构总览

本文是整套解读的入口：先建立全局观，再看细节。读完你应能回答三个问题——系统分几层、每层在哪、代码在哪个目录。

1. 这是什么

Grok Bot 0.18 重构版：对公开发布的 Grok Bot 0.18.0 macOS 应用做的、面向源码的重构。运行时代码是可读 TypeScript（source/），渲染层保留 checksum 固定的 shipped renderer 作为 UI 基线，另加一个最小可审计的 Router 设置补丁。

2. 运行时拓扑（分层）

polished shipped renderer（UI）
   │  preload RPC（source/electron-preload/）
   ▼
Electron main（source/electron-main/）
   │  设置/密钥/认证/插件生命周期、box 连接器、coordinator 所有权、RPC handler
   ▼
node-agent-coordinator（source/node-agent-coordinator/）
   │  transcript 路由、流式 activity、reaction、推理路由、routed MCP bridge
   ▼
host（source/host/）
   │  system prompt 组装、auto-review、沙箱管理、turn 执行
   │  runner/（turn-run-shell / sand-agent-runner / turn-agent-composition）
   ▼
packages/agent（source/packages/agent/）
   │  Agent 核心：turn 循环、工具执行、总结、prompt 渲染
   ├── box-exec-daemon / local-exec-daemon（命令执行守护进程）
   ▼
推理后端（inference）：Cursor / Claude Code / Codex / OpenRouter

自上而下：UI 事件经 preload RPC 进入 Electron 主进程，主进程把「会话/turn 运行」交给 coordinator + host；host 组装 system prompt、做 auto-review、跑 turn；packages/agent 是真正的 agent 循环（模型调用 + 工具执行 + 总结）；命令执行落在两个 daemon 上；最终模型调用路由到所选推理后端。

3. 源码目录地图

目录	职责
`source/electron-main/`	桌面生命周期、设置、认证、box 连接器、coordinator 所有权、RPC handler
`source/electron-preload/`	暴露给 UI 的窄受信桥
`source/node-agent-coordinator/`	transcript 路由、流式 activity、reaction、推理路由、routed MCP bridge
`source/host/`	推理、工具、MCP、设置、turn 执行；`runner/` 是宿主侧运行器与 prompt 组装
`source/packages/agent/`	Agent 核心：turn 循环、工具、总结、prompt 渲染
`source/packages/`（其余）	`chat-inference`（模型调用）、`agent-core`（交互更新）、`mcp-core`、`proto`（protobuf）、`redaction`（隐私）、`prompt-jsx`（prompt 渲染）等
`source/shared/`	共享契约、设置、协议、provider 辅助
`source/box-exec-daemon/`	box 内命令执行守护进程（`Shell`/`Read` 落点）
`source/local-exec-daemon/`	宿主侧本地执行守护进程（`ExternalShell` 等落点）
`frontend/`	可读 React 渲染层重构与设计工作区
`scripts/`	bootstrap、编译、渲染层补丁、打包、签名、验证
`tests/`	发布与路由回归测试

4. 构建模型（精简）

上游 0.18.0 应用是外部的、checksum 固定的构建输入。npm run bootstrap 下载并校验 DMG 与 app.asar，把 dist 解到被忽略的 src/app/dist；npm run package 编译 source/ 运行时、应用渲染层/settings 补丁与 updater guard，再打成新 ASAR，产出 dist/Grok Bot 0.18 Reconstructed.app。详见仓库根 README.md 的 Requirements / Quick start。

5. 关键概念速览

概念	一句话	详见
Turn / Step / Action	一个用户消息驱动一个 turn，可含多个 step（一次模型调用 + 工具执行）	CORE-FLOW
双机器模型	box（自己的沙箱）vs 用户本机（`ExternalShell`/`ExternalRead`）	EXECUTION
两层 prompt	system prompt + UserInfo 首条用户消息	PROMPTS
隐私三元组	`PrivacyMode × DataClassification × PrivacyCapability`	SAFETY
推理路由	同一 agent 可切 Cursor / Claude Code / Codex / OpenRouter	AGENTS

6. 怎么读

建议顺序（详见导读）：

ARCHITECTURE（本篇）→ CORE-FLOW → PROMPTS → CHARACTER → EXECUTION → SAFETY → AGENTS → RUNTIME

各文档结尾都有「相关文档」互链，读完一篇可按兴趣跳转。