dsh-qq-tools 0.9.0 → 0.9.2

package/README.md

@@ -9,7 +9,7 @@
 | 列出 QQ 群 | `qq_list_groups` | 群号、群名、人数 |
 | 看群聊天记录 | `qq_get_group_history` | 最近消息 + 图片，只读；消息带 `#message_id` |
 | 看群成员 | `qq_get_group_members` | 昵称、群名片、QQ 号、身份 |
-| 发群消息 | `qq_send_group_message` | 发群消息；同时负责 @ 提醒和群后续轮询 |
+| 发群消息 | `qq_send_group_message` | 发群消息，可引用消息、@人、@全体；同时负责 @ 提醒和群后续轮询 |
 | 发表情 | `qq_send_face` | 在群里或私聊里发系统表情或 QQ 收藏夹里的自定义表情，可带一句话 |
 | 收藏表情 | `qq_list_faces` / `qq_favorite_face` | 看/管理 QQ 账号收藏夹（SnowLuma）：收藏图片、取消收藏、改备注、移到最前 |
 | 私聊 | `qq_list_friends` / `qq_get_private_history` / `qq_send_private_message` | 好友列表、私聊记录、发私聊消息；同时负责私聊消息唤醒 |
@@ -102,12 +102,22 @@ test/smoke.mjs                   离线冒烟测试：假 OneBot HTTP 服务 +
 
 这些自定义表情接口是 SnowLuma 扩展，NapCat 没有。用 NapCat 时系统表情照常能发，收藏表情工具会提示接口不可用。
 
+## 群消息：引用和 @
+
+`qq_send_group_message` 除了 `group_id` 和 `message`，还支持：
+
+- `reply_to`：消息前面的 `#编号`，引用那条消息；
+- `at_user_ids`：QQ 号数组，@ 这些人；
+- `at_all`：`true` 表示 @全体成员（这时 `at_user_ids` 会被忽略）。
+
+`message` 可以只写文字，也可以留空只发 @；引用和 @ 可以同时用。群 @ 提醒和群后续里的每条消息是 `昵称(QQ号)：内容（消息 #编号）`，可以直接把 `#编号` 传给 `reply_to`，把里面括号中的 QQ 号传给 `at_user_ids`。戳一戳和私聊唤醒也是 `昵称(QQ号)` 的形式。
+
 ## 私聊
 
 私聊和群聊在程序里是分开的两条路径：群聊靠轮询 @，私聊靠 WebSocket 的 `message_type=private` 事件。私聊没有观察窗，每收到一条私聊消息都会直接唤醒目标会话。
 
-- 唤醒提示里会带发送者昵称、QQ 号、`message_id` 和文字；如果消息里有图片，也会把图片一起给模型看（有 sharp 时 GIF 会拆成首/中/尾最多 3 帧；没有 sharp 时交给 DSH 显示首帧，和群聊记录的处理一致）。
-- 模型用 `qq_get_private_history` 看和对方的最近记录，用 `qq_send_private_message` 回文字，用 `qq_send_face` 回表情。
+- 唤醒提示里的消息行是 `昵称(QQ号)：内容（消息 #编号）`；如果消息里有图片，也会把图片一起给模型看（有 sharp 时 GIF 会拆成首/中/尾最多 3 帧；没有 sharp 时交给 DSH 显示首帧，和群聊记录的处理一致）。
+- 模型用 `qq_get_private_history` 看和对方的最近记录，用 `qq_send_private_message` 回文字（传 `reply_to=#编号` 可以引用），用 `qq_send_face` 回表情。
 - `qq_list_friends` 列好友，可以按昵称、备注或 QQ 号搜；`privateUsers` 非空时只列白名单里的好友。
 - `qq_get_private_history` 的消息带 `#message_id`，可以传给 `qq_send_private_message` / `qq_send_face` 的 `reply_to` 做引用回复。
 - 私聊唤醒的 `source.kind` 是 `qq-private`，和群聊的 `qq-mention` / `qq-followup` / `qq-poke` 区分开。
@@ -179,7 +189,7 @@ dsh plugin --profile <profile> add dsh-qq-tools
 需要固定版本时：
 
 ```sh
-dsh plugin --profile <profile> add dsh-qq-tools@0.9.0
+dsh plugin --profile <profile> add dsh-qq-tools@0.9.2
 ```
 
 ### 本地开发 / 自己改代码
@@ -192,7 +202,7 @@ dsh plugin --profile <profile> add link:/path/to/dsh-qq-tools
 
 ```sh
 pnpm pack
-dsh plugin --profile <profile> add ./dsh-qq-tools-0.9.0.tgz
+dsh plugin --profile <profile> add ./dsh-qq-tools-0.9.2.tgz
 ```
 
 `dsh plugin` 会在安装后自动把这个包追加进 profile 的 `dsh.profile.bundles`，不用手改 `package.json`。卸载用：
@@ -201,6 +211,14 @@ dsh plugin --profile <profile> add ./dsh-qq-tools-0.9.0.tgz
 dsh plugin --profile <profile> remove dsh-qq-tools
 ```
 
+## 兼容性、权限与商城状态
+
+Node.js 要求为 `>=22`，DSH 支持范围为 `0.2.x`，与原有依赖说明一致。机器可读版本范围声明位于 `package.json` 的 `dsh.compatibility`。
+
+本次声明依据、已获得的安装证据及未验证项见 [整改记录](docs/verification/README.md)。用户已自行测试现有功能；本次不重复功能测试，也不将手工使用情况冒充完整的商城生命周期验收。
+
+本插件需要文件、网络和 OneBot token 权限。配置/诊断日志、本地图片读取、外部服务、账号写操作及失败边界详见 [SECURITY.md](SECURITY.md)。这些能力是 QQ 桥接的实际需要；补齐声明和验收证据不保证 DSH STORE 自动批准，商城可能仍要求 `user-reviewed` 专项审阅或保持 `blocked`。本仓库的验收记录不构成独立安全审计。
+
 ## 依赖
 
 - DSH 0.2.x（cordis 插件体系）
@@ -212,4 +230,4 @@ dsh plugin --profile <profile> remove dsh-qq-tools
 
 ---
 
-版本：0.9.0
+版本：0.9.2

package/lib/shared.js

@@ -442,6 +442,14 @@ function senderId(m) {
   return clean(s.user_id || (m && m.user_id) || '')
 }
 
+// 唤醒提示里的消息行：和戳一戳一致，固定带上昵称和 QQ 号。
+// 有 message_id 时附在末尾，模型可以把它传给 reply_to 做引用。
+export function formatIncomingLine(name, userId, text, messageId) {
+  const who = clean(name) || 'QQ'
+  const qq = String(userId || '?')
+  return `${who}(${qq})：${text || '（空）'}` + (messageId != null ? `（消息 #${messageId}）` : '')
+}
+
 
 function renderTool(_args, v) {
   if (!v || !v.ok) return [{ type: 'text', text: 'QQ 工具失败：' + String((v && v.error) || '未知错误') }]
@@ -917,15 +925,19 @@ export function makeSendTool(onSent) {
     name: 'qq_send_group_message',
     description:
       '在指定群里发一条消息。发之前先确认群号；只发到允许的群。' +
+      'reply_to 传消息前面的 #编号 可以引用那条消息；at_user_ids 传 QQ 号可以 @ 人，at_all=true 是 @全体成员。' +
       '普通闲聊不要用 Markdown；一句话短一点，像群友随手打的。' +
       '不想说话就不要调用这个工具；调用后不要再重复说自己发了什么。',
     parameters: {
       type: 'object',
       properties: {
         group_id: { type: 'number', description: '群号' },
-        message: { type: 'string', description: '要发到群里的文字，不要 Markdown' },
+        message: { type: 'string', description: '要发到群里的文字；只 @ 不说话时可以留空' },
+        reply_to: { type: 'string', description: '要引用的消息 ID（消息前面的 #编号），可选' },
+        at_user_ids: { type: 'array', items: { type: 'number' }, description: '要 @ 的 QQ 号列表，可选' },
+        at_all: { type: 'boolean', description: 'true = @全体成员，可选' },
       },
-      required: ['group_id', 'message'],
+      required: ['group_id'],
       additionalProperties: false,
     },
     output: { schema: { type: 'object', additionalProperties: true }, render: renderTool },
@@ -933,24 +945,42 @@ export function makeSendTool(onSent) {
       const cfg = loadCfg()
       const groupId = Number(args && args.group_id)
       const text = String((args && args.message) || '').trim()
+      const atIds = [...new Set(
+        (Array.isArray(args && args.at_user_ids) ? args.at_user_ids : [])
+          .map((x) => Number(x)).filter((x) => Number.isInteger(x) && x > 0),
+      )].slice(0, 20)
+      const atAll = args && args.at_all === true
       if (!Number.isFinite(groupId)) return { ok: false, error: 'group_id 不是有效群号' }
-      if (!text) return { ok: false, error: '消息是空的' }
+      if (!text && !atIds.length && !atAll) return { ok: false, error: '消息是空的' }
       if (!allowedGroup(groupId, cfg)) return { ok: false, error: '这个群不在允许列表里' }
       try {
-        const data = await onebot(
-          'send_group_msg',
-          { group_id: groupId, message: [{ type: 'text', data: { text: text.slice(0, 1000) } }] },
-          cfg,
-        )
+        const message = []
+        const replyTo = args && args.reply_to
+        if (replyTo != null && replyTo !== '') message.push({ type: 'reply', data: { id: String(replyTo) } })
+        if (atAll) message.push({ type: 'at', data: { qq: 'all' } })
+        else for (const qq of atIds) message.push({ type: 'at', data: { qq: String(qq) } })
+        if (text) message.push({ type: 'text', data: { text: text.slice(0, 1000) } })
+        const data = await onebot('send_group_msg', { group_id: groupId, message }, cfg)
         try { if (typeof onSent === 'function') onSent(groupId, '发群消息') } catch (error) {}
-        return { ok: true, group_id: groupId, message_id: data && data.message_id }
+        return {
+          ok: true,
+          group_id: groupId,
+          message_id: data && data.message_id,
+          reply_to: replyTo != null && replyTo !== '' ? String(replyTo) : '',
+          at_user_ids: atAll ? [] : atIds,
+          at_all: atAll,
+        }
       } 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: `已发到群 ${v.group_id}（消息 ${v.message_id || '?'}）。` }]
+      const extra = []
+      if (v.reply_to) extra.push('引用了 #' + v.reply_to)
+      if (v.at_all) extra.push('@全体成员')
+      else if (Array.isArray(v.at_user_ids) && v.at_user_ids.length) extra.push('@了 ' + v.at_user_ids.join('、'))
+      return [{ type: 'text', text: `已发到群 ${v.group_id}（消息 ${v.message_id || '?'}${extra.length ? '，' + extra.join('，') : ''}）。` }]
     },
   }
 }
@@ -1096,6 +1126,7 @@ export function makeSendPrivateTool() {
     name: 'qq_send_private_message',
     description:
       '给某个 QQ 好友发一条私聊消息。user_id 从 qq_list_friends 或私聊唤醒提示里拿。' +
+      'reply_to 传消息前面的 #编号 可以引用那条消息。' +
       '普通闲聊不要用 Markdown；一句话短一点，像聊天一样。' +
       '不想说话就不要调用；调用后不要再重复说自己发了什么。',
     parameters: {
@@ -1103,7 +1134,7 @@ export function makeSendPrivateTool() {
       properties: {
         user_id: { type: 'number', description: '对方的 QQ 号' },
         message: { type: 'string', description: '要发的文字，不要 Markdown' },
-        reply_to: { type: 'string', description: '要回复的消息 ID，可选' },
+        reply_to: { type: 'string', description: '要引用的消息 ID（消息前面的 #编号），可选' },
         group_id: { type: 'number', description: '临时会话的来源群号，可选；普通好友私聊不用传' },
       },
       required: ['user_id', 'message'],
@@ -1126,14 +1157,20 @@ export function makeSendPrivateTool() {
         const body = { user_id: userId, message }
         if (groupId) body.group_id = groupId
         const data = await onebot('send_private_msg', body, cfg)
-        return { ok: true, user_id: userId, message_id: data && data.message_id }
+        return {
+          ok: true,
+          user_id: userId,
+          message_id: data && data.message_id,
+          reply_to: replyTo != null && replyTo !== '' ? String(replyTo) : '',
+        }
       } 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.message_id || '?'}）。` }]
+      const quote = v.reply_to ? '，引用了 #' + v.reply_to : ''
+      return [{ type: 'text', text: `已发给 QQ ${v.user_id}（消息 ${v.message_id || '?'}${quote}）。` }]
     },
   }
 }
@@ -2959,13 +2996,30 @@ async function pollMentions(ctx) {
         )
         const text = segText(segs) || '（没有文字）'
         const name = clean((m.sender && (m.sender.card || m.sender.nickname)) || String(uid))
+        const senderQQ = String(uid || (m.sender && m.sender.user_id) || '?')
         const winUntil = windows.get(String(gid)) || 0
         if (Date.now() < winUntil) {
           const arr = followups.get(String(gid)) || []
-          arr.push({ gid: String(gid), group: names.get(String(gid)) || String(gid), sender: name, text, time: t })
+          arr.push({
+            gid: String(gid),
+            group: names.get(String(gid)) || String(gid),
+            sender: name,
+            user_id: senderQQ,
+            message_id: mid,
+            text,
+            time: t,
+          })
           followups.set(String(gid), arr)
         } else if (atMe) {
-          mentions.push({ gid: String(gid), group: names.get(String(gid)) || String(gid), sender: name, text, time: t })
+          mentions.push({
+            gid: String(gid),
+            group: names.get(String(gid)) || String(gid),
+            sender: name,
+            user_id: senderQQ,
+            message_id: mid,
+            text,
+            time: t,
+          })
         }
       }
       lastSeen.set(String(gid), maxTime)
@@ -2973,15 +3027,19 @@ async function pollMentions(ctx) {
     if (seen.size > 500) seen.clear()
     for (const [gid, until] of windows) if (Date.now() >= until) windows.delete(gid)
     if (!mentions.length && followups.size === 0) return
-    const lines = mentions.slice(-5).map((x) => `群「${x.group}」${x.sender}：${x.text}`)
+    const fmtLine = (x) => formatIncomingLine(x.sender, x.user_id, x.text, x.message_id)
+    const lines = mentions.slice(-5).map((x) => `群「${x.group}」${fmtLine(x)}`)
     const sendTools = []
     if (hasActiveTool('qq_send_group_message')) sendTools.push('qq_send_group_message')
     if (hasActiveTool('qq_send_face')) sendTools.push('qq_send_face')
     const sendHint = sendTools.length ? '想说话可以用 ' + sendTools.join(' / ') + ' 回复；' : ''
+    const quoteHint = hasActiveTool('qq_send_group_message')
+      ? '想引用某条消息就传 reply_to=消息编号；想 @ 人就传 at_user_ids=[QQ号]，@全体传 at_all=true；'
+      : ''
     const prompt =
       '【群聊 @ 提醒】有人 @ 了你：\n' +
       lines.join('\n') +
-      '\n' + lookHint() + '再决定要不要回复、回哪个群。' + sendHint + '不想说话就安静待着；' +
+      '\n' + lookHint() + '再决定要不要回复、回哪个群。' + sendHint + quoteHint + '不想说话就安静待着；' +
       '不要用 Markdown，不要提工具和私聊内容，短一点。'
     const message = {
       id: randomUUID(),
@@ -2995,12 +3053,12 @@ async function pollMentions(ctx) {
     }
     for (const [gid, list] of followups) {
       const group = list[0] && list[0].group ? list[0].group : gid
-      const lines2 = list.slice(-10).map((x) => `${x.sender}：${x.text}`)
+      const lines2 = list.slice(-10).map(fmtLine)
       const prompt2 =
         '【群聊后续】你刚才在群「' + group + '」里说过话，现在又有人说话：\n' +
         lines2.join('\n') +
         '\n想接就接；' +
-        (hasActiveTool('qq_send_group_message') ? '想说话用 qq_send_group_message 发到这个群；' : '') +
+        (hasActiveTool('qq_send_group_message') ? '想说话用 qq_send_group_message 发到这个群，引用某条传 reply_to=消息编号，@人传 at_user_ids=[QQ号]，@全体传 at_all=true；' : '') +
         (hasActiveTool('qq_send_face') ? '想回表情用 qq_send_face；' : '') +
         '不想接就安静待着。不要用 Markdown，短一点。'
       await agent.followup({
@@ -3127,20 +3185,20 @@ async function handlePrivateMessage(ctx, ev, admitImages) {
   const segs = Array.isArray(ev.message) ? ev.message : []
   const text = segText(segs) || clean(ev.raw_message) || '（没有文字）'
   const groupId = ev.group_id ? String(ev.group_id) : ''
+  const midHint = ev.message_id != null ? '，引用传 reply_to=' + ev.message_id : ''
   const actions = []
   if (hasActiveTool('qq_get_private_history')) {
     actions.push('想看上下文用 qq_get_private_history（user_id=' + userId + '）')
   }
   if (hasActiveTool('qq_send_private_message')) {
-    actions.push('想回就用 qq_send_private_message（user_id=' + userId + (groupId ? ', group_id=' + groupId : '') + '）')
+    actions.push('想回就用 qq_send_private_message（user_id=' + userId + (groupId ? ', group_id=' + groupId : '') + midHint + '）')
   }
   if (hasActiveTool('qq_send_face')) {
-    actions.push('想回表情用 qq_send_face（user_id=' + userId + (groupId ? ', group_id=' + groupId : '') + '）')
+    actions.push('想回表情用 qq_send_face（user_id=' + userId + (groupId ? ', group_id=' + groupId : '') + midHint + '）')
   }
   const where = groupId ? '群 ' + groupId + ' 的临时会话' : '私聊'
   const prompt =
-    '【QQ ' + where + '】' + name + '(' + userId + ') 给你发消息：\n' + text +
-    (ev.message_id != null ? '\n（消息 #' + ev.message_id + '）' : '') +
+    '【QQ ' + where + '】' + formatIncomingLine(name, userId, text, ev.message_id) +
     '\n' + (actions.length ? actions.join('；') + '。' : '') +
     '不想回就安静待着；不要用 Markdown，不要提工具，短一点。'
   const content = [{ type: 'text', text: prompt }]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-qq-tools",
-  "version": "0.9.0",
-  "description": "给大肥鱼会话用的 QQ 群/私聊工具：列群、看群记录、发群消息、发表情、收藏表情（SnowLuma 收藏夹）、好友/私聊记录、发私聊消息、私聊唤醒、群成员、戳一戳感知/戳回去、更改头像、好友管理（资料/备注/分组/删好友/名片赞/好友申请）、QQ 空间说说（列表/详情/发表/评论/点赞/权限）、挂载会话选择。11 个工具组加 1 个设置组件，可在插件页逐个开关。",
+  "version": "0.9.2",
+  "description": "给大肥鱼会话用的 QQ 群/私聊工具：列群、看群记录、发群消息（可引用/@）、发表情、收藏表情（SnowLuma 收藏夹）、好友/私聊记录、发私聊消息、私聊唤醒、群成员、戳一戳感知/戳回去、更改头像、好友管理（资料/备注/分组/删好友/名片赞/好友申请）、QQ 空间说说（列表/详情/发表/评论/点赞/权限）、挂载会话选择。11 个工具组加 1 个设置组件，可在插件页逐个开关。",
   "type": "module",
   "main": "lib/index.js",
   "license": "MIT",
@@ -29,6 +29,8 @@
     "locale",
     "cordis.patch.yml",
     "README.md",
+    "SECURITY.md",
+    "docs/verification",
     "LICENSE"
   ],
   "engines": {
@@ -78,6 +80,10 @@
     "./package.json": "./package.json"
   },
   "dsh": {
+    "compatibility": {
+      "dsh": "0.2.x",
+      "node": ">=22"
+    },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },

package/tools/qq-send-group-message/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Send group message",
-    "description": "Send a message to a QQ group; also polls @ mentions and follow-up chatter."
+    "description": "Send group messages with quotes, @mentions and @all; also polls @ mentions and follow-up chatter."
   }
 }

package/tools/qq-send-group-message/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "发群消息",
-    "description": "在指定的 QQ 群里发一条消息；也负责 @ 提醒和群后续的轮询。"
+    "description": "在指定的 QQ 群里发消息，可引用消息、@人和 @全体；也负责 @ 提醒和群后续的轮询。"
   }
 }