dsh-opencode-go-models

Readme

# dsh-opencode-go-models

DSH 插件 – 同步 **OpenCode Go 套餐**的模型清单，并基于精确的家族配置标记多模态（图像/视频）支持。

> 🌏 语言 / Language：**中文** · [English](#english-version)

> ⚠️ **范围声明**：本插件仅覆盖 **OpenCode Go** 订阅套餐
> （端点 `https://opencode.ai/zen/go/v1`）。OpenCode Zen 另有**主套餐**
> （端点 `https://opencode.ai/zen/v1`），其模型清单、每 1M tokens 按量价格、
> 计费模式（按量付费 vs Go 的订阅制）和弃用节奏均与 Go 不同——本插件
> **不**处理 Zen 主套餐，请勿将本插件的模型/价格数据套用到 `/zen/v1`。

## 功能

- 拉取 `https://opencode.ai/zen/go/v1/models` 获取最新模型列表
- 与 pi-ai 安装 catalog（`data/opencode-go.json`）对比，计算新增/下线模型
- 新增模型直接写入 catalog JSON（dsh 运行时经 pi-ai 包装模块在加载时 import 该 JSON，重启即生效）：
  - **协议准确**：每个模型记录自带上 `api` 字段，按 opencode.ai 文档端点分配
    `anthropic-messages` / `openai-completions` / `openai-responses`，绝不强制统一协议
  - 容量/价格优先取内置模板表（文档定价表 + 同族容量），未知模型回退同族/家族配置
  - **精确区分多模态模型**：`input: ['text', 'image']` 仅授予官方确认的视觉模型
- 原子写入遵循官方 `@deepseek-ai/dsh-atomic-write`：`withFileLock` 跨进程写锁 +
  `writeFileAtomic`（排除性临时文件 + rename 原子提交），任何失败旧文件保持完好
- 注意：catalog 在 dsh **启动时**加载进内存，**同步后需重启 dsh** 才能看到新模型

## 安装与加载

### 从 npm 安装（推荐，已发布 `dsh-opencode-go-models`）

```bash
npx @deepseek-ai/dsh plugin --profile web add dsh-opencode-go-models
```

- 装完**重启 dsh** 生效（bundle 层变更）；发布包内含 `cordis.patch.yml`，
  `dsh.bundle` 声明随包生效，无需手工 patch
- 升级/指版本：`npx @deepseek-ai/dsh plugin --profile web add dsh-opencode-go-models@<版本>`
- 国内网络若等不到镜像同步，用官方源（同样经由 CLI，无需手工进目录）：

  ```bash
  npx @deepseek-ai/dsh plugin --profile web add dsh-opencode-go-models --registry=https://registry.npmjs.org
  ```

### 从源码安装（开发/贡献）

```bash
git clone <your-repo-url>
cd dsh-opencode-go-models
pnpm install   # 或 npm install
pnpm run build
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-opencode-go-models
```

### 对本机已有运行实例做热加载（开发模式）

本地安装后，编辑 `~/.dsh/profiles/web/cordis.patch.yml` 追加：

```yaml
- insert:
  - id: dsh-opencode-go-models
    name: 'dsh-opencode-go-models'
```

patch 层经 HMR 热生效，无需重启；但**模型列表**的同步结果仍需重启 dsh（catalog 启动时加载）。

## 使用

在 DSH 对话中：

- **同步模型**：`请帮我同步 opencode-go 的模型列表`
- **预览变更**：`请预览 opencode-go 模型同步的变更`
- **查询多模态支持**：`kimi-k3 支持图片输入吗？`
- **恢复原样**：`恢复 opencode-go 模型清单`（撤销插件对 catalog 的全部修改）

## 自动同步

插件**默认在加载时自动同步**，但受冷却窗口节制（默认 12 小时，可配置）：
冷却期内启动零网络、零写盘；超窗才拉取线上清单比对，**仅在确有差异时**
写入 catalog 并提示"重启后生效"。凭据缺失/网络失败只记日志跳过，不影响插件加载。

手动同步（`sync_opencode_models`）始终可用，与自动同步共享同一套原子写路径；
冷却期在自动检查与手动同步后都会刷新。

调整自动同步的 patch 配置示例：

```yaml
- insert:
  - id: dsh-opencode-go-models
    name: 'dsh-opencode-go-models'
    config:
      autoSync: true          # 默认 true；false 关闭自动同步
      autoSyncIntervalHours: 12   # 冷却窗口（小时）
```

## 卸载与恢复原样

官方文档（develop/basic）规定：通过 `ctx` 注册的监听/工具/定时器在插件卸载时会被
自动清理；需要手动管理的资源用 `ctx.effect()` 注册清理函数。本插件修改的是持久
文件（catalog），采用**备份 + 卸载恢复**方案：

- 插件**首次修改 catalog 前**把原文件整体备份到 `opencode-go.json.dsh-backup.json`
  （内容含 `original` 原文件与 `ours` 插件写入版本）
- **卸载时自动恢复**：dispose 时检查 profiles 目录是否仍有配置文件
  （`cordis.patch.yml` / `package.json`）引用本插件——patch 层被移除或依赖被删除
  （真卸载）→ 把备份整体写回；HMR 重载 / 普通关停 / 换 profile（仍被引用）→
  不恢复，避免每次重启丢失已同步模型
- **随时手动恢复**：`恢复 opencode-go 模型清单` → `reset_opencode_models` 工具
- **防护**：当前文件若已不含插件写入的模型 id（例如被 pi-ai 升级整体替换）→
  跳过恢复并清理备份，避免回退升级结果
- 语义说明（整体备份方案）：恢复会回退到"首次同步前"的完整文件——同步之后
  的手工改动会一并回退；需要只撤销插件改动时请在恢复前自行确认

## 已知限制

- **同步后需重启 dsh** 才能看到新模型（catalog 在启动时加载进内存）
- 升级 pi-ai 会覆盖其 `data/*.json`（含本插件写入的模型），升级后重新同步即可
- 未收录的未知新模型，其容量/价格/多模态等元数据取同族模型估值或保守默认值，请按厂商官方文档校准
- 文档未收录"模型 ID ↔ 端点协议"对照时按 `openai-completions` 兜底（`/v1` 端点原生 OpenAI 兼容）

---

## English Version

DSH plugin – syncs the model catalog of the **OpenCode Go plan** and flags multimodal (image/video) support based on accurate family configuration.

> ⚠️ **Scope**: This plugin covers **only** the **OpenCode Go** subscription plan
> (endpoint `https://opencode.ai/zen/go/v1`). OpenCode Zen also has a **main plan**
> (endpoint `https://opencode.ai/zen/v1`); its model list, per-1M-token usage prices,
> billing model (pay-as-you-go vs Go's subscription) and deprecation cadence all differ
> from Go's — this plugin does **not** handle the Zen main plan; do not apply this
> plugin's model/price data to `/zen/v1`.

## Features

- Fetches `https://opencode.ai/zen/go/v1/models` for the latest model list
- Diffs against the pi-ai install catalog (`data/opencode-go.json`) and reports added/removed models
- New models are written straight into the catalog JSON (dsh imports the JSON at load time through the pi-ai wrapper module — a restart applies it):
  - **Protocol-accurate**: each model record carries its own `api` field, assigned per the opencode.ai documented endpoints as
    `anthropic-messages` / `openai-completions` / `openai-responses` — never forced onto one uniform protocol
  - Capacity/price prefer the built-in template table (documented pricing table + same-family capacities); unknown models fall back to same-family/default configuration
  - **Precise multimodal marking**: `input: ['text', 'image']` is granted only to officially confirmed vision models
- Atomic writes follow the official `@deepseek-ai/dsh-atomic-write`: `withFileLock` cross-process write lock +
  `writeFileAtomic` (exclusive temp file + atomic rename commit); on any failure the old file stays intact
- Note: the catalog is loaded into memory at dsh **startup** — **restart dsh after syncing** to see the new models

## Installation

### Install from npm (recommended; `dsh-opencode-go-models` is published)

```bash
npx @deepseek-ai/dsh plugin --profile web add dsh-opencode-go-models
```

- **Restart dsh** after installing to take effect (bundle-layer change); the published package ships `cordis.patch.yml`,
  and the `dsh.bundle` declaration takes effect with the package — no manual patching needed
- Upgrade / pin a version: `npx @deepseek-ai/dsh plugin --profile web add dsh-opencode-go-models@<version>`
- If the mirror does not sync in time on a domestic network, use the official registry (still via the CLI, no need to go into the directory manually):

  ```bash
  npx @deepseek-ai/dsh plugin --profile web add dsh-opencode-go-models --registry=https://registry.npmjs.org
  ```

### Install from source (development / contribution)

```bash
git clone <your-repo-url>
cd dsh-opencode-go-models
pnpm install   # or npm install
pnpm run build
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-opencode-go-models
```

### Hot-reload an existing local instance (dev mode)

After a local install, append to `~/.dsh/profiles/web/cordis.patch.yml`:

```yaml
- insert:
  - id: dsh-opencode-go-models
    name: 'dsh-opencode-go-models'
```

The patch layer hot-applies via HMR — no restart needed; but the **synced model list** still requires a dsh restart (the catalog loads at startup).

## Usage

In a DSH conversation:

- **Sync models**: `请帮我同步 opencode-go 的模型列表`
- **Preview changes**: `请预览 opencode-go 模型同步的变更`
- **Query multimodal support**: `kimi-k3 支持图片输入吗？`
- **Restore everything**: `恢复 opencode-go 模型清单` (undoes all plugin modifications to the catalog)

## Auto-sync

The plugin **auto-syncs by default on load**, gated by a cooldown window (default 12 h, configurable):
within the cooldown, startup does zero network I/O and zero disk writes; only after the window does it
fetch the online list and diff — it writes to the catalog **only when there is an actual difference**
and then hints "restart to take effect". Missing credentials / network failures are merely logged and
skipped, without affecting plugin load.

Manual sync (`sync_opencode_models`) is always available and shares the same atomic-write path with
auto-sync; the cooldown refreshes after both the automatic check and a manual sync.

Example patch config to tune auto-sync:

```yaml
- insert:
  - id: dsh-opencode-go-models
    name: 'dsh-opencode-go-models'
    config:
      autoSync: true          # default true; false disables auto-sync
      autoSyncIntervalHours: 12   # cooldown window (hours)
```

## Uninstall & Restore

Per the official docs (develop/basic): listeners/tools/timers registered through `ctx` are cleaned up
automatically when the plugin unloads; resources managed manually should be registered with `ctx.effect()`.
This plugin modifies a persistent file (the catalog) and uses a **backup + restore-on-uninstall** scheme:

- **Before its first catalog modification**, the plugin backs up the original file whole to `opencode-go.json.dsh-backup.json`
  (containing `original` — the untouched file — and `ours` — the version the plugin wrote)
- **Restores automatically on uninstall**: on dispose it checks whether any config file in the profiles directory
  (`cordis.patch.yml` / `package.json`) still references this plugin — when the patch layer is removed or the
  dependency is deleted (a true uninstall) → the backup is written back whole; on HMR reload / normal shutdown /
  profile switch (still referenced) → no restore, so synced models are not lost on every restart
- **Manual restore anytime**: `恢复 opencode-go 模型清单` → `reset_opencode_models` tool
- **Guard**: if the current file no longer contains model IDs the plugin wrote (e.g. it was wholly replaced by a
  pi-ai upgrade) → skip restoring and clean up the backup instead, avoiding rolling back the upgrade
- Semantics (whole-file backup): restoring rolls back to the complete file from "before the first sync" — manual
  edits made after a sync are rolled back too; confirm yourself before restoring if you want to undo only the
  plugin's changes

## Known Limitations

- **Restart dsh after syncing** to see the new models (the catalog loads into memory at startup)
- Upgrading pi-ai overwrites its `data/*.json` (including the models this plugin wrote) — just resync after upgrading
- For unknown new models not in the templates, metadata (capacity/price/multimodal) is estimated from same-family models or conservative defaults — calibrate against the vendor's official docs
- When the docs do not include a "model ID ↔ endpoint protocol" mapping, fall back to `openai-completions` (the `/v1` endpoint is natively OpenAI-compatible)