前言¶

在 DSH 里跑 Agent，常见入口是 Web UI 或 CLI；要把日常聊天渠道接进来，往往需要自己写转发层、维护会话 id，还要处理群 @、消息攒批和回复节奏。OneBot v11 生态（NapCat、Lagrange、go-cqhttp 等）已经能把 QQ 事件打成统一协议，但和 Harness 的 Session、工具白名单、长期记忆仍要自己对齐。

下面介绍社区插件 flyinstar/dsh-qq-bridge（npm 包名 @qqbot/dsh-plugin-qq，当前版本 0.2.0，MIT 许可）。它把 QQ 经 OneBot 正向 WebSocket 接到 DSH：入站消息驱动专属 Agent 会话，出站可通过 qq_send_* 等工具主动发回 QQ。维护者为 flyinstar；GitHub 仓库约 1 star。作者说明这是个人自用项目，文档按单机用法写，不保证开箱即用，需按文档自行改配置。

这是什么¶

一句话：QQ ↔ DSH 双向桥接插件——每个 QQ 私聊或群对应一个持久化 DSH Session（id 由会话 key 经 SHA-256 确定性派生，重启后 resume），Agent 该轮最后一条有文本的 assistant 回复会发回 QQ，中间工具调用不会直接出现在 QQ 侧。

数据流（摘自官方 README）：

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

配置集中在 cordis.patch.yml 的 config:（schema 在 config.js），也可在 Web UI 设置 → QQ Bridge 修改。注意 DSH 的 patch 是整块替换而非深合并，不要手写只含少量字段的 config: 覆盖整段配置。

核心功能¶

以下能力均来自仓库 README 与文档索引，按模块归纳。

双向聊天与会话¶

• 入站：QQ 私聊，或群里 @ 机器人（默认 groupTrigger: mention）的消息进入对应 Session 处理，结果自动回 QQ。
• 出站：任意 DSH Agent（含 Web UI 主会话）可调用 qq_send_* 主动发文字、图片等。
• 群友式表达：消息攒批（默认 batchWindowMs 2 秒）、回复拆成短气泡、打字节奏、引用 / @；模型自写的搭话不挂指向。
• 旁路行为：同字复读、冷场主动冒泡、聊起来后免 @ 接话（activeFollow）、私聊补一句等，各有开关与上限；私聊默认不主动打扰。

媒体、记忆与提醒¶

• 图片与表情包：支持 read_image 看图、发表情、把用户表情存入收藏目录；链接 / 视频 / 语音等有单独处理说明（见 docs/media.md）。
• 定时提醒：到点由插件直接发送，重启不丢；默认权限偏保守（提醒自己为主，@ 他人 / 全体默认关）。
• 长期记忆（memory 默认开）：转录落盘、每日摘要写入 MEMORY.md 等，检索式注入；人物表、认知库、表情包目录等见 docs/memory.md。
• 撤回消息：清引用为安全层；是否调侃由 recallMode（默认 ignore）等配置决定。

人格与工具面¶

• PERSONA.md、STYLE.md 热读，定义「是谁」与「怎么说」。
• QQ 会话默认挂最小 qq 预设，allowTools 白名单约 18 个工具，默认无 write / edit / bash；运维侧提供 doctor / status / logs / restart（见 docs/ops.md）。

安全默认值（务必先读）¶

• QQ 消息视为不可信输入；群消息默认仅 @ 触发。proactive、activeFollow 等会放宽「只在被叫到说话时回复」，不放心可在配置或 Web UI 关闭。
• 能直接写磁盘的 QQ 侧能力 mainly 限于表情包目录与校验过的提醒任务等，细节见 README「安全」一节与 docs/security.md。

安装与启用¶

前置：已安装 DSH，并在 Web UI Models 页配置模型凭据。OneBot 实现需开 正向 WebSocket 服务端（不是 websocketClients），地址与插件 endpoint 一致（默认 ws://127.0.0.1:3001）。

获取插件代码¶

官方 README 的「30 秒开始」写法如下（本文不写 git clone）：

1. 到 GitHub Releases 下载发布包；Windows 上可解压后运行 scripts\napcat-setup.cmd，脚本会配置 NapCat 与插件。
2. Linux / 容器场景见仓库 docs/install.md；Windows 桌面同机部署见 docs/windows.md。

运行环境：package.json 要求 Node >= 22。

连接 OneBot 并启动 Harness¶

1. 让 NapCat（或其它 OneBot v11 实现）监听 WebSocket，端口与 endpoint 一致，完成 QQ 扫码登录。
2. 若配置了 accessToken，在插件 accessToken（或环境变量 QQBOT_ACCESS_TOKEN）中填写一致值。
3. 启动常驻进程（README 示例）：

dsh --profile qqbot --port 3081 --no-open

也可使用仓库中的 deploy/qqbot.service 等方式托管。改完插件源码后需重启 Harness（Loader 按 URL 缓存模块）。

验证¶

私聊机器人发一句话，若在 QQ 内收到回复，说明 OneBot → 插件 → DSH Session → 回发链路已通。

典型用法与配置¶

常改配置项¶

完整字段见 docs/configuration.md。

人设与自检¶

想固定角色：按 docs/persona-workshop.md 复制模板修改 PERSONA.md / STYLE.md，或用文档中的选择题流程生成后再跑自检脚本查看模型可见内容。

开发自测¶

维护者本地验证命令：

node --test test/

适用场景与注意¶

适合谁：已在用 DSH 跑 Agent，希望通过 OneBot v11 把 QQ 当作双向渠道；愿意自己维护 NapCat（或同类）与 cordis.patch.yml / 环境变量，并接受作者「非通用插件、需按文档改」的定位。

运行权限：插件随当前 dsh 进程 执行，工具白名单与 cwd 决定能读写的路径；安装前请阅读仓库源码与 MIT 许可证，核对 allowTools、提醒与表情包写盘等行为是否符合你的安全要求。

生态说明：DSH 社区插件目录（如 SkillHub 上的 flyinstar/dsh-qq-bridge）由社区维护，与 DeepSeek / 幻方无官方从属关系；版本与行为以 GitHub 仓库与 CHANGELOG 为准。

结尾¶

dsh-qq-bridge 把 OneBot v11 与 DSH Session 对齐：入站聊天、出站 qq_send_*、群聊节奏与记忆提醒在一套配置里完成。部署上重点是 Releases 包、qqbot profile 与 NapCat 正向 WebSocket；细节以官方文档地图（安装、配置、安全、记忆、运维）为准。

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