opencode-image 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-image contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# opencode-image
+
+给 [opencode](https://opencode.ai) 用的图片生成 / 编辑插件，支持把生成的图片**直接渲染在对话里**。
+
+- `image_generate` — 文生图
+- `image_edit` — 图生图（基于上一张继续改）
+- 兼容任何 OpenAI 风格的 `/images/generations` 与 `/images/edits` 接口
+- 跨平台缩放（基于 [sharp](https://sharp.pixelplumbing.com)），不依赖 `sips` 等系统命令
+
+## 安装
+
+在 `opencode.json` / `opencode.jsonc` 里配置：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["opencode-image", { "apiKey": "sk-..." }]
+  ]
+}
+```
+
+opencode 启动时会自动从 npm 安装插件到 `~/.cache/opencode/packages/opencode-image/node_modules/`。
+
+## 配置项
+
+`plugin` 数组的元组形式第二个元素就是插件配置：
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `apiKey` | `PI_IMAGE_API_KEY` | **必填**。接口密钥，建议用环境变量而不是写进配置 |
+| `baseURL` | `PI_IMAGE_BASE_URL` 或内置默认 | OpenAI 兼容接口地址 |
+| `model` | `gpt-image-2` | 模型名 |
+| `outDir` | `<项目目录>/.opencode-images` | 图片输出目录，相对路径基于当前项目 |
+| `maxSize` | `1024` | 落盘图片最长边上限，超出等比缩小 |
+| `displayMaxSize` | `448` | 仅在对话里展示的尺寸，不影响落盘原图 |
+| `serverIdleMs` | `0` | 本地图片服务空闲关闭时间（毫秒），`0` = 不主动关闭 |
+| `timeoutMs` | `600000` | 单次请求超时 |
+
+## 图片是怎么显示出来的
+
+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)`
+4. 工具描述里强制模型把这行**原样抄进回复正文**
+
+服务的安全边界：只服务显式注册过的文件，URL 里没有真实路径，无法路径穿越读取任意文件。
+
+服务的生命周期：**首次生成图片时懒启动**，端口随机；`unref()` 后不阻塞 opencode 退出，
+opencode 进程结束即自动释放。默认不主动关闭——历史消息里的图片会被重新请求，提前关闭会 404。
+
+> 同时在工具结果里返回了 `attachments`，这样模型自己也能看到生成的图，便于继续迭代。
+
+## 环境变量
+
+```bash
+export PI_IMAGE_API_KEY=sk-...
+export PI_IMAGE_BASE_URL=https://api.example.com/v1
+```
+
+## 平台支持
+
+缩放使用 `sharp`（Node-API 原生模块，npm 会自动装对应平台的预编译包），
+macOS / Linux / Windows 均可。
+
+## 开发
+
+```bash
+bun install
+bun test        # 端到端测试：桩掉图像接口，验证落盘、缩放、服务与安全边界
+bun run build   # 产出 dist/index.js + dist/index.d.ts
+```
+
+## 已知限制
+
+- 只有能渲染 Markdown 图片的客户端才看得到图；纯终端 TUI 里会退化成一串 URL。
+- 预览图缓存在系统临时目录，`serverIdleMs = 0`（默认）时随进程退出由系统回收。
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,23 @@
+export type RemoteImage = {
+    url?: string;
+    b64?: string;
+    usage?: unknown;
+};
+/** 从 JSON 或 SSE（data: 行）响应里取出第一张图片 */
+export declare function parseImageResponse(body: string): RemoteImage;
+/** 把外部 AbortSignal 与超时合并成一个可清理的 signal */
+export declare function withTimeout(external: AbortSignal, ms: number): {
+    signal: AbortSignal;
+    clear: () => void;
+};
+type RequestConfig = {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    timeoutMs: number;
+};
+/** 下载图片 URL 或 base64 内容为字节 */
+export declare function fetchImageBytes(image: RemoteImage, signal: AbortSignal): Promise<Buffer>;
+export declare function generateImage(config: RequestConfig, prompt: string, signal: AbortSignal): Promise<RemoteImage>;
+export declare function editImage(config: RequestConfig, source: Buffer, filename: string, prompt: string, signal: AbortSignal): Promise<RemoteImage>;
+export {};

package/dist/image.d.ts

@@ -0,0 +1,24 @@
+export type Dimensions = {
+    width: number;
+    height: number;
+};
+/** resize 参数：等比缩到最长边不超过 max，且绝不放大 */
+export declare function fitInside(max: number): {
+    width: number;
+    height: number;
+    fit: "inside";
+    withoutEnlargement: boolean;
+};
+/** 读取图片尺寸，不是合法图片时抛错 */
+export declare function imageDimensions(file: string): Promise<Dimensions>;
+/** 读取任意图片并按需缩放，统一输出 PNG 字节（用于上传接口，mime 才准确） */
+export declare function toPngBuffer(source: string, maxSize: number): Promise<Buffer>;
+/** 生成等比缩放的 PNG 预览；原图本身不超过 max 时直接返回原图路径 */
+export declare function renderPreview(source: string, destination: string, max: number): Promise<string>;
+/**
+ * 把接口返回的原始字节归一化为 PNG 落盘：
+ * 1. 先写 staging 文件，再从落盘字节读尺寸（避免半截文件被当成成品）
+ * 2. 超过 maxSize 时等比缩小
+ * 3. 统一转 PNG，保证扩展名、mime 与实际字节一致
+ */
+export declare function persistImage(raw: Buffer, destination: string, maxSize: number): Promise<Dimensions>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type Plugin } from "@opencode-ai/plugin";
+export declare const OpenCodeImagePlugin: Plugin;
+export default OpenCodeImagePlugin;

package/dist/index.js

@@ -0,0 +1,392 @@
+// src/index.ts
+import { tool } from "@opencode-ai/plugin";
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+
+// src/api.ts
+function parseImageResponse(body) {
+  const trimmed = body.trim();
+  if (trimmed.startsWith("{")) {
+    return fromPayload(JSON.parse(trimmed));
+  }
+  for (const line of trimmed.split(/\r?\n/)) {
+    const raw = line.trim();
+    if (!raw.startsWith("data:"))
+      continue;
+    const payload = raw.slice(5).trim();
+    if (!payload || payload === "[DONE]")
+      continue;
+    try {
+      return fromPayload(JSON.parse(payload));
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(`opencode-image: no image in response: ${trimmed.slice(0, 500)}`);
+}
+function fromPayload(obj) {
+  const item = obj?.data?.[0] ?? obj;
+  if (item?.b64_json)
+    return { b64: item.b64_json, usage: obj?.usage ?? item?.usage };
+  if (typeof item?.url === "string")
+    return { url: item.url, usage: obj?.usage ?? item?.usage };
+  throw new Error(`opencode-image: no image in response payload: ${JSON.stringify(obj).slice(0, 500)}`);
+}
+function withTimeout(external, ms) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(new Error(`timed out after ${ms}ms`)), ms);
+  const forward = () => controller.abort(external.reason);
+  if (external.aborted)
+    forward();
+  else
+    external.addEventListener("abort", forward, { once: true });
+  return {
+    signal: controller.signal,
+    clear: () => {
+      clearTimeout(timer);
+      external.removeEventListener("abort", forward);
+    }
+  };
+}
+async function readImage(res, endpoint) {
+  const body = await res.text();
+  if (!res.ok) {
+    throw new Error(`opencode-image: ${endpoint} HTTP ${res.status}: ${body.slice(0, 500)}`);
+  }
+  return parseImageResponse(body);
+}
+async function fetchImageBytes(image, signal) {
+  if (image.b64)
+    return Buffer.from(image.b64, "base64");
+  if (!image.url)
+    throw new Error("opencode-image: response has neither url nor b64_json");
+  const res = await fetch(image.url, { signal });
+  if (!res.ok)
+    throw new Error(`opencode-image: image download failed: HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+async function generateImage(config, prompt, signal) {
+  const res = await fetch(`${config.baseURL}/images/generations`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${config.apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ model: config.model, prompt, n: 1 }),
+    signal
+  });
+  return readImage(res, "POST /images/generations");
+}
+async function editImage(config, source, filename, prompt, signal) {
+  const form = new FormData;
+  form.append("model", config.model);
+  form.append("prompt", prompt);
+  form.append("image", new Blob([new Uint8Array(source)], { type: "image/png" }), filename);
+  const res = await fetch(`${config.baseURL}/images/edits`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${config.apiKey}` },
+    body: form,
+    signal
+  });
+  return readImage(res, "POST /images/edits");
+}
+
+// src/image.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import sharp from "sharp";
+function fitInside(max) {
+  return { width: max, height: max, fit: "inside", withoutEnlargement: true };
+}
+async function imageDimensions(file) {
+  const meta = await sharp(file).metadata();
+  if (!meta.width || !meta.height) {
+    throw new Error(`opencode-image: cannot read image dimensions: ${file}`);
+  }
+  return { width: meta.width, height: meta.height };
+}
+async function toPngBuffer(source, maxSize) {
+  const current = await imageDimensions(source);
+  const pipeline = Math.max(current.width, current.height) > maxSize ? sharp(source).resize(fitInside(maxSize)) : sharp(source);
+  return pipeline.png().toBuffer();
+}
+async function renderPreview(source, destination, max) {
+  const current = await imageDimensions(source);
+  if (Math.max(current.width, current.height) <= max)
+    return source;
+  await sharp(source).resize(fitInside(max)).png().toFile(destination);
+  return destination;
+}
+async function persistImage(raw, destination, maxSize) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  const staging = `${destination}.${process.pid}-${Date.now()}.download`;
+  fs.writeFileSync(staging, raw);
+  try {
+    const meta = await sharp(staging).metadata();
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    if (!width || !height)
+      throw new Error("opencode-image: response is not a decodable image");
+    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 });
+  }
+  return imageDimensions(destination);
+}
+
+// src/options.ts
+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_IDLE_MS = 0;
+var DEFAULT_TIMEOUT_MS = 600000;
+function resolveOptions(options) {
+  const opts = options ?? {};
+  const apiKey = opts.apiKey ?? process.env.PI_IMAGE_API_KEY;
+  if (!apiKey) {
+    throw new Error("opencode-image: missing apiKey. Pass it in the plugin options or set PI_IMAGE_API_KEY.");
+  }
+  return {
+    baseURL: (opts.baseURL ?? process.env.PI_IMAGE_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    apiKey,
+    model: opts.model ?? DEFAULT_MODEL,
+    outDir: opts.outDir,
+    maxSize: opts.maxSize ?? DEFAULT_MAX_SIZE,
+    displayMaxSize: opts.displayMaxSize ?? DEFAULT_DISPLAY_MAX_SIZE,
+    serverIdleMs: opts.serverIdleMs ?? DEFAULT_SERVER_IDLE_MS,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  };
+}
+
+// src/server.ts
+import * as fs2 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";
+var MIME_BY_EXT = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif"
+};
+
+class ImageServer {
+  idleMs;
+  server;
+  port = 0;
+  registry = new Map;
+  previews = new Map;
+  timer;
+  starting;
+  constructor(idleMs) {
+    this.idleMs = idleMs;
+  }
+  get baseURL() {
+    return this.port ? `http://127.0.0.1:${this.port}` : "";
+  }
+  register(file) {
+    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 });
+    return id;
+  }
+  url(id, width) {
+    return `${this.baseURL}/img/${id}?w=${width}`;
+  }
+  async start() {
+    if (this.server) {
+      this.arm();
+      return;
+    }
+    if (!this.starting) {
+      this.starting = this.listen().finally(() => {
+        this.starting = undefined;
+      });
+    }
+    await this.starting;
+    this.arm();
+  }
+  stop() {
+    if (this.timer)
+      clearTimeout(this.timer);
+    this.timer = undefined;
+    const server = this.server;
+    this.server = undefined;
+    this.port = 0;
+    server?.closeAllConnections?.();
+    server?.close();
+    for (const file of this.previews.values())
+      fs2.rmSync(file, { force: true });
+    this.previews.clear();
+  }
+  async listen() {
+    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 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");
+    }
+    this.server = server;
+    this.port = port;
+  }
+  arm() {
+    if (this.timer)
+      clearTimeout(this.timer);
+    if (this.idleMs <= 0)
+      return;
+    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;
+    });
+  }
+  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)) {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("not found");
+      return;
+    }
+    this.send(entry, Number(parsed.searchParams.get("w")), res);
+  }
+  async send(entry, width, res) {
+    try {
+      const target = width > 0 ? await this.preview(entry.file, Math.round(width)) : entry.file;
+      const body = fs2.readFileSync(target);
+      res.writeHead(200, {
+        "content-type": entry.mime,
+        "content-length": body.length,
+        "cache-control": "private, max-age=86400"
+      });
+      res.end(body);
+    } catch (error) {
+      res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+      res.end(`opencode-image: cannot serve image: ${String(error)}`);
+    }
+  }
+}
+
+// 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");
+  if (filename) {
+    const target = path3.isAbsolute(filename) ? filename : path3.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`);
+}
+function asAttachment(file) {
+  return [
+    {
+      type: "file",
+      mime: "image/png",
+      filename: path3.basename(file),
+      url: `data:image/png;base64,${fs3.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 { 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)})`;
+    } catch (error) {
+      display = `[opencode-image: local image server unavailable, cannot render inline: ${String(error)}]`;
+    }
+    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(`
+`),
+      metadata: { file, prompt, usage },
+      attachments: asAttachment(file)
+    };
+  };
+  const generate = async (args, ctx) => {
+    ctx.metadata({ title: `Generating image: ${args.prompt.slice(0, 60)}` });
+    const { signal, clear } = withTimeout(ctx.abort, options.timeoutMs);
+    try {
+      const remote = await generateImage(options, 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 generated", args.prompt, destination, 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))
+      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 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);
+    } finally {
+      clear();
+    }
+  };
+  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.",
+        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")
+        },
+        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.",
+        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
+      })
+    }
+  };
+};
+var src_default = OpenCodeImagePlugin;
+export {
+  src_default as default,
+  OpenCodeImagePlugin
+};

package/dist/options.d.ts

@@ -0,0 +1,37 @@
+/** 插件可配置项，通过 opencode 配置的 `plugin` 元组第二个元素传入 */
+export type PluginOptions = {
+    /** OpenAI 兼容的图像接口地址，默认从 PI_IMAGE_BASE_URL 读取 */
+    baseURL?: string;
+    /** 接口密钥，默认从 PI_IMAGE_API_KEY 读取 */
+    apiKey?: string;
+    /** 图像模型名 */
+    model?: string;
+    /** 图片输出目录；相对路径基于当前项目目录，默认 <project>/.opencode-images */
+    outDir?: string;
+    /** 落盘图片的最长边上限（像素），超出会等比缩小 */
+    maxSize?: number;
+    /** 在对话里展示的图片最长边（像素）；只影响展示，不影响落盘原图 */
+    displayMaxSize?: number;
+    /** 本地图片服务的空闲关闭时间（毫秒），0 表示不主动关闭 */
+    serverIdleMs?: 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;
+export declare const DEFAULT_SERVER_IDLE_MS = 0;
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+export type ResolvedOptions = {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    outDir?: string;
+    maxSize: number;
+    displayMaxSize: number;
+    serverIdleMs: number;
+    timeoutMs: number;
+};
+/** 合并默认值、环境变量与用户配置；缺少 apiKey 时直接抛错 */
+export declare function resolveOptions(options: PluginOptions | undefined): ResolvedOptions;

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 本地图片服务：把生成结果通过 http://127.0.0.1:<port>/img/<id>?w=<width> 暴露给客户端渲染。
+ *
+ * 客户端限制说明：图片只有出现在助手回复的 Markdown 正文里才会渲染，
+ * 而正文里的 file:// 会被 Chromium 拦截，所以必须走本地 HTTP。
+ *
+ * 安全边界：只服务显式 register() 过的文件，id 为随机值，URL 里没有真实路径，
+ * 因此无法通过路径穿越读取任意文件。
+ */
+export declare class ImageServer {
+    private readonly idleMs;
+    private server?;
+    private port;
+    private registry;
+    private previews;
+    private timer?;
+    private starting?;
+    constructor(idleMs: number);
+    get baseURL(): string;
+    /** 注册文件并返回可访问的 id */
+    register(file: string): string;
+    url(id: string, width: number): string;
+    /** 懒启动：首次需要时监听随机端口；unref 后不阻塞宿主进程退出 */
+    start(): Promise<void>;
+    /**
+     * 关闭服务并清理预览缓存。
+     * 默认不调用：历史消息里的图片会重新请求，提前关闭会 404。
+     */
+    stop(): void;
+    private listen;
+    private arm;
+    private preview;
+    private handle;
+    private send;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "opencode-image",
+  "version": "0.1.0",
+  "description": "Image generation and editing tools for opencode, with inline rendering in the conversation.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "image",
+    "image-generation",
+    "gpt-image"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jianhao/opencode-image.git"
+  },
+  "homepage": "https://github.com/jianhao/opencode-image#readme",
+  "bugs": {
+    "url": "https://github.com/jianhao/opencode-image/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build src/index.ts --target=node --format=esm --external sharp --external @opencode-ai/plugin --outfile=dist/index.js",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.18.30",
+    "sharp": "^0.35.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "typescript": "^5.8.2"
+  }
+}