前言¶

在 DeepSeek Harness（DSH）里跑智能体，常见入口是 CLI 或 Web。若希望同事或用户在 QQ 里直接对话，而不引入 mirai、go-cqhttp 等第三方机器人框架，就需要插件直接对接 QQ 开放平台提供的 WebSocket 网关与 REST API，并把每条会话映射到独立的 dsh Agent。

下面介绍社区插件 dsh-qq-bot（维护者 sindo-s），它走官方通道，用 Node.js 内置 WebSocket 和 fetch 完成连接与收发，属于 DSH 生态中的工作流类插件。

这是什么¶

dsh-qq-bot 是标准 DSH 插件：通过 QQ 开放平台官方 WebSocket 网关和 REST API，将 QQ 群聊与单聊连接到独立的 dsh Agent。简介原文为：DeepSeek Harness plugin bridging QQ official Bot API to dsh agents (no third-party bot framework)。

它不依赖 Desktop Next，复用宿主 DSH 的 Agent、默认模型、工具和附件服务；在 Linux 服务器或容器里同样可用环境变量与独立 profile 运行，无需为本插件暴露入站端口（出站 WebSocket/HTTPS 即可）。

核心功能¶

已核实的能力包括：

1. 会话隔离：每个 QQ 群或用户对应独立 Agent 会话；消息按 Harness turn 关联，网关重连时对事件去重。
2. 内置命令：/new、/stop、/tools、/help；可用 /whoami（或 /id）自助发现 OpenID，便于配置白名单。
3. 安全默认：publicMode 默认为 false，仅 allowGroups / allowUsers 中的 OpenID 可访问 Agent；白名单为空时普通消息会被拒绝。enableWhoami 默认开启，方便首次配置。
4. 工具边界：QQ Agent 默认不继承宿主全部工具；qq_send 只能发到当前会话。通过 allowedTools 白名单放行已在宿主注册的工具名，需先在 DSH 中安装对应插件或 MCP。
5. 图片输入：私聊或群聊 @ 机器人 可发图（需视觉模型与宿主 attachments 服务）；不支持语音、视频、文件等类型（见 README 已知限制）。
6. 可靠性：single-flight 创建会话、Token 刷新合并、网关指数退避、超长文本按 Unicode 分片等，细节见项目 README「可靠性策略」一节。

当前包版本 0.3.2（package.json），声明兼容 DSH 0.1.5-rc.2 与 0.1.6-alpha.2，Cordis 4.0.2 / Schemastery 3.18.2。许可证 MIT。

前置条件¶

1. Node.js 22.6 或更高。
2. 已能运行 DeepSeek Harness，并配置默认 provider/model。
3. 在 QQ 开放平台 创建机器人，取得 AppID 与 AppSecret；机器人已上线，或将测试群/用户加入沙箱。
4. 安装与运行使用相同的 DSH_HOME、profile 和系统用户；QQ 凭据通过环境变量或配置文件提供，插件不会自动加载 .env。

凭据环境变量（在启动 DSH 的进程中设置）：

# PowerShell
$env:QQ_BOT_APP_ID = '你的 AppID'
$env:QQ_BOT_APP_SECRET = '你的 AppSecret'

# Bash
export QQ_BOT_APP_ID='你的 AppID'
export QQ_BOT_APP_SECRET='你的 AppSecret'

安装与启用¶

源码调试（patch 方式）¶

在插件源码目录执行依赖安装与向导，再用绝对路径 patch 启动 DSH：

npm ci
npm run setup
npm run doctor

启动已安装的 DSH（将路径换成你的 cordis.yml 绝对路径）：

dsh web --patch "/absolute/path/to/dsh-qq-bot/cordis.yml"

若从 DSH 源码运行，在 DSH 仓库目录执行：

pnpm dsh web --patch "/absolute/path/to/dsh-qq-bot/cordis.yml"

向导会生成含绝对插件路径的配置；AppSecret 输入不回显，已有文件不会被覆盖。另存配置可用：

npm run setup -- --output qq.local.yml

安装为 DSH 插件 bundle¶

遵循 DSH 官方打包规范，在源码目录构建并安装到指定 profile（示例 profile 名为 qq，tarball 名随版本为 dsh-qq-bot-0.3.2.tgz）：

npm ci
npm pack
dsh plugin --profile qq add /absolute/path/to/dsh-qq-bot-0.3.2.tgz
npm run setup -- --bundle --output cordis.yml
npm run doctor
dsh --profile qq --patch /absolute/path/to/cordis.yml

先在该 profile 中配置 DSH 默认 provider/model。--bundle 模式生成对 id: qq-bot 的覆盖条目，与源码模式的「插入条目」不要混用。发布包还提供 dsh-qq-bot setup、dsh-qq-bot doctor 可执行入口。

无桌面服务器 / 独立 profile¶

非交互初始化 bundle 配置：

npm ci
npm pack
dsh plugin --profile qq add /absolute/path/to/dsh-qq-bot-0.3.2.tgz
npm run init -- --bundle --output cordis.yml

在同一运行环境设置 QQ 凭据变量后：

npm run doctor
dsh --profile qq --patch /absolute/path/to/cordis.yml

init 不读取环境变量中的凭据，生成配置默认仅允许白名单；交互配置仍可用 npm run setup -- --bundle。

配置检查¶

npm run doctor 离线检查 YAML、QQ 条目、凭据是否存在、字段类型与范围，不打印凭据、不调用 QQ API。自定义文件示例：

npm run doctor -- --output qq.local.yml

主要配置字段（节选，完整表见 README）：

DSH 的 patch 会替换整个 config，编辑覆盖层时需保留该层所需的全部配置。

典型用法¶

用 /whoami 配置白名单¶

首次不知道 OpenID 时可留空白名单。保持 publicMode: false、enableWhoami: true，启动后：

1. 私聊机器人发送 /whoami，取得 user_openid；或在测试群中 @ 机器人并发送 /whoami，取得 group_openid。
2. 将回复中的 allowUsers 或 allowGroups 片段复制到 cordis.yml，保存并重载插件。
3. 沙箱环境下还需在 QQ 开放平台把对应群/用户加入沙箱名单。

OpenID 不是 QQ 号或群号，且只对当前机器人 AppID 有效。若普通消息无响应但 /whoami 正常，多半是未把 OpenID 加入白名单。

在 QQ 里管理会话与工具¶

若需联网搜索等能力，先在宿主安装工具，再把准确注册名写入 allowedTools，例如：

allowedTools:
  - web_search

在 QQ 中发送 /tools 确认状态。不要在公开机器人上开放 Shell、任意写文件或凭据类工具。

DSH Desktop Next（WSL）¶

插件须安装在 Desktop Next 当前 WSL 发行版与 active slot 的 DSH_HOME 中，用该运行时自带的 dsh plugin --profile web add <tarball> 安装。QQ 配置写在 home/profiles/web/cordis.patch.yml 的 id: qq-bot 覆盖条目中；暂无凭据时可设 enabled: false，填好后再启用。核心升级可能切换 slot，升级后需确认插件与 QQ 配置已迁移。

适用场景与注意¶

适合谁：已在 DSH 上配置好模型与工具，希望用 QQ 官方 Bot 能力做内测或小范围协作；需要每群/每用户独立 Agent 会话，且能接受文本与图片输入、暂不支持音视频文件的场景。

运行权限：插件在当前 dsh 进程中加载，Agent 可调用的工具以 allowedTools 与宿主已加载服务为准。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认凭据与白名单策略符合你的安全要求；仅在对机器人和工具能力有把握时再设 publicMode: true。

生态说明：DeepSeek Harness 采用「一切皆插件」的扩展方式；SkillHub 插件目录 为社区站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-qq-bot 把 QQ 开放平台官方网关与 REST API 接到 DSH Agent，不绑第三方机器人框架，适合在 CLI、Web、服务器或 Desktop Next 的 WSL 运行时里做受控的 QQ 对话入口。更多配置、排障表与开发检查命令见项目 README。

• 插件目录：https://www.skillhub.cn/plugins/sindo-s/dsh-qq-bot
• 源码与文档：https://github.com/sindo-s/dsh-qq-bot