minimal-agent 0.10.0 → 0.12.0

package/src/multimodal.js

@@ -11,6 +11,7 @@ import { readFile, stat } from 'node:fs/promises';
 import { extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getWorkingDir } from './bootstrap/workingDir.js';
+import { removeManagedClipboardTemp } from './utils/clipboardImage.js';
 export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
 const IMAGE_MIME_BY_EXT = {
     '.jpg': 'image/jpeg',
@@ -18,8 +19,101 @@ const IMAGE_MIME_BY_EXT = {
     '.png': 'image/png',
     '.gif': 'image/gif',
     '.webp': 'image/webp',
+    // Read can attach BMP files directly even though inline drag/drop parsing
+    // intentionally remains limited to formats accepted by most providers.
+    '.bmp': 'image/bmp',
 };
 const IMAGE_EXT_PATTERN = String.raw `(?:png|jpe?g|gif|webp)`;
+/**
+ * 「路径 token」允许的字符：非空白，或 `\x` 这样的转义对——macOS Terminal / iTerm2
+ * 拖入文件时空格默认转义成 `\ `，不认它就会把 `/Users/me/My\ Pic.png` 切成两半。
+ * 反斜杠**只能**作为转义对的首字符出现（不写成 `(?:\\.|\S)`），这样两个分支互斥、
+ * 不会因重叠产生指数级回溯。
+ */
+const PATH_RUN = String.raw `(?:\\.|[^\s\\])`;
+/**
+ * 一次扫描认出所有「行内图片来源」的写法。分支顺序即优先级（同一起点按 alternation 左优先）：
+ *
+ *   ① `@"..."` / `@'...'` / `@bare`  —— 显式语法，用户主动指定
+ *   ② `"..."` / `'...'`              —— 裸引号包裹：Windows Terminal 拖入含空格路径时自带引号
+ *   ③ `https://…` / `file://…`       —— 裸 URL；GNOME Terminal / VTE 拖入给的正是 file:// URI
+ *   ④ `C:\…` / `C:/…` / `\\server\…` —— 裸 Windows 盘符与 UNC：Windows Terminal 拖入形态
+ *   ⑤ `./` `../` `/` `~/` 开头的路径 —— 裸 POSIX 路径（允许 `\ ` 转义空格）
+ *
+ * 为什么这几种写法必须全认：**终端把「拖进窗口的文件」翻译成一次「粘贴文件路径文本」**，
+ * stdin 上没有任何图片字节。所以"支持拖拽"= 认得出各终端各自的路径写法，然后自己去读盘。
+ * 各终端形态不统一（mac 转义空格 / Windows 加引号 / GNOME 给 URI），少认一种就是那个平台不能用。
+ *
+ * 一次拖多张图（空格或换行分隔）不需要额外切分：全局扫描天然逐个命中，
+ * 分隔符会被下一次匹配的 `(^|\s)` 前缀吃掉并原样留在文本里。
+ */
+const INLINE_SOURCE_RE = new RegExp(String.raw `(^|\s)(?:` +
+    [
+        String.raw `@"(?<atDouble>[^"\n]+)"`,
+        String.raw `@'(?<atSingle>[^'\n]+)'`,
+        String.raw `@(?<atBare>${PATH_RUN}+)`,
+        String.raw `"(?<quotedDouble>[^"\n]+\.${IMAGE_EXT_PATTERN})"`,
+        String.raw `'(?<quotedSingle>[^'\n]+\.${IMAGE_EXT_PATTERN})'`,
+        String.raw `(?<url>(?:https?|file):\/\/${PATH_RUN}+?\.${IMAGE_EXT_PATTERN}(?:[?#]\S*)?)`,
+        String.raw `(?<winPath>[A-Za-z]:[\\\/]${PATH_RUN}+?\.${IMAGE_EXT_PATTERN})(?!\w)`,
+        String.raw `(?<uncPath>\\\\${PATH_RUN}+?\.${IMAGE_EXT_PATTERN})(?!\w)`,
+        String.raw `(?<posixPath>(?:\.{1,2}\/|\/|~\/)${PATH_RUN}+?\.${IMAGE_EXT_PATTERN})(?!\w)`,
+    ].join('|') +
+    String.raw `)`, 'gi');
+/**
+ * 去掉 shell 转义反斜杠（`My\ Pic.png` → `My Pic.png`）。
+ *
+ * ⚠️ 判据只看**字符串长相**、绝不看 `process.platform`：同一个函数在 `-p` / stream-json
+ * 下会在 Linux 宿主上收到 Windows 路径，按平台判会把 `C:\Users\bills` 吃成 `C:Usersbills`。
+ * Windows 盘符 / UNC 开头的串里反斜杠是路径分隔符，原样返回。
+ */
+function unescapePathToken(value) {
+    if (/^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\'))
+        return value;
+    return value.replace(/\\(.)/g, '$1');
+}
+function scanInlineImages(input, defaults) {
+    const segments = [];
+    const images = [];
+    const raws = [];
+    let last = 0;
+    for (const m of input.matchAll(INLINE_SOURCE_RE)) {
+        const g = m.groups ?? {};
+        // 引号包裹的内容是字面量，不做反转义；裸 token 才可能带 shell 转义。
+        const quoted = g.atDouble ?? g.atSingle ?? g.quotedDouble ?? g.quotedSingle;
+        const bare = g.atBare ?? g.url ?? g.winPath ?? g.uncPath ?? g.posixPath;
+        const raw = quoted ?? bare;
+        if (raw === undefined)
+            continue;
+        const source = quoted !== undefined
+            ? stripWrappingQuotes(quoted.trim())
+            : unescapePathToken(stripWrappingQuotes(bare.trim()));
+        // 认不出是图片源（如 @某个词、.bmp）就当普通文字原样留着，不吞。
+        if (!isSupportedImageSource(source))
+            continue;
+        const start = (m.index ?? 0) + (m[1] ?? '').length;
+        const end = (m.index ?? 0) + m[0].length;
+        segments.push(input.slice(last, start), { image: images.length });
+        raws.push(input.slice(start, end));
+        images.push({
+            source,
+            detail: defaults.detail,
+            maxLongSidePixel: defaults.maxLongSidePixel,
+        });
+        last = end;
+    }
+    segments.push(input.slice(last));
+    return { segments, images, raws };
+}
+/** 把扫描结果拼回文本：被采纳的图占位抹掉，未采纳的原位还原成原始 token。 */
+function renderSegments(scan, kept) {
+    return scan.segments
+        .map((seg) => typeof seg === 'string' ? seg : kept(seg.image) ? '' : (scan.raws[seg.image] ?? ''))
+        .join('');
+}
+function normalizeExtractedText(text) {
+    return text.replace(/[ \t]{2,}/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+}
 export function isSupportedImageSource(source) {
     const clean = stripWrappingQuotes(source.trim());
     if (isHttpUrl(clean)) {
@@ -75,64 +169,52 @@ export function contentToDisplayText(content) {
     return [text, ...badges].filter(Boolean).join('\n');
 }
 export function extractInlineImageInputs(input, defaults = {}) {
-    const images = [];
-    let text = input;
-    const consume = (raw) => {
-        const source = stripWrappingQuotes(raw.trim());
-        if (!source || !isSupportedImageSource(source))
-            return raw;
-        images.push({
-            source,
-            detail: defaults.detail,
-            maxLongSidePixel: defaults.maxLongSidePixel,
-        });
-        return '';
-    };
-    // @"/path with spaces/a.png" / @'path' / @./a.png / @https://x/a.png
-    text = text.replace(/(^|\s)@(?:"([^"]+)"|'([^']+)'|(\S+))/g, (match, prefix, dq, sq, bare) => {
-        const before = prefix ?? '';
-        const source = dq ?? sq ?? bare ?? '';
-        const out = consume(source);
-        return out === '' ? before : match;
-    });
-    // 裸 URL 图片。
-    text = text.replace(new RegExp(String.raw `(^|\s)(https?:\/\/\S+?\.${IMAGE_EXT_PATTERN}(?:[?#]\S*)?)`, 'gi'), (match, prefix, source) => {
-        const out = consume(source);
-        return out === '' ? prefix : match;
-    });
-    // 裸本地图片路径只支持无空格写法；含空格请用 @"/path with spaces/a.png"。
-    text = text.replace(new RegExp(String.raw `(^|\s)((?:\.{1,2}\/|\/|~\/)\S+?\.${IMAGE_EXT_PATTERN})`, 'gi'), (match, prefix, source) => {
-        const out = consume(source);
-        return out === '' ? prefix : match;
-    });
+    const scan = scanInlineImages(input, defaults);
     return {
-        text: text.replace(/[ \t]{2,}/g, ' ').replace(/\n{3,}/g, '\n\n').trim(),
-        images,
+        text: normalizeExtractedText(renderSegments(scan, () => true)),
+        images: scan.images,
     };
 }
 export async function buildUserContent(args) {
     let text = args.text;
-    const images = [...(args.images ?? [])];
-    if (args.parseInlineImages) {
-        const parsed = extractInlineImageInputs(text, {
+    const scan = args.parseInlineImages
+        ? scanInlineImages(args.text, {
             detail: args.detail,
             maxLongSidePixel: args.maxLongSidePixel,
-        });
-        text = parsed.text;
-        images.push(...parsed.images);
+        })
+        : null;
+    // 显式传入的图（`-p --image` / 浏览器实况截图 visionImages）读失败**照旧抛错**：
+    // 调用方明确要求了这张图，静默降级等于假装做了。
+    const explicitParts = [];
+    for (const image of args.images ?? []) {
+        explicitParts.push(await imageToContentPart(image));
     }
-    if (images.length === 0)
-        return text;
-    const parts = [];
-    const finalText = text.trim() || '请分析这张图片。';
-    parts.push({ type: 'text', text: finalText });
-    for (const image of images) {
-        parts.push(await imageToContentPart(image));
+    const inlineParts = [];
+    if (scan) {
+        const resolved = [];
+        for (const image of scan.images) {
+            try {
+                resolved.push(await imageToContentPart(image));
+            }
+            catch (e) {
+                // 行内图片是**我们从文本里猜**出来的：路径不存在 / 过大 / 格式不认时绝不能打死整个回合
+                // （loop.ts 对 buildUserContent 抛错的处理是 yield error + return，整轮当场死）。
+                // 把原始 token 原位还回文本当普通文字，模型照样看得见这个路径、可以自己 Read 或去生成它。
+                resolved.push(null);
+                args.onInlineImageSkipped?.(image.source, e.message);
+            }
+        }
+        text = normalizeExtractedText(renderSegments(scan, (i) => resolved[i] !== null));
+        inlineParts.push(...resolved.filter((p) => p !== null));
     }
-    return parts;
+    const parts = [...explicitParts, ...inlineParts];
+    if (parts.length === 0)
+        return text;
+    return [{ type: 'text', text: text.trim() || '请分析这张图片。' }, ...parts];
 }
 export async function imageToContentPart(input) {
     const url = await imageSourceToUrl(input.source);
+    await removeManagedClipboardTemp(input.source);
     const image_url = {
         url,
         detail: input.detail ?? 'default',

package/src/multimodal.ts

@@ -0,0 +1,349 @@
+/**
+ * ============================================================
+ *  src/multimodal.ts —— OpenAI 兼容多模态输入辅助
+ * ------------------------------------------------------------
+ *  v1 支持图片：本地路径 → data URL，公网 URL → 原样 image_url。
+ *  这里不调用模型，只负责把 TUI / -p / stream-json 的输入规整成
+ *  Chat Completions 的 content blocks。
+ * ============================================================
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getWorkingDir } from './bootstrap/workingDir.js';
+import type {
+  ChatContentPart,
+  ImageDetail,
+  ImageInputSpec,
+  Message,
+} from './types.js';
+import { removeManagedClipboardTemp } from './utils/clipboardImage.js';
+
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+const IMAGE_MIME_BY_EXT: Record<string, string> = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  // Read can attach BMP files directly even though inline drag/drop parsing
+  // intentionally remains limited to formats accepted by most providers.
+  '.bmp': 'image/bmp',
+};
+
+const IMAGE_EXT_PATTERN = String.raw`(?:png|jpe?g|gif|webp)`;
+
+/**
+ * 「路径 token」允许的字符：非空白，或 `\x` 这样的转义对——macOS Terminal / iTerm2
+ * 拖入文件时空格默认转义成 `\ `，不认它就会把 `/Users/me/My\ Pic.png` 切成两半。
+ * 反斜杠**只能**作为转义对的首字符出现（不写成 `(?:\\.|\S)`），这样两个分支互斥、
+ * 不会因重叠产生指数级回溯。
+ */
+const PATH_RUN = String.raw`(?:\\.|[^\s\\])`;
+
+/**
+ * 一次扫描认出所有「行内图片来源」的写法。分支顺序即优先级（同一起点按 alternation 左优先）：
+ *
+ *   ① `@"..."` / `@'...'` / `@bare`  —— 显式语法，用户主动指定
+ *   ② `"..."` / `'...'`              —— 裸引号包裹：Windows Terminal 拖入含空格路径时自带引号
+ *   ③ `https://…` / `file://…`       —— 裸 URL；GNOME Terminal / VTE 拖入给的正是 file:// URI
+ *   ④ `C:\…` / `C:/…` / `\\server\…` —— 裸 Windows 盘符与 UNC：Windows Terminal 拖入形态
+ *   ⑤ `./` `../` `/` `~/` 开头的路径 —— 裸 POSIX 路径（允许 `\ ` 转义空格）
+ *
+ * 为什么这几种写法必须全认：**终端把「拖进窗口的文件」翻译成一次「粘贴文件路径文本」**，
+ * stdin 上没有任何图片字节。所以"支持拖拽"= 认得出各终端各自的路径写法，然后自己去读盘。
+ * 各终端形态不统一（mac 转义空格 / Windows 加引号 / GNOME 给 URI），少认一种就是那个平台不能用。
+ *
+ * 一次拖多张图（空格或换行分隔）不需要额外切分：全局扫描天然逐个命中，
+ * 分隔符会被下一次匹配的 `(^|\s)` 前缀吃掉并原样留在文本里。
+ */
+const INLINE_SOURCE_RE = new RegExp(
+  String.raw`(^|\s)(?:` +
+    [
+      String.raw`@"(?<atDouble>[^"\n]+)"`,
+      String.raw`@'(?<atSingle>[^'\n]+)'`,
+      String.raw`@(?<atBare>${PATH_RUN}+)`,
+      String.raw`"(?<quotedDouble>[^"\n]+\.${IMAGE_EXT_PATTERN})"`,
+      String.raw`'(?<quotedSingle>[^'\n]+\.${IMAGE_EXT_PATTERN})'`,
+      String.raw`(?<url>(?:https?|file):\/\/${PATH_RUN}+?\.${IMAGE_EXT_PATTERN}(?:[?#]\S*)?)`,
+      String.raw`(?<winPath>[A-Za-z]:[\\\/]${PATH_RUN}+?\.${IMAGE_EXT_PATTERN})(?!\w)`,
+      String.raw`(?<uncPath>\\\\${PATH_RUN}+?\.${IMAGE_EXT_PATTERN})(?!\w)`,
+      String.raw`(?<posixPath>(?:\.{1,2}\/|\/|~\/)${PATH_RUN}+?\.${IMAGE_EXT_PATTERN})(?!\w)`,
+    ].join('|') +
+    String.raw`)`,
+  'gi',
+);
+
+/**
+ * 去掉 shell 转义反斜杠（`My\ Pic.png` → `My Pic.png`）。
+ *
+ * ⚠️ 判据只看**字符串长相**、绝不看 `process.platform`：同一个函数在 `-p` / stream-json
+ * 下会在 Linux 宿主上收到 Windows 路径，按平台判会把 `C:\Users\bills` 吃成 `C:Usersbills`。
+ * Windows 盘符 / UNC 开头的串里反斜杠是路径分隔符，原样返回。
+ */
+function unescapePathToken(value: string): string {
+  if (/^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\')) return value;
+  return value.replace(/\\(.)/g, '$1');
+}
+
+/** 文本片段与图片占位交替；`{ image: i }` 指向 InlineScan.images 的下标。 */
+type InlineSegment = string | { image: number };
+
+interface InlineScan {
+  segments: InlineSegment[];
+  images: ImageInputSpec[];
+  /** 与 images 同下标的原始匹配文本。读图失败时用它**原位**还原，不丢用户写的东西。 */
+  raws: string[];
+}
+
+function scanInlineImages(
+  input: string,
+  defaults: { detail?: ImageDetail; maxLongSidePixel?: number },
+): InlineScan {
+  const segments: InlineSegment[] = [];
+  const images: ImageInputSpec[] = [];
+  const raws: string[] = [];
+  let last = 0;
+
+  for (const m of input.matchAll(INLINE_SOURCE_RE)) {
+    const g = m.groups ?? {};
+    // 引号包裹的内容是字面量，不做反转义；裸 token 才可能带 shell 转义。
+    const quoted = g.atDouble ?? g.atSingle ?? g.quotedDouble ?? g.quotedSingle;
+    const bare = g.atBare ?? g.url ?? g.winPath ?? g.uncPath ?? g.posixPath;
+    const raw = quoted ?? bare;
+    if (raw === undefined) continue;
+    const source =
+      quoted !== undefined
+        ? stripWrappingQuotes(quoted.trim())
+        : unescapePathToken(stripWrappingQuotes(bare!.trim()));
+    // 认不出是图片源（如 @某个词、.bmp）就当普通文字原样留着，不吞。
+    if (!isSupportedImageSource(source)) continue;
+
+    const start = (m.index ?? 0) + (m[1] ?? '').length;
+    const end = (m.index ?? 0) + m[0].length;
+    segments.push(input.slice(last, start), { image: images.length });
+    raws.push(input.slice(start, end));
+    images.push({
+      source,
+      detail: defaults.detail,
+      maxLongSidePixel: defaults.maxLongSidePixel,
+    });
+    last = end;
+  }
+
+  segments.push(input.slice(last));
+  return { segments, images, raws };
+}
+
+/** 把扫描结果拼回文本：被采纳的图占位抹掉，未采纳的原位还原成原始 token。 */
+function renderSegments(scan: InlineScan, kept: (index: number) => boolean): string {
+  return scan.segments
+    .map((seg) =>
+      typeof seg === 'string' ? seg : kept(seg.image) ? '' : (scan.raws[seg.image] ?? ''),
+    )
+    .join('');
+}
+
+function normalizeExtractedText(text: string): string {
+  return text.replace(/[ \t]{2,}/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+export function isSupportedImageSource(source: string): boolean {
+  const clean = stripWrappingQuotes(source.trim());
+  if (isHttpUrl(clean)) {
+    try {
+      const u = new URL(clean);
+      return new RegExp(`\\.(${IMAGE_EXT_PATTERN})(?:$|[?#])`, 'i').test(
+        u.pathname,
+      );
+    } catch {
+      return false;
+    }
+  }
+  return Object.hasOwn(IMAGE_MIME_BY_EXT, extname(clean).toLowerCase());
+}
+
+export function normalizeImageDetail(value: string | undefined): ImageDetail {
+  if (value === 'low' || value === 'high' || value === 'default') return value;
+  return 'default';
+}
+
+export function contentToPlainText(content: Message['content']): string {
+  if (typeof content === 'string') return content;
+  if (content === null) return '';
+  return content
+    .map((part) => {
+      if (part.type === 'text') return part.text;
+      if (part.type === 'image_url') return '[图片]';
+      if (part.type === 'video_url') return '[视频]';
+      return '';
+    })
+    .filter(Boolean)
+    .join(' ');
+}
+
+export function contentToDisplayText(content: Message['content']): string {
+  if (typeof content === 'string') return content;
+  if (content === null) return '';
+  const imageCount = content.filter((p) => p.type === 'image_url').length;
+  const videoCount = content.filter((p) => p.type === 'video_url').length;
+  const text = content
+    .filter((p): p is Extract<ChatContentPart, { type: 'text' }> => p.type === 'text')
+    .map((p) => p.text)
+    .join('\n')
+    .trim();
+  const badges = [
+    imageCount > 0 ? `[已附加 ${imageCount} 张图片]` : '',
+    videoCount > 0 ? `[已附加 ${videoCount} 个视频]` : '',
+  ].filter(Boolean);
+  return [text, ...badges].filter(Boolean).join('\n');
+}
+
+export function extractInlineImageInputs(
+  input: string,
+  defaults: { detail?: ImageDetail; maxLongSidePixel?: number } = {},
+): { text: string; images: ImageInputSpec[] } {
+  const scan = scanInlineImages(input, defaults);
+  return {
+    text: normalizeExtractedText(renderSegments(scan, () => true)),
+    images: scan.images,
+  };
+}
+
+export async function buildUserContent(args: {
+  text: string;
+  images?: ImageInputSpec[];
+  parseInlineImages?: boolean;
+  detail?: ImageDetail;
+  maxLongSidePixel?: number;
+  /**
+   * 行内猜出来的图片读取失败时的通知（宿主据此发 warning）。不提供则静默还原成文本——
+   * 但内核调用方（loop.ts）应当提供，让降级可见。
+   */
+  onInlineImageSkipped?: (source: string, reason: string) => void;
+}): Promise<string | ChatContentPart[]> {
+  let text = args.text;
+  const scan = args.parseInlineImages
+    ? scanInlineImages(args.text, {
+        detail: args.detail,
+        maxLongSidePixel: args.maxLongSidePixel,
+      })
+    : null;
+
+  // 显式传入的图（`-p --image` / 浏览器实况截图 visionImages）读失败**照旧抛错**：
+  // 调用方明确要求了这张图，静默降级等于假装做了。
+  const explicitParts: ChatContentPart[] = [];
+  for (const image of args.images ?? []) {
+    explicitParts.push(await imageToContentPart(image));
+  }
+
+  const inlineParts: ChatContentPart[] = [];
+  if (scan) {
+    const resolved: (ChatContentPart | null)[] = [];
+    for (const image of scan.images) {
+      try {
+        resolved.push(await imageToContentPart(image));
+      } catch (e) {
+        // 行内图片是**我们从文本里猜**出来的：路径不存在 / 过大 / 格式不认时绝不能打死整个回合
+        // （loop.ts 对 buildUserContent 抛错的处理是 yield error + return，整轮当场死）。
+        // 把原始 token 原位还回文本当普通文字，模型照样看得见这个路径、可以自己 Read 或去生成它。
+        resolved.push(null);
+        args.onInlineImageSkipped?.(image.source, (e as Error).message);
+      }
+    }
+    text = normalizeExtractedText(renderSegments(scan, (i) => resolved[i] !== null));
+    inlineParts.push(...resolved.filter((p): p is ChatContentPart => p !== null));
+  }
+
+  const parts = [...explicitParts, ...inlineParts];
+  if (parts.length === 0) return text;
+  return [{ type: 'text', text: text.trim() || '请分析这张图片。' }, ...parts];
+}
+
+export async function imageToContentPart(
+  input: ImageInputSpec,
+): Promise<Extract<ChatContentPart, { type: 'image_url' }>> {
+  const url = await imageSourceToUrl(input.source);
+  await removeManagedClipboardTemp(input.source);
+  const image_url: Extract<ChatContentPart, { type: 'image_url' }>['image_url'] = {
+    url,
+    detail: input.detail ?? 'default',
+  };
+  if (typeof input.maxLongSidePixel === 'number' && input.maxLongSidePixel > 0) {
+    image_url.max_long_side_pixel = Math.floor(input.maxLongSidePixel);
+  }
+  return { type: 'image_url', image_url };
+}
+
+/**
+ * 按文件头魔数嗅探图片 MIME（扩展名认不出时的回退）。只认 JPEG/PNG/GIF/WEBP——
+ * 与 IMAGE_MIME_BY_EXT 支持集一致（OpenAI 兼容接口可吃这四类）。非图返回 null。
+ * 动机：下载来的图常带非标准/无扩展名（如爬虫/配图工作流把候选存成 cand_K.img），
+ * 仅按扩展名查会误判「不支持」而拒图——魔数嗅探让任意扩展名的真图都能用。
+ */
+export function sniffImageMime(buf: Buffer): string | null {
+  if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
+    return 'image/png';
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg';
+  if (buf.length >= 4 && buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38)
+    return 'image/gif';
+  if (
+    buf.length >= 12 &&
+    buf.toString('ascii', 0, 4) === 'RIFF' &&
+    buf.toString('ascii', 8, 12) === 'WEBP'
+  )
+    return 'image/webp';
+  return null;
+}
+
+async function imageSourceToUrl(source: string): Promise<string> {
+  const clean = stripWrappingQuotes(source.trim());
+  if (isHttpUrl(clean) || clean.startsWith('data:image/')) return clean;
+
+  const filePath = resolveImagePath(clean);
+  const st = await stat(filePath).catch((e) => {
+    throw new Error(`无法读取图片：${source}（${(e as Error).message}）`);
+  });
+  if (!st.isFile()) throw new Error(`图片路径不是文件：${source}`);
+  if (st.size > MAX_IMAGE_BYTES) {
+    throw new Error(
+      `图片过大：${source} ${(st.size / 1024 / 1024).toFixed(1)}MB，` +
+        `OpenAI 兼容接口单图上限按 10MB 处理。`,
+    );
+  }
+
+  const data = await readFile(filePath);
+  // 先按扩展名查 MIME；认不出（无扩展名 / .img / 扩展名错）再按文件头魔数嗅探，都不认才拒。
+  const mime = IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? sniffImageMime(data);
+  if (!mime) {
+    throw new Error(
+      `不支持的图片格式：${source}。仅支持 JPEG/PNG/GIF/WEBP（按扩展名与文件头都未识别）。`,
+    );
+  }
+  return `data:${mime};base64,${data.toString('base64')}`;
+}
+
+function resolveImagePath(source: string): string {
+  if (source.startsWith('file://')) return fileURLToPath(source);
+  if (source.startsWith('~/')) {
+    return resolve(process.env.HOME ?? '', source.slice(2));
+  }
+  return resolve(getWorkingDir(), source);
+}
+
+function isHttpUrl(source: string): boolean {
+  return /^https?:\/\//i.test(source);
+}
+
+function stripWrappingQuotes(value: string): string {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}

package/src/plugin-sdk.js

@@ -18,7 +18,24 @@
 export { runQuery } from './loop.js';
 export { runAgentTurn } from './session/runAgentTurn.js';
 export { chat } from './llm/client.js';
+export { derivePromptCacheContext, } from './llm/promptCache.js';
 export { ALL_TOOLS, executeTool, getToolByName } from './tools/index.js';
+export { shutdownAllLsp } from './tools/lsp/service.js';
+// --- Computer Use ---
+//
+// 桌面操作的**知识与命令面**住在 `plugins/computer_use/`，可信执行层住在内核
+// （`src/tools/computeruse/`）。这里**只**开放只读诊断门面：
+//
+// ⚠️ 曾经这里导出的是完整的 `computerUseService`，而那个对象的 `request()`
+//    能派发 click / type / file_drop —— 一个「只做诊断与知识管理」的插件不该
+//    拿得到操作鼠标键盘的能力。注释当时宣称「只开放这几件事」，代码没做到。
+//    别再把 service 加回来。
+export { computerUseDiagnostics } from './tools/computeruse/diagnostics.js';
+export { describeCapabilities } from './tools/computeruse/capabilityLabels.js';
+export { readRecentComputerUseAudit } from './cli/computerUse.js';
+export { readComputerUseTelemetryReport } from './tools/computeruse/telemetryLog.js';
+export { matchGuide, describeMatch, loadAllAppManuals, } from './tools/computeruse/vision/appGuide.js';
+export { EMPTY_MANUAL, validateManual, } from './tools/computeruse/manualSchema.js';
 // pre-read 守卫状态登记：tool 步覆盖「声明产物」时用来解除内核「先读后写 / 截断禁写」
 // 守卫（确定性步的 args 写死、模型没机会先 Read）。详见 stepExecutors/tool.ts。
 export { recordRead } from './tools/shared/fileState.js';
@@ -27,7 +44,10 @@ export { dlog } from './utils/debugLog.js';
 // <think> 思维链剥离：内核与 workflow-runner 共享（原住 agentCommon.ts，
 // Agent 子任务工具也需要 → 上移内核，插件经此 re-export）。
 export { stripThinkBlocks } from './utils/stripThink.js';
-export { buildFullSystemPrompt } from './prompts/system.js';
+// buildFullSystemPrompt is retained for compatibility. New long-running hosts should keep
+// buildBaseSystemPrompt stable and pass buildTransientContext separately for each turn.
+export { buildBaseSystemPrompt, buildTransientContext, buildTransientPromptBundle, } from './prompts/system.js';
+export { createAgentRuntimeContext, filterToolsForRuntime, } from './runtime/agentRuntimeContext.js';
 export { getResourceSearchPaths } from './utils/resourcePaths.js';
 // 确定性检查设施：verify 步（shell/file_exists/file_contains/test_count）经此跑校验。
 export { parseCheckString, runVerification } from './infra/verification.js';