@wbline/pi-opencode-adapter0.1.1
Use OpenCode free models in pi coding agent — local bridge with live streaming, tool calls, and real-time retry status
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
pi-opencode-adapter
在 pi coding agent 中使用 OpenCode 的全部免费模型 —— ling-3.1-flash-free、nemotron-3-ultra-free、big-pickle、space-bunny-free 等 10+ 个，实时流式输出，支持工具调用。
| 流式输出 | thinking / 正文 / 工具调用逐字实时转发到 pi（TUI 与 ACP 均可） |
| 模型目录 | 后台从本地 opencode 服务实时刷新（启动时读本地快照，不阻塞启动），无写死清单，含上下文窗口、成本、thinking 档位 |
| 工具调用 | 通过文本契约桥接 pi 工具（<pi-tool> 行），模型自动完成调用 |
| 状态可见 | 上游限流重试实时显示在 thinking 区，不再黑盒等待 |
| 额度安全 | 中断/出错即中断 opencode 侧并删除临时会话，不浪费免费额度 |
为什么需要适配器
OpenCode 的免费层在服务端校验：直接请求 https://opencode.ai/zen/v1 会被 FreeTierError 拒绝（"免费层只能在 OpenCode 内使用"），除非携带由 opencode 进程签发的真实 session id——而它无法离线伪造。
本扩展把每个请求路由到本地运行的 opencode 服务，由它代为发起真正的模型调用（天然通过免费层校验），再把结果翻译回 pi：
pi ──渲染 transcript──▶ 本地 opencode 服务 ──真实调用──▶ 免费模型
◀──翻译回 pi 事件── (SSE: thinking/文本/工具调用/用量)
- pi 把自己的 transcript（系统提示、工具目录、对话）渲染成一段文本载荷，内嵌工具调用契约。
- 适配器在默认 agent 上新建一个临时 opencode 会话（自定义 agent 会被免费层校验拒绝），把载荷作为单条 prompt 发送。
- opencode 进程发出真正的模型调用；适配器把它的 SSE 流实时翻译回 pi 事件。
- 会话用完即删，不会在 opencode 界面里堆积。
环境要求
- pi ≥ 1.0
- OpenCode 桌面应用保持运行，或
opencode serve。凭据自动从~/.local/state/opencode/service.json发现。 - 服务未运行时会自动拉起无头服务（
opencode serve --service，detached 常驻）。
使用
pi --model opencode/ling-3.1-flash-free
pi --model opencode/big-pickle --thinking high
模型注册在 opencode provider 下，引用方式与 opencode 完全一致。这会替换 pi 内置的 zen 直连 opencode provider——它的免费模型在 pi 里本来就不可用。
- 模型目录在后台刷新时从本地服务实时获取（结果快照缓存到
~/.local/state/pi-opencode-adapter/），注册真实元数据：上下文窗口、输出上限、成本、输入类型（文本/图像；video/audio/pdf 不支持，自动忽略）。 - thinking 档位自动映射到模型的 variants（如
--thinking high→ 对应 variant），无 variants 的模型忽略该设置。 - 服务未运行时
opencodeprovider 下暂时没有模型，恢复后刷新即可。
随时用 /opencode-status 诊断：显示发现的后端地址、来源、可用模型目录。
配置项
| 环境变量 | 默认 | 说明 |
|---|---|---|
OPENCODE_SERVER_URL |
自动发现 | 手动指定本地服务地址 |
OPENCODE_SERVER_PASSWORD |
自动发现 | 手动指定服务密码 |
OPENCODE_AUTOSTART |
on |
off 禁止自动拉起无头服务 |
OPENCODE_BRIDGE |
on |
off 时本扩展不注册，保留内置 provider（用真实 OPENCODE_API_KEY 走付费模型） |
OPENCODE_BIN |
自动查找 | 指定 opencode CLI 路径（自动启动用） |
可靠性
- 限流可见：免费上游限流较严。重试期间桥接把实时状态（已提交、第 N 次重试、预计等待）写入 thinking 块，不再黑盒等待。
- 看门狗：流完全静默 120 秒（重试退避窗口豁免）视为僵死并中止；正常长生成因持续 delta 保持存活。
- 额度安全：中断 pi 回合时同步中断 opencode 侧并删除临时会话。
- 不重复：opencode 透明重试失败步骤时，适配器丢弃失败尝试的部分输出，回复永不重复。
- 可读的错误：限流、地区封锁、配额耗尽、免费层校验失败均以可操作的提示呈现。
已知限制
- 工具调用走文本契约，延迟略高于原生工具 API。
- 多数免费模型不支持图像输入；video/audio/pdf 不桥接。
- 免费上游对大上下文预填充较慢（10 万 token 级会话首 token 可能 20s+），等待期间会显示重试/等待状态。