dsh-qq-tools

dsh-qq-tools

给 DSH（DeepSeek Harness）里的大肥鱼会话用的 QQ 群/私聊工具，走 OneBot 11 HTTP + WebSocket。系统表情在 SnowLuma / NapCat 上都能发；收藏表情用 SnowLuma 的自定义表情扩展接口，和 QQ 客户端里的收藏夹是同一份数据。

8 个工具各自是一个独立的 cordis 组件，外加一个负责选择挂载会话的设置组件，在 DSH 插件页的「包含的组件」里可以逐个开关：

组件 · 工具 · 说明 列出 QQ 群 · qq_list_groups · 群号、群名、人数 看群聊天记录 · 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_list_friends / qq_get_private_history / qq_send_private_message · 好友列表、私聊记录、发私聊消息；同时负责私聊消息唤醒 戳一戳 · qq_send_poke · 戳人；同时负责接收戳一戳事件 挂载会话 · — · 插件页里的「配置」页面：下拉选择 QQ 消息唤醒哪个 DSH 会话

关掉「发群消息」会同时停掉 @ 提醒轮询，关掉「私聊」会同时停掉私聊消息唤醒，关掉「戳一戳」会同时停掉戳一戳通知；三个只读工具互不影响。关掉「挂载会话」只会让配置页面不可用，已经写进配置的 targetSession 仍然生效。

目录结构

cordis.patch.yml                 9 个组件行
lib/shared.js                    共享核心：配置、OneBot、挂载、@ 轮询、私聊唤醒、戳一戳、表情、观察窗
lib/client.js                    浏览器半侧：插件页里的挂载会话下拉框
lib/index.js                     包根 carrier（承载浏览器半侧和挂载会话接口），也是旧的全量入口
locale/                          包根行在插件页显示的标题和说明
tools/qq-list-groups/            组件入口 + locale
tools/qq-get-group-history/
tools/qq-get-group-members/
tools/qq-send-group-message/
tools/qq-send-face/
tools/qq-favorite-faces/
tools/qq-private-chat/
tools/qq-send-poke/

「挂载会话」用的是包根行（模块名 dsh-qq-tools，所以插件卡片名仍是 dsh-qq-tools）：DSH 只从包根发现 dsh.client，子路径行不会扫描；config.carrier: true 让它只承载设置接口，不会重复挂一遍工具。

每个 tools//index.js 只做一件事：把自己的工具挂到目标会话。locale/{en,zh}.json 提供插件页显示的标题和说明；左侧栏入口和插件行配置页在 lib/client.js 里注册。

选择挂载会话

左侧栏的「挂载会话」入口（也可以在「插件 → dsh-qq-tools → 挂载会话 → 配置」里打开）会列出当前 DSH 里的会话（标题 + 短 ID + 运行状态）。选中后保存，配置写回 ~/.dsh/qq-tools-config.json 的 targetSession，各组件在 3 秒内重新挂到这个会话。

• 归档会话和子会话不会出现在列表里；如果当前目标后来被归档，列表会把它标成「当前目标（已归档）」。
• 工具只注册在选中的会话上，其他会话看不到 QQ 工具，也不会被 QQ 消息唤醒。
• 选「不挂载」或留空会卸下所有工具并停止唤醒。
• 保存时不校验会话是否存活：会话暂时关掉不会把配置清掉，等它重新打开后会自动挂上。
• 这个页面依赖「挂载会话」组件；关掉该组件后接口不可用，但已保存的 targetSession 仍然生效，也可以直接改配置文件。

配置

首次启动会自动创建 ~/.dsh/qq-tools-config.json：

{
  "napCat": "http://127.0.0.1:3000",
  "accessToken": "",
  "targetSession": "",
  "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
}

• napCat 是 OneBot 11 HTTP 地址（SnowLuma 默认 http://127.0.0.1:3000，NapCat 也一样）；wsUrl 是 WebSocket 事件地址（默认 ws://127.0.0.1:3001）。
• targetSession 是目标会话 ID；可以在插件页「挂载会话 → 配置」里下拉选择，也可以直接改这个文件；留空时工具不会挂到任何会话。
• groups 是允许看/发的群；空数组表示不限制。
• mentionEnabled / pokeEnabled / privateEnabled 分别是 @ 轮询、戳一戳事件、私聊唤醒的总闸，对应组件关掉时它们也不会运行。
• privateUsers 是允许唤醒和私聊工具的 QQ 白名单；空数组表示不限制。非空时，不在列表里的私聊消息不会唤醒，qq_list_friends 也不会列出他们。

表情

发表情和收藏表情都走 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_favorite_face：
• file 传 http(s) 链接、base64://、本机路径或 data:image/...，收藏一张新表情；
• message_id + index 直接从聊天消息里的图片收藏（群记录里的 [图片#0] / [表情包#0] 就是索引）；
• emoji_id + remove 取消收藏；
• emoji_id + desc 改备注；
• emoji_id + move_to_front 移到收藏夹最前。
• 聊天记录里的 #编号 是 message_id，可以用 qq_send_face 的 reply_to 回复，也可以配合 qq_favorite_face 收藏消息里的图片。

这些自定义表情接口是 SnowLuma 扩展，NapCat 没有。用 NapCat 时系统表情照常能发，收藏表情工具会提示接口不可用。

私聊

私聊和群聊在程序里是分开的两条路径：群聊靠轮询 @，私聊靠 WebSocket 的 message_type=private 事件。私聊没有观察窗，每收到一条私聊消息都会直接唤醒目标会话。

• 唤醒提示里会带发送者昵称、QQ 号、message_id 和文字；如果消息里有图片，也会把图片一起给模型看（有 sharp 时 GIF 会拆成首/中/尾最多 3 帧；没有 sharp 时交给 DSH 显示首帧，和群聊记录的处理一致）。
• 模型用 qq_get_private_history 看和对方的最近记录，用 qq_send_private_message 回文字，用 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 区分开。

安装

DSH 插件用 dsh plugin 安装。` 换成你启动 DSH 用的 profile 名（桌面端通常是 desktop，Web 端常见 web，也可以是 tui` 或你自己的 profile）。

从 GitHub 安装（现在就能用）

dsh plugin --profile <profile> add github:cyhddyx/dsh-qq-tools

本插件是纯 JavaScript，没有构建步骤，所以不需要 prepare 脚本，也不需要给 pnpm 加 allowBuilds 授权。安装完成后重启 DSH，插件页里应该能看到 8 个组件，每个带开关。

从 npm 安装（推荐）

已发布到 npm，装最新版：

dsh plugin --profile <profile> add dsh-qq-tools

需要固定版本时：

dsh plugin --profile <profile> add dsh-qq-tools@0.8.2

本地开发 / 自己改代码

dsh plugin --profile <profile> add link:/path/to/dsh-qq-tools

离线 tarball

pnpm pack
dsh plugin --profile <profile> add ./dsh-qq-tools-0.8.2.tgz

dsh plugin 会在安装后自动把这个包追加进 profile 的 dsh.profile.bundles，不用手改 package.json。卸载用：

dsh plugin --profile <profile> remove dsh-qq-tools

依赖

• DSH 0.2.x（cordis 插件体系）
• Node.js 22+（内置 fetch / WebSocket）
• SnowLuma 提供 OneBot 11 HTTP 接口和 WebSocket 事件（收藏表情需要 SnowLuma；系统表情 NapCat 也能发）
• 可选：sharp（GIF 拆帧、尺寸被拒时的兜底重编码）。会从 SHARP_PATH、插件自己的 node_modules、DSH 宿主 runtimeDir（桌面版通过 process.argv[2] 传入）等位置自动查找；找不到时 GIF 交给 DSH 显示首帧，大图仍由 DSH 自动归一化（默认单张源图上限 20MiB），图片不会因此丢失。

版本：0.8.2