dsh-qq-tools 0.9.5 → 0.10.2

package/README.md

@@ -1,6 +1,6 @@
 # dsh-qq-tools
 
-给 DSH（DeepSeek Harness）里的大肥鱼会话用的 QQ 群/私聊工具，走 OneBot 11 HTTP + WebSocket。系统表情在 SnowLuma / NapCat 上都能发；收藏表情、更改头像、好友管理和 QQ 空间走 SnowLuma 的扩展接口，和 QQ 客户端里的数据是同一份。
+给 DSH（DeepSeek Harness）里的大肥鱼会话用的 QQ 群/私聊工具。**只支持 SnowLuma**（通过它的 OneBot 11 HTTP + WebSocket 接口），NapCat 或其他 OneBot 实现都不支持。发表情只发 QQ 收藏夹里的自定义表情；收藏表情、更改头像、好友管理和 QQ 空间走 SnowLuma 的扩展接口，和 QQ 客户端里的数据是同一份。
 
 11 个工具组各自是一个独立的 cordis 组件，外加一个负责选择挂载会话的设置组件，在 DSH 插件页的「包含的组件」里可以逐个开关：
 
@@ -10,8 +10,8 @@
 | 看群聊天记录 | `qq_get_group_history` | 最近消息 + 图片，只读；消息带 `#message_id` |
 | 看群成员 | `qq_get_group_members` | 昵称、群名片、QQ 号、身份 |
 | 发群消息 | `qq_send_group_message` | 发群消息，可引用消息、@人、@全体；同时负责 @ 提醒和群后续轮询 |
-| 发表情 | `qq_send_face` | 在群里或私聊里发系统表情或 QQ 收藏夹里的自定义表情，可带一句话 |
-| 收藏表情 | `qq_list_faces` / `qq_favorite_face` | 看/管理 QQ 账号收藏夹（SnowLuma）：收藏图片、取消收藏、改备注、移到最前 |
+| 发表情 | `qq_send_face` | 在群里或私聊里发 QQ 收藏夹里的自定义表情，可带一句话 |
+| 收藏表情 | `qq_list_faces` / `qq_favorite_face` | 看收藏夹的 `emoji_id` 和文字备注、收藏图片、取消收藏、改备注、移到最前（SnowLuma） |
 | 私聊 | `qq_list_friends` / `qq_get_private_history` / `qq_send_private_message` | 好友列表、私聊记录、发私聊消息；同时负责私聊消息唤醒 |
 | 戳一戳 | `qq_send_poke` | 戳人；同时负责接收戳一戳事件 |
 | 更改头像 | `qq_set_avatar` | 换自己的 QQ 头像：链接、本机文件，或从聊天记录里取图 |
@@ -25,7 +25,17 @@
 
 ```
 cordis.patch.yml                 12 个组件行
-lib/shared.js                    共享核心：配置、OneBot、挂载、@ 轮询、私聊唤醒、戳一戳、表情、头像、好友管理、QQ 空间、观察窗
+lib/config.js                    配置读写、群/私聊白名单
+lib/onebot.js                    SnowLuma HTTP 接口
+lib/qq-state.js                  登录号 / 群名缓存
+lib/session.js                   目标会话、工具挂载、挂载会话接口
+lib/observation.js               观察窗
+lib/images.js                    sharp、图片准入、GIF 拆帧、取图
+lib/prompts.js                   唤醒提示词与回复风格
+lib/tools/                       按域拆开的工具工厂（groups/private/faces/avatar/poke/friends/qzone）
+lib/watchers/                    @ 轮询、戳一戳、私聊唤醒、通用 WS
+lib/mount-all.js                 旧的全量入口
+lib/shared.js                    兼容 barrel：re-export 上面所有模块，保持旧 import 路径可用
 lib/client.js                    浏览器半侧：插件页里的挂载会话下拉框
 lib/index.js                     包根 carrier（承载浏览器半侧和挂载会话接口），也是旧的全量入口
 locale/                          包根行在插件页显示的标题和说明
@@ -80,7 +90,7 @@ test/smoke.mjs                   离线冒烟测试：假 OneBot HTTP 服务 +
 }
 ```
 
-- `napCat` 是 OneBot 11 HTTP 地址（SnowLuma 默认 `http://127.0.0.1:3000`，NapCat 也一样）；`wsUrl` 是 WebSocket 事件地址（默认 `ws://127.0.0.1:3001`）。
+- `napCat` 是 SnowLuma 的 OneBot 11 HTTP 地址（默认 `http://127.0.0.1:3000`；字段名沿用 `napCat`，但只填 SnowLuma，不支持 NapCat 或其他 OneBot 实现）；`wsUrl` 是 SnowLuma 的 WebSocket 事件地址（默认 `ws://127.0.0.1:3001`）。
 - `targetSession` 是目标会话 ID；可以在插件页「挂载会话 → 配置」里下拉选择，也可以直接改这个文件；留空时工具不会挂到任何会话。
 - `groups` 是允许看/发的群；空数组表示不限制。
 - `mentionEnabled` / `pokeEnabled` / `privateEnabled` 分别是 @ 轮询、戳一戳事件、私聊唤醒的总闸，对应组件关掉时它们也不会运行。
@@ -90,8 +100,8 @@ test/smoke.mjs                   离线冒烟测试：假 OneBot HTTP 服务 +
 
 发表情和收藏表情都走 SnowLuma 的扩展接口，收藏夹和 QQ 客户端里的是同一份数据。
 
-- `qq_list_faces`：列 QQ 收藏夹（`emoji_id` + 备注），默认给 3 张不同位置的预览图；想看指定表情就传 `preview`（列表序号或 `emoji_id`，最多 6 张）。传 `query` 时用 SnowLuma 的 `search_sys_faces` 按名字/别名/编号搜系统表情，搜不到再退回内置的常用表情表。
-- `qq_send_face`：`face_id` 发系统表情（OneBot 11 的 `face` 段，SnowLuma 会自动选 classic / small / super 编码）；`emoji_id` 发收藏表情（`send_custom_face`）。两者二选一；带 `text` 时系统表情和文字同一条发出，收藏表情则先发文字再发图。群聊传 `group_id`，私聊传 `user_id`（可选 `group_id` 表示临时会话来源群）。
+- `qq_list_faces`：列 QQ 收藏夹，每个只返回 `emoji_id` 和文字备注，不发预览图；传 `query` 按备注或 `emoji_id` 过滤，`count` 默认 200、最多 500。
+- `qq_send_face`：只发收藏表情（`emoji_id`，走 SnowLuma 的 `send_custom_face`），不再支持系统表情编号。正式发之前先传 `preview=true`：只返回这一张表情图、不发送，确认合适再真发；这样列表阶段不用给模型灌图。带 `text` 时先发文字再发表情。群聊传 `group_id`，私聊传 `user_id`（可选 `group_id` 表示临时会话来源群）。
 - `qq_favorite_face`：
   - `file` 传 `http(s)` 链接、`base64://`、本机路径或 `data:image/...`，收藏一张新表情；
   - `message_id` + `index` 直接从聊天消息里的图片收藏（群记录里的 `[图片#0]` / `[表情包#0]` 就是索引）；
@@ -100,7 +110,9 @@ test/smoke.mjs                   离线冒烟测试：假 OneBot HTTP 服务 +
   - `emoji_id` + `move_to_front` 移到收藏夹最前。
 - 聊天记录里的 `#编号` 是 `message_id`，可以用 `qq_send_face` 的 `reply_to` 回复，也可以配合 `qq_favorite_face` 收藏消息里的图片。
 
-这些自定义表情接口是 SnowLuma 扩展，NapCat 没有。用 NapCat 时系统表情照常能发，收藏表情工具会提示接口不可用。
+主动行为写进了唤醒提示词（@ 提醒、群后续、戳一戳、私聊）：模型约有 25% 的概率主动回一个收藏表情（先看备注挑、再 `preview=true` 看一张图、最后正式发）；收到带图片/表情包的消息时，也约有 25% 的概率用 `qq_favorite_face(message_id, index, desc)` 顺手收藏，`desc` 直接简短描述画面内容（如「闭眼安详」「锅铲敲地」「穿冬装的肥鱼」），否则以后只有备注可看、不知道用哪张。概率由模型按提示词自行把握，代码里不掷骰子。
+
+本插件只支持 SnowLuma；这些自定义表情接口是它的扩展，NapCat 等其他 OneBot 实现没有。
 
 ## 群消息：引用和 @
 
@@ -164,7 +176,7 @@ QQ空间组件提供 4 个工具，走 SnowLuma 的「空间」扩展：
   - `set_right`：改自己空间一条说说的可见范围，参数和发说说时的 `visibility` 一致；
   - `ban` / `unban`：拉黑或解除拉黑某人的空间访问（修改的是你自己空间的黑名单）。
 
-这些接口是 SnowLuma 的扩展，NapCat 上不一定都有；接口不可用时工具会返回 OneBot 的错误原文，不会影响群聊/私聊工具。
+这些接口是 SnowLuma 的扩展（本插件只支持 SnowLuma，NapCat 等其他 OneBot 实现没有这些接口）；接口不可用时工具会返回 SnowLuma 的错误原文，不会影响群聊/私聊工具。
 
 ## 安装
 
@@ -217,13 +229,13 @@ Node.js 要求为 `>=22`，DSH 支持范围为 `0.2.x`，与原有依赖说明
 
 本次声明依据、已获得的安装证据及未验证项见 [整改记录](docs/verification/README.md)。用户已自行测试现有功能；本次不重复功能测试，也不将手工使用情况冒充完整的商城生命周期验收。
 
-本插件需要文件、网络和 OneBot token 权限。配置/诊断日志、本地图片读取、外部服务、账号写操作及失败边界详见 [SECURITY.md](SECURITY.md)。这些能力是 QQ 桥接的实际需要；补齐声明和验收证据不保证 DSH STORE 自动批准，商城可能仍要求 `user-reviewed` 专项审阅或保持 `blocked`。本仓库的验收记录不构成独立安全审计。
+本插件需要文件、网络和 SnowLuma 的 OneBot token 权限。配置/诊断日志、本地图片读取、外部服务、账号写操作及失败边界详见 [SECURITY.md](SECURITY.md)。这些能力是 QQ 桥接的实际需要；补齐声明和验收证据不保证 DSH STORE 自动批准，商城可能仍要求 `user-reviewed` 专项审阅或保持 `blocked`。本仓库的验收记录不构成独立安全审计。
 
 ## 依赖
 
 - DSH 0.2.x（cordis 插件体系）
 - Node.js 22+（内置 `fetch` / `WebSocket`）
-- SnowLuma 提供 OneBot 11 HTTP 接口和 WebSocket 事件。系统表情、群聊和私聊 NapCat 也能用；收藏表情、更改头像、好友分组/备注/申请和 QQ 空间依赖 SnowLuma 的扩展接口，NapCat 上不保证可用。
+- SnowLuma 提供 OneBot 11 HTTP 接口和 WebSocket 事件，本插件只支持 SnowLuma；NapCat 或其他 OneBot 实现不支持。发表情、收藏表情、更改头像、好友分组/备注/申请和 QQ 空间都依赖 SnowLuma 的扩展接口。
 - 可选：`sharp`（GIF 拆帧、尺寸被拒时的兜底重编码）。会从 `SHARP_PATH`、插件自己的 `node_modules`、DSH 宿主 runtimeDir（桌面版通过 `process.argv[2]` 传入）等位置自动查找；找不到时 GIF 交给 DSH 显示首帧，大图仍由 DSH 自动归一化（默认单张源图上限 20MiB），图片不会因此丢失。
 
 改完代码可以跑 `npm test`：它会起一个假 OneBot HTTP 服务、用临时 `DSH_HOME` 加载工具，检查头像、好友管理、好友申请和 QQ 空间的请求体与校验，不连真实 QQ，也不碰 `~/.dsh/qq-tools-config.json`。

package/cordis.patch.yml

@@ -1,7 +1,7 @@
 # DSH 大肥鱼 QQ 群/私聊工具：11 个组件，插件页里可以逐个开关
 #   · 列出 QQ 群 / 看群聊天记录 / 看群成员 —— 只读工具
 #   · 发群消息 —— 同时负责 @ 提醒与群后续轮询
-#   · 发表情 —— 在群里或私聊里发系统表情或 QQ 收藏夹里的自定义表情
+#   · 发表情 —— 在群里或私聊里发 QQ 收藏夹里的自定义表情
 #   · 收藏表情 —— QQ 收藏夹（SnowLuma）：qq_list_faces + qq_favorite_face
 #   · 私聊 —— 好友列表 / 私聊记录 / 发私聊消息，同时负责私聊消息唤醒
 #   · 戳一戳 —— 同时负责接收戳一戳事件

package/lib/config.js

@@ -0,0 +1,96 @@
+// QQ 工具配置：路径、默认值、读写，以及群/私聊白名单。
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, renameSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const DSH_HOME = process.env.DSH_HOME || join(homedir(), '.dsh')
+const CFG_PATH = join(DSH_HOME, 'qq-tools-config.json')
+const DIAG_PATH = join(DSH_HOME, 'qq-tools-diag.log')
+
+const DEFAULT_GROUPS = []
+const DEFAULT_CFG = {
+  napCat: 'http://127.0.0.1:3000',
+  accessToken: '',
+  targetSession: '',
+  groups: DEFAULT_GROUPS,
+  historyCount: 30,
+  maxHistoryCount: 50,
+  pollMs: 5000,
+  mentionEnabled: true,
+  wsUrl: 'ws://127.0.0.1:3001',
+  pokeEnabled: true,
+  privateEnabled: true,
+  privateUsers: [],
+  observationMs: 60000,
+  timeoutMs: 6000,
+}
+
+export function diag(msg) {
+  try {
+    appendFileSync(DIAG_PATH, new Date().toISOString() + '  ' + msg + '\n', 'utf8')
+  } catch (error) {}
+}
+
+export function ensureCfg() {
+  try {
+    if (existsSync(CFG_PATH)) return
+    mkdirSync(DSH_HOME, { recursive: true })
+    writeFileSync(CFG_PATH, JSON.stringify(DEFAULT_CFG, null, 2), 'utf8')
+    diag('已创建配置：' + CFG_PATH)
+  } catch (error) {}
+}
+
+export function loadCfg() {
+  try {
+    const raw = JSON.parse(readFileSync(CFG_PATH, 'utf8'))
+    const out = { ...DEFAULT_CFG, ...(raw && typeof raw === 'object' ? raw : {}) }
+    out.groups = Array.isArray(out.groups) ? out.groups.map((x) => Number(x)).filter(Number.isFinite) : DEFAULT_GROUPS
+    out.napCat = String(out.napCat || DEFAULT_CFG.napCat).replace(/\/+$/, '')
+    out.historyCount = Math.max(1, Math.min(Number(out.historyCount) || 30, Number(out.maxHistoryCount) || 50))
+    out.maxHistoryCount = Math.max(out.historyCount, Math.min(Number(out.maxHistoryCount) || 50, 100))
+    out.pollMs = Math.max(2000, Math.min(Number(out.pollMs) || 5000, 60000))
+    out.timeoutMs = Math.max(1000, Math.min(Number(out.timeoutMs) || 6000, 15000))
+    out.mentionEnabled = out.mentionEnabled !== false
+    out.wsUrl = String(out.wsUrl || DEFAULT_CFG.wsUrl)
+    out.pokeEnabled = out.pokeEnabled !== false
+    out.privateEnabled = out.privateEnabled !== false
+    out.privateUsers = Array.isArray(out.privateUsers) ? out.privateUsers.map((x) => Number(x)).filter(Number.isFinite) : []
+    out.observationMs = Math.max(30000, Math.min(Number(out.observationMs) || 60000, 600000))
+    return out
+  } catch (error) {
+    return { ...DEFAULT_CFG }
+  }
+}
+
+// UI 保存挂载会话时只覆盖传进来的字段，其余配置原样保留；先写临时文件再换名，
+// 避免写一半留下坏 JSON 让后面所有工具都退回默认配置。
+export function saveCfg(patch) {
+  ensureCfg()
+  let current = {}
+  try {
+    const raw = JSON.parse(readFileSync(CFG_PATH, 'utf8'))
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) current = raw
+  } catch (error) {}
+  const next = { ...current, ...(patch && typeof patch === 'object' ? patch : {}) }
+  try {
+    mkdirSync(DSH_HOME, { recursive: true })
+    const tmp = CFG_PATH + '.tmp'
+    writeFileSync(tmp, JSON.stringify(next, null, 2), 'utf8')
+    renameSync(tmp, CFG_PATH)
+  } catch (error) {
+    diag('保存配置失败：' + String((error && error.message) || error))
+    throw error
+  }
+  return next
+}
+
+export function allowedGroup(groupId, cfg) {
+  if (!Array.isArray(cfg.groups) || cfg.groups.length === 0) return true
+  return cfg.groups.includes(Number(groupId))
+}
+
+export function allowedPrivate(userId, cfg) {
+  if (!Array.isArray(cfg.privateUsers) || cfg.privateUsers.length === 0) return true
+  return cfg.privateUsers.includes(Number(userId))
+}

package/lib/images.js

@@ -0,0 +1,420 @@
+// sharp 加载、图片准入（DSH 附件层）、GIF 拆帧，以及从消息/本机路径取图。
+
+import { existsSync, statSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import { onebot } from './onebot.js'
+import { loadCfg, diag } from './config.js'
+
+const requireFromHere = createRequire(import.meta.url)
+let sharpSource = ''
+
+function sharpFromDir(dir) {
+  try {
+    const s = createRequire(join(String(dir), 'noop.js'))('sharp')
+    return s || null
+  } catch (error) {
+    return null
+  }
+}
+
+function sharpFromCache() {
+  try {
+    const cache = requireFromHere.cache || {}
+    for (const key of Object.keys(cache)) {
+      if (!/[\\/]node_modules[\\/]sharp[\\/]/.test(key)) continue
+      const mod = cache[key]
+      if (mod && mod.exports) return mod.exports
+    }
+  } catch (error) {}
+  return null
+}
+
+// sharp 是可选的，按顺序找：SHARP_PATH → 插件自己装的 → 宿主 runtime → 常见宿主目录。
+// 关键的一条是 process.argv[2]：DSH 桌面版的 dsh-desktop-host 用 argv[2] 接 runtimeDir，
+// 插件和宿主在同一个进程里，所以 runtimeDir/node_modules/sharp 就是宿主实际加载的那份。
+// 不写死安装路径；找不到时核心图片逻辑照常工作，只是不拆 GIF 帧，
+// 尺寸被宿主拒绝时也没法兜底重编码。
+function loadSharp() {
+  const probes = []
+  const add = (label, fn) => probes.push({ label, fn })
+
+  if (process.env.SHARP_PATH) add('SHARP_PATH', () => requireFromHere(process.env.SHARP_PATH))
+  add('插件 node_modules', () => requireFromHere('sharp'))
+  if (process.argv[1]) add('宿主入口', () => createRequire(process.argv[1])('sharp'))
+  if (process.argv[2]) add('宿主 runtimeDir', () => sharpFromDir(process.argv[2]))
+
+  // 不同启动方式下 runtimeDir 的位置可能变；把 argv 里看起来像目录的路径都试一遍。
+  for (let i = 1; i < process.argv.length; i++) {
+    const raw = String(process.argv[i] || '')
+    if (!raw) continue
+    try {
+      if (existsSync(raw) && statSync(raw).isDirectory()) add('argv 目录 ' + raw, () => sharpFromDir(raw))
+    } catch (error) {}
+  }
+
+  if (process.cwd()) add('当前目录', () => sharpFromDir(process.cwd()))
+  if (process.resourcesPath) {
+    for (const root of [
+      join(process.resourcesPath, 'app.asar', 'dsh'),
+      join(process.resourcesPath, 'app.asar.unpacked', 'dsh'),
+      join(process.resourcesPath, 'app.asar'),
+      join(process.resourcesPath, 'app.asar.unpacked'),
+      join(process.resourcesPath, 'runtime'),
+    ]) {
+      add('resources ' + root, () => sharpFromDir(root))
+    }
+  }
+  add('已加载模块缓存', sharpFromCache)
+
+  for (const probe of probes) {
+    try {
+      const s = probe.fn()
+      if (s) {
+        sharpSource = probe.label
+        return s
+      }
+    } catch (error) {}
+  }
+  return null
+}
+
+const sharp = loadSharp()
+diag('sharp：' + (sharp
+  ? '已加载（' + sharpSource + '）'
+  : '没找到；GIF 只取首帧，大图交给 DSH 归一化，图片不会因此丢失'))
+let gifWarned = false
+
+// ---------- 图片类型与尺寸 ----------
+// DSH 附件层按真实字节复核 mediaType（IMAGE_TYPE_MISMATCH），文件名和 QQ 的
+// animated 提示都可能撒谎，所以只信字节。大图不依赖 sharp：DSH 默认单张源图
+// 上限 20MiB、归一化目标 4MiB，直接交给它处理；sharp 只用于 GIF 拆帧和
+// admit 被尺寸拒绝后的兜底重编码。
+// 一次 admit 最多处理 10 张：聊天记录现在最多带 10 张图，GIF 拆帧也共用这个上限。
+const ADMIT_IMAGE_LIMIT = 10
+const IMAGE_SOFT_LIMIT = 4 * 1024 * 1024
+const IMAGE_MEDIA_TYPES = {
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  gif: 'image/gif',
+}
+
+function sniffImageType(bytes) {
+  if (!bytes || bytes.length < 12) return ''
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 &&
+      bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) return 'image/png'
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38 &&
+      (bytes[4] === 0x37 || bytes[4] === 0x39) && bytes[5] === 0x61) return 'image/gif'
+  if (bytes.toString('latin1', 0, 4) === 'RIFF' && bytes.toString('latin1', 8, 12) === 'WEBP') return 'image/webp'
+  return ''
+}
+
+async function sharpImageType(bytes) {
+  if (!sharp) return ''
+  try {
+    const meta = await sharp(bytes, { animated: true }).metadata()
+    return IMAGE_MEDIA_TYPES[String((meta && meta.format) || '').toLowerCase()] || ''
+  } catch (error) {
+    return ''
+  }
+}
+
+// DSH 只收 png/jpeg/webp/gif；sharp 能解的其他格式（TIFF 等）先转成它认识的格式。
+async function convertImage(bytes) {
+  if (!sharp) return null
+  try {
+    const meta = await sharp(bytes).metadata()
+    const hasAlpha = !!meta.hasAlpha
+    const out = hasAlpha
+      ? await sharp(bytes).webp({ quality: 82 }).toBuffer()
+      : await sharp(bytes).jpeg({ quality: 82 }).toBuffer()
+    return { bytes: out, mediaType: hasAlpha ? 'image/webp' : 'image/jpeg' }
+  } catch (error) {
+    return null
+  }
+}
+
+// 大图不丢：超过 DSH 归一化目标就先缩到 2048 长边并重编码，通常能压到 1MiB 以内。
+async function shrinkImage(bytes) {
+  if (!sharp || !bytes || !bytes.length) return null
+  try {
+    const meta = await sharp(bytes, { animated: false }).metadata()
+    const width = Number(meta && meta.width) || 0
+    const height = Number(meta && meta.height) || 0
+    if (!width || !height) return null
+    const hasAlpha = !!meta.hasAlpha
+    const scale = Math.min(1, 2048 / Math.max(width, height))
+    const targetWidth = Math.max(1, Math.round(width * scale))
+    const targetHeight = Math.max(1, Math.round(height * scale))
+    for (const quality of [82, 70, 58]) {
+      const pipeline = sharp(bytes, { animated: false })
+        .rotate()
+        .resize({ width: targetWidth, height: targetHeight, fit: 'inside', withoutEnlargement: true })
+      const out = hasAlpha
+        ? await pipeline.webp({ quality }).toBuffer()
+        : await pipeline.jpeg({ quality }).toBuffer()
+      if (out.length <= IMAGE_SOFT_LIMIT) {
+        return { bytes: out, mediaType: hasAlpha ? 'image/webp' : 'image/jpeg' }
+      }
+    }
+  } catch (error) {}
+  return null
+}
+
+
+async function gifFrames(bytes, max = 3) {
+  if (!sharp || !bytes || !bytes.length) return null
+  try {
+    const meta = await sharp(bytes, { animated: true }).metadata()
+    const pages = Number(meta.pages || 1)
+    if (!(pages > 1)) return null
+    const indices = pages <= max
+      ? Array.from({ length: pages }, (_, i) => i)
+      : [0, Math.floor((pages - 1) / 2), pages - 1]
+    const out = []
+    for (const i of indices) {
+      try {
+        const buf = await sharp(bytes, { page: i, pages: 1 })
+          .resize({ width: 1024, withoutEnlargement: true })
+          .png()
+          .toBuffer()
+        if (buf && buf.length) out.push({ bytes: buf, page: i + 1, pages })
+      } catch (error) {}
+    }
+    return out.length ? out : null
+  } catch (error) {
+    return null
+  }
+}
+
+async function imageBytes(data, cfg) {
+  const d = data || {}
+  const url = String(d.url || '').trim()
+  if (/^https?:/i.test(url)) {
+    try {
+      const ctrl = new AbortController()
+      const timer = setTimeout(() => ctrl.abort(), 8000)
+      try {
+        const r = await fetch(url, { signal: ctrl.signal })
+        if (r.ok) return Buffer.from(await r.arrayBuffer())
+      } finally {
+        clearTimeout(timer)
+      }
+    } catch (error) {}
+  }
+  const file = String(d.file || '').trim()
+  if (file.startsWith('base64://')) {
+    try { return Buffer.from(file.slice('base64://'.length), 'base64') } catch (error) {}
+  }
+  if (/^https?:/i.test(file)) {
+    try {
+      const r = await fetch(file)
+      if (r.ok) return Buffer.from(await r.arrayBuffer())
+    } catch (error) {}
+  }
+  if (file && (file.includes('/') || file.includes('\\'))) {
+    try { return readFileSync(file) } catch (error) {}
+  }
+  if (file) {
+    try {
+      const info = await onebot('get_image', { file }, cfg)
+      const u = String((info && (info.url || info.file)) || '').trim()
+      if (/^https?:/i.test(u)) {
+        const r = await fetch(u)
+        if (r.ok) return Buffer.from(await r.arrayBuffer())
+      }
+      if (u && (u.includes('/') || u.includes('\\'))) {
+        try { return readFileSync(u) } catch (error) {}
+      }
+    } catch (error) {}
+  }
+  return null
+}
+
+function admitErrorText(error) {
+  if (!error) return '未知错误'
+  return (error.code ? String(error.code) + '：' : '') + String(error.message || error)
+}
+
+// 单张被拒时可以重编码再试；批量/存储层错误重试没有意义。
+const RETRYABLE_IMAGE_ERRORS = new Set([
+  'IMAGE_TYPE_MISMATCH',
+  'INVALID_IMAGE',
+  'UNSUPPORTED_IMAGE_TYPE',
+  'IMAGE_TOO_LARGE',
+  'IMAGE_TOO_MANY_PIXELS',
+  'IMAGE_DIMENSION_TOO_LARGE',
+])
+
+async function admitOneImage(attachments, block) {
+  try {
+    const out = await attachments.admitPromptContent([block])
+    const hit = (Array.isArray(out) ? out : []).find((x) => x && x.type === 'image')
+    return hit ? { block: hit } : { error: new Error('附件层没有返回图片') }
+  } catch (error) {
+    return { error }
+  }
+}
+
+async function retryImageBlock(block) {
+  let bytes
+  try {
+    bytes = Buffer.from(String((block && block.data) || ''), 'base64')
+  } catch (error) {
+    return null
+  }
+  if (!bytes || !bytes.length) return null
+  const type = sniffImageType(bytes)
+  const fixed = type ? await shrinkImage(bytes) : await convertImage(bytes)
+  if (!fixed) return null
+  return { ...block, data: fixed.bytes.toString('base64'), mediaType: fixed.mediaType }
+}
+
+// 一张坏图不能拖垮整批：先整批送，失败后退回逐张，逐张失败的再重编码试一次。
+async function admitPreparedImages(attachments, prepared) {
+  const blocks = prepared.map((x) => x.block)
+  try {
+    const out = await attachments.admitPromptContent(blocks)
+    const images = (Array.isArray(out) ? out : []).filter((x) => x && x.type === 'image')
+    if (images.length === blocks.length) {
+      return images.map((block, i) => ({ caption: prepared[i].caption, block }))
+    }
+    diag('图片 admit 返回数量不符（' + images.length + '/' + blocks.length + '），改为逐张处理')
+  } catch (error) {
+    diag('图片批量 admit 失败，改为逐张重试：' + admitErrorText(error))
+  }
+  const admitted = []
+  let firstError = ''
+  for (const item of prepared) {
+    let result = await admitOneImage(attachments, item.block)
+    if (result.error && RETRYABLE_IMAGE_ERRORS.has(String(result.error.code || ''))) {
+      const retried = await retryImageBlock(item.block)
+      if (retried) result = await admitOneImage(attachments, retried)
+    }
+    if (result.block) admitted.push({ caption: item.caption, block: result.block })
+    else if (!firstError) firstError = admitErrorText(result.error)
+  }
+  if (firstError && admitted.length < prepared.length) {
+    diag('有图片没能进来（已跳过，其余保留）：' + firstError)
+  }
+  return admitted
+}
+
+export function admitImagesFor(ctx) {
+  return async function admitImages(list) {
+    const attachments = ctx.attachments || (typeof ctx.get === 'function' ? ctx.get('attachments') : null)
+    if (!attachments || typeof attachments.admitPromptContent !== 'function') return []
+    const prepared = []
+    for (const x of Array.isArray(list) ? list : []) {
+      if (prepared.length >= ADMIT_IMAGE_LIMIT) break
+      let bytes = await imageBytes(x.data, x.cfg || loadCfg())
+      if (!bytes || !bytes.length) continue
+      const name = String(x.name || 'qq-image.jpg')
+      // animated 只是提示，type 一律按字节来；猜错会被 DSH 按 IMAGE_TYPE_MISMATCH 整批拒掉。
+      let mediaType = sniffImageType(bytes) || (await sharpImageType(bytes))
+      if (!mediaType) {
+        const converted = await convertImage(bytes)
+        if (!converted) {
+          diag('图片跳过：认不出格式（' + name + '）')
+          continue
+        }
+        bytes = converted.bytes
+        mediaType = converted.mediaType
+      }
+      if (mediaType === 'image/gif') {
+        const frames = await gifFrames(bytes, 3)
+        if (frames) {
+          for (const f of frames) {
+            prepared.push({
+              caption: String(x.caption || '') + `（GIF 第 ${f.page}/${f.pages} 帧）`,
+              block: {
+                type: 'image',
+                data: f.bytes.toString('base64'),
+                mediaType: 'image/png',
+                name: name.replace(/\.[^.]+$/, '') + `-gif-${f.page}.png`,
+              },
+            })
+            if (prepared.length >= ADMIT_IMAGE_LIMIT) break
+          }
+          continue
+        }
+        if (!sharp && !gifWarned) {
+          gifWarned = true
+          diag('GIF 帧拆分不可用：没有加载到 sharp，动图会按静图处理')
+        }
+      }
+      // 大图不在这里预缩放：DSH 自己会把源图归一化到 4MiB，20MiB 以内都能收。
+      // 只有 admit 因尺寸被拒时才在 retryImageBlock 里用 sharp 兜底重编码。
+      prepared.push({
+        caption: String(x.caption || ''),
+        block: { type: 'image', data: bytes.toString('base64'), mediaType, name },
+      })
+    }
+    if (!prepared.length) return []
+    return admitPreparedImages(attachments, prepared)
+  }
+}
+
+// SnowLuma 的 add_custom_face 只认 file:///、base64://、http(s)://，
+// 本机路径要先转成 file:/// URL，data:image/... 转成 base64://。
+export function imageSourceOf(raw) {
+  const s = String(raw || '').trim()
+  if (!s) return ''
+  if (/^(https?:\/\/|base64:\/\/|file:\/\/)/i.test(s)) return s
+  const dataUrl = s.match(/^data:[^;,]*;base64,(.*)$/is)
+  if (dataUrl) return 'base64://' + dataUrl[1].replace(/\s+/g, '')
+  try {
+    if (existsSync(s)) return pathToFileURL(s).href
+  } catch (error) {}
+  return s
+}
+
+// 从聊天消息里取图片：get_msg → 图片段 → 可直接交给 SnowLuma 的 file 来源。
+// 收藏表情、换头像、发说说都用这一条路径，索引从 0 开始。
+export async function imageSourceFromMessage(messageId, index, cfg) {
+  const msg = await onebot('get_msg', { message_id: messageId }, cfg)
+  const segs = Array.isArray(msg && msg.message) ? msg.message : []
+  const images = segs.filter((s) => s && (s.type === 'image' || s.type === 'mface') && s.data)
+  const idx = Number.isInteger(Number(index)) ? Math.max(0, Number(index)) : 0
+  const pick = images[idx]
+  if (!pick) return { error: `这条消息里没有第 ${idx} 张图片（共 ${images.length} 张）` }
+  const source = imageSourceOf(pick.data.url || pick.data.file)
+  if (!source) return { error: '拿不到这条消息里的图片地址' }
+  return { source, total: images.length }
+}
+
+export async function imageSourcesFromMessage(messageId, indexes, cfg, max = 9) {
+  const msg = await onebot('get_msg', { message_id: messageId }, cfg)
+  const segs = Array.isArray(msg && msg.message) ? msg.message : []
+  const picks = segs.filter((s) => s && (s.type === 'image' || s.type === 'mface') && s.data)
+  const wanted = Array.isArray(indexes) && indexes.length
+    ? indexes.map((x) => Number(x)).filter((x) => Number.isInteger(x))
+    : picks.map((_, i) => i)
+  const sources = []
+  for (const i of wanted) {
+    if (sources.length >= max) break
+    const pick = picks[i]
+    if (!pick) continue
+    const source = imageSourceOf(pick.data.url || pick.data.file)
+    if (source) sources.push(source)
+  }
+  return { sources, total: picks.length }
+}
+
+// 工具回执里不要把 base64 原样吐回去，不然一次换头像就能塞满上下文。
+export function describeSource(source) {
+  const s = String(source || '')
+  if (/^base64:\/\//i.test(s)) return 'base64://…'
+  if (/^file:\/\//i.test(s)) {
+    try {
+      return decodeURIComponent(new URL(s).pathname).split('/').pop() || '本机图片'
+    } catch (error) {
+      return '本机图片'
+    }
+  }
+  if (/^https?:/i.test(s)) return s.length > 200 ? s.slice(0, 200) + '…' : s
+  return s.slice(0, 200)
+}

package/lib/index.js

@@ -5,7 +5,8 @@
 //     「挂载会话」的 HTTP 接口；浏览器半侧（lib/client.js）也只能从包根行
 //     被发现，子路径行不会被 dsh-client-modules 扫描到。
 //   · 旧配置直接引用 `dsh-qq-tools` 时没有 carrier 标记，仍然挂全部工具。
-import { mountAll, mountTargetSessionRoute } from './shared.js'
+import { mountAll } from './mount-all.js'
+import { mountTargetSessionRoute } from './session.js'
 
 export * from './shared.js'