opencode-vision-analyze 0.1.0-beta.1 → 0.2.0

package/README.md

@@ -8,22 +8,7 @@ A tool-based vision routing plugin for [opencode](https://opencode.ai): when the
 
 **Zero runtime dependencies.** Only node builtins (`crypto`/`fs`/`path`) and type-only imports — nothing to install beyond the plugin itself.
 
-## Why this one
-
-There are already a few vision plugins in the ecosystem. The differences:
-
-| | opencode-vision | opencode-vision-router | opencode-image-vision | **opencode-vision-analyze** |
-|---|---|---|---|---|
-| Mechanism | skill + subagent delegation | pointer + subagent delegation | direct SDK call (read-image / read-ocr) | **tool + plugin-managed sub-session** |
-| Vision model source | auto-discovered image models | single `model` option | per-feature provider/model | single `model` option |
-| Main-model capability detection | models.dev catalog + auth | `chat.params` live learning | name regex (fragile) | `config.providers()` capabilities (cached) |
-| Image persistence | /tmp (session+part hash) | tmpDir | user dir / clipboard dir | `.opencode/vision/` content-addressed sha256 |
-| Output | subagent answers itself | subagent answers itself | description / OCR text | description text (with cache) |
-| Vision-capable main model | skip registration | skip routing (`force` to override) | skipModels / forceDescription | skip injection + **native fast path** (tool returns the raw image as attachment) |
-| Request path | opencode session | opencode session | **direct third-party SDK** | opencode sub-session (unified auth, no extra credentials) |
-| Failure visibility | via subagent tool chain | via subagent | tool output | tool output (never throws) |
-
-Highlights:
+## Features
 
 - **Tool-based, not pre-analysis.** The turn starts immediately; the model decides when (and with which question) to look. No blocking on submit, failures are visible and retryable inside the agent loop. Same philosophy as production-proven agent designs.
 - **Question-aware descriptions.** The model passes its own focused question to `vision_analyze` — not a one-shot generic caption computed at submit time.
@@ -31,12 +16,6 @@ Highlights:
 - **Content-addressed cache.** Images are stored as `<sha256>.<ext>` (deduped across sessions); descriptions are cached per `<image-hash>:<question>` — the same image with the same question is described exactly once.
 - **Unified auth.** The vision call runs through an opencode sub-session, so it reuses the provider credentials opencode already manages. No extra API key plumbing.
 
-## Requirements
-
-- [opencode](https://opencode.ai) (plugins are loaded with Bun; npm plugins are installed automatically at startup)
-- a vision model you have access to, referenced as `provider/model` (e.g. `"openai/gpt-4o-mini"`, `"anthropic/claude-sonnet-4-5"`)
-- supported image extensions: png / jpg / jpeg / gif / webp
-
 ## Installation
 
 ### Option A — npm (recommended)
@@ -45,7 +24,7 @@ Highlights:
 // opencode.json (project or global)
 {
   "plugin": [
-    ["opencode-vision-analyze", { "model": "openai/gpt-4o-mini" }]
+    ["opencode-vision-analyze", { "models": ["openai/gpt-4o-mini"] }]
   ]
 }
 ```
@@ -66,14 +45,14 @@ curl -fsSL https://raw.githubusercontent.com/MwumLi/opencode-vision-analyze/main
 // opencode.json
 {
   "plugin": [
-    ["./.opencode/vision-analyze.ts", { "model": "openai/gpt-4o-mini" }]
+    ["./.opencode/vision-analyze.ts", { "models": ["openai/gpt-4o-mini"] }]
   ]
 }
 ```
 
 Notes for the curl path:
 
-- Pin a release tag instead of `main` for stability, e.g. `.../opencode-vision-analyze/v0.1.0/src/index.ts`. Upgrading = re-run curl.
+- The URL above points at the `main` branch (latest source); for a pinned release, swap `main` for a release tag (e.g. `v0.1.0`) and re-run curl.
 - The file is TypeScript source — opencode loads plugins with Bun, so this works as-is.
 - Options must be passed via the `plugin` tuple (the auto-discovered `.opencode/plugins/` directory can't carry options).
 
@@ -81,15 +60,40 @@ Notes for the curl path:
 
 | Option | Required | Default | Description |
 |---|---|---|---|
-| `model` | yes | — | Vision model in `provider/model` format, e.g. `"anthropic/claude-sonnet-4-5"`, `"openai/gpt-4o-mini"` |
-| `timeout_ms` | no | `60000` | Timeout (ms) for vision sub-session requests |
+| `models` | no | — | Ordered candidate list of vision models (`provider/model`), tried one after another until one succeeds. A single vision model is written as `models: ["..."]`. When omitted (or an empty array) the plugin auto-discovers all image-capable models. |
+| `unlisted_fallback` | no | `false` | When an explicit `models` chain is configured and it is exhausted, keep going with image-capable models that were not listed. |
+| `free_first` | no | `false` | In auto-discovery, prefer anonymous/built-in free providers (`custom` source) ahead of config-defined ones — reverses the source-tier order. |
+| `timeout_ms` | no | `60000` | Timeout (ms) budget for each individual `create`/`prompt` request inside the vision sub-session |
+
+Supported image extensions: png / jpg / jpeg / gif / webp.
+
+An ordered-candidates example with auto-fallback and free-first discovery:
+
+```jsonc
+// opencode.json
+{
+  "plugin": [
+    [
+      "opencode-vision-analyze",
+      {
+        "models": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o-mini"],
+        "unlisted_fallback": true,
+        "free_first": true
+      }
+    ]
+  ]
+}
+```
 
 ## How it works
 
 ```
 User pastes image + question
  └─ chat.message hook (before persist)
+     ├─ message model ∈ candidate chain → do nothing (recursion guard)
      ├─ main model has image input capability → do nothing (raw image goes to model)
+     ├─ no image-capable model available → do nothing (no hint, no persist;
+     │    core's default image handling applies)
      └─ text-only main model → persist image to .opencode/vision/<sha256>.<ext>
         and inject a synthetic hint (hidden in TUI, visible to model):
         "use the vision_analyze tool with image_path: ..."
@@ -103,15 +107,19 @@ vision_analyze tool:
  │    → return raw image as attachment (no vision model call)
  ├─ http(s) image URL → download (20 MB cap) → same disk path
  ├─ description cache hit (sha + question) → return cached text
- └─ sub-session: parentID under current session, all tools disabled,
-     dedicated system prompt, image + question sent to YOUR vision model
-     → description text returned → sub-session deleted immediately
+ │    (tagged with the model that produced it)
+ └─ candidate chain: sub-session under current session per candidate, in order —
+      parentID, all tools disabled, dedicated system prompt, image + question
+      sent to that vision model → first success returns → sub-session deleted
 ```
 
 Key behaviors:
 
 - **Capability gating** — queries `config.providers()` capabilities; results cached per process. A vision-capable main model never gets hints or routing.
-- **Recursion guard** — the vision model's own messages (from the sub-session) are never re-processed.
+- **Candidate chain** — the `models` list is tried in order until one succeeds. Explicit models always head the chain. With no explicit config (or an empty `models` list) the plugin auto-discovers every image-capable model, ordered by provider source (config first, then env/api, then custom/anonymous; reversed with `free_first: true`). With `unlisted_fallback: true`, an exhausted explicit chain continues onto unlisted image-capable models.
+- **Recursion guard (whole chain)** — messages from the candidate chain's own sub-sessions are never re-processed.
+- **Empty chain degradation** — if no vision model is available at all, the plugin still loads: pasted images are left untouched (no hint injected) and the tool returns a clear error instead of routing.
+- **Loginless free models** — auto-discovery uses `config.providers()`, the same source as the `/models` picker, so image-capable zen free models are found even without login (their provider is `custom` source → default last tier; put them first with `free_first: true`).
 - **The tool never throws** — every failure returns readable text so the agent loop can retry, rephrase, or inform the user.
 - **URL images** — `image_path` accepts `http(s)://...` URLs (must end in a supported image extension: png/jpg/jpeg/gif/webp).
 
@@ -122,11 +130,9 @@ Key behaviors:
 - **Abort doesn't propagate** — user aborts don't cancel in-flight downloads/sub-session requests; they run to their own deadlines (30s download, `timeout_ms` sub-session). After timeout/abort the sub-session is deleted, but the orphan turn may still be billed by the provider.
 - **Historical images** — images from messages sent before the plugin was enabled can't be described (no hint, no path on disk).
 - **Unbounded caches** — both the image store and description cache grow without eviction (per process / per project dir).
-- **Single model, no fallback chain** — one explicit `model` option; if it fails, the tool returns an error message instead of trying other providers.
 
 ## Roadmap
 
-- [ ] `model: undefined` fallback for first messages without an explicit model
 - [ ] Timeout wrapping for the capability query (`config.providers()`)
 - [ ] Abort sub-session (`/session/{id}/abort`) before delete on timeout
 - [ ] LRU / size cap for the description cache
@@ -144,6 +150,31 @@ bun run build       # tsc → dist/
 
 The unit tests stub the plugin input/client — no running opencode instance is required.
 
+## Release
+
+Versioning is driven entirely by `npm version` — no manual `package.json` edits. It updates the version, creates a commit and an annotated `v<version>` tag, and (via hooks) runs a local gate then pushes to trigger the GitHub release workflow that publishes to npm.
+
+```bash
+npm version patch                      # 0.1.x → 0.1.(x+1): commit + tag v0.1.x, auto-push → release
+npm version 1.2.0                      # explicit full version
+npm version prerelease --preid beta    # beta smoke: 0.1.1 → 0.1.2-beta.0
+```
+
+Hooks configured in `package.json`:
+
+- `preversion` — runs `typecheck && test && build` locally; if any fails the version is not bumped or tagged.
+- `postversion` — `git push --follow-tags`; pushes the commit and its tag, which triggers the GitHub Actions `release.yml` (`on.push.tags: ["v*"]`) that runs the checks again and `npm publish --access public` using the `NPM_TOKEN` secret.
+
+Beta smoke → stable flow:
+
+```bash
+npm version prerelease --preid beta   # publish a beta to npm
+# verify the beta on npm, then:
+npm version patch                      # drops the pre-release and bumps to the stable version
+```
+
+Escape hatches: `npm version 1.2.3 --no-git-tag-version` (only bump the file) or `--ignore-scripts` (skip all hooks). `npm version` requires a clean working tree. If the `postversion` push fails, run `git push --follow-tags` manually.
+
 ## License
 
 [MIT](./LICENSE)

package/README.zh.md

@@ -10,22 +10,7 @@
 
 **零运行时依赖。** 只用 node 内置模块（`crypto`/`fs`/`path`）和纯类型导入——除插件本身外无需安装任何东西。
 
-## 为什么选这个
-
-生态里已有若干视觉插件，差异如下：
-
-| | opencode-vision | opencode-vision-router | opencode-image-vision | **opencode-vision-analyze** |
-|---|---|---|---|---|
-| 机制 | skill + 子代理委托 | 指针 + 子代理委托 | 直连 SDK（read-image / read-ocr） | **工具 + 插件自管子会话** |
-| 视觉模型来源 | 自动发现的视觉模型 | 单一 `model` 选项 | 每功能独立 provider/model | 单一 `model` 选项 |
-| 主模型能力判定 | models.dev 目录 + auth | `chat.params` 实时学习 | 名字正则（脆弱） | `config.providers()` 能力查询（缓存） |
-| 图片落盘 | /tmp（会话+part 哈希） | tmpDir | 用户目录 / 剪贴板目录 | `.opencode/vision/` 内容寻址 sha256 |
-| 产出 | 子代理自行作答 | 子代理自行作答 | 描述 / OCR 文本 | 描述文本（带缓存） |
-| 有视觉主模型 | 跳过注册 | 跳过路由（`force` 可强制） | skipModels / forceDescription | 跳过注入 + **原生快速路径**（工具直接回传原图附件） |
-| 请求路径 | opencode 会话 | opencode 会话 | **第三方 SDK 直连** | opencode 子会话（统一鉴权，无需额外密钥） |
-| 失败可见性 | 经子代理工具链 | 经子代理 | 工具输出 | 工具输出（永不抛错） |
-
-亮点：
+## 特性
 
 - **工具化，而非提交时预分析。** 轮次即时启动；模型自己决定何时看图、带着什么问题看。提交零阻塞，失败在 agent 循环里可见、可重试。
 - **描述针对问题。** 模型把自己关注的问题传给 `vision_analyze`——而不是提交时预生成的一次性通用描述。
@@ -33,12 +18,6 @@
 - **内容寻址缓存。** 图片按 `<sha256>.<ext>` 落盘（跨会话天然去重）；描述按 `<图片哈希>:<问题>` 缓存——同图同问题只描述一次。
 - **统一鉴权。** 视觉调用走 opencode 子会话，复用 opencode 已管理的 provider 凭据，无需额外配置 API Key。
 
-## 运行前提
-
-- [opencode](https://opencode.ai)（插件由 Bun 加载；npm 插件启动时自动安装）
-- 一个你可用的视觉模型，以 `provider/model` 引用（如 `"openai/gpt-4o-mini"`、`"anthropic/claude-sonnet-4-5"`）
-- 受支持的图片扩展名：png / jpg / jpeg / gif / webp
-
 ## 安装
 
 ### 方式 A —— npm（推荐）
@@ -47,7 +26,7 @@
 // opencode.json（项目级或全局）
 {
   "plugin": [
-    ["opencode-vision-analyze", { "model": "openai/gpt-4o-mini" }]
+    ["opencode-vision-analyze", { "models": ["openai/gpt-4o-mini"] }]
   ]
 }
 ```
@@ -68,14 +47,14 @@ curl -fsSL https://raw.githubusercontent.com/MwumLi/opencode-vision-analyze/main
 // opencode.json
 {
   "plugin": [
-    ["./.opencode/vision-analyze.ts", { "model": "openai/gpt-4o-mini" }]
+    ["./.opencode/vision-analyze.ts", { "models": ["openai/gpt-4o-mini"] }]
   ]
 }
 ```
 
 curl 方式说明：
 
-- 建议固定到发布 tag 而非 `main`，如 `.../opencode-vision-analyze/v0.1.0/src/index.ts`；升级即重新 curl。
+- 上方 URL 指向 `main` 分支（最新源码）；如需固定版本，把 `main` 换成发布 tag（如 `v0.1.0`）再重新 curl。
 - 文件是 TypeScript 源码——opencode 用 Bun 加载插件，直接可用。
 - 选项必须通过 `plugin` 元组传入（`.opencode/plugins/` 自动发现目录无法携带选项）。
 
@@ -83,15 +62,40 @@ curl 方式说明：
 
 | 选项 | 必填 | 默认值 | 说明 |
 |---|---|---|---|
-| `model` | 是 | — | 视觉模型，`provider/model` 格式，如 `"anthropic/claude-sonnet-4-5"`、`"openai/gpt-4o-mini"` |
-| `timeout_ms` | 否 | `60000` | 视觉子会话请求超时（毫秒） |
+| `models` | 否 | — | 有序候选视觉模型数组（`provider/model`），逐个尝试直到成功即止；单个视觉模型写作 `models: ["..."]`。缺省或空数组时自动发现全部 image-capable 模型。 |
+| `unlisted_fallback` | 否 | `false` | 显式 `models` 链耗尽后，自动续试未列入清单的 image-capable 模型。 |
+| `free_first` | 否 | `false` | 自动发现时优先匿名/内置免费（`custom` 源）provider，置于 config 源之前——反转 source 档序。 |
+| `timeout_ms` | 否 | `60000` | 子会话内每次 create/prompt 请求各自的超时预算（毫秒） |
+
+受支持的图片扩展名：png / jpg / jpeg / gif / webp。
+
+有序候选 + 自动续接 + 免费优先的配置示例：
+
+```jsonc
+// opencode.json
+{
+  "plugin": [
+    [
+      "opencode-vision-analyze",
+      {
+        "models": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o-mini"],
+        "unlisted_fallback": true,
+        "free_first": true
+      }
+    ]
+  ]
+}
+```
 
 ## 工作原理
 
 ```
 用户贴图 + 提问
  └─ chat.message 钩子（消息持久化前）
+     ├─ 消息模型 ∈ 候选链 → 不做任何处理（递归防护）
      ├─ 主模型支持图片输入 → 不做任何处理（原图直发）
+     ├─ 无任何 image-capable 模型 → 不做处理（不注入 hint、不落盘；
+     │    交给核心对图片的默认处理）
      └─ 纯文本主模型 → 图片落盘 .opencode/vision/<sha256>.<ext>
         并注入 synthetic 提示（TUI 隐藏、模型可见）：
         "用 vision_analyze 工具查看，image_path: ..."
@@ -105,15 +109,19 @@ vision_analyze 工具：
  │    → 原图作为附件直接返回（不调视觉模型）
  ├─ http(s) 图片 URL → 下载（20 MB 上限）→ 统一磁盘路径
  ├─ 描述缓存命中（图片哈希 + 问题）→ 直接返回缓存文本
- └─ 子会话：parentID 挂当前会话、禁用全部工具、专用 system
-     prompt，图片 + 问题发给你的视觉模型
-     → 返回描述文字 → 子会话立即删除
+ │    （标签沿用产出该描述的模型）
+ └─ 候选链：沿链逐候选建子会话（parentID 挂当前会话、禁用全部工具、
+     专用 system prompt，图片 + 问题发给该候选视觉模型）
+     → 首个成功即返回 → 子会话删除
 ```
 
 关键行为：
 
 - **能力门控** —— 查询 `config.providers()` 能力字段，进程级缓存；有视觉能力的主模型永远不会收到提示或被路由。
-- **递归防护** —— 视觉模型自己的消息（来自子会话）不会被再次处理。
+- **候选链** —— `models` 列表按序逐个尝试直到成功。显式模型恒在链首；无显式配置（或 `models` 为空数组）时自动发现全部 image-capable 模型，按 provider 来源排序（config 最前 → env/api → custom/匿名；`free_first: true` 时反转）。`unlisted_fallback: true` 时显式链耗尽后会续试未列出的 image-capable 模型。
+- **递归防护（整链）** —— 候选链子会话发起的消息不会被再次处理。
+- **空链降级** —— 完全没有可用视觉模型时插件仍正常加载：贴图保持原样（不注入 hint），工具返回清晰错误而非路由。
+- **免登录免费模型** —— 自动发现与 `/models` 选择器同源（`config.providers()`），免登录也可发现的 zen free 视觉模型会进入候选链（其 provider 为 `custom` 源 → 默认最末档；`free_first: true` 可提到最前）。
 - **工具永不抛错** —— 所有失败都返回可读文字，agent 循环可以重试、换问题或告知用户。
 - **URL 图片** —— `image_path` 接受 `http(s)://...` 地址（需以受支持的图片扩展名结尾：png/jpg/jpeg/gif/webp）。
 
@@ -124,11 +132,9 @@ vision_analyze 工具：
 - **中止不传导** —— 用户中止不会取消进行中的下载/子会话请求，它们会跑到各自的 deadline（下载 30 秒、子会话 `timeout_ms`）。超时/中止后子会话虽被删除，但 provider 端的孤儿回合仍可能计费。
 - **历史图片** —— 插件启用之前发送的图片无法被描述（无提示、磁盘上无路径）。
 - **缓存无上限** —— 图片存储与描述缓存均不淘汰（进程级 / 项目目录级）。
-- **单模型无备选链** —— 只有一个显式 `model` 选项；失败时返回错误文字，不会尝试其他 provider。
 
 ## Roadmap
 
-- [ ] `model` 未显式指定时对首条消息的回退处理
 - [ ] 能力查询（`config.providers()`）加超时保护
 - [ ] 超时路径先中止子会话（`/session/{id}/abort`）再删除
 - [ ] 描述缓存 LRU / 容量上限
@@ -146,6 +152,31 @@ bun run build       # tsc → dist/
 
 单元测试使用 stub 的插件输入/client——不需要运行中的 opencode。
 
+## 发布
+
+版本变更完全由 `npm version` 驱动——无需手改 `package.json`。它会更新版本号、创建 commit 与 annotated `v<版本>` tag，并通过钩子先跑本地门禁再自动推送，触发 GitHub release workflow 发布到 npm。
+
+```bash
+npm version patch                      # 0.1.x → 0.1.(x+1)：commit + tag v0.1.x，自动推送 → 发布
+npm version 1.2.0                      # 显式指定完整版本
+npm version prerelease --preid beta    # beta 冒烟：0.1.1 → 0.1.2-beta.0
+```
+
+`package.json` 中配置的钩子：
+
+- `preversion` —— 本地执行 `typecheck && test && build`；任一失败则不 bump / 不打 tag。
+- `postversion` —— `git push --follow-tags`；推送 commit 及其 tag，触发 GitHub Actions `release.yml`（`on.push.tags: ["v*"]`），先复跑全部检查再用 `NPM_TOKEN` secret 执行 `npm publish --access public`。
+
+beta 冒烟 → 正式两段式：
+
+```bash
+npm version prerelease --preid beta   # 先发一个 beta 到 npm
+# 在 npm 上验证 beta 无误后：
+npm version patch                      # 去掉 pre 段并升到正式版本
+```
+
+逃逸舱：`npm version 1.2.3 --no-git-tag-version`（只改版本文件）或 `--ignore-scripts`（跳过全部钩子）。`npm version` 要求工作区干净；若 `postversion` 推送失败，手动执行 `git push --follow-tags`。
+
 ## 许可证
 
 [MIT](./LICENSE)

package/dist/index.js

@@ -9,19 +9,26 @@
  *
  * 安装方式一（npm）：
  *   {
- *     "plugin": [["opencode-vision-analyze", { "model": "provider/vision-model" }]]
+ *     "plugin": [["opencode-vision-analyze", { "models": ["provider/vision-model"] }]]
  *   }
  *
  * 安装方式二（curl 下载单文件，免 npm）：
  *   mkdir -p .opencode
  *   curl -fsSL <raw-url>/src/index.ts -o .opencode/vision-analyze.ts
  *   {
- *     "plugin": [["./.opencode/vision-analyze.ts", { "model": "provider/vision-model" }]]
+ *     "plugin": [["./.opencode/vision-analyze.ts", { "models": ["provider/vision-model"] }]]
  *   }
  *
  * 选项：
- *   - model（必填）：视觉模型的 "provider/model" 标识，例如 "anthropic/claude-sonnet-4-5"
- *   - timeout_ms：子会话请求的超时毫秒数（正数，默认 60000）
+ *   - models（可选，缺省/空数组 = 自动模式）：有序视觉候选数组，如
+ *     ["provider-a/m1", "provider-b/m2"]；单模型写 ["provider/model"] 即可
+ *   - unlisted_fallback（可选，默认 false）：显式候选耗尽后自动续接未列出的 image-capable 模型
+ *   - free_first（可选，默认 false）：自动发现档序反转（custom/匿名免费源优先，默认 config 优先）
+ *   - timeout_ms：单候选子会话请求的超时毫秒数（正数，默认 60000）
+ *
+ * 候选链语义：显式 models 恒在链首；缺省/空数组 → 自动发现全部 image-capable
+ * 模型并按 Provider.source 档序排列。链上候选逐个尝试，成功即止，全败聚合报错。
+ * 描述子会话的模型属于候选链，chat.message 递归防护以整链成员为集。
  *
  * 工作方式（vision_analyze 工具路径）：主模型调用 vision_analyze 时，插件
  * 创建一个 parentID 挂在当前会话下的临时子会话（不进会话列表、不生成
@@ -91,13 +98,35 @@ const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
  */
 const plugin = async (input, optionsArg) => {
     // ---- 选项解析与校验 ----------------------------------------------------
-    const model = optionsArg?.model;
-    if (typeof model !== "string" || !model.includes("/")) {
-        throw new Error(`opencode-vision-analyze requires a "model" option in "provider/model" format, got: ${JSON.stringify(model)}`);
+    // 归一化规则：models 是唯一显式入口 —— 有序候选数组（保序去重，重复只留首个）。
+    // 缺省或空数组 → explicit 为空（进入自动发现，见 resolveChain）。传了 models 但
+    // 类型不对（非字符串数组）直接抛错，避免用户配错被静默当成自动模式。
+    const modelsOption = optionsArg?.models;
+    if (optionsArg?.models !== undefined && !Array.isArray(modelsOption)) {
+        throw new Error('opencode-vision-analyze option "models" must be an array of "provider/model" strings');
     }
-    const separator = model.indexOf("/");
-    const visionProviderID = model.slice(0, separator);
-    const visionModelID = model.slice(separator + 1);
+    const hasModels = Array.isArray(modelsOption) && modelsOption.length > 0;
+    // 收集字符串候选并逐项校验 provider/model 格式（modelID 允许含 "/"，按首个 "/" 切分）。
+    // 逐项 throw：元素非法报 label "models[i]"；保序去重（重复只留首个）。
+    const raw = hasModels ? modelsOption : [];
+    const explicitModels = [];
+    const seenKeys = new Set();
+    raw.forEach((item, index) => {
+        const label = `models[${index}]`;
+        if (typeof item !== "string" || !item.includes("/")) {
+            throw new Error(`opencode-vision-analyze option "${label}" must be in "provider/model" format, got: ${JSON.stringify(item)}`);
+        }
+        const sep = item.indexOf("/");
+        if (seenKeys.has(item))
+            return; // 重复模型只保留首个
+        seenKeys.add(item);
+        explicitModels.push({ providerID: item.slice(0, sep), modelID: item.slice(sep + 1) });
+    });
+    // unlisted_fallback：显式链耗尽后是否自动续接未列出的 image-capable 模型（仅显式配置时
+    // 生效）。free_first：自动发现档序是否反转（匿名/内置 custom 优先，默认 config 优先）。
+    // 二者按严格布尔取真，非布尔值宽容忽略按 false 处理（与下方 timeout_ms 的宽容校验一致）。
+    const fallbackUnlisted = optionsArg?.unlisted_fallback === true;
+    const freeFirst = optionsArg?.free_first === true;
     // 子会话请求的超时时间：timeout_ms 为正数时生效，默认 60 秒。
     const timeoutOption = optionsArg?.timeout_ms;
     const timeoutMs = typeof timeoutOption === "number" && Number.isFinite(timeoutOption) && timeoutOption > 0 ? timeoutOption : 60000;
@@ -106,7 +135,11 @@ const plugin = async (input, optionsArg) => {
     const sessionModels = new Map();
     /** "provider/model" → 是否具备图片输入能力（查询结果缓存，进程级） */
     const imageCapable = new Map();
-    /** 描述缓存："<sha>:<question>" → 描述文本（同一张图 + 同一个问题只描述一次） */
+    /**
+     * 描述缓存："<sha>:<question>" → 描述结果（同一张图 + 同一个问题只描述一次）。
+     * 值带 modelId：记录实际产出该描述的候选模型，缓存命中时标签沿用入库模型，
+     * 而不是用当前候选链链首近似（链配置变化或 fallback 命中次选时标签才真实）。
+     */
     const descriptions = new Map();
     /** 本插件创建的子会话 ID 集合（正常路径用后即删，dispose 兜底清理残留） */
     const subSessions = new Set();
@@ -143,13 +176,16 @@ const plugin = async (input, optionsArg) => {
                 ctx.abort.removeEventListener("abort", onAbort);
         });
     };
+    /** 判断错误是否为中止信号（AbortError），供 attemptModel 标记 / 链循环中止整链。 */
+    const isAbortError = (error) => error instanceof Error && error.name === "AbortError";
     /**
-     * 创建临时子会话（parentID 挂在当前会话下，不进会话列表、不生成标题），
-     * 让视觉模型描述一张图片并返回描述文本。
-     * 任何失败（会话创建 / 请求 / 超时 / abort / 无文本）都返回 { ok: false, error }。
-     * 无论成败，finally 中都会删除子会话——用后即删，不留孤儿。
+     * 单个候选的尝试：创建子会话（parentID 挂当前会话）→ 用该候选模型描述 →
+     * 删除子会话。任何失败（创建 / 请求 / 超时 / 中止 / 底层抛错 / 无文本）都
+     * 收敛为 { ok: false } 返回而不向上抛——推进与否交给 describeWithChain 的
+     * 链循环决策；中止额外打 aborted 标记，链循环据此立即停整链。无论成败，
+     * finally 中都删除子会话——用后即删，不留孤儿。
      */
-    const describeImage = async (image, question, ctx) => {
+    const attemptModel = async (candidate, image, question, ctx) => {
         const dataURL = `data:${image.mime};base64,${image.bytes.toString("base64")}`;
         let subID;
         try {
@@ -162,7 +198,7 @@ const plugin = async (input, optionsArg) => {
             const response = await withDeadline(input.client.session.prompt({
                 path: { id: subID },
                 body: {
-                    model: { providerID: visionProviderID, modelID: visionModelID },
+                    model: { providerID: candidate.providerID, modelID: candidate.modelID },
                     agent: "build",
                     // 子会话禁用全部工具：视觉模型只做纯文本描述，避免它反过来调用
                     // vision_analyze 形成递归，也避免任何副作用。
@@ -185,6 +221,10 @@ const plugin = async (input, optionsArg) => {
                 return { ok: false, error: "vision model returned no text" };
             return { ok: true, text };
         }
+        catch (error) {
+            // 异常（超时 / 中止 / 底层抛错）同样收敛为失败结果；aborted 标记交由链循环判断
+            return { ok: false, error: errText(error), aborted: isAbortError(error) };
+        }
         finally {
             if (subID) {
                 subSessions.delete(subID);
@@ -192,6 +232,36 @@ const plugin = async (input, optionsArg) => {
             }
         }
     };
+    /**
+     * 候选链描述：沿 resolveChain() 产出的候选链逐个尝试，首个成功即返回（附带
+     * 成功候选的引用键作标签来源）；单个候选失败记录 `${key}: ${error}` 并推进
+     * 下一个；收到 abort（pre-abort 短路或尝试结果的 aborted 标记）立即中止整链；
+     * 全部失败聚合各候选原因；空链返回友好错误。本函数永不抛错。
+     */
+    const describeWithChain = async (image, question, ctx) => {
+        // pre-abort 短路：不解析候选链、不建子会话，直接以 Aborted 收尾
+        if (ctx.abort.aborted)
+            return { ok: false, error: "Aborted" };
+        const chain = await resolveChain();
+        const failures = [];
+        for (const candidate of chain) {
+            const attempt = await attemptModel(candidate, image, question, ctx);
+            if (attempt.ok)
+                return { ok: true, text: attempt.text, modelId: modelRefKey(candidate) };
+            if (attempt.aborted)
+                return { ok: false, error: attempt.error }; // abort 中止整链
+            failures.push(`${modelRefKey(candidate)}: ${attempt.error}`);
+        }
+        if (failures.length === 0) {
+            return {
+                ok: false,
+                error: "no image-capable model configured (set the plugin models option or configure an image-capable provider model)",
+            };
+        }
+        return { ok: false, error: `all ${failures.length} candidate model(s) failed: ${failures.join("; ")}` };
+    };
+    /** 描述标签：标注图片文件名与产出描述的模型引用键（basename 运行时按图传入）。 */
+    const format = (basename, modelId, text) => `[Image: ${basename} — described by ${modelId}]\n${text}`;
     /**
      * 下载 http(s) URL 指向的图片并落盘到 <visionDir>/<sha256><ext>：
      * 与 chat.message 落盘路径一致，内容哈希命名天然去重。
@@ -285,15 +355,19 @@ const plugin = async (input, optionsArg) => {
             }
             // 描述缓存：内容哈希 + 问题作为 key，命中直接复用（title 标注 cached）。
             const key = `${createHash("sha256").update(image.bytes).digest("hex")}:${question}`;
-            const format = (text) => `[Image: ${path.basename(imagePath)} — described by ${visionProviderID}/${visionModelID}]\n${text}`;
             const cached = descriptions.get(key);
-            if (cached !== undefined)
-                return { title: `${title} (cached)`, output: format(cached) };
-            const result = await describeImage(image, question, ctx);
+            if (cached !== undefined) {
+                // 命中时标签沿用入库时的模型（cached.modelId）：即便此刻候选链链首
+                // 已与入库模型不同，也保持标签真实、不重写。
+                return { title: `${title} (cached)`, output: format(path.basename(imagePath), cached.modelId, cached.text) };
+            }
+            const result = await describeWithChain(image, question, ctx);
             if (!result.ok)
                 return { title, output: `Image analysis failed: ${result.error}` };
-            descriptions.set(key, result.text);
-            return { title, output: format(result.text) };
+            // 入库带上实际产出描述的候选 modelId，供后续缓存命中还原真实标签
+            descriptions.set(key, { modelId: result.modelId, text: result.text });
+            // 成功标签直接用实际产出描述的候选引用键（而非链首近似）
+            return { title, output: format(path.basename(imagePath), result.modelId, result.text) };
         }
         catch (error) {
             return { title, output: `Image analysis failed: ${errText(error)}` };
@@ -326,6 +400,71 @@ const plugin = async (input, optionsArg) => {
             return false;
         }
     };
+    /** Provider.source → 自动发现档位：config 最优先，env/api 次之，custom 与未知值最末 */
+    const tierOfSource = (source) => source === "config" ? 0 : source === "env" || source === "api" ? 1 : 2;
+    /** "provider/model" 引用键（与 imageCapable 缓存的键格式一致） */
+    const modelRefKey = (c) => `${c.providerID}/${c.modelID}`;
+    // 候选链 memoize：chat.message 钩子与 vision_analyze 工具共享一次 providers 查询
+    let chainPromise;
+    /**
+     * 归一化产出最终候选链（统一数组，运行时只做逐个尝试）：
+     * - 显式非空：显式链恒在链首（不受 free_first/档序影响）；
+     *   unlisted_fallback=true 时再追加未列出的 image-capable 模型
+     * - 显式为空：整链 = 自动发现（全部 image-capable 模型，按 source 档序）
+     */
+    const resolveChain = () => {
+        chainPromise ??= (async () => {
+            // 自动模式：整链由自动发现决定
+            if (explicitModels.length === 0)
+                return listImageCapableModels();
+            // 显式模式：默认只用显式链；unlisted_fallback=true 时追加 inventory 中未列出的模型
+            if (!fallbackUnlisted)
+                return explicitModels;
+            const inventory = await listImageCapableModels();
+            const explicitSet = new Set(explicitModels.map(modelRefKey));
+            return [...explicitModels, ...inventory.filter((c) => !explicitSet.has(modelRefKey(c)))];
+        })();
+        return chainPromise;
+    };
+    /**
+     * 枚举 config.providers() 中全部 image-capable 模型，并按 Provider.source 档位
+     * 稳定排序（档内保持 providers 返回顺序）：默认 config > env/api > custom；
+     * free_first=true 时档序反转（custom 优先）。顺带预填 imageCapable 缓存
+     * （与 imageSupport 同源，避免后续重复请求）。providers 查询瞬时失败返回空数组
+     * 并记日志：显式链仍可用（fallback 追加部分静默跳过），自动模式退化为空链——
+     * 因 resolveChain 的 memoize，本次空链会持续整个进程（见 docs/superpowers/specs/2026-09-05-opencode-vision-analyze-design.md 已知限制）。
+     */
+    const listImageCapableModels = async () => {
+        try {
+            const result = await input.client.config.providers();
+            if (!result.data)
+                return [];
+            const found = [];
+            for (const provider of result.data.providers ?? []) {
+                const tier = tierOfSource(provider.source);
+                for (const [modelID, model] of Object.entries(provider.models ?? {})) {
+                    if (model?.capabilities?.input?.image !== true)
+                        continue;
+                    imageCapable.set(`${provider.id}/${modelID}`, true);
+                    found.push({ providerID: provider.id, modelID, tier });
+                }
+            }
+            // 稳定排序：默认按档位升序（config 优先）；free_first 反转成降序（custom 优先）
+            found.sort((a, b) => (freeFirst ? b.tier - a.tier : a.tier - b.tier));
+            return found.map(({ providerID, modelID }) => ({ providerID, modelID }));
+        }
+        catch (error) {
+            // 自动发现的关键 providers 查询失败要可观测：不静默吞掉，记一行日志便于定位。
+            // 显式链不受影响；自动模式按空链处理（本次进程内不再重试，见已知限制）。
+            console.error("[opencode-vision-analyze] config.providers() failed; auto vision discovery disabled", error);
+            return [];
+        }
+    };
+    /** 判断某 model 是否为当前候选链成员（chat.message 递归防护用） */
+    const isCandidateModel = async (model) => {
+        const chain = await resolveChain();
+        return chain.some((c) => c.providerID === model.providerID && c.modelID === model.modelID);
+    };
     /**
      * 把一个图片 file part 落盘到 <directory>/.opencode/vision/<sha256>.<ext>。
      * 文件名用内容哈希，天然去重（同一张图多次发送只落一份）。
@@ -358,11 +497,12 @@ const plugin = async (input, optionsArg) => {
      * push 进去的 part 会一并入库）。
      *
      * 职责：
-     * 1. 递归防护——视觉模型自身的消息（例如子会话）不做任何处理；
-     * 2. 记录会话当前模型；
-     * 3. 收集图片 part，没有图片则直接返回；
+     * 1. 记录会话当前模型（先于递归防护：会话模型恰为视觉模型时也需记录）；
+     * 2. 收集图片 part，没有图片则直接返回；
+     * 3. 递归防护——消息模型 ∈ 候选链全体成员（我们的描述子会话）则放行；
      * 4. 能力门控——主模型本身能看图则不注入提示；
-     * 5. 图片落盘，并注入一条 synthetic text part 引导模型使用 vision_analyze。
+     * 5. 空链降级——没有任何可用视觉模型时不注入 hint；
+     * 6. 图片落盘，并注入一条 synthetic text part 引导模型使用 vision_analyze。
      */
     const onChatMessage = async (hookInput, output) => {
         // 记录会话当前模型，供后续 vision_analyze 快速路径与未显式指定 model 的
@@ -371,18 +511,24 @@ const plugin = async (input, optionsArg) => {
         // 看不到该模型，会退化为子会话描述。
         if (hookInput.model)
             sessionModels.set(hookInput.sessionID, hookInput.model);
-        // 递归防护：视觉模型自身的 prompt（描述子会话）直接放行，
-        // 避免插件处理自己发起的消息造成循环。
-        if (hookInput.model?.providerID === visionProviderID && hookInput.model?.modelID === visionModelID)
-            return;
         // 只处理 base64 图片附件；没有图片就没有副作用。
         const images = output.parts.filter((part) => part.type === "file" && part.mime.startsWith("image/"));
         if (images.length === 0)
             return;
+        // 递归防护：防护集 = 整条候选链（而非单模型/链首）。描述子会话用的模型是
+        // 链上任意候选，只要消息模型命中任一成员就放行，避免插件处理自己发起的
+        // 消息形成循环。resolveChain 懒加载 + memoize，只在首次触发一次 providers 查询。
+        if (hookInput.model && (await isCandidateModel(hookInput.model)))
+            return;
         // 能力门控：主模型有视觉能力时原图直发，不需要任何提示。
         const current = hookInput.model ?? sessionModels.get(hookInput.sessionID);
         if (current && (await imageSupport(current.providerID, current.modelID)))
             return;
+        // 空链降级：没有任何可用视觉模型时不注入 hint、不落盘——落盘只会制造没有
+        // 视觉模型可消费的垃圾文件；交给核心 unsupportedParts 对图片 part 的默认处理。
+        const chain = await resolveChain();
+        if (chain.length === 0)
+            return;
         // 每张图落盘并生成两行提示；任何一张落盘失败就跳过该图（不影响其余图片）。
         const lines = [];
         for (const part of images) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-vision-analyze",
-  "version": "0.1.0-beta.1",
+  "version": "0.2.0",
   "description": "OpenCode plugin: vision_analyze tool — describe images & image URLs with your own vision model for text-only main models; native-image fast path for multimodal models. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,9 @@
     "typecheck": "tsc --noEmit",
     "build": "tsc",
     "test": "bun test",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "preversion": "bun run typecheck && bun test && bun run build",
+    "postversion": "git push --follow-tags"
   },
   "keywords": [
     "opencode",