dsh-qq-tools 0.8.1 → 0.9.0

package/lib/shared.js

@@ -1,12 +1,15 @@
 // dsh-qq-tools —— 给大肥鱼会话用的轻量 QQ 群/私聊工具 + 唤醒（共享核心）
 //
-// 结构（2026-10-23 拆分，2026-10-24 加表情和私聊）：
-//   · 每个工具是一个独立的 cordis 组件，由 cordis.patch.yml 里的 8 个 insert 行加载；
-//     插件详情页「包含的组件」会列出 8 个工具，每个都有自己的开关。
-//   · 本文件只放共享逻辑：配置、OneBot、目标会话挂载、@ 轮询、私聊唤醒、戳一戳、表情、观察窗。
+// 结构（2026-10-23 拆分，2026-10-24 加表情和私聊，2026-10-26 加头像/好友管理/QQ 空间）：
+//   · 每个工具是一个独立的 cordis 组件，由 cordis.patch.yml 里的 11 个工具 insert 行加载
+//     （包根 carrier 另有一行）；插件详情页会列出 11 个工具组，每个都有自己的开关。
+//   · 本文件只放共享逻辑：配置、OneBot、目标会话挂载、@ 轮询、私聊唤醒、戳一戳、表情、
+//     头像、好友管理、QQ 空间、观察窗。
 //   · 发群消息组件负责 @ 提醒轮询；戳一戳组件负责接收戳一戳事件；
 //     收藏表情组件负责 QQ 收藏夹（走 SnowLuma 的自定义表情接口，和 QQ 客户端同步）；
-//     私聊组件负责好友/私聊记录/发私聊消息，以及私聊消息唤醒。
+//     私聊组件负责好友/私聊记录/发私聊消息，以及私聊消息唤醒；
+//     好友管理组件负责好友资料/备注/分组/删好友/名片赞和好友申请；
+//     QQ 空间组件负责说说列表、详情评论、发表和管理。
 //
 // 设计目标（按用户要求）：
 //   · 群聊不逐条转发、不自动回；由「主动搭话」或「有人 @」触发，
@@ -34,7 +37,7 @@
 //
 // 工具本身的开关在 DSH 插件页的组件列表里：关掉某个组件，它就不再注册对应工具。
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, renameSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, renameSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { randomUUID } from 'node:crypto'
@@ -47,34 +50,82 @@ const DIAG_PATH = join(DSH_HOME, 'qq-tools-diag.log')
 
 
 const requireFromHere = createRequire(import.meta.url)
+let sharpSource = ''
 
-// sharp 是可选的，按这个顺序找：SHARP_PATH → 插件自己装的 → 宿主进程能解析到的。
-// DSH 桌面版把 sharp 打在 resources/app.asar/dsh/node_modules 下，CLI 版跟着
-// @deepseek-ai/dsh 的依赖走，所以从宿主的启动入口解析最稳，不用写死安装路径。
+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 = []
-  if (process.env.SHARP_PATH) probes.push(() => requireFromHere(process.env.SHARP_PATH))
-  probes.push(() => requireFromHere('sharp'))
-  if (process.argv[1]) probes.push(() => createRequire(process.argv[1])('sharp'))
-  if (process.resourcesPath) {
-    probes.push(() => createRequire(join(process.resourcesPath, 'app.asar', 'dsh', 'package.json'))('sharp'))
+  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) {}
   }
-  for (const p of [
-    '/usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/sharp',
-    '/usr/lib/node_modules/@deepseek-ai/dsh/node_modules/sharp',
-  ]) {
-    probes.push(() => requireFromHere(p))
+
+  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()
-      if (s) return s
+      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
 
 const DEFAULT_GROUPS = []
@@ -106,6 +157,15 @@ function clean(s) {
   return String(s == null ? '' : s).replace(/[\u0000-\u001F\u007F]/g, ' ').replace(/\s+/g, ' ').trim()
 }
 
+// 说说正文和评论要保留换行；只清掉控制字符，不折叠空白。
+function cleanMultiline(s, max = 4000) {
+  return String(s == null ? '' : s)
+    .replace(/\r\n?/g, '\n')
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, ' ')
+    .trim()
+    .slice(0, max)
+}
+
 function ensureCfg() {
   try {
     if (existsSync(CFG_PATH)) return
@@ -469,8 +529,9 @@ export function makeListTool() {
 
 // ---------- 图片类型与尺寸 ----------
 // DSH 附件层按真实字节复核 mediaType（IMAGE_TYPE_MISMATCH），文件名和 QQ 的
-// animated 提示都可能撒谎，所以只信字节。DSH 默认单张源图上限 20MiB，
-// 归一化目标 4MiB；源图超过 4MiB 时本地先缩一下，避免白白走一遍宿主重编码。
+// animated 提示都可能撒谎，所以只信字节。大图不依赖 sharp：DSH 默认单张源图
+// 上限 20MiB、归一化目标 4MiB，直接交给它处理；sharp 只用于 GIF 拆帧和
+// admit 被尺寸拒绝后的兜底重编码。
 const ADMIT_IMAGE_LIMIT = 6
 const IMAGE_SOFT_LIMIT = 4 * 1024 * 1024
 const IMAGE_MEDIA_TYPES = {
@@ -725,14 +786,8 @@ export function admitImagesFor(ctx) {
           diag('GIF 帧拆分不可用：没有加载到 sharp，动图会按静图处理')
         }
       }
-      // 以前这里直接丢弃 >5MiB 的图；DSH 实际能收 20MiB 并自动归一化，所以改成先缩放。
-      if (bytes.length > IMAGE_SOFT_LIMIT) {
-        const shrunk = await shrinkImage(bytes)
-        if (shrunk) {
-          bytes = shrunk.bytes
-          mediaType = shrunk.mediaType
-        }
-      }
+      // 大图不在这里预缩放：DSH 自己会把源图归一化到 4MiB，20MiB 以内都能收。
+      // 只有 admit 因尺寸被拒时才在 retryImageBlock 里用 sharp 兜底重编码。
       prepared.push({
         caption: String(x.caption || ''),
         block: { type: 'image', data: bytes.toString('base64'), mediaType, name },
@@ -1161,6 +1216,54 @@ function imageSourceOf(raw) {
   return s
 }
 
+// 从聊天消息里取图片：get_msg → 图片段 → 可直接交给 SnowLuma 的 file 来源。
+// 收藏表情、换头像、发说说都用这一条路径，索引从 0 开始。
+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 }
+}
+
+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 原样吐回去，不然一次换头像就能塞满上下文。
+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)
+}
+
+
 export function makeSendFaceTool(onSent) {
   return {
     name: 'qq_send_face',
@@ -1450,16 +1553,9 @@ export function makeFavoriteFaceTool() {
         }
         let source = imageSourceOf(args && args.file)
         if (!source && args && args.message_id != null && args.message_id !== '') {
-          const msg = await onebot('get_msg', { message_id: args.message_id }, 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(args.index)) ? Math.max(0, Number(args.index)) : 0
-          const pick = images[idx]
-          if (!pick) {
-            return { ok: false, error: `这条消息里没有第 ${idx} 张图片（共 ${images.length} 张）` }
-          }
-          source = imageSourceOf(pick.data.url || pick.data.file)
-          if (!source) return { ok: false, error: '拿不到这条消息里的图片地址' }
+          const got = await imageSourceFromMessage(args.message_id, args.index, cfg)
+          if (got.error) return { ok: false, error: got.error }
+          source = got.source
         }
         if (!source) return { ok: false, error: '要收藏就传 file 或 message_id' }
         const data = await onebot('add_custom_face', { file: source }, cfg)
@@ -1534,6 +1630,1171 @@ export function makePokeTool(onSent) {
 }
 
 
+// ---------- 头像 ----------
+// set_qq_avatar 是 SnowLuma 扩展，file 和图片接口一样吃 http(s)/base64:///file://。
+// 换头像会立刻对所有好友和群友可见，描述里明确要求只在用户提出时调用。
+export function makeSetAvatarTool() {
+  return {
+    name: 'qq_set_avatar',
+    description:
+      '改自己的 QQ 头像（SnowLuma set_qq_avatar）。' +
+      'file 传 http(s) 链接、base64://、data:image/... 或本机文件路径；' +
+      '也可以用 message_id + index 从聊天记录里的某张图片取图。' +
+      '只有用户明确要求换头像时才用；换完不用再重复说明。',
+    parameters: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: '图片：http(s) 链接、base64://、data:image/... 或本机路径；和 message_id 二选一' },
+        message_id: { type: 'string', description: '从这条消息里取图当头像；和 file 二选一' },
+        index: { type: 'number', description: 'message_id 里第几张图片，从 0 开始，默认 0' },
+      },
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const fileRaw = String((args && args.file) || '').trim()
+      const hasMessage = args && args.message_id != null && args.message_id !== ''
+      if (fileRaw && hasMessage) return { ok: false, error: 'file 和 message_id 只能选一个' }
+      if (!fileRaw && !hasMessage) return { ok: false, error: '要换头像就传 file 或 message_id' }
+      try {
+        let source = imageSourceOf(fileRaw)
+        if (!source && hasMessage) {
+          const got = await imageSourceFromMessage(args.message_id, args.index, cfg)
+          if (got.error) return { ok: false, error: got.error }
+          source = got.source
+        }
+        if (!source) return { ok: false, error: '拿不到头像图片' }
+        await onebot('set_qq_avatar', { file: source }, cfg)
+        return { ok: true, avatar: true, source: describeSource(source) }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '换头像失败：' + String((v && v.error) || '未知错误') }]
+      return [{ type: 'text', text: 'QQ 头像已更新（' + (v.source || '图片') + '）。' }]
+    },
+  }
+}
+
+
+// ---------- 好友管理 ----------
+// 读写好友资料、备注、分组、名片赞，以及好友申请。
+// 普通好友申请只有 request 事件，SnowLuma 没有「列出历史好友申请」的 HTTP 接口，
+// 所以这里一边接 WebSocket 事件进收件箱，一边用 get_doubt_friends_add_request
+// 拿服务端保存的可疑申请；历史普通申请只能去 QQ 客户端看。
+const FRIEND_REQUEST_LIMIT = 30
+const friendRequestInbox = new Map()
+
+function rememberFriendRequest(ev) {
+  const flag = clean(ev && ev.flag)
+  if (!flag) return
+  const userId = String((ev && ev.user_id) || '')
+  const time = Number(ev && ev.time) || Math.floor(Date.now() / 1000)
+  friendRequestInbox.set(flag, {
+    flag,
+    user_id: userId,
+    nickname: '',
+    comment: String((ev && ev.comment) || '').slice(0, 500),
+    time,
+    at: Date.now(),
+  })
+  if (friendRequestInbox.size > FRIEND_REQUEST_LIMIT) {
+    const oldest = [...friendRequestInbox.entries()].sort((a, b) => (a[1].at || 0) - (b[1].at || 0))[0]
+    if (oldest) friendRequestInbox.delete(oldest[0])
+  }
+  diag('好友申请 → 收件箱：' + userId + ' ' + clean(ev && ev.comment).slice(0, 120))
+}
+
+async function friendEntryOf(cfg, userId) {
+  try {
+    const groups = await onebot('get_friends_with_category', {}, cfg)
+    if (Array.isArray(groups) && groups.length) {
+      for (const g of groups) {
+        const list = Array.isArray(g && g.buddyList) ? g.buddyList : []
+        const hit = list.find((b) => String(b && b.user_id) === String(userId))
+        if (hit) {
+          const categoryId = Number(g.categoryId)
+          return {
+            entry: hit,
+            category: { id: Number.isFinite(categoryId) ? categoryId : 0, name: clean(g.categoryName) },
+          }
+        }
+      }
+    }
+  } catch (error) {}
+  // 分组接口不可用（或好友不在分组结果里）时退回普通好友列表：
+  // 至少能判断是不是好友、拿到备注。
+  try {
+    const data = await onebot('get_friend_list', {}, cfg)
+    const hit = (Array.isArray(data) ? data : []).find((f) => String(f && f.user_id) === String(userId))
+    if (hit) return { entry: hit, category: null }
+  } catch (error) {}
+  return null
+}
+
+// 接口不可用时返回 null（未知），不要谎报「不是单向好友」。
+async function oneWayOf(cfg, userId) {
+  try {
+    const list = await onebot('get_unidirectional_friend_list', {}, cfg)
+    return (Array.isArray(list) ? list : []).some((x) => {
+      const id = x && typeof x === 'object'
+        ? String(x.user_id || x.uin || x.qq || '')
+        : String(x || '')
+      return !!id && id === String(userId)
+    })
+  } catch (error) {
+    return null
+  }
+}
+
+function sexText(value) {
+  const s = String(value == null ? '' : value).toLowerCase()
+  if (s === 'male' || s === '1' || s === '男') return '男'
+  if (s === 'female' || s === '2' || s === '女') return '女'
+  if (!s || s === '0' || s === 'unknown' || s === '未知') return '未知'
+  return clean(value)
+}
+
+export function makeGetFriendInfoTool() {
+  return {
+    name: 'qq_get_friend_info',
+    description:
+      '看某个 QQ 的资料和好友关系：昵称、备注、分组、性别年龄、等级、VIP、是否单向好友。' +
+      'user_id 从 qq_list_friends、聊天记录或好友申请里拿。只读。',
+    parameters: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'number', description: '对方 QQ 号' },
+      },
+      required: ['user_id'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const userId = Number(args && args.user_id)
+      if (!Number.isFinite(userId)) return { ok: false, error: 'user_id 不是有效 QQ 号' }
+      if (!allowedPrivate(userId, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+      let info = null
+      let infoError = ''
+      try {
+        info = await onebot('get_stranger_info', { user_id: userId }, cfg)
+      } catch (error) {
+        infoError = String((error && error.message) || error)
+      }
+      const found = await friendEntryOf(cfg, userId)
+      if (!info && !found) {
+        return { ok: false, error: infoError || '查不到这个 QQ 的资料' }
+      }
+      const entry = (found && found.entry) || {}
+      const oneWay = await oneWayOf(cfg, userId)
+      const rawLevel = info
+        ? (info.qq_level != null ? info.qq_level : info.qqLevel != null ? info.qqLevel : info.level)
+        : 0
+      const friend = {
+        user_id: String(userId),
+        nickname: clean((info && info.nickname) || entry.nickname),
+        remark: clean(entry.remark || (info && info.remark)),
+        category: found ? found.category : null,
+        sex: sexText(info && info.sex),
+        age: Number((info && info.age) || 0),
+        qid: clean(info && info.qid),
+        level: Number(rawLevel || 0),
+        vip: !!(info && info.is_vip),
+        vip_level: Number((info && info.vip_level) || 0),
+        is_friend: !!found,
+        one_way: oneWay,
+      }
+      return { ok: true, friend }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '看好友资料失败：' + String((v && v.error) || '未知错误') }]
+      const f = v.friend || {}
+      const lines = [
+        `QQ ${f.user_id}：`,
+        '- 昵称：' + (f.nickname || '未知'),
+        '- 备注：' + (f.remark || '（无）'),
+        '- 分组：' + (f.category ? `${f.category.name || '未命名'}（id ${f.category.id}）` : (f.is_friend ? '未知（分组接口没返回）' : '不是好友')),
+        '- 性别年龄：' + (f.sex || '未知') + (f.age ? '，' + f.age + ' 岁' : ''),
+        '- 等级：' + (f.level || '未知'),
+        '- VIP：' + (f.vip ? '是' + (f.vip_level ? '（' + f.vip_level + ' 级）' : '') : '否'),
+        '- 单向好友：' + (f.one_way === true ? '是' : f.one_way === false ? '否' : '未知（接口不可用）'),
+      ]
+      if (f.qid) lines.splice(2, 0, '- QID：' + f.qid)
+      return [{ type: 'text', text: lines.join('\n') }]
+    },
+  }
+}
+
+export function makeListFriendCategoriesTool() {
+  return {
+    name: 'qq_list_friend_categories',
+    description:
+      '看好友分组和每个分组里的好友（SnowLuma get_friends_with_category）。' +
+      '移动好友分组时，category_id / category_name 从这里拿。' +
+      '分组接口漏掉的好友会补进「未分组（接口未返回）」里。只读。',
+    parameters: { type: 'object', properties: {}, additionalProperties: false },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute() {
+      const cfg = loadCfg()
+      try {
+        let categories = []
+        let usedFriendListFallback = false
+        try {
+          const data = await onebot('get_friends_with_category', {}, cfg)
+          if (!Array.isArray(data)) throw new Error('好友分组接口返回的不是数组')
+          categories = data.map((g) => ({
+            id: Number.isFinite(Number(g && g.categoryId)) ? Number(g.categoryId) : 0,
+            name: clean(g && g.categoryName),
+            count: Number((g && g.categoryMbCount) || 0),
+            friends: (Array.isArray(g && g.buddyList) ? g.buddyList : []).map((b) => ({
+              user_id: String((b && b.user_id) || ''),
+              nickname: clean(b && b.nickname),
+              remark: clean(b && b.remark),
+            })),
+          }))
+        } catch (error) {
+          // 老版本或 NapCat 没有分组接口时，退回普通好友列表，至少还能看到人。
+          const data = await onebot('get_friend_list', {}, cfg)
+          const friends = (Array.isArray(data) ? data : []).map((f) => ({
+            user_id: String((f && f.user_id) || ''),
+            nickname: clean(f && f.nickname),
+            remark: clean(f && f.remark),
+          }))
+          categories = [{ id: 0, name: '我的好友', count: friends.length, friends }]
+          usedFriendListFallback = true
+        }
+        // SnowLuma 的分组接口可能漏人（真机见过 86 个好友只返回 83 个），
+        // 用普通好友列表补齐，免得模型以为这些人不存在。
+        if (!usedFriendListFallback) {
+          try {
+            const data = await onebot('get_friend_list', {}, cfg)
+            const known = new Set()
+            for (const c of categories) for (const f of c.friends) known.add(f.user_id)
+            const missing = (Array.isArray(data) ? data : []).map((f) => ({
+              user_id: String((f && f.user_id) || ''),
+              nickname: clean(f && f.nickname),
+              remark: clean(f && f.remark),
+            })).filter((f) => f.user_id && !known.has(f.user_id))
+            if (missing.length) {
+              categories.push({ id: -1, name: '未分组（接口未返回）', count: missing.length, friends: missing })
+            }
+          } catch (error) {}
+        }
+        for (const c of categories) {
+          c.friends = c.friends.filter((f) => f.user_id && allowedPrivate(f.user_id, cfg))
+          c.count = c.friends.length
+        }
+        const total = categories.reduce((n, c) => n + c.friends.length, 0)
+        return { ok: true, total, categories }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '看好友分组失败：' + String((v && v.error) || '未知错误') }]
+      if (!v.categories.length) return [{ type: 'text', text: '没有好友分组。' }]
+      const lines = [`好友分组（${v.categories.length} 个，共 ${v.total} 人）：`]
+      for (const c of v.categories) {
+        const names = c.friends.slice(0, 20).map((f) => f.remark || f.nickname || f.user_id)
+        const idText = c.id >= 0 ? `id ${c.id}，` : ''
+        lines.push(`- ${c.name || '未命名'}（${idText}${c.count} 人）${names.length ? '：' + names.join('、') : ''}${c.friends.length > names.length ? ' …' : ''}`)
+      }
+      return [{ type: 'text', text: lines.join('\n') }]
+    },
+  }
+}
+
+export function makeUpdateFriendTool() {
+  return {
+    name: 'qq_update_friend',
+    description:
+      '改好友备注或把好友移到别的分组。' +
+      'remark 传空字符串表示清空备注；分组用 category_id 或 category_name（名称必须唯一且完全匹配），' +
+      '分组 id/名称从 qq_list_friend_categories 拿。两件事至少做一件。',
+    parameters: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'number', description: '好友 QQ 号' },
+        remark: { type: 'string', description: '新备注；传空字符串清空；不传就不改备注' },
+        category_id: { type: 'number', description: '目标分组 ID' },
+        category_name: { type: 'string', description: '目标分组名称（完全匹配）' },
+      },
+      required: ['user_id'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const userId = Number(args && args.user_id)
+      if (!Number.isFinite(userId)) return { ok: false, error: 'user_id 不是有效 QQ 号' }
+      if (!allowedPrivate(userId, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+      const hasRemark = args && args.remark != null
+      const remark = clean(args && args.remark)
+      const hasCategoryId = args && args.category_id != null && args.category_id !== ''
+      const categoryId = hasCategoryId ? Number(args.category_id) : null
+      const categoryName = clean(args && args.category_name)
+      if (!hasRemark && !hasCategoryId && !categoryName) {
+        return { ok: false, error: '要改什么？传 remark，或 category_id / category_name' }
+      }
+      if (hasCategoryId && !Number.isInteger(categoryId)) return { ok: false, error: 'category_id 不是有效整数' }
+      try {
+        const changes = []
+        if (hasRemark) {
+          await onebot('set_friend_remark', { user_id: userId, remark }, cfg)
+          changes.push(remark ? '备注改成「' + remark + '」' : '备注已清空')
+        }
+        if (hasCategoryId || categoryName) {
+          let targetId = categoryId
+          let targetName = categoryName
+          if (!hasCategoryId) {
+            try {
+              const data = await onebot('get_friends_with_category', {}, cfg)
+              const hits = (Array.isArray(data) ? data : []).filter((g) => clean(g && g.categoryName) === categoryName)
+              if (hits.length !== 1) {
+                return {
+                  ok: false,
+                  error: (hits.length
+                    ? `有 ${hits.length} 个分组都叫「${categoryName}」，请改用 category_id`
+                    : `没找到叫「${categoryName}」的分组，先用 qq_list_friend_categories 看`)
+                    + (changes.length ? '（已' + changes.join('；') + '）' : ''),
+                  changed: changes,
+                }
+              }
+              targetId = Number(hits[0].categoryId)
+              if (!Number.isInteger(targetId)) targetId = null
+              targetName = clean(hits[0].categoryName)
+            } catch (error) {
+              // 分组列表接口不可用时直接让 SnowLuma 按名称处理。
+              targetId = null
+            }
+          }
+          const body = { uin: userId }
+          if (targetId != null) body.categoryId = targetId
+          else if (targetName) body.categoryName = targetName
+          await onebot('set_friends_category', body, cfg)
+          changes.push('移到分组「' + (targetName || targetId) + '」')
+        }
+        return { ok: true, user_id: userId, remark: hasRemark ? remark : undefined, changes }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '改好友资料失败：' + String((v && v.error) || '未知错误') }]
+      return [{ type: 'text', text: `QQ ${v.user_id} 已更新：${(v.changes || []).join('；')}。` }]
+    },
+  }
+}
+
+export function makeDeleteFriendTool() {
+  return {
+    name: 'qq_delete_friend',
+    description:
+      '删除一个好友。不可撤销：只有用户明确要求删好友时才用，并且必须传 confirm=true。' +
+      'block=true 会在删除的同时屏蔽对方。',
+    parameters: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'number', description: '好友 QQ 号' },
+        block: { type: 'boolean', description: 'true = 删除并屏蔽，默认 false' },
+        confirm: { type: 'boolean', description: '必须显式传 true，防止误删' },
+      },
+      required: ['user_id', 'confirm'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const userId = Number(args && args.user_id)
+      if (!Number.isFinite(userId)) return { ok: false, error: 'user_id 不是有效 QQ 号' }
+      if (!allowedPrivate(userId, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+      if (!args || args.confirm !== true) return { ok: false, error: '删好友不可撤销，需要 confirm=true 才会执行' }
+      try {
+        const block = args.block === true
+        await onebot('delete_friend', { user_id: userId, block }, cfg)
+        return { ok: true, removed: true, user_id: userId, blocked: block }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '删好友失败：' + String((v && v.error) || '未知错误') }]
+      return [{ type: 'text', text: `已删除好友 QQ ${v.user_id}${v.blocked ? '，并已屏蔽' : ''}。` }]
+    },
+  }
+}
+
+export function makeSendLikeTool() {
+  return {
+    name: 'qq_send_like',
+    description:
+      '给好友的名片点赞（QQ 资料卡赞）。times 是次数，默认 1，最多 20。别频繁调用。',
+    parameters: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'number', description: '好友 QQ 号' },
+        times: { type: 'number', description: '点赞次数，默认 1，最多 20' },
+      },
+      required: ['user_id'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const userId = Number(args && args.user_id)
+      if (!Number.isFinite(userId)) return { ok: false, error: 'user_id 不是有效 QQ 号' }
+      if (!allowedPrivate(userId, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+      const times = Math.max(1, Math.min(Math.floor(Number(args && args.times) || 1), 20))
+      try {
+        await onebot('send_like', { user_id: userId, times }, cfg)
+        return { ok: true, user_id: userId, times }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '点赞失败：' + String((v && v.error) || '未知错误') }]
+      return [{ type: 'text', text: `已给 QQ ${v.user_id} 点了 ${v.times} 个赞。` }]
+    },
+  }
+}
+
+export function makeListFriendRequestsTool() {
+  return {
+    name: 'qq_list_friend_requests',
+    description:
+      '看待处理的好友申请：插件运行期间通过 WebSocket 收到的普通申请 + QQ 账号里保存的可疑好友申请。' +
+      '每项带 flag，用 qq_handle_friend_request 同意/拒绝。' +
+      '普通申请只在插件启动后收到才在这里，历史申请要去 QQ 客户端看。只读。',
+    parameters: {
+      type: 'object',
+      properties: {
+        include_doubt: { type: 'boolean', description: '要不要一起查可疑好友申请，默认 true' },
+      },
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const includeDoubt = !(args && args.include_doubt === false)
+      const requests = [...friendRequestInbox.values()]
+        .sort((a, b) => (b.time || 0) - (a.time || 0) || (b.at || 0) - (a.at || 0))
+        .slice(0, FRIEND_REQUEST_LIMIT)
+      if (requests.length) {
+        await Promise.all(requests.slice(0, 5).map(async (r) => {
+          if (r.nickname || !r.user_id) return
+          try {
+            const info = await onebot('get_stranger_info', { user_id: Number(r.user_id) }, cfg)
+            r.nickname = clean(info && info.nickname)
+          } catch (error) {}
+        }))
+      }
+      let doubt = []
+      let doubtError = ''
+      if (includeDoubt) {
+        try {
+          const data = await onebot('get_doubt_friends_add_request', { count: 50 }, cfg)
+          doubt = (Array.isArray(data) ? data : []).map((x) => ({
+            kind: 'doubt',
+            flag: String((x && x.uid) || ''),
+            user_id: String((x && x.user_id) || ''),
+            nickname: clean(x && x.nick),
+            source: clean(x && x.source),
+            reason: clean(x && x.reason),
+            comment: String((x && x.msg) || '').slice(0, 500),
+            group_code: String((x && x.group_code) || ''),
+            time: Number((x && x.reqTime) || 0),
+          })).filter((x) => x.flag)
+        } catch (error) {
+          doubtError = String((error && error.message) || error)
+        }
+      }
+      return {
+        ok: true,
+        requests: requests.map(({ at, ...r }) => ({ kind: 'friend', ...r })),
+        doubt,
+        doubt_error: doubtError,
+        inbox_note: '普通申请从插件启动后开始收，历史申请不在收件箱里',
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '看好友申请失败：' + String((v && v.error) || '未知错误') }]
+      const lines = []
+      if (v.requests.length) {
+        lines.push(`普通好友申请（${v.requests.length} 个）：`)
+        for (const r of v.requests) {
+          const who = r.nickname ? `${r.nickname}(${r.user_id})` : `QQ ${r.user_id}`
+          lines.push(`- ${who}${r.comment ? '：' + r.comment : ''}  flag=${r.flag}`)
+        }
+      }
+      if (v.doubt.length) {
+        lines.push(`可疑好友申请（${v.doubt.length} 个）：`)
+        for (const d of v.doubt) {
+          const who = d.nickname ? `${d.nickname}(${d.user_id})` : `QQ ${d.user_id}`
+          const extra = [d.source && '来源 ' + d.source, d.reason && '原因 ' + d.reason].filter(Boolean).join('，')
+          lines.push(`- ${who}${extra ? '（' + extra + '）' : ''}${d.comment ? '：' + d.comment : ''}  flag=${d.flag}`)
+        }
+      }
+      if (!v.requests.length && !v.doubt.length) {
+        lines.push(v.doubt_error
+          ? '现在没有普通好友申请；可疑申请接口不可用：' + v.doubt_error.slice(0, 200)
+          : '现在没有待处理的好友申请。')
+      } else if (v.doubt_error) {
+        lines.push('可疑申请接口不可用：' + v.doubt_error.slice(0, 200))
+      }
+      if (v.requests.length || v.doubt.length) {
+        lines.push('用 qq_handle_friend_request 处理：传 flag、kind（friend/doubt）、approve=true/false。')
+      }
+      return [{ type: 'text', text: lines.join('\n') }]
+    },
+  }
+}
+
+export function makeHandleFriendRequestTool() {
+  return {
+    name: 'qq_handle_friend_request',
+    description:
+      '同意或拒绝好友申请。flag 从 qq_list_friend_requests 拿，也可以传 user_id 自动在待处理列表里找。' +
+      'kind=friend 是普通申请，kind=doubt 是可疑申请。approve 必须明确传 true（同意）或 false（拒绝）。',
+    parameters: {
+      type: 'object',
+      properties: {
+        flag: { type: 'string', description: '申请的处理标识，来自 qq_list_friend_requests' },
+        user_id: { type: 'number', description: '申请人 QQ 号；不传 flag 时用它查收件箱' },
+        kind: { type: 'string', enum: ['friend', 'doubt'], description: '申请类型，默认 friend' },
+        approve: { type: 'boolean', description: 'true = 同意，false = 拒绝' },
+      },
+      required: ['approve'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const kind = args && args.kind === 'doubt' ? 'doubt' : 'friend'
+      const userId = args && args.user_id != null ? Number(args.user_id) : 0
+      if (args && args.user_id != null && !Number.isFinite(userId)) {
+        return { ok: false, error: 'user_id 不是有效 QQ 号' }
+      }
+      if (!args || typeof args.approve !== 'boolean') return { ok: false, error: 'approve 必须明确传 true 或 false' }
+      const approve = args.approve
+      let flag = clean(args && args.flag)
+      let nickname = ''
+      if (!flag && userId) {
+        if (kind === 'friend') {
+          const hit = [...friendRequestInbox.values()]
+            .filter((r) => String(r.user_id) === String(userId))
+            .sort((a, b) => (b.at || 0) - (a.at || 0))[0]
+          if (hit) {
+            flag = hit.flag
+            nickname = hit.nickname
+          }
+        } else {
+          try {
+            const data = await onebot('get_doubt_friends_add_request', { count: 50 }, cfg)
+            const hit = (Array.isArray(data) ? data : []).find((x) => String((x && x.user_id) || '') === String(userId))
+            if (hit) {
+              flag = String((hit && hit.uid) || '')
+              nickname = clean(hit && hit.nick)
+            }
+          } catch (error) {}
+        }
+      }
+      if (!flag) {
+        return { ok: false, error: '没有找到要处理的申请；先用 qq_list_friend_requests 拿 flag' }
+      }
+      try {
+        if (kind === 'doubt') {
+          await onebot('set_doubt_friends_add_request', { flag, approve }, cfg)
+        } else {
+          await onebot('set_friend_add_request', { flag, approve }, cfg)
+          friendRequestInbox.delete(flag)
+        }
+        return { ok: true, kind, approved: approve, flag, user_id: userId || null, nickname }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '处理好友申请失败：' + String((v && v.error) || '未知错误') }]
+      const who = v.nickname ? `${v.nickname}(${v.user_id || ''})` : (v.user_id ? 'QQ ' + v.user_id : '这条申请')
+      return [{ type: 'text', text: `已${v.approved ? '同意' : '拒绝'}${who}的好友申请。` }]
+    },
+  }
+}
+
+export function startFriendRequestWatcher(ctx) {
+  startWsWatcher(ctx, '好友申请', () => true, (ev) => {
+    if (ev && ev.post_type === 'request' && ev.request_type === 'friend') rememberFriendRequest(ev)
+  })
+}
+
+
+// ---------- QQ 空间（说说） ----------
+// SnowLuma 的「空间」扩展：send_qzone_msg / get_qzone_msg_list / get_qzone_feeds /
+// get_qzone_msg_detail / like_qzone / unlike_qzone / comment_qzone /
+// delete_qzone_msg / set_qzone_msg_right / set_qzone_ban。
+// 图片统一走 imageSourceOf：http(s)、base64://、file://（本机路径会转成 file://）。
+const QZONE_VISIBILITY = { public: 1, friends: 4, partial: 16, private: 64, exclude: 128 }
+const QZONE_VISIBILITY_NAMES = {
+  1: '所有人可见',
+  4: '好友可见',
+  16: '部分好友可见',
+  64: '仅自己可见',
+  128: '部分好友不可见',
+}
+
+function qzoneRightOf(value) {
+  const key = String(value == null ? '' : value).trim()
+  if (QZONE_VISIBILITY[key] != null) return QZONE_VISIBILITY[key]
+  const n = Number(key)
+  if (Number.isInteger(n) && QZONE_VISIBILITY_NAMES[n]) return n
+  return 0
+}
+
+function plainText(s) {
+  return clean(String(s || '')
+    .replace(/<br\s*\/?>/gi, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'"))
+}
+
+function qzoneImagesOf(list) {
+  return (Array.isArray(list) ? list : [])
+    .map((x) => {
+      const url = String(x || '').trim()
+      return url.startsWith('//') ? 'https:' + url : url
+    })
+    .filter((x) => /^https?:/i.test(x))
+}
+
+async function admitQzoneImages(admitImages, cfg, items) {
+  if (typeof admitImages !== 'function') return []
+  const picked = []
+  for (const item of Array.isArray(items) ? items : []) {
+    if (picked.length >= 4) break
+    if (!item || !/^https?:/i.test(String(item.url || ''))) continue
+    picked.push(item)
+  }
+  if (!picked.length) return []
+  return admitImages(picked.map((item) => ({
+    data: { url: item.url },
+    cfg,
+    name: item.name || 'qq-qzone.jpg',
+    caption: item.caption || 'QQ 空间图片',
+  })))
+}
+
+function qzonePostOf(x, max = 500) {
+  const time = Number((x && x.time) || 0)
+  return {
+    tid: String((x && x.tid) || ''),
+    content: clean((x && x.content) || plainText(x && x.html)).slice(0, max),
+    time,
+    t: fmtTime(time),
+    comment_num: Number((x && (x.comment_num != null ? x.comment_num : x.comment_count)) || 0),
+    is_private: !!(x && x.is_private),
+    images: qzoneImagesOf(x && x.images),
+  }
+}
+
+// 部分 SnowLuma 版本只会把 feed 的 HTML 透传回来，tid/content 仍是 null。
+// 说说（appid=311）的 tid 在 HTML 的 tid="..." / data-tid="..." 里，
+// 取出来就能继续用详情、点赞和评论；补不回来的 feed 保持只读。
+function qzoneTidOf(x) {
+  const direct = x && x.tid != null ? String(x.tid).trim() : ''
+  if (direct) return direct
+  if (Number(x && x.appid) !== 311) return ''
+  const html = String((x && x.html) || '')
+  const hit = html.match(/(?:data-)?tid[="'\s:]+([0-9a-fA-F]{16,64})/)
+  return hit ? hit[1] : ''
+}
+
+export function makeListQzoneTool(admitImages) {
+  return {
+    name: 'qq_list_qzone',
+    description:
+      '看 QQ 空间说说。默认看自己的说说；传 target_uin 看别人的；feeds=true 看好友动态（可用 cursor 翻页）。' +
+      '好友动态里只保留说说（appid=311）；如果 SnowLuma 没从 HTML 里解析出 tid，会尽量自己补回来，补不回来的只能看不能互动。' +
+      '返回 tid、正文、时间、评论数和图片；tid 可以传给 qq_get_qzone_post / qq_manage_qzone。只读。',
+    parameters: {
+      type: 'object',
+      properties: {
+        feeds: { type: 'boolean', description: 'true = 看好友动态（get_qzone_feeds），默认 false' },
+        target_uin: { type: 'number', description: '看谁的说说；不传就是自己（feeds 模式忽略）' },
+        pos: { type: 'number', description: '从第几条开始，默认 0（feeds 模式忽略）' },
+        count: { type: 'number', description: '本页数量，默认 10，最多 50' },
+        cursor: { type: 'string', description: '好友动态翻页游标，传上一页返回的 next_cursor' },
+        include_images: { type: 'boolean', description: '要不要把最近的图片也给你看（最多 4 张，默认 true）' },
+      },
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const count = Math.max(1, Math.min(Math.floor(Number(args && args.count) || 10), 50))
+      const withImages = !(args && args.include_images === false)
+      try {
+        if (args && args.feeds === true) {
+          const body = { count }
+          const cursor = String((args && args.cursor) || '').trim()
+          if (cursor) body.cursor = cursor
+          const data = await onebot('get_qzone_feeds', body, cfg)
+          const rawFeeds = Array.isArray(data && data.feeds) ? data.feeds : []
+          const feeds = rawFeeds.map((x) => {
+            const post = qzonePostOf(x)
+            const tid = qzoneTidOf(x)
+            return {
+              ...post,
+              tid,
+              actionable: !!tid,
+              appid: Number((x && x.appid) || 0),
+              uin: String((x && x.uin) || ''),
+              name: clean(x && x.nickname),
+              like_count: Number((x && x.like_count) || 0),
+              content_complete: !!(x && x.content_complete),
+            }
+          }).filter((x) => x.appid === 311 || x.tid)
+          const imageItems = []
+          for (const f of feeds) {
+            for (const url of f.images) {
+              imageItems.push({
+                url,
+                name: `qq-qzone-${f.tid}.jpg`,
+                caption: `好友动态 ${f.tid} 的图片（${f.name || f.uin || '好友'}）`,
+              })
+            }
+          }
+          const images = withImages ? await admitQzoneImages(admitImages, cfg, imageItems) : []
+          return {
+            ok: true,
+            mode: 'feeds',
+            count: feeds.length,
+            feeds,
+            skipped: rawFeeds.length - feeds.length,
+            has_more: !!(data && data.has_more),
+            next_cursor: String((data && data.next_cursor) || ''),
+            images,
+          }
+        }
+        const targetUin = args && args.target_uin != null ? Number(args.target_uin) : 0
+        if (args && args.target_uin != null && !Number.isFinite(targetUin)) {
+          return { ok: false, error: 'target_uin 不是有效 QQ 号' }
+        }
+        if (targetUin && !allowedPrivate(targetUin, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+        const body = {
+          pos: Math.max(0, Math.floor(Number(args && args.pos) || 0)),
+          num: count,
+        }
+        if (targetUin) body.target_uin = targetUin
+        const data = await onebot('get_qzone_msg_list', body, cfg)
+        const raw = listOf(data, 'msglist')
+        const posts = raw.map((x) => qzonePostOf(x)).filter((x) => x.tid)
+        const imageItems = []
+        for (const p of posts) {
+          for (const url of p.images) {
+            imageItems.push({
+              url,
+              name: `qq-qzone-${p.tid}.jpg`,
+              caption: `说说 ${p.tid} 的图片${p.content ? '（' + p.content.slice(0, 30) + '）' : ''}`,
+            })
+          }
+        }
+        const images = withImages ? await admitQzoneImages(admitImages, cfg, imageItems) : []
+        return {
+          ok: true,
+          mode: 'list',
+          target_uin: targetUin || null,
+          total: Number((data && data.total) || posts.length),
+          count: posts.length,
+          posts,
+          images,
+        }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '看 QQ 空间失败：' + String((v && v.error) || '未知错误') }]
+      const blocks = []
+      if (v.mode === 'feeds') {
+        if (!v.feeds.length) {
+          return [{ type: 'text', text: '好友动态里现在没有能识别的说说。' + (v.skipped ? `（跳过 ${v.skipped} 条非说说动态）` : '') }]
+        }
+        const lines = [`好友动态（${v.feeds.length} 条${v.has_more ? '，还有更多' : ''}）：`]
+        for (const f of v.feeds) {
+          const tag = f.tid ? `[tid=${f.tid}]` : '[没有 tid，只能看]'
+          lines.push(`- ${f.name || f.uin || '好友'}(${f.uin || '?'}) ${tag} ${f.t} 赞 ${f.like_count} 评论 ${f.comment_num}`)
+          if (f.content) lines.push('  ' + f.content.split('\n').join('\n  '))
+        }
+        if (v.next_cursor) lines.push(`翻下一页：feeds=true，cursor=${v.next_cursor}`)
+        if (v.skipped) lines.push(`另有 ${v.skipped} 条非说说动态（相册、广告等）没有列出。`)
+        if (v.feeds.some((f) => !f.tid)) lines.push('没有 tid 的动态不能直接点赞/评论，可以配合 qq_get_qzone_post 或去 QQ 客户端看。')
+        blocks.push({ type: 'text', text: lines.join('\n') })
+      } else {
+        if (!v.posts.length) return [{ type: 'text', text: '没有看到说说。' }]
+        const where = v.target_uin ? `QQ ${v.target_uin} 的空间` : '你的空间'
+        const lines = [`${where}（共 ${v.total} 条，本页 ${v.count} 条）：`]
+        for (const p of v.posts) {
+          lines.push(`- [tid=${p.tid}] ${p.t} 评论 ${p.comment_num}${p.is_private ? '（仅自己可见）' : ''}`)
+          if (p.content) lines.push('  ' + p.content.split('\n').join('\n  '))
+        }
+        lines.push('看评论详情用 qq_get_qzone_post；发新说说用 qq_send_qzone_post。')
+        blocks.push({ type: 'text', text: lines.join('\n') })
+      }
+      for (const img of Array.isArray(v.images) ? v.images : []) {
+        if (img && img.caption) blocks.push({ type: 'text', text: img.caption })
+        if (img && img.block) blocks.push(img.block)
+      }
+      return blocks
+    },
+  }
+}
+
+export function makeGetQzonePostTool(admitImages) {
+  return {
+    name: 'qq_get_qzone_post',
+    description:
+      '看一条说说的详情和评论（SnowLuma get_qzone_msg_detail）。tid 从 qq_list_qzone 拿。' +
+      '返回评论的 comment_id 和 uin；回复时传给 qq_manage_qzone：' +
+      '回复一级评论传 comment_id + comment_uin，回复楼中楼再传 reply_uin + reply_name。只读。',
+    parameters: {
+      type: 'object',
+      properties: {
+        tid: { type: 'string', description: '说说 tid' },
+        target_uin: { type: 'number', description: '说说所属 QQ 号，默认自己' },
+        pos: { type: 'number', description: '从第几条评论开始，默认 0' },
+        count: { type: 'number', description: '看多少条一级评论，默认 20，最多 50' },
+        include_images: { type: 'boolean', description: '详情里带图片时要不要看图，默认 true' },
+      },
+      required: ['tid'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const tid = args && args.tid != null ? String(args.tid).trim() : ''
+      if (!tid) return { ok: false, error: 'tid 不能为空' }
+      const targetUin = args && args.target_uin != null ? Number(args.target_uin) : 0
+      if (args && args.target_uin != null && !Number.isFinite(targetUin)) {
+        return { ok: false, error: 'target_uin 不是有效 QQ 号' }
+      }
+      if (targetUin && !allowedPrivate(targetUin, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+      const count = Math.max(1, Math.min(Math.floor(Number(args && args.count) || 20), 50))
+      try {
+        const body = { tid, pos: Math.max(0, Math.floor(Number(args && args.pos) || 0)), num: count }
+        if (targetUin) body.target_uin = targetUin
+        const data = await onebot('get_qzone_msg_detail', body, cfg)
+        const comments = (Array.isArray(data && data.comments) ? data.comments : []).map((c) => ({
+          uin: String((c && (c.uin || c.user_id)) || ''),
+          name: clean(c && (c.name || c.nickname)),
+          time: Number((c && c.time) || 0),
+          t: fmtTime(c && c.time),
+          content: cleanMultiline(c && c.content, 1000),
+          comment_id: c && c.comment_id != null ? String(c.comment_id) : '',
+          replies: (Array.isArray(c && c.replies) ? c.replies : []).map((r) => ({
+            uin: String((r && (r.uin || r.user_id)) || ''),
+            name: clean(r && (r.name || r.nickname)),
+            time: Number((r && r.time) || 0),
+            t: fmtTime(r && r.time),
+            content: cleanMultiline(r && r.content, 1000),
+            comment_id: r && r.comment_id != null ? String(r.comment_id) : '',
+            parent_comment_id: r && r.parent_comment_id != null ? String(r.parent_comment_id) : '',
+            parent_comment_uin: r && r.parent_comment_uin != null ? String(r.parent_comment_uin) : '',
+          })),
+        }))
+        const post = {
+          tid: String((data && data.tid) || tid),
+          content: cleanMultiline(data && data.content, 4000),
+          comment_num: Number((data && data.comment_num) || 0),
+          comments,
+          images: qzoneImagesOf(data && data.images),
+        }
+        let images = []
+        if (!(args && args.include_images === false) && post.images.length) {
+          images = await admitQzoneImages(admitImages, cfg, post.images.map((url) => ({
+            url,
+            name: `qq-qzone-${post.tid}.jpg`,
+            caption: `说说 ${post.tid} 的图片`,
+          })))
+        }
+        return { ok: true, post, images }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '看说说详情失败：' + String((v && v.error) || '未知错误') }]
+      const p = v.post || {}
+      const lines = [`说说 ${p.tid}：`, p.content || '（没有正文）']
+      lines.push(`评论 ${p.comment_num || 0} 条：`)
+      if (!p.comments.length) lines.push('（还没有评论）')
+      for (const c of p.comments) {
+        lines.push(`- ${c.name || c.uin}(${c.uin}) [comment_id=${c.comment_id}] ${c.t}：${c.content || '（空）'}`)
+        for (const r of c.replies) {
+          lines.push(`  ↳ ${r.name || r.uin}(${r.uin}) [comment_id=${r.comment_id} parent=${r.parent_comment_id}] ${r.t}：${r.content || '（空）'}`)
+        }
+      }
+      if (p.comments.length) {
+        lines.push('回复一级评论：qq_manage_qzone action=comment，传 comment_id + comment_uin=该评论 uin；' +
+          '回复楼中楼再加 reply_uin + reply_name，comment_id 仍用一级评论的 id（不要用二级回复自己的 id）。')
+      }
+      const blocks = [{ type: 'text', text: lines.join('\n') }]
+      for (const img of Array.isArray(v.images) ? v.images : []) {
+        if (img && img.caption) blocks.push({ type: 'text', text: img.caption })
+        if (img && img.block) blocks.push(img.block)
+      }
+      return blocks
+    },
+  }
+}
+
+export function makeSendQzonePostTool() {
+  return {
+    name: 'qq_send_qzone_post',
+    description:
+      '发一条 QQ 空间说说（SnowLuma send_qzone_msg）。content 是正文；' +
+      'images 是图片（http(s)、base64://、本机路径，最多 9 张），也可以用 message_id 从消息里取图。' +
+      'visibility：public=所有人，friends=好友，partial=指定好友可见，private=仅自己，exclude=指定好友不可见；' +
+      'partial/exclude 要传 target_uins。发说说对外可见，只有用户明确要求时才用。',
+    parameters: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: '说说正文，不要 Markdown' },
+        images: { type: 'array', items: { type: 'string' }, description: '图片列表，最多 9 张' },
+        message_id: { type: 'string', description: '从这条消息里取图片一起发' },
+        image_indexes: { type: 'array', items: { type: 'number' }, description: 'message_id 里要哪几张图片（从 0 开始）；不传就全取' },
+        visibility: { type: 'string', enum: ['public', 'friends', 'partial', 'private', 'exclude'], description: '可见范围，默认 public' },
+        target_uins: { type: 'array', items: { type: 'number' }, description: 'partial/exclude 时的 QQ 号列表' },
+      },
+      required: ['content'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const content = cleanMultiline(args && args.content, 2000)
+      if (!content) return { ok: false, error: '说说正文是空的' }
+      const visibilityKey = String((args && args.visibility) || 'public')
+      const ugcRight = qzoneRightOf(visibilityKey)
+      if (!ugcRight) return { ok: false, error: 'visibility 只能是 public/friends/partial/private/exclude' }
+      const targetUins = (Array.isArray(args && args.target_uins) ? args.target_uins : [])
+        .map((x) => Number(x)).filter((x) => Number.isInteger(x) && x > 0)
+      if ((ugcRight === 16 || ugcRight === 128) && !targetUins.length) {
+        return { ok: false, error: 'partial/exclude 需要 target_uins 指定名单' }
+      }
+      try {
+        const images = (Array.isArray(args && args.images) ? args.images : [])
+          .map(imageSourceOf).filter(Boolean)
+        const messageId = args && args.message_id
+        if (messageId != null && messageId !== '') {
+          if (images.length >= 9) return { ok: false, error: '最多 9 张图片' }
+          const got = await imageSourcesFromMessage(messageId, args.image_indexes, cfg, 9 - images.length)
+          if (!got.sources.length) {
+            return {
+              ok: false,
+              error: got.total
+                ? `选中的图片序号没有匹配到（这条消息共 ${got.total} 张）`
+                : '这条消息里没有图片',
+            }
+          }
+          images.push(...got.sources)
+        }
+        if (images.length > 9) return { ok: false, error: '最多 9 张图片' }
+        const body = { content, ugc_right: ugcRight }
+        if (images.length) body.images = images
+        if (ugcRight === 16 || ugcRight === 128) body.target_uins = targetUins
+        const data = await onebot('send_qzone_msg', body, cfg)
+        return {
+          ok: true,
+          tid: String((data && data.tid) || ''),
+          time: Number((data && data.time) || 0),
+          visibility: QZONE_VISIBILITY_NAMES[ugcRight],
+          image_count: images.length,
+        }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '发说说失败：' + String((v && v.error) || '未知错误') }]
+      const extra = v.image_count ? `，${v.image_count} 张图` : ''
+      return [{ type: 'text', text: `说说已发布（tid ${v.tid || '?'}${extra}，${v.visibility || '所有人可见'}）。` }]
+    },
+  }
+}
+
+export function makeManageQzoneTool() {
+  return {
+    name: 'qq_manage_qzone',
+    description:
+      '管理 QQ 空间说说。action：\n' +
+      '- like / unlike：点赞或取消赞，需要 tid（abstime 传列表里的 time 更可靠）\n' +
+      '- comment：评论或回复，需要 tid + content；回复一级评论再传 comment_id + comment_uin，' +
+      '回复楼中楼再传 reply_uin + reply_name；只有普通评论能带图\n' +
+      '- delete：删除自己空间的一条说说，需要 tid + confirm=true，不可撤销\n' +
+      '- set_right：改自己空间一条说说的可见范围，需要 tid + visibility（partial/exclude 再传 target_uins）\n' +
+      '- ban / unban：拉黑或解除拉黑某人的空间访问，需要 user_id',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['like', 'unlike', 'comment', 'delete', 'set_right', 'ban', 'unban'],
+          description: '要做什么',
+        },
+        tid: { type: 'string', description: '说说 tid；like/unlike/comment/delete/set_right 需要' },
+        target_uin: { type: 'number', description: '说说所属 QQ 号，默认自己' },
+        abstime: { type: 'number', description: '说说发表时间（unix 秒），点赞时传更可靠' },
+        content: { type: 'string', description: '评论内容（action=comment）' },
+        images: { type: 'array', items: { type: 'string' }, description: '评论图片（普通评论可选，最多 9 张）' },
+        comment_id: { type: 'string', description: '要回复的一级评论 ID（评论详情里的 comment_id）' },
+        comment_uin: { type: 'number', description: '一级评论作者 QQ 号' },
+        reply_uin: { type: 'number', description: '楼中楼里要回复的用户 QQ 号' },
+        reply_name: { type: 'string', description: '楼中楼里要回复的用户昵称' },
+        visibility: { type: 'string', enum: ['public', 'friends', 'partial', 'private', 'exclude'], description: 'set_right 的新可见范围' },
+        target_uins: { type: 'array', items: { type: 'number' }, description: 'set_right 时 partial/exclude 的 QQ 号列表' },
+        user_id: { type: 'number', description: 'ban/unban 的目标 QQ 号' },
+        confirm: { type: 'boolean', description: 'delete 时必须显式传 true' },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
+    async execute(args) {
+      const cfg = loadCfg()
+      const action = String((args && args.action) || '')
+      const tid = args && args.tid != null ? String(args.tid).trim() : ''
+      const targetUin = args && args.target_uin != null ? Number(args.target_uin) : 0
+      if (args && args.target_uin != null && !Number.isFinite(targetUin)) {
+        return { ok: false, error: 'target_uin 不是有效 QQ 号' }
+      }
+      if (targetUin && !allowedPrivate(targetUin, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+      const needTid = ['like', 'unlike', 'comment', 'delete', 'set_right']
+      if (needTid.includes(action) && !tid) return { ok: false, error: action + ' 需要 tid' }
+      try {
+        if (action === 'like' || action === 'unlike') {
+          const body = { tid }
+          if (targetUin) body.target_uin = targetUin
+          const abstime = Number(args && args.abstime)
+          if (Number.isFinite(abstime) && abstime > 0) body.abstime = Math.floor(abstime)
+          await onebot(action === 'like' ? 'like_qzone' : 'unlike_qzone', body, cfg)
+          return { ok: true, action, tid, liked: action === 'like' }
+        }
+        if (action === 'comment') {
+          const content = cleanMultiline(args && args.content, 1000)
+          if (!content) return { ok: false, error: '评论内容是空的' }
+          const images = (Array.isArray(args && args.images) ? args.images : [])
+            .map(imageSourceOf).filter(Boolean)
+          if (images.length > 9) return { ok: false, error: '评论最多 9 张图片' }
+          const parentId = args && args.comment_id != null ? String(args.comment_id).trim() : ''
+          const hasParentUin = args && args.comment_uin != null
+          const parentUin = hasParentUin ? Number(args.comment_uin) : 0
+          const hasReplyUin = args && args.reply_uin != null
+          const replyUin = hasReplyUin ? Number(args.reply_uin) : 0
+          const replyName = clean(args && args.reply_name)
+          if (parentId && (!hasParentUin || !Number.isInteger(parentUin) || parentUin <= 0)) {
+            return { ok: false, error: 'comment_id 和 comment_uin 要一起传，comment_uin 是正整数 QQ 号' }
+          }
+          if (hasParentUin && !parentId) {
+            return { ok: false, error: 'comment_uin 要配合 comment_id 一起传' }
+          }
+          if (hasReplyUin && (!Number.isInteger(replyUin) || replyUin <= 0)) {
+            return { ok: false, error: 'reply_uin 不是有效 QQ 号' }
+          }
+          if (hasReplyUin && (!parentId || !replyName)) {
+            return { ok: false, error: '回复楼中楼需要 comment_id + comment_uin + reply_uin + reply_name' }
+          }
+          if (parentId && images.length) return { ok: false, error: '回复评论只能发文字，不能带图' }
+          const body = { tid, content }
+          if (targetUin) body.target_uin = targetUin
+          if (images.length) body.images = images
+          if (parentId) {
+            body.comment_id = parentId
+            body.comment_uin = parentUin
+          }
+          if (replyUin) {
+            body.reply_uin = replyUin
+            body.reply_name = replyName
+          }
+          const data = await onebot('comment_qzone', body, cfg)
+          return {
+            ok: true,
+            action,
+            tid,
+            comment_id: data && data.comment_id != null ? String(data.comment_id) : '',
+            parent_comment_id: data && data.parent_comment_id != null ? String(data.parent_comment_id) : '',
+            parent_comment_uin: Number((data && data.parent_comment_uin) || 0),
+          }
+        }
+        if (action === 'delete') {
+          if (!args || args.confirm !== true) {
+            return { ok: false, error: '删说说不可撤销，需要 confirm=true 才会执行' }
+          }
+          await onebot('delete_qzone_msg', { tid }, cfg)
+          return { ok: true, action, tid, deleted: true }
+        }
+        if (action === 'set_right') {
+          const ugcRight = qzoneRightOf(args && args.visibility)
+          if (!ugcRight) return { ok: false, error: 'set_right 需要 visibility（public/friends/partial/private/exclude）' }
+          const targetUins = (Array.isArray(args && args.target_uins) ? args.target_uins : [])
+            .map((x) => Number(x)).filter((x) => Number.isInteger(x) && x > 0)
+          if ((ugcRight === 16 || ugcRight === 128) && !targetUins.length) {
+            return { ok: false, error: 'partial/exclude 需要 target_uins 指定名单' }
+          }
+          const body = { tid, ugc_right: ugcRight }
+          if (ugcRight === 16 || ugcRight === 128) body.target_uins = targetUins
+          const data = await onebot('set_qzone_msg_right', body, cfg)
+          return {
+            ok: true,
+            action,
+            tid,
+            ugc_right: Number((data && data.ugc_right) || ugcRight),
+            visibility: QZONE_VISIBILITY_NAMES[Number((data && data.ugc_right) || ugcRight)],
+          }
+        }
+        if (action === 'ban' || action === 'unban') {
+          const userId = Number(args && args.user_id)
+          if (!Number.isFinite(userId) || !userId) return { ok: false, error: 'ban/unban 需要 user_id' }
+          if (!allowedPrivate(userId, cfg)) return { ok: false, error: '这个 QQ 不在允许列表里' }
+          await onebot('set_qzone_ban', { user_id: userId, enable: action === 'ban' }, cfg)
+          return { ok: true, action, user_id: userId, banned: action === 'ban' }
+        }
+        return { ok: false, error: '不认识的 action：' + action }
+      } catch (error) {
+        return { ok: false, error: String((error && error.message) || error) }
+      }
+    },
+    render(_args, v) {
+      if (!v || !v.ok) return [{ type: 'text', text: '操作 QQ 空间失败：' + String((v && v.error) || '未知错误') }]
+      if (v.action === 'like' || v.action === 'unlike') {
+        return [{ type: 'text', text: `${v.liked ? '已点赞' : '已取消赞'}（tid ${v.tid}）。` }]
+      }
+      if (v.action === 'comment') {
+        return [{ type: 'text', text: `评论已发（tid ${v.tid}，comment_id ${v.comment_id || '?'}）。` }]
+      }
+      if (v.action === 'delete') {
+        return [{ type: 'text', text: `已删除说说 ${v.tid}。` }]
+      }
+      if (v.action === 'set_right') {
+        return [{ type: 'text', text: `说说 ${v.tid} 的可见范围已改为「${v.visibility || v.ugc_right}」。` }]
+      }
+      if (v.action === 'ban' || v.action === 'unban') {
+        return [{ type: 'text', text: `已${v.banned ? '拉黑' : '解除拉黑'} QQ ${v.user_id} 的空间访问。` }]
+      }
+      return [{ type: 'text', text: 'QQ 空间操作完成。' }]
+    },
+  }
+}
+
+
 // ---------- 当前活着的工具组件 ----------
 // @ 提醒的提示词只提还开着的工具，免得模型去调一个被关掉的组件。
 const activeCounts = new Map()
@@ -2004,14 +3265,32 @@ export function mountAll(ctx) {
   const faceList = mountOneTool(ctx, makeListFacesTool(admitImages))
   const faceFav = mountOneTool(ctx, makeFavoriteFaceTool())
   const poke = mountOneTool(ctx, makePokeTool(startObservation))
+  const avatar = mountOneTool(ctx, makeSetAvatarTool())
   const friends = mountOneTool(ctx, makeListFriendsTool())
   const privateHistory = mountOneTool(ctx, makePrivateHistoryTool(admitImages))
   const privateSend = mountOneTool(ctx, makeSendPrivateTool())
+  const friendInfo = mountOneTool(ctx, makeGetFriendInfoTool())
+  const friendCategories = mountOneTool(ctx, makeListFriendCategoriesTool())
+  const friendUpdate = mountOneTool(ctx, makeUpdateFriendTool())
+  const friendDelete = mountOneTool(ctx, makeDeleteFriendTool())
+  const friendLike = mountOneTool(ctx, makeSendLikeTool())
+  const friendRequests = mountOneTool(ctx, makeListFriendRequestsTool())
+  const friendHandle = mountOneTool(ctx, makeHandleFriendRequestTool())
+  const qzoneList = mountOneTool(ctx, makeListQzoneTool(admitImages))
+  const qzoneDetail = mountOneTool(ctx, makeGetQzonePostTool(admitImages))
+  const qzoneSend = mountOneTool(ctx, makeSendQzonePostTool())
+  const qzoneManage = mountOneTool(ctx, makeManageQzoneTool())
   startMentionPolling(ctx)
   startPokeWatcher(ctx)
   startPrivateWatcher(ctx, admitImages)
+  startFriendRequestWatcher(ctx)
   return {
-    tools: [list, history, members, send, face, faceList, faceFav, poke, friends, privateHistory, privateSend],
+    tools: [
+      list, history, members, send, face, faceList, faceFav, poke, avatar,
+      friends, privateHistory, privateSend,
+      friendInfo, friendCategories, friendUpdate, friendDelete, friendLike, friendRequests, friendHandle,
+      qzoneList, qzoneDetail, qzoneSend, qzoneManage,
+    ],
     startObservation,
   }
 }