{"author":{"id":"4e3fvwoonbfzbvqtdwehr2fzdp","name":"陈成","avatar_url":"https://lh3.googleusercontent.com/a/ACg8ocLP6uaUWVTzl3dUQgZAldOJdTbU_NCUcOxb0Jx1K5CuD97UlDiQ=s96-c","handle":"sorrycc"},"mine":false,"report":{"topic_id":"lipmqfzj6gq3","markdown":"# OpenCode 2 调研报告\n\n| 项目 | 内容 |\n|---|---|\n| 日期 | 2026-10-23 |\n| 对象 | OpenCode 2，2026-10-12 正式发布，当前版本 v2.1.3 |\n| 依据 | 官方博客与 v2 文档、v2.1.3 源码、X 与 Reddit 社区讨论 |\n| 专题文档 | `opencode2-code-mode-分析-2026-10-23.md`、`opencode2-新API-分析-2026-10-23.md` |\n\n## 摘要\n\n- OpenCode 2 是一次架构重写，不是功能迭代。核心变化有六项：常驻后台服务、新 API、Code Mode、后台任务、插件化与热重载、可嵌入的 SDK。\n- 定位从\"终端里的编码助手\"转向\"可嵌入的 agent 后端\"。TUI、Web、桌面端都只是同一个服务的客户端，同一套代码还能运行在用户进程或 Cloudflare Durable Object 中。\n- 设计重心是长时间运行、多客户端并存、允许断线的场景。具体做法是持久化的输入队列、可续读的事件日志，以及不破坏 prompt cache 的工具清单更新。\n- 主要代价是兼容性。v1 插件和 Server API 全部失效，实验性接口占比较高，发布节奏和版本说明也不够清晰。\n\n## 1. 时间线\n\n| 时间 | 事件 |\n|---|---|\n| 2026-04-30 | 官方预告 2.0 将更易嵌入，支持分布式会话与断线重新同步 |\n| 2026-08 | opencode2 beta 开放试用，约 1.5 万用户每日使用 |\n| 2026-10-12 | 2.0 正式发布；Cloudflare 同日发布基于它的 OpenCodeHarness |\n| 2026-10-20 至 22 | v2.1.0 至 v2.1.3 连续发布 |\n\n## 2. 架构变化概览\n\n| 维度 | v1 | v2 |\n|---|---|---|\n| 进程模型 | 每个客户端各自启动，server 模式需手动开启 | 本机单一常驻服务，所有客户端共享 |\n| API | 逐步累积的路由，188 个操作 | 从零重写，146 个操作，由单一契约生成 |\n| 工具调用 | 逐个调用，全部工具 schema 常驻 prompt | MCP 等长尾工具经 Code Mode 脚本化调用 |\n| 扩展 | 插件系统存在但覆盖有限 | 80 余项内置功能以插件实现，全部可热重载 |\n| 嵌入 | 需启动独立 server 并通过 HTTP 连接 | 进程内 SDK，无需监听端口 |\n\n## 3. 核心特性\n\n### 3.1 常驻服务与多端客户端\n\n- 服务以单一后台进程运行。TUI、Web、桌面端连接同一进程，多个会话共享资源，社区反馈的主要收益是多会话下内存占用更低。\n- 会话与窗口解耦。关闭终端不会中断会话，可在其他客户端继续操作。\n- 图形界面内部称为 \"gooey\"。通过 `/pair` 在浏览器中打开，默认启用密码认证，可经 Tailscale 等方式远程访问，并支持作为 PWA 安装。\n- 已知问题包括服务启动等待、端口冲突，以及桌面端性能和完成度不及部分竞品。\n\n### 3.2 新 API\n\n- **单一契约。** 接口用 Effect `HttpApi` 和 Schema 定义一次，OpenAPI、Promise 客户端和 Effect 客户端均由此自动生成，CI 校验生成结果与契约一致。\n- **输入持久化。** 发送消息不再同步等待回复，而是写入会话收件箱后立即返回。调用方可选择插入当前执行（steer）或排队（queue）。客户端可指定消息 ID，重试具备幂等性。\n- **事件可续读。** 实时事件流在断线期间会丢失事件，另提供带序号的会话事件日志，客户端重连后可从断点补齐。这一机制对应官方确认采用的 event sourcing。\n- **资源模型完整。** 会话支持创建、分叉、迁移、导入导出与归档，并提供表单、权限、终端、MCP、凭据等资源接口。插件可通过 RPC 对外提供接口。\n- **类型化错误。** 定义 31 种错误类型，各对应固定 HTTP 状态码。\n- **服务发现与认证。** 客户端可自动发现并拉起本地服务。配对签发 30 天有效的会话令牌，修改服务密码即全部失效。\n- **自调用。** agent 可通过 API 管理自身会话与 worktree，例如新建 worktree 并将当前会话迁入。\n\n### 3.3 Code Mode\n\n- **机制。** 模型通过一个 `execute` 工具提交 JavaScript 脚本，在脚本中调用、组合工具，只有最终返回值进入上下文。\n- **适用范围。** 读写文件、shell、子代理等主力工具仍为直接调用。Code Mode 承载 MCP 工具（默认全部接入）、OpenCode 自身的会话与 worktree 工具，以及桌面端的浏览器控制工具。\n- **运行时。** 自研的 JavaScript 子集解释器，基于 Acorn 解析，未采用 QuickJS 或 V8 isolate。程序只能通过宿主授予的工具与 `fetch` 访问外部，不存在文件系统、进程或模块能力，所有跨边界数据均为拷贝。\n- **上下文控制。** 工具描述保持不变以利于 prompt cache。工具清单单独注入，预算约 2000 token，超出部分通过 `search()` 按需检索。工具集变化时只下发差异。\n- **可配置性。** 可按 MCP server 关闭 Code Mode，也可通过权限规则整体禁用。\n- **风险。** 当前未设置执行超时、调用次数与输出大小上限，也没有并发限制。部分失败需模型自行处理。工具检索仅支持 ASCII 关键词匹配。\n\n### 3.4 后台任务\n\n- 子代理和 shell 命令可在后台执行，完成后通知主 agent。子代理可指定不同模型。\n- 运行中的前台任务可通过 ctrl+b 转入后台。\n- 同类能力在 Claude Code 等工具中已有，OpenCode 2 的特点是与常驻服务结合，后台任务不依赖客户端存活。\n\n### 3.5 插件化与热重载\n\n- 内置 agent、集成、配置加载、system prompt 等 80 余项功能以内部插件实现，可单独禁用，插件 API 由官方自身持续使用。\n- 配置、MCP、插件的变更立即对所有会话生效，模型可在同一轮中编写并调用新工具，无需重启，也不破坏 prompt cache。实现方式是每类状态由一组可重放的变换构建，重载时从空状态重新执行。\n- TUI 插件已转为稳定，社区已出现 vim 模式、文件树、用量统计、目标模式等插件。\n- 这一方向与 deepseek-harness 的 \"Everything is a Plugin\" 一致。\n\n### 3.6 SDK 与 Effect API\n\n- `@opencode/sdk` 与 CLI 共用代码，在调用方进程内运行同一套 router，不监听端口、无网络开销。默认内存存储，可配置数据库实现重启恢复。\n- 支持按会话选择插件实例，例如为每个 Slack 线程加载不同插件。官方说明该机制不构成授权或存储隔离边界。\n- 提供 Workerd 入口，可运行于 Cloudflare Durable Object。\n- 同时提供 Promise 与 Effect 两种 API，端点一一对应：\n\n| | Promise 版 | Effect 版 |\n|---|---|---|\n| 依赖 | 无 Effect 依赖，基于 `fetch` | 依赖 Effect，HTTP 客户端可注入 |\n| 数据 | JSON 结构，不做运行时校验 | 领域类型，运行时 Schema 校验 |\n| 错误 | 以带标签的异常 reject | 体现在类型签名中 |\n| 适用 | 脚本、前端、轻量集成 | 已采用 Effect 的项目，需要类型化错误、中断与依赖注入 |\n\n官方选择 Effect 的理由有两点：规模扩大后稳定性问题集中暴露；AI 生成 Effect 代码的质量较高。\n\n## 4. 升级与迁移\n\n- 升级方式为先更新到最新 1.x，再执行 `opencode upgrade --major`。v1 与 v2 共用 `opencode` 命令，默认不能并存。\n- 破坏性变更共三项：插件 API 全新，v1 插件不可用；Server API 与客户端协议全新；`tui.json` 迁移为全局 `cli.json`（自动完成）。\n- 其余配置与 `.opencode/` 文件保持兼容。原生 v2 配置的主要变化是权限改为有序规则数组，并统一了若干字段命名。\n- 安全相关默认值有变化：v2 默认允许访问项目目录以外的路径，如需保持 v1 行为须显式配置。\n- 官方建议由 OpenCode 自身执行配置与插件迁移。\n\n## 5. 社区反馈\n\n**正面**\n- 单进程架构在多会话场景下资源占用明显更低。\n- 后台子代理与并行执行被普遍视为升级的主要理由。\n- Code Mode 缓解了大量 MCP 导致的上下文膨胀。\n- 多模型、多订阅用户认为其灵活性优于单一厂商工具。\n\n**负面**\n- 发布初期版本状态不清：GitHub Release 仍显示 1.x，更新频繁且版本说明不完整。\n- 插件迁移成本高，社区插件质量参差。\n- 界面层面存在并行操作难以追踪、标签页占用空间、桌面端偏慢等问题。\n- 会话间协同与整体打磨仍被认为不及 Claude Code。\n\n## 6. 评估\n\n**优势**\n- 以契约驱动的 API 与可嵌入 SDK 使其适合作为平台底座，第三方集成有稳定依据。\n- 持久化输入、幂等重试与可续读事件，针对的是 agent 长时运行和多端接入的实际问题。\n- Code Mode 与清单增量更新的组合，在工具规模与 prompt cache 之间取得了可行的平衡。\n- 插件化与热重载让定制成本显著下降，并支持 agent 自我扩展。\n\n**风险**\n- 146 个 API 操作中有 32 个处于实验阶段，事件日志、导入导出等关键能力尚未稳定。\n- Code Mode 缺少默认资源限制，复杂脚本也降低了操作的可审查性。\n- 生态迁移尚未完成，依赖 v1 插件或 API 的用户短期内需要投入改造。\n- 默认放开项目外路径访问，对安全敏感场景需要额外配置。\n\n## 参考资料\n\n**官方**\n- [OpenCode 2.0 发布博客](https://anoma.ly/notes/opencode-2-0/)\n- [热重载设计：OpenCode Reloaded](https://anoma.ly/notes/opencode-reloaded)\n- [v1 至 v2 迁移文档](https://opencode.ai/v2/docs/migrate-v1/)\n- [更新日志](https://opencode.ai/changelog)\n- [源码 v2.1.3](https://github.com/anomalyco/opencode/tree/v2.1.3)\n- [Cloudflare：Run OpenCode 2.0 on Cloudflare with the Agents SDK](https://developers.cloudflare.com/changelog/post/2026-10-12-opencode-harness/)\n\n**社区**\n- [@opencode 发布公告](https://x.com/opencode/status/2109649032931119362)\n- [@thdxr：2.0 可嵌入与 event sourcing](https://x.com/thdxr/status/2049523023145771476)\n- [@thdxr：几乎一切都是内部插件](https://x.com/thdxr/status/2087945880863191162)\n- [@thdxr：图形界面与 `/pair`](https://x.com/thdxr/status/2092247685524865257)\n- [@thdxr：内置 tool search 与 Code Mode](https://x.com/thdxr/status/2085865399195779308)\n- [r/opencode：Is OpenCode v2 quietly becoming the better harness than Claude Code?](https://www.reddit.com/r/opencode/comments/1x7iqzv/is_opencode_v2_quietly_becoming_the_better/)\n- [r/opencodeCLI：Opencode 2 stable?](https://www.reddit.com/r/opencodeCLI/comments/1xcgor3/opencode_2_stable/)\n","html":"","default_view":"markdown","version":3,"updated_by":"4e3fvwoonbfzbvqtdwehr2fzdp","updated_at":"2026-10-23T09:38:00Z","assets":[],"base_url":"/pub/lipmqfzj6gq3/p/"},"sources":[],"topic":{"id":"lipmqfzj6gq3","title":"OpenCode 2","question":"OpenCode 2 相比 v1 有哪些架构变化和亮点，社区怎么看？","visibility":"public","slug":"opencode2","hue":58,"emoji":"🧩","owner_id":"4e3fvwoonbfzbvqtdwehr2fzdp","created_at":"2026-10-23T09:37:54Z","updated_at":"2026-10-23T09:38:06Z","published_at":"2026-10-23T09:38:06Z","item_count":0,"report_words":923,"formats":["markdown"],"url":"https://research.sorrycc.dev/@sorrycc/opencode2"}}