opencode-vision-analyze 0.3.0 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@ A tool-based vision routing plugin for [opencode](https://opencode.ai): when the
 - **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 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 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).
 - **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,7 +69,9 @@ 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.
+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:
 
@@ -98,8 +100,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: ..."
 
@@ -112,7 +115,8 @@ 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
- │    (tagged with the model that produced it)
+ │    (persisted under <cache>/opencode-vision-analyze/descriptions,
+ │     tagged with the model that produced it, LRU-capped 2000 entries / 50 MB)
  └─ 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,12 +135,9 @@ Key behaviors:
 ## 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).
 
 ## Roadmap
 
-- [ ] Persistent description cache (content-addressed on disk, with LRU / size cap)
 - [ ] Region cropping for zooming into image details
 
 ## Development

package/README.zh.md

@@ -15,7 +15,7 @@
 - **工具化，而非提交时预分析。** 轮次即时启动；模型自己决定何时看图、带着什么问题看。提交零阻塞，失败在 agent 循环里可见、可重试。
 - **描述针对问题。** 模型把自己关注的问题传给 `vision_analyze`——而不是提交时预生成的一次性通用描述。
 - **原生快速路径。** 主模型本身有视觉能力时，`vision_analyze` 完全跳过视觉模型，直接把原图作为工具附件返回。
-- **内容寻址缓存。** 图片按内容寻址 `<sha256>.<ext>` 落盘（跨会话、同一存储域内天然去重）；描述按 `<图片哈希>:<问题>` 缓存——同图同问题只描述一次。
+- **内容寻址缓存。** 图片按内容寻址 `<sha256>.<ext>` 落盘到**用户级共享目录**（`<cache>/opencode-vision-analyze/vision`，跨项目/会话天然去重，LRU 上限 2000 条 / 500MB）；描述按 `<图片哈希>:<问题>` 缓存到**用户级共享目录**（`<cache>/opencode-vision-analyze/descriptions`）——跨项目/进程/插件重启同图同问题只描述一次；描述缓存 LRU 上限 2000 条 / 50MB。
 - **统一鉴权。** 视觉调用走 opencode 子会话，复用 opencode 已管理的 provider 凭据，无需额外配置 API Key。
 
 ## 安装
@@ -69,7 +69,9 @@ 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。
+图片存储：**恒定放用户级共享目录** `<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 进程可安全共享同一描述缓存。
 
 有序候选 + 自动续接 + 免费优先的配置示例：
 
@@ -98,8 +100,9 @@ curl 方式说明：
      ├─ 主模型支持图片输入 → 不做任何处理（原图直发）
      ├─ 无任何 image-capable 模型 → 不做处理（不注入 hint、不落盘；
      │    交给核心对图片的默认处理）
-     └─ 纯文本主模型 → 图片落盘到 vision 存储
-        （<sha256>.<ext>；git 项目内 → 项目目录，非 git → 用户缓存目录）
+     └─ 纯文本主模型 → 图片落盘到用户级 vision 存储
+        （<sha256>.<ext>；位于 <cache>/opencode-vision-analyze/vision；
+         本地已存在文件路径原位读用、不复制）
         并注入 synthetic 提示（TUI 隐藏、模型可见）：
         "用 vision_analyze 工具查看，image_path: ..."
 
@@ -112,7 +115,8 @@ vision_analyze 工具：
  │    → 原图作为附件直接返回（不调视觉模型）
  ├─ http(s) 图片 URL → 下载（20 MB 上限）→ 统一磁盘路径
  ├─ 描述缓存命中（图片哈希 + 问题）→ 直接返回缓存文本
- │    （标签沿用产出该描述的模型）
+ │    （持久化于 <cache>/opencode-vision-analyze/descriptions，
+ │      标签沿用产出该描述的模型；LRU 上限 2000 条 / 50MB）
  └─ 候选链：沿链逐候选建子会话（parentID 挂当前会话、禁用全部工具、
      专用 system prompt，图片 + 问题发给该候选视觉模型）
      → 首个成功即返回 → 子会话删除
@@ -131,12 +135,9 @@ vision_analyze 工具：
 ## 已知限制
 
 - **仅 V1 会话流** —— 钩子挂在 V1 `SessionPrompt` 路径上；若 opencode 默认交互切到 V2 会话核心，钩子不会触发（且不报错）。
-- **历史图片** —— 插件启用之前发送的图片无法被描述（无提示、磁盘上无路径）。
-- **缓存无上限** —— 图片存储与描述缓存均不淘汰（图片存储：git 项目级 / 用户级缓存目录；描述缓存：进程级）。
 
 ## Roadmap
 
-- [ ] 描述缓存按内容 sha 落盘持久化（含 LRU / 容量上限）
 - [ ] 区域裁剪（放大查看图片细节）
 
 ## 开发

package/dist/index.d.ts

@@ -7,24 +7,47 @@ 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 function resolveVisionDir(inputDir: string, env: Record<string, string | undefined>, platform: string, home: string): string;
+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;
+};
 declare const _default: {
     id: string;
     server: Plugin;

package/dist/index.js

@@ -2,17 +2,22 @@
  * 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 双上限、单条超限不入缓存）——
+ * 跨项目/跨进程/插件重启后同图同问题只描述一次。
+ * image_path 除了绝对路径也接受 http(s) URL：先下载落盘到同一用户级 vision
+ * 目录（内容哈希命名，天然与附件落盘去重；LRU + 容量上限，2000 条 / 500MB），
+ * 再走统一的磁盘加载路径。**本地已存在的文件直接原位读取**（不复制、不 touch），
+ * 只有贴图/下载才写缓存。
  * 主模型本身支持图片输入时走快速路径：不做子会话描述，直接把原图作为
  * 工具附件回传给模型自行查看。
  *
@@ -24,7 +29,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,45 +78,58 @@ 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");
+}
+/**
+ * 图片缓存的平台根（恒用户级、与 git 无关）：cache 目录 + opencode-vision-analyze/vision。
+ * 贴图与 http(s) 下载统一落盘于此（内容寻址命名）；本地已存在文件不复制、原位读用。
+ */
+export function userVisionCacheRoot(env, platform, home) {
+    return path.join(userCacheRootBase(env, platform, home), "vision");
 }
 /**
- * 图片存储根：与 opencode 的项目/全局语义对齐——
- * git 项目内 → <项目>/.opencode/vision（现状）；非 git 目录 → 用户级缓存目录。
- * 解析一次即可（纯函数，入参可注入以便三平台与 env 覆盖的单测）。
+ * 描述缓存的持久化目录：恒走用户级共享 cache（<cache>/opencode-vision-analyze/descriptions），
+ * **与 git / 非 git 分域无关**。描述缓存键是「图片内容 sha + 问题」，与项目解耦，放用户级
+ * 目录才能在跨项目 / 跨进程 / 重启后共享同一份"同图同问题只描述一次"的结果。
+ * 纯函数（入参注入 env/platform/homedir，便于三平台 + 空串 env 回退的单测）。
  */
-export function resolveVisionDir(inputDir, env, platform, home) {
-    if (isInsideGitRepo(inputDir))
-        return path.join(path.resolve(inputDir), ".opencode", "vision");
-    return userVisionCacheRoot(env, platform, home);
+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 const visionCacheLimits = {
+    maxEntries: 2000,
+    maxBytes: 500 * 1024 * 1024,
+};
 /**
  * http(s) 下载图片的大小上限（20 MB）。提示注入可让模型指向超大图片，
  * 下载不限长是成本/健壮性放大器：先按 content-length 头提前拒绝，
@@ -164,12 +181,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 +329,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 +349,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 +411,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 +422,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 循环可以读到原因并
@@ -420,7 +534,7 @@ const plugin = async (input, optionsArg) => {
         const title = "vision_analyze";
         try {
             const question = args.question?.trim() || "Describe this image in full detail.";
-            // http(s) URL：先下载到本地 vision 目录，再统一走磁盘加载路径。
+            // http(s) URL：先下载到用户级 vision 缓存目录，再统一走磁盘加载路径。
             // ctx.abort 传入下载：用户中止即刻断下载（含 pre-abort 不再发请求）。
             const download = /^https?:\/\//i.test(args.image_path)
                 ? await downloadImage(args.image_path, ctx.abort)
@@ -450,8 +564,9 @@ const plugin = async (input, optionsArg) => {
                 };
             }
             // 描述缓存：内容哈希 + 问题作为 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）：即便此刻候选链链首
                 // 已与入库模型不同，也保持标签真实、不重写。
@@ -461,7 +576,7 @@ const plugin = async (input, optionsArg) => {
             if (!result.ok)
                 return { title, output: `Image analysis failed: ${result.error}` };
             // 入库带上实际产出描述的候选 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) };
         }

package/package.json

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