dsh-qqbot：DeepSeek Harness × QQ 双通道接入插件

前言¶

DeepSeek Harness（DSH）采用插件化架构，通过扩展能力实现不同场景的接入。将 DSH 接入 QQ 机器人需要处理协议转换与会话管理。dsh-qqbot 插件支持 OneBot 11（NapCat/Lagrange 等正向 WebSocket）与 QQ 官方开放平台（q.qq.com）双通道，允许每个 QQ 会话对应一个持久 Agent，支持文件、Shell、联网等完整工具链，并允许 Agent 主动发消息。

核心功能¶

双通道接入：支持 OneBot 11 协议端（NapCat、Lagrange 等）与 QQ 官方开放平台（AppID/AppSecret 直连）。
持久化会话：每个 QQ 会话（私聊、群聊、频道）对应一个独立 Agent，历史记录跨重启保留。
完整工具链：挂载 DSH 预设（默认 standard），具备文件读写、Shell/PowerShell、网页搜索、子代理、任务清单等能力。
主动发消息：注册 qq_send 工具，Agent 可主动向对话方汇报或提问。
本地命令：支持 #help、#status、#reset 等本地指令。

安装与配置¶

1. 准备 QQ 接入端¶

OneBot 通道：选择 NapCat 或 Lagrange 等协议实现，开启正向 WebSocket，获取地址与 Token。
官方通道：在 QQ 开放平台创建机器人，获取 AppID 与 AppSecret。

2. 安装插件¶

在 DSH 的 web profile 下执行安装命令：

dsh plugin --profile web add file:C:\path\to\dsh-qqbot

安装后需重启 dsh web 进程。启动日志中出现 qqbot: connected to ... 即为成功。

3. 配置¶

配置通过环境变量或 cordis.patch.yml 完成。

OneBot 通道（默认）：

set QQBOT_WS_URL=ws://127.0.0.1:3001
set QQBOT_ACCESS_TOKEN=你的token
dsh web

QQ 官方通道：

set QQBOT_TRANSPORT=official
set QQBOT_APP_ID=你的AppID
set QQBOT_APP_SECRET=你的AppSecret
dsh web

或编辑 $DSH_HOME/profiles/web/cordis.patch.yml：

- id: qqbot
  config:
    transport: official
    appId: '你的AppID'
    clientSecret: '你的AppSecret'
    allowedGroups: []  # 限制回复群组，空为全部
    allowedUsers: []  # 限制私聊用户，空为全部

使用方法¶

正常对话：向机器人发送任意消息，由当前会话的 Agent 处理并回复。
查看状态：输入 #status 查看接入通道、连接与会话状态。
重置会话：输入 #reset 清空当前会话上下文。
Agent 主动消息：Agent 可调用 qq_send 工具向当前会话发送文本。

注意事项¶

安全限制：QQ 机器人入口无认证，任何能发消息的人均可调用 Agent 能力（含 Shell）。必须通过 allowedUsers / allowedGroups 限制范围。
官方通道限制：QQ 官方开放平台自 2025-04-21 起已停用主动消息能力，官方通道下 qq_send 会报错。OneBot 通道不受此限制。
回复限制：官方回复受平台窗口和“同一条入站消息最多回复 5 次”限制，插件会拒绝超过 5 条的分块发送。
工作目录：Agent 的工作目录默认位于 DSH 沙箱根内。若修改 workspaceRoot，请确保路径在沙箱范围内，否则文件类工具会被拦截。

结尾¶

dsh-qqbot 为 DSH 用户提供了标准化的 QQ 机器人接入方案，通过双通道支持与持久化 Agent 机制，适合需要将大模型能力集成到 QQ 生态的开发场景。更多细节可参考 GitHub 仓库。