前言¶
DeepSeek Harness（DSH）支持通过 QQ 频道作为远程入口，上游 dsh-qq-plugin 提供了私聊遥控、扫码绑定、多会话、附件与审批回流等能力。但原插件没有群聊支持，在 QQ 群里只能被动接收消息，无法主动应答或参与群内讨论。
dsh-qq-plugin-group-expand 是对上游项目的扩展分支，补上了群聊收发、群聊礼仪、引用图片、表情包收藏、权限默认值与 token 优化。项目基于官方 QQ 机器人平台，不需要个人号协议，也不依赖公网 IP。
插件定位¶
- 包名：
dsh-qq-plugin-group-expand - 版本：1.2.0
- 运行环境：DSH desktop 0.2.0-rc.2 或更新
- QQ 侧：腾讯官方机器人，通过手机 QQ 扫码创建
核心能力¶
与上游的关系¶
上游 dsh-qq-plugin 提供的能力在 dsh-qq-plugin-group-expand 中全部继承：
- 私聊遥控、扫码绑定、多会话（
/new/list/switch） - 图片 / 文件 / 语音双向
- 权限审批回流、
notify_qq主动推送 - 语音优先使用 QQ 服务端 ASR 转写
本分支新增的能力：
- 群聊收发：支持在 QQ 群里与 agent 交互
- 群聊礼仪与门禁：只在特定条件（被 @、提到人格名或关键词）下发言
- 连续对话窗口：被 @ 后 5 分钟内，每条文字消息都交给 agent 判断是否回应
- 引用图片：下载引用消息中的图片到本地，把绝对路径交给 agent
- 表情包收藏：自动收集群里的方形小图，支持用户导入，最多 300 张
- 权限默认值：新会话默认
read-only，强制锁定只读 - Token 优化：
presenceNote（渠道上下文说明）只在每个新对话的第一条提示词里发送一次
安装¶
从 npm 安装（推荐）¶
dsh plugin --profile desktop add dsh-qq-plugin-group-expand
也可以在 DSH 的「添加插件」里直接输入包名：
dsh-qq-plugin-group-expand
从 GitHub 安装¶
dsh plugin --profile web add https://github.com/jjjjjsgrmjjjjj/dsh-qq-plugin-group-expand
或者把 Git 地址粘进「添加插件」。
从本地目录 / tarball¶
npm pack
生成 dsh-qq-plugin-group-expand-1.2.0.tgz 后，把 .tgz 的绝对路径或放着 package.json 的目录粘进「添加插件」。
从旧插件迁移¶
- 先在 DSH 里停用并移除原来的
dsh-qq-plugin，否则两个插件会抢同一个 QQ 通道和qqChannel服务 - 安装
dsh-qq-plugin-group-expand - 凭据作用域沿用上游的
dsh-qq-plugin，已绑定过的 AppSecret 可以直接复用 - 状态文件仍是
~/.dsh/qq/state.json，会话映射、待发队列和设置会继续生效 - 启动后检查设置页的连接状态和
boot.log
群聊行为与礼仪¶
群聊和私聊的礼貌规则不同。本分支默认只在以下情况发言：
| 条件 | 行为 |
|---|---|
| 被 @ | 立即交给 agent，正常回答 |
| 被 @ 后 5 分钟内 | 每条文字消息都交给 agent，由模型判断是否回应 |
| 正文提到人格名或接话关键词 | 本地短句 + 表情包接一句，不调用模型 |
| 其他 | 不发言 |
被 @ 后会开启一个 5 分钟的连续对话窗口。窗口内不按关键词过滤：消息会原样交给 agent，并在提示词里附上最近 8 条群消息（发送者 + 正文，单条截断 120 字）。如果 agent 输出 [[NO_REPLY]]，插件会把整条回复丢弃，群里一个字都不发。
表情包与引用图片¶
表情包¶
不生成表情包，只用两种来源：
- 群里像表情包的方形小图，收到时静默下载到
~/.dsh/qq/stickers/collected/ - 用户自己导入到
~/.dsh/qq/stickers/根目录的png/jpg/gif/webp
收藏判定条件：
- 最长边 ≤ 1024
- 宽高比 0.45–2.2
- 文件 ≤ 2 MiB
- SHA-256 去重
- 最多 300 张
索引写 index.json。手机照片和截图会被排除。发送失败或目录为空时退到 emoji，不影响文字回复。
引用图片¶
QQ 把被引消息的图片放在 msg_elements[<refMsgIdx>].attachments。本分支会把引用附件下载到会话媒体目录，把本地绝对路径交给 agent，而不是只写一句「（引用了 image/png）」。
权限与安全¶
新会话默认 read-only：
permissionPreset默认值改为read-onlynewSessionsReadOnly默认开启，新建/采纳的会话会被强制施加只读，即使状态文件里存着旧的danger-full-access- 已有会话的权限由 DSH 锁定，插件不会偷偷改
要让某条新会话动手，需要先关闭只读锁，再选择「工作区可写」或「完全访问」。这是有意的摩擦：群里任何人都能触发它，默认不能写文件。
配置¶
设置项与上游一致，群聊新增字段主要在 lib/settings.js：
| 设置 | 默认 | 说明 |
|---|---|---|
groupChatEnabled |
true |
群聊总开关 |
groupPersonaNames |
鲸鱼娘 |
群里认的人格名，逗号分隔 |
groupAutoSpeak |
true |
提到人格/关键词时自动接话 |
groupFollowUpWindowMs |
300000 |
被 @ 后的连续对话窗口（5 分钟） |
groupContextWindowMs |
120000 |
群历史语境窗口 |
groupAutoSpeakKeywords |
鲸鱼娘,鱼鱼,胖鱼,在吗,哈哈,笑死,可爱,笨蛋 |
接话关键词 |
groupSpeakCooldownMs |
20000 |
自动接话冷却 |
groupSpeakMaxPerHour |
20 |
自动接话每小时上限 |
groupCollectStickers |
true |
收藏群里的表情包 |
groupStickerChance |
70 |
接话时附带表情包的概率 |
groupStickerDir |
<home>/qq/stickers |
表情包目录 |
groupFullMessageMode |
未启用 | 平台推送全量群消息时才有的分支 |
permissionPreset |
read-only |
新会话权限预设 |
newSessionsReadOnly |
true |
新会话强制只读锁 |
完整说明见 docs/HANDBOOK-USER.md 和设置页内置帮助。
适用场景与注意¶
适合需要通过 QQ 群与 DSH 智能体交互的场景，例如：
- 群内日常问答与协作
- 群聊中的任务审批与决策
- 通过群聊分享图片、文件与语音
注意：
- 插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证
- 官方通道下，非 @ 的群消息默认不可见；需要平台权限，插件无法绕过
sendTyping仅支持单聊，群聊里会记录一条非致命错误- 群历史在内存中，DSH 重启后从零开始
- 表情包只支持图片，不支持群里的动态表情协议
结尾¶
dsh-qq-plugin-group-expand 在上游 dsh-qq-plugin 的基础上补齐了群聊能力，通过官方 QQ 机器人平台提供了更安全的默认权限和 token 优化，适合需要在 QQ 群里远程控制 DSH 的场景。
- 目录页：https://www.skillhub.cn/plugins/jjjjjsgrmjjjjj/dsh-qq-plugin-group-expand
- GitHub：https://github.com/jjjjjsgrmjjjjj/dsh-qq-plugin-group-expand
