OpenCode V2 兼容性¶

验证基线¶

2026-08-26 兼容性基线是 OpenCode V2 提交 6c392355dd6c4f15889d28273c6e3dbf69c4548c 以及官方 V2 API 参考。 npm 注册表中验证到的最新已发布 V2 分支 CLI 是 @opencode-ai/cli@0.0.0-dev-18334， 它由同一次提交通过 发布运行 18334 发布。 其目录、生成和服务发现契约与 009eca8b5baa01b690753992725b450d045dd623 处的初始审计相比未发生变化。 本次记录包含源码审查和本地回归测试，包括使用 1 MB JSON 请求体进行带认证的回环生成、取消以及截止时间到期。 另有一个由提供方支持的生成测试通过，使用 CLI 0.0.0-dev-18334 和已在运行的服务器 0.0.0-dev-18329，期间未创建会话，也未重启服务。

这是一个带日期的验证快照，并非对当前可用的最新 CLI 的声明。下面的集成契约描述的是 Hex 当前实现；新的提供方支持验证必须记录各自的 CLI 和服务器版本。

集成契约¶

Hex 从不运行 OpenCode 可执行文件，从不启动或重启服务，也从不搜索或探测已安装的 CLI。它只与已在运行的服务通信（src/desktop/opencode_service.rs）：

• 它读取受限的注册文件 service.json（稳定版、beta 和 dev 渠道），然后读取其他渠道的 service-<channel>.json，位置在 $XDG_STATE_HOME/opencode，否则在 ~/.local/state/opencode；OpenCode 在 Windows 上也使用同一路径。在 macOS 和 Linux 上，该文件必须是用户拥有的常规文件，且不带有组权限或其他权限。
• 注册信息中的 url 必须是回环 http://（localhost、0.0.0.0 和 :: 均通过回环访问）；其他任何值一律拒绝。
• 使用注册信息中的密码（HTTP Basic，用户 opencode）发送 GET /api/info 时，必须返回已注册的 pid（以及已注册时的 version）。否则注册信息已过期，OpenCode 未在运行。
• 请求通过 TcpStream 使用 HTTP/1.1；content-length 和 chunked 响应会被解码并限制在 16 MiB 以内，每次等待都会遵守调用方的截止时间和取消请求。凭据永远不会进入诊断信息。

当没有服务应答时，功能会报告“OpenCode 未在运行”并链接到 OpenCode 文档；Hex 不会启动任何东西。

Hex 通过经认证的 HTTP 读取 /api/model 和 /api/model/default，避免大型管道式 CLI 响应。它为其中 Application Support 工作区提供 x-opencode-directory。模型选择使用目录中的 id，而不是上游提供方的 modelID。可用的文本输出模型不受发布状态限制仍可选择，包括 alpha 和 beta。为浮动默认项选择推理变体时，会将解析出的目录模型一并保存；已有的显式模型选择会被保留。

一次性生成接受一个 prompt 和可选模型引用，并返回 data.text。当前 OpenCode 在 /api/experimental/generate 提供该接口；仅当服务器对新路由返回 HTTP 404 时，Hex 才会在同一生成截止时间内回退到较旧的 /api/generate。它是无状态的，并使用服务器的基础配置，而不是目录请求中的目录头。已保存选择中目录 ID 与上游 ID 匹配的，无需迁移。之前损坏的别名选择可以通过重新选择模型来修复；Hex 不会猜测 ID 迁移。

更新基线¶

为隔离的发布验证运行固定一个确切的 CLI 版本和源码提交，然后在测试完上述契约、截止时间和取消之后，审慎地更新此基线。在 2026-08-26 审计时，v2 源码分支发布到了 npm 的 dev 标签；next 是较旧的 beta，而不是最新的 V2 构建。请解析已发布的版本，而不是假定某个移动标签指向所需源码提交。

记录所连接服务器的 /api/info 版本。不要为了执行兼容性验证而替换用户正在运行的服务。

保持对注册隐私、过期注册、仅回环准入、chunked 响应、截止时间和取消的回归覆盖。