OpenCode SDK 作为自定义 AI Agent 平台基座的选型理由

关联文档：[[../../harness/工作台/软件设计/004 Codex 会话模块设计]]

问题背景

我在比较 OpenCode、Codex、Claude、Pi 这些 Agent 工具时，最先需要澄清的是：这里要选的不是一个“最好用的 AI 编程工具”，而是一个适合承载自定义 AI Agent 平台的基座。

这两个问题完全不同。个人使用工具时，重点是交互顺不顺、模型强不强、命令能不能跑通。做平台时，重点变成了运行时边界是否清晰、会话能否管理、事件能否订阅、权限能否控制、文件和 diff 能否被上层产品稳定消费。

所以，我不会把 Claude SDK、OpenAI SDK、Pi SDK、Codex app server 和 OpenCode SDK 简单放在同一个层面比较。它们解决的问题不同，适合的位置也不同。

模型 SDK 和 Agent 运行时不是一回事

Claude SDK 和 OpenAI SDK 更接近模型 API 层。它们擅长解决模型调用、streaming、tool use、结构化输出等问题。如果只是做一个业务聊天助手，或者在后端服务里调用模型完成某个固定任务，它们非常合适。

但自定义 AI Agent 平台需要的不只是“向模型发消息”。平台还要管理项目、会话、消息、工具、文件、命令、权限、事件、diff、revert、模型供应商和审计记录。模型 SDK 不会直接提供这些能力，团队必须自己实现一套 Agent runtime。

这部分工作很重，而且大多不是业务差异化。真正有价值的是平台产品层，比如任务模型、团队协作、权限策略、流程编排、质量审查和交付闭环，而不是重新造一遍文件搜索、命令执行和会话事件协议。

因此，我更倾向于把 Claude SDK、OpenAI SDK 放在 provider 层，而不是把它们作为整个平台的基座。

Pi 更像极简可改造的 harness

Pi 的定位很清楚：它是一个极简 agent harness，强调“让 harness 适应你的工作流”。它支持 extensions、skills、prompt templates、themes，也提供 interactive、print / JSON、RPC 和 SDK 等多种使用方式。

这个设计对个人工作流很有吸引力。Pi 的核心很轻，扩展空间很大，适合把一个 agent 工具改造成非常贴合自己习惯的形态。

但从团队级平台视角看，这种极简也意味着很多平台能力需要自己补。Pi 官方把 MCP、sub-agent、permission popup、plan mode、内置 todo、background bash 等能力留给扩展或使用者自行实现。这不是缺陷，而是它的设计哲学。

如果目标是做一个可塑性很强的个人 agent shell，我会认真考虑 Pi。如果目标是做产品化的 AI Agent 平台，我会更重视默认运行时能力的完整性，这也是我偏向 OpenCode SDK 的原因。

Codex app server 需要谨慎依赖

Codex 是成熟的 AI 编程工具体系，但如果讨论的是 Codex App 或 CLI 背后的 app server，就需要谨慎判断它是不是稳定公开的开发接口。

平台基座不能过度依赖内部服务层。只要接口稳定性、版本承诺和能力边界不清晰，后续就会出现适配成本：客户端一变，上层平台也要跟着修；某个事件结构一变，前端状态就可能出问题；权限、会话、中断、历史这些关键流程也很难形成长期可靠的产品契约。

所以，除非 Codex 明确提供稳定的 agent server SDK，否则我不会把 app server 当成自定义平台的核心基座。它更适合被当作现成工具使用，或者在局部自动化里集成。

OpenCode SDK 的优势在运行时边界

OpenCode SDK 的关键优势不是“能发 prompt”，而是它连接的是 OpenCode server。OpenCode 的 TUI 本身就是 server 的一个 client，SDK 也是另一个 client。这说明它天然采用了多客户端架构：终端、Web、IDE、桌面端、自动化 worker 都可以围绕同一个运行时工作。

从平台开发角度看，这个边界很重要。OpenCode server 暴露了 project、session、message、file、find、diff、permission、event、agent、config、provider、auth、MCP、LSP、formatter、TUI control 等能力。它们正好对应一个 coding agent 平台需要管理的核心对象。

更重要的是，OpenCode server 通过 OpenAPI 3.1 暴露接口，SDK 是类型安全 client。这比直接包 CLI 或依赖内部 app server 更适合长期开发。上层平台可以围绕这些 API 做权限网关、审计日志、任务队列、状态同步和前端展示，而不需要猜测底层工具的内部状态。

推荐的分层方式

我会把基于 OpenCode SDK 的平台拆成四层。

产品层：Web 控制台、工作台、IDE 插件、自动化任务入口
平台层：用户、项目、任务、权限、审计、队列、通知、组织管理
运行时层：OpenCode server + OpenCode SDK
模型与工具层：Claude、OpenAI、其他 provider、MCP、Shell、LSP、formatter

这种拆法的好处是边界清晰。OpenCode 负责 Agent runtime，平台负责产品化编排。模型供应商仍然可以替换，工具生态也可以继续扩展，但上层业务不必直接绑定某一个模型 SDK。

结论

如果只是调用模型，Claude SDK 或 OpenAI SDK 就够了。如果想做一个极简、可深度改造的个人 agent harness，Pi 很适合。如果只是想使用成熟 AI 编程产品，Codex 或 Claude Code 可以直接作为工具使用。

但如果目标是开发团队级、自定义、可产品化的 AI Agent 平台，我会选择 OpenCode SDK 作为基座。

原因不是 OpenCode 功能最多，而是它已经提供了平台真正需要的运行时对象：项目、会话、消息、文件、工具、权限、事件、配置、agent 和多客户端 server。它让平台团队可以站在 Agent runtime 之上做产品，而不是从模型 API 之上重新搭基础设施。

Comments

Post a Comment

Popular posts from this blog

How to turn off Sass warning prompts in Nuxt.js projects

Background of the Issue When developing projects with Nuxt.js, it’s common to encounter a large number of Sass-related warning messages in the console. These warnings mainly include: Warnings about the order of mixin declarations. Warnings about the use of Legacy JS API. Although these warnings do not affect the operation of the program, they can degrade the development experience by cluttering the console. Today, we will explore how to elegantly address this issue. Solutions 1. Disable Warnings via Configuration In the nuxt.config.js file, we can modify the Sass configuration to suppress these warning messages: export default { build: { loaders: { scss: { sassOptions: { quietDeps: true , // Suppress warnings from dependencies logger: { warn: function ( message ) { return null ; // Silence warning messages }, debug: function ( message ) { return null ; // Silence ...
Read more

Configuring SSH Access to a Docker Container via an Alternative Port

Configuring SSH Access to a Docker Container via an Alternative Port If you want to configure SSH access to a Docker container using an alternative port, such as port 6666 , follow the steps below carefully. This guide assumes that you have administrative access to your Docker host and are familiar with basic Linux commands. Step 1: Run the Container with SSH Service Start by running a new container from your image with port 6666 on the host mapped to port 22 inside the container: sudo docker run -it -p 6666 : 22 --name ssh-container testimage Make sure to replace testimage with the actual name of your Docker image. The --name option gives the container a specific name for easier management. Step 2: Install OpenSSH Server in the Container Once inside the container, update the package list and install the OpenSSH server: apt-get update && apt-get install -y openssh-server Step 3: Set the Root Password Set a password for the root user, which will be required when l...
Read more

Quickly Set Up a Cloud Database Using MongoDB Atlas

Quickly Set Up a Cloud Database Using MongoDB Atlas MongoDB Atlas is the official fully managed cloud database service from MongoDB, simplifying the deployment, management, and scaling of MongoDB in the cloud. This article will guide you on how to quickly create a MongoDB Atlas cluster and set up basic connection configurations. Creating a MongoDB Atlas Cluster Sign Up & Log In If you do not have a MongoDB Atlas account yet, head over to MongoDB Atlas to sign up. After logging in, click on “Build a Cluster” to start creating a new cluster. Select Cluster Configuration To meet the needs of most development and testing scenarios, you can choose the free tier (M0) shared cluster, which is usually sufficient for small applications or personal projects. When choosing a cloud provider, select based on your preference. Here we chose Azure, but AWS and GCP are also great choices. Specify Geographic Location For geographic location selection, choose according to your u...
Read more