model-manager

模型目录管理插件（OpenCode TUI）：停用/恢复/恢复出厂。

背景

OpenCode 的 /models 命令读取模型目录，新版目录存在 SQLite 数据库里：

• DB 文件：~/.local/share/opencode/opencode.db（WAL 模式）
• 表：kv
• key：models-dev:catalog
• value：JSON 字符串 {updatedAt, digest, body}，其中 body 本身又是嵌套 JSON 字符串：

  { providerID: { id, npm, api, models: { modelID: entry, ... }, ... }, ... }
  

/models 渲染的就是这份 catalog。要"停用某模型"（不在 /models 显示）或"恢复出厂"（还原所有被停用的模型），就得改这份 DB。

难点：OC 进程持有 SQLite 写锁

OC 的 main 进程常驻打开这个 DB（WAL 模式）。插件跑在 OC 内部（Bun 运行时），如果在插件进程里直接 better-sqlite3 写同一个文件，会撞上 OC 主进程的写锁 → SQLITE_BUSY / 死锁。

解法：插件不直接写 DB，而是走 outbox 队列 + fork 外部 Python 子进程 执行 DB 写：

1. 插件收到操作请求（CLI / 外部脚本触发）→ 写一行 JSON 到 ~/.config/opencode/model-manager.outbox.jsonl（outbox 队列）
2. 插件后台 daemon（setup 里 spawn，每 5s 轮询）发现新行 → fork python 子进程执行 model-manager-db-exec.py（OC setup 时自动落盘到 ~/.config/opencode/）
3. Python 子进程用 sqlite3 标准库（Python 对 WAL 模式无独占锁问题）读写 DB
4. 写完后调 POST http://127.0.0.1:4096/api/location/reload 让 OC 热重载目录
5. 结果回写到 outbox 的响应字段，daemon 记录日志

三种操作

操作	含义	实现
disable	停用某模型（不在 /models 显示）	在 body 的对应 provider.models 里把该 modelID 条目标记 disabled:true（或移出 models 字典，视 catalog schema）
enable	恢复某被停用的模型	清除 disabled 标记 / 恢复出厂 entry
reset	恢复出厂（全部模型还原）	用首次启用时自动拍的 ~/.config/opencode/model-manager.pristine.json 备份覆盖 DB catalog

触发方式

方式一：TUI 命令 /manage（推荐）

OC TUI 里输入 /manage（别名 /managent）打开模型管理面板，操作不直接改 DB，而是写 outbox 队列，由本插件 daemon 消费：

• 第一层：选 provider（顶置「恢复出厂」全局项）
• 第二层：对该 provider 选 停用 / 启用 / 恢复出厂
• 选中模型 → 选 停用 / 启用

命令注册在 tui-plugins/oc-session-all.js（model.manage 命令），写的是同一个 outbox 文件，daemon 统一消费。

方式二：外部脚本写 outbox

直接写一行 JSON 到 ~/.config/opencode/model-manager.outbox.jsonl：

{"op":"disable","payload":{"provider":"anthropic","modelID":"claude-opus-4.6"},"ts":1700000000}
{"op":"enable","payload":{"provider":"anthropic","modelID":"claude-opus-4.6"},"ts":1700000000}
{"op":"reset","payload":{"provider":"anthropic"},"ts":1700000000}

（daemon 5s 轮询，操作有最多 5s 延迟。）

日志

~/.config/opencode/model-manager.log

关键行：

• OUTBOX 收到 op=disable provider=anthropic model=claude-opus-4.6
• DB 写成功，digest 更新
• reload 200 热重载完成
• reset 已还原 pristine 备份
• pristine 备份已建立（首次启用时）

部署

端	路径
Windows 本机	~/.config/opencode/plugins/model-manager.ts
WSL	/root/.config/opencode/plugins/model-manager.ts

依赖：Python 3（用 sqlite3 标准库，无需 pip install）。

由 tools/sync_wsl.py 的 ITEMS 清单管理。

已知取舍

1. 不直接写 DB：OC 主进程持写锁，插件进程内直接 better-sqlite3 会 SQLITE_BUSY。outbox + fork Python 是绕开锁的可靠路径。
2. reset 依赖 pristine 备份：首次启用时自动拍 model-manager.pristine.json；若该文件被手动删了，reset 会失败（日志报 pristine not found），需重新拍一份。
3. 5s 轮询：daemon 每 5s 扫一次 outbox，操作有最多 5s 延迟。实为 fire-and-forget，不影响 OC 主流程。
4. 目录 reload 用 4096 端口：假设 OC serve 跑在默认端口；若用了 --port 自定义端口，reload 调用需带对端口（插件默认 4096，改 OPENCODE_PORT 环境变量可覆盖）。

文件

• model-manager.ts — 插件主文件（TypeScript）
• model-manager-db-exec.py — DB 写执行器（Python，OC setup 时自动落盘到 ~/.config/opencode/，本仓库也保留一份供 sync_wsl 同步）