feat(1.5.0): P1-2 expand NATIVE_VISION (pixtral, llama, doubao, etc.), P1-5 README sync, P2-1 type assertions, P2-7 unit tests (68 pass), P2-8 install.js writes opencode.json, P2-9 uninstall cleans tmp dir, P2-10 empty path filter

Author: JochenYang

README.md

@@ -47,17 +47,25 @@ npx @jochenyang/opencode-vision --uninstall
 用户粘贴图片 + "这是什么？"
   ↓
 vision-helper 插件 (experimental.chat.messages.transform)
-  ├─ 解 base64 → 保存到临时目录
-  ├─ 用简短占位替换原始图片部分（消除不支持的模型的 ERROR 噪音）
-  └─ 路径提示注入到用户文本前
+  ├─ 检查当前模型是否原生多模态 → 是则跳过（直接看图）
+  ├─ 检查是否在压缩/总结阶段 → 是则跳过
+  ├─ 解 base64 → 计算 MD5 → 复用/分配 image{N} 序号
+  ├─ 保存到 tmp/opencode-vision/image{N}/{hash}.{ext}
+  ├─ 用简短占位替换原始图片 part（消除 ERROR 噪音）
+  ├─ 注入路径提示（vision tool 引导）
+  └─ 清理上次 transform 注入的 hint（防累积）
   ↓
 模型看到路径提示 → 自动调用 vision 工具
   ↓
-vision 工具调用视觉 API 返回图片描述
+vision 工具：
+  ├─ 路径沙箱校验（必须在 TMP_DIR 下，必须是图片扩展名）
+  ├─ base64 编码 → 调视觉 API
+  └─ 返回描述
 ```
 
 - **单图** → 模型调用 `vision(path)` 读取单张图片
 - **多图** → 模型调用 `vision(paths=[...])` 一次 API 调用处理全部图片
+- **原生多模态模型**（如 GPT-4o、MiniMax-M3、Qwen3.5+、Kimi K2.5+）→ 自动跳过插件，原生看图
 
 ## 前置要求
 
@@ -67,12 +75,15 @@ vision 工具调用视觉 API 返回图片描述
 
 ## 环境变量
 
-| 变量               | 说明                                   | 示例值                                                        |
+| 变量               | 说明                                   | 默认值 / 示例                                                        |
 | ------------------ | -------------------------------------- | ------------------------------------------------------------- |
 | `VISION_API_KEY`   | 视觉 API 的密钥                        | `sk-your-api-key`                                              |
 | `VISION_API_URL`   | 视觉 API 的基础地址                     | `https://your-api-endpoint/v1`                                 |
 | `VISION_MODEL`     | 视觉模型名称<br>（MiniMax 无需设置）    | `your-vision-model`                                            |
 | `VISION_API_TYPE`  | 可选，强制指定 API 类型<br>`openai` / `minimax` | `minimax`                                           |
+| `VISION_MAX_TOKENS` | 可选，视觉 API 返回的最大 token 数    | `4096`                                                          |
+| `VISION_FETCH_TIMEOUT_MS` | 可选，视觉 API fetch 超时毫秒数 | `60000`                                                         |
+| `VISION_MAX_IMAGES` | 可选，LRU 保留的最大图片数            | `200`                                                           |
 
 > `VISION_API_URL`：OpenAI 兼容接口会自动补全 `/chat/completions`；MiniMax 会自动使用 `/v1/coding_plan/vlm` 端点。
 >
@@ -194,10 +205,12 @@ opencode-vision/
 
 ## 注意事项
 
-- 图片保存到系统临时目录 `os.tmpdir()/opencode-vision/`，重启系统后自动清理
-- 临时文件以 `pasted-{timestamp}-{random}.{ext}` 命名
-- 同一会话中多次粘贴同一张图会产生多个临时文件
-- 视觉 API 调用使用 `max_tokens: 4096`，多图场景下足够返回详细描述
+- 图片保存到系统临时目录 `os.tmpdir()/opencode-vision/image{N}/{hash}.{ext}`（N 为全局序号）
+- 同一会话中**同一张图**通过 MD5 内容哈希去重，**不会**重复写盘
+- **LRU 清理**：默认保留最近 200 张图片（可通过 `VISION_MAX_IMAGES` 环境变量调整）
+- 视觉 API 调用使用 `max_tokens: 4096`（可通过 `VISION_MAX_TOKENS` 调整）
+- 视觉 API fetch 默认 60s 超时（可通过 `VISION_FETCH_TIMEOUT_MS` 调整）
+- **多模态模型自动原生识图**：GPT-4o+/Claude 3+/Gemini/MiniMax-M3/Qwen3.5+/Kimi K2.5+ 等模型无需配置视觉 API，插件会自动跳过
 
 ## 自定义视觉 API
 

bin/install.js

@@ -122,6 +122,11 @@ async function doInstall() {
     log("未检测到 OpenCode — 请先安装 https://github.com/opencode-ai/opencode", false)
   }
 
+  // P2-8: offer to write env vars into opencode.json so users don't have to restart
+  if (missing > 0) {
+    await offerWriteOpencodeJson()
+  }
+
   title("安装完成")
   console.log("  ✅ 文件已就位，重启 OpenCode 后即可使用。")
   if (missing > 0) {
@@ -132,6 +137,79 @@ async function doInstall() {
   console.log('     "[图片] 这是什么？"')
 }
 
+/**
+ * P2-8: 交互式询问是否将环境变量写入 ~/.config/opencode/opencode.json 的 env 字段。
+ * 这样用户不需要重启终端或系统就能让变量生效。
+ */
+async function offerWriteOpencodeJson() {
+  const configPath = path.join(DST, "opencode.json")
+  title("opencode.json 写入选项")
+  console.log("  检测到环境变量未完整配置。")
+  console.log("  可以直接将变量写入 ~/.config/opencode/opencode.json（无需重启终端）。")
+  console.log()
+  console.log("  \x1b[36m写入内容预览：\x1b[0m")
+  const preview = {
+    env: {
+      VISION_API_KEY: "<your-key-here>",
+      VISION_API_URL: "<your-api-url-here>",
+      ...(process.env["VISION_API_TYPE"] ? { VISION_API_TYPE: process.env["VISION_API_TYPE"] } : {}),
+    },
+  }
+  console.log("  " + JSON.stringify(preview, null, 2).split("\n").join("\n  "))
+  console.log()
+
+  const readline = require("readline")
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await new Promise((resolve) =>
+    rl.question("  写入 opencode.json? [y/N] ", (ans) => {
+      rl.close()
+      resolve(ans)
+    }),
+  )
+
+  if (!/^y(es)?$/i.test(answer.trim())) {
+    console.log("  跳过写入，请手动设置环境变量。")
+    return
+  }
+
+  // Read or init config
+  let config = {}
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, "utf8"))
+    } catch (err) {
+      log(`无法读取 ${configPath}: ${err.message}，请手动备份后重试`, false)
+      return
+    }
+  }
+  config.env = config.env || {}
+
+  // For each missing env var, prompt for a value
+  const readline2 = require("readline")
+  const rl2 = readline2.createInterface({ input: process.stdin, output: process.stdout })
+  for (const v of ENV_VARS) {
+    if (process.env[v.name]) continue
+    const val = await new Promise((resolve) =>
+      rl2.question(`  ${v.name}: `, (ans) => resolve(ans.trim())),
+    )
+    if (val) {
+      config.env[v.name] = val
+      log(`已记录 ${v.name}`)
+    }
+  }
+  rl2.close()
+
+  // Write back with a .bak backup
+  if (fs.existsSync(configPath)) {
+    fs.copyFileSync(configPath, configPath + ".bak")
+  }
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n")
+  log(`已写入 ${path.relative(os.homedir(), configPath)}`)
+  if (fs.existsSync(configPath + ".bak")) {
+    log(`原文件已备份到 ${path.basename(configPath)}.bak`)
+  }
+}
+
 async function doUninstall() {
   title("opencode-vision 卸载")
 
@@ -153,6 +231,17 @@ async function doUninstall() {
     }
   }
 
+  // P2-9: clean up the temp directory containing cached images (user privacy)
+  const tmpDir = path.join(os.tmpdir(), "opencode-vision")
+  if (fs.existsSync(tmpDir)) {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+      log(`已清理临时目录 ${path.relative(os.tmpdir(), tmpDir)}/* (含缓存图片)`)
+    } catch (err) {
+      log(`清理临时目录失败: ${err.message}`, false)
+    }
+  }
+
   title("卸载完成")
   if (removed > 0) {
     console.log("  已删除 opencode-vision 相关文件。")

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jochenyang/opencode-vision",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Vision plugin + tool for OpenCode — automatically handles pasted images for non-vision models",
   "keywords": [
     "opencode",

plugins/vision-helper.ts

@@ -33,7 +33,30 @@ function touchLRU(seqDir: string) {
 // Regex matching models with native multimodal (image) support.
 // Matched models → skip the transform, let OpenCode's native pipeline handle the image.
 // Non-matched models → fall through to the vision tool.
-const NATIVE_VISION = /gpt-|o[0-9]|claude-|gemini-|qwen3\.(5|6)|qwen-vl|qwen2-5-vl|qwen3-vl|qwen-omni|qvq-max|kimi-k2\.(5|6)|minimax-m3|minimax-vl|glm-[0-9.]+v|mimo-v2-omni|mimo-v2\.5$|yi-vl|deepseek-vl2/i
+//
+// Coverage:
+//   Foreign  : GPT-4o+, o1/o3/o4+, Claude 3/4/5, Gemini, Pixtral, Llama 3.2 Vision, Nova Vision
+//   Alibaba  : Qwen VL/Omni series, Qwen 3.5/3.6, QVQ-Max
+//   Kimi     : kimi-k2.5, kimi-k2.6
+//   MiniMax  : MiniMax-M3, MiniMax-VL-*
+//   GLM      : glm-*v (with "v" suffix = vision variant)
+//   Xiaomi   : mimo-v2-omni, mimo-v2.5
+//   Yi       : yi-vl-*
+//   DeepSeek : deepseek-vl2 (SiliconFlow hosted)
+//   Doubao   : doubao-*-vision
+//   InternVL : internvl*
+//   Seed     : seed-*-vision
+//
+// Note on Qwen 3.5/3.6: NOT followed by `-max`/`-max-preview` (which are text-only).
+//   Match: qwen3.5-plus, qwen3.6-flash, qwen3.6-plus, qwen3.5-flash
+//   Skip : qwen3.6-max-preview (text), qwen3.7-max (text), qwen3-max (text)
+// Foreign: GPT/o[0-9]/Claude/Gemini/Pixtral/Llama 3.2 Vision/Nova Vision
+// Qwen VL family: matches qwen-vl-*, qwen2-vl-*, qwen2.5-vl-*, qwen3-vl-*, qwen-omni-*, qvq-max
+//   The "qwen-vl" branch handles the no-version-number case; the numbered branch
+//   matches qwen2/2.5/3 with optional separator variants (-/_/.)
+// Qwen 3.5/3.6 multimodal series: qwen3.5-plus, qwen3.5-flash, qwen3.6-plus, qwen3.6-flash
+//   Negative lookahead (?!-max) excludes text-only qwen3.6-max-preview / qwen3.7-max / qwen3-max
+const NATIVE_VISION = /gpt-|o[0-9]|claude-|gemini-|pixtral|llama-3\.2.*vision|nova-.*vision|qwen3\.[56](?!-max)|qwen(?:-vl|2[._-]?5?[._-]?vl)|qwen2-vl|qwen3-vl|qwen-omni|qvq-max|kimi-k2\.(5|6)|minimax-m3|minimax-vl|glm-[0-9.]+v|mimo-v2-omni|mimo-v2\.5$|yi-vl|deepseek-vl2|doubao-.*vision|seed-.*vision|internvl/i
 
 /**
  * Hook runs just before messages are sent to the model. Detects image attachments in
@@ -131,16 +154,16 @@ export default (async () => {
           msg.parts.splice(index, 1, {
             type: "text",
             text: `[vision: image${seq}/${name}]`,
-          } as never)
+          } as { type: "text"; text: string })
         }
 
         // Build path hint(s) for the model to use the vision tool
         const hints = saved.length === 1
           ? `[Image #${saved[0].seq} auto-saved to ${path.join(TMP_DIR, `image${saved[0].seq}`, saved[0].name)} — use the vision tool to read it]`
           : `[Images auto-saved to:\n${saved.map((s) => `  ${path.join(TMP_DIR, `image${s.seq}`, s.name)}`).join("\n")}\n— use the vision tool with paths=[...] to read them all at once]`
 
-        ;(msg.parts as unknown as Record<string, unknown>[]).push({
-          type: "text" as const,
+        msg.parts.push({
+          type: "text",
           text: hints,
         })
       }

tests/native-vision.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test"
+
+// Mirror the NATIVE_VISION regex from the plugin so we can test the matching logic
+// without importing the plugin module (which has side effects on load).
+const NATIVE_VISION = /gpt-|o[0-9]|claude-|gemini-|pixtral|llama-3\.2.*vision|nova-.*vision|qwen3\.[56](?!-max)|qwen(?:-vl|2[._-]?5?[._-]?vl)|qwen2-vl|qwen3-vl|qwen-omni|qvq-max|kimi-k2\.(5|6)|minimax-m3|minimax-vl|glm-[0-9.]+v|mimo-v2-omni|mimo-v2\.5$|yi-vl|deepseek-vl2|doubao-.*vision|seed-.*vision|internvl/i
+
+describe("NATIVE_VISION regex", () => {
+  // Should match (native multimodal)
+  const yesCases: Array<[string, string]> = [
+    ["gpt-5.4", "OpenAI latest"],
+    ["gpt-4o", "OpenAI 4o"],
+    ["gpt-4o-mini", "OpenAI 4o mini"],
+    ["gpt-5-codex", "OpenAI codex"],
+    ["o4-mini", "OpenAI o-series"],
+    ["o1", "OpenAI o1"],
+    ["claude-sonnet-4-6", "Anthropic sonnet"],
+    ["claude-3-5-sonnet", "Anthropic 3.5"],
+    ["claude-opus-4-6", "Anthropic opus"],
+    ["gemini-2.5-pro", "Google gemini"],
+    ["gemini-3-pro", "Google gemini 3"],
+    ["pixtral-12b", "Mistral pixtral"],
+    ["llama-3.2-90b-vision", "Meta llama 3.2 vision"],
+    ["llama-3.2-11b-vision", "Meta llama 3.2 vision"],
+    ["nova-pro-vision", "AWS nova vision"],
+    ["qwen3.5-plus", "Qwen 3.5 plus"],
+    ["qwen3.6-flash", "Qwen 3.6 flash"],
+    ["qwen-vl-max", "Qwen VL max"],
+    ["qwen2-5-vl-72b-instruct", "Qwen 2.5 VL"],
+    ["qwen2-vl-7b", "Qwen 2 VL"],
+    ["qwen3-vl-30b", "Qwen 3 VL"],
+    ["qwen-omni-turbo", "Qwen omni"],
+    ["qvq-max", "Qwen QVQ"],
+    ["kimi-k2.5", "Kimi 2.5"],
+    ["kimi-k2.6", "Kimi 2.6"],
+    ["moonshotai/Kimi-K2.5", "Kimi prefixed"],
+    ["MiniMax-M3", "MiniMax M3 (case-insensitive)"],
+    ["minimax-m3", "MiniMax M3 lower"],
+    ["minimax-vl-01", "MiniMax VL"],
+    ["glm-4.5v", "GLM 4.5 vision"],
+    ["glm-4.6v", "GLM 4.6 vision"],
+    ["glm-5v-turbo", "GLM 5 vision turbo"],
+    ["mimo-v2-omni", "Xiaomi MiMo omni"],
+    ["mimo-v2.5", "Xiaomi MiMo 2.5"],
+    ["yi-vl-6b", "Yi VL"],
+    ["deepseek-vl2", "DeepSeek VL2"],
+    ["Qwen/Qwen2.5-VL-72B-Instruct", "Qwen with org prefix"],
+    ["doubao-1-5-vision-pro", "Doubao vision"],
+    ["seed-1-6-vision", "Seed vision"],
+    ["internvl2.5", "InternVL"],
+  ]
+
+  for (const [id, desc] of yesCases) {
+    test(`matches native vision: ${id} (${desc})`, () => {
+      expect(NATIVE_VISION.test(id.toLowerCase())).toBe(true)
+    })
+  }
+
+  // Should NOT match (text-only, fall back to vision tool)
+  const noCases: Array<[string, string]> = [
+    ["deepseek-v4-flash", "DeepSeek V4 Flash"],
+    ["deepseek-v4-pro", "DeepSeek V4 Pro"],
+    ["deepseek-r1", "DeepSeek R1"],
+    ["deepseek-chat", "DeepSeek chat"],
+    ["MiniMax-M2.7", "MiniMax M2.7"],
+    ["MiniMax-M2.5", "MiniMax M2.5"],
+    ["MiniMax-M2", "MiniMax M2"],
+    ["qwen3-max", "Qwen 3 max"],
+    ["qwen3.7-max", "Qwen 3.7 max"],
+    ["qwen3.6-max-preview", "Qwen 3.6 max preview"],
+    ["qwen-plus", "Qwen plus"],
+    ["qwen-flash", "Qwen flash"],
+    ["qwen-turbo", "Qwen turbo"],
+    ["qwen3-32b", "Qwen 3 32B"],
+    ["qwen3-235b-a22b", "Qwen 3 235B"],
+    ["qwen3-coder-plus", "Qwen coder"],
+    ["glm-4.5", "GLM 4.5"],
+    ["glm-4.6", "GLM 4.6"],
+    ["glm-4.7", "GLM 4.7"],
+    ["glm-5", "GLM 5"],
+    ["glm-5.1", "GLM 5.1"],
+    ["mimo-v2-flash", "MiMo 2 flash"],
+    ["mimo-v2-pro", "MiMo 2 pro"],
+    ["mimo-v2.5-pro", "MiMo 2.5 pro"],
+    ["kimi-k2-thinking", "Kimi thinking"],
+    ["kimi-k2-turbo", "Kimi turbo"],
+    ["step-1-32k", "Step 1"],
+    ["step-3.5-flash", "Step 3.5"],
+  ]
+
+  for (const [id, desc] of noCases) {
+    test(`does NOT match (text-only): ${id} (${desc})`, () => {
+      expect(NATIVE_VISION.test(id.toLowerCase())).toBe(false)
+    })
+  }
+})