opencode-vision-analyze 0.2.0 → 0.4.0

package/README.md

@@ -4,6 +4,8 @@
 [![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.zh.md)
+
 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.
@@ -13,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 `<sha256>.<ext>` (deduped across sessions); 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
@@ -67,6 +69,10 @@ 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
@@ -94,7 +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 .opencode/vision/<sha256>.<ext>
+     └─ 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: ..."
 
@@ -107,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
@@ -126,17 +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).
-- **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).
 
 ## Roadmap
 
-- [ ] 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

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,6 +69,10 @@ 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
@@ -96,7 +100,9 @@ curl 方式说明：
      ├─ 主模型支持图片输入 → 不做任何处理（原图直发）
      ├─ 无任何 image-capable 模型 → 不做处理（不注入 hint、不落盘；
      │    交给核心对图片的默认处理）
-     └─ 纯文本主模型 → 图片落盘 .opencode/vision/<sha256>.<ext>
+     └─ 纯文本主模型 → 图片落盘到用户级 vision 存储
+        （<sha256>.<ext>；位于 <cache>/opencode-vision-analyze/vision；
+         本地已存在文件路径原位读用、不复制）
         并注入 synthetic 提示（TUI 隐藏、模型可见）：
         "用 vision_analyze 工具查看，image_path: ..."
 
@@ -109,7 +115,8 @@ vision_analyze 工具：
  │    → 原图作为附件直接返回（不调视觉模型）
  ├─ http(s) 图片 URL → 下载（20 MB 上限）→ 统一磁盘路径
  ├─ 描述缓存命中（图片哈希 + 问题）→ 直接返回缓存文本
- │    （标签沿用产出该描述的模型）
+ │    （持久化于 <cache>/opencode-vision-analyze/descriptions，
+ │      标签沿用产出该描述的模型；LRU 上限 2000 条 / 50MB）
  └─ 候选链：沿链逐候选建子会话（parentID 挂当前会话、禁用全部工具、
      专用 system prompt，图片 + 问题发给该候选视觉模型）
      → 首个成功即返回 → 子会话删除
@@ -128,17 +135,9 @@ vision_analyze 工具：
 ## 已知限制
 
 - **仅 V1 会话流** —— 钩子挂在 V1 `SessionPrompt` 路径上；若 opencode 默认交互切到 V2 会话核心，钩子不会触发（且不报错）。
-- **SSRF 面** —— URL 下载跟随重定向、不拦截私网/云元数据地址。本地单用户 CLI 信任级别下可接受；多租户环境使用前应加地址过滤。
-- **中止不传导** —— 用户中止不会取消进行中的下载/子会话请求，它们会跑到各自的 deadline（下载 30 秒、子会话 `timeout_ms`）。超时/中止后子会话虽被删除，但 provider 端的孤儿回合仍可能计费。
-- **历史图片** —— 插件启用之前发送的图片无法被描述（无提示、磁盘上无路径）。
-- **缓存无上限** —— 图片存储与描述缓存均不淘汰（进程级 / 项目目录级）。
 
 ## Roadmap
 
-- [ ] 能力查询（`config.providers()`）加超时保护
-- [ ] 超时路径先中止子会话（`/session/{id}/abort`）再删除
-- [ ] 描述缓存 LRU / 容量上限
-- [ ] URL 下载可选私网地址拦截
 - [ ] 区域裁剪（放大查看图片细节）
 
 ## 开发

package/dist/index.d.ts

@@ -1,4 +1,53 @@
 import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * `config.providers()` 能力查询的超时预算（毫秒）。做成可改写对象（而非常量/选项）：
+ * 避免选项膨胀；测试把 ms 调小即可缩短等待（TS 不允许对 import 的 let 绑定赋值）。
+ */
+export declare const providersTimeout: {
+    ms: number;
+};
+/**
+ * 用户级 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;
+/**
+ * 描述缓存的持久化目录：恒走用户级共享 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;
+};
 declare const _default: {
     id: string;
     server: Plugin;

package/dist/index.js

@@ -2,40 +2,22 @@
  * opencode-vision-analyze
  *
  * 为「不具备视觉能力的主模型」提供图片解读路由：当用户在消息中附带图片时，
- * 插件把图片落盘到 .opencode/vision/<sha256>.<ext>，并向模型注入一条
- * synthetic 提示（TUI 界面隐藏、模型可见），引导它通过 vision_analyze 工具
- * 让指定的视觉模型描述图片。若主模型本身支持图片输入，则不做任何干预，
- * 原图直接发给主模型。
- *
- * 安装方式一（npm）：
- *   {
- *     "plugin": [["opencode-vision-analyze", { "models": ["provider/vision-model"] }]]
- *   }
- *
- * 安装方式二（curl 下载单文件，免 npm）：
- *   mkdir -p .opencode
- *   curl -fsSL <raw-url>/src/index.ts -o .opencode/vision-analyze.ts
- *   {
- *     "plugin": [["./.opencode/vision-analyze.ts", { "models": ["provider/vision-model"] }]]
- *   }
- *
- * 选项：
- *   - models（可选，缺省/空数组 = 自动模式）：有序视觉候选数组，如
- *     ["provider-a/m1", "provider-b/m2"]；单模型写 ["provider/model"] 即可
- *   - unlisted_fallback（可选，默认 false）：显式候选耗尽后自动续接未列出的 image-capable 模型
- *   - free_first（可选，默认 false）：自动发现档序反转（custom/匿名免费源优先，默认 config 优先）
- *   - timeout_ms：单候选子会话请求的超时毫秒数（正数，默认 60000）
- *
- * 候选链语义：显式 models 恒在链首；缺省/空数组 → 自动发现全部 image-capable
- * 模型并按 Provider.source 档序排列。链上候选逐个尝试，成功即止，全败聚合报错。
- * 描述子会话的模型属于候选链，chat.message 递归防护以整链成员为集。
+ * 插件把图片落盘到**用户级共享目录**（<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），
+ * 只有贴图/下载才写缓存。
  * 主模型本身支持图片输入时走快速路径：不做子会话描述，直接把原图作为
  * 工具附件回传给模型自行查看。
  *
@@ -43,17 +25,12 @@
  * 类型依赖仅 @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 { homedir } from "node:os";
 import path from "node:path";
 /** 支持的图片扩展名 → MIME 类型（vision_analyze 加载磁盘图片时使用） */
 const EXT_MIME = {
@@ -70,6 +47,22 @@ const MIME_EXT = {
     "image/gif": ".gif",
     "image/webp": ".webp",
 };
+/**
+ * 内部超时错误类型（name = "DeadlineError"）。
+ * 与 AbortError 并列可判别：超时路径（providers 查询 / 子会话请求）据此判断
+ * "底层请求可能仍在飞"，供调用方决定是否需要 abort 取消（见 attemptModel）。
+ */
+class DeadlineError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeadlineError";
+    }
+}
+/**
+ * `config.providers()` 能力查询的超时预算（毫秒）。做成可改写对象（而非常量/选项）：
+ * 避免选项膨胀；测试把 ms 调小即可缩短等待（TS 不允许对 import 的 let 绑定赋值）。
+ */
+export const providersTimeout = { ms: 5000 };
 /**
  * 视觉子会话使用的系统提示词。
  * 要求：精确转录图中文字，描述 UI/布局/对象/颜色等，优先回答用户问题，
@@ -84,6 +77,59 @@ const VISION_SYSTEM_PROMPT = [
 ].join("\n");
 /** data URL 形如 data:<mime>;base64,<payload> */
 const DATA_URL_PATTERN = /^data:([^;]+);base64,(.+)$/;
+/**
+ * 用户级 cache 的平台根（不带应用子目录）：cache 目录 + opencode-vision-analyze。
+ * 空字符串 env 视为未设置（XDG/LOCALAPPDATA 官规：空值=未设置）——避免把 "" 当
+ * 有效根导致 path.join("",…) 产出相对路径、相对进程 cwd 落盘。
+ * darwin 亦接受 $XDG_CACHE_HOME 覆盖（跨平台统一 dotfiles 的宽容超集）。
+ */
+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");
+}
+/**
+ * 图片缓存的平台根（恒用户级、与 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 const visionCacheLimits = {
+    maxEntries: 2000,
+    maxBytes: 500 * 1024 * 1024,
+};
 /**
  * http(s) 下载图片的大小上限（20 MB）。提示注入可让模型指向超大图片，
  * 下载不限长是成本/健壮性放大器：先按 content-length 头提前拒绝，
@@ -135,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 序列化兜底。 */
@@ -151,33 +191,49 @@ const plugin = async (input, optionsArg) => {
             return error;
         return JSON.stringify(error) ?? String(error);
     };
+    /**
+     * 无 ToolContext 的超时原语：到期以 DeadlineError(timeoutMessage) 拒绝。
+     * 与 withDeadline 的差别是它不感知 abort——能力查询（providers）等无 ctx 的
+     * 请求只关心"别永久挂起"，不需要监听用户中止；子会话请求由 withDeadline 组合
+     * abort 信号后复用它，保证全插件只有一套计时机制。
+     */
+    const withTimeout = async (promise, ms, timeoutMessage) => {
+        let timer;
+        const guard = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new DeadlineError(timeoutMessage)), ms);
+        });
+        try {
+            return await Promise.race([promise, guard]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
     /**
      * 给子会话请求加超时与 abort 保护：任一触发即让 Promise 以错误结束，
-     * 不再等待底层请求；finally 中清理 timer 与监听器，避免泄漏。
+     * 不再等待底层请求；超时复用 withTimeout（DeadlineError），abort 仍以
+     * AbortError 拒绝；finally 中清理 timer 与监听器，避免泄漏。
      */
     const withDeadline = (promise, ctx) => {
-        let timer;
+        // ctx.abort 已中止时 abort 事件不会再触发，必须立即拒绝，
+        // 否则 race 只能干等 timer 超时。
+        if (ctx.abort.aborted)
+            return Promise.reject(new DOMException("Aborted", "AbortError"));
         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);
+        const abortGuard = new Promise((_, reject) => {
             onAbort = () => reject(new DOMException("Aborted", "AbortError"));
             ctx.abort.addEventListener("abort", onAbort, { once: true });
         });
-        return Promise.race([promise, guarded]).finally(() => {
-            if (timer)
-                clearTimeout(timer);
+        return withTimeout(Promise.race([promise, abortGuard]), timeoutMs, `vision model call timed out after ${timeoutMs}ms`).finally(() => {
             if (onAbort)
                 ctx.abort.removeEventListener("abort", onAbort);
         });
     };
     /** 判断错误是否为中止信号（AbortError），供 attemptModel 标记 / 链循环中止整链。 */
     const isAbortError = (error) => error instanceof Error && error.name === "AbortError";
+    /** 判断错误是否为本插件超时信号（DeadlineError）——与 AbortError 并列，表示"请求到期被本地掐断"。 */
+    const isDeadlineError = (error) => error instanceof Error && error.name === "DeadlineError";
     /**
      * 单个候选的尝试：创建子会话（parentID 挂当前会话）→ 用该候选模型描述 →
      * 删除子会话。任何失败（创建 / 请求 / 超时 / 中止 / 底层抛错 / 无文本）都
@@ -188,6 +244,9 @@ const plugin = async (input, optionsArg) => {
     const attemptModel = async (candidate, image, question, ctx) => {
         const dataURL = `data:${image.mime};base64,${image.bytes.toString("base64")}`;
         let subID;
+        // "回合可能仍在飞"标记：请求被本地 deadline（超时）或用户 abort 掐断时置位，
+        // finally 据此先 abort 子会话（取消 provider 端孤儿回合）再 delete。
+        let endedByDeadline = false;
         try {
             const created = await withDeadline(input.client.session.create({ body: { parentID: ctx.sessionID, title: "vision analysis" } }), ctx);
             if (created.error || !created.data) {
@@ -222,12 +281,19 @@ const plugin = async (input, optionsArg) => {
             return { ok: true, text };
         }
         catch (error) {
-            // 异常（超时 / 中止 / 底层抛错）同样收敛为失败结果；aborted 标记交由链循环判断
+            // 异常（超时 / 中止 / 底层抛错）同样收敛为失败结果；aborted 标记交由链循环判断。
+            // 超时与中止都意味着底层请求可能仍在飞 → 需要先 abort 再 delete。
+            endedByDeadline = isDeadlineError(error) || isAbortError(error);
             return { ok: false, error: errText(error), aborted: isAbortError(error) };
         }
         finally {
             if (subID) {
                 subSessions.delete(subID);
+                // 先 abort（best-effort，取消 provider 端孤儿回合）再 delete；
+                // 成功/普通失败路径 turn 已自然结束，无需 abort。
+                if (endedByDeadline) {
+                    await input.client.session.abort({ path: { id: subID } }).catch(() => { });
+                }
                 await input.client.session.delete({ path: { id: subID } }).catch(() => { });
             }
         }
@@ -263,13 +329,45 @@ const plugin = async (input, optionsArg) => {
     /** 描述标签：标注图片文件名与产出描述的模型引用键（basename 运行时按图传入）。 */
     const format = (basename, modelId, text) => `[Image: ${basename} — described by ${modelId}]\n${text}`;
     /**
-     * 下载 http(s) URL 指向的图片并落盘到 <visionDir>/<sha256><ext>：
-     * 与 chat.message 落盘路径一致，内容哈希命名天然去重。
-     * 扩展名不受支持、HTTP 非 2xx、网络失败（含 30 秒下载超时）、超过
-     * 20 MB 下载上限（content-length 预检 + 读后复核）都返回 { error }，
+     * 把图片字节内容原子落盘到**用户级缓存目录**（<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 = 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()}`);
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        try {
+            await fs.writeFile(tmpPath, bytes);
+            await fs.rename(tmpPath, filepath);
+        }
+        catch (error) {
+            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;
+    };
+    /**
+     * 下载 http(s) URL 指向的图片并落盘（内容哈希命名天然去重，写盘细节见
+     * persistImageBytes）。扩展名不受支持、HTTP 非 2xx、网络失败（含 30 秒下载
+     * 超时）、超过 20 MB 下载上限（content-length 预检 + 读后复核）都返回 { error }，
      * 由调用方转成可读的错误文字。
+     *
+     * 中止传导：abort（用户中止）与 30 秒超时共同驱动一个 AbortController——
+     * 中止即刻断请求，不空跑满超时；pre-abort 直接放弃、不发请求。手动组合信号
+     * 而非 AbortSignal.any()：engines node>=18（any 需 18.17+/20.3+），且与
+     * withDeadline 的 addEventListener 风格同构。错误以 AbortError/超时形式落入
+     * catch，统一转可读文字。
      */
-    const downloadImage = async (url) => {
+    const downloadImage = async (url, abort) => {
         try {
             // URL 解析与扩展名提取放在 try 内：畸形 URL 在 new URL 处抛错时，
             // 错误以 "Image download failed" 前缀返回，而不是漏到外层的
@@ -278,24 +376,34 @@ const plugin = async (input, optionsArg) => {
             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" };
+            // pre-abort：已中止则不必发请求，直接以 Aborted 收尾
+            if (abort.aborted)
+                return { error: "Aborted" };
+            const controller = new AbortController();
+            const onAbort = () => controller.abort();
+            abort.addEventListener("abort", onAbort, { once: true });
+            const timer = setTimeout(() => controller.abort(), 30_000);
+            try {
+                // 整个下载（fetch 响应头 + arrayBuffer 读 body）都在同一 guard 内：
+                // 30 秒预算与用户中止都覆盖到 body 读取阶段；收尾再清 timer/listener。
+                const response = await fetch(url, { signal: controller.signal });
+                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" };
+                }
+                return { filepath: await persistImageBytes(bytes, ext) };
             }
-            const bytes = Buffer.from(await response.arrayBuffer());
-            // 复核实际字节数：chunked 等无 content-length 的响应只有读后才能判大小。
-            if (bytes.length > MAX_DOWNLOAD_BYTES) {
-                return { error: "image exceeds 20 MB download limit" };
+            finally {
+                clearTimeout(timer);
+                abort.removeEventListener("abort", onAbort);
             }
-            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) };
@@ -303,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()];
@@ -312,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 循环可以读到原因并
@@ -327,8 +534,11 @@ 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 目录，再统一走磁盘加载路径。
-            const download = /^https?:\/\//i.test(args.image_path) ? await downloadImage(args.image_path) : undefined;
+            // http(s) URL：先下载到用户级 vision 缓存目录，再统一走磁盘加载路径。
+            // ctx.abort 传入下载：用户中止即刻断下载（含 pre-abort 不再发请求）。
+            const download = /^https?:\/\//i.test(args.image_path)
+                ? await downloadImage(args.image_path, ctx.abort)
+                : undefined;
             if (download && "error" in download) {
                 return { title, output: `Image download failed: ${download.error}` };
             }
@@ -354,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）：即便此刻候选链链首
                 // 已与入库模型不同，也保持标签真实、不重写。
@@ -365,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) };
         }
@@ -385,7 +596,7 @@ const plugin = async (input, optionsArg) => {
         if (cached !== undefined)
             return cached;
         try {
-            const result = await input.client.config.providers();
+            const result = await withTimeout(input.client.config.providers(), providersTimeout.ms, `config.providers() timed out after ${providersTimeout.ms}ms`);
             // HTTP 非 2xx 时 openapi-fetch 不抛错而是返回 { error }（data 为空）。
             // 「查询失败」不能缓存成 false——那是一次瞬时故障而非「确认不支持」，
             // 缓存会永久关闭能力门控；本次保守返回 false，下次再重试。
@@ -436,7 +647,7 @@ const plugin = async (input, optionsArg) => {
      */
     const listImageCapableModels = async () => {
         try {
-            const result = await input.client.config.providers();
+            const result = await withTimeout(input.client.config.providers(), providersTimeout.ms, `config.providers() timed out after ${providersTimeout.ms}ms`);
             if (!result.data)
                 return [];
             const found = [];
@@ -466,8 +677,7 @@ const plugin = async (input, optionsArg) => {
         return chain.some((c) => c.providerID === model.providerID && c.modelID === model.modelID);
     };
     /**
-     * 把一个图片 file part 落盘到 <directory>/.opencode/vision/<sha256>.<ext>。
-     * 文件名用内容哈希，天然去重（同一张图多次发送只落一份）。
+     * 把一个图片 file part 落盘（内容哈希命名去重，写盘细节见 persistImageBytes）。
      * 返回落盘信息；MIME 不受支持或 URL 不是 base64 data URL 时返回 undefined。
      */
     const persistImage = async (part) => {
@@ -479,12 +689,7 @@ const plugin = async (input, optionsArg) => {
             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 };
+            return { filepath: await persistImageBytes(bytes, ext) };
         }
         catch {
             // fail-open 原则：图片落盘失败（EACCES/ENOSPC 等）只是少了 vision_analyze

package/package.json

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