opencode-vision-analyze 0.2.0 → 0.3.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 (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.
 - **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,8 @@ 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
@@ -94,7 +98,8 @@ 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 vision store
+        (<sha256>.<ext>; project-local inside a git repo, user cache otherwise)
         and inject a synthetic hint (hidden in TUI, visible to model):
         "use the vision_analyze tool with image_path: ..."
 
@@ -126,17 +131,12 @@ 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).
+- **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
 
-- [ ] 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
+- [ ] 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>` 落盘（跨会话、同一存储域内天然去重）；描述按 `<图片哈希>:<问题>` 缓存——同图同问题只描述一次。
 - **统一鉴权。** 视觉调用走 opencode 子会话，复用 opencode 已管理的 provider 凭据，无需额外配置 API Key。
 
 ## 安装
@@ -69,6 +69,8 @@ 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
@@ -96,7 +98,8 @@ curl 方式说明：
      ├─ 主模型支持图片输入 → 不做任何处理（原图直发）
      ├─ 无任何 image-capable 模型 → 不做处理（不注入 hint、不落盘；
      │    交给核心对图片的默认处理）
-     └─ 纯文本主模型 → 图片落盘 .opencode/vision/<sha256>.<ext>
+     └─ 纯文本主模型 → 图片落盘到 vision 存储
+        （<sha256>.<ext>；git 项目内 → 项目目录，非 git → 用户缓存目录）
         并注入 synthetic 提示（TUI 隐藏、模型可见）：
         "用 vision_analyze 工具查看，image_path: ..."
 
@@ -128,17 +131,12 @@ vision_analyze 工具：
 ## 已知限制
 
 - **仅 V1 会话流** —— 钩子挂在 V1 `SessionPrompt` 路径上；若 opencode 默认交互切到 V2 会话核心，钩子不会触发（且不报错）。
-- **SSRF 面** —— URL 下载跟随重定向、不拦截私网/云元数据地址。本地单用户 CLI 信任级别下可接受；多租户环境使用前应加地址过滤。
-- **中止不传导** —— 用户中止不会取消进行中的下载/子会话请求，它们会跑到各自的 deadline（下载 30 秒、子会话 `timeout_ms`）。超时/中止后子会话虽被删除，但 provider 端的孤儿回合仍可能计费。
 - **历史图片** —— 插件启用之前发送的图片无法被描述（无提示、磁盘上无路径）。
-- **缓存无上限** —— 图片存储与描述缓存均不淘汰（进程级 / 项目目录级）。
+- **缓存无上限** —— 图片存储与描述缓存均不淘汰（图片存储：git 项目级 / 用户级缓存目录；描述缓存：进程级）。
 
 ## Roadmap
 
-- [ ] 能力查询（`config.providers()`）加超时保护
-- [ ] 超时路径先中止子会话（`/session/{id}/abort`）再删除
-- [ ] 描述缓存 LRU / 容量上限
-- [ ] URL 下载可选私网地址拦截
+- [ ] 描述缓存按内容 sha 落盘持久化（含 LRU / 容量上限）
 - [ ] 区域裁剪（放大查看图片细节）
 
 ## 开发

package/dist/index.d.ts

@@ -1,4 +1,30 @@
 import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * `config.providers()` 能力查询的超时预算（毫秒）。做成可改写对象（而非常量/选项）：
+ * 避免选项膨胀；测试把 ms 调小即可缩短等待（TS 不允许对 import 的 let 绑定赋值）。
+ */
+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。
+ * 空字符串 env 视为未设置（XDG/LOCALAPPDATA 官规：空值=未设置）——避免把 "" 当
+ * 有效根导致 path.join("",…) 产出相对路径、相对进程 cwd 落盘。
+ * darwin 亦接受 $XDG_CACHE_HOME 覆盖（跨平台统一 dotfiles 的宽容超集）。
+ */
+export declare function userVisionCacheRoot(env: Record<string, string | undefined>, platform: string, home: string): string;
+/**
+ * 图片存储根：与 opencode 的项目/全局语义对齐——
+ * git 项目内 → <项目>/.opencode/vision（现状）；非 git 目录 → 用户级缓存目录。
+ * 解析一次即可（纯函数，入参可注入以便三平台与 env 覆盖的单测）。
+ */
+export declare function resolveVisionDir(inputDir: string, env: Record<string, string | undefined>, platform: string, home: string): string;
 declare const _default: {
     id: string;
     server: Plugin;

package/dist/index.js

@@ -2,33 +2,10 @@
  * 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 递归防护以整链成员为集。
+ * 插件把图片落盘到 vision 目录（git 项目内 → <项目>/.opencode/vision；
+ * 非 git 目录 → 用户级缓存目录），并向模型注入一条 synthetic 提示
+ * （TUI 界面隐藏、模型可见），引导它通过 vision_analyze 工具让指定的视觉
+ * 模型描述图片。若主模型本身支持图片输入，则不做任何干预，原图直接发给主模型。
  *
  * 工作方式（vision_analyze 工具路径）：主模型调用 vision_analyze 时，插件
  * 创建一个 parentID 挂在当前会话下的临时子会话（不进会话列表、不生成
@@ -43,17 +20,13 @@
  * 类型依赖仅 @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 { existsSync } from "node:fs";
 import fs from "node:fs/promises";
+import { homedir } from "node:os";
 import path from "node:path";
 /** 支持的图片扩展名 → MIME 类型（vision_analyze 加载磁盘图片时使用） */
 const EXT_MIME = {
@@ -70,6 +43,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 +73,46 @@ const VISION_SYSTEM_PROMPT = [
 ].join("\n");
 /** 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。
+ * 空字符串 env 视为未设置（XDG/LOCALAPPDATA 官规：空值=未设置）——避免把 "" 当
+ * 有效根导致 path.join("",…) 产出相对路径、相对进程 cwd 落盘。
+ * darwin 亦接受 $XDG_CACHE_HOME 覆盖（跨平台统一 dotfiles 的宽容超集）。
+ */
+export function userVisionCacheRoot(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");
+}
+/**
+ * 图片存储根：与 opencode 的项目/全局语义对齐——
+ * git 项目内 → <项目>/.opencode/vision（现状）；非 git 目录 → 用户级缓存目录。
+ * 解析一次即可（纯函数，入参可注入以便三平台与 env 覆盖的单测）。
+ */
+export function resolveVisionDir(inputDir, env, platform, home) {
+    if (isInsideGitRepo(inputDir))
+        return path.join(path.resolve(inputDir), ".opencode", "vision");
+    return userVisionCacheRoot(env, platform, home);
+}
 /**
  * http(s) 下载图片的大小上限（20 MB）。提示注入可让模型指向超大图片，
  * 下载不限长是成本/健壮性放大器：先按 content-length 头提前拒绝，
@@ -151,33 +180,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 +233,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 +270,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 +318,41 @@ 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 }，
+     * 把图片字节内容原子落盘并返回最终 filepath。每次调用现算存储根
+     * （git 项目 → 项目 .opencode/vision；非 git → 用户级缓存，见 resolveVisionDir）：
+     * 运行中存储范围变化（如 git init）从下一条图片起即时生效，无需重启。
+     * 先写 `<sha><ext>.tmp-<uuid>` 再 rename：共享目录（用户级/多实例）并发写同一 sha
+     * 时内容寻址下原子幂等；失败先清理临时文件再抛错，避免孤儿 tmp 累积。
+     */
+    const persistImageBytes = async (bytes, ext) => {
+        const dir = resolveVisionDir(input.directory, 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;
+        }
+        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 +361,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) };
@@ -328,7 +421,10 @@ const plugin = async (input, optionsArg) => {
         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;
+            // 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}` };
             }
@@ -385,7 +481,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 +532,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 +562,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 +574,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.3.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",