cortico-world-forward-reader 0.1.7 → 0.1.11

package/README.md

@@ -2,7 +2,7 @@
 
 给 [Coopanion](https://github.com/Pal-AI-Lab/Coopanion) 的 Coo 一个工具：把 QQ 的「合并转发 / 聊天记录」一层层拆到底。
 
-> **前置：先装「QQ 群聊」插件（qqbot）。** 这个 World 自己不连 QQ，也不存 QQ 的连接信息——它借 QQ 群聊插件配好的那套东西干活：
+> **前置：先装「QQ群聊插件」。** 这个 World 自己不连 QQ，也不存 QQ 的连接信息——它借 QQ群聊插件配好的那套东西干活：
 > SnowLuma 的 OneBot HTTP 接口用来取消息，插件里配的视觉端点用来识图。
 > 没装那个插件，这里两个工具都只会回「连不上」。
 
@@ -28,17 +28,27 @@ Coopanion 自带的消息展开只摊开一层，转发里套着的转发看不
 
 ## 前置
 
-- 装了 **QQ 群聊插件（qqbot）**：SnowLuma 连接、OneBot 地址、视觉端点都在它那儿配。
+- 装了 **QQ群聊插件（qqbot）**：SnowLuma 连接、OneBot 地址、视觉端点都在它那儿配。
 - 装了 **SnowLuma**（OneBot v11 实现），HTTP 接口开着，默认 `127.0.0.1:3000`。
 - OneBot 配置文件里有 `accessToken`。默认读 `D:/snowluma/config/onebot_<QQ号>.json`，也可以在配置页手填路径或直接填地址和 token。
 
-## 识图（可选，默认关）
+## 图片（默认当附件交出去）
 
-拆到图片时，可以让视觉端点在图后面补一句「这张图是什么」。
+拆到图片时，图会被下载下来、作为**附件**跟回执一起交给模型。
 
-- 端点默认**跟着 QQ 群聊插件走**：先在 QQ 群聊插件里把视觉端点、模型、key 配好，这里就自动认得到，不用再填一遍。
-- 那边没配、或者想单独用别的模型，才在下面的「视觉端点 / 模型 / 密钥」里填。
-- 一张图一次调用，会花钱，所以默认关；工具调用时也可以当场传 `captions: true`。
+- 能看图的模型（主模型支持图片）就直接看到图，不用多花一次调用。
+- 看不见图的模型只会收到一行文字说明（谁、什么时候、链接），不会因为带图出错。
+- 一次最多贴 `attachMax` 张（默认 6），单张超过 `attachMaxMb`（默认 8 MB）就跳过，正文里仍然有链接。
+- 不想贴附件，把「把图片当附件一起交出去」关掉，就退回只给链接。
+
+## 识图（只在要文字描述时才跑）
+
+附件之外还想要一句**文字描述**时，在调用时传 `captions: true`——**没有开关会自动识图**，因为图已经当附件交给模型了，再识一遍是白花钱。
+
+- 端点默认**跟着 QQ群聊插件走**：那边配好了视觉端点、模型、key，这里就自动认得到，不用再填一遍。
+- 配置页里**没有**端点/模型/密钥这几格；那边没配，识图就只会写一句「没找到视觉端点」。
+- 它只对**看不见图的模型**有用（纯文字模型只会读到一行「谁、什么时候、一张图、链接」），能看图的模型用不上。
+- 一张图一次调用，会花钱，所以不传就不跑。
 - 识图失败不会弄坏整份拆解，只会在那张图后面写一句失败原因。
 
 
@@ -50,6 +60,8 @@ Coopanion 自带的消息展开只摊开一层，转发里套着的转发看不
 - 嵌套层数上限（默认 8）
 - 回执字数上限（默认 12000）
 - 请求超时（默认 15000 ms）
+- 把图片当附件一起交出去（默认开）、一次最多处理几张（默认 6，附件和识图共用）、单张上限 MB（默认 8）
+- 识图：每句描述字数（不传 `captions: true` 就不会跑；端点自动跟着 QQ群聊插件走，不单独配）
 
 ## 限制
 

package/describe.json

@@ -5,7 +5,7 @@
       "tags": [
         "read"
       ],
-      "description": "拆开 QQ 的「合并转发 / 聊天记录」卡片，包括转发里套着的转发。\n什么时候用：收到 `qq.forward` 事件、或者 QQ 消息里写着「[合并转发]」但只摊开了一层、里面还有「又一层」时；想看清某段聊天记录到底是谁说了什么，也用它。\n怎么给编号：QQ 消息事件行首的 `#编号`（如 `#265277450`）就是 message_id，原样填进 ref；带不带 `#`、前后有空格都不要紧。编号可能是负数（如 `#-1175570559`），负号是编号的一部分，要一起填，别去掉。\n它只读，只走本机的 SnowLuma OneBot HTTP 接口（默认 127.0.0.1:3000，由 QQ 群聊插件配好），不发消息、不改任何东西；接口没开或 token 不对会直接说清楚哪一步不对。输出过长会截断。\n图片：默认只给链接；传 `captions: true` 会顺便把图交给视觉端点，在结尾单列一节说每张图是什么（一张图一次调用，按需开）。",
+      "description": "拆开 QQ 的「合并转发 / 聊天记录」卡片，包括转发里套着的转发。\n什么时候用：收到 `qq.forward` 事件、或者 QQ 消息里写着「[合并转发]」但只摊开了一层、里面还有「又一层」时；想看清某段聊天记录到底是谁说了什么，也用它。\n怎么给编号：QQ 消息事件行首的 `#编号`（如 `#265277450`）就是 message_id，原样填进 ref；带不带 `#`、前后有空格都不要紧。编号可能是负数（如 `#-1175570559`），负号是编号的一部分，要一起填，别去掉。\n它只读，只走本机的 SnowLuma OneBot HTTP 接口（默认 127.0.0.1:3000，由 QQ群聊插件配好），不发消息、不改任何东西；接口没开或 token 不对会直接说清楚哪一步不对。输出过长会截断。\n图片：默认把图下载成附件，跟回执一起交给你——能看图的模型直接就看得到；看不见图的模型只会收到一行文字说明，不会出错。不会自动识图；还想要一句「这张图是什么」的文字描述，再传 `captions: true`（会花钱）。",
       "parameters": {
         "type": "object",
         "properties": {
@@ -27,7 +27,7 @@
           },
           "captions": {
             "type": "boolean",
-            "description": "顺便给图片配描述（默认按配置，通常关）。一张图一次视觉调用，会花一点钱；图多的时候只识前几张。"
+            "description": "要一句「这张图是什么」的文字描述才传 true——不传就不识图，一次视觉调用一张图，会花钱。"
           }
         },
         "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-forward-reader",
-  "version": "0.1.7",
+  "version": "0.1.11",
   "description": "转发拆解 World：把 QQ 的「合并转发」一层层拆到底，嵌套在里面的转发也展开，输出带缩进的人话。只读，不发消息。",
   "type": "module",
   "main": "./src/index.js",
@@ -41,11 +41,11 @@
     "locales": {
       "zh": {
         "displayName": "转发拆解",
-        "description": "【需要先装 QQ 群聊插件】把 QQ 的「合并转发」一层层拆到底——嵌套在里面的转发也会展开，按人、按时间列成带缩进的文字。只读：借 QQ 群聊插件（qqbot）配好的本机 SnowLuma OneBot HTTP 接口取消息，不发消息、不改任何东西。识图也借那边的视觉端点，用之前先在 QQ 群聊插件里配好端点/模型/key。"
+        "description": "【需要先装 QQ群聊插件】把 QQ 的「合并转发」一层层拆到底——嵌套在里面的转发也会展开，按人、按时间列成带缩进的文字。只读：借 QQ群聊插件（qqbot）配好的本机 SnowLuma OneBot HTTP 接口取消息，不发消息、不改任何东西。拆到的图片默认作为附件一起交给模型（能看图就直接看到，看不见图只会读到一行文字说明）。"
       },
       "en": {
         "displayName": "Forward Reader",
-        "description": "Requires the QQ chat (qqbot) plugin. Expands QQ merged-forward messages recursively, including forwards nested inside forwards, into an indented transcript. Read-only: it reuses the SnowLuma OneBot HTTP API that plugin already set up, and never sends or changes anything. Image captions reuse that plugin's vision endpoint too — configure it there first."
+        "description": "Requires the QQ chat (qqbot) plugin. Expands QQ merged-forward messages recursively, including forwards nested inside forwards, into an indented transcript. Read-only: it reuses the SnowLuma OneBot HTTP API that plugin already set up, and never sends or changes anything. Images are attached to the tool result by default, so a model that accepts images sees them; others just get a one-line text note."
       }
     },
     "describe": "describe.json",

package/src/config.js

@@ -18,22 +18,26 @@ export const DEFAULTS = {
   /** 单次请求超时（毫秒）。 */
   timeoutMs: 15000,
 
-  // ── 识图（可选，默认关）────────────────────────────────────────────
-  /** 拆到图片时，顺便让视觉端点说一句图里是什么。一百张图就一百次调用，默认关。 */
-  caption: false,
-  /** 一次拆解最多识几张图，多出来的只留链接。 */
-  captionMax: 6,
-  /** 每句描述最多多少字。 */
-  captionChars: 60,
+  // ── 图片附件（默认开）─────────────────────────────────────────────
+  /**
+   * 拆到的图片下载下来，作为附件跟回执一起交给模型。
+   * 能看图的模型直接看到；看不见的模型只会收到 fallbackText，不会出错。
+   */
+  attachImages: true,
+  /** 一次最多贴几张附件，多出来的只在正文留链接；识图也用这一个上限。 */
+  attachMax: 6,
+  /** 单张图最大多少 MB，超了就不贴（正文里还有链接）。 */
+  attachMaxMb: 8,
+
+  // ── 识图（只在工具调用时明确要求才跑）─────────────────────────────────
   /**
-   * 想复用别的配置文件里的视觉端点时才填；留空＝自己去本机 Coopanion 的配置里找。
-   * 一般不用碰：这台机器上已经配好的视觉端点会被自动认出来。
+   * 不设开关：图默认当附件交给模型，再自动识一遍是白花钱。
+   * 只有 qq_forward_read 传了 captions: true 才会调视觉端点。
    */
-  visionConfig: '',
-  /** 下面三项留空就沿用找到的那份配置；填了就以这里为准。 */
-  visionEndpoint: '',
-  visionModel: '',
-  visionKey: '',
+  /** 每句描述最多多少字。 */
+  captionChars: 60,
+  // 视觉端点不在这配：自己去本机 Coopanion 的配置里找（一般就是 QQ群聊插件那份），
+  // 配置页里一个格子都不露——留空格子只会让人以为非得填。
 };
 
 export const CONFIG_GROUP = {
@@ -43,13 +47,14 @@ export const CONFIG_GROUP = {
     type: 'object',
     title: '转发拆解',
     description:
-      '【前置：先装 QQ 群聊插件】把 QQ 的「合并转发」一层层拆到底：借那个插件配好的 SnowLuma OneBot HTTP 接口递归调 get_forward_msg，' +
-      '嵌套在里面的转发也会展开；识图也借它的视觉端点（识图前先在 QQ 群聊插件里配好端点/模型/key）。只读，不发消息、不改 QQ 配置。',
+      '把 QQ 的「合并转发」一层层拆到底，嵌套在里面的转发也展开，按人、按时间列成带缩进的文字。' +
+      '前置：先装 QQ群聊插件（本 World 借它的 OneBot 接口取消息，自己不连 QQ）。' +
+      '拆到的图片默认作为附件交给模型，看不见图的模型只会读到一行文字说明。只读，不发消息、不改 QQ 配置。',
     properties: {
       'worlds.forward-reader.snowlumaConfig': {
         type: 'string',
         title: 'SnowLuma 配置路径',
-        description: 'OneBot 配置文件（含 accessToken）。默认 D:/snowluma/config/onebot_2565315695.json。',
+        description: 'OneBot 配置文件，里面存着 accessToken；换了 QQ 号才需要改。',
         'x-hot': true,
       },
       'worlds.forward-reader.baseUrl': {
@@ -88,22 +93,28 @@ export const CONFIG_GROUP = {
         maximum: 120000,
         'x-hot': true,
       },
-      'worlds.forward-reader.caption': {
+      'worlds.forward-reader.attachImages': {
         type: 'boolean',
-        title: '拆到图片时顺手识图',
+        title: '把图片当附件一起交出去',
         description:
-          '打开后，拆解里出现的图片会被下载、交给视觉端点，在图后补一句「这张图是什么」。' +
-          '一张图一次调用，会花一点钱，默认关；工具调用时也可以单独指定。',
+          '拆到的图片下载下来当附件交给模型：能看图就直接看到，看不见图只会读到一行文字说明。关掉就只留链接。',
         'x-hot': true,
       },
-      'worlds.forward-reader.captionMax': {
+      'worlds.forward-reader.attachMax': {
         type: 'integer',
-        title: '一次最多识几张图',
-        description: '默认 6；多出来的图只留链接，不送去识图。',
+        title: '一次最多处理几张图',
+        description: '默认 6：附件和识图共用这一个上限，多出来的只在正文里留链接。',
         minimum: 0,
         maximum: 30,
         'x-hot': true,
       },
+      'worlds.forward-reader.attachMaxMb': {
+        type: 'integer',
+        title: '单张图大小上限(MB)',
+        description: '超过这个大小的图不贴，只在正文里留链接。默认 8。',
+        minimum: 1,
+        maximum: 32,
+      },
       'worlds.forward-reader.captionChars': {
         type: 'integer',
         title: '每句描述字数',
@@ -111,29 +122,6 @@ export const CONFIG_GROUP = {
         minimum: 20,
         maximum: 200,
       },
-      'worlds.forward-reader.visionConfig': {
-        type: 'string',
-        title: '视觉端点配置路径（一般不用填）',
-        description:
-          '留空就行：留空时会自己在本机 Coopanion 的配置里找已经配好的视觉端点。' +
-          '只有想改用另一份配置文件时才填它的路径。',
-      },
-      'worlds.forward-reader.visionEndpoint': {
-        type: 'string',
-        title: '视觉端点（可选）',
-        description:
-          '留空就行：会用 QQ 群聊插件里配好的视觉端点（那边没配的话，在这里填端点/模型/key）。',
-      },
-      'worlds.forward-reader.visionModel': {
-        type: 'string',
-        title: '视觉模型（可选）',
-        description: '留空就跟端点自动找到的那份配置走。',
-      },
-      'worlds.forward-reader.visionKey': {
-        type: 'string',
-        title: '视觉端点密钥（可选）',
-        description: '留空就用找到的那份配置里的密钥；别把 key 写进仓库。',
-      },
     },
   },
 };

package/src/index.js

@@ -36,6 +36,33 @@ function pad(depth) {
   return '  '.repeat(depth);
 }
 
+const EXT_BY_MIME = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/bmp': 'bmp',
+  'image/avif': 'avif',
+};
+
+const MIME_BY_EXT = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+  avif: 'image/avif',
+};
+
+/** 优先信 Content-Type，其次看链接后缀；都不是图就当 jpeg 试。 */
+function mimeOf(contentType, url) {
+  const ct = String(contentType || '').split(';')[0].trim().toLowerCase();
+  if (/^image\//.test(ct)) return ct;
+  const ext = (String(url || '').split('?')[0].match(/\.([a-z0-9]+)$/i) || [])[1];
+  return MIME_BY_EXT[String(ext || '').toLowerCase()] || 'image/jpeg';
+}
+
 function senderName(sender) {
   if (!sender) return '?';
   return sender.card || sender.nickname || (sender.user_id ? String(sender.user_id) : '?');
@@ -166,7 +193,8 @@ export class ForwardReaderWorld {
     const whole = foldMessage(segments, { links: true });
     const who = senderName(data?.sender);
     const when = clockOf(data?.time);
-    const wantCaption = Boolean(args.captions ?? cfg.caption);
+    // 识图只在调用时明确要求才跑：图已经当附件交给模型了，再自动识一遍是白花钱。
+    const wantCaption = args.captions === true;
 
     if (!whole.nested.length) {
       // 不是合并转发：直接把这条消息本身给人看。
@@ -176,7 +204,7 @@ export class ForwardReaderWorld {
       out.push('');
       out.push('这条不是合并转发卡片，所以没有可拆的层。');
       if (wantCaption) await this.addCaptions(out, whole.images.map((i) => ({ ...i, who, when })));
-      return cap(out.join('\n'), limit);
+      return this.finish(out, limit, whole.images.map((i) => ({ ...i, who, when })));
     }
 
     out.push(`# 转发拆解 · 消息 ${rawRef}${who !== '?' ? ` · ${who}` : ''}${when ? ` · ${when}` : ''}`);
@@ -195,18 +223,66 @@ export class ForwardReaderWorld {
     if (wantCaption) await this.addCaptions(out, state.images);
 
     out.unshift(`共 ${state.levels} 层 / ${state.items} 条${state.truncated ? '（已达条数上限，后面没再往下翻）' : ''}`);
-    return cap(out.join('\n'), limit);
+    return this.finish(out, limit, state.images);
+  }
+
+  /**
+   * 收尾：正文截断，再把图片当附件一起交出去。
+   * 能看图的模型直接看到图；看不见的模型只收到 fallbackText，不会报错。
+   */
+  async finish(out, limit, images) {
+    const blobs = await this.collectBlobs(images || []);
+    if (blobs.length) {
+      out.push('');
+      out.push(
+        `—— 有 ${blobs.length} 张图片已经作为附件一起给你了（看不见图的话，正文里的链接还在；想让它转述一句就传 captions: true）——`
+      );
+    }
+    const text = cap(out.join('\n'), limit);
+    return blobs.length ? { text, blobs } : text;
+  }
+
+  /** 把图片下载成附件；太大、下载失败、不是图的，直接跳过（正文里本来就有链接）。 */
+  async collectBlobs(images) {
+    if (!this.cfg.attachImages) return [];
+    const max = clampInt(this.cfg.attachMax, 6, 0, 30);
+    if (max <= 0) return [];
+    const maxBytes = clampInt(this.cfg.attachMaxMb, 8, 1, 32) * 1024 * 1024;
+    const timeoutMs = clampInt(this.cfg.timeoutMs, 15000, 1000, 120000);
+    const picked = images.filter((i) => i && i.url).slice(0, max);
+    const blobs = [];
+    for (let i = 0; i < picked.length; i += 1) {
+      const img = picked[i];
+      try {
+        const res = await fetch(img.url, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok) continue;
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        if (!bytes.length || bytes.length > maxBytes) continue;
+        const mime = mimeOf(res.headers.get('content-type'), img.url);
+        if (!/^image\//.test(mime)) continue;
+        const tag = `${img.who && img.who !== '?' ? img.who + ' ' : ''}${img.when || ''}`.trim();
+        blobs.push({
+          bytes,
+          mime,
+          name: `forward-${i + 1}.${EXT_BY_MIME[mime] || 'png'}`,
+          fallbackText: `${tag ? '[' + tag + '] ' : ''}图片 ${i + 1}：${img.url}`,
+        });
+      } catch {
+        // 拿不到就当没有这张：不炸整份拆解。
+      }
+    }
+    return blobs;
   }
 
   /** 把拆出来的图片送去识图，在结尾单列一节。失败也是一句话，不炸整份拆解。 */
   async addCaptions(out, images) {
     const list = (images || []).filter((i) => i && i.url);
     if (!list.length) return;
-    const max = clampInt(this.cfg.captionMax, 6, 0, 30);
+    const max = clampInt(this.cfg.attachMax, 6, 0, 30);
     const chars = clampInt(this.cfg.captionChars, 60, 20, 200);
     const picked = max > 0 ? list.slice(0, max) : [];
     if (!picked.length) return;
-    const vision = await resolveVision(this.cfg);
+    const vision = await resolveVision();
     out.push('');
     out.push(`—— 图片 ${list.length} 张${list.length > picked.length ? `（只识前 ${picked.length} 张）` : ''} ——`);
     for (const img of picked) {

package/src/tools.js

@@ -17,9 +17,10 @@ export const TOOL_DECLS = [
       '想看清某段聊天记录到底是谁说了什么，也用它。\n' +
       '怎么给编号：QQ 消息事件行首的 `#编号`（如 `#265277450`）就是 message_id，原样填进 ref；带不带 `#`、前后有空格都不要紧。' +
       '编号可能是负数（如 `#-1175570559`），负号是编号的一部分，要一起填，别去掉。\n' +
-      '它只读，只走本机的 SnowLuma OneBot HTTP 接口（默认 127.0.0.1:3000，由 QQ 群聊插件配好），不发消息、不改任何东西；' +
+      '它只读，只走本机的 SnowLuma OneBot HTTP 接口（默认 127.0.0.1:3000，由 QQ群聊插件配好），不发消息、不改任何东西；' +
       '接口没开或 token 不对会直接说清楚哪一步不对。输出过长会截断。\n' +
-      '图片：默认只给链接；传 `captions: true` 会顺便把图交给视觉端点，在结尾单列一节说每张图是什么（一张图一次调用，按需开）。',
+      '图片：默认把图下载成附件，跟回执一起交给你——能看图的模型直接就看得到；看不见图的模型只会收到一行文字说明，不会出错。' +
+      '不会自动识图；还想要一句「这张图是什么」的文字描述，再传 `captions: true`（会花钱）。',
     parameters: {
       type: 'object',
       properties: {
@@ -41,7 +42,7 @@ export const TOOL_DECLS = [
         },
         captions: {
           type: 'boolean',
-          description: '顺便给图片配描述（默认按配置，通常关）。一张图一次视觉调用，会花一点钱；图多的时候只识前几张。',
+          description: '要一句「这张图是什么」的文字描述才传 true——不传就不识图，一次视觉调用一张图，会花钱。',
         },
       },
       required: ['ref'],

package/src/vision.js

@@ -1,9 +1,9 @@
 /**
  * 识图：借本机已经配好的视觉端点，给一张图配一句描述。
  *
- * 端点从哪来：优先用这个 World 自己的 visionEndpoint / visionModel / visionKey；
- * 没填就自动去本机 Coopanion 的配置里找（一般是 QQ 那份 qqbot.vision），找到就用，
- * 找不到就老实说没找到。写死不合适的盘符和模型名没有意义——换台机器就跑不通。
+ * 端点从哪来：本机 Coopanion 的配置里找（一般是 QQ 那份 qqbot.vision），找到就用，
+ * 找不到就老实说没找到。配置页里不给格子填——留空的格子只会让人以为非得填。
+ * 写死不合适的盘符和模型名没有意义——换台机器就跑不通。
  * 端点按 OpenAI 兼容格式 POST /chat/completions，content 里混 text + image_url（data URL 也行）。
  *
  * 踩过的坑：
@@ -58,21 +58,9 @@ async function readHostVision(configPath) {
   return null;
 }
 
-/** 配置里的显式值优先，其次读宿主配置。 */
-export async function resolveVision(cfg) {
-  const own = {
-    endpoint: String(cfg.visionEndpoint || '').trim(),
-    model: String(cfg.visionModel || '').trim(),
-    key: String(cfg.visionKey || '').trim(),
-  };
-  if (own.endpoint && own.model) return own;
-  const host = await readHostVision(cfg.visionConfig);
-  if (!host) return null;
-  return {
-    endpoint: own.endpoint || host.endpoint,
-    model: own.model || host.model,
-    key: own.key || host.key,
-  };
+/** 只认本机 Coopanion 配置里已经配好的视觉端点；找不到就返回 null。 */
+export async function resolveVision() {
+  return readHostVision(process.env.COOPANION_CONFIG || '');
 }
 
 function guessMime(buf) {
@@ -104,7 +92,7 @@ async function fetchImage(url, timeoutMs) {
 export async function captionImage(vision, url, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 30000;
   const chars = opts.chars ?? 60;
-  if (!vision) return '（没找到视觉端点：先在 QQ 群聊插件里配好，或在这里填端点/模型/key）';
+  if (!vision) return '（没找到视觉端点：需要先在 QQ群聊插件里把视觉端点配好）';
   let buf;
   try {
     buf = await fetchImage(url, timeoutMs);