opencode-vision-analyze 0.3.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 (deduped across sessions within the same store); descriptions are cached per `<image-hash>:<question>` — the same image with the same question is described exactly once.
+- **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,8 +69,6 @@ Notes for the curl path:
 
 Supported image extensions: png / jpg / jpeg / gif / webp.
 
-Image storage: inside a git project images live under `<project>/.opencode/vision`; in non-git directories they go to the user cache dir (`<cache>/opencode-vision-analyze/vision`) — mirroring opencode's own project/global session scoping. 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). In git projects, add `.opencode/vision/` to your `.gitignore` if you don't want the cache tracked. The storage root is re-resolved on every write, so switching scope (e.g. after `git init`) takes effect on the next pasted image — though old session hints keep pointing at stale absolute paths until you re-paste.
-
 An ordered-candidates example with auto-fallback and free-first discovery:
 
 ```jsonc
@@ -89,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
 
 ```
@@ -98,8 +102,9 @@ User pastes image + question
      ├─ 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 the vision store
-        (<sha256>.<ext>; project-local inside a git repo, user cache otherwise)
+     └─ text-only main model → persist image to the user-level vision store
+        (<sha256>.<ext> under <cache>/opencode-vision-analyze/vision;
+         already-local file paths are read in place, never copied)
         and inject a synthetic hint (hidden in TUI, visible to model):
         "use the vision_analyze tool with image_path: ..."
 
@@ -111,8 +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
- │    (tagged with the model that produced it)
+ ├─ 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
@@ -127,16 +134,10 @@ 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).
-- **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 the description cache grow without eviction (image store: git-project-scoped or user-cache-scoped; description cache: per process).
+- **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
 
-- [ ] Persistent description cache (content-addressed on disk, with LRU / size cap)
 - [ ] Region cropping for zooming into image details
 
 ## Development

package/README.zh.md

@@ -13,9 +13,9 @@
 ## 特性
 
 - **工具化，而非提交时预分析。** 轮次即时启动；模型自己决定何时看图、带着什么问题看。提交零阻塞，失败在 agent 循环里可见、可重试。
-- **描述针对问题。** 模型把自己关注的问题传给 `vision_analyze`——而不是提交时预生成的一次性通用描述。
+- **描述针对问题。** 模型把自己关注的问题传给 `vision_analyze`——而不是提交时预生成的一次性通用描述。若只是让描述整张图，模型留空 `question`，工具用固定文案兜底，使同一张图的泛描述共享一条缓存（见"内容寻址缓存"）。
 - **原生快速路径。** 主模型本身有视觉能力时，`vision_analyze` 完全跳过视觉模型，直接把原图作为工具附件返回。
-- **内容寻址缓存。** 图片按内容寻址 `<sha256>.<ext>` 落盘（跨会话、同一存储域内天然去重）；描述按 `<图片哈希>:<问题>` 缓存——同图同问题只描述一次。
+- **内容寻址缓存。** 图片与描述按内容哈希落到用户级共享目录，跨会话 / 项目 / 重启复用——同一张图不会重复付费描述；同一张图的所有泛解析请求都收敛到同一条缓存。存储路径、容量上限与固定文案详见下文「存储与缓存」。
 - **统一鉴权。** 视觉调用走 opencode 子会话，复用 opencode 已管理的 provider 凭据，无需额外配置 API Key。
 
 ## 安装
@@ -69,8 +69,6 @@ curl 方式说明：
 
 受支持的图片扩展名：png / jpg / jpeg / gif / webp。
 
-图片存储：git 项目内图片放在 `<项目>/.opencode/vision`；非 git 目录则放入用户级缓存目录（`<cache>/opencode-vision-analyze/vision`）——与 opencode 自身的项目/全局会话分域一致。各平台默认：Linux `$XDG_CACHE_HOME || ~/.cache`；macOS `~/Library/Caches`（亦接受 `$XDG_CACHE_HOME` 覆盖）；Windows `%LOCALAPPDATA% || ~/AppData/Local`。缓存根 env 为空串视为未设置（回退默认）。git 项目中如不想跟踪缓存图片，请把 `.opencode/vision/` 加入 `.gitignore`。存储根在每次落盘时现算：切换存储范围（如执行 `git init`）后，从下一条贴图起即写入新域；旧会话 hint 里的绝对路径仍指向旧处，重新贴图即注入新 hint。
-
 有序候选 + 自动续接 + 免费优先的配置示例：
 
 ```jsonc
@@ -89,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 进程可安全共享同一描述缓存。
+
 ## 工作原理
 
 ```
@@ -98,8 +102,9 @@ curl 方式说明：
      ├─ 主模型支持图片输入 → 不做任何处理（原图直发）
      ├─ 无任何 image-capable 模型 → 不做处理（不注入 hint、不落盘；
      │    交给核心对图片的默认处理）
-     └─ 纯文本主模型 → 图片落盘到 vision 存储
-        （<sha256>.<ext>；git 项目内 → 项目目录，非 git → 用户缓存目录）
+     └─ 纯文本主模型 → 图片落盘到用户级 vision 存储
+        （<sha256>.<ext>；位于 <cache>/opencode-vision-analyze/vision；
+         本地已存在文件路径原位读用、不复制）
         并注入 synthetic 提示（TUI 隐藏、模型可见）：
         "用 vision_analyze 工具查看，image_path: ..."
 
@@ -111,8 +116,10 @@ vision_analyze 工具：
  ├─ 原生快速路径：会话主模型有视觉能力
  │    → 原图作为附件直接返回（不调视觉模型）
  ├─ http(s) 图片 URL → 下载（20 MB 上限）→ 统一磁盘路径
- ├─ 描述缓存命中（图片哈希 + 问题）→ 直接返回缓存文本
- │    （标签沿用产出该描述的模型）
+ ├─ 描述缓存命中（图片哈希 + 生效问题）→ 直接返回缓存文本
+ │    （泛解析收敛到 <sha>:<固定整图描述文案>；
+ │      持久化于 <cache>/opencode-vision-analyze/descriptions，
+ │      标签沿用产出该描述的模型）
  └─ 候选链：沿链逐候选建子会话（parentID 挂当前会话、禁用全部工具、
      专用 system prompt，图片 + 问题发给该候选视觉模型）
      → 首个成功即返回 → 子会话删除
@@ -127,16 +134,10 @@ 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 会话核心，钩子不会触发（且不报错）。
-- **历史图片** —— 插件启用之前发送的图片无法被描述（无提示、磁盘上无路径）。
-- **缓存无上限** —— 图片存储与描述缓存均不淘汰（图片存储：git 项目级 / 用户级缓存目录；描述缓存：进程级）。
+- **泛解析共享同一条缓存** —— 空 / 省略的 `question` 视为整图描述，复用该图已缓存的描述；具体追问各自保留条目（细节见「存储与缓存」）。
 
 ## Roadmap
 
-- [ ] 描述缓存按内容 sha 落盘持久化（含 LRU / 容量上限）
 - [ ] 区域裁剪（放大查看图片细节）
 
 ## 开发

package/dist/index.d.ts

@@ -7,24 +7,78 @@ export declare const providersTimeout: {
     ms: number;
 };
 /**
- * 判断目录是否位于 git 项目内：从 dir 向上（含自身）逐级找 `.git`
- * （目录，或 worktree/submodule 的 `.git` 指针文件），到文件系统根为止。
- * 纯同步、纯内置模块；作为命名导出便于单元测试注入真实临时目录验证。
- */
-export declare function isInsideGitRepo(dir: string): boolean;
-/**
- * 用户级（非 git）图片缓存的平台根：cache 目录 + opencode-vision-analyze/vision。
+ * 用户级 cache 的平台根（不带应用子目录）：cache 目录 + opencode-vision-analyze。
  * 空字符串 env 视为未设置（XDG/LOCALAPPDATA 官规：空值=未设置）——避免把 "" 当
  * 有效根导致 path.join("",…) 产出相对路径、相对进程 cwd 落盘。
  * darwin 亦接受 $XDG_CACHE_HOME 覆盖（跨平台统一 dotfiles 的宽容超集）。
  */
+export declare function userCacheRootBase(env: Record<string, string | undefined>, platform: string, home: string): string;
+/**
+ * 图片缓存的平台根（恒用户级、与 git 无关）：cache 目录 + opencode-vision-analyze/vision。
+ * 贴图与 http(s) 下载统一落盘于此（内容寻址命名）；本地已存在文件不复制、原位读用。
+ */
 export declare function userVisionCacheRoot(env: Record<string, string | undefined>, platform: string, home: string): string;
 /**
- * 图片存储根：与 opencode 的项目/全局语义对齐——
- * git 项目内 → <项目>/.opencode/vision（现状）；非 git 目录 → 用户级缓存目录。
- * 解析一次即可（纯函数，入参可注入以便三平台与 env 覆盖的单测）。
+ * 描述缓存的持久化目录：恒走用户级共享 cache（<cache>/opencode-vision-analyze/descriptions），
+ * **与 git / 非 git 分域无关**。描述缓存键是「图片内容 sha + 问题」，与项目解耦，放用户级
+ * 目录才能在跨项目 / 跨进程 / 重启后共享同一份"同图同问题只描述一次"的结果。
+ * 纯函数（入参注入 env/platform/homedir，便于三平台 + 空串 env 回退的单测）。
+ */
+export declare function resolveDescriptionDir(env: Record<string, string | undefined>, platform: string, home: string): string;
+/**
+ * 描述缓存的容量上限（模块级可变对象，便于测试注入小值；与 providersTimeout 同风格）。
+ * - maxEntries：最大条目数（2000）
+ * - maxBytes：条目文件字节总和上限（50 MB）
+ * 容量超限触发 LRU 淘汰（按文件 mtime 升序删最旧）。**单条即超 maxBytes 的条目不入缓存**
+ * （A / 硬上限，写前 utf8 字节预检跳过），保证磁盘恒 ≤ maxBytes、不因巨值挤掉已付费条目。
+ */
+export declare const descriptionCacheLimits: {
+    maxEntries: number;
+    maxBytes: number;
+};
+/**
+ * 图片缓存的容量上限（模块级可变对象，便于测试注入小值；与 providersTimeout 同风格）。
+ * - maxEntries：最大条目数（2000）
+ * - maxBytes：条目文件字节总和上限（500 MB）
+ * 容量超限触发 LRU 淘汰（按文件 mtime 升序删最旧）。与描述缓存不同，图片**允许单图超限**
+ * （贴图/下载必须给模型稳定 image_path，不能拒绝落盘）：单图 > maxBytes 仍写入且当次受
+ * protect 保护，容量可短暂超限，待下一次无关写入淘汰时收敛（best-effort）。
+ */
+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 resolveVisionDir(inputDir: string, env: Record<string, string | undefined>, platform: string, home: string): string;
+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

@@ -2,17 +2,26 @@
  * opencode-vision-analyze
  *
  * 为「不具备视觉能力的主模型」提供图片解读路由：当用户在消息中附带图片时，
- * 插件把图片落盘到 vision 目录（git 项目内 → <项目>/.opencode/vision；
- * 非 git 目录 → 用户级缓存目录），并向模型注入一条 synthetic 提示
+ * 插件把图片落盘到**用户级共享目录**（<cache>/opencode-vision-analyze/vision，
+ * 恒用户级、与 git/非 git 无关），并向模型注入一条 synthetic 提示
  * （TUI 界面隐藏、模型可见），引导它通过 vision_analyze 工具让指定的视觉
  * 模型描述图片。若主模型本身支持图片输入，则不做任何干预，原图直接发给主模型。
  *
  * 工作方式（vision_analyze 工具路径）：主模型调用 vision_analyze 时，插件
  * 创建一个 parentID 挂在当前会话下的临时子会话（不进会话列表、不生成
  * 标题、禁用全部工具），把原图以 data URL 发给视觉模型，取回描述文字后
- * 删除子会话并返回描述。同一张图 + 同一问题的描述按内容哈希缓存。
- * image_path 除了绝对路径也接受 http(s) URL：先下载落盘到同一 vision
- * 目录（内容哈希命名，天然与附件落盘去重），再走统一的磁盘加载路径。
+ * 删除子会话并返回描述。描述按「<图片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），
+ * 只有贴图/下载才写缓存。
  * 主模型本身支持图片输入时走快速路径：不做子会话描述，直接把原图作为
  * 工具附件回传给模型自行查看。
  *
@@ -24,7 +33,6 @@
  *   若交互默认切到 V2 Session 核心，本钩子不会触发（也不会报错）。
  */
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -74,44 +82,96 @@ const VISION_SYSTEM_PROMPT = [
 /** data URL 形如 data:<mime>;base64,<payload> */
 const DATA_URL_PATTERN = /^data:([^;]+);base64,(.+)$/;
 /**
- * 判断目录是否位于 git 项目内：从 dir 向上（含自身）逐级找 `.git`
- * （目录，或 worktree/submodule 的 `.git` 指针文件），到文件系统根为止。
- * 纯同步、纯内置模块；作为命名导出便于单元测试注入真实临时目录验证。
- */
-export function isInsideGitRepo(dir) {
-    let cur = path.resolve(dir);
-    for (;;) {
-        if (existsSync(path.join(cur, ".git")))
-            return true;
-        const parent = path.dirname(cur);
-        if (parent === cur)
-            return false; // 已到文件系统根
-        cur = parent;
-    }
-}
-/**
- * 用户级（非 git）图片缓存的平台根：cache 目录 + opencode-vision-analyze/vision。
+ * 用户级 cache 的平台根（不带应用子目录）：cache 目录 + opencode-vision-analyze。
  * 空字符串 env 视为未设置（XDG/LOCALAPPDATA 官规：空值=未设置）——避免把 "" 当
  * 有效根导致 path.join("",…) 产出相对路径、相对进程 cwd 落盘。
  * darwin 亦接受 $XDG_CACHE_HOME 覆盖（跨平台统一 dotfiles 的宽容超集）。
  */
-export function userVisionCacheRoot(env, platform, home) {
+export function userCacheRootBase(env, platform, home) {
     const base = platform === "darwin"
         ? (env.XDG_CACHE_HOME || path.join(home, "Library", "Caches"))
         : platform === "win32"
             ? (env.LOCALAPPDATA || path.join(home, "AppData", "Local"))
             : (env.XDG_CACHE_HOME || path.join(home, ".cache"));
-    return path.join(base, "opencode-vision-analyze", "vision");
+    return path.join(base, "opencode-vision-analyze");
 }
 /**
- * 图片存储根：与 opencode 的项目/全局语义对齐——
- * git 项目内 → <项目>/.opencode/vision（现状）；非 git 目录 → 用户级缓存目录。
- * 解析一次即可（纯函数，入参可注入以便三平台与 env 覆盖的单测）。
+ * 图片缓存的平台根（恒用户级、与 git 无关）：cache 目录 + opencode-vision-analyze/vision。
+ * 贴图与 http(s) 下载统一落盘于此（内容寻址命名）；本地已存在文件不复制、原位读用。
+ */
+export function userVisionCacheRoot(env, platform, home) {
+    return path.join(userCacheRootBase(env, platform, home), "vision");
+}
+/**
+ * 描述缓存的持久化目录：恒走用户级共享 cache（<cache>/opencode-vision-analyze/descriptions），
+ * **与 git / 非 git 分域无关**。描述缓存键是「图片内容 sha + 问题」，与项目解耦，放用户级
+ * 目录才能在跨项目 / 跨进程 / 重启后共享同一份"同图同问题只描述一次"的结果。
+ * 纯函数（入参注入 env/platform/homedir，便于三平台 + 空串 env 回退的单测）。
+ */
+export function resolveDescriptionDir(env, platform, home) {
+    return path.join(userCacheRootBase(env, platform, home), "descriptions");
+}
+/**
+ * 描述缓存的容量上限（模块级可变对象，便于测试注入小值；与 providersTimeout 同风格）。
+ * - maxEntries：最大条目数（2000）
+ * - maxBytes：条目文件字节总和上限（50 MB）
+ * 容量超限触发 LRU 淘汰（按文件 mtime 升序删最旧）。**单条即超 maxBytes 的条目不入缓存**
+ * （A / 硬上限，写前 utf8 字节预检跳过），保证磁盘恒 ≤ maxBytes、不因巨值挤掉已付费条目。
+ */
+export const descriptionCacheLimits = {
+    maxEntries: 2000,
+    maxBytes: 50 * 1024 * 1024,
+};
+/**
+ * 图片缓存的容量上限（模块级可变对象，便于测试注入小值；与 providersTimeout 同风格）。
+ * - maxEntries：最大条目数（2000）
+ * - maxBytes：条目文件字节总和上限（500 MB）
+ * 容量超限触发 LRU 淘汰（按文件 mtime 升序删最旧）。与描述缓存不同，图片**允许单图超限**
+ * （贴图/下载必须给模型稳定 image_path，不能拒绝落盘）：单图 > maxBytes 仍写入且当次受
+ * protect 保护，容量可短暂超限，待下一次无关写入淘汰时收敛（best-effort）。
  */
-export function resolveVisionDir(inputDir, env, platform, home) {
-    if (isInsideGitRepo(inputDir))
-        return path.join(path.resolve(inputDir), ".opencode", "vision");
-    return userVisionCacheRoot(env, platform, home);
+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）。提示注入可让模型指向超大图片，
@@ -164,12 +224,6 @@ const plugin = async (input, optionsArg) => {
     const sessionModels = new Map();
     /** "provider/model" → 是否具备图片输入能力（查询结果缓存，进程级） */
     const imageCapable = new Map();
-    /**
-     * 描述缓存："<sha>:<question>" → 描述结果（同一张图 + 同一个问题只描述一次）。
-     * 值带 modelId：记录实际产出该描述的候选模型，缓存命中时标签沿用入库模型，
-     * 而不是用当前候选链链首近似（链配置变化或 fallback 命中次选时标签才真实）。
-     */
-    const descriptions = new Map();
     /** 本插件创建的子会话 ID 集合（正常路径用后即删，dispose 兜底清理残留） */
     const subSessions = new Set();
     /** 任意错误值 → 可读文本：Error 取 message，字符串原样，其余 JSON 序列化兜底。 */
@@ -318,14 +372,14 @@ const plugin = async (input, optionsArg) => {
     /** 描述标签：标注图片文件名与产出描述的模型引用键（basename 运行时按图传入）。 */
     const format = (basename, modelId, text) => `[Image: ${basename} — described by ${modelId}]\n${text}`;
     /**
-     * 把图片字节内容原子落盘并返回最终 filepath。每次调用现算存储根
-     * （git 项目 → 项目 .opencode/vision；非 git → 用户级缓存，见 resolveVisionDir）：
-     * 运行中存储范围变化（如 git init）从下一条图片起即时生效，无需重启。
-     * 先写 `<sha><ext>.tmp-<uuid>` 再 rename：共享目录（用户级/多实例）并发写同一 sha
-     * 时内容寻址下原子幂等；失败先清理临时文件再抛错，避免孤儿 tmp 累积。
+     * 把图片字节内容原子落盘到**用户级缓存目录**（<cache>/opencode-vision-analyze/vision，
+     * 与 git 无关）并返回最终 filepath。贴图与 http(s) 下载统一经此写入（本地已存在文件
+     * 不复制、直接原位读用）。先写 `<sha><ext>.tmp-<uuid>` 再 rename：共享目录多进程并发
+     * 写同一 sha 时内容寻址下原子幂等；失败先清理临时文件再抛错，避免孤儿 tmp 累积。
+     * rename 成功后触发图片 LRU 容量淘汰（刚写入文件受 protect 保护）。
      */
     const persistImageBytes = async (bytes, ext) => {
-        const dir = resolveVisionDir(input.directory, process.env, process.platform, homedir());
+        const dir = userVisionCacheRoot(process.env, process.platform, homedir());
         const sha = createHash("sha256").update(bytes).digest("hex");
         const filepath = path.join(dir, `${sha}${ext}`);
         const tmpPath = path.join(dir, `${sha}${ext}.tmp-${randomUUID()}`);
@@ -338,6 +392,10 @@ const plugin = async (input, optionsArg) => {
             await fs.unlink(tmpPath).catch(() => { });
             throw error;
         }
+        await evictToCaps(dir, visionCacheLimits, {
+            filter: (name) => /^[0-9a-f]{64}\.(png|jpe?g|gif|webp)$/i.test(name),
+            protectName: path.basename(filepath),
+        });
         return filepath;
     };
     /**
@@ -396,6 +454,8 @@ const plugin = async (input, optionsArg) => {
     };
     /**
      * 从磁盘加载图片：按扩展名识别 MIME，读取失败或文件为空返回 undefined。
+     * LRU 时钟：**仅当图片位于本插件 vision 缓存根内**（贴图/下载落盘产物）才 touch mtime；
+     * 流程 B 直读的外部本地文件绝不触碰（不得改写用户文件 mtime）。
      */
     const loadImage = async (filepath) => {
         const mime = EXT_MIME[path.extname(filepath).toLowerCase()];
@@ -405,12 +465,109 @@ const plugin = async (input, optionsArg) => {
             const bytes = await fs.readFile(filepath);
             if (bytes.length === 0)
                 return undefined;
+            const visionRoot = userVisionCacheRoot(process.env, process.platform, homedir());
+            const rel = path.relative(visionRoot, filepath);
+            if (rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+                // 命中缓存内文件 → touch mtime 作 LRU 时钟（best-effort，失败不影响读）
+                const now = new Date();
+                await fs.utimes(filepath, now, now).catch(() => { });
+            }
             return { bytes, mime };
         }
         catch {
             return undefined;
         }
     };
+    // ---- 描述缓存（用户级目录落盘，磁盘即事实；全链 fail-open） ---------------------
+    /** 描述缓存 key → 磁盘文件路径（<dir>/<sha256(key)>.json）。 */
+    const descCacheFile = (key) => path.join(resolveDescriptionDir(process.env, process.platform, homedir()), `${createHash("sha256").update(key).digest("hex")}.json`);
+    /** 读取描述缓存：命中（JSON shape 合法）touch mtime 后返回，任何失败一律 miss。 */
+    const descCacheGet = async (key) => {
+        try {
+            const file = descCacheFile(key);
+            const raw = JSON.parse(await fs.readFile(file, "utf8"));
+            if (typeof raw !== "object" ||
+                raw === null ||
+                typeof raw.modelId !== "string" ||
+                typeof raw.text !== "string") {
+                return undefined;
+            }
+            const value = raw;
+            // 命中即触摸 mtime → 作为 LRU 时钟（best-effort）
+            const now = new Date();
+            await fs.utimes(file, now, now).catch(() => { });
+            return value;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /**
+     * 写描述缓存（tmp+rename 原子）并触发容量淘汰；任何失败静默吞掉（best-effort）。
+     * 超限策略（A / 硬上限）：序列化后先按 utf8 字节预检，单条 > maxBytes 则**不入缓存**
+     * （不写盘、不触发淘汰、不删除该 key 已有的旧条目）——避免"超限巨值挤掉全部已付费条目、
+     * 且自身活不过下一次无关写入"的写→删抖动，保证磁盘恒 ≤ maxBytes。
+     */
+    const descCacheSet = async (key, value) => {
+        const payload = JSON.stringify(value);
+        // 口径与 evict 的 fs.stat().size 一致：磁盘 utf8 字节，非字符串 length（中文/emoji 不等价）
+        if (Buffer.byteLength(payload, "utf8") > descriptionCacheLimits.maxBytes)
+            return;
+        const file = descCacheFile(key);
+        const dir = path.dirname(file);
+        const tmp = path.join(dir, `${path.basename(file)}.tmp-${randomUUID()}`);
+        try {
+            await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+            await fs.writeFile(tmp, payload);
+            await fs.rename(tmp, file);
+        }
+        catch {
+            await fs.unlink(tmp).catch(() => { });
+            return;
+        }
+        await evictToCaps(dir, descriptionCacheLimits, {
+            filter: (name) => name.endsWith(".json"),
+            protectName: path.basename(file),
+        });
+    };
+    /**
+     * 通用 LRU + 容量淘汰（描述/图片缓存复用）：超出 limits.maxEntries / maxBytes 时按
+     * mtime 升序删最旧，直到双条件满足。filter 限定参与淘汰的文件（描述 .json；图片 sha 文件，
+     * 排除 tmp 残留）；protectName 保护刚写入的条目不被本次淘汰自删。
+     */
+    const evictToCaps = async (dir, limits, opts) => {
+        try {
+            const names = (await fs.readdir(dir)).filter(opts.filter);
+            const stats = await Promise.all(names.map(async (name) => {
+                try {
+                    const s = await fs.stat(path.join(dir, name));
+                    return { name, size: s.size, mtimeMs: s.mtimeMs };
+                }
+                catch {
+                    return undefined;
+                }
+            }));
+            const entries = stats.filter((s) => s !== undefined);
+            const { maxEntries, maxBytes } = limits;
+            let total = entries.reduce((sum, e) => sum + e.size, 0);
+            entries.sort((a, b) => a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name));
+            // 逐条删最旧直至双条件满足；刚写入的条目受保护（极端单条超限时保留最新，不自我删除）。
+            // 用额外计数控制，不就地改遍历数组（entries 仅作删除候选快照）。
+            let remaining = entries.length;
+            for (const entry of entries) {
+                if (total <= maxBytes && remaining <= maxEntries)
+                    break;
+                if (entry.name === opts.protectName)
+                    continue;
+                await fs.unlink(path.join(dir, entry.name)).catch(() => { });
+                total -= entry.size;
+                remaining -= 1;
+            }
+        }
+        catch {
+            // 目录扫描/删除失败忽略：淘汰是 best-effort，下次写入再触发
+        }
+    };
     /**
      * vision_analyze 工具：主模型传入图片路径与问题，返回视觉模型给出的描述。
      * 工具永不抛错——所有失败都以错误文字返回，让 agent 循环可以读到原因并
@@ -419,8 +576,14 @@ 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.";
-            // http(s) URL：先下载到本地 vision 目录，再统一走磁盘加载路径。
+            // 泛解析判定：没给问题（空/纯空白），或措辞与 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)
                 ? await downloadImage(args.image_path, ctx.abort)
@@ -449,9 +612,10 @@ const plugin = async (input, optionsArg) => {
                     ],
                 };
             }
-            // 描述缓存：内容哈希 + 问题作为 key，命中直接复用（title 标注 cached）。
+            // 描述缓存：内容哈希 + 生效问题作为 key，命中直接复用（title 标注 cached）。
+            // 落盘在用户级共享目录（resolveDescriptionDir）——跨项目/进程/重启命中；磁盘即事实。
             const key = `${createHash("sha256").update(image.bytes).digest("hex")}:${question}`;
-            const cached = descriptions.get(key);
+            const cached = await descCacheGet(key);
             if (cached !== undefined) {
                 // 命中时标签沿用入库时的模型（cached.modelId）：即便此刻候选链链首
                 // 已与入库模型不同，也保持标签真实、不重写。
@@ -460,8 +624,14 @@ 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，供后续缓存命中还原真实标签
-            descriptions.set(key, { modelId: result.modelId, text: result.text });
+            await descCacheSet(key, { modelId: result.modelId, text: result.text });
             // 成功标签直接用实际产出描述的候选引用键（而非链首近似）
             return { title, output: format(path.basename(imagePath), result.modelId, result.text) };
         }
@@ -630,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 = {
@@ -650,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.3.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",