OpenCode 1.19.0 开放升级到 OpenCode 2：插件与服务端 API 不兼容，自动更新改为手动

核心背景与行业痛点

OpenCode 是目前 Star 数最高的开源终端编码 Agent 之一（GitHub 约 21.2 万 Star）。OpenCode 2 的标签自 9 月 11 日起已迭代到 v2.0.26，但 1.x 用户一直缺少官方迁移入口。10 月 11 日的 v1.19.0 补上了这一步：opencode upgrade --major 或 TUI 中的 /update 可主动升级到 V2，同时不再自动安装更新。对把编码 Agent 跑在 CI、容器或团队统一环境里的人来说，静默自更新本身就是供应链风险，改为手动更有利于版本锁定。

架构亮点与底层机制

按官方迁移指南，V2 只有三处有意的破坏性变更：新插件 API（V1 插件实现无法运行）、新服务端 API 与客户端（改用 @opencode/client）、分层的 tui.json 合并为全局 ~/.config/opencode/cli.json（首次启动自动迁移）。配置层面，权限改为有序的 permissions 数组（bash 更名为 shell、task 更名为 subagent）；MCP 服务器移到 mcp.servers，超时拆成 catalog 与 execution；模型变体写成 provider/model#variant；带 subagent 的命令会在后台运行并把结果回报给父会话。V2 仍接受 lsp 配置，但不再运行语言服务器。

权威 Benchmark 与实测跑分对比

本次是平台与版本线升级，官方未发布任何性能或任务成功率跑分，本文不作推测。可核实的数字只有版本与时间：v2.0.0（9/11）到 v2.0.26（10/8），v1.19.0 于 10/11 发布。

开发者实战落地与开箱指南

1. 先备份 V1 配置；V1 与 V2 共用同一配置路径，转换成 V2 原生格式后不要再给 V1 使用。
2. 用包管理器装的 V1 先卸载，再执行 curl -fsSL https://opencode.ai/v2/install | bash 或 npm i -g @opencode/cli。
3. 现有 opencode.json、agents、commands、skills 可以直接沿用，重点核对模型凭据、权限和 MCP。
4. 有自研插件或调用服务端 API 的集成，必须按指南移植。依赖 LSP 诊断的流程改用 lint 或 typecheck 命令。
5. 官方建议直接让 OpenCode 自己把配置迁移到 V2 原生格式。