opencode-image 0.1.1 → 0.1.2

package/README.md

@@ -31,12 +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` | 单次请求超时 |
 
 ## 图片是怎么显示出来的
@@ -44,11 +46,20 @@ opencode 启动时会自动从 npm 安装插件到 `~/.cache/opencode/packages/o
 openCode（桌面端 / Web）**只在助手回复的 Markdown 正文里渲染图片**，工具输出一律按纯文本处理。
 而正文里的 `file://` 会被 Chromium 拦掉，所以插件做了这件事：
 
-1. 图片落盘到 `outDir`
+1. 图片落盘到 `outDir`（默认是全局数据目录，不在项目里）
 2. 插件进程内起一个只绑 `127.0.0.1` 的 HTTP 服务
-3. 工具输出第一行给出 `![alt](http://127.0.0.1:<port>/img/<id>?w=448)`
+3. 工具输出给出 `![alt](...)`（`displayMaxSize = 0` 时就是原图）
 4. 工具描述里强制模型把这行**原样抄进回复正文**
 
+> **不支持「图片套链接」**：opencode 覆写了 marked 的 link renderer，取的是链接里的原始文本，
+> `[![图](缩略图)](原图)` 里的图片不会被渲染。所以缩略图模式下改成两行：
+> `![alt](缩略图)` + `[查看原图](原图)`。
+>
+> 显示原图还是缩略图只取决于 `displayMaxSize`：
+> - `0`（默认）→ 直接显示原图，会话里右键 Copy / Save 拿到的就是原图
+> - `> 0`（如 `448`）→ 会话里显示轻量缩略图，下面附带一个「查看原图」链接，
+>   点击会用系统浏览器打开原图（opencode 把所有外链交给系统浏览器）
+
 **链接为什么跨重启还有效**：`id` 是「文件相对 `outDir` 的路径」的 base64url 编码，可逆且稳定；
 端口默认由项目目录派生（同一项目恒定）。所以服务**不需要任何内存登记表**，
 重启后历史消息里的旧链接仍能解析到同一个文件。
@@ -93,6 +104,51 @@ 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

package/bin/cli.js

@@ -4,6 +4,9 @@ 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 {
@@ -17,22 +20,38 @@ const version = (() => {
 const USAGE = `${PACKAGE} v${version}
 
 用法:
-  npx ${PACKAGE} --update     清理 opencode 的插件缓存，然后重启 opencode 即可装上最新版
-  npx ${PACKAGE} --version    显示版本
-  npx ${PACKAGE} --help       显示帮助
+  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 cacheRoot() {
-  return process.env.OPENCODE_IMAGE_CACHE_ROOT ?? path.join(os.homedir(), ".cache", "opencode", "packages")
+function pluginCacheRoot() {
+  return process.env.OPENCODE_IMAGE_PLUGIN_CACHE ?? path.join(os.homedir(), ".cache", "opencode", "packages")
 }
 
 function update() {
-  const root = cacheRoot()
+  const root = pluginCacheRoot()
   if (!fs.existsSync(root)) {
     console.log(`缓存目录不存在，无需清理：${root}`)
     console.log("直接重启 opencode 即可。")
@@ -58,7 +77,33 @@ function update() {
   console.log(`✅ 已清理 ${targets.length} 个缓存目录，重启 opencode 后会重新下载最新版。`)
 }
 
-const args = process.argv.slice(2)
+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)
@@ -75,5 +120,10 @@ if (args.includes("--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 fs4 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,27 @@ 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;
@@ -156,12 +295,14 @@ function resolveOptions(options) {
     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 fs2 from "node:fs";
+import * as fs3 from "node:fs";
 var REGISTRY = "https://registry.npmjs.org";
 var PACKAGE = "opencode-image";
 function parse(version) {
@@ -187,14 +328,14 @@ function isNewer(candidate, current) {
 function readOwnVersion() {
   try {
     const file = new URL("../package.json", import.meta.url);
-    const pkg = JSON.parse(fs2.readFileSync(file, "utf8"));
+    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。`;
+  return `[请转述给用户] ${PACKAGE} 有新版本 ${latest}（当前 ${current}）。升级：npx ${PACKAGE} --update 然后重启 opencode。`;
 }
 async function checkForUpdate(current, timeoutMs = 3000) {
   const controller = new AbortController;
@@ -218,11 +359,11 @@ async function checkForUpdate(current, timeoutMs = 3000) {
 }
 
 // src/server.ts
-import * as fs3 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 { createHash, 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",
@@ -230,28 +371,29 @@ var MIME_BY_EXT = {
   ".webp": "image/webp",
   ".gif": "image/gif"
 };
-var ID_PATTERN = /^\/img\/([A-Za-z0-9_-]{1,2048})$/;
+var ID_PATTERN = /^\/img\/([A-Za-z0-9_-]{1,2048})(?:\/[^/]*)?$/;
 var APP_NAME = "opencode-image";
 function derivePort(key) {
-  const digest = createHash("sha1").update(key).digest();
+  const digest = createHash2("sha1").update(key).digest();
   return 41000 + digest.readUInt16BE(0) % 4000;
 }
 
 class ImageServer {
   idleMs;
   configuredPort;
+  cache;
   server;
   port = 0;
   root;
   ready = false;
   owned = false;
   extra = new Map;
-  previews = new Map;
   timer;
   starting;
-  constructor(idleMs, configuredPort) {
+  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}` : "";
@@ -259,9 +401,9 @@ class ImageServer {
   idFor(file) {
     const root = this.root;
     if (root) {
-      const relative2 = path2.relative(root, file);
-      if (relative2 && !relative2.startsWith("..") && !path2.isAbsolute(relative2)) {
-        return Buffer.from(relative2.split(path2.sep).join("/"), "utf8").toString("base64url");
+      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) {
@@ -273,10 +415,12 @@ class ImageServer {
     return id;
   }
   url(file, width) {
-    return `${this.baseURL}/img/${this.idFor(file)}?w=${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(opts) {
-    this.root = path2.resolve(opts.outDir);
+    this.root = path4.resolve(opts.outDir);
     if (this.ready) {
       this.arm();
       return;
@@ -302,17 +446,23 @@ class ImageServer {
     this.owned = false;
     this.ready = false;
     this.port = 0;
-    for (const file of this.previews.values())
-      fs3.rmSync(file, { force: true });
-    this.previews.clear();
+  }
+  cacheStats() {
+    return this.cache.stats();
+  }
+  cleanCache() {
+    return this.cache.clean();
+  }
+  consumeCacheNotice() {
+    return this.cache.consumeNotice();
   }
   async listen(opts) {
-    const port = this.configuredPort || derivePort(opts.directory);
+    const port = this.configuredPort || derivePort(path4.resolve(opts.outDir));
     const server = http.createServer((req, res) => void this.handle(req, res));
     server.unref();
-    const failure = await new Promise((resolve2) => {
-      server.once("error", resolve2);
-      server.listen(port, "127.0.0.1", () => resolve2(undefined));
+    const failure = await new Promise((resolve3) => {
+      server.once("error", resolve3);
+      server.listen(port, "127.0.0.1", () => resolve3(undefined));
     });
     if (!failure) {
       this.server = server;
@@ -334,7 +484,7 @@ class ImageServer {
       if (!res.ok)
         return false;
       const body = await res.json();
-      return body.app === APP_NAME && body.root === path2.resolve(outDir);
+      return body.app === APP_NAME && body.root === path4.resolve(outDir);
     } catch {
       return false;
     }
@@ -347,22 +497,20 @@ 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 && fs3.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 fs3.existsSync(registered) ? registered : undefined;
+      return fs4.existsSync(registered) ? registered : undefined;
     const root = this.root;
     if (!root)
       return;
@@ -372,17 +520,17 @@ class ImageServer {
     } catch {
       return;
     }
-    if (!relative2 || relative2.includes("\x00") || path2.isAbsolute(relative2))
+    if (!relative2 || relative2.includes("\x00") || path4.isAbsolute(relative2))
       return;
-    const target = path2.resolve(root, relative2);
-    if (target === root || !target.startsWith(root + path2.sep))
+    const target = path4.resolve(root, relative2);
+    if (target === root || !target.startsWith(root + path4.sep))
       return;
     try {
-      if (!fs3.statSync(target).isFile())
+      if (!fs4.statSync(target).isFile())
         return;
-      const real = fs3.realpathSync(target);
-      const realRoot = fs3.realpathSync(root);
-      if (real !== realRoot && !real.startsWith(realRoot + path2.sep))
+      const real = fs4.realpathSync(target);
+      const realRoot = fs4.realpathSync(root);
+      if (real !== realRoot && !real.startsWith(realRoot + path4.sep))
         return;
     } catch {
       return;
@@ -410,9 +558,9 @@ class ImageServer {
   async send(file, width, res) {
     try {
       const target = width > 0 ? await this.preview(file, Math.round(width)) : file;
-      const body = fs3.readFileSync(target);
+      const body = fs4.readFileSync(target);
       res.writeHead(200, {
-        "content-type": MIME_BY_EXT[path2.extname(target).toLowerCase()] ?? "application/octet-stream",
+        "content-type": MIME_BY_EXT[path4.extname(target).toLowerCase()] ?? "application/octet-stream",
         "content-length": body.length,
         "cache-control": "private, max-age=86400"
       });
@@ -426,34 +574,30 @@ class ImageServer {
 
 // src/index.ts
 var z = tool.schema;
-function resolveOutDir(directory, outDir) {
-  if (!outDir)
-    return path3.join(directory, ".opencode-images");
-  return path3.isAbsolute(outDir) ? outDir : path3.join(directory, outDir);
-}
 function resolveDestination(filename, outDir, ctx) {
   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,${fs4.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, options.serverPort);
+  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;
@@ -468,8 +612,13 @@ var OpenCodeImagePlugin = async (_input, rawOptions) => {
     const { width, height } = await imageDimensions(file);
     let display;
     try {
-      await server.start({ directory: ctx.directory, outDir: resolveOutDir(ctx.directory, options.outDir) });
-      display = `![${prompt.slice(0, 60)}](${server.url(file, 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)}]`;
     }
@@ -482,6 +631,9 @@ var OpenCodeImagePlugin = async (_input, rawOptions) => {
     ];
     if (notice)
       output.push(notice);
+    const cacheNotice = server.consumeCacheNotice();
+    if (cacheNotice)
+      output.push(cacheNotice);
     return {
       title: `${label}: ${prompt.slice(0, 60)}`,
       output: output.join(`
@@ -504,14 +656,14 @@ var OpenCodeImagePlugin = async (_input, rawOptions) => {
     }
   };
   const edit = async (args, ctx) => {
-    const source = path3.isAbsolute(args.image) ? args.image : path3.resolve(ctx.directory, args.image);
-    if (!fs4.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);
@@ -523,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")
@@ -531,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,11 +15,14 @@ export type PluginOptions = {
     apiKey?: string;
     /** 图像模型名 */
     model?: string;
-    /** 图片输出目录；相对路径基于当前项目目录，默认 <project>/.opencode-images */
+    /**
+     * 图片输出目录。默认是全局数据目录（建议保持默认，跟项目/会话解耦）；
+     * 填相对路径（如 ".opencode-images"）会落在当前项目里。
+     */
     outDir?: string;
     /** 落盘图片的最长边上限（像素），超出会等比缩小 */
     maxSize?: number;
-    /** 在对话里展示的图片最长边（像素）；只影响展示，不影响落盘原图 */
+    /** 对话里展示时的最长边（像素）。0 = 不缩放，直接显示原图（默认，右键复制即原图） */
     displayMaxSize?: number;
     /** 本地图片服务端口；默认 0 = 由项目目录派生（同一项目恒定），需要避开占用时手动指定 */
     serverPort?: number;
@@ -18,13 +30,18 @@ export type PluginOptions = {
     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;
@@ -39,6 +56,8 @@ export type ResolvedOptions = {
     serverPort: number;
     serverIdleMs: number;
     updateCheck: boolean;
+    cacheDir: string;
+    cacheLimit: number;
     timeoutMs: number;
 };
 /** 合并默认值、环境变量与用户配置；缺少 apiKey 时直接抛错 */

package/dist/server.d.ts

@@ -1,6 +1,8 @@
+import { PreviewCache } from "./cache.js";
 /**
- * 端口由项目目录派生：同一个项目永远是同一个端口，所以历史消息里的链接跨重启仍然有效；
- * 不同项目基本不会撞到同一个端口。需要覆盖时用 serverPort 配置项。
+ * 端口由「图片根目录」派生：同一个根目录永远同一个端口，所以历史消息里的链接跨重启仍然有效。
+ * 默认根目录是全局数据目录，因此全机通用一个端口、一个服务；
+ * 若把 outDir 指到项目里，则那个项目有自己稳定的端口。需要覆盖时用 serverPort 配置项。
  */
 export declare function derivePort(key: string): number;
 /**
@@ -19,6 +21,7 @@ export declare function derivePort(key: string): number;
 export declare class ImageServer {
     private readonly idleMs;
     private readonly configuredPort;
+    private readonly cache;
     private server?;
     private port;
     private root?;
@@ -26,17 +29,19 @@ export declare class ImageServer {
     private owned;
     /** outDir 之外的文件退回进程内随机 id（仅本次运行有效） */
     private extra;
-    private previews;
     private timer?;
     private starting?;
-    constructor(idleMs: number, configuredPort: number);
+    constructor(idleMs: number, configuredPort: number, cache: PreviewCache);
     get baseURL(): string;
     /** 生成稳定 id；outDir 内的文件跨重启一致 */
     idFor(file: string): string;
+    /**
+     * width > 0 时给出缩略图地址；width <= 0 时是原图地址（不带查询参数）。
+     * 末尾拼一段真实的文件名，纯粹为了让浏览器「另存为」时有个正常名字。
+     */
     url(file: string, width: number): string;
     /** 懒启动：首次需要时按派生端口监听；unref 后不阻塞宿主进程退出 */
     start(opts: {
-        directory: string;
         outDir: string;
     }): Promise<void>;
     /**
@@ -44,6 +49,14 @@ export declare class ImageServer {
      * 默认不调用：历史消息里的图片会重新请求，提前关闭会 404。
      */
     stop(): void;
+    /** 缩略图缓存的统计 / 清理，透传给上层工具与展示通知 */
+    cacheStats(): import("./cache.js").CacheStats;
+    cleanCache(): {
+        dir: string;
+        count: number;
+        bytes: number;
+    };
+    consumeCacheNotice(): string | undefined;
     private listen;
     private servedByUs;
     private arm;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-image",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Image generation and editing tools for opencode, with inline rendering in the conversation.",
   "type": "module",
   "license": "MIT",