前言¶
在 DeepSeek Harness（DSH）里跑 Agent，常见入口是桌面或 Web GUI。若希望私聊、群聊都走同一个 Agent，还要能戳一戳、贴表情、发图发文件，就需要一个把 IM 协议接进 DSH 的客户端插件。下面介绍社区维护的 dsh-qq-onebot（仓库 2710586329/dsh-qq，目录页 skillhub.cn/plugins/2710586329/dsh-qq）：底层走 OneBot v11，默认搭配 NapCat，把 QQ 消息转给进程内的 Agent，并把回复与互动工具送回 QQ。
DSH 生态是「一切皆插件」；SkillHub 等目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-qq-onebot 是 DSH 的 QQ 频道插件（分类：客户端）。维护者 GitHub 用户 2710586329，npm 包名 dsh-qq-onebot，当前资料中版本 1.2.2，许可证 MIT，依赖 Node >=20，DSH >=0.2.0。
架构可以概括为：本机 QQ 客户端经 NapCat 注入，与插件之间用 OneBot v11 WebSocket；插件跑在 DSH 宿主进程里，通过 ctx.agents 调用你自己的 Agent（预设、工具、记忆由你配置）。README 说明：不必公网 IP、不必备案、不必企业主体；若场景能用 QQ 官方机器人，官方方案优先。
合规与风险（资料原文强调）：NapCat 属于非官方 QQ 协议端，跑在你自己登录的客户端上，不符合腾讯用户协议，存在风控或封禁可能；建议用小号、不与常用号同设备、不发垃圾消息。插件只负责 OneBot 消息与 Agent 的桥接，协议端怎么稳、怎么合规需自行负责。
核心功能¶
以下能力均来自仓库 README 与 package.json 描述，未在资料中出现的数字与案例不写。
| 方向 | 说明 |
|---|---|
| 会话 | 一个 QQ 会话对应一个持久 Agent 会话；默认按会话隔离工作目录（AGENTS.md、记忆区/），与宿主私人记忆分开 |
| 群 / 私聊 | 群聊默认需 @ 才回复；被 @ 后 60 秒内同群同人可免再 @；可配置白名单、主人识别、引用与 [SILENT] 等 |
| 多模态 | 语音可走本地 vosk 离线 ASR；图片可见；上下文快满时有守卫与换会话策略 |
| Agent 工具 | qq_poke、qq_react、qq_like、qq_send_image、qq_send_file、qq_face、qq_mface、qq_reply、qq_send、qq_recall 等 |
| 问答回 QQ | ask_user_question 的问题会发到 QQ，用户用数字回复即可 |
共存注意：一台 NapCat 的 WebSocket 只应被一个 Agent 连接；若与 dsh-onebot-hub 等同连 NapCat，会出现消息重复、回复错乱。资料建议只保留一个 OneBot 类插件。
安装与启用¶
整体分三步：NapCat + 小号 → 装插件 → 重启 DSH 填连接信息。
1. NapCat 与 WebSocket¶
下载 NapCat Windows 一键版（NapCat.Shell.Windows.OneKey.zip），解压运行 NapCatInstaller.exe（独立 QQ，不覆盖现有安装）。登录小号后打开 WebUI（默认 http://127.0.0.1:6099），在「网络配置」新建 WebSocket 服务器，例如：
| 项 | 示例 |
|---|---|
| 地址 | 127.0.0.1 |
| 端口 | 3001（占用则换端口并记住） |
| Token | 自设，如 my-token-2026 |
| 消息格式 | array（勿选 string） |
2. 安装插件¶
先完全退出 DSH（含托盘），避免插件文件被占用导致安装失败。
推荐从 npm 安装（须用 DSH 自带的 dsh，且 必须 带 --profile desktop）：
dsh plugin --profile desktop add dsh-qq-onebot
也可从 Releases 的 dsh-qq-onebot-1.0.0.tgz 或本地解压目录安装，路径写绝对路径，例如：
dsh plugin --profile desktop add "D:\下载\dsh-qq-onebot-1.0.0.tgz"
PATH 里没有 dsh 时，可用桌面端内置 CLI，例如：
& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-qq-onebot
装完后可用下面命令确认：
dsh plugin --profile desktop why dsh-qq-onebot
3. 连接 DSH 与 NapCat¶
重启 DSH，在 设置 → QQ 填写 wsUrl 与 accessToken；若设置页暂无 QQ 项，可直接改 $DSH_HOME/dsh-qq/settings.json（Windows 常见路径 C:\Users\<用户名>\.dsh\dsh-qq\settings.json），保存后约 800ms 生效，例如：
{
"wsUrl": "ws://127.0.0.1:3001",
"accessToken": "my-token-2026"
}
也可在 $DSH_HOME/profiles/desktop/cordis.patch.yml 中配置 dsh-qq 段（整段替换）。日志出现 已连接 ws://127.0.0.1:3001 后，给小号发私聊验证。
私聊默认安全策略：privateMode 默认为 allowlist，且 privateAllow 默认为空——装好后私聊不会自动回复。需显式加入 QQ 号或改为 open（风险自担）。能私聊该号的人，在资料语境下相当于能指挥跑在你机器上的 Agent（含读文件、跑命令），安装前应理解插件以 当前 DSH 进程权限 运行，并自行审阅源码与 MIT 许可证。
典型配置与用法¶
常用项¶
| 配置 | 默认 / 要点 | 何时改 |
|---|---|---|
persona |
空 | 设定称呼与性格 |
ownerIds / ownerLabel |
[] / 主人 |
群内识别主人 |
requireMention |
true |
群聊免 @ 接话 |
groupMode / privateMode |
open / allowlist |
限定群或私聊对象 |
groupReplyGapMs |
20000 |
控制回复密度 |
rateLimitPerMin |
12 |
每会话每分钟发送上限 |
workspaceRoot / isolateByPeer |
— | 会话目录与是否按对端隔离 |
设置面板约 34 项；完整 50+ 项见仓库 docs/configuration.md。人设、部署、开发分别见 docs/persona.md、docs/deployment.md、docs/development.md。
放通私聊示例¶
在 profile 或等价配置中：
privateMode: 'allowlist'
privateAllow:
- '你的QQ号'
适用场景与注意¶
适合：已在 DSH 上维护 Agent，希望用 QQ 私聊 / 群聊作为入口，并需要戳一戳、表情、点赞、发图发文件等 OneBot 能力；本机或内网 NapCat，无需公网暴露。
不适合或需另选方案：必须合规的企业客服、大规模群发（资料写明不做群发）；只能接受官方机器人 API 的场景应优先官方平台。
安装前建议：阅读 GitHub README 中的风控说明；确认不与其它 OneBot 插件共抢同一 NapCat WS；检查 $DSH_HOME/dsh-qq/ 下日志（如 <workspaceRoot>/logs/dsh-qq-<日期>.log）排障。卸载插件时 $DSH_HOME/dsh-qq/ 不会自动删除，设置与日志会保留。
结尾¶
dsh-qq-onebot 把 QQ 通过 OneBot v11 接到 DSH，让私聊与群聊共享同一套 Agent 能力，并带会话隔离、群 @ 策略与一批 QQ 互动工具。部署核心是 NapCat WebSocket + dsh plugin --profile desktop add dsh-qq-onebot + wsUrl / accessToken 对齐。
- 目录页：https://www.skillhub.cn/plugins/2710586329/dsh-qq
- 源码与文档：https://github.com/2710586329/dsh-qq
