cortico-world-forward-reader 0.1.2 → 0.1.4

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-forward-reader",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "转发拆解 World：把 QQ 的「合并转发」一层层拆到底，嵌套在里面的转发也展开，输出带缩进的人话。只读，不发消息。",
   "type": "module",
   "main": "./src/index.js",

package/src/config.js

@@ -17,6 +17,20 @@ export const DEFAULTS = {
   maxChars: 12000,
   /** 单次请求超时（毫秒）。 */
   timeoutMs: 15000,
+
+  // ── 识图（可选，默认关）────────────────────────────────────────────
+  /** 拆到图片时，顺便让视觉端点说一句图里是什么。一百张图就一百次调用，默认关。 */
+  caption: false,
+  /** 一次拆解最多识几张图，多出来的只留链接。 */
+  captionMax: 6,
+  /** 每句描述最多多少字。 */
+  captionChars: 60,
+  /** 从哪儿读视觉端点（Coopanion 主配置里的 qqbot.vision）。 */
+  visionConfig: 'D:/Coopanion/data/home/companion/config.json',
+  /** 下面三项一般留空：留空就用 visionConfig 里配的值。 */
+  visionEndpoint: '',
+  visionModel: '',
+  visionKey: '',
 };
 
 export const CONFIG_GROUP = {
@@ -71,6 +85,50 @@ export const CONFIG_GROUP = {
         maximum: 120000,
         'x-hot': true,
       },
+      'worlds.forward-reader.caption': {
+        type: 'boolean',
+        title: '拆到图片时顺手识图',
+        description:
+          '打开后，拆解里出现的图片会被下载、交给视觉端点，在图后补一句「这张图是什么」。' +
+          '一张图一次调用，会花一点钱，默认关；工具调用时也可以单独指定。',
+        'x-hot': true,
+      },
+      'worlds.forward-reader.captionMax': {
+        type: 'integer',
+        title: '一次最多识几张图',
+        description: '默认 6；多出来的图只留链接，不送去识图。',
+        minimum: 0,
+        maximum: 30,
+        'x-hot': true,
+      },
+      'worlds.forward-reader.captionChars': {
+        type: 'integer',
+        title: '每句描述字数',
+        description: '每张图的描述最多多少字，默认 60。',
+        minimum: 20,
+        maximum: 200,
+      },
+      'worlds.forward-reader.visionConfig': {
+        type: 'string',
+        title: '视觉端点配置路径',
+        description:
+          '从哪个配置文件读视觉端点（默认读 Coopanion 主配置里的 qqbot.vision：endpoint / model / apiKeySecret）。',
+      },
+      'worlds.forward-reader.visionEndpoint': {
+        type: 'string',
+        title: '视觉端点（可选）',
+        description: '留空就用上面配置文件里的值；填了就盖过它。',
+      },
+      'worlds.forward-reader.visionModel': {
+        type: 'string',
+        title: '视觉模型（可选）',
+        description: '留空就用配置文件里的值。',
+      },
+      'worlds.forward-reader.visionKey': {
+        type: 'string',
+        title: '视觉端点密钥（可选）',
+        description: '留空就用配置文件里的值；别把 key 写进仓库。',
+      },
     },
   },
 };

package/src/index.js

@@ -10,6 +10,7 @@
 import { CONFIG_GROUP, DEFAULTS, WORLD_ID } from './config.js';
 import { TOOL_DECLS } from './tools.js';
 import { callOneBot, describeSource, resolveEndpoint, resolveToken, segmentText } from './onebot.js';
+import { resolveVision, captionImage } from './vision.js';
 
 const LABEL = '转发拆解';
 const MAX_OUTPUT_CHARS = 12000;
@@ -57,20 +58,25 @@ function clockOf(time) {
   return `${year}${mo}-${dd} ${hh}:${mm}`;
 }
 
-/** 把一条消息的段合成一行，并挑出里面嵌套的转发段。 */
-function foldMessage(segments) {
+/** 把一条消息的段合成一行，并挑出里面嵌套的转发段（和图片，识图时要用）。 */
+function foldMessage(segments, opts = {}) {
   const parts = [];
   const nested = [];
+  const images = [];
   for (const seg of segments || []) {
     if (!seg) continue;
     if (seg.type === 'forward') {
       nested.push(seg);
       continue;
     }
-    const piece = segmentText(seg);
+    if (seg.type === 'image' && seg.data) {
+      const url = seg.data.url || seg.data.path || '';
+      if (url) images.push({ url, summary: seg.data.summary || '' });
+    }
+    const piece = segmentText(seg, opts);
     if (piece) parts.push(piece);
   }
-  return { text: parts.join('').trim(), nested };
+  return { text: parts.join('').trim(), nested, images };
 }
 
 export class ForwardReaderWorld {
@@ -155,11 +161,12 @@ export class ForwardReaderWorld {
     }
 
     const out = [];
-    const state = { items: 0, levels: 0, truncated: false };
+    const state = { items: 0, levels: 0, truncated: false, images: [] };
     const segments = data?.message || [];
-    const whole = foldMessage(segments);
+    const whole = foldMessage(segments, { links: true });
     const who = senderName(data?.sender);
     const when = clockOf(data?.time);
+    const wantCaption = Boolean(args.captions ?? cfg.caption);
 
     if (!whole.nested.length) {
       // 不是合并转发：直接把这条消息本身给人看。
@@ -168,6 +175,7 @@ export class ForwardReaderWorld {
       out.push(whole.text || '（没有文字内容）');
       out.push('');
       out.push('这条不是合并转发卡片，所以没有可拆的层。');
+      if (wantCaption) await this.addCaptions(out, whole.images.map((i) => ({ ...i, who, when })));
       return cap(out.join('\n'), limit);
     }
 
@@ -184,10 +192,30 @@ export class ForwardReaderWorld {
       await this.walk(seg.data?.id, 0, out, state, maxDepth);
     }
 
+    if (wantCaption) await this.addCaptions(out, state.images);
+
     out.unshift(`共 ${state.levels} 层 / ${state.items} 条${state.truncated ? '（已达条数上限，后面没再往下翻）' : ''}`);
     return cap(out.join('\n'), limit);
   }
 
+  /** 把拆出来的图片送去识图，在结尾单列一节。失败也是一句话，不炸整份拆解。 */
+  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 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);
+    out.push('');
+    out.push(`—— 图片 ${list.length} 张${list.length > picked.length ? `（只识前 ${picked.length} 张）` : ''} ——`);
+    for (const img of picked) {
+      const tag = `${img.who && img.who !== '?' ? img.who + ' ' : ''}${img.when || ''}`.trim();
+      const text = await captionImage(vision, img.url, { chars, timeoutMs: this.cfg.timeoutMs ?? 15000 });
+      out.push(`${tag ? '[' + tag + '] ' : ''}${text}`);
+    }
+  }
+
   async walk(forwardId, depth, out, state, maxDepth) {
     if (!forwardId || state.truncated) return;
     if (depth >= maxDepth) {
@@ -212,7 +240,8 @@ export class ForwardReaderWorld {
       }
       const who = senderName(item?.sender);
       const when = clockOf(item?.time);
-      const folded = foldMessage(item?.message);
+      const folded = foldMessage(item?.message, { links: true });
+      for (const img of folded.images) state.images.push({ ...img, who, when });
       const head = `${pad(depth)}[${who}${when ? ' ' + when : ''}]`;
       state.items += 1;
       out.push(`${head} ${folded.text || '（空）'}`);

package/src/onebot.js

@@ -97,15 +97,23 @@ export async function callOneBot(cfg, action, params = {}) {
   return json.data ?? json;
 }
 
-/** 一条消息里的某个段 → 一行给人看的小字。 */
-export function segmentText(seg) {
+/**
+ * 一条消息里的某个段 → 一行给人看的小字。
+ * opts.links 为真时，图片后面补上地址（SnowLuma 一般给 url，取不到就退回 file），
+ * 这样带图的那条记录也能拿链接去看图，而不是只剩一个「[图片]」。
+ */
+export function segmentText(seg, opts = {}) {
   if (!seg || typeof seg !== 'object') return '';
   const d = seg.data || {};
   switch (seg.type) {
     case 'text':
       return d.text || '';
-    case 'image':
-      return `[图片${d.summary ? '：' + d.summary : ''}]`;
+    case 'image': {
+      const base = `[图片${d.summary ? '：' + d.summary : ''}]`;
+      if (!opts.links) return base;
+      const where = d.url || d.path || d.file || '';
+      return where ? `${base} ${where}` : base;
+    }
     case 'face':
       return `[表情${d.id ? ':' + d.id : ''}]`;
     case 'mface':

package/src/tools.js

@@ -18,7 +18,8 @@ export const TOOL_DECLS = [
       '怎么给编号：QQ 消息事件行首的 `#编号`（如 `#265277450`）就是 message_id，原样填进 ref；带不带 `#`、前后有空格都不要紧。' +
       '编号可能是负数（如 `#-1175570559`），负号是编号的一部分，要一起填，别去掉。\n' +
       '它只读，只走本机的 SnowLuma OneBot HTTP 接口（默认 127.0.0.1:3000），不发消息、不改任何东西；' +
-      '接口没开或 token 不对会直接说清楚哪一步不对。输出过长会截断。',
+      '接口没开或 token 不对会直接说清楚哪一步不对。输出过长会截断。\n' +
+      '图片：默认只给链接；传 `captions: true` 会顺便把图交给视觉端点，在结尾单列一节说每张图是什么（一张图一次调用，按需开）。',
     parameters: {
       type: 'object',
       properties: {
@@ -38,6 +39,10 @@ export const TOOL_DECLS = [
           maximum: 60000,
           description: '这次回执最多多少字，不填用配置里的默认值（默认 12000）。',
         },
+        captions: {
+          type: 'boolean',
+          description: '顺便给图片配描述（默认按配置，通常关）。一张图一次视觉调用，会花一点钱；图多的时候只识前几张。',
+        },
       },
       required: ['ref'],
     },

package/src/vision.js

@@ -0,0 +1,123 @@
+/**
+ * 识图：拿 Coopanion 里已经配好的视觉端点（qqbot.vision）给一张图配一句描述。
+ *
+ * 为什么不直接抄一个模型名和 key：主人在设置里换端点/换模型时，这里跟着变，不用改代码。
+ * 端点按 OpenAI 兼容格式 POST /chat/completions，content 里混 text + image_url（data URL 也行）。
+ *
+ * 踩过的坑：
+ *  1. max_tokens 给小了（比如 8）会被 reasoning_tokens 吃光，message.content 是空串——至少给 200。
+ *  2. 图片要先下载成 buffer 再转 base64，直接把外链丢过去有的端点拉不到（QQ 的图还带 rkey）。
+ */
+import { readFile } from 'node:fs/promises';
+
+const MAX_BYTES = 6 * 1024 * 1024;
+
+/** 从 Coopanion 的配置文件里读 qqbot.vision；读不到就返回 null。 */
+async function readHostVision(configPath) {
+  if (!configPath) return null;
+  try {
+    const raw = await readFile(configPath, 'utf8');
+    const json = JSON.parse(raw);
+    const v = json?.worlds?.qqbot?.vision ?? json?.qqbot?.vision;
+    if (!v || !v.endpoint || !v.model) return null;
+    return {
+      endpoint: String(v.endpoint),
+      model: String(v.model),
+      key: String(v.apiKeySecret || v.apiKey || ''),
+    };
+  } catch {
+    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,
+  };
+}
+
+function guessMime(buf) {
+  if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50) return 'image/png';
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8) return 'image/jpeg';
+  if (buf.length >= 6 && buf[0] === 0x47 && buf[1] === 0x49) return 'image/gif';
+  if (buf.length >= 12 && buf[0] === 0x52 && buf[1] === 0x49 && buf[8] === 0x57) return 'image/webp';
+  return 'image/jpeg';
+}
+
+async function fetchImage(url, timeoutMs) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctl.signal });
+    if (!res.ok) throw new Error(`下载图片失败：HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (!buf.length) throw new Error('下载图片失败：拿到空文件');
+    if (buf.length > MAX_BYTES) throw new Error(`图片太大（${Math.round(buf.length / 1024)} KB）`);
+    return buf;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 给一张图配一句描述。失败就返回一句人话，不抛——识图失败不该把整份拆解弄坏。
+ */
+export async function captionImage(vision, url, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 30000;
+  const chars = opts.chars ?? 60;
+  if (!vision) return '（没找到能用的视觉端点）';
+  let buf;
+  try {
+    buf = await fetchImage(url, timeoutMs);
+  } catch (err) {
+    return `（图取不下来：${err.message}）`;
+  }
+  const dataUrl = `data:${guessMime(buf)};base64,${buf.toString('base64')}`;
+  const body = {
+    model: vision.model,
+    max_tokens: 400,
+    messages: [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: `用中文一句话说清这张图是什么，不超过 ${chars} 字，别铺垫。` },
+          { type: 'image_url', image_url: { url: dataUrl } },
+        ],
+      },
+    ],
+  };
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${vision.endpoint.replace(/\/+$/, '')}/chat/completions`, {
+      method: 'POST',
+      signal: ctl.signal,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(vision.key ? { Authorization: `Bearer ${vision.key}` } : {}),
+      },
+      body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) return `（识图失败：HTTP ${res.status}）`;
+    const json = JSON.parse(text);
+    const out = String(json?.choices?.[0]?.message?.content || '').trim();
+    return out || '（端点没给出描述）';
+  } catch (err) {
+    const why = err?.name === 'AbortError' ? '超时' : err?.message || String(err);
+    return `（识图失败：${why}）`;
+  } finally {
+    clearTimeout(timer);
+  }
+}