前言¶
DeepSeek Harness（DSH）的 Agent 会话主要在 Web 界面里进行。人不在电脑前时，任务发不出去；在 Web 里跑完一轮对话，手机端也没有即时提醒。常见做法是另开一套消息机器人或自己写转发层，还要处理公网暴露、权限白名单等问题。
dsh-qq-bridge 是 DSH Web profile 下的客户端插件，由 TomoyoNatsume 维护，把 QQ 消息转成 DSH Agent 会话请求，再把回复发回 QQ。链路走本机 NapCat / OneBot 或腾讯官方 QQ Bot，不需要为 bridge 单独开放外部端口。
这是什么¶
dsh-qq-bridge 的定位很直接：QQ 发消息 → bridge → DSH Agent → QQ 收回复。
QQ 发送消息 -> NapCat / OneBot -> dsh-qq-bridge -> DSH Agent -> QQ 回复
插件以 DSH bundle 形式挂载，npm 包名为 @yachangchang/dsh-qq-bridge（当前版本 1.0.5），许可证 MIT。社区目录页在 SkillHub，源码在 GitHub（11 stars）。SkillHub 是独立的 DSH 插件社区站点，与 DeepSeek / 幻方无官方从属关系。
默认推荐 NapCat / OneBot：用一个 QQ 号登录 NapCat，从手机 QQ 给自己发消息即可，不必额外准备机器人小号。也支持双号模式（一个号登录 NapCat 收消息，另一个号发指令）和腾讯官方 QQ 开放平台机器人两种路径。
核心功能¶
下面这些是 README 中已列出的能力，安装前可按需对照。
QQ 遥控 Agent
白名单用户直接在 QQ 里发任务，插件转成 DSH live session，最终回复发回 QQ。
工作区、模型与会话控制
支持 bridge 侧指令 /dir、/new-session、/models、/model、/reasoningEff、/permission 等，也支持用自然语言切换常用设置。
定时提醒与 memo
v0.4.0 起支持一次性定时任务；v1.0.0 起可在 Web UI 中配置。例如在 QQ 里说「请在 2026 年 9 月 1 号中午 12 点提醒我提交报告」，到点后在同一会话触发 Agent 并主动提醒。数据通过 DSH storageDomain 持久化。
Web 会话完成提醒
非 QQ 发起的 Web 会话结束后，可主动给管理员 QQ 发提醒。QQ 发起的会话只返回实际 Agent 回复。官方 QQ Bot 路径下不支持该功能。
双接入路径
- NapCat / OneBot：本机个人使用，功能完整，社区方案，小号存在被强制下线的风险。
- 腾讯官方 QQ Bot：需 AppID、AppSecret，对接更稳，功能较少；主动提醒有额度限制，插件在官方模式下默认关闭
notifications.agentReply.enabled。
安装与启用¶
系统要求¶
- 已安装 DSH，
dsh web可正常启动。 - Linux / WSL2 环境；Node.js 20+。自动安装向导目前只适配 Linux / WSL2，原生 Windows 建议先用 WSL2。
- NapCat 路径：本机需先安装 NapCat CLI，并有一个可扫码登录的 QQ 号。
- 官方 QQ Bot 路径：需在 QQ 开放平台 创建机器人，提供 AppID、AppSecret。
安装插件¶
推荐从 npm 安装稳定版：
pnpm dsh plugin --profile web add @yachangchang/dsh-qq-bridge
也可以直接从 GitHub 安装当前仓库：
pnpm dsh plugin --profile web add github:TomoyoNatsume/dsh-qq-bridge
插件会写入 dsh.profile.bundles。刚安装时默认 enabled: false，不会连接 QQ，也不会启动 bridge。
NapCat 安装（选 NapCat 路径时）¶
Linux / WSL2 推荐：
cd ~
curl -o napcat.sh https://raw.githubusercontent.com/NapNeko/NapCat-Installer/main/script/install.sh
bash napcat.sh --docker n --cli y
确认命令可用：
napcat help
只需安装 NapCat CLI，不必手动先启动 QQ 后台；设置页保存配置时会按填写的 QQ 号执行 napcat start <QQ>。
在 Web UI 中启用¶
- 启动
dsh web，打开左下角「设置」，进入QQ bridge。 - 选择接入方式（NapCat / OneBot 或腾讯官方 QQ Bot），填写管理员、Agent 模型等，点击「保存配置」。NapCat 分支会检测本机 NapCat，并自动写入 OneBot 正向 WebSocket 配置和 token（默认
127.0.0.1:3001）。 - 保存成功后，在 QQ 里发送
ping验证。若无响应，执行napcat log <你的QQ号>或查看~/Napcat/log/napcat_<你的QQ号>.log，确认是否已扫码登录。
官方 QQ Bot 首次配置时，setup 会生成一次性 pair <code>，用管理员 QQ 发给机器人即可完成 adminOpenId 配对。
典型用法¶
验证连通后，README 建议依次尝试以下消息：
ping
当前工作目录是什么
列出当前工作目录下的目录和文件
/dir /home/xxx/project
/models
/model deepseek-v4-pro
/reasoningEff high
/permission workspace-write
/new-session
帮我把工作目录改到 /home/xxx/project
请在 2026 年 9 月 1 号中午 12 点提醒我提交报告
收到有效 QQ 指令后，插件会先回复 agent.ackMessage（默认「收到，正在处理…」），设为空字符串可关闭。
常用 Agent 配置示例：
agent:
provider: deepseek-official
model: deepseek-v4-pro
cwd: "~"
preset: dsh-qq-bridge
ackMessage: 收到，正在处理...
cwd：QQ Agent 默认工作目录；/dir <目录>会覆盖当前 QQ 会话的后续 session 目录。preset：QQ 会话专用 preset；普通 Web 会话不选它则不会套用 QQ 回复风格 skill。
NapCat 模式配置示例：
platform: napcat
napcat:
wsUrl: ws://127.0.0.1:3001
token: "<NapCat OneBot access token>"
配置修改推荐在 Web UI 的 QQ bridge 页面完成；手动排查时可查看 ~/.dsh/profiles/web/cordis.patch.yml，改完后重启 dsh web。
适用场景与注意¶
适合谁
- 需要在手机 QQ 里远程给 DSH Agent 派任务、收回复的开发者。
- 希望 Web 会话结束后收到 QQ 提醒、不想长期盯着浏览器进度的人（NapCat 路径）。
- 已有 NapCat 环境，或愿意在 QQ 开放平台注册官方 Bot 的用户。
使用前务必了解
- 权限边界：插件以当前
dsh web进程的用户权限运行，Agent 能访问的工作区、文件和网络范围与 DSH 一致。安装前应阅读源码与 MIT 许可证，确认白名单和管理员配置符合你的安全要求。 - 接入方式差异：NapCat 功能更全但非官方；官方 Bot 更稳但不支持 Web 会话完成自动提醒，且主动消息有额度限制。
- 单号 / 双号模式：双号模式推荐新用户直接使用；单号模式可收 Agent 完成提醒，但可能收不到消息提示。登录 DSH 的 NapCat 账号不建议用极不常用的小号。
- 已知限制：当前不支持通过 QQ「我的电脑」会话完整交互；这类消息可被日志捕获，但回复链路不完整。
- 旧版迁移：从旧版 setup 迁移到 bundle 时，启动会自动清理
cordis.patch.yml里旧的id: dsh-qq-bridge插入项，并在同目录留下.bak备份。
更完整的架构说明见仓库 docs/project-overview.md，使用导图见 docs/usage-guide.html。
结尾¶
dsh-qq-bridge 把 QQ 接进 DSH 的 Agent 链路，在本机完成消息转发，兼顾遥控、模型切换、定时提醒和 Web 会话通知。DSH 生态的理念是「一切皆插件」；若你需要在移动端驱动鲸鱼娘，可以先从 ping 验通，再按场景选 NapCat 或官方 Bot 路径。
