opencode-vision-analyze 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MwumLi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# opencode-vision-analyze
+
+[![npm](https://img.shields.io/npm/v/opencode-vision-analyze)](https://www.npmjs.com/package/opencode-vision-analyze)
+[![license](https://img.shields.io/npm/l/opencode-vision-analyze)](./LICENSE)
+[![opencode plugin](https://img.shields.io/badge/opencode-plugin-blue)](https://opencode.ai/docs/plugins)
+
+A tool-based vision routing plugin for [opencode](https://opencode.ai): when the main model can't see images, it calls the `vision_analyze` tool on demand — your dedicated vision model describes the image and the description flows straight back into the conversation. When the main model already supports images, pasted images pass through untouched and the tool short-circuits to return raw pixels.
+
+**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:
+
+- **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.
+- **Native fast path.** If the main model is vision-capable, `vision_analyze` skips the vision model entirely and returns the raw image as a tool attachment.
+- **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)
+
+```jsonc
+// opencode.json (project or global)
+{
+  "plugin": [
+    ["opencode-vision-analyze", { "model": "openai/gpt-4o-mini" }]
+  ]
+}
+```
+
+opencode installs npm plugins automatically at startup.
+
+### Option B — curl single file (no npm)
+
+The plugin is a single self-contained TypeScript file with zero runtime dependencies — you can just download it:
+
+```bash
+mkdir -p .opencode
+curl -fsSL https://raw.githubusercontent.com/MwumLi/opencode-vision-analyze/main/src/index.ts \
+  -o .opencode/vision-analyze.ts
+```
+
+```jsonc
+// opencode.json
+{
+  "plugin": [
+    ["./.opencode/vision-analyze.ts", { "model": "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 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).
+
+### Options
+
+| 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 |
+
+## How it works
+
+```
+User pastes image + question
+ └─ chat.message hook (before persist)
+     ├─ main model has image input capability → do nothing (raw image goes to model)
+     └─ 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: ..."
+
+Main model processes:
+ ├─ vision-capable: sees the original image directly (zero cost)
+ └─ text-only: sees the hint, calls vision_analyze(image_path, question)
+
+vision_analyze tool:
+ ├─ native fast path: session's main model is vision-capable
+ │    → 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
+```
+
+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.
+- **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).
+
+## Known limitations
+
+- **V1 session flow only** — hooks are attached to the V1 `SessionPrompt` path; if opencode's default interaction moves to the V2 session core, hooks won't fire (silently).
+- **SSRF surface** — URL downloads follow redirects and don't block private-range / cloud-metadata addresses. Acceptable for a local single-user CLI; add address filtering before using in multi-tenant environments.
+- **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
+- [ ] Optional private-address blocking for URL downloads
+- [ ] Region cropping for zooming into image details
+
+## Development
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit
+bun test            # unit tests (stub client, no opencode needed)
+bun run build       # tsc → dist/
+```
+
+The unit tests stub the plugin input/client — no running opencode instance is required.
+
+## License
+
+[MIT](./LICENSE)

package/README.zh.md

@@ -0,0 +1,151 @@
+# opencode-vision-analyze
+
+[![npm](https://img.shields.io/npm/v/opencode-vision-analyze)](https://www.npmjs.com/package/opencode-vision-analyze)
+[![license](https://img.shields.io/npm/l/opencode-vision-analyze)](./LICENSE)
+[![opencode plugin](https://img.shields.io/badge/opencode-plugin-blue)](https://opencode.ai/docs/plugins)
+
+[English](./README.md) | 简体中文
+
+一个面向 [opencode](https://opencode.ai) 的工具化视觉路由插件：当主模型看不了图片时，由它按需调用 `vision_analyze` 工具——你指定的视觉模型描述图片，描述文字直接回到对话中。当主模型本身支持图片时，贴图原样直发，工具短路返回原图。
+
+**零运行时依赖。** 只用 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`——而不是提交时预生成的一次性通用描述。
+- **原生快速路径。** 主模型本身有视觉能力时，`vision_analyze` 完全跳过视觉模型，直接把原图作为工具附件返回。
+- **内容寻址缓存。** 图片按 `<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（推荐）
+
+```jsonc
+// opencode.json（项目级或全局）
+{
+  "plugin": [
+    ["opencode-vision-analyze", { "model": "openai/gpt-4o-mini" }]
+  ]
+}
+```
+
+opencode 启动时会自动安装 npm 插件。
+
+### 方式 B —— curl 单文件（免 npm）
+
+本插件是零运行时依赖的单文件 TypeScript 源码，直接下载即可使用：
+
+```bash
+mkdir -p .opencode
+curl -fsSL https://raw.githubusercontent.com/MwumLi/opencode-vision-analyze/main/src/index.ts \
+  -o .opencode/vision-analyze.ts
+```
+
+```jsonc
+// opencode.json
+{
+  "plugin": [
+    ["./.opencode/vision-analyze.ts", { "model": "openai/gpt-4o-mini" }]
+  ]
+}
+```
+
+curl 方式说明：
+
+- 建议固定到发布 tag 而非 `main`，如 `.../opencode-vision-analyze/v0.1.0/src/index.ts`；升级即重新 curl。
+- 文件是 TypeScript 源码——opencode 用 Bun 加载插件，直接可用。
+- 选项必须通过 `plugin` 元组传入（`.opencode/plugins/` 自动发现目录无法携带选项）。
+
+### 选项
+
+| 选项 | 必填 | 默认值 | 说明 |
+|---|---|---|---|
+| `model` | 是 | — | 视觉模型，`provider/model` 格式，如 `"anthropic/claude-sonnet-4-5"`、`"openai/gpt-4o-mini"` |
+| `timeout_ms` | 否 | `60000` | 视觉子会话请求超时（毫秒） |
+
+## 工作原理
+
+```
+用户贴图 + 提问
+ └─ chat.message 钩子（消息持久化前）
+     ├─ 主模型支持图片输入 → 不做任何处理（原图直发）
+     └─ 纯文本主模型 → 图片落盘 .opencode/vision/<sha256>.<ext>
+        并注入 synthetic 提示（TUI 隐藏、模型可见）：
+        "用 vision_analyze 工具查看，image_path: ..."
+
+主模型处理：
+ ├─ 有视觉：直接看原图（零成本）
+ └─ 无视觉：看到提示，调用 vision_analyze(image_path, question)
+
+vision_analyze 工具：
+ ├─ 原生快速路径：会话主模型有视觉能力
+ │    → 原图作为附件直接返回（不调视觉模型）
+ ├─ http(s) 图片 URL → 下载（20 MB 上限）→ 统一磁盘路径
+ ├─ 描述缓存命中（图片哈希 + 问题）→ 直接返回缓存文本
+ └─ 子会话：parentID 挂当前会话、禁用全部工具、专用 system
+     prompt，图片 + 问题发给你的视觉模型
+     → 返回描述文字 → 子会话立即删除
+```
+
+关键行为：
+
+- **能力门控** —— 查询 `config.providers()` 能力字段，进程级缓存；有视觉能力的主模型永远不会收到提示或被路由。
+- **递归防护** —— 视觉模型自己的消息（来自子会话）不会被再次处理。
+- **工具永不抛错** —— 所有失败都返回可读文字，agent 循环可以重试、换问题或告知用户。
+- **URL 图片** —— `image_path` 接受 `http(s)://...` 地址（需以受支持的图片扩展名结尾：png/jpg/jpeg/gif/webp）。
+
+## 已知限制
+
+- **仅 V1 会话流** —— 钩子挂在 V1 `SessionPrompt` 路径上；若 opencode 默认交互切到 V2 会话核心，钩子不会触发（且不报错）。
+- **SSRF 面** —— URL 下载跟随重定向、不拦截私网/云元数据地址。本地单用户 CLI 信任级别下可接受；多租户环境使用前应加地址过滤。
+- **中止不传导** —— 用户中止不会取消进行中的下载/子会话请求，它们会跑到各自的 deadline（下载 30 秒、子会话 `timeout_ms`）。超时/中止后子会话虽被删除，但 provider 端的孤儿回合仍可能计费。
+- **历史图片** —— 插件启用之前发送的图片无法被描述（无提示、磁盘上无路径）。
+- **缓存无上限** —— 图片存储与描述缓存均不淘汰（进程级 / 项目目录级）。
+- **单模型无备选链** —— 只有一个显式 `model` 选项；失败时返回错误文字，不会尝试其他 provider。
+
+## Roadmap
+
+- [ ] `model` 未显式指定时对首条消息的回退处理
+- [ ] 能力查询（`config.providers()`）加超时保护
+- [ ] 超时路径先中止子会话（`/session/{id}/abort`）再删除
+- [ ] 描述缓存 LRU / 容量上限
+- [ ] URL 下载可选私网地址拦截
+- [ ] 区域裁剪（放大查看图片细节）
+
+## 开发
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit
+bun test            # 单元测试（stub client，无需 opencode 实例）
+bun run build       # tsc → dist/
+```
+
+单元测试使用 stub 的插件输入/client——不需要运行中的 opencode。
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const _default: {
+    id: string;
+    server: Plugin;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,435 @@
+/**
+ * opencode-vision-analyze
+ *
+ * 为「不具备视觉能力的主模型」提供图片解读路由：当用户在消息中附带图片时，
+ * 插件把图片落盘到 .opencode/vision/<sha256>.<ext>，并向模型注入一条
+ * synthetic 提示（TUI 界面隐藏、模型可见），引导它通过 vision_analyze 工具
+ * 让指定的视觉模型描述图片。若主模型本身支持图片输入，则不做任何干预，
+ * 原图直接发给主模型。
+ *
+ * 安装方式一（npm）：
+ *   {
+ *     "plugin": [["opencode-vision-analyze", { "model": "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" }]]
+ *   }
+ *
+ * 选项：
+ *   - model（必填）：视觉模型的 "provider/model" 标识，例如 "anthropic/claude-sonnet-4-5"
+ *   - timeout_ms：子会话请求的超时毫秒数（正数，默认 60000）
+ *
+ * 工作方式（vision_analyze 工具路径）：主模型调用 vision_analyze 时，插件
+ * 创建一个 parentID 挂在当前会话下的临时子会话（不进会话列表、不生成
+ * 标题、禁用全部工具），把原图以 data URL 发给视觉模型，取回描述文字后
+ * 删除子会话并返回描述。同一张图 + 同一问题的描述按内容哈希缓存。
+ * image_path 除了绝对路径也接受 http(s) URL：先下载落盘到同一 vision
+ * 目录（内容哈希命名，天然与附件落盘去重），再走统一的磁盘加载路径。
+ * 主模型本身支持图片输入时走快速路径：不做子会话描述，直接把原图作为
+ * 工具附件回传给模型自行查看。
+ *
+ * 说明：本插件只用 node 内置模块（crypto/fs/path），无任何运行时外部依赖，
+ * 类型依赖仅 @opencode-ai/plugin 与 @opencode-ai/sdk 的 type import。
+ *
+ * 已知限制：
+ * - SSRF 面：downloadImage 的 fetch 跟随重定向、不拦截私网/云元数据地址。
+ *   本地单用户 CLI 的信任级别下可接受；生产多租户环境使用前应加私网
+ *   地址拦截。
+ * - 中止不传导：用户中止不会取消进行中的下载/子会话请求，最长空跑至
+ *   各自的 deadline（下载 30 秒、子会话 timeout_ms）；超时/中止后子会话
+ *   虽被删除，但 provider 端已发出的孤儿回合仍可能计入用量。
+ * - 仅 V1 会话流有效：chat.message 钩子挂在 V1 SessionPrompt 路径上；
+ *   若交互默认切到 V2 Session 核心，本钩子不会触发（也不会报错）。
+ */
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+/** 支持的图片扩展名 → MIME 类型（vision_analyze 加载磁盘图片时使用） */
+const EXT_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+/** MIME 类型 → 落盘使用的扩展名（与 EXT_MIME 互为反向映射） */
+const MIME_EXT = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+};
+/**
+ * 视觉子会话使用的系统提示词。
+ * 要求：精确转录图中文字，描述 UI/布局/对象/颜色等，优先回答用户问题，
+ * 不使用工具，纯文本回复。
+ */
+const VISION_SYSTEM_PROMPT = [
+    "You are an image analysis assistant.",
+    "Transcribe any text in the image exactly as it appears.",
+    "Describe the UI layout, objects, positions, and colors when present.",
+    "Answer the user's question first and foremost.",
+    "Do not use tools. Reply with plain text only.",
+].join("\n");
+/** data URL 形如 data:<mime>;base64,<payload> */
+const DATA_URL_PATTERN = /^data:([^;]+);base64,(.+)$/;
+/**
+ * http(s) 下载图片的大小上限（20 MB）。提示注入可让模型指向超大图片，
+ * 下载不限长是成本/健壮性放大器：先按 content-length 头提前拒绝，
+ * 读取后再按实际字节数复核（防御不带 content-length 的响应）。
+ */
+const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
+/**
+ * 插件服务端入口。
+ *
+ * @param input      opencode 插件运行环境（client / directory / project 等）
+ * @param optionsArg 插件配置，来自 opencode.json 中 plugin 数组的第二项
+ */
+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)}`);
+    }
+    const separator = model.indexOf("/");
+    const visionProviderID = model.slice(0, separator);
+    const visionModelID = model.slice(separator + 1);
+    // 子会话请求的超时时间：timeout_ms 为正数时生效，默认 60 秒。
+    const timeoutOption = optionsArg?.timeout_ms;
+    const timeoutMs = typeof timeoutOption === "number" && Number.isFinite(timeoutOption) && timeoutOption > 0 ? timeoutOption : 60000;
+    // ---- 闭包状态 ----------------------------------------------------------
+    /** sessionID → 该会话最近一次 prompt 的模型（prompt 未显式指定 model 时回退使用） */
+    const sessionModels = new Map();
+    /** "provider/model" → 是否具备图片输入能力（查询结果缓存，进程级） */
+    const imageCapable = new Map();
+    /** 描述缓存："<sha>:<question>" → 描述文本（同一张图 + 同一个问题只描述一次） */
+    const descriptions = new Map();
+    /** 本插件创建的子会话 ID 集合（正常路径用后即删，dispose 兜底清理残留） */
+    const subSessions = new Set();
+    /** 任意错误值 → 可读文本：Error 取 message，字符串原样，其余 JSON 序列化兜底。 */
+    const errText = (error) => {
+        if (error instanceof Error)
+            return error.message;
+        if (typeof error === "string")
+            return error;
+        return JSON.stringify(error) ?? String(error);
+    };
+    /**
+     * 给子会话请求加超时与 abort 保护：任一触发即让 Promise 以错误结束，
+     * 不再等待底层请求；finally 中清理 timer 与监听器，避免泄漏。
+     */
+    const withDeadline = (promise, ctx) => {
+        let timer;
+        let onAbort;
+        const guarded = new Promise((_, reject) => {
+            // ctx.abort 已中止时 abort 事件不会再触发，必须立即拒绝，
+            // 否则 race 只能干等 timer 超时。
+            if (ctx.abort.aborted) {
+                reject(new DOMException("Aborted", "AbortError"));
+                return;
+            }
+            timer = setTimeout(() => reject(new Error(`vision model call timed out after ${timeoutMs}ms`)), timeoutMs);
+            onAbort = () => reject(new DOMException("Aborted", "AbortError"));
+            ctx.abort.addEventListener("abort", onAbort, { once: true });
+        });
+        return Promise.race([promise, guarded]).finally(() => {
+            if (timer)
+                clearTimeout(timer);
+            if (onAbort)
+                ctx.abort.removeEventListener("abort", onAbort);
+        });
+    };
+    /**
+     * 创建临时子会话（parentID 挂在当前会话下，不进会话列表、不生成标题），
+     * 让视觉模型描述一张图片并返回描述文本。
+     * 任何失败（会话创建 / 请求 / 超时 / abort / 无文本）都返回 { ok: false, error }。
+     * 无论成败，finally 中都会删除子会话——用后即删，不留孤儿。
+     */
+    const describeImage = async (image, question, ctx) => {
+        const dataURL = `data:${image.mime};base64,${image.bytes.toString("base64")}`;
+        let subID;
+        try {
+            const created = await withDeadline(input.client.session.create({ body: { parentID: ctx.sessionID, title: "vision analysis" } }), ctx);
+            if (created.error || !created.data) {
+                return { ok: false, error: `session create failed: ${errText(created.error)}` };
+            }
+            subID = created.data.id;
+            subSessions.add(subID);
+            const response = await withDeadline(input.client.session.prompt({
+                path: { id: subID },
+                body: {
+                    model: { providerID: visionProviderID, modelID: visionModelID },
+                    agent: "build",
+                    // 子会话禁用全部工具：视觉模型只做纯文本描述，避免它反过来调用
+                    // vision_analyze 形成递归，也避免任何副作用。
+                    tools: { "*": false },
+                    system: VISION_SYSTEM_PROMPT,
+                    parts: [
+                        { type: "file", mime: image.mime, url: dataURL },
+                        { type: "text", text: question },
+                    ],
+                },
+            }), ctx);
+            if (response.error || !response.data) {
+                return { ok: false, error: errText(response.error) || "vision model prompt returned no data" };
+            }
+            const text = response.data.parts
+                .flatMap((part) => (part.type === "text" ? [part.text] : []))
+                .join("\n")
+                .trim();
+            if (!text)
+                return { ok: false, error: "vision model returned no text" };
+            return { ok: true, text };
+        }
+        finally {
+            if (subID) {
+                subSessions.delete(subID);
+                await input.client.session.delete({ path: { id: subID } }).catch(() => { });
+            }
+        }
+    };
+    /**
+     * 下载 http(s) URL 指向的图片并落盘到 <visionDir>/<sha256><ext>：
+     * 与 chat.message 落盘路径一致，内容哈希命名天然去重。
+     * 扩展名不受支持、HTTP 非 2xx、网络失败（含 30 秒下载超时）、超过
+     * 20 MB 下载上限（content-length 预检 + 读后复核）都返回 { error }，
+     * 由调用方转成可读的错误文字。
+     */
+    const downloadImage = async (url) => {
+        try {
+            // URL 解析与扩展名提取放在 try 内：畸形 URL 在 new URL 处抛错时，
+            // 错误以 "Image download failed" 前缀返回，而不是漏到外层的
+            // "Image analysis failed"。
+            const ext = path.extname(new URL(url).pathname).toLowerCase();
+            const mime = EXT_MIME[ext];
+            if (!mime)
+                return { error: `unsupported image URL extension: ${ext || "(none)"}` };
+            const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+            if (!response.ok)
+                return { error: `HTTP ${response.status}` };
+            // 头字段缺失时 Number(null) 为 NaN，比较结果为 false，自然放行到读后复核。
+            if (Number(response.headers.get("content-length")) > MAX_DOWNLOAD_BYTES) {
+                return { error: "image exceeds 20 MB download limit" };
+            }
+            const bytes = Buffer.from(await response.arrayBuffer());
+            // 复核实际字节数：chunked 等无 content-length 的响应只有读后才能判大小。
+            if (bytes.length > MAX_DOWNLOAD_BYTES) {
+                return { error: "image exceeds 20 MB download limit" };
+            }
+            const sha = createHash("sha256").update(bytes).digest("hex");
+            const dir = path.join(input.directory, ".opencode", "vision");
+            await fs.mkdir(dir, { recursive: true });
+            const filepath = path.join(dir, `${sha}${ext}`);
+            await fs.writeFile(filepath, bytes);
+            return { filepath };
+        }
+        catch (error) {
+            return { error: errText(error) };
+        }
+    };
+    /**
+     * 从磁盘加载图片：按扩展名识别 MIME，读取失败或文件为空返回 undefined。
+     */
+    const loadImage = async (filepath) => {
+        const mime = EXT_MIME[path.extname(filepath).toLowerCase()];
+        if (!mime)
+            return undefined;
+        try {
+            const bytes = await fs.readFile(filepath);
+            if (bytes.length === 0)
+                return undefined;
+            return { bytes, mime };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /**
+     * vision_analyze 工具：主模型传入图片路径与问题，返回视觉模型给出的描述。
+     * 工具永不抛错——所有失败都以错误文字返回，让 agent 循环可以读到原因并
+     * 自行决定下一步（重试、换问题或告知用户）。
+     */
+    const visionAnalyze = async (args, ctx) => {
+        const title = "vision_analyze";
+        try {
+            const question = args.question?.trim() || "Describe this image in full detail.";
+            // http(s) URL：先下载到本地 vision 目录，再统一走磁盘加载路径。
+            const download = /^https?:\/\//i.test(args.image_path) ? await downloadImage(args.image_path) : undefined;
+            if (download && "error" in download) {
+                return { title, output: `Image download failed: ${download.error}` };
+            }
+            const imagePath = download ? download.filepath : args.image_path;
+            const image = await loadImage(imagePath);
+            if (!image) {
+                return { title, output: `Image not found or unsupported: ${args.image_path}` };
+            }
+            // 快速路径：主模型本身具备视觉能力时，不再走子会话描述，直接把原图
+            // 作为附件回传给模型自行查看（省一次往返，模型看到的是原图而非转述）。
+            const current = sessionModels.get(ctx.sessionID);
+            if (current && (await imageSupport(current.providerID, current.modelID))) {
+                return {
+                    title,
+                    output: `[Image attached for direct inspection: ${path.basename(imagePath)}]`,
+                    attachments: [
+                        {
+                            type: "file",
+                            mime: image.mime,
+                            url: `data:${image.mime};base64,${image.bytes.toString("base64")}`,
+                        },
+                    ],
+                };
+            }
+            // 描述缓存：内容哈希 + 问题作为 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 (!result.ok)
+                return { title, output: `Image analysis failed: ${result.error}` };
+            descriptions.set(key, result.text);
+            return { title, output: format(result.text) };
+        }
+        catch (error) {
+            return { title, output: `Image analysis failed: ${errText(error)}` };
+        }
+    };
+    /**
+     * 查询某个模型是否支持图片输入。
+     * 通过 server 的 /config/providers 接口读取模型 capabilities.input.image，
+     * 结果按 "provider/model" 缓存；任何失败都静默返回 false（保守处理：
+     * 宁可多注入提示，也不让钩子抛错阻断消息持久化）。
+     */
+    const imageSupport = async (providerID, modelID) => {
+        const key = `${providerID}/${modelID}`;
+        const cached = imageCapable.get(key);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const result = await input.client.config.providers();
+            // HTTP 非 2xx 时 openapi-fetch 不抛错而是返回 { error }（data 为空）。
+            // 「查询失败」不能缓存成 false——那是一次瞬时故障而非「确认不支持」，
+            // 缓存会永久关闭能力门控；本次保守返回 false，下次再重试。
+            if (!result.data)
+                return false;
+            const provider = result.data.providers?.find((item) => item.id === providerID);
+            const capable = provider?.models?.[modelID]?.capabilities?.input?.image === true;
+            imageCapable.set(key, capable);
+            return capable;
+        }
+        catch {
+            return false;
+        }
+    };
+    /**
+     * 把一个图片 file part 落盘到 <directory>/.opencode/vision/<sha256>.<ext>。
+     * 文件名用内容哈希，天然去重（同一张图多次发送只落一份）。
+     * 返回落盘信息；MIME 不受支持或 URL 不是 base64 data URL 时返回 undefined。
+     */
+    const persistImage = async (part) => {
+        const ext = MIME_EXT[part.mime];
+        if (!ext)
+            return undefined;
+        const match = DATA_URL_PATTERN.exec(part.url);
+        if (!match)
+            return undefined;
+        try {
+            const bytes = Buffer.from(match[2], "base64");
+            const sha = createHash("sha256").update(bytes).digest("hex");
+            const dir = path.join(input.directory, ".opencode", "vision");
+            await fs.mkdir(dir, { recursive: true });
+            const filepath = path.join(dir, `${sha}${ext}`);
+            await fs.writeFile(filepath, bytes);
+            return { filepath };
+        }
+        catch {
+            // fail-open 原则：图片落盘失败（EACCES/ENOSPC 等）只是少了 vision_analyze
+            // 提示，不应让用户消息落库失败。返回 undefined，外层逐图跳过。
+            return undefined;
+        }
+    };
+    /**
+     * chat.message 钩子：用户消息持久化前触发（parts 数组与持久化同引用，
+     * push 进去的 part 会一并入库）。
+     *
+     * 职责：
+     * 1. 递归防护——视觉模型自身的消息（例如子会话）不做任何处理；
+     * 2. 记录会话当前模型；
+     * 3. 收集图片 part，没有图片则直接返回；
+     * 4. 能力门控——主模型本身能看图则不注入提示；
+     * 5. 图片落盘，并注入一条 synthetic text part 引导模型使用 vision_analyze。
+     */
+    const onChatMessage = async (hookInput, output) => {
+        // 记录会话当前模型，供后续 vision_analyze 快速路径与未显式指定 model 的
+        // prompt 回退判断。必须先于递归防护：会话模型恰好就是视觉模型时（用户
+        // 直接用视觉模型开会话），sessionModels 也要记录，否则快速路径门控永远
+        // 看不到该模型，会退化为子会话描述。
+        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;
+        // 能力门控：主模型有视觉能力时原图直发，不需要任何提示。
+        const current = hookInput.model ?? sessionModels.get(hookInput.sessionID);
+        if (current && (await imageSupport(current.providerID, current.modelID)))
+            return;
+        // 每张图落盘并生成两行提示；任何一张落盘失败就跳过该图（不影响其余图片）。
+        const lines = [];
+        for (const part of images) {
+            const persisted = await persistImage(part);
+            if (!persisted)
+                continue;
+            lines.push(`[The user attached an image: ${part.filename ?? "image"}]`);
+            lines.push(`[Examine it with the vision_analyze tool using image_path: ${persisted.filepath}]`);
+        }
+        if (lines.length === 0)
+            return;
+        // 注入 synthetic text part：TUI 隐藏（不干扰用户输入展示），但会发给模型。
+        // id 需满足 PartID 约定（prt 前缀）。
+        const hint = {
+            id: `prt_${randomUUID()}`,
+            sessionID: hookInput.sessionID,
+            messageID: hookInput.messageID ?? output.message.id,
+            type: "text",
+            synthetic: true,
+            text: lines.join("\n"),
+        };
+        output.parts.push(hint);
+    };
+    return {
+        "chat.message": onChatMessage,
+        // 工具注册。参数用 JSON-Schema 形式描述（image_path / question）。
+        // 类型签名上 args 是 zod RawShape，但注册表对非 zod 的参数值走
+        // JSON-Schema 兼容路径运行时处理；这里做一次受控的边界转换，
+        // 既不引入 zod 运行时依赖（本插件只用 node 内置模块），也不使用 any。
+        tool: {
+            vision_analyze: {
+                description: "Analyze an image with the dedicated vision model. image_path is an absolute file path (as given in the user's attachment hint) or an http(s) image URL. question describes what to look for; be specific.",
+                args: {
+                    image_path: { type: "string", description: "Absolute path to the image file, or an http(s) image URL." },
+                    question: { type: "string", description: "What to look for or answer about the image." },
+                },
+                execute: visionAnalyze,
+            },
+        },
+        // dispose：清理可能残留的子会话（正常路径用后即删，这里兜底异常路径），
+        // 删除失败静默忽略——插件卸载不应因清理失败而报错。
+        dispose: async () => {
+            for (const id of subSessions) {
+                await input.client.session.delete({ path: { id } }).catch(() => { });
+            }
+            subSessions.clear();
+        },
+    };
+};
+export default { id: "opencode-vision-analyze", server: plugin };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "opencode-vision-analyze",
+  "version": "0.1.0-beta.1",
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "bun test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "vision",
+    "vision-model",
+    "image",
+    "multimodal",
+    "plugin"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MwumLi/opencode-vision-analyze.git"
+  },
+  "homepage": "https://github.com/MwumLi/opencode-vision-analyze#readme",
+  "bugs": {
+    "url": "https://github.com/MwumLi/opencode-vision-analyze/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.16.2",
+    "@opencode-ai/sdk": "^1.16.2",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  }
+}