cortico-world-forward-reader 0.1.5 → 0.1.6

package/README.md

@@ -2,6 +2,10 @@
 
 给 [Coopanion](https://github.com/Pal-AI-Lab/Coopanion) 的 Coo 一个工具：把 QQ 的「合并转发 / 聊天记录」一层层拆到底。
 
+> **前置：先装「QQ 群聊」插件（qqbot）。** 这个 World 自己不连 QQ，也不存 QQ 的连接信息——它借 QQ 群聊插件配好的那套东西干活：
+> SnowLuma 的 OneBot HTTP 接口用来取消息，插件里配的视觉端点用来识图。
+> 没装那个插件，这里两个工具都只会回「连不上」。
+
 Coopanion 自带的消息展开只摊开一层，转发里套着的转发看不见。这个 World 借本机 SnowLuma 的 OneBot HTTP 接口递归调 `get_forward_msg`，把整棵树拉出来，按「谁 · 什么时候 · 说了什么」列成带缩进的文字。
 
 **只读**：只调 `get_login_info` / `get_msg` / `get_forward_msg`，不发消息、不改配置、不写任何东西。
@@ -24,9 +28,19 @@ Coopanion 自带的消息展开只摊开一层，转发里套着的转发看不
 
 ## 前置
 
+- 装了 **QQ 群聊插件（qqbot）**：SnowLuma 连接、OneBot 地址、视觉端点都在它那儿配。
 - 装了 **SnowLuma**（OneBot v11 实现），HTTP 接口开着，默认 `127.0.0.1:3000`。
 - OneBot 配置文件里有 `accessToken`。默认读 `D:/snowluma/config/onebot_<QQ号>.json`，也可以在配置页手填路径或直接填地址和 token。
 
+## 识图（可选，默认关）
+
+拆到图片时，可以让视觉端点在图后面补一句「这张图是什么」。
+
+- 端点默认**跟着 QQ 群聊插件已经配好的那份走**，不用在这里再填一遍 key；想单独用别的模型，才填配置里的端点/模型/密钥。
+- 一张图一次调用，会花钱，所以默认关；工具调用时也可以当场传 `captions: true`。
+- 识图失败不会弄坏整份拆解，只会在那张图后面写一句失败原因。
+
+
 ## 配置项
 
 - SnowLuma 配置路径（默认 `D:/snowluma/config/onebot_<QQ号>.json`）

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 不对会直接说清楚哪一步不对。输出过长会截断。\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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortico-world-forward-reader",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "转发拆解 World：把 QQ 的「合并转发」一层层拆到底，嵌套在里面的转发也展开，输出带缩进的人话。只读，不发消息。",
   "type": "module",
   "main": "./src/index.js",
@@ -41,11 +41,11 @@
     "locales": {
       "zh": {
         "displayName": "转发拆解",
-        "description": "把 QQ 的「合并转发」一层层拆到底——嵌套在里面的转发也会展开，按人、按时间列成带缩进的文字。只读：借本机 SnowLuma 的 OneBot HTTP 接口取消息，不发消息、不改任何东西。"
+        "description": "【需要先装 QQ 群聊插件】把 QQ 的「合并转发」一层层拆到底——嵌套在里面的转发也会展开，按人、按时间列成带缩进的文字。只读：借 QQ 群聊插件（qqbot）配好的本机 SnowLuma OneBot HTTP 接口取消息，识图也借那里的视觉端点，不发消息、不改任何东西。"
       },
       "en": {
         "displayName": "Forward Reader",
-        "description": "Expands QQ merged-forward messages recursively, including forwards nested inside forwards, into an indented transcript. Read-only: it queries the local SnowLuma OneBot HTTP API and never sends or changes anything."
+        "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 and the vision endpoint that the QQ chat plugin already set up, and never sends or changes anything."
       }
     },
     "describe": "describe.json",

package/src/config.js

@@ -25,9 +25,12 @@ export const DEFAULTS = {
   captionMax: 6,
   /** 每句描述最多多少字。 */
   captionChars: 60,
-  /** 从哪儿读视觉端点（Coopanion 主配置里的 qqbot.vision）。 */
-  visionConfig: 'D:/Coopanion/data/home/companion/config.json',
-  /** 下面三项一般留空：留空就用 visionConfig 里配的值。 */
+  /**
+   * 想复用别的配置文件里的视觉端点时才填；留空＝自己去本机 Coopanion 的配置里找。
+   * 一般不用碰：这台机器上已经配好的视觉端点会被自动认出来。
+   */
+  visionConfig: '',
+  /** 下面三项留空就沿用找到的那份配置；填了就以这里为准。 */
   visionEndpoint: '',
   visionModel: '',
   visionKey: '',
@@ -40,8 +43,8 @@ export const CONFIG_GROUP = {
     type: 'object',
     title: '转发拆解',
     description:
-      '把 QQ 的「合并转发」一层层拆到底：借 SnowLuma 的 OneBot HTTP 接口递归调 get_forward_msg，' +
-      '嵌套在里面的转发也会展开。只读，不发消息、不改 QQ 配置。',
+      '【前置：先装 QQ 群聊插件】把 QQ 的「合并转发」一层层拆到底：借那个插件配好的 SnowLuma OneBot HTTP 接口递归调 get_forward_msg，' +
+      '嵌套在里面的转发也会展开；识图也借它的视觉端点。只读，不发消息、不改 QQ 配置。',
     properties: {
       'worlds.forward-reader.snowlumaConfig': {
         type: 'string',
@@ -110,24 +113,25 @@ export const CONFIG_GROUP = {
       },
       'worlds.forward-reader.visionConfig': {
         type: 'string',
-        title: '视觉端点配置路径',
+        title: '视觉端点配置路径（一般不用填）',
         description:
-          '从哪个配置文件读视觉端点（默认读 Coopanion 主配置里的 qqbot.vision：endpoint / model / apiKeySecret）。',
+          '留空就行：留空时会自己在本机 Coopanion 的配置里找已经配好的视觉端点。' +
+          '只有想改用另一份配置文件时才填它的路径。',
       },
       'worlds.forward-reader.visionEndpoint': {
         type: 'string',
         title: '视觉端点（可选）',
-        description: '留空就用上面配置文件里的值；填了就盖过它。',
+        description: '填了就忽略上面自动找到的那份，改用这里填的；留空即自动。',
       },
       'worlds.forward-reader.visionModel': {
         type: 'string',
         title: '视觉模型（可选）',
-        description: '留空就用配置文件里的值。',
+        description: '留空就跟端点自动找到的那份配置走。',
       },
       'worlds.forward-reader.visionKey': {
         type: 'string',
         title: '视觉端点密钥（可选）',
-        description: '留空就用配置文件里的值；别把 key 写进仓库。',
+        description: '留空就用找到的那份配置里的密钥；别把 key 写进仓库。',
       },
     },
   },

package/src/tools.js

@@ -17,7 +17,7 @@ export const TOOL_DECLS = [
       '想看清某段聊天记录到底是谁说了什么，也用它。\n' +
       '怎么给编号：QQ 消息事件行首的 `#编号`（如 `#265277450`）就是 message_id，原样填进 ref；带不带 `#`、前后有空格都不要紧。' +
       '编号可能是负数（如 `#-1175570559`），负号是编号的一部分，要一起填，别去掉。\n' +
-      '它只读，只走本机的 SnowLuma OneBot HTTP 接口（默认 127.0.0.1:3000），不发消息、不改任何东西；' +
+      '它只读，只走本机的 SnowLuma OneBot HTTP 接口（默认 127.0.0.1:3000，由 QQ 群聊插件配好），不发消息、不改任何东西；' +
       '接口没开或 token 不对会直接说清楚哪一步不对。输出过长会截断。\n' +
       '图片：默认只给链接；传 `captions: true` 会顺便把图交给视觉端点，在结尾单列一节说每张图是什么（一张图一次调用，按需开）。',
     parameters: {

package/src/vision.js

@@ -1,7 +1,9 @@
 /**
- * 识图：拿 Coopanion 里已经配好的视觉端点（qqbot.vision）给一张图配一句描述。
+ * 识图：借本机已经配好的视觉端点，给一张图配一句描述。
  *
- * 为什么不直接抄一个模型名和 key：主人在设置里换端点/换模型时，这里跟着变，不用改代码。
+ * 端点从哪来：优先用这个 World 自己的 visionEndpoint / visionModel / visionKey；
+ * 没填就自动去本机 Coopanion 的配置里找（一般是 QQ 那份 qqbot.vision），找到就用，
+ * 找不到就老实说没找到。写死不合适的盘符和模型名没有意义——换台机器就跑不通。
  * 端点按 OpenAI 兼容格式 POST /chat/completions，content 里混 text + image_url（data URL 也行）。
  *
  * 踩过的坑：
@@ -9,16 +11,32 @@
  *  2. 图片要先下载成 buffer 再转 base64，直接把外链丢过去有的端点拉不到（QQ 的图还带 rkey）。
  */
 import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 
 const MAX_BYTES = 6 * 1024 * 1024;
 
-/** 从 Coopanion 的配置文件里读 qqbot.vision；读不到就返回 null。 */
-async function readHostVision(configPath) {
-  if (!configPath) return null;
+/**
+ * 本机上可能放着 Coopanion 配置的地方，按顺序试。
+ * 不写死盘符：跑在 Coopanion 里时应用目录就是 execPath 的目录，外面手动跑也能从 cwd 猜。
+ */
+function configCandidates() {
+  const dirs = [dirname(process.execPath), join(dirname(process.execPath), '..'), process.cwd()];
+  const out = [];
+  if (process.env.COOPANION_CONFIG) out.push(process.env.COOPANION_CONFIG);
+  for (const dir of dirs) {
+    out.push(join(dir, 'data', 'home', 'companion', 'config.json'));
+    out.push(join(dir, 'home', 'companion', 'config.json'));
+    out.push(join(dir, 'config.json'));
+  }
+  return [...new Set(out)];
+}
+
+/** 从一份 Coopanion 配置里取视觉端点；没配就返回 null。 */
+async function readVisionFrom(configPath) {
   try {
     const raw = await readFile(configPath, 'utf8');
     const json = JSON.parse(raw);
-    const v = json?.worlds?.qqbot?.vision ?? json?.qqbot?.vision;
+    const v = json?.worlds?.qqbot?.vision ?? json?.qqbot?.vision ?? json?.vision;
     if (!v || !v.endpoint || !v.model) return null;
     return {
       endpoint: String(v.endpoint),
@@ -30,6 +48,16 @@ async function readHostVision(configPath) {
   }
 }
 
+/** 配置里指定了路径就只读那一份，没指定就自己在本机找。 */
+async function readHostVision(configPath) {
+  if (configPath) return readVisionFrom(configPath);
+  for (const path of configCandidates()) {
+    const found = await readVisionFrom(path);
+    if (found) return found;
+  }
+  return null;
+}
+
 /** 配置里的显式值优先，其次读宿主配置。 */
 export async function resolveVision(cfg) {
   const own = {
@@ -76,7 +104,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 '（没找到能用的视觉端点）';
+  if (!vision) return '（没找到能用的视觉端点：可以在设置里填端点/模型/key）';
   let buf;
   try {
     buf = await fetchImage(url, timeoutMs);