Fanier's Library

本文字数：974，阅读时长大约2分钟

导读：OpenCode 是一个用 Go 写的开源 AI 编程助手，GitHub 10 万+ Star。

OpenCode 是一个用 Go 写的开源 AI 编程助手，GitHub 10 万+ Star。

![](/Media/editor/wechat2026-02-198273817088846678/2026-02-197168778980717270.png "null")

最近在疯狂的了解各种 agent 的实现方式，所以我花了几周时间读完它的源码，然后用 Rust 从零重写了一个——不是为了替代它，而是想搞清楚：一个 AI 编程 Agent 到底是怎么工作的？Rust 做这件事有什么不同？重写的过程中，我又做了哪些超越原版的设计？

直接看看效果。

![TUI版本](/Media/editor/wechat2026-02-198273817088846678/2026-02-196778868088808081.png "null")

TUI版本

![接入 telegram](/Media/editor/wechat2026-02-198273817088846678/2026-02-196985658485868784.jpg "null")

接入 telegram

### 为什么要研究 OpenCode？

如果你用过 Claude Code 或 Cursor，你大概知道 AI 编程助手能做什么——读代码、改文件、跑命令、搜索代码库。但你可能不知道它背后是怎么运转的。

商业产品的代码你看不到。而 OpenCode 是开源的。

OpenCode 用 Go 写成，Bubble Tea 做 TUI，SQLite 存会话，支持十几个 AI Provider，有完整的工具系统、MCP 协议、LSP 集成、上下文压缩……它基本上就是一个开源版的 Claude Code。

我读它的源码，是想回答几个问题：

1. 1. **Agent Loop 怎么实现？** 工具调用 → LLM 判断 → 再调用，这个循环的边界条件在哪？
2. 2. **上下文压缩怎么做？** 对话越来越长，token 用完了怎么办？
3. 3. **权限系统怎么设计？** AI 要执行 `rm -rf`，你怎么拦？
4. 4. **多模式怎么共存？** 同一个 Agent 核心，怎么同时支持 REPL、TUI、HTTP Server？

读完源码之后，我决定用 Rust 重写。不是因为 Go 不好，而是我想在重写的过程中，用 Rust 的方式重新思考每一个设计决策。

### 从 OpenCode 学到的核心设计

#### Agent Loop：工具调用的无限循环

OpenCode 教会我的第一课：AI Agent 的本质是一个 **while 循环**。

```
loop {  
    response = LLM.chat(messages)  
    if response 包含工具调用:  
        result = 执行工具(tool_name, input)  
        messages.push(tool_result)  
        continue  // 继续循环，让 LLM 决定下一步  
    else:  
        break  // LLM 选择用文本回复，循环结束  
    if 步数 > max_steps:  
        break  // 安全阀门  
}
```

就这么简单。所有的"智能"都在 LLM 端——Agent 框架只负责忠实地执行工具、把结果喂回去、让 LLM 继续决策。

OpenCode 在 Go 中的实现大约在 `agent.go` 的 300 行左右。我在 Rust 里对应的是 `agent_loop.rs` 的 `run_emitting()` 方法。逻辑本质相同，但表达方式因语言而异（后面会讲）。

#### 事件驱动：Agent 不关心前端

OpenCode 的第二个关键设计：Agent 核心和 UI 之间通过**事件**解耦。

在 Go 版本中，Bubble Tea 的 TUI 通过 channel 接收 Agent 的输出事件。这意味着 Agent 不直接 `fmt.Println`，而是把事件发到 channel 里，由 UI 层决定怎么展示。

这个思路我完全继承了，并且进一步推广——不只是 TUI，**所有五种模式都通过同一个 channel 消费事件**：

```
Agent.run_emitting()  
    → mpsc::channel<AgentEvent>  
        → REPL: 打印到 stdout  
        → TUI: 更新 ratatui 状态  
        → Server: 转成 SSE  
        → Telegram: 累积成聊天消息  
        → Discord: 转成 Embed
```

#### 会话持久化 + 上下文压缩

OpenCode 用 SQLite 存会话历史（messages 表），在 token 接近 95% 上限时触发 auto-compaction——用 LLM 自己来总结之前的对话，用摘要替换原始消息。

我的实现沿用了这个方案，因为它确实是最实用的：

- • SQLite 轻量、无需额外依赖、单文件
- • LLM 做摘要比规则裁剪丢失的信息更少
- • compaction 对用户透明，不会打断工作流

### 为什么用 Rust 重写？

读懂了设计之后，为什么不直接用 OpenCode，而要自己重写？

#### 理解的最深层次是重建

看代码和写代码是两回事。

读 OpenCode 的源码，我能理解"Agent Loop 是一个 while 循环"。但只有自己写的时候，我才会碰到这些问题：

- • 工具调用超时了怎么办？
- • 流式输出中途断了怎么恢复？
- • 两个工具调用的结果顺序不一致时怎么处理？
- • 权限请求和事件流在同一个 select! 里怎么协调？

**读源码让你知道 What，重写让你理解 Why。**

#### Rust 的类型系统逼你做对的设计

这是我选 Rust 最重要的原因。

Go 的 interface{} 和 Rust 的 enum 在表达 Agent 事件时的差异，直接影响架构质量。

在我的 Rust 实现中，Agent 的所有可能事件是一个穷尽的枚举：

```
pub enum AgentEvent {  
    TextDelta(String),  
    TextComplete(String),  
    ToolCallStart { id: String, name: String, input: Value },  
    ToolCallResult { id: String, name: String, output: String, is_error: bool },  
    SubAgentStart { name: String, prompt: String },  
    SubAgentEnd { name: String, result: String },  
    CompactionStarted,  
    CompactionCompleted,  
    TokenUsage { input_tokens: u64, output_tokens: u64 },  
    TurnComplete,  
    Error(String),  
    SessionInfo { session_id: String, message: String },  
}
```

当我写 event consumer 时，`match` 表达式要求我处理每一个变体。**编译器不允许你遗漏任何情况。** 这意味着每加一个新的 `AgentEvent` 变体，所有 consumer（REPL、TUI、Server、Telegram、Discord）都会编译报错，直到你处理了它。

Go 的做法通常是 `switch` + `default` 分支，漏掉一个 case 不会报错，只会在运行时静默跳过。

权限系统同理：

```
pub enum PermissionResponse {  
    Allow,  
    AlwaysAllow,  
    Deny,  
    NeverAllow,  
}
```

四种响应，每个 handler 都必须穷尽处理。你不可能"忘记处理 NeverAllow"——编译器不让你过。

#### 所有权模型天然防并发 Bug

Bot 模式下，多个用户可能同时发消息。Agent 被包在 `Arc<Mutex<Agent>>` 里。

在 Go 里，你需要人肉记住哪些地方该加锁、锁的范围是什么。忘了就是 data race，而且 Go 的 race detector 只能在运行时发现。

Rust 的方案：

```
// 编译器强制你获取锁才能访问 Agent  
let mut agent = agent_arc.lock().await;  
agent.run_emitting(&text, event_tx, perm_tx).await;  
// lock guard drop 时自动释放锁
```

你不可能在不持有锁的情况下访问 Agent 的任何字段——这不是靠纪律，是靠编译器保证。如果你尝试跨 `.await` 持有 `std::sync::Mutex` 的锁，编译器会直接报错（因为 MutexGuard 不是 Send）。

#### Feature Flags：零成本的可选功能

这是 Cargo 独有的优势。

teloxide（Telegram SDK）编译要拉几十个 crate，serenity（Discord SDK）也是。但如果你只用 REPL 模式，为什么要编译它们？

```
[features]  
default = []  
telegram = ["teloxide"]  
discord = ["serenity"]
```

`cargo build` → 不编译任何 bot 代码，二进制体积不增加。  
`cargo build --features telegram` → 只编译 Telegram 相关代码。

Go 没有原生的条件编译机制（build tags 功能有限），通常的做法是全量编译或拆成多个 binary。

#### 零成本抽象：channel 没有运行时开销

Rust 的 `tokio::sync::mpsc` channel 和 `oneshot` channel 是零成本抽象。在 release 模式下，channel 的性能开销几乎可以忽略——它不需要反射、不需要 GC、不需要装箱拆箱。

我的权限系统用了一个巧妙的模式：

```
pub struct PermissionRequest {  
    pub tool_name: String,  
    pub input: serde_json::Value,  
    pub respond: oneshot::Sender<PermissionResponse>,  
}
```

Agent 发出请求后阻塞在 `oneshot::Receiver` 上等回复。如果 consumer 端 drop 了 Sender（比如超时），Receiver 自动收到 Err——这就是"自动 Deny"，不需要额外代码。

**所有权转移就是通信协议，drop 就是超时处理。** 这种设计只有 Rust 的所有权语义能如此自然地表达。

### 超越 OpenCode：接入 Telegram 和 Discord

OpenCode 原版支持 REPL 和 TUI 两种模式。我的 Rust 版本在此基础上增加了三种：HTTP Server、Telegram Bot、Discord Bot。

其中 Bot 模式是最有趣的——**在手机上发条消息，就能驱动远程服务器上的 AI Agent 读代码、改文件、跑测试。**

#### 700 行代码接入两个平台

得益于 channel 解耦架构，整个 Bot 模块只有 ~700 行代码：

```
src/bot/  
├── mod.rs        -- BotState, SessionManager, 访问控制 (~115 行)  
├── formatter.rs  -- AgentEvent → 聊天消息转换 (~170 行)  
├── splitter.rs   -- 按平台字符限制智能拆分 (~100 行)  
├── telegram.rs   -- Telegram 适配器 (~350 行)  
└── discord.rs    -- Discord 适配器 (~350 行)
```

核心的事件消费逻辑长这样（Telegram 和 Discord 共用）：

```
loop {  
    tokio::select! {  
        // 消费 Agent 事件  
        event = event_rx.recv() => {  
            letmessages = accumulator.process(event);  
            formsgin messages {  
                send_to_platform(msg).await;  
            }  
        }  
        // 处理权限请求  
        perm = perm_rx.recv() => {  
            ifauto_approve(tool_name) {  
                respond(Allow);  
            } else {  
                send_inline_buttons();  // 让用户点按钮  
            }  
        }  
        // 定时 flush 累积的文本  
        _ = interval.tick() => {  
            flush_accumulated_text().await;  
        }  
    }  
}
```

#### 文本累积：解决聊天平台的流式难题

LLM 的流式输出是一个 token 一个 token 来的。终端可以实时打印，但聊天平台不行——你不能每收到一个字就发一条消息。

解决方案是 `EventAccumulator`：

- • `TextDelta` → 追加到缓冲区，不发送
- • `ToolCallStart` → 先 flush 缓冲区的文本，再发工具通知
- • `TurnComplete` → flush 所有剩余文本
- • 每 3 秒 → 定时 flush，让用户看到中间进度

#### 权限按钮：oneshot 的妙用

当 Agent 需要执行危险操作时，Bot 会发一组 inline buttons：

```
⚠️ Permission required  
Tool: bash  
Input: rm -rf node_modules && npm install  
  
[✅ Allow] [✅ Always] [❌ Deny] [❌ Never]
```

用户点击按钮后，callback handler 通过之前存好的 `oneshot::Sender` 把决定传回 Agent。如果 60 秒没人点，超时任务 drop 掉 Sender，Agent 自动收到拒绝。

整个流程没有轮询、没有全局状态——就是一个 oneshot channel 完成双向通信。

### Rust vs Go：做 AI Agent 框架的体感对比

写完整个项目，我可以给一个比较客观的对比：

| 维度 | Go (OpenCode) | Rust (rust-code) |
| --- | --- | --- |
| **上手速度** | 快，goroutine + channel 天然好写 | 慢，所有权要过脑子 |
| **并发安全** | 靠纪律 + race detector | 靠编译器，不安全的代码编译不过 |
| **枚举表达力** | interface{} + type switch，可能遗漏 | enum + match 穷尽检查，不会遗漏 |
| **条件编译** | build tags（有限） | feature flags（原生、强大） |
| **错误处理** | if err != nil（容易忽略） | Result<T, E> 必须处理 |
| **生态丰富度** | AI/Web 生态成熟 | 追赶中，但 tokio 生态够用 |
| **编译速度** | 秒级 | 分钟级（首次），增量秒级 |
| **二进制大小** | 较大（runtime） | 较小（无 GC runtime） |
| **部署** | 单二进制 | 单二进制 |

**结论：Go 更适合快速出原型，Rust 更适合"把事情做对"。**

如果你是要快速验证 AI Agent 的产品 idea，Go（或 Python）是更好的选择。但如果你像我一样，目的是深入理解每一个设计决策、并且希望编译器帮你兜底并发安全，Rust 是更好的选择。

### 架构全景

五个 Phase 走下来，rust-code 的完整架构长这样：

```
CLI: --mode repl | tui | server | telegram | discord  
              │      │       │         │          │  
         ┌────▼──┐ ┌─▼──┐ ┌─▼───┐ ┌───▼───┐ ┌───▼────┐  
         │ REPL  │ │TUI │ │axum │ │teloxide│ │serenity│  
         │stdout │ │rat.│ │SSE  │ │Tg API  │ │Dc API  │  
         └───┬───┘ └─┬──┘ └──┬──┘ └───┬───┘ └───┬────┘  
             └────────┴───────┴────────┴─────────┘  
                     Agent.run_emitting()  
               mpsc<AgentEvent> + mpsc<PermissionRequest>  
                          │  
              ┌───────────┼───────────┐  
              │           │           │  
         ┌────▼────┐ ┌───▼────┐ ┌───▼───┐  
         │ Provider │ │ Tools  │ │Session│  
         │Anthropic │ │ 15个   │ │SQLite │  
         │ OpenAI   │ │+MCP    │ │+压缩  │  
         └─────────┘ └────────┘ └───────┘
```

~5000 行 Rust，15 个工具，5 种交互模式，支持任意 OpenAI 兼容 Provider。

### 踩过的坑

#### 1. Mutex 跨 await：Rust 编译器救了我

```
// ❌ 编译报错：MutexGuard 跨 await  
let agent = agent_arc.lock().await;  
agent.run_emitting(&text, tx, ptx).await;  // 还在持有锁！  
  
// ✅ 正确：tokio::Mutex 支持跨 await  
let mut agent = agent_arc.lock().await;  // tokio::sync::Mutex  
agent.run_emitting(&text, tx, ptx).await;  
// drop 时释放
```

Go 里这种 bug 是运行时 panic（如果你记得用 race detector 的话），Rust 里是编译期错误。

#### 2. Telegram MarkdownV2 转义地狱

Telegram 的 MarkdownV2 模式需要转义 18 个特殊字符。AI 输出的代码到处都是这些字符。最后选择纯文本发送——简单粗暴但可靠。

#### 3. oneshot drop = 自动拒绝

如果 60 秒没人点权限按钮，超时任务 drop 掉 `oneshot::Sender`，Agent 端的 `Receiver` 收到 `Err`，自动当作拒绝处理。不需要显式发送 Deny 消息——所有权转移就是通信，drop 就是超时。这种模式在 Go 里需要 select + timer + default 来模拟，不如 Rust 优雅。

### 写在最后

从读 OpenCode 源码到 Rust 重写，再到接入 Telegram，整个过程大概三周。

我得到了什么？

**第一，对 AI Agent 的深度理解。** Agent 不是魔法，就是一个 while 循环 + 工具调用 + context 管理。理解了这些，你就能理解市面上所有 AI 编程工具的核心机制。

**第二，对 Rust 异步编程的实战经验。** tokio::spawn + Arc + Mutex + mpsc + oneshot + select! 这套组合拳，做完这个项目你就真的会了。

**第三，一个可用的工具。** 现在我出门在外，在手机上给 Telegram Bot 发一条消息，就能让远程服务器上的 Agent 帮我查代码、跑测试。这种感觉很爽。

OpenCode 是一个很好的学习对象。如果你对 AI Agent 感兴趣，我建议你也去读它的源码。如果你想更进一步，试着用你熟悉的语言重写一遍——你会发现，理解的最深层次，是重建。

**项目地址**：https://github.com/coder-zhang/rust-code

**OpenCode 原版**：https://github.com/opencode-ai/opencode

---

如果你对 AI Agent 的实现细节或者 Rust 异步编程有疑问，欢迎评论区交流。

从 OpenCode 到 rust-code：我用 Rust 重写了一个 AI 编程 Agent，还把它接入了 Telegram

猜你喜欢

如何快速读懂一本书？

基于 4C 理论的亚马逊购物网营销策略研究

安全套能防所有性病吗？如淋病，艾滋

送走渣男

为什么现在的年轻人这么怀念苏联？

荆棘之上