# 发布（维护者文档）

## ⛔ 已废弃（Deprecated）

本仓库 / npm 包 `dsh-opencode-go-models` **自 pi-ai 1.x 起不再需要，已停止维护**。

**原因**：

1. **功能被上游取代**。pi-ai ≥ 1.0（实测 1.1.0）在发布时用自己的
   `scripts/generate-models.ts --strict` 生成 `dist/providers/data/opencode-go.json`，
   已覆盖当前全部有效 Go 模型（30 个），协议（anthropic-messages / openai-completions /
   openai-responses）、价格、多模态、thinking/compat 字段齐全。
2. **格式不兼容**。本插件的 catalog 假设是 `{ "<api>": { "<裸id>": {...} } }`，
   而 pi-ai 1.x 实际是 `{ "<api>": { "chat:<id>": {...} } }`。继续同步会判定“全部模型
   都是新增”，以裸 id 再写一份重复记录，污染 catalog。
3. **peer 范围过窄**。`package.json` 声明 `@earendil-works/pi-ai >=0.82.1 <0.89.0`，
   排除了实际安装的 1.x。
4. **元数据过时**。硬编码的 `PROTOCOL_MAP` / `RECORD_TEMPLATES` / `FAMILIES` 基于
   2026-08 文档：会把已下架模型（glm-5.1、minimax-m2.5、qwen3.6-plus 等）加回，会把
   `gemini-4-argon-contributor` 用默认 completions 协议写入（pi-ai 的 opencode-go
   provider 根本不接 Google 协议），并对 grok-4.6/4.7、gpt-6-luna、claude-haiku-5-5、
   qwen3.8-flash 等错路由。

**迁移**：直接升级 pi-ai（`dsh plugin update` 或依赖升级）即可获得准确、完整的 Go 模型清单。
若仍需“提前感知 opencode.ai 新增模型”，请改为只读对比提示（拉 `/v1/models` 与 catalog 的
裸 id 对比，仅提示升级，不写盘）。

> 消费方用户请直接参考 [README](README.md) 的使用部分；本文档面向本仓库维护者。

推送形如 `vX.Y.Z` 的 tag 即自动发布到 npm（工作流 `.github/workflows/publish.yml`：
标签版本校验 → `npm ci` → 构建 → 打包核查 → `npm publish`）：

```bash
npm version patch                      # 或 minor / major（自动改版本并打 tag）
git push && git push --tags            # 触发 GitHub Actions 发布
```

## 首次配置（一次性）

在 GitHub 仓库 **Settings → Secrets and variables → Actions** 添加 secret `NPM_TOKEN`：

- 到 https://www.npmjs.com/settings/<你的账号>/tokens 创建 **Granular Access Token**：
  Packages 选 `dsh-opencode-go-models`，权限 **Read and write**，**勾选 Bypass 2FA**
  （npmjs 发布强制 2FA，普通 token 会 403）
- 把 `npm_xxx` 填入 `NPM_TOKEN`

也可以用 `workflow_dispatch` 手动触发一次发布。

## 注意

- 搜索索引（`npm search` / npmjs.com 搜索）对新版本是异步收录，可能有小时级延迟；
  `npm view` / `npm install` 走 registry，即时可用
- 国内镜像（npmmirror）同步官方 registry 存在延迟，且镜像的 `latest` 标签可能滞后，
  `plugin update`/`add` 拉不到最新版时，在任意目录用 CLI 直连官方源：

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

- 若确需裸 `pnpm`（排查手段），才需要 `cd ~/.dsh/profiles/web`——CLI 已内置该目录，日常不需要

## 维护模型数据

新模型的元数据（wire 协议、显示名、input 模态、价格、容量）维护在两个文件：

- `src/families.ts`：`FAMILIES` 家族配置表——最长前缀匹配；`input: ['text', 'image']`
  标注多模态（影响 `check_model_supports_image` 判定）；修改后需 `npm run build`
- `src/sync.ts`：
  - `RECORD_TEMPLATES`：新增模型记录的唯一权威来源（基于 opencode.ai 官方文档
    端点/定价表；厂商文档更新后改这里）
  - `PROTOCOL_MAP`：文档确认的非 completions 模型（responses / anthropic-messages），
    其余默认 `openai-completions`
  - 未收录的未知模型回退到同族记录（`siblingOf`）或家族配置

修改后 `npm run build`，下次同步（自动或手动）即按新模板生成。