opencode-vision-analyze 0.5.0 → 0.6.0

package/README.md

@@ -89,9 +89,34 @@ 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.
+Two **user-level shared caches** live side by side under `<cache>/opencode-vision-analyze/`, shared across sessions, projects and restarts, independent of git scope — 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.
+| Cache | Directory | Content | Naming | Cap |
+|---|---|---|---|---|
+| Images | `vision/` | image bytes | `<sha256>.<ext>` | 2000 entries / 500 MB |
+| Descriptions | `descriptions/` | description text (JSON) | `sha256(key)` | 2000 entries / 50 MB |
+
+**Image storage (`vision/`)**
+
+- **Written to cache**: clipboard images (raw pixels, no source path) and `http(s)` downloads.
+- **Read in place (never copied)**: path-pasted attachments (the message part carries a real `source.path`, e.g. a file path copied to the clipboard) and already-local paths passed straight to the tool — the file is re-read at analysis time, so re-pasting a path always analyses the latest content.
+- **Eviction**: LRU by file mtime; when either 2000 entries or 500 MB is exceeded, the oldest entries are removed.
+- **Concurrency**: atomic temp-file + rename, so concurrent opencode processes can safely share the store.
+
+**Description cache (`descriptions/`)**
+
+- **Key**: `<image-sha>:<effective-question>`, filename `sha256(key)`.
+- **General full-image parse** (empty / omitted `question`): normalised to the fixed prompt `Describe this image in full detail, including all text, UI elements, diagrams, or content visible.`, so every generic parse collapses onto one entry.
+- **Specific follow-ups**: keep their own `<image-sha>:<question>` keys (format unchanged, existing entries keep hitting).
+- **Write threshold**: generic entries are only written when the description is ≥ 100 chars, so a short refuse/fail answer can't poison the shared full-image entry.
+- **Eviction**: LRU by file mtime, capped at 2000 entries / 50 MB; **concurrency** as above.
+
+**Default cache root 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).
 
 ## How it works
 
@@ -102,9 +127,11 @@ 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 user-level vision store
-        (<sha256>.<ext> under <cache>/opencode-vision-analyze/vision;
-         already-local file paths are read in place, never copied)
+     └─ text-only main model → resolve a stable image path:
+        path-pasted attachments use the source path in place (never copied,
+        always the latest file content); clipboard images are persisted to
+        the user-level vision store (<sha256>.<ext> under
+        <cache>/opencode-vision-analyze/vision)
         and inject a synthetic hint (hidden in TUI, visible to model):
         "use the vision_analyze tool with image_path: ..."
 

package/README.zh.md

@@ -89,9 +89,34 @@ 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/` 下，跨会话 / 项目 / 重启共享，与 git 分域无关，无需任何 `.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 进程可安全共享同一描述缓存。
+| 缓存 | 目录 | 内容 | 命名 | 容量上限 |
+|---|---|---|---|---|
+| 图片 | `vision/` | 图片字节 | `<sha256>.<ext>` | 2000 条 / 500MB |
+| 描述 | `descriptions/` | 描述文本（JSON） | `sha256(key)` | 2000 条 / 50MB |
+
+**图片存储（`vision/`）**
+
+- **写入缓存**：剪贴板位图（无源路径）与 `http(s)` 下载。
+- **原位读用（不复制）**：路径粘贴（消息 part 带真实 `source.path`，如复制到剪贴板的文件路径）与模型直接传入的本地文件路径——分析时当场重读，故同一路径每次粘贴都取最新内容。
+- **淘汰**：按文件 mtime LRU；超出 2000 条或 500MB 即删最久未用的条目。
+- **并发安全**：临时文件 + rename 原子写，多个 opencode 进程可安全共享。
+
+**描述缓存（`descriptions/`）**
+
+- **key**：`<图片sha256>:<生效问题>`，文件名取 `sha256(key)`。
+- **泛解析（`question` 空 / 省略）**：归一化到固定文案 `Describe this image in full detail, including all text, UI elements, diagrams, or content visible.`，所有泛解析收敛到同一条。
+- **具体追问**：保留原问句，走各自的 `<图片sha256>:<问题>` key（格式与旧版一致，存量条目照常命中）。
+- **写入门槛**：泛解析条目要求描述 ≥ 100 字符，防止视觉模型敷衍/拒答的短文本毒化共享条目。
+- **淘汰**：按文件 mtime LRU，上限 2000 条 / 50MB；**并发安全**同上。
+
+**平台默认缓存根**
+
+- Linux：`$XDG_CACHE_HOME || ~/.cache`
+- macOS：`~/Library/Caches`（亦接受 `$XDG_CACHE_HOME` 覆盖）
+- Windows：`%LOCALAPPDATA% || ~/AppData/Local`
+- 空串 env 视为未设置，回退默认。
 
 ## 工作原理
 
@@ -102,9 +127,10 @@ curl 方式说明：
      ├─ 主模型支持图片输入 → 不做任何处理（原图直发）
      ├─ 无任何 image-capable 模型 → 不做处理（不注入 hint、不落盘；
      │    交给核心对图片的默认处理）
-     └─ 纯文本主模型 → 图片落盘到用户级 vision 存储
-        （<sha256>.<ext>；位于 <cache>/opencode-vision-analyze/vision；
-         本地已存在文件路径原位读用、不复制）
+     └─ 纯文本主模型 → 解析出稳定 image_path：
+        路径粘贴用源文件路径原位读用（不复制、始终取最新内容）；
+        剪贴板位图落盘到用户级 vision 存储
+        （<sha256>.<ext>；位于 <cache>/opencode-vision-analyze/vision）
         并注入 synthetic 提示（TUI 隐藏、模型可见）：
         "用 vision_analyze 工具查看，image_path: ..."
 

package/dist/index.js

@@ -2,10 +2,12 @@
  * opencode-vision-analyze
  *
  * 为「不具备视觉能力的主模型」提供图片解读路由：当用户在消息中附带图片时，
- * 插件把图片落盘到**用户级共享目录**（<cache>/opencode-vision-analyze/vision，
- * 恒用户级、与 git/非 git 无关），并向模型注入一条 synthetic 提示
- * （TUI 界面隐藏、模型可见），引导它通过 vision_analyze 工具让指定的视觉
- * 模型描述图片。若主模型本身支持图片输入，则不做任何干预，原图直接发给主模型。
+ * 插件解析出一个稳定的图片绝对路径（**路径粘贴**——part 带真实 source.path——
+ * 直接原位读用、不复制；**复制图片本身**（剪贴板位图）等无有效源路径时才落盘到
+ * 用户级共享目录 <cache>/opencode-vision-analyze/vision，恒用户级、与 git/非 git
+ * 无关），并向模型注入一条 synthetic 提示（TUI 界面隐藏、模型可见），引导它通过
+ * vision_analyze 工具让指定的视觉模型描述图片。若主模型本身支持图片输入，则不做
+ * 任何干预，原图直接发给主模型。
  *
  * 工作方式（vision_analyze 工具路径）：主模型调用 vision_analyze 时，插件
  * 创建一个 parentID 挂在当前会话下的临时子会话（不进会话列表、不生成
@@ -20,8 +22,8 @@
  * 泛解析条目是全图共享的，写入前按最短文本长度把关，防一条垃圾描述毒化整图。
  * image_path 除了绝对路径也接受 http(s) URL：先下载落盘到同一用户级 vision
  * 目录（内容哈希命名，天然与附件落盘去重；LRU + 容量上限，2000 条 / 500MB），
- * 再走统一的磁盘加载路径。**本地已存在的文件直接原位读取**（不复制、不 touch），
- * 只有贴图/下载才写缓存。
+ * 再走统一的磁盘加载路径。**路径粘贴与本地已存在的文件直接原位读取**（不复制、
+ * 不 touch，始终读文件最新内容）；只有剪贴板贴图/下载才写缓存。
  * 主模型本身支持图片输入时走快速路径：不做子会话描述，直接把原图作为
  * 工具附件回传给模型自行查看。
  *
@@ -752,6 +754,34 @@ const plugin = async (input, optionsArg) => {
             return undefined;
         }
     };
+    /**
+     * 解析图片 part 的可用绝对路径：
+     * - **路径粘贴**（part 带真实 source.path）：原位读用，不复制进 vision 缓存。相对路径
+     *   以 input.directory 为基准绝对化，与 opencode 工具一致（tool/read.ts 等用
+     *   path.resolve(instance.directory, filepath)）。提示里给绝对路径，vision_analyze
+     *   每次调用当场重读该文件 → 始终分析最新内容；描述缓存按内容 sha，天然不缓存旧内容。
+     * - **复制图片本身**（剪贴板位图，source.path="clipboard"）、无 source、扩展名不受支持、
+     *   文件缺失/为空 → 回退 persistImage 内容寻址落盘（贴图必须给模型稳定 image_path）。
+     * 判定失败一律回退，绝不抛错（fail-open）。
+     */
+    const resolveImagePath = async (part) => {
+        const src = part.source;
+        if (src?.type === "file" && src.path) {
+            const abs = path.isAbsolute(src.path) ? src.path : path.resolve(input.directory, src.path);
+            const ext = path.extname(abs).toLowerCase();
+            if (EXT_MIME[ext]) {
+                try {
+                    const st = await fs.stat(abs);
+                    if (st.isFile() && st.size > 0)
+                        return abs;
+                }
+                catch {
+                    // 缺失/不可读 → 回退落盘
+                }
+            }
+        }
+        return (await persistImage(part))?.filepath;
+    };
     /**
      * chat.message 钩子：用户消息持久化前触发（parts 数组与持久化同引用，
      * push 进去的 part 会一并入库）。
@@ -762,7 +792,8 @@ const plugin = async (input, optionsArg) => {
      * 3. 递归防护——消息模型 ∈ 候选链全体成员（我们的描述子会话）则放行；
      * 4. 能力门控——主模型本身能看图则不注入提示；
      * 5. 空链降级——没有任何可用视觉模型时不注入 hint；
-     * 6. 图片落盘，并注入一条 synthetic text part 引导模型使用 vision_analyze。
+     * 6. 解析图片路径（路径粘贴原位读用、其余落盘），并注入一条 synthetic text part
+     *    引导模型使用 vision_analyze。
      */
     const onChatMessage = async (hookInput, output) => {
         // 记录会话当前模型，供后续 vision_analyze 快速路径与未显式指定 model 的
@@ -789,14 +820,14 @@ const plugin = async (input, optionsArg) => {
         const chain = await resolveChain();
         if (chain.length === 0)
             return;
-        // 每张图落盘并生成两行提示；任何一张落盘失败就跳过该图（不影响其余图片）。
+        // 每张图解析路径并生成两行提示；任一张解析失败就跳过该图（不影响其余图片）。
         const lines = [];
         for (const part of images) {
-            const persisted = await persistImage(part);
-            if (!persisted)
+            const imagePath = await resolveImagePath(part);
+            if (!imagePath)
                 continue;
             lines.push(`[The user attached an image: ${part.filename ?? "image"}]`);
-            lines.push(`[Examine it with the vision_analyze tool using image_path: ${persisted.filepath}]`);
+            lines.push(`[Examine it with the vision_analyze tool using image_path: ${imagePath}]`);
         }
         if (lines.length === 0)
             return;

package/package.json

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