opencode-image 0.1.0 → 0.1.1

package/README.md

@@ -34,7 +34,9 @@ opencode 启动时会自动从 npm 安装插件到 `~/.cache/opencode/packages/o
 | `outDir` | `<项目目录>/.opencode-images` | 图片输出目录，相对路径基于当前项目 |
 | `maxSize` | `1024` | 落盘图片最长边上限，超出等比缩小 |
 | `displayMaxSize` | `448` | 仅在对话里展示的尺寸，不影响落盘原图 |
+| `serverPort` | `0` | 本地图片服务端口。`0` = 由项目目录派生（同一项目恒定，保证历史链接跨重启有效） |
 | `serverIdleMs` | `0` | 本地图片服务空闲关闭时间（毫秒），`0` = 不主动关闭 |
+| `updateCheck` | `true` | 首次出图时查一次 npm 最新版，落后则在工具输出末尾附升级提示 |
 | `timeoutMs` | `600000` | 单次请求超时 |
 
 ## 图片是怎么显示出来的
@@ -43,17 +45,54 @@ openCode（桌面端 / Web）**只在助手回复的 Markdown 正文里渲染图
 而正文里的 `file://` 会被 Chromium 拦掉，所以插件做了这件事：
 
 1. 图片落盘到 `outDir`
-2. 插件进程内起一个只绑 `127.0.0.1` 的 HTTP 服务，为图片分配随机 id
+2. 插件进程内起一个只绑 `127.0.0.1` 的 HTTP 服务
 3. 工具输出第一行给出 `![alt](http://127.0.0.1:<port>/img/<id>?w=448)`
 4. 工具描述里强制模型把这行**原样抄进回复正文**
 
-服务的安全边界：只服务显式注册过的文件，URL 里没有真实路径，无法路径穿越读取任意文件。
+**链接为什么跨重启还有效**：`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 + 清掉本机缓存
+```
+
 ## 环境变量
 
 ```bash
@@ -78,6 +117,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,79 @@
+#!/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 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} --version    显示版本
+  npx ${PACKAGE} --help       显示帮助
+
+为什么需要 --update:
+  opencode 对 npm 形式的插件不做版本检查——只要缓存目录里已经装过就直接复用。
+  所以发布新版后必须清掉缓存，opencode 才会重新下载。详见 README「升级」一节。
+`
+
+/** 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 update() {
+  const root = cacheRoot()
+  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 后会重新下载最新版。`)
+}
+
+const args = process.argv.slice(2)
+
+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)
+}
+
+console.log(USAGE)
+process.exit(1)

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import { tool } from "@opencode-ai/plugin";
-import * as fs3 from "node:fs";
+import * as fs4 from "node:fs";
 import * as path3 from "node:path";
 
 // src/api.ts
@@ -137,6 +137,7 @@ 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_SERVER_PORT = 0;
 var DEFAULT_SERVER_IDLE_MS = 0;
 var DEFAULT_TIMEOUT_MS = 600000;
 function resolveOptions(options) {
@@ -152,17 +153,76 @@ 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,
     timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
   };
 }
 
-// src/server.ts
+// src/update.ts
 import * as fs2 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(fs2.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 fs3 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 { createHash, randomUUID } from "node:crypto";
 var MIME_BY_EXT = {
   ".png": "image/png",
   ".jpg": "image/jpeg",
@@ -170,71 +230,114 @@ 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 = createHash("sha1").update(key).digest();
+  return 41000 + digest.readUInt16BE(0) % 4000;
+}
 
 class ImageServer {
   idleMs;
+  configuredPort;
   server;
   port = 0;
-  registry = new Map;
+  root;
+  ready = false;
+  owned = false;
+  extra = new Map;
   previews = new Map;
   timer;
   starting;
-  constructor(idleMs) {
+  constructor(idleMs, configuredPort) {
     this.idleMs = idleMs;
+    this.configuredPort = configuredPort;
   }
   get baseURL() {
     return this.port ? `http://127.0.0.1:${this.port}` : "";
   }
-  register(file) {
+  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");
+      }
+    }
+    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) {
+    return `${this.baseURL}/img/${this.idFor(file)}?w=${width}`;
   }
-  async start() {
-    if (this.server) {
+  async start(opts) {
+    this.root = path2.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 });
+      fs3.rmSync(file, { force: true });
     this.previews.clear();
   }
-  async listen() {
+  async listen(opts) {
+    const port = this.configuredPort || derivePort(opts.directory);
     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((resolve2) => {
+      server.once("error", resolve2);
+      server.listen(port, "127.0.0.1", () => resolve2(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 === path2.resolve(outDir);
+    } catch {
+      return false;
     }
-    this.server = server;
-    this.port = port;
   }
   arm() {
     if (this.timer)
@@ -247,7 +350,7 @@ class ImageServer {
   preview(source, max) {
     const key = `${source}@${max}`;
     const cached = this.previews.get(key);
-    if (cached && fs2.existsSync(cached))
+    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) => {
@@ -256,24 +359,60 @@ class ImageServer {
       return file;
     });
   }
+  resolve(id) {
+    const registered = this.extra.get(id);
+    if (registered)
+      return fs3.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") || path2.isAbsolute(relative2))
+      return;
+    const target = path2.resolve(root, relative2);
+    if (target === root || !target.startsWith(root + path2.sep))
+      return;
+    try {
+      if (!fs3.statSync(target).isFile())
+        return;
+      const real = fs3.realpathSync(target);
+      const realRoot = fs3.realpathSync(root);
+      if (real !== realRoot && !real.startsWith(realRoot + path2.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 = fs3.readFileSync(target);
       res.writeHead(200, {
-        "content-type": entry.mime,
+        "content-type": MIME_BY_EXT[path2.extname(target).toLowerCase()] ?? "application/octet-stream",
         "content-length": body.length,
         "cache-control": "private, max-age=86400"
       });
@@ -287,8 +426,13 @@ 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 = 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);
     return `${target.replace(/\.[A-Za-z0-9]+$/, "")}.png`;
@@ -303,31 +447,44 @@ function asAttachment(file) {
       type: "file",
       mime: "image/png",
       filename: path3.basename(file),
-      url: `data:image/png;base64,${fs3.readFileSync(file).toString("base64")}`
+      url: `data:image/png;base64,${fs4.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 server = new ImageServer(options.serverIdleMs, options.serverPort);
+  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({ directory: ctx.directory, outDir: resolveOutDir(ctx.directory, options.outDir) });
+      display = `![${prompt.slice(0, 60)}](${server.url(file, options.displayMaxSize)})`;
     } 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);
     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,14 +498,14 @@ 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))
+    if (!fs4.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);
@@ -358,7 +515,7 @@ 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 edited", args.prompt, destination, remote.usage);
+      return result("Image edited", args.prompt, destination, ctx, remote.usage);
     } finally {
       clear();
     }

package/dist/options.d.ts

@@ -12,8 +12,12 @@ export type PluginOptions = {
     maxSize?: number;
     /** 在对话里展示的图片最长边（像素）；只影响展示，不影响落盘原图 */
     displayMaxSize?: number;
+    /** 本地图片服务端口；默认 0 = 由项目目录派生（同一项目恒定），需要避开占用时手动指定 */
+    serverPort?: number;
     /** 本地图片服务的空闲关闭时间（毫秒），0 表示不主动关闭 */
     serverIdleMs?: number;
+    /** 首次出图时查一次 npm 最新版，落后则在工具输出末尾附升级提示。默认开启 */
+    updateCheck?: boolean;
     /** 单次图像请求超时（毫秒） */
     timeoutMs?: number;
 };
@@ -21,6 +25,8 @@ 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_SERVER_PORT = 0;
 export declare const DEFAULT_SERVER_IDLE_MS = 0;
 export declare const DEFAULT_TIMEOUT_MS = 600000;
 export type ResolvedOptions = {
@@ -30,7 +36,9 @@ export type ResolvedOptions = {
     outDir?: string;
     maxSize: number;
     displayMaxSize: number;
+    serverPort: number;
     serverIdleMs: number;
+    updateCheck: boolean;
     timeoutMs: number;
 };
 /** 合并默认值、环境变量与用户配置；缺少 apiKey 时直接抛错 */

package/dist/server.d.ts

@@ -1,35 +1,55 @@
+/**
+ * 端口由项目目录派生：同一个项目永远是同一个端口，所以历史消息里的链接跨重启仍然有效；
+ * 不同项目基本不会撞到同一个端口。需要覆盖时用 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 server?;
     private port;
-    private registry;
+    private root?;
+    private ready;
+    private owned;
+    /** outDir 之外的文件退回进程内随机 id（仅本次运行有效） */
+    private extra;
     private previews;
     private timer?;
     private starting?;
-    constructor(idleMs: number);
+    constructor(idleMs: number, configuredPort: number);
     get baseURL(): string;
-    /** 注册文件并返回可访问的 id */
-    register(file: string): string;
-    url(id: string, width: number): string;
-    /** 懒启动：首次需要时监听随机端口；unref 后不阻塞宿主进程退出 */
-    start(): Promise<void>;
+    /** 生成稳定 id；outDir 内的文件跨重启一致 */
+    idFor(file: string): string;
+    url(file: string, width: number): string;
+    /** 懒启动：首次需要时按派生端口监听；unref 后不阻塞宿主进程退出 */
+    start(opts: {
+        directory: string;
+        outDir: string;
+    }): Promise<void>;
     /**
      * 关闭服务并清理预览缓存。
      * 默认不调用：历史消息里的图片会重新请求，提前关闭会 404。
      */
     stop(): void;
     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.1",
   "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"
   }
 }