Skip to content

feat: 迁移到 OpenCode V2（v2.0.19） - #173

Open
AAEE86 wants to merge 4 commits into
lehhair:mainfrom
AAEE86:feat/opencode-v2-migration
Open

feat: 迁移到 OpenCode V2（v2.0.19）#173
AAEE86 wants to merge 4 commits into
lehhair:mainfrom
AAEE86:feat/opencode-v2-migration

Conversation

@AAEE86

@AAEE86 AAEE86 commented Sep 30, 2026

Copy link
Copy Markdown

概述

将 OpenCodeUI 从 OpenCode V1 完整迁移到 V2（验证基线 v2.0.19），不再兼容 V1。

覆盖：API 层、消息模型、事件流、功能补齐与裁撤、Docker/WSL 分发修复、Rust 侧修正。
规模：302 个文件，+27,907 / −27,700 行。

背景

OpenCode V2 做了大量不兼容变更：SDK 换包（@opencode-ai/sdk → @opencode/client）、端点全部迁到 /api 前缀、消息模型重构、事件体系重写、部分能力删除。旧前端连上 V2 的表现是「界面能打开、一发消息就失败」，且全程零报错，排查成本极高。

主要变更

  • 依赖：@opencode-ai/sdk → @opencode/client@2.0.19
  • API 层：端点全部迁移到 /api 前缀（对照 V2 权威 spec：115 路径 / 247 schema）；健康检查改用 GET /api/info + 响应体形状校验
  • 消息模型：V1 的 {info, parts} 两层结构 → V2 扁平联合 + 游标分页；新增 system / skill / shell / synthetic / idle 等 8 种消息类型
  • 事件流：重写 src/api/events.ts，45 个 V2 事件类型全覆盖
  • 功能补齐：中断（interrupt）、回退三段式（stage/commit/clear）、权限回复、Form 表单渲染器（六种字段类型）、PTY 两步连接、MCP + Integration
  • 功能裁撤：移除 V2 已删除能力的 UI（分享 / 归档 / 待办 / LSP / 格式化器 / 内容搜索 / 符号搜索）
  • 配置编辑器：降级为只读展示 + 仅 shell 可写 + 一键复制 JSON（V2 服务端只接受 shell，其他字段会被静默丢弃）
  • Docker：钉死 opencode v2.0.19 + 双架构 sha256 校验
  • WSL：安装按钮改用 opencode.ai/v2/install
  • Rust：修复 WSL filewatcher 环境变量静默失效；健康检查改 /api/info 并校验响应体
  • v1Model.ts 收敛：1492 → 920 行、104 → 42 个导出

最值得注意的几处「静默故障」修复

  1. session.idle / session.status 在 V2 从未下发（schema 已标 deprecated）→ 照旧实现会让界面永远停在「生成中」。已改用 session.execution.*。
  2. session.diff 语义变化：V2 是「按轮次」的，from 默认 = 最新一条 user 消息 → 旧映射会悄悄退化成「只显示最后一轮」。
  3. Docker / WSL 会静默装成 V1：GitHub releases 的 latest 已停在 v1.18.33，V2 的实际分发渠道是 opencode.ai/files/bin/…（Docker 已钉版本 + sha256；WSL 安装按钮已换）。
  4. WSL filewatcher 环境变量静默失效：OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER 在 V2 无任何读取处。

验证

项 结果
tsc 0 报错
prettier / eslint 全仓库通过 / 0 error
单测 958 passed / 0 failed（1002 用例 / 113 文件）
真实服务冒烟 44/44（5 个套件，跑在 v2.0.19 上）
cargo check 0 报错（含从零完整编译 692 crate）

已知未覆盖

  • Tauri 桌面版与 WSL 真机未验证（开发环境无对应运行时）——docs/opencode-v2-migration-regression-checklist.md 提供了四形态逐步回归清单（Docker / WSL / Tauri / 多服务器）。
  • Docker 镜像构建命令已更新，建议在真实 Docker 环境跑一次（清单 §1）。

文档

docs/ 下新增 9 份迁移记录（主计划 + 各阶段报告 + 回归清单，共 7,675 行），记录了每处变更的实测依据与决策原因。如不希望合并进仓库，可以只取代码部分。

BREAKING CHANGE: 不再支持 OpenCode V1，要求 v2.x（验证基线 v2.0.19）。

@AAEE86
feat: 迁移到 OpenCode V2（v2.0.19）
cdf7e7f 
将 OpenCodeUI 从 OpenCode V1 完整迁移到 V2，不再兼容 V1。

主要变更：
- 依赖：@opencode-ai/sdk → @opencode/client@2.0.19
- API 层：端点全部迁移到 /api 前缀（对照 V2 权威 spec 115 路径/247 schema）；
  健康检查改用 GET /api/info + 响应体形状校验
- 消息模型：V1 的 {info, parts} 两层结构 → V2 扁平联合 + 游标分页；
  新增 system/skill/shell/synthetic/idle 等 8 种消息类型
- 事件流：重写 src/api/events.ts，45 个 V2 事件类型全覆盖；
  修正 session.idle/session.status 从未下发等认知错误（改用 session.execution.*）
- 功能补齐：中断、回退三段式（stage/commit/clear）、权限回复、
  Form 表单渲染器（六种字段类型）、PTY 两步连接、MCP + Integration
- 功能裁撤：移除 V2 已删除能力的 UI（分享/归档/待办/LSP/格式化器/内容搜索/符号搜索）
- 配置编辑器：降级为只读展示 + 仅 shell 可写 + 一键复制 JSON
- Docker：钉死 opencode v2.0.19 + 双架构 sha256 校验
  （原 releases/latest 已停在 v1.18.33，会静默装成 V1）
- WSL：安装按钮改用 opencode.ai/v2/install（原脚本同样装成 V1）
- Rust：修复 WSL filewatcher 环境变量静默失效；健康检查改 /api/info 并校验响应体
- v1Model.ts 收敛：1492 → 920 行、104 → 42 个导出

验证：
- tsc 0 报错；prettier 全仓库通过；eslint 0 error
- 单测 958 passed / 0 failed（1002 用例 / 113 文件）
- 真实 v2.0.19 服务冒烟 44/44（5 个套件）
- cargo check 0 报错（含从零完整编译）

文档：docs/ 下新增 9 份迁移记录（主计划 + 各阶段报告 + 回归清单）。

BREAKING CHANGE: 不再支持 OpenCode V1，要求 v2.x（验证基线 v2.0.19）。
@AAEE86 AAEE86 mentioned this pull request Sep 30, 2026
Open
@AAEE86
fix(deploy): V2 反代修正 —— Caddy/nginx 不再削 /api 前缀 + 透传 Authorization
793d47d 
由真实部署（NAS + Caddy 反代）发现的配置遗漏：迁移时修了 vite 开发代理，
但生产反代配置仍是 V1 写法。

- V2 端点本身带 /api 前缀（/api/session、/api/info…）；削掉后会命中 SPA 兜底
  HTML（实测 200 + text/html），前端拿 HTML 当 JSON 解析 → 全链路坏
- docker/Caddyfile.standalone：handle_path → handle（原样透传）
- docker/Caddyfile.gateway：同上；并补 Authorization 透传（后端开启
  OPENCODE_SERVER_PASSWORD 时必需，否则所有 /api/* 会 401）
- docker/nginx.host.conf.example：proxy_pass 去尾斜杠（尾斜杠 = 削 /api/），
  /api/pty/ 同步修正
- README.md / README_EN.md：自定义 Caddyfile 示例同步更新
- docs/opencode-v2-migration.md：§10.5 补记该发现与修复

该问题单测与冒烟均无法发现（它们直连后端、不经过反代），由真实 Docker 部署暴露。
@AAEE86
fix: Docker 默认服务器 URL 的 V2 兼容（真实部署暴露的 401 根因）
281c37a 
Docker 构建注入 VITE_API_BASE_URL=/api 是 V1 语义（相对 base + 反代削 /api 前缀），
V2 下无法工作：
- 健康检查拼成 /api/api/info → 实测 401（界面显示「401」）
- SDK 用 new URL(baseUrl) 解析 → 相对地址直接抛 Invalid URL

修复：
- src/constants/api.ts：相对 base 一律解析为当前页面 origin
  （V2 端点自带 /api 前缀，不再需要反代/base 前缀）
- src/store/serverStore.ts：读取持久化服务器时，把历史遗留的相对地址
  就地升级为 origin（老用户无需手动删除重加）
- docker/Dockerfile.frontend：补注释说明 VITE_API_BASE_URL=/api 的 V2 语义
- docs/opencode-v2-migration.md：§10.5 补记该发现

另确认（本次未改）：内置 Local 服务器故意不可编辑（isDefault 隐藏编辑按钮），
带密码的后端请用「添加服务器」+「添加认证」（用户名固定 opencode）。

验证：tsc 0 报错；单测 958 passed / 0 failed（与基线一致）；prettier 通过。
@AAEE86
fix: 切换模型不生效 —— 发送前同步会话模型（V2 会话级模型）
c5f0bb4 
真实使用反馈：界面切换模型后回复仍来自默认模型。
根因：V2 的 prompt 不接受 model 参数（模型是会话级的），迁移时只把
所选模型写进消息 metadata 供显示、从未同步到会话（阶段 2b §7#6 缺口）。

- src/api/message.ts：发送前调用 session.switchModel（幂等：模型未变时
  服务端直接返回、不插记录；真正变化才留一条 model-switched 记录）
- SessionContext.createSession 支持传 model；useChatSession 建新会话时
  带上界面所选模型（避免新会话起在服务端默认模型上）
- 单测：同步先于 prompt / variant 透传 / 阻塞版同样同步
- 文档：主文档 §10.6、回归清单 1.5b、phase2b 与 phase4 修订指针

真实后端（v2.0.19）端到端实测：创建带模型 A → switchModel 切到 B →
发消息，assistant 消息 model 为 B；幂等重复切换与记录插入均验证。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@AAEE86