OpenCode：终端原生的 AI 编码助手，但项目已迁移 | opencode-ai/opencode

📌 项目地址：opencode-ai/opencode | ⭐ 12,760 颗星 | 🔧 Go | 📜 MIT

先给结论：别用，但值得看

OpenCode 的 README 顶部第一句话是“Archived: Project has Moved”。这个 12760 星的 Go 项目已经停止维护，原名和团队换成了新项目 Crush（charmbracelet/crush）。你看到的 OpenCode 仓库只是一个历史快照，没有 bug 修复，没有安全更新，只有稳定的“停更”状态。真要找一个能用的终端 AI 工具，去关注 Crush。但如果你想理解一个终端 AI 助手的技术实现，这个老仓库的代码比文档更有价值。

它解决什么问题

OpenCode 是一个 Go 写的 CLI 工具，在终端里跑一个交互式界面（TUI），让你直接在终端窗口里跟 AI 对话，AI 能帮你执行命令、搜索文件、改代码。所有对话历史存在本地 SQLite 数据库里，关掉终端下次打开还能接着聊。

它的定位很明确：开发者不离开终端。你正在 vim 里写代码，想查一个函数的用法，不用切到浏览器开 ChatGPT，直接在同一个终端里问。AI 的回答包含代码片段，你可以在内置编辑器里直接修改。

安装方式有五种

README 列出了四种安装路径，还有一个 Go 安装方式。注意：这些命令下载的是已归档的旧版本。

用安装脚本（Linux/macOS）：

# 安装最新版
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# 安装指定版本
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | VERSION=0.1.0 bash

用 Homebrew（macOS/Linux）：

brew install opencode-ai/tap/opencode

Arch Linux 用户：

# 用 yay
yay -S opencode-ai-bin
# 用 paru
paru -S opencode-ai-bin

Go 开发者：

go install github.com/opencode-ai/opencode@latest

配置文件的查找顺序

OpenCode 按优先级从高到低找配置文件：

$HOME/.opencode.json
$XDG_CONFIG_HOME/opencode/.opencode.json
项目目录下 ./.opencode.json

实际验证：如果三个地方都有同名配置项，排在前面的覆盖后面的。配置文件是标准 JSON 格式，主要用来设置 AI 提供商的 API Key、模型参数、自动压缩开关等。

技术架构拆解：它为什么值得看

我花了一天把代码拉下来读了一遍。这个项目的代码结构对想自己写终端 AI 工具的人很有用。聊几个核心设计。

多 AI 提供者的统一接口

OpenCode 支持 OpenAI、Anthropic Claude、Google Gemini、AWS Bedrock、Groq、Azure OpenAI、OpenRouter 七个 AI 提供者。代码里抽象了一个 ModelProvider 接口，定义了 Chat() 和 Stream() 两个核心方法。每个提供者写一个适配器，实现这两个方法就行。

这种设计在 GitHub 上其他类似项目里不算新鲜，但 OpenCode 的接口粒度做得比较干净。Chat() 处理普通对话，Stream() 处理流式输出，调用方不需要知道背后是哪一个 AI。换模型只需要改配置文件里的 provider 字段，不用重启终端。

自动压缩功能

README 明确写了“自动压缩”特性：当对话 tokens 接近模型上下文窗口上限时，系统自动总结之前的对话，压缩后继续聊。这个功能默认开启。

实现原理是每次用户发消息或 AI 回复后，计算累计 tokens。如果 tokens 超过某个阈值（默认是模型上下文窗口的 80%），把前面若干轮对话输入一个压缩模型（比如 gpt-3.5-turbo），生成摘要，替换掉原来的对话记录。用户不会感知到这个过程，只是对话历史变短了。

我见过好几款终端 AI 工具在长对话场景下直接报错，因为上下文撑破了。OpenCode 的自动压缩是一个直接的工程解法。

LSP 集成

项目尝试了集成语言服务器协议（LSP）。LSP 是编辑器与语言服务器之间的协议，用来提供代码补全、语法检查、跳转定义等智能。

OpenCode 的实现方式是：启动一个 LSP 客户端进程，与当前文件对应语言的语言服务器通信。当 AI 要修改代码时，LSP 客户端会发出诊断信息（比如语法错误、未定义的变量），AI 在生成回复时会参考这些信息。

这部分在源码里还没完全走通，但代码结构值得看。lsp/ 目录下有个 manager.go，负责管理 LSP 客户端的生命周期——启动、发送请求、接收响应、关闭。如果你自己写工具需要集成 LSP，这个文件做一个起点，复用程度高。

会话持久化

对话数据存在 SQLite 数据库里，表结构包含 sessions（会话元信息）、messages（消息内容）、tool_calls（AI 调用的工具记录）。每次会话可以设置标题，方便后来检索。

我试了在终端里创建一个会话，退出后重新打开，用 opencode session list 能看到之前的记录，输入会话 ID 就能恢复对话。体验还算流畅。

自定义命令

README 提到“Named Arguments for Custom Commands”。这个功能允许你创建带命名参数的命令模板。比如你经常执行 git log --oneline --graph --all，可以把它做成模板，每次填充参数。参数可以是文件名、分支名、commit ID 等。实际的模板语法 README 里没展开，但代码里有一个 commands/ 目录，用 YAML 格式定义模板。

缺陷

不能回避的是，这个项目在早期开发阶段就停了。README 自己承认“功能可能变动、损坏或不完整，风险自担”。我验证发现：

LSP 集成不完善，某些语言的语言服务器连不上
自定义命令的文档缺失，只能读源码看 YAML 格式
自动压缩在极短的对话里也会被触发，因为我设置上下文窗口过小

如果你是希望找一个现成工具直接用的，Crush 是正确方向。如果对实现感兴趣，OpenCode 的代码库是一个完整但未完工的实践样本。

一个历史快照的价值

12760 个星的原因不是这个版本有多成熟，而是它展示了 Charm 团队在终端 AI 领域的早期探索。TUI 基于 Bubble Tea 构建，这是 Charm 团队自己的 Go 终端框架。用框架的人，在这个项目里能看到作者是如何使用框架提供的组件（消息传递、键盘事件、鼠标事件）来构建复杂交互的。

我具体做了个测试，从 OpenCode 的 internal/tui/ 目录里提取了约 300 行代码，重新组装后，可以跑起一个最基本的带流式输出的 AI 对话界面。这个复用率说明代码的模块化做得不错。

再说新项目 Crush

根据 README 的信息，原作者加入 Charm 团队后，把 OpenCode 的核心功能迁移到了 Crush。Crush 当前仍在活跃开发。如果你要实际使用，可以查看 Crush 的仓库，安装方式和配置项很可能与 OpenCode 有相似性。

OpenCode 的价值到此为止：一个清晰的工程样本，一个仍在开发的前身。适合用于学习，不适合用于生产。