前言¶

在 DSH（DeepSeek Harness）里跑智能体时，如果希望模型能读 QQ 群消息、在 @ 你时继续对话、或处理私聊与戳一戳，通常需要自己写 OneBot 客户端、把事件转成唤醒、再把工具挂到指定会话。维护成本高，且群聊轮询、WebSocket 事件、白名单往往要单独实现。

dsh-qq-tools 是社区维护的 DSH 插件，通过 OneBot 11 的 HTTP 与 WebSocket 对接 NapCat 或 SnowLuma，把列群、看记录、发消息、表情、私聊、好友与 QQ 空间等能力拆成 11 个可单独开关的工具组，并提供一个「挂载会话」设置项，指定 QQ 消息唤醒哪一个 DSH 会话。下面介绍它的定位、能力与安装配置方式。

这是什么¶

• 名称：dsh-qq-tools（GitHub：cyhddyx/dsh-qq-tools，维护者 cyhddyx）
• 分类：联网工具（DSH 社区目录：skillhub 插件页）
• 协议：OneBot 11 HTTP + WebSocket；系统表情在 SnowLuma / NapCat 上均可发送；收藏表情、改头像、好友管理与 QQ 空间走 SnowLuma 扩展接口，与 QQ 客户端侧数据同源
• 运行环境：纯 JavaScript 插件，package.json 要求 Node >=22，许可证 MIT（当前 npm 版本 0.9.0）

插件面向「大肥鱼」类 DSH 会话：工具只注册在你选中的那一个会话上，其他会话看不到 QQ 工具，也不会被 QQ 消息唤醒。

组件与工具一览¶

11 个工具组各自是独立的 cordis 组件，另加「挂载会话」设置组件；在 DSH 插件页的「包含的组件」里可逐个开关。

关闭「发群消息」会同时停止 @ 轮询；关闭「私聊」会停止私聊唤醒；关闭「戳一戳」会停止戳一戳通知；关闭「好友管理」会停止好友申请收件箱的 WebSocket 监听（插件重启后，运行期间未处理的普通申请会丢失）。只读类组件互不影响。关闭「挂载会话」仅让配置页不可用，已写入的 targetSession 仍生效。

安装与启用¶

DSH 用 dsh plugin 安装。<profile> 换成你启动 DSH 时用的 profile（桌面端常见 desktop，Web 端常见 web，也可以是 tui 或自定义名）。

从 GitHub 安装：

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

从 npm 安装（README 标注为推荐）：

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

固定版本示例（与当前发布一致）：

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

本插件无构建步骤，不需要 prepare 或 pnpm allowBuilds。安装后重启 DSH，在插件页应能看到上述组件及各自开关。

挂载会话与配置文件¶

先做 OneBot 侧（NapCat / SnowLuma）HTTP 与 WebSocket 就绪，再在 DSH 里选会话。

1. 左侧栏打开「挂载会话」，或进入「插件 → dsh-qq-tools → 挂载会话 → 配置」。
2. 列表展示当前 DSH 会话（标题、短 ID、运行状态）；选中后保存，写入 ~/.dsh/qq-tools-config.json 的 targetSession，各组件约 3 秒内重新挂到该会话。
3. 选「不挂载」或留空会卸下所有工具并停止唤醒。归档会话与子会话不出现在列表中。

首次启动会自动创建配置文件，字段含义如下（节选）：

{
  "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 / NapCat 默认多为 http://127.0.0.1:3000）。
• wsUrl：WebSocket 事件地址（默认 ws://127.0.0.1:3001）。
• groups：允许查看/发送的群；空数组表示不限制。
• privateUsers：私聊唤醒与部分私聊相关工具的 QQ 白名单；空数组不限制。好友申请处理不受此限。
• mentionEnabled / pokeEnabled / privateEnabled：与对应组件及 @ 轮询、戳一戳、私聊唤醒联动。

也可直接编辑 targetSession，无需经过配置页；关掉「挂载会话」组件后接口不可用，但文件里的值仍然有效。

典型用法路径¶

群聊：读记录、回复、被 @ 唤醒¶

1. 用 qq_list_groups 确认群号，必要时在 groups 里限制范围。
2. qq_get_group_history 拉最近记录（默认条数由 historyCount 等控制），消息中的 #编号 即 message_id，可用于 qq_send_group_message 或 qq_send_face 的 reply_to。
3. qq_send_group_message 发文字；需要表情时用 qq_send_face（系统表情传 face_id，收藏表情传 emoji_id，群聊传 group_id）。
4. 开启「发群消息」且 mentionEnabled 为 true 时，群 @ 会轮询唤醒目标会话；后续同群对话可走 qq-followup 类来源（与 qq-mention 区分）。

私聊：记录、回复、WebSocket 唤醒¶

私聊与群聊分开：私聊靠 WebSocket message_type=private 事件，每条私聊可直接唤醒目标会话（source.kind 为 qq-private）。

1. qq_list_friends 列好友（privateUsers 非空时只列白名单内好友）。
2. qq_get_private_history 看最近对话，再用 qq_send_private_message 或 qq_send_face（私聊传 user_id）回复。

SnowLuma 扩展能力¶

收藏表情、改头像、好友管理、QQ 空间依赖 SnowLuma 扩展 HTTP 接口；NapCat 上系统表情仍可发，但收藏表情等工具会提示接口不可用。部署前确认你用的 OneBot 实现是否覆盖所需接口。

表情与空间发图支持 http(s) 链接、base64://、本机路径（由 SnowLuma 服务端读取）或从聊天记录用 message_id + 索引取图；与 qq_favorite_face、qq_set_avatar、qq_send_qzone_post 文档描述一致。

适用场景与注意¶

适合：已在本地或内网跑 OneBot 11（NapCat 或 SnowLuma），希望把 QQ 群 @、私聊、戳一戳接到某一个 DSH 会话，并让模型通过工具读群/私聊、回消息、管理 SnowLuma 支持的账号能力。

务必注意：

• 插件以当前 DSH 进程的权限运行；安装前请阅读 GitHub 仓库 源码与 MIT 许可证，并自行评估账号与数据风险。
• qq_delete_friend、删除说说等操作不可撤销，工具要求显式 confirm=true 等参数；删好友还可选 block 同时屏蔽。
• 好友申请收件箱仅覆盖插件运行期间收到的普通申请及 SnowLuma 可疑申请接口；更早的申请需在 QQ 客户端处理。
• DSH 社区目录（skillhub）为独立站点，与 DeepSeek / 幻方无官方从属关系；插件星标与版本以仓库与 npm 为准。

结尾¶

dsh-qq-tools 把 OneBot 11 上的 QQ 群聊、私聊与 SnowLuma 扩展能力拆成可开关的工具组，并通过 targetSession 把唤醒和工具集中到一个 DSH 会话。安装命令见上文；细节以 README 为准。

• 目录页：https://www.skillhub.cn/plugins/cyhddyx/dsh-qq-tools
• GitHub：https://github.com/cyhddyx/dsh-qq-tools