opencode-vision-analyze 0.4.0 → 0.5.0

package/README.md

@@ -13,9 +13,9 @@ A tool-based vision routing plugin for [opencode](https://opencode.ai): when the
 ## 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.
+- **Question-aware descriptions.** The model passes its own focused question to `vision_analyze` — not a one-shot generic caption computed at submit time. For a general parse of an image the model leaves `question` empty, and the tool falls back to a fixed prompt so all generic descriptions of the same image share one cache entry (see *Content-addressed cache*).
 - **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 content-addressed `<sha256>.<ext>` files in a **user-level shared directory** (`<cache>/opencode-vision-analyze/vision`, deduped across projects/sessions, LRU-capped 2000 entries / 500 MB); descriptions are cached per `<image-hash>:<question>` in a **user-level shared directory** (`<cache>/opencode-vision-analyze/descriptions`) — the same image with the same question is described exactly once, across projects, processes, and plugin restarts. The description cache is LRU-capped (2000 entries / 50 MB).
+- **Content-addressed cache.** Images and descriptions are stored by content hash in user-level shared dirs and reused across sessions, projects and restarts — the same image is never described twice, and all generic full-image parses collapse onto that image's single entry. Storage layout, size limits and the canonical prompt are detailed in *Storage and caches* below.
 - **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.
 
 ## Installation
@@ -69,10 +69,6 @@ Notes for the curl path:
 
 Supported image extensions: png / jpg / jpeg / gif / webp.
 
-Image storage: stored in a **user-level shared directory** `<cache>/opencode-vision-analyze/vision` regardless of git scope — one content-addressed `<sha256>.<ext>` file per unique image, shared across all projects. Pasted images and `http(s)` downloads are written here (atomic temp-file + rename, so concurrent opencode processes can safely share the store); **already-local image paths passed straight to the tool are read in place and never copied**. Defaults per platform: Linux `$XDG_CACHE_HOME || ~/.cache`, macOS `~/Library/Caches` (a `$XDG_CACHE_HOME` override is honored), Windows `%LOCALAPPDATA% || ~/AppData/Local`. An empty cache-root env var is treated as unset (falls back to the default). The store is LRU-capped (2000 entries / 500 MB; oldest by file mtime is evicted when either limit is exceeded), so no `.gitignore` entry is needed anywhere.
-
-Description cache: stored in a **user-level shared directory** `<cache>/opencode-vision-analyze/descriptions` regardless of git scope — one JSON entry per `<image-sha>:<question>` key, named by `sha256(key)`. It is capped at 2000 entries / 50 MB with LRU eviction (oldest by file mtime is removed when either limit is exceeded). Writes are atomic (temp file + rename), so concurrent opencode processes can safely share the cache.
-
 An ordered-candidates example with auto-fallback and free-first discovery:
 
 ```jsonc
@@ -91,6 +87,12 @@ An ordered-candidates example with auto-fallback and free-first discovery:
 }
 ```
 
+### Storage and caches
+
+Image storage: stored in a **user-level shared directory** `<cache>/opencode-vision-analyze/vision` regardless of git scope — one content-addressed `<sha256>.<ext>` file per unique image, shared across all projects. Pasted images and `http(s)` downloads are written here (atomic temp-file + rename, so concurrent opencode processes can safely share the store); **already-local image paths passed straight to the tool are read in place and never copied**. Defaults per platform: Linux `$XDG_CACHE_HOME || ~/.cache`, macOS `~/Library/Caches` (a `$XDG_CACHE_HOME` override is honored), Windows `%LOCALAPPDATA% || ~/AppData/Local`. An empty cache-root env var is treated as unset (falls back to the default). The store is LRU-capped (2000 entries / 500 MB; oldest by file mtime is evicted when either limit is exceeded), so no `.gitignore` entry is needed anywhere.
+
+Description cache: stored in a **user-level shared directory** `<cache>/opencode-vision-analyze/descriptions` regardless of git scope — one JSON entry per `<image-sha>:<effective-question>` key, named by `sha256(key)`. `question` is optional on the tool: a general full-image parse (empty or omitted) is normalised to the fixed prompt `Describe this image in full detail, including all text, UI elements, diagrams, or content visible.`, so every such request uses the key `<image-sha>:Describe this image in full detail, including all text, UI elements, diagrams, or content visible.` when its wording normalises to that prompt; specific follow-ups keep their own `<image-sha>:<question>` keys (format unchanged, existing entries keep hitting). Generic entries are only written when the description is long enough (≥ 100 chars), so a short refuse/fail answer can't poison the shared full-image entry. It is capped at 2000 entries / 50 MB with LRU eviction (oldest by file mtime is removed when either limit is exceeded). Writes are atomic (temp file + rename), so concurrent opencode processes can safely share the cache.
+
 ## How it works
 
 ```
@@ -114,9 +116,10 @@ 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
- │    (persisted under <cache>/opencode-vision-analyze/descriptions,
- │     tagged with the model that produced it, LRU-capped 2000 entries / 50 MB)
+ ├─ description cache hit (image sha + effective question) → return cached text
+ │    (general parses converge on <sha>:<canonical full-detail prompt>;
+ │     persisted under <cache>/opencode-vision-analyze/descriptions,
+ │     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
@@ -131,10 +134,7 @@ Key behaviors:
 - **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).
-
-## 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).
+- **General parses share one cache entry** — an empty or omitted `question` is treated as a full-image parse and reuses that image's cached description; specific follow-ups keep their own entries (details in *Storage and caches*).
 
 ## Roadmap
 

package/README.zh.md

@@ -13,9 +13,9 @@
 ## 特性
 
 - **工具化，而非提交时预分析。** 轮次即时启动；模型自己决定何时看图、带着什么问题看。提交零阻塞，失败在 agent 循环里可见、可重试。
-- **描述针对问题。** 模型把自己关注的问题传给 `vision_analyze`——而不是提交时预生成的一次性通用描述。
+- **描述针对问题。** 模型把自己关注的问题传给 `vision_analyze`——而不是提交时预生成的一次性通用描述。若只是让描述整张图，模型留空 `question`，工具用固定文案兜底，使同一张图的泛描述共享一条缓存（见"内容寻址缓存"）。
 - **原生快速路径。** 主模型本身有视觉能力时，`vision_analyze` 完全跳过视觉模型，直接把原图作为工具附件返回。
-- **内容寻址缓存。** 图片按内容寻址 `<sha256>.<ext>` 落盘到**用户级共享目录**（`<cache>/opencode-vision-analyze/vision`，跨项目/会话天然去重，LRU 上限 2000 条 / 500MB）；描述按 `<图片哈希>:<问题>` 缓存到**用户级共享目录**（`<cache>/opencode-vision-analyze/descriptions`）——跨项目/进程/插件重启同图同问题只描述一次；描述缓存 LRU 上限 2000 条 / 50MB。
+- **内容寻址缓存。** 图片与描述按内容哈希落到用户级共享目录，跨会话 / 项目 / 重启复用——同一张图不会重复付费描述；同一张图的所有泛解析请求都收敛到同一条缓存。存储路径、容量上限与固定文案详见下文「存储与缓存」。
 - **统一鉴权。** 视觉调用走 opencode 子会话，复用 opencode 已管理的 provider 凭据，无需额外配置 API Key。
 
 ## 安装
@@ -69,10 +69,6 @@ curl 方式说明：
 
 受支持的图片扩展名：png / jpg / jpeg / gif / webp。
 
-图片存储：**恒定放用户级共享目录** `<cache>/opencode-vision-analyze/vision`（与 git / 非 git 分域无关），同一用户所有项目共享；每个唯一图片一个内容寻址 `<sha256>.<ext>` 文件。贴图与 http(s) 下载写入于此（临时文件 + rename 原子写，多个 opencode 进程可安全共享）；**模型直接把本地已存在文件路径传给工具时不复制、原位读用**。各平台默认：Linux `$XDG_CACHE_HOME || ~/.cache`；macOS `~/Library/Caches`（亦接受 `$XDG_CACHE_HOME` 覆盖）；Windows `%LOCALAPPDATA% || ~/AppData/Local`。缓存根 env 为空串视为未设置（回退默认）。图片缓存 LRU 上限 2000 条 / 500MB，任一超限即按文件 mtime 淘汰最久未用的条目——无需任何 `.gitignore` 条目。
-
-描述缓存：**恒定放用户级共享目录** `<cache>/opencode-vision-analyze/descriptions`（与 git / 非 git 分域无关）——每条目一个 JSON 文件，key 为 `<图片sha256>:<问题>`、文件名取 `sha256(key)`。容量上限 2000 条 / 50MB，任一超限即按文件 mtime 淘汰最久未用的条目（LRU）。写入为原子操作（临时文件 + rename），多个 opencode 进程可安全共享同一描述缓存。
-
 有序候选 + 自动续接 + 免费优先的配置示例：
 
 ```jsonc
@@ -91,6 +87,12 @@ curl 方式说明：
 }
 ```
 
+### 存储与缓存
+
+图片存储：**恒定放用户级共享目录** `<cache>/opencode-vision-analyze/vision`（与 git / 非 git 分域无关），同一用户所有项目共享；每个唯一图片一个内容寻址 `<sha256>.<ext>` 文件。贴图与 http(s) 下载写入于此（临时文件 + rename 原子写，多个 opencode 进程可安全共享）；**模型直接把本地已存在文件路径传给工具时不复制、原位读用**。各平台默认：Linux `$XDG_CACHE_HOME || ~/.cache`；macOS `~/Library/Caches`（亦接受 `$XDG_CACHE_HOME` 覆盖）；Windows `%LOCALAPPDATA% || ~/AppData/Local`。缓存根 env 为空串视为未设置（回退默认）。图片缓存 LRU 上限 2000 条 / 500MB，任一超限即按文件 mtime 淘汰最久未用的条目——无需任何 `.gitignore` 条目。
+
+描述缓存：**恒定放用户级共享目录** `<cache>/opencode-vision-analyze/descriptions`（与 git / 非 git 分域无关）——每条目一个 JSON 文件，key 为 `<图片sha256>:<生效问题>`、文件名取 `sha256(key)`。`question` 参数可选：描述整张图的泛解析（空 / 省略）会归一化到固定文案 `Describe this image in full detail, including all text, UI elements, diagrams, or content visible.`，措辞与固定文案归一化等价时即落在 key `<图片sha>:Describe this image in full detail, including all text, UI elements, diagrams, or content visible.`；具体追问保留原问句走各自的 `<图片sha>:<问题>` key（格式与旧版一致，存量条目照常命中）。泛解析条目要求描述文本 ≥ 100 字符才写入，防止视觉模型敷衍/拒答的短文本毒化整图共享条目。容量上限 2000 条 / 50MB，任一超限即按文件 mtime 淘汰最久未用的条目（LRU）。写入为原子操作（临时文件 + rename），多个 opencode 进程可安全共享同一描述缓存。
+
 ## 工作原理
 
 ```
@@ -114,9 +116,10 @@ vision_analyze 工具：
  ├─ 原生快速路径：会话主模型有视觉能力
  │    → 原图作为附件直接返回（不调视觉模型）
  ├─ http(s) 图片 URL → 下载（20 MB 上限）→ 统一磁盘路径
- ├─ 描述缓存命中（图片哈希 + 问题）→ 直接返回缓存文本
- │    （持久化于 <cache>/opencode-vision-analyze/descriptions，
- │      标签沿用产出该描述的模型；LRU 上限 2000 条 / 50MB）
+ ├─ 描述缓存命中（图片哈希 + 生效问题）→ 直接返回缓存文本
+ │    （泛解析收敛到 <sha>:<固定整图描述文案>；
+ │      持久化于 <cache>/opencode-vision-analyze/descriptions，
+ │      标签沿用产出该描述的模型）
  └─ 候选链：沿链逐候选建子会话（parentID 挂当前会话、禁用全部工具、
      专用 system prompt，图片 + 问题发给该候选视觉模型）
      → 首个成功即返回 → 子会话删除
@@ -131,10 +134,7 @@ vision_analyze 工具：
 - **免登录免费模型** —— 自动发现与 `/models` 选择器同源（`config.providers()`），免登录也可发现的 zen free 视觉模型会进入候选链（其 provider 为 `custom` 源 → 默认最末档；`free_first: true` 可提到最前）。
 - **工具永不抛错** —— 所有失败都返回可读文字，agent 循环可以重试、换问题或告知用户。
 - **URL 图片** —— `image_path` 接受 `http(s)://...` 地址（需以受支持的图片扩展名结尾：png/jpg/jpeg/gif/webp）。
-
-## 已知限制
-
-- **仅 V1 会话流** —— 钩子挂在 V1 `SessionPrompt` 路径上；若 opencode 默认交互切到 V2 会话核心，钩子不会触发（且不报错）。
+- **泛解析共享同一条缓存** —— 空 / 省略的 `question` 视为整图描述，复用该图已缓存的描述；具体追问各自保留条目（细节见「存储与缓存」）。
 
 ## Roadmap
 

package/dist/index.d.ts

@@ -48,6 +48,37 @@ export declare const visionCacheLimits: {
     maxEntries: number;
     maxBytes: number;
 };
+/**
+ * 泛解析（描述整张图）用的固定问题文案。
+ *
+ * 主模型对「解析这张图 / 描述图片」这类请求应省略 question，由工具用这里的文案兜底，
+ * 从而让所有泛解析请求的缓存 key 收敛到同一条（key = <图片sha>:GENERIC_QUESTION），
+ * 避免主模型每次自编措辞把缓存拆成多份、跨会话永远命中不了。文案点名文字/UI/图表/
+ * 可见内容，驱动视觉模型把整图信息尽量带全。
+ *
+ * 这份文案相当于公开契约：改动它会让旧的泛解析缓存条目失去命中（由 LRU 按 mtime 清理），
+ * 属于刻意为之——将来想改泛描述措辞、或按用户/场景定制时，改文案即可自然分开新旧缓存。
+ */
+export declare const GENERIC_QUESTION = "Describe this image in full detail, including all text, UI elements, diagrams, or content visible.";
+/**
+ * 泛解析缓存条目的最短文本长度（字符）。
+ *
+ * canonical 描述要求整图加逐字转录，正常结果不可能太短；太短多半是视觉模型敷衍或拒答。
+ * 泛解析条目是全图共享的，存进一条垃圾描述会让之后所有泛解析都命中它，所以写入时长度
+ * 低于该值就跳过。具体追问不受限制（“答案是 42”是合法答案）。
+ * 做成模块级可变对象，测试注入大值/小值验证两侧行为。
+ */
+export declare const genericWriteMinText: {
+    chars: number;
+};
+/**
+ * 归一化问题文本，供「是否为泛解析」判定使用：
+ * 去掉首尾空白与引号/括号，把连续空白（含全角/换行）折成一个空格，去掉句末标点，统一小写。
+ * 只做字符级归一化，不做语义匹配——误判泛解析会把针对性回答套到错误语义上，宁可 miss。
+ */
+export declare function normalizeQuestion(q: string): string;
+/** 是否泛解析请求：没给问题（空/纯空白），或归一化后与 GENERIC_QUESTION 一致。 */
+export declare function isGenericQuestion(q: string): boolean;
 declare const _default: {
     id: string;
     server: Plugin;

package/dist/index.js

@@ -10,10 +10,14 @@
  * 工作方式（vision_analyze 工具路径）：主模型调用 vision_analyze 时，插件
  * 创建一个 parentID 挂在当前会话下的临时子会话（不进会话列表、不生成
  * 标题、禁用全部工具），把原图以 data URL 发给视觉模型，取回描述文字后
- * 删除子会话并返回描述。同一张图 + 同一问题的描述按「<图片sha256>:<问题>」
- * 键缓存到**用户级共享目录**（<cache>/opencode-vision-analyze/descriptions，
- * 每条目一文件、mtime 作 LRU 时钟、2000 条 / 50MB 双上限、单条超限不入缓存）——
- * 跨项目/跨进程/插件重启后同图同问题只描述一次。
+ * 删除子会话并返回描述。描述按「<图片sha256>:<问题>」键缓存到**用户级共享目录**
+ * （<cache>/opencode-vision-analyze/descriptions，每条目一文件、mtime 作 LRU
+ * 时钟、2000 条 / 50MB 双上限、单条超限不入缓存）——跨项目/跨进程/插件重启后
+ * 同图同问题只描述一次。
+ * 泛解析（描述整图）请求的 question 会归一化到固定文案 GENERIC_QUESTION
+ * （主模型省略 question 即走该默认值），key 收敛为 <图片sha>:GENERIC_QUESTION，
+ * 避免主模型每次自编措辞把缓存拆碎；有具体追问时保留原问句走各自精确 key。
+ * 泛解析条目是全图共享的，写入前按最短文本长度把关，防一条垃圾描述毒化整图。
  * image_path 除了绝对路径也接受 http(s) URL：先下载落盘到同一用户级 vision
  * 目录（内容哈希命名，天然与附件落盘去重；LRU + 容量上限，2000 条 / 500MB），
  * 再走统一的磁盘加载路径。**本地已存在的文件直接原位读取**（不复制、不 touch），
@@ -130,6 +134,45 @@ export const visionCacheLimits = {
     maxEntries: 2000,
     maxBytes: 500 * 1024 * 1024,
 };
+/**
+ * 泛解析（描述整张图）用的固定问题文案。
+ *
+ * 主模型对「解析这张图 / 描述图片」这类请求应省略 question，由工具用这里的文案兜底，
+ * 从而让所有泛解析请求的缓存 key 收敛到同一条（key = <图片sha>:GENERIC_QUESTION），
+ * 避免主模型每次自编措辞把缓存拆成多份、跨会话永远命中不了。文案点名文字/UI/图表/
+ * 可见内容，驱动视觉模型把整图信息尽量带全。
+ *
+ * 这份文案相当于公开契约：改动它会让旧的泛解析缓存条目失去命中（由 LRU 按 mtime 清理），
+ * 属于刻意为之——将来想改泛描述措辞、或按用户/场景定制时，改文案即可自然分开新旧缓存。
+ */
+export const GENERIC_QUESTION = "Describe this image in full detail, including all text, UI elements, diagrams, or content visible.";
+/**
+ * 泛解析缓存条目的最短文本长度（字符）。
+ *
+ * canonical 描述要求整图加逐字转录，正常结果不可能太短；太短多半是视觉模型敷衍或拒答。
+ * 泛解析条目是全图共享的，存进一条垃圾描述会让之后所有泛解析都命中它，所以写入时长度
+ * 低于该值就跳过。具体追问不受限制（“答案是 42”是合法答案）。
+ * 做成模块级可变对象，测试注入大值/小值验证两侧行为。
+ */
+export const genericWriteMinText = { chars: 100 };
+/**
+ * 归一化问题文本，供「是否为泛解析」判定使用：
+ * 去掉首尾空白与引号/括号，把连续空白（含全角/换行）折成一个空格，去掉句末标点，统一小写。
+ * 只做字符级归一化，不做语义匹配——误判泛解析会把针对性回答套到错误语义上，宁可 miss。
+ */
+export function normalizeQuestion(q) {
+    return q
+        .trim()
+        .replace(/^[\s"'“”「」『』()（）\[\]]+|[\s"'“”「」『』()（）\[\]]+$/g, "")
+        .replace(/[\s]+/g, " ")
+        .replace(/[.。!！?？]+$/g, "")
+        .toLowerCase();
+}
+/** 是否泛解析请求：没给问题（空/纯空白），或归一化后与 GENERIC_QUESTION 一致。 */
+export function isGenericQuestion(q) {
+    const s = (q ?? "").trim();
+    return s === "" || normalizeQuestion(s) === normalizeQuestion(GENERIC_QUESTION);
+}
 /**
  * http(s) 下载图片的大小上限（20 MB）。提示注入可让模型指向超大图片，
  * 下载不限长是成本/健壮性放大器：先按 content-length 头提前拒绝，
@@ -533,7 +576,13 @@ const plugin = async (input, optionsArg) => {
     const visionAnalyze = async (args, ctx) => {
         const title = "vision_analyze";
         try {
-            const question = args.question?.trim() || "Describe this image in full detail.";
+            // 泛解析判定：没给问题（空/纯空白），或措辞与 GENERIC_QUESTION 归一化一致。
+            // 泛解析请求统一改写为 GENERIC_QUESTION——缓存 key 固定成 <图片sha>:GENERIC_QUESTION，
+            // 跨会话、跨措辞都能命中；主模型若问的是具体对象/文字/区域/颜色，则保留原问句，
+            // 走各自的精确 key（与旧版本格式一致，存量条目不受影响）。
+            const trimmed = args.question?.trim() ?? "";
+            const generic = trimmed === "" || isGenericQuestion(trimmed);
+            const question = generic ? GENERIC_QUESTION : trimmed;
             // http(s) URL：先下载到用户级 vision 缓存目录，再统一走磁盘加载路径。
             // ctx.abort 传入下载：用户中止即刻断下载（含 pre-abort 不再发请求）。
             const download = /^https?:\/\//i.test(args.image_path)
@@ -563,7 +612,7 @@ const plugin = async (input, optionsArg) => {
                     ],
                 };
             }
-            // 描述缓存：内容哈希 + 问题作为 key，命中直接复用（title 标注 cached）。
+            // 描述缓存：内容哈希 + 生效问题作为 key，命中直接复用（title 标注 cached）。
             // 落盘在用户级共享目录（resolveDescriptionDir）——跨项目/进程/重启命中；磁盘即事实。
             const key = `${createHash("sha256").update(image.bytes).digest("hex")}:${question}`;
             const cached = await descCacheGet(key);
@@ -575,6 +624,12 @@ const plugin = async (input, optionsArg) => {
             const result = await describeWithChain(image, question, ctx);
             if (!result.ok)
                 return { title, output: `Image analysis failed: ${result.error}` };
+            // 泛解析条目是全图共享的：文本太短多半是视觉模型敷衍/拒答，存进去会毒化这条
+            // canonical 缓存，让以后所有泛解析都命中垃圾描述，所以低于门槛就跳过落盘。
+            // 具体追问不受限（"答案是 42" 是合法短答案）。
+            if (generic && result.text.length < genericWriteMinText.chars) {
+                return { title, output: format(path.basename(imagePath), result.modelId, result.text) };
+            }
             // 入库带上实际产出描述的候选 modelId，供后续缓存命中还原真实标签
             await descCacheSet(key, { modelId: result.modelId, text: result.text });
             // 成功标签直接用实际产出描述的候选引用键（而非链首近似）
@@ -745,6 +800,10 @@ const plugin = async (input, optionsArg) => {
         }
         if (lines.length === 0)
             return;
+        // 泛解析指引：主模型对"描述整图/解析图片"这类请求应省略 question（工具内部会用固定
+        // canonical 文案兜底，缓存 key 才能跨会话收敛）；只有用户问具体对象/文字/区域/颜色时才
+        // 填具体问句。措辞分化的泛问句会让缓存 key 拆碎、永远命中不了。
+        lines.push("[When the user asks for a general parse of the whole image, call vision_analyze WITHOUT a question (omit the question parameter). Only pass a question when the user asks about a specific object, text, region, or color.]");
         // 注入 synthetic text part：TUI 隐藏（不干扰用户输入展示），但会发给模型。
         // id 需满足 PartID 约定（prt 前缀）。
         const hint = {
@@ -765,10 +824,13 @@ const plugin = async (input, optionsArg) => {
         // 既不引入 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.",
+                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 is optional: pass it only when you need a specific detail (an object, text, region or color); otherwise omit it to get a full description of the whole image.",
                 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." },
+                    question: {
+                        type: "string",
+                        description: "Optional. What specific detail to look for (object/text/region/color). Omit for a full description of the whole image.",
+                    },
                 },
                 execute: visionAnalyze,
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-vision-analyze",
-  "version": "0.4.0",
+  "version": "0.5.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",