QQ群友 lilith1257/dsh-plugin-qq-groupmate

dsh-plugin-qq-groupmate

仅自用：个人自用项目，按需更新，不承诺兼容性与技术支持。感谢ds老师。

让 DeepSeek Harness 里的 AI 以普通群友的身份住进 QQ 群。

通过 OneBot 11 接协议端，用角色卡定义人设，每个群可以独立切换角色与模型；所有配置都在 dsh 设置页的插件卡片里改，改完即时生效，不用重启。

功能

- OneBot 11 接入：正向 / 反向 WebSocket 都支持，NapCat、SnowLuma、LLOneBot、Lagrange、go-cqhttp 等协议端均可
- 角色卡：人设、性格、说话风格、示例对话；兼容 SillyTavern V2 卡片，也支持一份 JSON 里的原生格式
- 按群独立配置：每个群单独指定角色、模型、触发规则、上下文长度，和 dsh 主会话互不干扰
- 触发控制：被 @ / 关键词前缀 / 概率接话，带冷却；私聊也响应
- 上下文与记忆：多轮上下文 + 长期记忆压缩，群里的印象能沉淀下来
- 命令系统：.help、角色切换、印象管理、提醒、贴纸、天气、塔罗等，命令前缀可配
- 可选生图：模型输出 [生图:标签] 就画一张发进群（需要自备 Nai2API 兼容服务，见下文）
- 语音回复（可选）：本地 GPT-SoVITS 合成语音发成 QQ 语音，中文 / 日文两套音色各自独立，情绪自动切参考音
- 本机可靠路由：问时间 / 日期 / 星期直接在本机回答，不花模型额度
- 设置页可视化：全部配置都在设置页里改，带开关、下拉、说明文案

安装

前置：dsh 已装好，且 PATH 上有 pnpm（dsh plugin 是一层 pnpm 转发器）。

profile 名按自己用的填：web / desktop / headless
dsh plugin --profile web add github:lilith1257/dsh-plugin-qq-groupmate

装完这个包装声明了 dsh.bundle，dsh 会把它自动并进 profile 的组合层，不需要手改 cordis.patch.yml。重启 dsh 生效。

更新 / 卸载：

dsh plugin --profile web update dsh-plugin-qq-groupmate
dsh plugin --profile web remove dsh-plugin-qq-groupmate

接协议端

默认是反向 WS：插件在本机 127.0.0.1:3001 监听，协议端连进来。

以 NapCat / SnowLuma 为例，在协议端的网络配置里加一个反向 WebSocket：

ws://127.0.0.1:3001

如果要走正向 WS（插件主动连协议端），在设置页把 mode 改成 forward，并填协议端的 WS 地址。

两边都能配 accessToken，填一致即可；留空表示不校验。

配置

设置页 →「插件」→ QQ 群友。几个常改的：

| 配置 | 说明 |
| mode / listenPort / wsUrl | 接入方式与端口 |
| defaultCharacter | 默认角色卡的 id |
| provider / model | 群聊用哪个模型；也可以给单个群单独指定 |
| trigger | 什么时候接话：被 @、前缀、随机概率、冷却、是否响应私聊 |
| context | 上下文轮数与字符上限 |
| groups | 按群覆盖角色与模型 |
| dataDir / charactersDir | 数据目录与角色卡目录 |

角色卡

角色卡是 JSON，放在 /characters/ 下（默认 ~/.dsh/qq-groupmate/characters/），文件名去掉扩展名就是角色 id。

仓库自带一张示例卡 characters/default.json（角色名「小可」）。刚装完数据目录还是空的，插件会先用随包那张兜底；往数据目录里放了自己的卡之后，就只读数据目录。

支持的字段：

{
"name": "小可",
"aliases": ["小可"],
"persona": "你是谁、怎么说话", "personality": "性格", "background": "背景与偏好", "speakingStyle": "说话风格", "scenario": "所处场景", "greeting": "第一句问候",
"exampleDialogues": ["群友: 在吗\n小可: 在的"],
"extraPrompt": "额外规则", "provider": "可选，覆盖模型服务商", "model": "可选，覆盖模型" }

SillyTavern V2 卡片（{"spec":"chara_card_v2","data":{...}}）也能直接丢进去。

生图（可选）

生图默认关。要用的话需要自己准备一个 Nai2API 兼容的出图服务，然后在设置页里填：

- 服务地址（imageGen.baseUrl）：你的出图服务地址，例如 https://your-host
- 密钥（imageGen.token）：该服务的 token

另有一条「网页引擎」路线：用无头浏览器驱动一个线上生图页面，让它自己拼参数出图。要启用得在配置里加上 imageGen.pageUrl（生图页面地址）——留空就等于关闭网页引擎，只走直连接口。

语音（可选）

回复可以顺带发一条 QQ 语音：本地 GPT-SoVITS（api_v2 格式接口）合成，合成失败只影响语音，文字照常发。

- 中文音色：voice.endpoint（默认 http://127.0.0.1:9880/tts），参考音放 voice.refsDir（默认 /voice/refs）
- 日文音色：voice.japaneseEndpoint（默认 http://127.0.0.1:9881/tts），参考音放 voice.japaneseRefsDir
- 语言选择：voice.language = auto（默认，回复里出现假名就走日文音色）/ zh / ja
- 参考音目录留空会自动探测：语音运行时隔壁的 voice（与 voice/jp），也就是 …/data/LilithTextInjector/voice 这种部署结构，装好运行时就能直接用
- 参考音文件名：calm-reference.wav、excited-reference.wav、wronged-reference.wav、sleepy-reference.wav（日文另加 calm-aux-reference.wav）
- 自动拉起：voice.autoStart 打开且端点是本机回环时，插件会按语言各自拉起一次本地服务（先试随包宿主，宿主起不来就改用运行时的 venv 直接跑 api_v2.py，配置按语言选 zh / ja 的 cuda / cpu 配置）
- 情绪 → 语气：按回复内容自动挑参考音（晚安 / 困 → 困倦，被逗 / 开心 → 开心，难过 / 被凶 → 委屈，其余 → 平静）

缓存命中（为什么请求要「前缀稳定」）

上游（DeepSeek 官方、中转站）按请求前缀做上下文缓存：前缀里改一个字，它后面的全部内容都要重新计费。群聊一轮动辄几万 token 的历史，前缀一抖就是整段 miss——后台看到的缓存命中率会趋近于零。

所以提示词被拆成两半：

- 系统提示只放「这个角色 + 这个群不变的东西」（人设、群聊规则、表情包与画图说明、工具箱说明）——同一角色同一群里逐轮逐字节一致，永远排在请求最前面；
- 每轮都会变的运行上下文（长期记忆、知识检索、群友档案、称呼指引、天气、成员列表）单独成块，插在消息序列末尾、当前消息之前。

历史裁剪同样是块状的（一次至少丢 16 条），不是每来一条就滑一格：滑动窗口会让前缀每轮都漂移。

记忆本身也必须有上限：长期记忆按金字塔合并（每 mergeCount 条并成一条，最高层封顶 8 条、每条目标 1200 字，越久远越浓缩），进提示词的部分再受条数与字数预算约束（先放最高层的浓缩记忆，剩下的预算才给最近的细节）——只取最近的会把老记忆的骨架丢掉。

打开调试日志时，每轮会打一条 缓存前缀 system=xxxxxxxx（1250 字）消息=… 条 上下文块=… 字 首条=…：同一角色同一群里 system 指纹应当每轮完全相同，变了就说明有动态内容被塞回了系统提示；「上下文块」的字数应当稳定在几千到一万多，写成几十万就说明某类累积数据又失控了。

数据目录

默认 $DSH_HOME/qq-groupmate（DSH_HOME 没设就是 ~/.dsh）。里面有：

- characters/ 角色卡
- state.json 群配置与运行状态
- qq-groupmate.log 运行日志
- tarot/cards/ 塔罗卡面（没有就用随包那份）
- 记忆、印象、贴纸、语音等子目录

目录结构

lib/ host 半（运行时 JS，Node 直接跑） client.js 浏览器半（设置页卡片） rphub/qq-bridge.js 网页引擎注入用的桥接脚本 characters/ 随包示例角色卡 assets/tarot-cards/ 塔罗卡面 knowledge/ 可选的群内答疑知识库（默认关） cordis.patch.yml 组合包补丁（默认配置）

这个仓库发布的是运行时产物，lib/*.js 就是实际跑的代码，不是压缩过的 bundle，可以直接读、直接改。

许可

MIT。随包的 knowledge/rp-hub-faq.md 是 Roleplay Hub（RP-Hub）1.9.3 的衍生整理，按 CC BY-NC 4.0 授权，详见该文件头部。