前言¶

在 DSH 里跑陪伴型或对话型智能体时，常见做法是只在本地终端或 IDE 里交互。若希望同一个 agent 在 QQ 上响应私聊、或在群里被 @ 后回复，往往需要自建一套「收消息 → 调模型 → 发回去」的胶水代码，还要处理会话持久化、群聊礼貌边界和对外暴露的工具面。

dsh-qq-bridge 是社区维护的 DSH bundle，定位是一条通道：它不逆向 QQ 协议、不登录账号，而是连接已经登录好的 OneBot 11 后端（如 NapCat、LLBot），把入站消息转成 DSH session 里的一轮对话，再把回答发回 QQ。登录与设备指纹的风险留在后端；桥只负责「收到消息 → 跑一轮 → 发回回答」。

这是什么¶

• 名称：dsh-qq-bridge（npm 包名同名，当前版本 0.1.0，MIT 许可证）
• 维护者：Dx3906-xn
• 仓库：https://github.com/Dx3906-xn/dsh-qq-bridge
• 定位：DSH 智能体的 QQ 通道插件，后端可插拔，一个 QQ 会话对应一个 DSH session，工具面刻意收窄，适合处理不可信的外部文本。

它不是 QQ 机器人框架，而是与 DSH Cordis 生态集成的桥接层；依赖 Node.js >= 22.5.0，以及 README 中列出的 @deepseek-ai/cordis、dsh-agent、dsh-session 等 peer 依赖。

会话模型与群聊策略¶

一个会话就是一个 DSH session¶

私聊用对方 QQ 号、群聊用群号区分「跟谁说话」。会话 id 由四段组成，每段经 encodeURIComponent 后再用 : 连接，例如：

qq:onebot:private:10001
qq:onebot:group:67890

第一段中的 namespace 默认是 onebot（配置项 sessionNamespace），刻意不绑定当前传输名称：同一个号换 NapCat / LLBot 传输时，会话 id 不变，重启后可以 resume 而不是重新 create。群聊是一个群一个会话，群内多人共享同一上下文。

groupMode：群里什么时候说话¶

修改 groupMode 需重启进程；mention 模式下会从文本中剥掉传输层合成的 @你 标记，避免模型误学称呼方式。

核心功能¶

消息路径¶

OneBot 后端通过正向 WebSocket 连入桥（桥主动连 endpoint，无需给桥开端口）。入站事件经策略层（群模式、白名单、去重、回声过滤等）后，按会话入队：同一会话串行处理，不同会话并行。模型返回空串时不发 QQ 消息；agent 抛异常时发送固定的一句错误提示，且每次失败只提示一次。

仅三个 agent 工具¶

面向被陌生人消息唤醒的 agent，插件只暴露：

• qq_whoami — 当前身份、已连接会话、当日剩余主动发送额度
• qq_send — 向已有会话发送文字
• qq_history — 读取当前会话最近消息

不包含任意选目标、列群、改群模式、读他人会话等能力。好友申请与群邀请等 notice/request 在传输层丢弃。

多传输与 /qq 命令¶

可在配置中声明多个 backends，运行时用 /qq status 查看连接，/qq backend <id> 先连新传输、成功后再断旧传输，失败则留在原传输。切换不对 agent 开放为工具，避免提示注入改连接方式。

与记忆插件的协作¶

入站消息除文本信封外，还带 source.speaker（id、name、kind、own、群信息等），供如 dsh-hippo 等记忆插件区分说话人。配置项 ownerIds 声明主人 QQ 号；应与 dsh-hippo 的 ownerIds 保持一致，否则桥的 own 与记忆归属会错位。dailyProactive 默认为 0，禁止模型主动发消息，需运维显式给每日额度。

安装与启用¶

桥以 DSH bundle 形式安装到某个 profile。README 给出的示例（路径需按本机替换）：

$env:DSH_HOME = 'D:\A\DSH-L\agent\home'
node D:\A\DSH-L\agent\node_modules\@deepseek-ai\dsh\lib\bin.js plugin --profile b add D:\A\DSH-L\projects\dsh-qq-bridge

在 profiles/<name>/cordis.patch.yml 中为插件行填写参数，例如：

- id: qq-bridge
  name: dsh-qq-bridge
  config:
    endpoint: ws://127.0.0.1:3001
    groupMode: mention
    preset: companion

NapCat 等后端需开启「WebSocket 服务器」，端口与 endpoint 一致即可。

典型配置项¶

完整列表见仓库 README「配置」一节。

适用场景与注意¶

适合：已在本机或内网部署 NapCat / LLBot 等 OneBot 11 后端，希望用 DSH 的 session 持久化、预设与工具生态承接 QQ 对话，并愿意接受「群默认仅 @ 回复」等礼貌默认值。

注意：

1. 插件在 当前 DSH 进程权限 下运行，可访问该进程能读写的路径与网络；安装前请阅读源码与 MIT 许可证，确认 endpoint、ownerIds 等配置符合你的安全边界。
2. 桥不持有 QQ 登录态；账号安全与合规使用由 OneBot 后端与运维负责。
3. 社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；「一切皆插件」是 DSH 生态的常见做法，而非官方应用商店条目。

本地可运行 npm test 执行断言套件；真机联调另有 test/e2e-agent.mjs（需真实 key，手动执行）。

结尾¶

dsh-qq-bridge 把 QQ 收敛为「一个会话一个 DSH session + 三个受限工具」，把协议与登录留给 OneBot 后端，把思考与记忆留给 DSH agent。若你正在给陪伴型智能体加 QQ 入口，可从仓库 README 的安装与 cordis.patch.yml 示例起步，再按群规模调整 groupMode 与 ownerIds。

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