前言¶

在 DeepSeek Harness（DSH）里跑 agent，常见做法是桌面或 Web 会话里打字交互。若希望对方在 QQ 里发一句、agent 在同一套会话里回一句，就需要一条稳定的「渠道」：入站事件、路由到会话、出站发消息。社区里已有基于 OneBot 的 QQ 机器人方案，但和 DSH 的 agent.followup()、工具调用模型并不天然对齐。

下面介绍维护者 danshuyue 发布的客户端插件 dsh-onebot-channel：基于 OneBot 11 协议，入站以 WebSocket 事件推送为主、HTTP 轮询兜底，出站通过 qq_send 等工具回话。npm 包名 dsh-onebot-channel，当前资料中版本为 0.15.2，许可证 MIT，运行环境要求 Node >= 22.19。

这是什么¶

一句话：把 QQ 私聊与群聊变成 DSH 会话里的回合——对方在 QQ 发消息，插件按路由表唤醒绑定的会话；agent 看到带时间戳与身份标注的正文，再通过 OneBot 的 send_private_msg / send_group_msg 回到 QQ。

数据流（摘自项目 README）：

QQ 客户端
   ↓  OneBot 11 协议端（SnowLuma / LLOneBot 等）
   ↓  本插件：WS 事件推送为主，HTTP 轮询兜底
路由表：这个 QQ 号 / 群绑的是哪个会话
   ↓  agent.followup()  唤醒会话
会话跑一个回合
   ↓  agent 调 qq_send 工具
OneBot send_private_msg / send_group_msg
   ↓  按换行或 segments 切条，带随机延时
回到 QQ

插件不读取 QQ 密码，只与已配置的 OneBot 协议端通信。未绑定到会话的 QQ 号或群会被忽略，避免误投到其他会话。

核心功能¶

入站与路由¶

• 私聊 / 群聊投递：每个 QQ 号或群在设置里绑定一个 DSH 会话；未绑定的一律忽略。
• WebSocket 实时推送：延迟接近零；断线后自动退回轮询补漏。
• 身份标注：逐条区分「用户本人」与「群友（不是用户本人）」，减少 agent 张冠李戴。
• 群聊上下文：被 @ 时可附带上次投递之后的未读群消息。
• 私聊合并窗口（mergeWindowMs，默认 2500 ms）：连续多条私聊先记账再合并为一个回合，避免连开多个回合；仅私聊生效，群聊仍以 @ 为触发。

出站与对话节奏¶

装好后 agent 可用 10 个工具（名称与用途以 README 为准）：

沉默权：qq_wait / qq_pass / qq_close 用于模拟真人节奏；qq_pass 不会吞掉已写入会话的真话正文（0.9.3 修正）。qq_close 在对方仍有未答提问时会被桥接拒绝。

引用与 @（0.13.0 / 0.14.0）：默认自动引用触发回复的那条；分条发送时 @ 与引用只挂在第一条。出站装饰段（引用、@、表情）失败时会逐级剥离重试，避免整段回复消失。

关系记忆：称呼与事实落在 ~/.dsh/qq-bridge-memory.json；可通过 memoryEnabled: false 关闭注入。

主动搭话（默认关，proactiveEnabled）：按静默时段、空闲时长、日配额等条件向已绑私聊投内部来信，是否开口仍由模型决定（可用 qq_pass）。状态在 ~/.dsh/qq-bridge-proactive.json。

媒体与其它¶

• 正文 [表情:呲牙] 或 qq_send 的 emoji / custom_emoji（商城大表情需先收藏）。
• QQ 图片下载后进 DSH 附件库，以 image 块进入会话；入站、群 @ 上下文及 qq_msg_history 等路径在 README 中均有说明。

更细的对话逻辑见仓库内 docs/QQ对话说明.md。

安装与启用¶

前置条件：先运行一个 OneBot 11 协议端（如 SnowLuma、LLOneBot），并在插件配置里填写协议端 HTTP 地址与 token。

官方安装命令：

dsh plugin --profile desktop add dsh-onebot-channel

装完后在 DSH 设置 → QQ 桥接 填写协议端地址和 token，将 QQ 号 / 群绑定到对应会话。

配置持久化在 ~/.dsh/qq-bridge.config.json，不在插件目录内，重装插件不会丢失该文件。

典型用法¶

发消息与表情¶

// 发消息 + 经典小表情
{ "text": "搞定了", "emoji": "OK" }

// 发收藏夹里的商城大表情
{ "text": "看这个", "custom_emoji": "猫" }

// 一句话拆成三条，逐条发出
{ "segments": ["我跟你说", "那个事搞定了", "不过还差一点"] }

查表情与历史¶

{ "query": "比心" }        // qq_emoji_search
{ "group_id": "1046436553", "count": 20 }  // qq_msg_history，默认 20 条，上限 100

发说说（须确认）¶

{ "content": "今天天气不错", "visibility": 1, "confirm": true }

说说可见性：1 所有人 · 4 仅好友 · 16 仅自己 · 64 指定好友 · 128 分组。

入站正文中的消息锚点形如 （2026-10-31 20:15）[#-2123597213]（QQ群 …）…，需要明确引用其它消息时在 qq_send 上传 reply_to 为 [#数字] 中的数字。

适用场景与注意¶

适合谁：已在 DSH desktop profile 上跑 agent，并愿意自建 OneBot 11 协议端、把 QQ 当作其中一个对话渠道的开发者和个人用户。

权限与安全：插件以当前 dsh 进程权限 运行，可读写 ~/.dsh/ 下桥接相关配置与记忆文件，并通过协议端代发 QQ 消息。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认协议端与白名单策略（如 allowlist.js）符合你的信任边界。

生态说明：DSH 社区插件目录托管于独立站点 SkillHub 插件页，与 DeepSeek / 幻方无官方从属关系；选用插件属于社区生态行为，需自行评估维护状态（GitHub 上资料显示 1 star、分类为客户端）。

结尾¶

dsh-onebot-channel 把 OneBot 11 的 WS 入站与 DSH 会话回合对齐，并用 qq_send 等工具覆盖发消息、表情、历史、节奏控制与可选主动搭话。若你要在 QQ 里和同一个 Harness agent 对话，可先起协议端，再按上述命令安装并在 QQ 桥接里完成绑定。

• 目录页：https://www.skillhub.cn/plugins/danshuyue/dsh-onebot-channel
• GitHub：https://github.com/danshuyue/dsh-onebot-channel