@jochenyang/opencode-vision 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,45 @@
-# opencode-vision
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo.svg">
+    <img src="assets/logo.svg" width="64" alt="opencode-vision logo">
+  </picture>
+</p>
+<h1 align="center">opencode-vision</h1>
+<p align="center">
+  🌐 <a href="README_en.md">English</a> · <strong>中文</strong>
+</p>
+<p align="center">
+  让不支持多模态的 OpenCode 模型也能「看懂」图片
+  <br />
+  自动存图 → 引导模型调用 vision 工具 → 返回描述
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@jochenyang/opencode-vision">
+    <img src="https://img.shields.io/npm/v/@jochenyang/opencode-vision?style=flat-square" alt="npm version">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License">
+  </a>
+  <a href="https://github.com/JochenYang/opencode-vision">
+    <img src="https://img.shields.io/github/stars/JochenYang/opencode-vision?style=flat-square" alt="GitHub stars">
+  </a>
+</p>
+
+---
+
+### ✨ 一行命令安装
 
-为 [OpenCode](https://github.com/opencode-ai/opencode) 提供视觉识别能力的插件 + 工具。
+```bash
+npx @jochenyang/opencode-vision
+```
 
-当模型本身不支持多模态输入时，自动将用户粘贴的图片保存到临时目录，并引导模型调用 vision 工具进行识别。支持单图和多图。
+卸载同样简单：
+
+```bash
+npx @jochenyang/opencode-vision --uninstall
+```
+
+---
 
 ## 原理
 
@@ -74,10 +111,14 @@ OpenCode 会自动发现 `~/.config/opencode/tools/` 和 `~/.config/opencode/plu
 
 > 如果对应目录不存在，手动创建即可。
 
-### 通过 npx（即将支持）
+### 通过 npx
 
 ```bash
-npx opencode-vision install
+# 安装
+npx @jochenyang/opencode-vision
+
+# 卸载
+npx @jochenyang/opencode-vision --uninstall
 ```
 
 ## 验证
@@ -145,4 +186,4 @@ $env:VISION_MODEL = 'your-vision-model'
 
 ## 许可证
 
-MIT
+[MIT](LICENSE)

package/README_en.md

@@ -0,0 +1,210 @@
+<p align="center">
+  🌐 <strong>English</strong> · <a href="README.md">中文</a>
+</p>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo.svg">
+    <img src="assets/logo.svg" width="64" alt="opencode-vision logo">
+  </picture>
+</p>
+<h1 align="center">opencode-vision</h1>
+<p align="center">
+  🌐 <strong>English</strong> · <a href="README.md">中文</a>
+</p>
+<p align="center">
+  Let non-vision OpenCode models "see" pasted images
+  <br />
+  Auto-saves images → guides model to call vision tool → returns description
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@jochenyang/opencode-vision">
+    <img src="https://img.shields.io/npm/v/@jochenyang/opencode-vision?style=flat-square" alt="npm version">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License">
+  </a>
+  <a href="https://github.com/JochenYang/opencode-vision">
+    <img src="https://img.shields.io/github/stars/JochenYang/opencode-vision?style=flat-square" alt="GitHub stars">
+  </a>
+</p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/@jochenyang/opencode-vision">
+      <img src="https://img.shields.io/npm/v/@jochenyang/opencode-vision?style=flat-square" alt="npm version">
+    </a>
+    <a href="LICENSE">
+      <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License">
+    </a>
+    <a href="https://github.com/JochenYang/opencode-vision">
+      <img src="https://img.shields.io/github/stars/JochenYang/opencode-vision?style=flat-square" alt="GitHub stars">
+    </a>
+  </p>
+</p>
+
+---
+
+### ✨ One-line install
+
+```bash
+npx @jochenyang/opencode-vision
+```
+
+Uninstall:
+
+```bash
+npx @jochenyang/opencode-vision --uninstall
+```
+
+---
+
+## How It Works
+
+```
+User pastes image + "What is this?"
+  ↓
+vision-helper plugin (experimental.chat.messages.transform)
+  ├─ Decode base64 → save to temp directory
+  ├─ Replace original image part with a short placeholder (remove ERROR noise from unsupportedParts)
+  └─ Inject path hint before user's text
+  ↓
+Model sees the path hint → automatically calls the vision tool
+  ↓
+vision tool calls the vision API → returns image description
+```
+
+- **Single image** → model calls `vision(path)` to read one image
+- **Multiple images** → model calls `vision(paths=[...])` to process all at once
+
+## Prerequisites
+
+- [OpenCode](https://github.com/opencode-ai/opencode) installed
+- An OpenAI-compatible vision API (e.g., Aliyun DashScope, OpenAI, etc.)
+- Environment variables configured (recommended system-wide)
+
+## Environment Variables
+
+| Variable          | Description                                            | Example                         |
+| ----------------- | ------------------------------------------------------ | ------------------------------- |
+| `VISION_API_KEY`  | Vision API key                                         | `sk-your-api-key`               |
+| `VISION_API_URL`  | Vision API base URL<br>(tool auto-appends `/chat/completions`) | `https://your-api-endpoint/v1`  |
+| `VISION_MODEL`    | Vision model name                                      | `your-vision-model`             |
+
+### Windows (System-wide)
+
+```powershell
+[System.Environment]::SetEnvironmentVariable('VISION_API_KEY', 'sk-your-api-key', 'User')
+[System.Environment]::SetEnvironmentVariable('VISION_API_URL', 'https://your-api-endpoint/v1', 'User')
+[System.Environment]::SetEnvironmentVariable('VISION_MODEL', 'your-vision-model', 'User')
+```
+
+**Restart your terminal** after setting.
+
+### macOS / Linux
+
+Add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export VISION_API_KEY="sk-your-api-key"
+export VISION_API_URL="https://your-api-endpoint/v1"
+export VISION_MODEL="your-vision-model"
+```
+
+## Installation
+
+### Manual
+
+Copy the two files to OpenCode's global config directory:
+
+```bash
+# Tool
+cp tools/vision.ts ~/.config/opencode/tools/
+
+# Plugin
+cp plugins/vision-helper.ts ~/.config/opencode/plugins/
+```
+
+OpenCode auto-discovers files under `~/.config/opencode/tools/` and `~/.config/opencode/plugins/` — **no need to modify `opencode.json`**.
+
+> Create the directories if they don't exist.
+
+### Via npx
+
+```bash
+# Install
+npx @jochenyang/opencode-vision
+
+# Uninstall
+npx @jochenyang/opencode-vision --uninstall
+```
+
+## Verification
+
+Start OpenCode:
+
+```bash
+opencode
+```
+
+Paste an image and ask:
+
+```
+[Image] What is this?
+```
+
+Expected behavior:
+
+1. The model cannot read the image directly (doesn't support multimodal)
+2. The plugin saves the image to temp and injects a path hint
+3. The model automatically calls the `vision` tool
+4. The model returns an image description
+
+## Project Structure
+
+```
+opencode-vision/
+├── tools/
+│   └── vision.ts          # Vision tool — calls the vision API
+├── plugins/
+│   └── vision-helper.ts   # Plugin — saves images, injects hints, removes ERROR noise
+├── bin/
+│   └── install.js         # CLI install/uninstall script
+├── package.json
+├── README.md
+├── README_en.md
+└── LICENSE
+```
+
+### Tool: `tools/vision.ts`
+
+- Reads local image files and describes them via a vision API
+- Supports `path` (single) and `paths` (multiple) parameters
+- Compatible with any OpenAI Chat Completions API
+
+### Plugin: `plugins/vision-helper.ts`
+
+- Hook: `experimental.chat.messages.transform`
+- Processes right before the message is sent to the model
+- Saves images to `os.tmpdir()/opencode-vision/`
+- Injects path hints before user text (not persisted to chat history)
+- Replaces original image parts to prevent ERROR noise from `unsupportedParts`
+
+## Notes
+
+- Images are saved to the system temp directory `os.tmpdir()/opencode-vision/` — automatically cleaned on reboot
+- Temp files are named `pasted-{timestamp}-{random}.{ext}`
+- Same image pasted multiple times in one session creates separate temp files
+- Vision API calls use `max_tokens: 4096`, sufficient for detailed multi-image descriptions
+
+## Custom Vision API
+
+Compatible with any OpenAI Chat Completions vision API. Just change the environment variables:
+
+```bash
+export VISION_API_KEY="sk-your-api-key"
+export VISION_API_URL="https://your-api-endpoint/v1"
+export VISION_MODEL="your-vision-model"
+```
+
+## License
+
+[MIT](LICENSE)

package/assets/logo.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48" fill="none">
+  <!-- Magnifying glass circle -->
+  <circle cx="20" cy="20" r="12" stroke="#6366f1" stroke-width="3" fill="none"/>
+  <!-- Magnifying glass handle -->
+  <line x1="29" y1="29" x2="40" y2="40" stroke="#6366f1" stroke-width="3.5" stroke-linecap="round"/>
+  <!-- Eye inside -->
+  <path d="M13 20c0-3.3 2.7-6 6-6s6 2.7 6 6-2.7 6-6 6-6-2.7-6-6z" stroke="#6366f1" stroke-width="1.5" fill="none"/>
+  <circle cx="19" cy="20" r="2.5" fill="#6366f1"/>
+  <!-- Small sparkle dots -->
+  <circle cx="8" cy="8" r="1.5" fill="#a5b4fc"/>
+  <circle cx="36" cy="10" r="1" fill="#a5b4fc"/>
+  <circle cx="42" cy="30" r="1.2" fill="#a5b4fc"/>
+</svg>

package/bin/install.js

@@ -5,12 +5,19 @@ const os = require("os")
 
 const SRC = path.join(__dirname, "..")
 const DST = path.join(os.homedir(), ".config", "opencode")
+const isWin = process.platform === "win32"
 
 const FILES = [
   ["tools/vision.ts", "tools/vision.ts"],
   ["plugins/vision-helper.ts", "plugins/vision-helper.ts"],
 ]
 
+const ENV_VARS = [
+  { name: "VISION_API_KEY", desc: "视觉 API 密钥 / Vision API key", example: "sk-your-api-key" },
+  { name: "VISION_API_URL", desc: "视觉 API 地址 / Vision API base URL", example: "https://your-api-endpoint/v1" },
+  { name: "VISION_MODEL", desc: "视觉模型名称 / Vision model name", example: "your-vision-model" },
+]
+
 function log(msg, ok = true) {
   const prefix = ok ? "\x1b[32m ✓\x1b[0m" : "\x1b[31m ✗\x1b[0m"
   console.log(`${prefix} ${msg}`)
@@ -20,45 +27,82 @@ function title(msg) {
   console.log(`\n\x1b[36m═══ ${msg} \x1b[0m\n`)
 }
 
+function printEnvGuide() {
+  console.log("\n  你需要设置以下环境变量才能使用视觉识别功能：")
+  console.log()
+
+  for (const v of ENV_VARS) {
+    console.log(`    \x1b[33m${v.name}\x1b[0m`)
+    console.log(`    → ${v.desc}`)
+    console.log(`    → 示例: ${v.example}`)
+    console.log()
+  }
+
+  if (isWin) {
+    console.log("  \x1b[36mWindows 系统级配置（管理员 PowerShell）：\x1b[0m")
+    console.log()
+    for (const v of ENV_VARS) {
+      console.log(`    [System.Environment]::SetEnvironmentVariable('${v.name}', '${v.example}', 'User')`)
+    }
+    console.log()
+    console.log("  设置后重启终端生效。")
+  } else {
+    console.log("  \x1b[36mmacOS / Linux 配置（添加到 ~/.zshrc 或 ~/.bashrc）：\x1b[0m")
+    console.log()
+    for (const v of ENV_VARS) {
+      console.log(`    export ${v.name}="${v.example}"`)
+    }
+    console.log()
+    console.log("  然后执行 source ~/.zshrc 或重启终端。")
+  }
+}
+
+async function checkVars() {
+  let missing = 0
+  for (const v of ENV_VARS) {
+    const val = process.env[v.name]
+    if (val) {
+      const masked = v.name === "VISION_API_KEY" ? val.slice(0, 6) + "****" : val
+      log(`${v.name} = ${masked}`)
+    } else {
+      log(`${v.name} 未设置`, false)
+      missing++
+    }
+  }
+  return missing
+}
+
 async function doInstall() {
   title("opencode-vision 安装")
 
+  // ── 文件复制 ──
   for (const [, rel] of FILES) {
     const dir = path.join(DST, path.dirname(rel))
     if (!fs.existsSync(dir)) {
       fs.mkdirSync(dir, { recursive: true })
     }
   }
-
   for (const [srcRel, dstRel] of FILES) {
     const src = path.join(SRC, srcRel)
     const dst = path.join(DST, dstRel)
-
     if (!fs.existsSync(src)) {
       log(`源文件不存在: ${srcRel}`, false)
       continue
     }
-
     fs.copyFileSync(src, dst)
     log(`安装 ${dstRel}`)
   }
 
+  // ── 环境变量检查 ──
   title("环境变量检查")
-  const vars = {
-    VISION_API_KEY: process.env.VISION_API_KEY,
-    VISION_API_URL: process.env.VISION_API_URL,
-    VISION_MODEL: process.env.VISION_MODEL,
-  }
+  const missing = await checkVars()
 
-  for (const [name, val] of Object.entries(vars)) {
-    if (val) {
-      const masked = name === "VISION_API_KEY" ? val.slice(0, 6) + "****" : val
-      log(`${name} = ${masked}`)
-    } else {
-      log(`${name} 未设置 — 请配置后再使用`, false)
-    }
+  if (missing > 0) {
+    console.log(`\n  \x1b[33m⚠ 有 ${missing} 个环境变量未设置。\x1b[0m`)
+    printEnvGuide()
   }
 
+  // ── OpenCode 检测 ──
   title("OpenCode 检测")
   try {
     const { execSync } = require("child_process")
@@ -73,9 +117,13 @@ async function doInstall() {
   }
 
   title("安装完成")
-  console.log("  重启 OpenCode 后即可使用。")
-  console.log("  粘贴一张图片试试看：")
-  console.log('    [图片] "这是什么？"')
+  console.log("  ✅ 文件已就位，重启 OpenCode 后即可使用。")
+  if (missing > 0) {
+    console.log("  ⚠ 环境变量未配置完整，视觉识别功能无法正常工作。")
+    console.log("     请按上面指引设置后再重启 OpenCode。")
+  }
+  console.log("  📝 使用方式：粘贴一张图片并提问")
+  console.log('     "[图片] 这是什么？"')
 }
 
 async function doUninstall() {
@@ -92,7 +140,6 @@ async function doUninstall() {
     log(`已删除 ${rel}`)
     removed++
 
-    // 如果目录空了就一并清理
     const dir = path.dirname(dst)
     if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
       fs.rmdirSync(dir)

package/package.json

@@ -1,19 +1,28 @@
 {
   "name": "@jochenyang/opencode-vision",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Vision plugin + tool for OpenCode — automatically handles pasted images for non-vision models",
-  "keywords": ["opencode", "vision", "image", "ai", "plugin", "tool"],
+  "keywords": [
+    "opencode",
+    "vision",
+    "image",
+    "ai",
+    "plugin",
+    "tool"
+  ],
   "homepage": "https://github.com/jochenyang/opencode-vision",
   "license": "MIT",
   "author": "Jochen Yang",
   "bin": {
-    "opencode-vision": "./bin/install.js"
+    "opencode-vision": "bin/install.js"
   },
   "files": [
     "bin/",
     "tools/",
     "plugins/",
-    "README.md"
+    "assets/",
+    "README.md",
+    "README_en.md"
   ],
   "engines": {
     "node": ">=18"

package/plugins/vision-helper.ts

@@ -7,8 +7,8 @@ const TMP_DIR = path.join(tmpdir(), "opencode-vision")
 /**
  * 在消息发送给模型前一刻，检测用户消息中的图片附件：
  * 1. 保存图片到临时目录
- * 2. 在用户文本前注入路径提示，让不支持多模态的模型自动调用 vision 工具
- * 3. 替换原始图片部分避免 unsupportedParts 产生噪音 ERROR 文本
+ * 2. 用简短占位替换原始图片部分（消除 unsupportedParts 的 ERROR 噪音）
+ * 3. 注入路径提示（新 push 的 part，不持久化，UI 不可见）
  */
 export default (async () => {
   await Bun.write(path.join(TMP_DIR, ".check"), "").catch(() => {})
@@ -40,8 +40,7 @@ export default (async () => {
 
         if (saved.length === 0) continue
 
-        // 用简短文本占位替换原始图片 part，防止 unsupportedParts 产生噪音 ERROR
-        // 逆序遍历避免 index 偏移
+        // 用简短占位替换原始图片 part，防止 unsupportedParts 产生噪音 ERROR
         for (const { index, filePath } of saved.toReversed()) {
           msg.parts.splice(index, 1, {
             type: "text",
@@ -49,16 +48,16 @@ export default (async () => {
           } as never)
         }
 
-        // 构造路径提示
-        const hintText = saved.length === 1
+        // 构造路径提示（新 push 的 part，不持久化，UI 不可见）
+        const hints = saved.length === 1
           ? `[Image auto-saved to ${saved[0].filePath} — use the vision tool to read it]`
           : `[Images auto-saved to:\n${saved.map((s) => `  ${s.filePath}`).join("\n")}\n— use the vision tool with paths=[...] to read them all at once]`
 
-        // 注入到用户文本前面
-        const firstText = msg.parts.find((p) => p.type === "text" && !p.synthetic)
-        if (firstText && typeof firstText.text === "string") {
-          firstText.text = hintText + "\n" + firstText.text
-        }
+        // push 新的 part 而非修改现有 part，避免影响 UI 渲染
+        ;(msg.parts as unknown as Record<string, unknown>[]).push({
+          type: "text" as const,
+          text: hints,
+        })
       }
     },
   }