opencode-image 0.1.0 → 0.1.2

package/README.md

@@ -31,10 +31,14 @@ opencode 启动时会自动从 npm 安装插件到 `~/.cache/opencode/packages/o
 | `apiKey` | `PI_IMAGE_API_KEY` | **必填**。接口密钥，建议用环境变量而不是写进配置 |
 | `baseURL` | `PI_IMAGE_BASE_URL` 或内置默认 | OpenAI 兼容接口地址 |
 | `model` | `gpt-image-2` | 模型名 |
-| `outDir` | `<项目目录>/.opencode-images` | 图片输出目录，相对路径基于当前项目 |
+| `outDir` | `<数据目录>/opencode-image` | 图片输出目录。默认全局，与项目/会话解耦；填相对路径（如 `.opencode-images`）则落到当前项目 |
 | `maxSize` | `1024` | 落盘图片最长边上限，超出等比缩小 |
-| `displayMaxSize` | `448` | 仅在对话里展示的尺寸，不影响落盘原图 |
+| `displayMaxSize` | `0` | 对话里展示的最长边。`0` = 不缩放，**直接显示原图**（右键复制/另存拿到的就是原图） |
+| `serverPort` | `0` | 本地图片服务端口。`0` = 由项目目录派生（同一项目恒定，保证历史链接跨重启有效） |
 | `serverIdleMs` | `0` | 本地图片服务空闲关闭时间（毫秒），`0` = 不主动关闭 |
+| `updateCheck` | `true` | 首次出图时查一次 npm 最新版，落后则在工具输出末尾附升级提示 |
+| `cacheDir` | `<系统临时目录>/opencode-image` | 对话里展示用的缩略图缓存目录 |
+| `cacheLimit` | `50` | 缩略图缓存最多保留多少个文件，超出按最久未访问淘汰；`0` = 不限制 |
 | `timeoutMs` | `600000` | 单次请求超时 |
 
 ## 图片是怎么显示出来的
@@ -42,18 +46,109 @@ opencode 启动时会自动从 npm 安装插件到 `~/.cache/opencode/packages/o
 openCode（桌面端 / Web）**只在助手回复的 Markdown 正文里渲染图片**，工具输出一律按纯文本处理。
 而正文里的 `file://` 会被 Chromium 拦掉，所以插件做了这件事：
 
-1. 图片落盘到 `outDir`
-2. 插件进程内起一个只绑 `127.0.0.1` 的 HTTP 服务，为图片分配随机 id
-3. 工具输出第一行给出 `![alt](http://127.0.0.1:<port>/img/<id>?w=448)`
+1. 图片落盘到 `outDir`（默认是全局数据目录，不在项目里）
+2. 插件进程内起一个只绑 `127.0.0.1` 的 HTTP 服务
+3. 工具输出给出 `![alt](...)`（`displayMaxSize = 0` 时就是原图）
 4. 工具描述里强制模型把这行**原样抄进回复正文**
 
-服务的安全边界：只服务显式注册过的文件，URL 里没有真实路径，无法路径穿越读取任意文件。
+> **不支持「图片套链接」**：opencode 覆写了 marked 的 link renderer，取的是链接里的原始文本，
+> `[![图](缩略图)](原图)` 里的图片不会被渲染。所以缩略图模式下改成两行：
+> `![alt](缩略图)` + `[查看原图](原图)`。
+>
+> 显示原图还是缩略图只取决于 `displayMaxSize`：
+> - `0`（默认）→ 直接显示原图，会话里右键 Copy / Save 拿到的就是原图
+> - `> 0`（如 `448`）→ 会话里显示轻量缩略图，下面附带一个「查看原图」链接，
+>   点击会用系统浏览器打开原图（opencode 把所有外链交给系统浏览器）
+
+**链接为什么跨重启还有效**：`id` 是「文件相对 `outDir` 的路径」的 base64url 编码，可逆且稳定；
+端口默认由项目目录派生（同一项目恒定）。所以服务**不需要任何内存登记表**，
+重启后历史消息里的旧链接仍能解析到同一个文件。
+
+服务的安全边界：请求里的 `id` 只允许解析成 `outDir` 内部的普通文件，
+解析后做 containment + `realpath` 双重校验，防路径穿越与符号链接逃逸。
+`outDir` 之外的文件只能用进程内临时 id（不跨重启）。
 
 服务的生命周期：**首次生成图片时懒启动**，端口随机；`unref()` 后不阻塞 opencode 退出，
 opencode 进程结束即自动释放。默认不主动关闭——历史消息里的图片会被重新请求，提前关闭会 404。
 
 > 同时在工具结果里返回了 `attachments`，这样模型自己也能看到生成的图，便于继续迭代。
 
+## 升级
+
+opencode 对 npm 形式的插件**不会自动升级**。
+
+它的安装逻辑是 `Npm.add()`：只要缓存目录里已经有这个包就直接复用，不会去比对版本
+（opencode 源码 `packages/core/src/npm.ts` 里的短路分支）。而裸包名会被规范化成
+`opencode-image@latest`，缓存目录名固定为 `~/.cache/opencode/packages/opencode-image@latest`，
+所以你会一直停留在**第一次安装到的版本**。
+
+升级只需要两条：
+
+```sh
+npx opencode-image --update   # 清理 opencode 的插件缓存
+# 然后重启 opencode，会自动重新下载最新版
+```
+
+插件首次出图时也会查一次 npm，发现落后就在工具输出末尾提示你执行上面这条命令（可用 `updateCheck: false` 关掉）。
+
+不想用命令的话，等价于手动删缓存后重启：
+
+```sh
+rm -rf ~/.cache/opencode/packages/opencode-image*
+```
+
+维护者发布新版：
+
+```sh
+git commit -am "..."   # npm version 要求工作区干净
+npm run release        # = version patch + publish + 清掉本机缓存
+```
+
+## 图片放在哪
+
+默认落在 **opencode 的数据目录**（`<XDG_DATA_HOME>/opencode/opencode-image/`，macOS/Linux 即
+`~/.local/share/opencode/opencode-image/`），跟 `opencode.db` 同级。
+
+这样设计的原因：
+
+- **不与项目/会话绑定**：换目录打开老会话、删掉项目、移动仓库，历史里的图都还在
+- **不污染工作区**：不再出现在 git 变更里
+- **全机一个服务**：根目录固定 → 端口由它派生 → 所有会话共用一个本地服务，而不是每个项目一个
+
+只有当你确实要让图片成为项目资产时，才把 `outDir` 设成项目内路径（如 `".opencode-images"`），
+或者让 agent 把图复制进仓库 —— 这与 Codex 的做法一致（Codex 默认存 `$CODEX_HOME/generated_images/`，
+需要在项目里用时再复制过去）。
+
+## 缓存与清理
+
+有两处"缓存"，职责完全不同，别搞混：
+
+| 是什么 | 在哪 | 删了会怎样 |
+|---|---|---|
+| **生成的图片本体** | `<数据目录>/opencode-image/`（`outDir` 可配；macOS/Linux 默认 `~/.local/share/opencode/opencode-image/`） | **会话里的图片会 404**。服务按路径解析，源文件没了就找不到 |
+| **对话缩略图**（448px） | `<系统临时目录>/opencode-image/`（`cacheDir` 可配） | 无影响，下次打开会按需重新生成 |
+
+缩略图缓存文件名由「源文件路径 + 大小 + mtime + 目标宽度」哈希而成，所以同一张图不会重复生成，跨重启也能复用。
+超过 `cacheLimit`（默认 50 个）时按最久未访问淘汰，并在**下一次工具输出末尾**提醒你（含目录、数量、总大小、最旧一个存在了多久）——每进程只提醒一次，不刷屏。
+
+清理缩略图缓存（两种方式等价）：
+
+```sh
+npx opencode-image --clean-cache
+# 如果你改过 cacheDir:
+npx opencode-image --clean-cache --cache-dir /your/cache/dir
+```
+
+也可以直接在会话里让 agent 调用 `image_cache`：
+
+- `image_cache(action="status")` —— 目录、数量、总大小、最旧一个多久了
+- `image_cache(action="clean")` —— 清空缩略图缓存（不动 `outDir` 里的原图）
+
+> **建议**：把输出目录加进项目 `.gitignore`，否则每画一张图都会出现在 git 变更里：
+> ```
+> .opencode-images/
+> ```
+
 ## 环境变量
 
 ```bash
@@ -78,6 +173,8 @@ bun run build   # 产出 dist/index.js + dist/index.d.ts
 
 - 只有能渲染 Markdown 图片的客户端才看得到图；纯终端 TUI 里会退化成一串 URL。
 - 预览图缓存在系统临时目录，`serverIdleMs = 0`（默认）时随进程退出由系统回收。
+- 两个不同项目极少数情况下会派生出同一个端口，此时后启动的实例会报错并提示用 `serverPort` 指定端口。
+- 工具结果里的 `attachments` 只是给模型看的，opencode 客户端**不会**把工具附件渲染成图片，所以内联显示必须靠上面的 Markdown 链接。
 
 ## License
 

package/bin/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+
+const PACKAGE = "opencode-image"
+const DEFAULT_CACHE_DIR = path.join(os.tmpdir(), "opencode-image")
+
+const args = process.argv.slice(2)
+
+const version = (() => {
+  try {
+    const file = new URL("../package.json", import.meta.url)
+    return JSON.parse(fs.readFileSync(file, "utf8")).version ?? "unknown"
+  } catch {
+    return "unknown"
+  }
+})()
+
+const USAGE = `${PACKAGE} v${version}
+
+用法:
+  npx ${PACKAGE} --update              清理 opencode 的插件缓存并重启 opencode，即可装上最新版
+  npx ${PACKAGE} --clean-cache         清理对话缩略图缓存（不影响生成的图片）
+  npx ${PACKAGE} --version             显示版本
+  npx ${PACKAGE} --help                显示帮助
+
+选项:
+  --cache-dir <path>   缩略图缓存目录，默认 <系统临时目录>/opencode-image
+                       （如果你的配置里改过 cacheDir，用这个参数或 OPENCODE_IMAGE_CACHE_DIR 指过去）
+
+为什么需要 --update:
+  opencode 对 npm 形式的插件不做版本检查——只要缓存目录里已经装过就直接复用。
+  所以发布新版后必须清掉缓存，opencode 才会重新下载。详见 README「升级」一节。
+`
+
+function flag(name) {
+  const index = args.indexOf(name)
+  return index >= 0 ? (args[index + 1] ?? "") : undefined
+}
+
+function humanBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`
+}
+
+/** opencode 的插件缓存在 <cache>/packages/<spec>，spec 可能是 opencode-image 或 opencode-image@latest */
+function pluginCacheRoot() {
+  return process.env.OPENCODE_IMAGE_PLUGIN_CACHE ?? path.join(os.homedir(), ".cache", "opencode", "packages")
+}
+
+function update() {
+  const root = pluginCacheRoot()
+  if (!fs.existsSync(root)) {
+    console.log(`缓存目录不存在，无需清理：${root}`)
+    console.log("直接重启 opencode 即可。")
+    return
+  }
+
+  const targets = fs
+    .readdirSync(root)
+    .filter((entry) => entry === PACKAGE || entry.startsWith(`${PACKAGE}@`))
+    .map((entry) => path.join(root, entry))
+
+  if (targets.length === 0) {
+    console.log(`没有找到 ${PACKAGE} 的缓存，无需清理。`)
+    console.log("直接重启 opencode 即可。")
+    return
+  }
+
+  for (const target of targets) {
+    fs.rmSync(target, { recursive: true, force: true })
+    console.log(`已删除 ${target}`)
+  }
+  console.log("")
+  console.log(`✅ 已清理 ${targets.length} 个缓存目录，重启 opencode 后会重新下载最新版。`)
+}
+
+function cleanCache() {
+  const dir = flag("--cache-dir") ?? process.env.OPENCODE_IMAGE_CACHE_DIR ?? DEFAULT_CACHE_DIR
+  if (!fs.existsSync(dir)) {
+    console.log(`缩略图缓存目录不存在，无需清理：${dir}`)
+    return
+  }
+
+  let count = 0
+  let bytes = 0
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith(".png")) continue
+    const file = path.join(dir, name)
+    try {
+      const stat = fs.statSync(file)
+      if (!stat.isFile()) continue
+      bytes += stat.size
+      count += 1
+      fs.rmSync(file, { force: true })
+    } catch {
+      // 单个文件删不掉就跳过，最后按实际删掉的数量汇报
+    }
+  }
+
+  console.log(`✅ 已清理缩略图缓存：${count} 个文件 / ${humanBytes(bytes)}`)
+  console.log(`目录：${dir}`)
+  console.log("生成的图片不受影响，会话里的图片仍能显示（需要时会重新生成缩略图）。")
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(USAGE)
+  process.exit(0)
+}
+
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(version)
+  process.exit(0)
+}
+
+if (args.includes("--update")) {
+  update()
+  process.exit(0)
+}
+
+if (args.includes("--clean-cache")) {
+  cleanCache()
+  process.exit(0)
+}
+
+console.log(USAGE)
+process.exit(1)

package/dist/cache.d.ts

@@ -0,0 +1,44 @@
+export declare const DEFAULT_CACHE_DIR: string;
+export declare const DEFAULT_CACHE_LIMIT = 50;
+export type CacheStats = {
+    dir: string;
+    count: number;
+    bytes: number;
+    /** 最旧一个预览文件已经存在了多久（毫秒）；空缓存时为 undefined */
+    oldestMs?: number;
+};
+export declare function humanBytes(bytes: number): string;
+export declare function humanAge(ms: number): string;
+/**
+ * 对话里展示用的缩略图缓存。
+ *
+ * 文件名由「源文件绝对路径 + 文件大小 + mtime + 目标宽度」哈希而成，所以：
+ * - 同一个文件同一尺寸永远命中同一个文件名 → 不重复生成，跨重启也能复用
+ * - 源文件内容变了（mtime/size 变）就是新 key → 不会拿到过期缩略图
+ * - 缓存目录里只有我们自己的 *.png，清理时不会误伤其它文件
+ *
+ * 超过上限时按访问时间（mtime，命中时会 utimes 刷新）淘汰最旧的，并记一条待展示的通知。
+ */
+export declare class PreviewCache {
+    private readonly dir;
+    private readonly limit;
+    private notice?;
+    constructor(dir: string, limit: number);
+    get directory(): string;
+    private target;
+    /** 命中则刷新访问时间并返回缓存文件；未命中返回 undefined */
+    hit(source: string, max: number): string | undefined;
+    /** 收下一个新生成的预览文件（从临时位置挪进缓存），并按需淘汰 */
+    put(source: string, max: number, generated: string): string;
+    stats(): CacheStats;
+    /** 一次性取走待展示的溢出通知 */
+    consumeNotice(): string | undefined;
+    /** 清空缓存目录里由本插件生成的预览文件 */
+    clean(): {
+        dir: string;
+        count: number;
+        bytes: number;
+    };
+    private entries;
+    private enforce;
+}

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 import { tool } from "@opencode-ai/plugin";
-import * as fs3 from "node:fs";
-import * as path3 from "node:path";
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
 
 // src/api.ts
 function parseImageResponse(body) {
@@ -88,9 +88,137 @@ async function editImage(config, source, filename, prompt, signal) {
   return readImage(res, "POST /images/edits");
 }
 
-// src/image.ts
+// src/cache.ts
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import { createHash } from "node:crypto";
+var DEFAULT_CACHE_DIR = path.join(os.tmpdir(), "opencode-image");
+var DEFAULT_CACHE_LIMIT = 50;
+function humanBytes(bytes) {
+  if (bytes < 1024)
+    return `${bytes} B`;
+  if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+function humanAge(ms) {
+  const minutes = Math.floor(ms / 60000);
+  if (minutes < 1)
+    return "不到 1 分钟";
+  if (minutes < 60)
+    return `${minutes} 分钟`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24)
+    return `${hours} 小时`;
+  return `${Math.floor(hours / 24)} 天`;
+}
+
+class PreviewCache {
+  dir;
+  limit;
+  notice;
+  constructor(dir, limit) {
+    this.dir = dir;
+    this.limit = limit;
+  }
+  get directory() {
+    return this.dir;
+  }
+  target(source, max) {
+    let stat;
+    try {
+      stat = fs.statSync(source);
+    } catch {
+      return;
+    }
+    const hash = createHash("sha1").update(`${path.resolve(source)}|${stat.size}|${Math.floor(stat.mtimeMs)}|${max}`).digest("hex").slice(0, 16);
+    return path.join(this.dir, `${hash}.png`);
+  }
+  hit(source, max) {
+    const file = this.target(source, max);
+    if (!file || !fs.existsSync(file))
+      return;
+    const now = new Date;
+    try {
+      fs.utimesSync(file, now, now);
+    } catch {}
+    return file;
+  }
+  put(source, max, generated) {
+    const file = this.target(source, max);
+    if (!file)
+      return generated;
+    fs.mkdirSync(this.dir, { recursive: true });
+    if (path.resolve(file) !== path.resolve(generated))
+      fs.renameSync(generated, file);
+    const now = new Date;
+    fs.utimesSync(file, now, now);
+    this.enforce();
+    return file;
+  }
+  stats() {
+    const entries = this.entries();
+    const bytes = entries.reduce((sum, entry) => sum + entry.size, 0);
+    if (entries.length === 0)
+      return { dir: this.dir, count: 0, bytes: 0 };
+    const oldest = Math.min(...entries.map((entry) => entry.mtimeMs));
+    return { dir: this.dir, count: entries.length, bytes, oldestMs: Date.now() - oldest };
+  }
+  consumeNotice() {
+    const notice = this.notice;
+    this.notice = undefined;
+    return notice;
+  }
+  clean() {
+    const entries = this.entries();
+    const bytes = entries.reduce((sum, entry) => sum + entry.size, 0);
+    for (const entry of entries)
+      fs.rmSync(entry.file, { force: true });
+    this.notice = undefined;
+    return { dir: this.dir, count: entries.length, bytes };
+  }
+  entries() {
+    try {
+      return fs.readdirSync(this.dir).filter((name) => name.endsWith(".png")).flatMap((name) => {
+        const file = path.join(this.dir, name);
+        try {
+          const stat = fs.statSync(file);
+          return stat.isFile() ? [{ file, size: stat.size, mtimeMs: stat.mtimeMs }] : [];
+        } catch {
+          return [];
+        }
+      });
+    } catch {
+      return [];
+    }
+  }
+  enforce() {
+    if (this.limit <= 0)
+      return;
+    const entries = this.entries();
+    if (entries.length <= this.limit)
+      return;
+    entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const entry of entries.slice(0, entries.length - this.limit)) {
+      fs.rmSync(entry.file, { force: true });
+    }
+    if (this.notice)
+      return;
+    const stats = this.stats();
+    this.notice = [
+      `[请转述给用户] 图片预览缓存已达上限（${this.limit} 个），已自动清理最旧的。`,
+      `目录：${stats.dir}`,
+      `当前：${stats.count} 个 / ${humanBytes(stats.bytes)}` + (stats.oldestMs === undefined ? "" : `，最旧一个存在了 ${humanAge(stats.oldestMs)}`),
+      `彻底清理：让 agent 调用 image_cache(action="clean")，或运行 npx opencode-image --clean-cache`
+    ].join(`
+`);
+  }
+}
+
+// src/image.ts
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
 import sharp from "sharp";
 function fitInside(max) {
   return { width: max, height: max, fit: "inside", withoutEnlargement: true };
@@ -115,9 +243,9 @@ async function renderPreview(source, destination, max) {
   return destination;
 }
 async function persistImage(raw, destination, maxSize) {
-  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs2.mkdirSync(path2.dirname(destination), { recursive: true });
   const staging = `${destination}.${process.pid}-${Date.now()}.download`;
-  fs.writeFileSync(staging, raw);
+  fs2.writeFileSync(staging, raw);
   try {
     const meta = await sharp(staging).metadata();
     const width = meta.width ?? 0;
@@ -127,16 +255,28 @@ async function persistImage(raw, destination, maxSize) {
     const pipeline = Math.max(width, height) > maxSize ? sharp(staging).resize(fitInside(maxSize)) : sharp(staging);
     await pipeline.png().toFile(destination);
   } finally {
-    fs.rmSync(staging, { force: true });
+    fs2.rmSync(staging, { force: true });
   }
   return imageDimensions(destination);
 }
 
 // src/options.ts
+import * as os2 from "node:os";
+import * as path3 from "node:path";
+function defaultImageDir(env = process.env, home = os2.homedir()) {
+  const base = env.XDG_DATA_HOME?.trim() || path3.join(home, ".local", "share");
+  return path3.join(base, "opencode", "opencode-image");
+}
+function resolveOutDir(directory, outDir) {
+  if (!outDir)
+    return defaultImageDir();
+  return path3.isAbsolute(outDir) ? outDir : path3.join(directory, outDir);
+}
 var DEFAULT_BASE_URL = "https://pi-ai.roiscloud.com/v1";
 var DEFAULT_MODEL = "gpt-image-2";
 var DEFAULT_MAX_SIZE = 1024;
-var DEFAULT_DISPLAY_MAX_SIZE = 448;
+var DEFAULT_DISPLAY_MAX_SIZE = 0;
+var DEFAULT_SERVER_PORT = 0;
 var DEFAULT_SERVER_IDLE_MS = 0;
 var DEFAULT_TIMEOUT_MS = 600000;
 function resolveOptions(options) {
@@ -152,17 +292,78 @@ function resolveOptions(options) {
     outDir: opts.outDir,
     maxSize: opts.maxSize ?? DEFAULT_MAX_SIZE,
     displayMaxSize: opts.displayMaxSize ?? DEFAULT_DISPLAY_MAX_SIZE,
+    serverPort: opts.serverPort ?? DEFAULT_SERVER_PORT,
     serverIdleMs: opts.serverIdleMs ?? DEFAULT_SERVER_IDLE_MS,
+    updateCheck: opts.updateCheck ?? true,
+    cacheDir: opts.cacheDir ?? DEFAULT_CACHE_DIR,
+    cacheLimit: opts.cacheLimit ?? DEFAULT_CACHE_LIMIT,
     timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
   };
 }
 
+// src/update.ts
+import * as fs3 from "node:fs";
+var REGISTRY = "https://registry.npmjs.org";
+var PACKAGE = "opencode-image";
+function parse(version) {
+  const [core, pre = ""] = version.split("-", 2);
+  const nums = core.split(".").map((part) => Number.parseInt(part, 10));
+  return { nums: [nums[0] || 0, nums[1] || 0, nums[2] || 0], pre };
+}
+function isNewer(candidate, current) {
+  const a = parse(candidate);
+  const b = parse(current);
+  for (let i = 0;i < 3; i++) {
+    if (a.nums[i] !== b.nums[i])
+      return a.nums[i] > b.nums[i];
+  }
+  if (a.pre === b.pre)
+    return false;
+  if (!a.pre)
+    return true;
+  if (!b.pre)
+    return false;
+  return a.pre > b.pre;
+}
+function readOwnVersion() {
+  try {
+    const file = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(fs3.readFileSync(file, "utf8"));
+    return pkg.version;
+  } catch {
+    return;
+  }
+}
+function upgradeHint(latest, current) {
+  return `[请转述给用户] ${PACKAGE} 有新版本 ${latest}（当前 ${current}）。升级：npx ${PACKAGE} --update 然后重启 opencode。`;
+}
+async function checkForUpdate(current, timeoutMs = 3000) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${REGISTRY}/${PACKAGE}/latest`, {
+      signal: controller.signal,
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok)
+      return;
+    const body = await res.json();
+    if (!body.version || !isNewer(body.version, current))
+      return;
+    return upgradeHint(body.version, current);
+  } catch {
+    return;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/server.ts
-import * as fs2 from "node:fs";
+import * as fs4 from "node:fs";
 import * as http from "node:http";
-import * as os from "node:os";
-import * as path2 from "node:path";
-import { randomUUID } from "node:crypto";
+import * as os3 from "node:os";
+import * as path4 from "node:path";
+import { createHash as createHash2, randomUUID } from "node:crypto";
 var MIME_BY_EXT = {
   ".png": "image/png",
   ".jpg": "image/jpeg",
@@ -170,71 +371,123 @@ var MIME_BY_EXT = {
   ".webp": "image/webp",
   ".gif": "image/gif"
 };
+var ID_PATTERN = /^\/img\/([A-Za-z0-9_-]{1,2048})(?:\/[^/]*)?$/;
+var APP_NAME = "opencode-image";
+function derivePort(key) {
+  const digest = createHash2("sha1").update(key).digest();
+  return 41000 + digest.readUInt16BE(0) % 4000;
+}
 
 class ImageServer {
   idleMs;
+  configuredPort;
+  cache;
   server;
   port = 0;
-  registry = new Map;
-  previews = new Map;
+  root;
+  ready = false;
+  owned = false;
+  extra = new Map;
   timer;
   starting;
-  constructor(idleMs) {
+  constructor(idleMs, configuredPort, cache) {
     this.idleMs = idleMs;
+    this.configuredPort = configuredPort;
+    this.cache = cache;
   }
   get baseURL() {
     return this.port ? `http://127.0.0.1:${this.port}` : "";
   }
-  register(file) {
+  idFor(file) {
+    const root = this.root;
+    if (root) {
+      const relative2 = path4.relative(root, file);
+      if (relative2 && !relative2.startsWith("..") && !path4.isAbsolute(relative2)) {
+        return Buffer.from(relative2.split(path4.sep).join("/"), "utf8").toString("base64url");
+      }
+    }
+    for (const [id2, registered] of this.extra) {
+      if (registered === file)
+        return id2;
+    }
     const id = randomUUID().replace(/-/g, "").slice(0, 16);
-    const mime = MIME_BY_EXT[path2.extname(file).toLowerCase()] ?? "application/octet-stream";
-    this.registry.set(id, { file, mime });
+    this.extra.set(id, file);
     return id;
   }
-  url(id, width) {
-    return `${this.baseURL}/img/${id}?w=${width}`;
+  url(file, width) {
+    const query = width > 0 ? `?w=${Math.round(width)}` : "";
+    const name = encodeURIComponent(path4.basename(file));
+    return `${this.baseURL}/img/${this.idFor(file)}/${name}${query}`;
   }
-  async start() {
-    if (this.server) {
+  async start(opts) {
+    this.root = path4.resolve(opts.outDir);
+    if (this.ready) {
       this.arm();
       return;
     }
     if (!this.starting) {
-      this.starting = this.listen().finally(() => {
+      this.starting = this.listen(opts).finally(() => {
         this.starting = undefined;
       });
     }
     await this.starting;
+    this.ready = true;
     this.arm();
   }
   stop() {
     if (this.timer)
       clearTimeout(this.timer);
     this.timer = undefined;
-    const server = this.server;
+    if (this.owned) {
+      this.server?.closeAllConnections?.();
+      this.server?.close();
+    }
     this.server = undefined;
+    this.owned = false;
+    this.ready = false;
     this.port = 0;
-    server?.closeAllConnections?.();
-    server?.close();
-    for (const file of this.previews.values())
-      fs2.rmSync(file, { force: true });
-    this.previews.clear();
   }
-  async listen() {
+  cacheStats() {
+    return this.cache.stats();
+  }
+  cleanCache() {
+    return this.cache.clean();
+  }
+  consumeCacheNotice() {
+    return this.cache.consumeNotice();
+  }
+  async listen(opts) {
+    const port = this.configuredPort || derivePort(path4.resolve(opts.outDir));
     const server = http.createServer((req, res) => void this.handle(req, res));
     server.unref();
-    await new Promise((resolve, reject) => {
-      server.once("error", reject);
-      server.listen(0, "127.0.0.1", resolve);
+    const failure = await new Promise((resolve3) => {
+      server.once("error", resolve3);
+      server.listen(port, "127.0.0.1", () => resolve3(undefined));
     });
-    const address = server.address();
-    const port = typeof address === "object" && address ? address.port : 0;
-    if (!port) {
-      server.close();
-      throw new Error("opencode-image: image server did not bind a port");
+    if (!failure) {
+      this.server = server;
+      this.port = port;
+      this.owned = true;
+      return;
+    }
+    server.close();
+    if (failure.code === "EADDRINUSE" && await this.servedByUs(port, opts.outDir)) {
+      this.port = port;
+      this.owned = false;
+      return;
+    }
+    throw new Error(`opencode-image: cannot listen on 127.0.0.1:${port} (${String(failure)}). ` + `Set the serverPort option to a free port, or stop whatever is using it.`);
+  }
+  async servedByUs(port, outDir) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/health`);
+      if (!res.ok)
+        return false;
+      const body = await res.json();
+      return body.app === APP_NAME && body.root === path4.resolve(outDir);
+    } catch {
+      return false;
     }
-    this.server = server;
-    this.port = port;
   }
   arm() {
     if (this.timer)
@@ -244,36 +497,70 @@ class ImageServer {
     this.timer = setTimeout(() => this.stop(), this.idleMs);
     this.timer.unref();
   }
-  preview(source, max) {
-    const key = `${source}@${max}`;
-    const cached = this.previews.get(key);
-    if (cached && fs2.existsSync(cached))
-      return Promise.resolve(cached);
-    const destination = path2.join(os.tmpdir(), `opencode-image-${process.pid}-${randomUUID()}.png`);
-    return renderPreview(source, destination, max).then((file) => {
-      if (file !== source)
-        this.previews.set(key, file);
-      return file;
-    });
+  async preview(source, max) {
+    const hit = this.cache.hit(source, max);
+    if (hit)
+      return hit;
+    const staging = path4.join(os3.tmpdir(), `opencode-image-${process.pid}-${randomUUID()}.png`);
+    const rendered = await renderPreview(source, staging, max);
+    if (rendered === source)
+      return source;
+    return this.cache.put(source, max, rendered);
+  }
+  resolve(id) {
+    const registered = this.extra.get(id);
+    if (registered)
+      return fs4.existsSync(registered) ? registered : undefined;
+    const root = this.root;
+    if (!root)
+      return;
+    let relative2;
+    try {
+      relative2 = Buffer.from(id, "base64url").toString("utf8");
+    } catch {
+      return;
+    }
+    if (!relative2 || relative2.includes("\x00") || path4.isAbsolute(relative2))
+      return;
+    const target = path4.resolve(root, relative2);
+    if (target === root || !target.startsWith(root + path4.sep))
+      return;
+    try {
+      if (!fs4.statSync(target).isFile())
+        return;
+      const real = fs4.realpathSync(target);
+      const realRoot = fs4.realpathSync(root);
+      if (real !== realRoot && !real.startsWith(realRoot + path4.sep))
+        return;
+    } catch {
+      return;
+    }
+    return target;
   }
   handle(req, res) {
     this.arm();
     const parsed = new URL(req.url ?? "/", "http://127.0.0.1");
-    const id = /^\/img\/([0-9a-f]{8,64})$/.exec(parsed.pathname)?.[1];
-    const entry = id ? this.registry.get(id) : undefined;
-    if (!entry || !fs2.existsSync(entry.file)) {
+    if (parsed.pathname === "/health") {
+      const body = JSON.stringify({ app: APP_NAME, root: this.root ?? "" });
+      res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(body) });
+      res.end(body);
+      return;
+    }
+    const id = ID_PATTERN.exec(parsed.pathname)?.[1];
+    const file = id ? this.resolve(id) : undefined;
+    if (!file) {
       res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
       res.end("not found");
       return;
     }
-    this.send(entry, Number(parsed.searchParams.get("w")), res);
+    this.send(file, Number(parsed.searchParams.get("w")), res);
   }
-  async send(entry, width, res) {
+  async send(file, width, res) {
     try {
-      const target = width > 0 ? await this.preview(entry.file, Math.round(width)) : entry.file;
-      const body = fs2.readFileSync(target);
+      const target = width > 0 ? await this.preview(file, Math.round(width)) : file;
+      const body = fs4.readFileSync(target);
       res.writeHead(200, {
-        "content-type": entry.mime,
+        "content-type": MIME_BY_EXT[path4.extname(target).toLowerCase()] ?? "application/octet-stream",
         "content-length": body.length,
         "cache-control": "private, max-age=86400"
       });
@@ -288,46 +575,68 @@ class ImageServer {
 // src/index.ts
 var z = tool.schema;
 function resolveDestination(filename, outDir, ctx) {
-  const dir = outDir ? path3.isAbsolute(outDir) ? outDir : path3.join(ctx.directory, outDir) : path3.join(ctx.directory, ".opencode-images");
+  const dir = resolveOutDir(ctx.directory, outDir);
   if (filename) {
-    const target = path3.isAbsolute(filename) ? filename : path3.join(dir, filename);
+    const target = path5.isAbsolute(filename) ? filename : path5.join(dir, filename);
     return `${target.replace(/\.[A-Za-z0-9]+$/, "")}.png`;
   }
   const stamp = new Date().toISOString().replace(/\..+$/, "").replace(/[:T]/g, "-");
   const suffix = Math.random().toString(36).slice(2, 6);
-  return path3.join(dir, `image-${stamp}-${suffix}.png`);
+  return path5.join(dir, `image-${stamp}-${suffix}.png`);
 }
 function asAttachment(file) {
   return [
     {
       type: "file",
       mime: "image/png",
-      filename: path3.basename(file),
-      url: `data:image/png;base64,${fs3.readFileSync(file).toString("base64")}`
+      filename: path5.basename(file),
+      url: `data:image/png;base64,${fs5.readFileSync(file).toString("base64")}`
     }
   ];
 }
 var OpenCodeImagePlugin = async (_input, rawOptions) => {
   const options = resolveOptions(rawOptions);
-  const server = new ImageServer(options.serverIdleMs);
-  const result = async (label, prompt, file, usage) => {
+  const cache = new PreviewCache(options.cacheDir, options.cacheLimit);
+  const server = new ImageServer(options.serverIdleMs, options.serverPort, cache);
+  const selfVersion = readOwnVersion();
+  let updateHint;
+  let updateChecked = false;
+  const upgradeNotice = async () => {
+    if (!options.updateCheck || updateChecked || !selfVersion)
+      return updateHint;
+    updateChecked = true;
+    updateHint = await checkForUpdate(selfVersion);
+    return updateHint;
+  };
+  const result = async (label, prompt, file, ctx, usage) => {
     const { width, height } = await imageDimensions(file);
-    const id = server.register(file);
     let display;
     try {
-      await server.start();
-      display = `![${prompt.slice(0, 60)}](${server.url(id, options.displayMaxSize)})`;
+      await server.start({ outDir: resolveOutDir(ctx.directory, options.outDir) });
+      const alt = prompt.slice(0, 60);
+      const lines = [`![${alt}](${server.url(file, options.displayMaxSize)})`];
+      if (options.displayMaxSize > 0)
+        lines.push(`[查看原图](${server.url(file, 0)})`);
+      display = lines.join(`
+`);
     } catch (error) {
       display = `[opencode-image: local image server unavailable, cannot render inline: ${String(error)}]`;
     }
+    const notice = await upgradeNotice();
+    const output = [
+      display,
+      `${label} saved to ${file} (${width}x${height})`,
+      `Refine it by calling image_edit with image="${file}" and a prompt describing the change.`,
+      `IMPORTANT: copy the Markdown image line above verbatim into your reply text, otherwise the user cannot see the picture.`
+    ];
+    if (notice)
+      output.push(notice);
+    const cacheNotice = server.consumeCacheNotice();
+    if (cacheNotice)
+      output.push(cacheNotice);
     return {
       title: `${label}: ${prompt.slice(0, 60)}`,
-      output: [
-        display,
-        `${label} saved to ${file} (${width}x${height})`,
-        `Refine it by calling image_edit with image="${file}" and a prompt describing the change.`,
-        `IMPORTANT: copy the Markdown image line above verbatim into your reply text, otherwise the user cannot see the picture.`
-      ].join(`
+      output: output.join(`
 `),
       metadata: { file, prompt, usage },
       attachments: asAttachment(file)
@@ -341,24 +650,24 @@ var OpenCodeImagePlugin = async (_input, rawOptions) => {
       const raw = await fetchImageBytes(remote, signal);
       const destination = resolveDestination(args.filename, options.outDir, ctx);
       await persistImage(raw, destination, options.maxSize);
-      return result("Image generated", args.prompt, destination, remote.usage);
+      return result("Image generated", args.prompt, destination, ctx, remote.usage);
     } finally {
       clear();
     }
   };
   const edit = async (args, ctx) => {
-    const source = path3.isAbsolute(args.image) ? args.image : path3.resolve(ctx.directory, args.image);
-    if (!fs3.existsSync(source))
+    const source = path5.isAbsolute(args.image) ? args.image : path5.resolve(ctx.directory, args.image);
+    if (!fs5.existsSync(source))
       throw new Error(`image_edit: source image not found: ${source}`);
     ctx.metadata({ title: `Editing image: ${args.prompt.slice(0, 60)}` });
     const { signal, clear } = withTimeout(ctx.abort, options.timeoutMs);
     try {
       const upload = await toPngBuffer(source, options.maxSize);
-      const remote = await editImage(options, upload, `${path3.basename(source, path3.extname(source))}.png`, args.prompt, signal);
+      const remote = await editImage(options, upload, `${path5.basename(source, path5.extname(source))}.png`, args.prompt, signal);
       const raw = await fetchImageBytes(remote, signal);
       const destination = resolveDestination(args.filename, options.outDir, ctx);
       await persistImage(raw, destination, options.maxSize);
-      return result("Image edited", args.prompt, destination, remote.usage);
+      return result("Image edited", args.prompt, destination, ctx, remote.usage);
     } finally {
       clear();
     }
@@ -366,7 +675,7 @@ var OpenCodeImagePlugin = async (_input, rawOptions) => {
   return {
     tool: {
       image_generate: tool({
-        description: "Generate a new image from a text prompt using an OpenAI-compatible image API. " + "The result includes a Markdown image line that you MUST copy verbatim into your reply text, " + "otherwise the user cannot see the picture. To iterate on a result, call image_edit with the returned path.",
+        description: "Generate a new image from a text prompt using an OpenAI-compatible image API. " + "The result starts with a Markdown image line (plus a separate 查看原图 link when displayMaxSize is set) that you MUST copy verbatim into your reply text, " + "If the output contains a line starting with [请转述给用户], relay that line to the user in your reply. " + "otherwise the user cannot see the picture. To iterate on a result, call image_edit with the returned path.",
         args: {
           prompt: z.string().describe("Detailed description of the image to generate"),
           filename: z.string().optional().describe("Optional output file name or path; defaults to a timestamped name")
@@ -374,14 +683,51 @@ var OpenCodeImagePlugin = async (_input, rawOptions) => {
         execute: generate
       }),
       image_edit: tool({
-        description: "Edit an existing image with a text instruction (image-to-image). Pass the exact path returned by a previous " + "image_generate or image_edit call to keep refining the same picture. " + "The result includes a Markdown image line that you MUST copy verbatim into your reply text, " + "otherwise the user cannot see the picture.",
+        description: "Edit an existing image with a text instruction (image-to-image). Pass the exact path returned by a previous " + "image_generate or image_edit call to keep refining the same picture. " + "The result starts with a Markdown image line (plus a separate 查看原图 link when displayMaxSize is set) that you MUST copy verbatim into your reply text, " + "If the output contains a line starting with [请转述给用户], relay that line to the user in your reply. " + "otherwise the user cannot see the picture.",
         args: {
           image: z.string().describe("Path to the source image, normally the file returned by image_generate/image_edit"),
           prompt: z.string().describe("What to change, e.g. 'make the hat red, keep everything else identical'"),
           filename: z.string().optional().describe("Optional output file name or path; defaults to a timestamped name")
         },
         execute: edit
+      }),
+      image_cache: tool({
+        description: "Inspect or clear the preview-thumbnail cache used for rendering images in the conversation. " + 'Use action="status" to report the cache directory, file count, total size and age of the oldest entry; ' + 'action="clean" to delete every cached preview (the generated images in outDir are NOT touched). ' + "This returns text only — do not turn it into a Markdown image line.",
+        args: {
+          action: z.enum(["status", "clean"]).describe("status = 查看缓存；clean = 清空缓存")
+        },
+        execute: async (args) => {
+          if (args.action === "clean") {
+            const removed = server.cleanCache();
+            return {
+              title: `已清理图片缓存（${removed.count} 个 / ${humanBytes(removed.bytes)}）`,
+              output: [
+                `已清理 ${removed.count} 个预览文件，共 ${humanBytes(removed.bytes)}。`,
+                `缓存目录：${removed.dir}`,
+                `注意：这不影响 outDir 里的原图，会话里的图片仍能正常显示（需要时会重新生成缩略图）。`
+              ].join(`
+`),
+              metadata: removed
+            };
+          }
+          const stats = server.cacheStats();
+          return {
+            title: `图片缓存：${stats.count} 个 / ${humanBytes(stats.bytes)}`,
+            output: [
+              `缓存目录：${stats.dir}`,
+              `文件数量：${stats.count}`,
+              `占用大小：${humanBytes(stats.bytes)}`,
+              `最旧一个：${stats.oldestMs === undefined ? "（空缓存）" : `已存在 ${humanAge(stats.oldestMs)}`}`,
+              `上限：${options.cacheLimit} 个（可通过 cacheLimit 配置，0 = 不限制）`
+            ].join(`
+`),
+            metadata: stats
+          };
+        }
       })
+    },
+    dispose: async () => {
+      server.stop();
     }
   };
 };

package/dist/options.d.ts

@@ -1,3 +1,12 @@
+/** opencode 的数据目录（与 opencode.db 同级），图片默认落在这里而不是项目里 */
+export declare function defaultImageDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * 解析图片输出目录：
+ * - 未配置 → 全局数据目录，和项目/会话解耦
+ * - 相对路径 → 基于当前项目目录（例如 ".opencode-images" 就回到项目里）
+ * - 绝对路径 → 原样使用
+ */
+export declare function resolveOutDir(directory: string, outDir?: string): string;
 /** 插件可配置项，通过 opencode 配置的 `plugin` 元组第二个元素传入 */
 export type PluginOptions = {
     /** OpenAI 兼容的图像接口地址，默认从 PI_IMAGE_BASE_URL 读取 */
@@ -6,21 +15,35 @@ export type PluginOptions = {
     apiKey?: string;
     /** 图像模型名 */
     model?: string;
-    /** 图片输出目录；相对路径基于当前项目目录，默认 <project>/.opencode-images */
+    /**
+     * 图片输出目录。默认是全局数据目录（建议保持默认，跟项目/会话解耦）；
+     * 填相对路径（如 ".opencode-images"）会落在当前项目里。
+     */
     outDir?: string;
     /** 落盘图片的最长边上限（像素），超出会等比缩小 */
     maxSize?: number;
-    /** 在对话里展示的图片最长边（像素）；只影响展示，不影响落盘原图 */
+    /** 对话里展示时的最长边（像素）。0 = 不缩放，直接显示原图（默认，右键复制即原图） */
     displayMaxSize?: number;
+    /** 本地图片服务端口；默认 0 = 由项目目录派生（同一项目恒定），需要避开占用时手动指定 */
+    serverPort?: number;
     /** 本地图片服务的空闲关闭时间（毫秒），0 表示不主动关闭 */
     serverIdleMs?: number;
+    /** 首次出图时查一次 npm 最新版，落后则在工具输出末尾附升级提示。默认开启 */
+    updateCheck?: boolean;
+    /** 对话里展示用的缩略图缓存目录，默认 <系统临时目录>/opencode-image */
+    cacheDir?: string;
+    /** 缩略图缓存最多保留多少个文件，超出按最久未访问淘汰；0 表示不限制 */
+    cacheLimit?: number;
     /** 单次图像请求超时（毫秒） */
     timeoutMs?: number;
 };
 export declare const DEFAULT_BASE_URL = "https://pi-ai.roiscloud.com/v1";
 export declare const DEFAULT_MODEL = "gpt-image-2";
 export declare const DEFAULT_MAX_SIZE = 1024;
-export declare const DEFAULT_DISPLAY_MAX_SIZE = 448;
+/** 0 = 不缩放，直接把落盘的原图显示出来（右键复制/另存拿到的就是原图） */
+export declare const DEFAULT_DISPLAY_MAX_SIZE = 0;
+/** 0 表示由项目目录派生端口，保证同一项目跨重启链接不变 */
+export declare const DEFAULT_SERVER_PORT = 0;
 export declare const DEFAULT_SERVER_IDLE_MS = 0;
 export declare const DEFAULT_TIMEOUT_MS = 600000;
 export type ResolvedOptions = {
@@ -30,7 +53,11 @@ export type ResolvedOptions = {
     outDir?: string;
     maxSize: number;
     displayMaxSize: number;
+    serverPort: number;
     serverIdleMs: number;
+    updateCheck: boolean;
+    cacheDir: string;
+    cacheLimit: number;
     timeoutMs: number;
 };
 /** 合并默认值、环境变量与用户配置；缺少 apiKey 时直接抛错 */

package/dist/server.d.ts

@@ -1,35 +1,68 @@
+import { PreviewCache } from "./cache.js";
+/**
+ * 端口由「图片根目录」派生：同一个根目录永远同一个端口，所以历史消息里的链接跨重启仍然有效。
+ * 默认根目录是全局数据目录，因此全机通用一个端口、一个服务；
+ * 若把 outDir 指到项目里，则那个项目有自己稳定的端口。需要覆盖时用 serverPort 配置项。
+ */
+export declare function derivePort(key: string): number;
 /**
  * 本地图片服务：把生成结果通过 http://127.0.0.1:<port>/img/<id>?w=<width> 暴露给客户端渲染。
  *
  * 客户端限制说明：图片只有出现在助手回复的 Markdown 正文里才会渲染，
  * 而正文里的 file:// 会被 Chromium 拦截，所以必须走本地 HTTP。
  *
- * 安全边界：只服务显式 register() 过的文件，id 为随机值，URL 里没有真实路径，
- * 因此无法通过路径穿越读取任意文件。
+ * 稳定性：id 是「文件相对 outDir 的路径」做 base64url 编码，可逆且稳定。
+ * 因此服务不需要任何内存登记表——同一个文件在任何一次启动里都能解析出同一个 id，
+ * 重启后历史消息里的旧链接依然可访问。
+ *
+ * 安全边界：请求里的 id 只允许解析成 outDir 内部的普通文件，
+ * 解析后会做 containment + realpath 双重校验，防路径穿越与符号链接逃逸。
  */
 export declare class ImageServer {
     private readonly idleMs;
+    private readonly configuredPort;
+    private readonly cache;
     private server?;
     private port;
-    private registry;
-    private previews;
+    private root?;
+    private ready;
+    private owned;
+    /** outDir 之外的文件退回进程内随机 id（仅本次运行有效） */
+    private extra;
     private timer?;
     private starting?;
-    constructor(idleMs: number);
+    constructor(idleMs: number, configuredPort: number, cache: PreviewCache);
     get baseURL(): string;
-    /** 注册文件并返回可访问的 id */
-    register(file: string): string;
-    url(id: string, width: number): string;
-    /** 懒启动：首次需要时监听随机端口；unref 后不阻塞宿主进程退出 */
-    start(): Promise<void>;
+    /** 生成稳定 id；outDir 内的文件跨重启一致 */
+    idFor(file: string): string;
+    /**
+     * width > 0 时给出缩略图地址；width <= 0 时是原图地址（不带查询参数）。
+     * 末尾拼一段真实的文件名，纯粹为了让浏览器「另存为」时有个正常名字。
+     */
+    url(file: string, width: number): string;
+    /** 懒启动：首次需要时按派生端口监听；unref 后不阻塞宿主进程退出 */
+    start(opts: {
+        outDir: string;
+    }): Promise<void>;
     /**
      * 关闭服务并清理预览缓存。
      * 默认不调用：历史消息里的图片会重新请求，提前关闭会 404。
      */
     stop(): void;
+    /** 缩略图缓存的统计 / 清理，透传给上层工具与展示通知 */
+    cacheStats(): import("./cache.js").CacheStats;
+    cleanCache(): {
+        dir: string;
+        count: number;
+        bytes: number;
+    };
+    consumeCacheNotice(): string | undefined;
     private listen;
+    private servedByUs;
     private arm;
     private preview;
+    /** id -> 文件；只接受 outDir 内、真实存在、且 realpath 不逃逸的普通文件 */
+    private resolve;
     private handle;
     private send;
 }

package/dist/update.d.ts

@@ -0,0 +1,9 @@
+export declare const REGISTRY = "https://registry.npmjs.org";
+export declare const PACKAGE = "opencode-image";
+/** 只做 x.y.z + 预发布标识的比较，够用且不引依赖 */
+export declare function isNewer(candidate: string, current: string): boolean;
+/** 从包自身的 package.json 读版本；dist/index.js 与 src/index.ts 都能解析到 */
+export declare function readOwnVersion(): string | undefined;
+export declare function upgradeHint(latest: string, current: string): string;
+/** 查 npm 最新版；落后则返回提示行，否则返回 undefined。失败一律当作"没查到"。 */
+export declare function checkForUpdate(current: string, timeoutMs?: number): Promise<string | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-image",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Image generation and editing tools for opencode, with inline rendering in the conversation.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "bin",
     "README.md",
     "LICENSE"
   ],
@@ -42,7 +43,8 @@
     "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "prepublishOnly": "bun run build && bun test"
+    "prepublishOnly": "bun run build && bun test",
+    "release": "npm version patch && npm publish && rm -rf ~/.cache/opencode/packages/opencode-image*"
   },
   "engines": {
     "node": ">=18"
@@ -54,5 +56,8 @@
   "devDependencies": {
     "@types/node": "^24.12.2",
     "typescript": "^5.8.2"
+  },
+  "bin": {
+    "opencode-image": "./bin/cli.js"
   }
 }