dsh-qq-bridge

@qqbot/dsh-plugin-qq — QQ ↔ DSH 桥接插件

个人自用项目，顺手传到 GitHub 方便朋友下载。文档里的配置与取舍都是照着 我这一台机器的用法写的，没有做成通用插件，也不保证开箱即用 —— 想拿去玩的话，照着文档慢慢改就行。

把 QQ（通过 OneBot v11，如 NapCat / Lagrange / go-cqhttp）接到 DeepSeek Harness：

• 入站：QQ 私聊或群里 @机器人 的消息 → 交给一个专属的 DSH Agent 会话处理 → 结果自动发回 QQ。
• 出站：任何 DSH Agent（包括 Web UI 里的主会话）都能调用 qq_send_* 主动发消息 / 图片。
• 像群友一样说话：几条消息攒成一轮、回复拆成短气泡、按打字节奏发出、引用 / @ 指向该指的人。
• 它自己的小动作：群里刷同一个字时跟着复读；安静下来后偶尔主动冒个泡； 聊起来之后免 @ 接话、回完再补一句；别人撤回消息时会清掉引用（默认假装没看到）。
• 图片与表情包：能 read_image 真的看图（动图会额外拆一张分镜图，不只看到第一帧）；能发表情包；能把你发的表情存进自己的收藏目录。
• 定时提醒：让它在明早 8 点提醒谁、每周一 @ 谁开会 —— 到点由插件直接发，重启不丢。
• 长期记忆：每句话落盘，每天由独立摘要会话整理成「这个群记得什么」；聊天时按当前消息检索相关条目（含全局人物表与梗），不再只读文件开头，文件满了会滚进 archive/ 而不是删掉。

它能做什么

30 秒开始

1. 装好 DSH，在 Web UI 的 Models 页填一次模型凭据。
2. 拿代码：到 Releases 下载发布包，或者 git clone 本仓库。 Windows 上解压后双击 scripts\napcat-setup.cmd，它会把 NapCat 与插件一起配好。
3. 让 NapCat 开一个 WebSocket 服务器（不是 websocketClients），端口与 endpoint 一致（默认 3001），扫码登录。
4. 起常驻进程：dsh --profile qqbot --port 3081 --no-open（或 deploy/qqbot.service）。
5. 私聊机器人发一句话，它在 QQ 里回你就说明整条链路通了。

想让它像某个具体的人：照写人设：模板与问答走 —— 复制两份模板改四处， 或者让 agent 用 18 道选择题问你一遍，再跑一个自检脚本看看「模型会看到什么」。

改了什么、这个版本有什么，见 CHANGELOG.md。

工作原理

QQ 客户端 ──▶ NapCat ──(OneBot v11 WebSocket)──▶ 本插件
                                                    │
                                    每个会话映射一个 DSH Session
                                                    │
                                    Agent 产出最终回复 ──▶ 发回 QQ

• 一个 QQ 会话（一个私聊对象 / 一个群）= 一个持久化 Session。Session id 由会话 key 经 SHA-256 派生，是确定性的：Harness 重启后同一个人再发消息，插件会 resume 原有会话。 /reset 不改这个算法，只是把「第几轮」也算进摘要（见会话与轮次）。
• Agent 的回复取该 turn 里最后一条有文本的 assistant 消息；中间步骤的工具调用不会发给 QQ。
• 前后脚到的消息先攒一个窗口（batchWindowMs，默认 2 秒）再投给 Agent；回复会拆成几条短消息、 按打字节奏发出，被叫到时按 replyStyle 引用 / @ 该指的人 —— 它自己凑上来的「搭话」不挂任何 指向（见说话方式与节奏）。
• 群消息默认只在被 @ 时触发；私聊 / 群里的「没有正文」消息、复读、主动搭话、 表情包那几条旁路各有自己的闸门，默认值都偏保守（见安全提醒）。

配置

全部配置项在 cordis.patch.yml 的 config: 下（schema 在 config.js，字段上的中文 .description() 就是给用户看的说明），也可以在 Web UI 的 设置 → QQ Bridge 里改。 完整的字段表与设置页说明见 配置项。

⚠️ 不要手写一个只有几个字段的 config: 去覆盖它。 DSH 的 patch 是整块替换、 不是深合并：只写一个 resetUsers 也会把 agentPreset / allowTools / proactive 一起顶掉， QQ 会话会挂上带 shell 的默认预设。改配置走仓库 patch 或 Web UI；每台部署不同的值走环境变量。

常改的几项：

安全（先看这三条）

• QQ 消息是不可信输入：默认 approvalPolicy: never、群消息只在被 @ 时触发。 activeFollow / proactive / privateAfterthought 默认开，是刻意放松了「只在被叫到时说话」， 每一条都有自己的闸门与上限；不放心就关掉。
• qq_save_sticker 是唯一让 QQ 会话按自己给的字节直接写磁盘的工具：只写表情包目录、 文件名洗成单层、同名不覆盖、张数受上限约束。qq_rename_sticker 也能动那个目录，但它只能 给已收藏的文件换个名字（不引入新字节、失败会回滚）。qq_remind_create 也会落盘，但写的是 reminderFile 里由纯函数校验过字段的任务。除此之外 QQ 会话没有 write / edit / bash。
• 会写全局状态的两处：apiKeyRotate 改 $DSH_HOME/.credentials.yaml； linkPreview 默认关（开了等于替群里任何人访问任意 URL）。定时提醒会把「未来要说的话」 写进 data/reminders.json 并在到点发出，所以默认只能提醒自己、@ 别人默认关。 细节与取舍见安全提醒。

文档地图

开发

node --test test/                    # 全部用例
node --test test/settings.test.mjs   # 只跑配置取值口径

改完源码必须重启 Harness（Loader 按 URL 缓存模块，停用 / 启用插件拿不回新代码）。 本机依赖怎么铺、测试覆盖了什么、Windows / 沙箱里的跑法，见 本机开发与测试；代码结构、模块依赖与「改哪里」的索引见 AGENTS.md。

许可

MIT。