Coding Agent on AI博士万戈

Nanobot 源码深度拆解：Python 异步消息总线构建的轻量级 AI Agent 框架

admin@yesmiracle.net (万戈) — Sun, 19 Jul 2026 00:00:00 +0000

这是我的编码 Agent 开源系列第四篇。前三天我分别拆解了 Grok Build（Rust 50+ crate）、Pi Agent（TypeScript 双队列）和 OpenCode（Effect TS 四轴路由）。今天的主角是 Nanobot。

Nanobot 由香港大学数据科学实验室（HKUDS）开发，是一个 Python 3.11+ asyncio 构建的轻量级 AI Agent 框架。它和前三者的最大区别在于：Nanobot 不是编码 Agent，而是通用 Agent 框架。

TL;DR：Nanobot 的 Dream 两阶段记忆合并系统是三者中最完善的记忆方案。它的 MessageBus 架构让 15+ 聊天平台可以即插即用。但 Python 的性能限制让它不适合做代码编辑等延迟敏感的任务。

一、架构全景：MessageBus 异步事件驱动

Nanobot 的核心架构是一句话：一个 async MessageBus 解耦了 Chat Channels 和 Agent Core。

Channels Layer (Telegram, Discord, Slack, Feishu, 微信...)
    ↓ InboundMessage (publish_inbound)
┌──────────────────────────────────────────────────┐
│  MessageBus (asyncio.Queue)                      │
│     ↓ consume_inbound                            │
├──────────────────────────────────────────────────┤
│  AgentLoop (调度层)                               │
│     ↓ AgentRunner (执行层 - LLM + Tool 循环)       │
│     ↓ ToolRegistry (工具执行)                      │
│     ↓ SessionManager (JSONL 持久化)               │
│     ↓ Consolidator (Dream 记忆合并)               │
│     ↑ OutboundMessage (publish_outbound)          │
├──────────────────────────────────────────────────┤
│  MessageBus (outbound)                            │
│     ↓ consume_outbound                           │
└──────────────────────────────────────────────────┘
Channels → send() to platform

看 nanobot/bus/queue.py，只有 44 行：

class MessageBus:
    def __init__(self):
        self.inbound: asyncio.Queue[InboundMessage] = asyncio.Queue()
        self.outbound: asyncio.Queue[OutboundMessage] = asyncio.Queue()

极简主义。没有优先级队列，没有持久化，没有死信队列。

对比其他三个项目的架构模式：

项目	通信模式	通道层	解耦方式
Grok Build	ACP 协议 (Gateway)	5 种部署模式	协议层解耦
OpenCode	Effect HttpApi	TUI + Desktop + Web	Service 层解耦
Pi Agent	EventEmitter	CLI TUI	事件订阅解耦
Nanobot	async Queue	15+ Chat 平台	消息总线解耦

Nanobot 是唯一一个原生支持多聊天平台的。Telegram、Discord、Slack、飞书、微信、企业微信、钉钉、Email、Mattermost、Matrix、WhatsApp、QQ、MoChat、Teams、WebSocket——15+ 平台，全部通过同一个 MessageBus 接入。

二、两阶段 Agent Loop：调度层和执行层分离

这是 Nanobot 最核心的架构设计。Agent 的处理被分成了两个清晰的层次。

2.1 AgentLoop — 调度层

nanobot/agent/loop.py，约 2000 行。

AgentLoop 负责：

消息消费：从 MessageBus 的 inbound 队列消费消息
会话路由：按 session_key 做任务路由，同一 session 串行，跨 session 并发
上下文构建：组装 system prompt、历史记录、memory、skills
状态管理：TurnState 状态机
MCP 连接管理：连接/断开 MCP 服务器
Cron 和自动化任务：协调定时任务和本地触发器

关键设计是会话锁和 pending 队列：

# 每个 session 一个锁
lock = self._session_locks.setdefault(session_key, asyncio.Lock())
# 消息路由到 pending 队列
if effective_key in self._pending_queues:
    self._pending_queues[effective_key].put_nowait(pending_msg)

这实现了 mid-turn injection 模式——用户可以在 Agent 思考过程中发送新消息，它们会被注入到正在运行的 LLM 循环中。

对比 Pi Agent 的 Steering 队列：两者都实现了 mid-turn injection，但实现方式不同。Pi Agent 在 Agent Loop 内部维护 Steering 队列，Nanobot 在外部通过 MessageBus 和 session 锁实现。Pi Agent 的方式更精细（可以区分 Steering 和 Follow-up），Nanobot 的方式更通用（不依赖 Agent Loop 实现）。

2.2 AgentRunner — 执行层

nanobot/agent/runner.py，约 1400 行。

AgentRunner 是一个纯函数式的执行引擎，不知道任何产品层概念（channel、session、用户）。它接收一个 AgentRunSpec 返回 AgentRunResult。

核心循环：

for iteration in range(spec.max_iterations):
    # 1. Context Governance — 修复消息格式、压缩历史
    messages_for_model = self.context_governor.prepare_for_model(...)
    # 2. 调用 LLM
    response = await self._request_model(spec, messages_for_model, hook, context)
    # 3. 执行工具
    for tool_call in response.tool_calls:
        result = await tool_registry.execute(tool_call, context)
    # 4. 检查继续条件

对比 Grok Build 的 MvpAgent：Grok Build 的 Agent 是有状态的（通过 SessionHandle 管理），而 Nanobot 的 AgentRunner 是无状态的——状态全部在 AgentRunSpec 中传递。这使得 AgentRunner 可以被单元测试，不需要 mock 任何全局状态。

三、TurnState 状态机：8 个状态的精细控制

Nanobot 的 TurnState 状态机是代码中最值得学习的模式之一：

RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE

状态	做了什么	失败时
RESTORE	从磁盘加载会话历史	跳过
COMPACT	检查是否需要压缩长历史	跳过
COMMAND	检查是否是 `/` 命令	进入 BUILD
BUILD	构建 LLM 请求	错误返回
RUN	调用 LLM + 执行工具	重试或失败
SAVE	持久化结果	继续
RESPOND	通过 MessageBus 发送回复	继续
DONE	清理和完成	—

对比 Grok Build 的会话 5 状态（Working → IdleResident → Dormant → Completed → DeadFailed）：Grok Build 的状态是会话生命周期，Nanobot 的状态是单个 turn 的执行过程。 两者关注不同层面。

对比 OpenCode 的 Processor 事件驱动：OpenCode 用事件流（LLMEvent → handleEvent），Nanobot 用显式状态机。状态机更容易理解和调试，事件流更灵活。

四、Dream 两阶段记忆合并

Nanobot 的记忆系统是三者中最完善的。nanobot/agent/memory.py（1167 行）实现了 Dream 两阶段记忆合并：

第一阶段：Consolidation

按 token 数量自动触发的 Incremental 合并：

if session_total_tokens > memory_config.consolidate_threshold:
    # 取出最早的消息块
    # 用 LLM 生成摘要
    # 用摘要替换原始消息块
    # 记录 token 节省量

第二阶段：Dream

定时触发的 LLM 驱动的跨会话总结：

# 在后台每隔一段时间：
# 1. 读取所有 session 的 consolidated history
# 2. 用 LLM 生成跨 session 的洞察
# 3. 写入全局 MEMORY.md

为什么这是三者中最完善的？

对比 Grok Build 的 xai-grok-memory crate：Grok Build 的记忆系统是用户手动管理的（memory 工具 + skill 工具），没有自动合并。它靠的是用户主动决定什么时候保存、保存什么。

对比 Pi Agent：Pi Agent 没有长期记忆系统，session 之间的数据不共享。

对比 OpenCode：OpenCode 有 Session Summary 生成（summary.ts），但仅限于单 session 的摘要，没有跨 session 的合并。

Nanobot 的 Dream 是唯一一个「自动的、跨 session 的、LLM 驱动的」记忆系统。 而且它的设计很克制——Consolidation 只做 token 层面的压缩，Dream 才做语义层面的总结，两阶段分开避免 LLM 调用过多。

五、MCP 集成：最复杂的子系统

Nanobot 的 MCP 集成在 nanobot/agent/tools/mcp.py（1435 行），是代码库中最复杂的子系统。

它实现了：

名称 sanitization：Python 方法名不能有 -，MCP 工具名可能有 -，需要做名字映射
Schema 标准化：MCP 的 JSON Schema 格式和 Nanobot 的 ToolSchema 格式不同，需要转换
会话重连：MCP Server 断开后自动重连，带退避策略
多 MCP Server 管理：每个 Server 独立连接池

对比 Grok Build 的 xai-grok-mcp：Grok Build 的 MCP 集成更底层——它直接操作 rmcp crate 的 transport 层，支持 Streamable HTTP 和子进程。Nanobot 的 MCP 是更高层的封装——通过 Python 的 mcp 库连 MCP Server，然后适配到自己的工具系统。

两者的差异是语言生态的体现：Rust 生态没有成熟的 MCP 客户端库，所以 Grok Build 必须自己实现 transport 层；Python 生态有 mcp 客户端库，Nanobot 可以站在上面做封装。

六、工具系统：自动发现 + 参数校验

Nanobot 的工具系统在 nanobot/agent/tools/ 下，每个工具一个文件。

6.1 自动发现

tools/loader.py 通过两种方式自动发现工具：

pkgutil 扫描：扫描 nanobot.agent.tools 包下的所有模块
entry_points 插件：通过 Python 的 entry_points 机制发现第三方工具

6.2 参数校验

tools/schema.py 实现了完整的 JSON Schema 类型系统：

class ToolSchema:
    type: str           # "string" | "integer" | "object" | ...
    description: str    # 工具描述
    properties: dict    # 参数定义
    required: list      # 必填参数

每个工具通过 ToolSchema 定义参数，registry.py 在调用时做 validate_params → cast_params 两阶段验证。

对比 Grok Build 的 ToolDefinition：Grok Build 的 MCP 工具通过 ToolBridge.register_mcp_tools() 注册，MCP 工具和本地工具共享同一个 FinalizedToolset。Nanobot 的 MCP 工具需要单独适配，不能和本地工具统一注册。

七、Provider 抽象层：Fallback 链式封装

Nanobot 的 Provider 系统在 nanobot/providers/ 中，支持 5 种后端：

Anthropic：Claude 系列
OpenAI Compat：兼容 OpenAI API 的模型
OpenAI Responses：OpenAI 的 Responses API
Azure OpenAI：Azure 部署
Bedrock：AWS Bedrock
GitHub Copilot：Copilot 代理

核心设计是 FallbackProvider：

class FallbackProvider:
    def __init__(self, providers: list[Provider]):
        self.providers = providers

    async def complete(self, messages):
        for provider in self.providers:
            try:
                return await provider.complete(messages)
            except Exception:
                continue
        raise AllProvidersFailed()

对比 Pi Agent 的 30+ Provider：Pi Agent 的 Provider 覆盖更广，但都是单 Provider 直连。Nanobot 的 Provider 数量少，但支持 Fallback 链式切换。这是两种不同的哲学：广度 vs 韧性。

八、和三个编码 Agent 的横向对比

维度	Grok Build	OpenCode	Pi Agent	Nanobot
语言	Rust	TypeScript/Effect	TypeScript	Python
定位	编码 Agent	编码 Agent	编码 Agent	通用 Agent 框架
源文件	2804	2499	859	500+
沟通平台	CLI 5 模式	TUI + Desktop	CLI TUI	15+ Chat 平台
会话存储	ACP 5 状态	Durable SQLite	JSONL 树形	JSONL 文件
记忆系统	手动管理	Session Summary	无	Dream 自动合并
MCP	✅ 完整传输层	✅ 插件化	❌	✅ 适配层
子 Agent	进程内 1 层	插件	RPC 进程	消息总线
工具数	60+	较多	中等	20+
验证系统	Skeptic + Goal	❌	❌	❌
权限系统	✅ 完整	✅ Ruleset	❌ 容器化	❌

写在最后

Nanobot 作为一个 Python Agent 框架，它的定位和前三者完全不同。它不是编码 Agent，而是通用 Agent 运行时。它的 15+ 聊天平台集成、Dream 两阶段记忆合并、TurnState 状态机，都是为「长时间、多平台、多会话」的通用 Agent 场景设计的。

如果你需要的是一个可以接入 Telegram、飞书、微信，能跑自动任务，有记忆系统的 Agent 框架，Nanobot 是这四个项目中唯一的选择。

但如果你需要的是高效的代码编辑能力，Python 的异步性能瓶颈和 GIL 会让它力不从心。这时候 Rust 的 Grok Build 或 TypeScript 的 OpenCode/Pi Agent 更适合。

OpenCode 源码深度拆解：Effect TS 代数效应系统构建的智能编码 Agent

admin@yesmiracle.net (万戈) — Sun, 19 Jul 2026 00:00:00 +0000

在读完 Grok Build 的 Rust 巨构和 Pi Agent 的 Steering 双队列之后，今天来看第三个编码 Agent——OpenCode。

OpenCode 由 SST/Anomaly 团队开发，是一个 TypeScript monorepo，2499 个 TS 源文件，20+ 个独立包。它的技术栈选择非常激进：Effect TS 不是「用了一下」，而是深嵌在每一层代码的核心。

TL;DR：OpenCode 的「四轴 LLM 路由」和「Schema First 协议层」设计，是三者中最工程化的。如果你追求代码的可测试性和架构的可维护性，OpenCode 的代码最值得读。

一、Monorepo 全景

packages/
├── opencode/    # 主 CLI Agent —— 双 Agent 系统 (build + plan)
├── core/        # 核心运行时 —— Session, Tool, Config, Permission
├── protocol/    # HTTP API 协议层 —— Effect HttpApi
├── server/      # 服务器实现
├── tui/         # 终端 UI
├── schema/      # 浏览器安全的序列化合约
├── plugin/      # 插件系统（V2 Effect 版 + V1 Promise 版）
├── llm/         # LLM 集成 —— 四轴路由体系
├── console/     # 桌面应用
└── web/         # Web 前端

对比前两篇的架构规模：

项目	源文件数	语言	包数	核心设计哲学
Grok Build	2804 .rs	Rust	50+ crate	编译期类型安全 + Actor 模型
OpenCode	2499 .ts	TypeScript	20+ 包	Effect TS 代数效应 + Schema First
Pi Agent	859 .ts	TypeScript	5 包	事件驱动 + 分层抽象

二、Effect TS：不是「用了」，是「深嵌」

OpenCode 对 Effect TS 的使用深度，是我见过的 TypeScript 项目中最彻底的。

2.1 Context.Service 依赖注入

每一层都通过 Context.Tag 声明服务接口：

// packages/opencode/src/session/llm.ts
class LLM extends Context.Tag("session/LLM")<
    LLM,
    { stream: (input: StreamInput) => Effect<StreamResult> }
>() {}

2.2 Effect.gen 代数效应

核心逻辑用 Effect.gen 编写，而不是 async/await：

const program = Effect.gen(function* () {
    const llm = yield* LLM;
    const session = yield* Session;
    const result = yield* llm.stream(input);
    return yield* session.save(result);
});

2.3 Schema 优先验证

packages/schema/ 定义了所有数据结构的 Schema，运行时验证 + 编译时类型推导：

export const AgentInfo = Schema.Struct({
    name: Schema.String,
    mode: Schema.Literals(["subagent", "primary", "all"]),
    permission: PermissionV1.Ruleset,
});

2.4 为什么这很重要？

对比 Grok Build 的 Rust 方案：Rust 的类型系统在编译期保证正确性，Effect TS 的 Schema 在运行时保证正确性。两者达到的最终效果类似——数据结构不会在管道中变形——但路径完全不同。

三、四轴 LLM 路由体系

这是 OpenCode 最独特的架构设计。packages/llm/ 将 LLM 调用拆成四个正交维度：

Protocol  → 协议层（OpenAI Chat、Anthropic Messages、Google Gemini...）
Endpoint → 端点层（api.openai.com、api.anthropic.com、自定义代理...）
Auth     → 认证层（API Key、OAuth、Bearer Token...）
Framing  → 框架层（AI SDK、原生 HTTP、流式/非流式...）

3.1 Protocol 复用

多个 Provider 共享同一个 Protocol 实现：

// 同一个 OpenAIChat.protocol 被多个 provider 复用
const deepseek = OpenAIChat.protocol({ baseURL: "https://api.deepseek.com" });
const together = OpenAIChat.protocol({ baseURL: "https://api.together.xyz" });
const fireworks = OpenAIChat.protocol({ baseURL: "https://api.fireworks.ai" });
const openai = OpenAIChat.protocol({ baseURL: "https://api.openai.com/v1" });

对比 Pi Agent 的 30+ Provider：Pi 为每个 provider 写一个适配文件，而 OpenCode 只需要写一个 OpenAIChat.protocol，然后通过配置不同的 baseURL 复用。这是架构抽象层次的差异。

3.2 RequestExecutor 重试逻辑

在 packages/llm/src/ 中，RequestExecutor 封装了完整的重试策略：

指数退避 + 抖动
按错误类型分类（4xx 不重试，5xx 重试，429 限速重试）
请求超时控制
流式响应中断恢复

对比 Grok Build 的 xai-grok-sampler：Grok Build 的 samper 有三层架构（SamplingClient → stream → SamplerHandle），重试逻辑在 retry.rs 中，支持 doom_loop 检测。OpenCode 的 RequestExecutor 功能类似但更轻量。

四、双 Agent 架构：build vs plan

OpenCode 内置了两个 Agent，定义在 packages/opencode/src/agent/agent.ts 中：

const AgentInfo = Schema.Struct({
    name: Schema.String,
    description: Schema.optional(Schema.String),
    mode: Schema.Literals(["subagent", "primary", "all"]),
    permission: PermissionV1.Ruleset,  // 权限系统
});

Agent	模式	权限	用途
build	primary	完整文件读写	开发工作
plan	primary	只读	代码分析、探索

两者通过 Tab 键在 TUI 中切换。核心差异只是 permission 级别不同——同一个 Agent Loop，不同的权限配置。

对比 Grok Build：Grok Build 的 AgentDefinition 系统更复杂，除了 permission 还支持 prompt_mode、completion_requirement、toolset 等配置，通过 AgentBuilder 构建。

对比 Pi Agent：Pi 没有内置的多 Agent 概念，但通过扩展系统可以实现。

五、Session 架构：V2 的持久化改革

OpenCode 的 Session 系统在 packages/opencode/src/session/ 下，约 24 个文件。V2 版本引入了 Durable Prompt Admission 模式：

SessionV2.prompt(input)
  ├── durable admission: 将 prompt 持久化到 SQLite
  ├── schedule wake: 通知 SessionRunner 有新工作
  └── return sessionID

关键设计：prompt 在发送给 LLM 之前先持久化。即使进程崩溃，prompt 不会丢失。

5.1 Session 处理循环（Processor）

processor.ts 是实现 Agent 循环的核心——一个事件驱动的状态机：

create(input) → LLM.Service.stream(input) → handleEvent(event)
  ├── reasoning-start → 管理推理过程
  ├── tool-call-start → 执行工具调用
  ├── tool-result → 处理工具结果
  ├── text-delta → 文本增量更新
  └── error → 错误处理

5.2 双运行时策略

OpenCode 同时支持两种 LLM 运行时：

AI SDK 路径（默认）：通过 Vercel AI SDK 调用
Native LLM 路径（新）：通过 native-runtime.ts 直接调用

双运行时通过 session/llm.ts 中的 LLM.Service 统一管理，根据配置自动选择。这种渐进式迁移策略——先通过成熟 SDK 上线，再逐步替换为原生实现——是工程化团队的典型做法。

六、插件系统：V1 + V2 双轨制

OpenCode 的插件系统在 packages/plugin/ 中，同时维护两套 API：

版本	架构	使用场景
V1 (Promise)	简单的 `() => Promise<void>`	快速原型、简单插件
V2 (Effect)	Effect 的 Context/Layer/Scope	复杂插件、生产环境

V2 插件支持 20+ 生命周期钩子：

onSessionStart / onSessionEnd
onToolCall / onToolResult
onPromptBuild / onPromptComplete
onError / onConfigLoad

对比 Pi Agent 的扩展系统：Pi 的扩展机制更丰富（注册工具、命令、UI 组件），但 OpenCode 的插件系统在类型安全上更好——Effect 的 Context 保证了插件依赖在编译期可验证。

七、和 Grok Build 的深层对比

7.1 哲学差异

维度	Grok Build (Rust)	OpenCode (Effect TS)
正确性保证	编译期类型系统	运行时 Schema 验证
并发模型	Tokio Actor + mpsc	Effect Fiber + Scope
错误处理	Result + thiserror	Effect.Either + Cause
依赖注入	手动 Resource 注入	Context.Service 自动
协议层	ACP (Gateway + Session)	Effect HttpApi

7.2 工具系统

Grok Build 的 ToolBridge + FinalizedToolset 通过类型安全的 Resource 注入管理工具依赖。OpenCode 的工具注册通过 Tool.Registry 的 Effect Service 实现。两者都在做同一件事——让工具不依赖全局状态——但 Grok Build 的 Rust 版本在编译期保证，而 OpenCode 在运行时保证。

7.3 MCP 集成

Grok Build 有完整的 xai-grok-mcp crate，支持 Streamable HTTP 和子进程两种传输，OAuth 认证，Managed MCP 自动刷新。OpenCode 的 MCP 支持在 packages/plugin/src/v2/ 中，通过插件系统实现。

八、三篇编码 Agent 的横向对比

维度	Grok Build	OpenCode	Pi Agent
语言	Rust	TypeScript/Effect	TypeScript
包数	50+ crate	20+ 包	5 包
文件数	2804	2499	859
会话模式	5 状态 + ACP 协议	Durable SQLite	JSONL 树形 + 分支
工具系统	ToolBridge 资源注入	Effect Service 注册	定义优先双层注册
Provider	少（委托 xAI）	四轴路由	30+ Provider
验证系统	✅ Skeptic + Goal	❌	❌
权限系统	✅ 完整	✅ Ruleset	❌ 容器化
子 Agent	进程内 1 层	❌ 未知	RPC 进程级
协议	ACP	Effect HttpApi	❌ CLI 原生
MCP	✅ 完整	✅ 插件化	❌

写在最后

OpenCode 的代码质量是三者中最高的。Effect TS 的选择让它的架构非常干净——每一层都有明确的边界，每个依赖都有显式的声明。

但代价也很明显：学习曲线陡峭。如果你不熟悉 Effect TS，读 OpenCode 的代码会非常吃力。而 Grok Build 的 Rust 代码虽然复杂，但 Rust 类型系统的表现力让代码「自文档化」程度更高。

如果你对 Effect TS 的代数效应系统在工程中的落地感兴趣，OpenCode 是最值得读的参考实现。它的「四轴 LLM 路由」和「Schema First 协议层」设计，是面向未来的 Agent 架构方向。

相关阅读：

GitHub: https://github.com/sst/opencode

Pi Agent 深度拆解：TypeScript 多包架构下的 Steering + Follow-up 双队列设计

admin@yesmiracle.net (万戈) — Sun, 19 Jul 2026 00:00:00 +0000

如果你一直在关注我前两天的博客——Grok Build 的 Rust 巨构和 OpenCode 的 Effect TS 体系——今天的主角是 Pi Agent（@earendil-works/pi）。

Pi 是一个 TypeScript 多包单体仓库项目，由 5 个核心包组成，共计 859 个 TypeScript 源文件。它的定位和 OpenCode 类似（都是 TypeScript 编码 Agent），但在架构设计上走了完全不同的路。

TL;DR：Pi 在「用户交互能力」上远超同类。它的 Steering + Follow-up 双队列设计，是 Grok Build 和 OpenCode 都没有的工程创新。

一、五层包的依赖关系

Pi 的包结构比 OpenCode 的 20+ 包更精简，但每层的抽象更严格：

@earendil-works/pi-orchestrator → RPC 子代理编排
    ↑
@earendil-works/pi-coding-agent → 编码 Agent CLI
    ↑
@earendil-works/pi-agent-core → 无状态 Agent Loop 引擎
    ↑
@earendil-works/pi-ai → 30+ LLM Provider 统一接口
    ↑
@earendil-works/pi-tui → 终端 UI 库

对比一下前两篇的架构：

项目	包数量	语言	Agent 数量	会话存储
Grok Build	50+ crate	Rust	1 (MvpAgent)	ACP 协议 + 磁盘序列化
OpenCode	20+ 包	TypeScript/Effect	2 (build/plan)	Drizzle SQLite
Pi Agent	5 个包	TypeScript	N/A (用户配置)	JSONL 树形文件

Pi 的包最少，但它的 Agent Loop 设计 反而是三者中最复杂的。

二、Agent Loop：Steering vs Follow-up 双队列

这是 Pi 最值得关注的架构创新。读 packages/agent/src/agent-loop.ts，它的核心循环是一个双层结构：

// 外层循环：处理 follow-up 消息
while (true) {
    let hasMoreToolCalls = true;

    // 内层循环：处理工具调用和 steering
    while (hasMoreToolCalls || pendingMessages.length > 0) {
        // step 1: 处理 pending steering 消息
        // step 2: 调用 LLM
        // step 3: 执行工具（并行或串行）
        // step 4: shouldStopAfterTurn 检查
        // step 5: 获取新的 steering
    }

    // 检查 follow-up 队列
    // 若有 → 继续外层循环
    // 若无 → break
}

Steering 和 Follow-up 有什么区别？

Steering：在当前 turn 内注入的消息。用户可以在 Agent 思考时发一条"等一下，换个思路"，它被排到 pending 队列，在当前 LLM 调用结束后立即处理。这是「打断并纠正」机制。
Follow-up：在当前 turn 结束后注入的消息。Agent 即将停止时，如果外部有新的请求（比如子 Agent 返回结果），它被注入到下一轮。这是「追加任务」机制。

对比 Grok Build：Grok Build 没有 Steering 机制。用户一旦提交 prompt，Agent 会一直跑到工具调用结束或达到最大迭代次数。用户在中途发送的消息会被排到新 turn 中，而不是注入到当前 turn。

这种差异的本质原因是：Architecture influences interaction design.

Grok Build 用 ACP 协议 + 网关模式：用户通过 session/prompt 提交请求，Agent 执行完毕后通过 PromptResponse 返回。协议层面就是「一问一答」。
Pi Agent 在进程内运行：Agent Loop 和 Steering 队列在同一个进程空间，天然支持 mid-turn injection。

三、30+ LLM Provider 的抽象层

Pi 的 @earendil-works/pi-ai（packages/ai/src/）拥有我在开源编码 Agent 中见过的最完整的 Provider 抽象层。

在 types.ts 中定义了核心类型：

interface Model {
    id: string;
    provider: string;
    description?: string;
    // 认证方式
    authType?: "api-key" | "oauth" | "cert" | "none";
    // 是否支持流式、工具调用、并行工具等
    capabilities?: ModelCapabilities;
}

注册机制在 providers/all.ts 中，每个 Provider 一个文件：

providers/
├── anthropic.ts       # Claude 系列
├── openai-codex.ts    # Codex 系列
├── openai.ts          # OpenAI 系列
├── deepseek.ts        # DeepSeek
├── google-vertex.ts   # Google Vertex AI
├── fireworks.ts       # Fireworks
├── openrouter.ts      # OpenRouter
├── cerebras.ts        # Cerebras
├── mistral.models.ts  # Mistral
├── minimax.ts         # MiniMax
├── moonshotai-cn.models.ts  # 月之暗面
└── ... (30+ providers)

对比 Grok Build：Grok Build 的 Provider 层在 xai-grok-sampler crate 中，核心是 Retry + Backoff + AuthScheme 三层。它不需要 30+ Provider 是因为 Grok Build 通过 ACP 协议的 backend_search 机制复用 xAI 服务器端的 model catalog。

对比 OpenCode：OpenCode 的四轴 LLM 路由体系（Protocol/Endpoint/Auth/Framing）比 Pi 更抽象，但 Pi 在 Provider 覆盖面上更广——尤其是对中文厂商的支持（MiniMax、月之暗面、小米、零一万物等），这是 Pi 的一个明显差异化。

四、工具系统：定义优先 + 双层注册

Pi 的工具系统在 packages/agent/src/types.ts 中定义了核心类型体系：

ToolDefinition → AgentTool → Agent
     ↓              ↓
  schema (JSON)   runtime implementation

ToolDefinition：工具的定义（名称、描述、参数 Schema），由 LLM 调用方消费。 AgentTool：工具的实现（validate → execute），由 Agent 执行方消费。

两层注册流程：

1. 注册 ToolDefinition（定义）→ 注册到 Agent
2. 注册 AgentTool（实现）→ 注册到 Agent
3. Agent Loop 中：LLM 选择工具 → Agent 匹配 ToolDefinition → Agent 调用对应的 AgentTool

Pi 支持两种工具执行模式：

串行执行：一个工具调用返回后再下一个
并行执行：多个工具调用同时执行（在 LLM 支持并行工具调用的情况下）

对比 Grok Build：Grok Build 的工具系统使用 ToolBridge + FinalizedToolset，通过 xai-tool-runtime crate 实现 类型安全的 Resource 注入。每个工具声明它需要的资源（Terminal、Cwd、SessionEnv 等），由系统注入。Pi 没有这一层——工具直接通过 input 参数获取依赖。

五、会话管理：JSONL 树形文件

Pi 的会话存储在 packages/coding-agent/src/agent-session.ts（3283 行！）中。它的存储格式是 JSONL 树形文件：

~/.pi/sessions/
├── {session_id}/
│   ├── config.json           # 会话配置
│   ├── turns.jsonl           # 核心数据：每个 turn 一行 JSON
│   └── branches/
│       └── {branch_id}/
│           ├── config.json
│           └── turns.jsonl

树形分支：Pi 支持从历史中的任何 turn 创建分支，这个分支可以独立发展。这是一个被严重低估的功能——在复杂的调试场景中，你想回到 10 分钟前的某个决策点重新探索，而不丢失那之后的分析结果。

对比 Grok Build：Grok Build 的会话通过 ACP 协议管理，5 个生命周期状态（Working → IdleResident → Dormant → Completed → DeadFailed），不支持分支。

对比 OpenCode：OpenCode 用 Drizzle SQLite 做持久化，支持 V2 Session 的 durable prompt admission——先持久化再执行。也不支持分支。

JSONL 树形 + 分支回滚，Pi 在会话管理的灵活度上独树一帜。

六、子代理：RPC 进程级编排

Pi 的子代理通过 packages/orchestrator/ 实现，和其他编码 Agent 最大的不同在于：它启动的是独立的 Pi 进程，通过 RPC 协议通信。

主 Pi 进程 → 启动子 Pi 进程（独立 Node/Bun 进程）
  │  RPC 协议（JSON-RPC over stdio/Unix socket）
  ▼
子 Pi 进程 → 拥有自己的 Agent Loop、工具、会话

这种方式和 Grok Build 的 SubagentCoordinator（进程内 spawn_local）完全不同：

Pi 的 RPC 模式更安全但更重。Grok Build 的进程内模式更高效但隔离性差——这和两者语言的选择一脉相承：Rust 的类型系统让进程内并发安全得多，而 TypeScript 需要用进程隔离来弥补。

七、扩展系统 vs 插件系统

Pi 的扩展系统比 Grok Build 和 OpenCode 的插件系统更轻量，但覆盖了完整的 Agent 生命周期事件。

在 packages/coding-agent/src/extensions/types.ts（1682 行）定义了所有扩展点：

onBeforeTurn / onAfterTurn：Turn 前后钩子
onToolCall / onToolResult：工具调用钩子
onUserMessage / onAssistantMessage：消息钩子
onConfigLoad / onConfigSave：配置钩子
onSessionCreate / onSessionDestroy：会话生命周期钩子

扩展可以：

注册新工具（通过 extensions.registerTool()）
注册新命令（如 /help、/search）
修改系统提示词
拦截和修改 LLM 响应
添加自定义 UI 组件（TUI 模式下）

对比 Grok Build：Grok Build 的 Hooks 系统在 xai-grok-agent 中，支持 before_turn 和 after_turn，通过 TurnHook trait 实现。Pi 的扩展系统更丰富，而 Grok Build 的 Hooks 更专注于安全和合规。

八、安全问题：没有内置权限系统

Pi 的 README 明确说明：

Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access.

它给出的替代方案是外部容器化：

Gondolin 扩展：在 Linux micro-VM 中运行工具
Plain Docker：整个 Pi 进程跑在 Docker 容器中
OpenShell：基于策略的沙箱

对比 Grok Build：Grok Build 有完整的 xai-grok-workspace 权限系统 + xai-grok-sandbox 沙箱 + permission::manager（6295 行的大模块）。它是三者中唯一有原生权限模型的。

对比 OpenCode：OpenCode 的 PermissionV1.Ruleset 在 Agent 定义中指定，支持细粒度的 allow/deny。

Pi 在安全性上最弱，但这也反映了它的目标用户群不同——Pi 更面向「个人开发者个人使用」，而 Grok Build 设计之初就考虑了企业级安全。

九、和 Grok Build 的深层对比

从代码层面，两者在四个关键维度上有本质差异：

9.1 并发模型

Grok Build：Tokio Actor 模型 + LocalSet，!Send 类型安全
Pi Agent：EventEmitter + async/await，无共享状态

9.2 工具系统

Grok Build：ToolBridge + FinalizedToolset，类型安全的 Resource 注入，支持 MCP 工具和本地工具统一注册
Pi Agent：ToolDefinition + AgentTool 双层注册，定义优先，不支持 MCP

9.3 协议

Grok Build：ACP 协议，支持 5 种部署模式（TUI/Headless/Stdio/Server/Leader）
Pi Agent：纯 CLI 工具，无标准化协议层

9.4 验证系统

Grok Build：Skeptic 验证 + Goal 系统 + Doom Loop 检测（最完善）
Pi Agent：无验证系统

写在最后

Pi Agent 是一个定位清晰的个人开发工具。它在架构设计上有两个真正的创新：

Steering + Follow-up 双队列：让用户可以在 Agent 思考过程中介入，这是其他编码 Agent 没有做到的。
JSONL 树形会话存储 + 分支：为探索式编程提供了天然的「反悔」机制。

但它也有明显的短板：没有权限模型、没有标准化协议、没有验证系统。如果你把它和 Grok Build 对比，它们解决的问题不同——Grok Build 是「企业级 AI 编码基础设施」，Pi 是「个人开发者的编码助手」。

如果你想深入了解，Pi 的 @earendil-works/pi-ai Provider 抽象层是三者中最值得学习的——30+ Provider 的统一接口设计，对于任何需要支持多模型的项目都有参考价值。

xAI 开源了 Grok Build！万字拆解 40 万行 Rust 构建的 AI Coding Agent 内部架构

admin@yesmiracle.net (万戈) — Sun, 19 Jul 2026 00:00:00 +0000

如果你是 AI 编程工具的深度用户，可能已经用过 Cursor、Claude Code、Codex 或者 Hermes Agent。但 2026 年 7 月 19 日，xAI 在 GitHub 上开源了 Grok Build——一个你可能不知道名字、但架构深度令人叹为观止的终端 AI Coding Agent。

这不是一个简单的"AI 调 API 封装"。我花了整整一天通读源码，只能说：这可能是目前开源社区能见到的最完整的 AI Agent 工程实现。

本文从源码出发，分 10 个维度拆解 Grok Build 的架构设计。

一、项目概览：40 万行 Rust，50+ 个 Crate 的模块化巨构

Grok Build 的代码量惊人——2804 个文件，约 132 万行代码（含第三方依赖），核心 Rust 源码约 60 万行。它被组织为 50+ 个独立的 Cargo crate，每个 crate 有清晰的职责边界。

从仓库布局看，xAI 将其抽象为 6 个层次：

xai-grok-pager-bin          → 二进制入口
xai-grok-pager / render     → TUI 界面层
xai-grok-shell              → Agent 运行时 + 会话管理
xai-grok-agent              → Agent 定义 + 系统提示词组装
xai-grok-tools              → 工具实现层（60+ 工具）
xai-grok-workspace          → 工作区（文件系统 + VCS + 权限）
xai-grok-sampler            → LLM 采样层（HTTP 流式 + 重试）
xai-acp-lib                 → ACP 协议通信层

这种分层设计使得 Grok Build 可以运行在 5 种模式下：

TUI 模式：全屏终端界面，交互式编程
Headless 模式：通过 Relay WebSocket 连接，无界面运行
Stdio 模式：JSON-RPC over stdin/stdout，适合 CI/CD
Server 模式：WebSocket 服务器，供外部客户端连接
Leader 模式：IPC 服务器，协调多个 follower 客户端

而这种多模式能力，正是其底层架构设计成功的证明。

二、ACP 协议：让 Agent 和客户端解耦的「七层协议」

Grok Build 最核心的设计决策是拥抱 ACP（Agent Client Protocol）。这不是 xAI 自创的协议——它来自 agent-client-protocol 这个开源 Rust crate（v0.10.4），是一个通用的 Agent ↔ 客户端通信规范。

ACP 定义了完整的请求-响应模型：

客户端                          Agent
  │                              │
  │── initialize ──────────────→│  (握手，交换能力)
  │←── InitializeResponse ──────│
  │                              │
  │── session/new ─────────────→│  (创建新会话)
  │←── SessionCreated ──────────│
  │                              │
  │── prompt ──────────────────→│  (发送提示词)
  │←── PromptResponse ──────────│
  │←── x.ai/tool/use ──────────│  (服务器调用工具)
  │── x.ai/tool/result ───────→│  (客户端返回结果)
  │                              │
  │── session/close ───────────→│  (关闭会话)

xai-acp-lib crate 封装了 ACP 的低层通信细节，提供了基于 mpsc channel 的 Gateway 模式：

AcpGatewaySender / AcpGatewayReceiver：双向消息通道
支持 AgentMessage 和 ClientMessage 两种消息类型
通过 serde_json::Value 的 _meta 字段支持扩展协议

这意味着，任何实现了 ACP 的客户端都可以连接 Grok Build——不仅是 xAI 自家的 TUI，还包括 VS Code 扩展、Web UI、CI 脚本等。

三、Agent 运行时：从 MvpAgent 到子 Agent 协调器

Grok Build 的 Agent 运行时位于 xai-grok-shell crate，核心是 MvpAgent 结构体。它实现了 ACP 的 acp::Agent trait，是真正的"大脑"。

3.1 MvpAgent 的职责

MvpAgent 是一个巨大的结构体，管理着：

会话注册表：所有活跃会话的 SessionHandle
认证管理器：OAuth、API Key 等多种认证方式
模型管理器：模型目录、模型切换
子 Agent 协调器：子任务管理
网关：与 leader/relay 的通信通道
工作区操作：文件系统、VCS、权限

3.2 会话生命周期

Grok Build 的会话有 5 个状态：

Working → 正在执行一个 turn（有 LLM 请求在跑）
IdleResident → Actor 存活，但无正在执行的 turn
Dormant → 序列化在磁盘上，但未加载
Completed → 已结束，可恢复
DeadFailed → Actor 崩溃（无害，可恢复）

这种设计让 Grok Build 可以同时管理数十个会话，并按需加载/卸载，避免内存爆炸。

3.3 子 Agent 系统

Grok Build 支持通过 task 工具创建子 Agent。子 Agent 的深度限制为 1 层（子 Agent 不能再创建子 Agent），但每个父会话可以同时运行多个子 Agent。

子 Agent 的协调通过 SubagentCoordinator 完成，支持：

Spawn：创建新子 Agent
Query：查询子 Agent 状态（支持阻塞等待）
Cancel：取消子 Agent
ListActive：列出活跃子 Agent
Completions：获取已完成子 Agent 结果

四、工具系统：60+ 工具的分层架构

Grok Build 的工具系统是最值得深入研究的部分。它位于 xai-grok-tools crate，包含 60+ 个工具实现，分为两层架构。

4.1 旧架构 vs 新架构

代码中同时存在两种工具 trait：

旧 Tool trait：早期的工具接口
新 NewTool trait：基于 xai-tool-runtime 的新架构

新架构的核心是 ToolBridge，它封装了 FinalizedToolset，提供：

pub struct ToolBridge {
    registry: Arc<FinalizedToolset>,
    terminal: Option<Arc<dyn TerminalBackend>>,
}

4.2 工具注册与资源注入

工具通过 ToolRegistryBuilder 注册，每个工具声明它需要的资源（Resource）：

Terminal：终端后端
Cwd：工作目录
ToolCallId：工具调用 ID
SessionFolder：输出文件路径前缀
SessionEnv：环境变量
NotificationHandle：通知通道

这种依赖注入模式让工具可以自由组合，且每个工具不需要关心全局状态。

4.3 核心工具一览

Grok Build 的工具集覆盖了 Coding Agent 所需的全部能力：

工具	功能	来源
`BashTool`	执行 shell 命令（支持前台/后台）	自研
`ReadFileTool`	读取文件	自研
`SearchReplaceTool`	搜索替换编辑	自研
`GrepTool`	代码搜索	自研
`ListDirTool`	列出目录	自研
`WebFetchTool`	获取网页内容	自研
`WebSearchTool`	网页搜索	自研
`TaskTool`	创建子 Agent	自研
`TodoWriteTool`	任务清单管理	自研
`UpdateGoalTool`	目标完成声明	自研

此外，还有来自 Codex（OpenAI）和 OpenCode（SST）的移植工具，以及完整的 MCP 工具集成。

五、终端系统：Actor 模式 + 智能超时管理

终端（Terminal）是 Coding Agent 最重要的工具。Grok Build 的终端实现是一个教科书级别的 Actor 模式实例。

5.1 Actor 架构

LocalTerminalBackend 是一个轻量级 handle，所有实际工作通过 mpsc channel 发送给 LocalTerminalActor 处理：

LocalTerminalBackend (Handle)
  │ 发送 TerminalCommand
  ▼
LocalTerminalActor (Actor)
  ├── Run (前台运行)
  ├── RunBackground (后台运行)
  ├── GetTask (查询任务)
  ├── Kill (终止任务)
  ├── KillForegroundCommands (终止前台命令)
  ├── BackgroundForeground (前台→后台迁移)
  └── WaitForCompletion (等待完成)

5.2 智能的超时策略

Grok Build 的终端超时策略非常 smart：

前台命令：默认 120s 超时，但可通过 max_timeout_secs 配置扩展到 10 小时
后台任务：最长 10 小时（BACKGROUND_MAX_RUNTIME）
自动后台迁移：前台命令运行超过 15s 后自动转为后台——模型不阻塞，用户可以继续交互
输出文件上限：5 GiB 后自动终止，防止 yes 等命令撑爆磁盘
SIGTERM → SIGKILL：1 秒宽限期

5.3 搜索工具 Shadow

Grok Build 还悄悄做了一个很聪明的事：它把 find 替换为 bfs，把 grep 替换为 ugrep，通过 SearchShadowConfig 控制。这样在底层就用更快的工具替代标准命令，对模型完全透明。

六、Sampler 层：三层架构的 LLM 请求处理

xai-grok-sampler crate 是 LLM 请求的 HTTP 流式+重试层，被设计为可独立复用的组件。

6.1 三层 API

Layer 1: SamplingClient  → 返回原始 chunk 流
Layer 2: stream          → 将原始流转换为 SamplingEvent
Layer 3: SamplerHandle   → 管理并发请求、重试、取消

6.2 重试策略

支持多种 API 后端（Chat Completions、Responses API、Messages API）
智能错误分类：classify_error() 区分速率限制、认证错误、服务器错误
指数退避 + 抖动（jitter）
重试次数可通过 max_retries 配置

6.3 Doom Loop 检测

Grok Build 有一个专门的 doom_loop 模块，检测 LLM 是否陷入无限循环（如持续调用工具但从不完成）。当检测到死循环时，自动取消当前 turn 并报告原因。

七、目标系统：阴谋论者式的验证机制

Grok Build 的 Goal 系统可能是最令人印象深刻的特性。它不是一个简单的"声明完成"——而是一个对抗性 skeptic 验证系统。

7.1 工作流程

模型: update_goal(completed: true)
  │
  ▼
Goal Tracker 创建验证任务
  │
  ▼
Goal Classifier 启动 N 个 skeptic 子 Agent
  ├── Skeptic 1: 检查代码，找漏洞
  ├── Skeptic 2: 检查代码，找漏洞
  └── Skeptic 3: 检查代码，找漏洞
  │
  ▼
Majority Refute 投票
  ├── ≥ 2 个 skeptic 说"没完成" → 拒绝，生成 gap 摘要
  └── ≥ 2 个 skeptic 说"完成了" → 接受，标记完成

7.2 关键参数

默认 3 个 skeptic（可配置 1-5 个）
最大验证次数：10 次（可配置）
每次验证的 diff 上限：256 KB
skeptic 使用独立的子 Agent，不污染父会话的上下文

这种设计确保了一个 bug 不会被模型自己"蒙混过关"。当一个 skeptic 指出"代码没处理边界情况"，模型必须真正修复代码才能再次声明完成。

八、MCP 与插件系统：生态扩展能力

8.1 MCP 集成

xai-grok-mcp crate 负责 MCP 集成，支持：

Streamable HTTP Transport：基于 rmcp 2.1 的 HTTP 流式传输
OAuth 支持：浏览器 OAuth 流程 + 进程间去重
凭证管理：$GROK_HOME/mcp_credentials.json
Managed MCP：自动刷新 MCP 服务器配置

8.2 插件系统

xai-grok-agent 的插件系统支持：

插件发现：从本地目录、Git 仓库、市场发现插件
Git 安装：从 GitHub 仓库直接安装
信任管理：插件信任级别配置
Hooks 适配器：支持 before_turn 和 after_turn 钩子

8.3 Hooks 系统

Grok Build 的 hooks 系统支持在 turn 的前后插入自定义逻辑：

before_turn：在模型生成前执行
after_turn：在模型生成后执行
可用于：代码审查、日志记录、策略执行等

九、代码库图：Tree-sitter 驱动的代码理解

xai-codebase-graph crate 是 Grok Build 的代码理解引擎，基于 Tree-sitter 构建。

9.1 能力

Go-to-definition：跳转到符号定义
Go-to-references：查找符号引用
增量索引：基于文件系统事件更新
并行解析：使用 Rayon 并行处理
内存映射 I/O：零拷贝文件读取

9.2 架构

IndexManager (Actor)
  ├── IndexCommand::Build → 构建完整索引
  ├── IndexCommand::Reindex → 增量重索引
  └── QueryCommand:
      ├── GotoDefinition → 跳转到定义
      ├── GotoReferences → 查找引用
      └── GetFileCount → 轻量统计

索引缓存到磁盘，支持跨会话复用。语言注册表支持多种语言，每种语言有自己的 Tree-sitter 查询配置。

十、编译与许可：Apache 2.0 开源的细节

10.1 构建系统

Grok Build 使用 Rust 2024 edition，依赖：

DotSlash：用于管理 protoc 等工具
jemalloc：生产环境使用 jemalloc 内存分配器
多构建 profile：release、release-dist（LTO+CGU1）、x-prod（unwind on panic）

10.2 许可

第一方代码：Apache 2.0
第三方代码：保留原许可证
包含了来自 OpenAI Codex 和 SST OpenCode 的移植代码，都注明了 Apache §4(b) 变更通知

10.3 已知限制

不接受外部贡献（CONTRIBUTING.md 明确说明）
Windows 构建是 best-effort，未在 CI 中测试
源码从 xAI 内部 monorepo 定期同步（SOURCE_REV 文件记录了 monorepo commit SHA）

写在最后

Grok Build 的开源，对 AI 编程工具领域有三个深远影响：

第一，ACP 协议的推广。 agent-client-protocol 作为一个通用规范，在 Grok Build 之后可能成为类似 LSP 在编辑器领域的标准——所有 AI Agent 都通过同一个协议与客户端通信。

第二，Rust 在 AI Agent 领域的示范。 50+ crate、Actor 模式、严格的类型系统、零成本抽象——这是 Rust 在复杂 AI 系统上的最佳实践展示。

第三，验证机制的工程化。 对抗性 skeptic 验证、目标系统、Doom Loop 检测——这些不是学术论文中的概念，而是实打实的生产级代码。

如果你对 AI Agent 工程感兴趣，我强烈建议你 clone 下来读一读。这不是一个"调 API"的项目，而是 xAI 工程团队在 AI Agent 基础设施上深思熟虑的答卷。

GitHub 地址：https://github.com/xai-org/grok-build

Coding Agent on AI博士 万戈

Nanobot 源码深度拆解：Python 异步消息总线构建的轻量级 AI Agent 框架

一、架构全景：MessageBus 异步事件驱动

二、两阶段 Agent Loop：调度层和执行层分离

2.1 AgentLoop — 调度层

2.2 AgentRunner — 执行层

三、TurnState 状态机：8 个状态的精细控制

四、Dream 两阶段记忆合并

第一阶段：Consolidation

第二阶段：Dream

五、MCP 集成：最复杂的子系统

六、工具系统：自动发现 + 参数校验

6.1 自动发现

6.2 参数校验

七、Provider 抽象层：Fallback 链式封装

八、和三个编码 Agent 的横向对比

写在最后

OpenCode 源码深度拆解：Effect TS 代数效应系统构建的智能编码 Agent

一、Monorepo 全景

二、Effect TS：不是「用了」，是「深嵌」

2.1 Context.Service 依赖注入

2.2 Effect.gen 代数效应

2.3 Schema 优先验证

2.4 为什么这很重要？

三、四轴 LLM 路由体系

3.1 Protocol 复用

3.2 RequestExecutor 重试逻辑

四、双 Agent 架构：build vs plan

五、Session 架构：V2 的持久化改革

5.1 Session 处理循环（Processor）

5.2 双运行时策略

六、插件系统：V1 + V2 双轨制

七、和 Grok Build 的深层对比

7.1 哲学差异

7.2 工具系统

7.3 MCP 集成

八、三篇编码 Agent 的横向对比

写在最后

Pi Agent 深度拆解：TypeScript 多包架构下的 Steering + Follow-up 双队列设计

一、五层包的依赖关系

二、Agent Loop：Steering vs Follow-up 双队列

三、30+ LLM Provider 的抽象层

四、工具系统：定义优先 + 双层注册

五、会话管理：JSONL 树形文件

六、子代理：RPC 进程级编排

七、扩展系统 vs 插件系统

八、安全问题：没有内置权限系统

九、和 Grok Build 的深层对比

9.1 并发模型

9.2 工具系统

9.3 协议

9.4 验证系统

写在最后

xAI 开源了 Grok Build！万字拆解 40 万行 Rust 构建的 AI Coding Agent 内部架构

一、项目概览：40 万行 Rust，50+ 个 Crate 的模块化巨构

二、ACP 协议：让 Agent 和客户端解耦的「七层协议」

三、Agent 运行时：从 MvpAgent 到子 Agent 协调器

3.1 MvpAgent 的职责

3.2 会话生命周期

3.3 子 Agent 系统

四、工具系统：60+ 工具的分层架构

4.1 旧架构 vs 新架构

4.2 工具注册与资源注入

4.3 核心工具一览

五、终端系统：Actor 模式 + 智能超时管理

5.1 Actor 架构

5.2 智能的超时策略

5.3 搜索工具 Shadow

六、Sampler 层：三层架构的 LLM 请求处理

6.1 三层 API

6.2 重试策略

6.3 Doom Loop 检测

七、目标系统：阴谋论者式的验证机制

7.1 工作流程

7.2 关键参数

八、MCP 与插件系统：生态扩展能力

8.1 MCP 集成

8.2 插件系统

8.3 Hooks 系统

九、代码库图：Tree-sitter 驱动的代码理解

Coding Agent on AI博士万戈