dsh-qqbot

把 DeepSeek Harness（DSH）接入 QQ 机器人的插件，支持两种接入通道：

通道	transport	适用	说明
OneBot 11	onebot（默认）	NapCat / Lagrange / LLOneBot 等协议端	正向 WebSocket，功能全（群聊任意消息、图片等）
QQ 官方开放平台	official	q.qq.com 官方机器人	AppID/AppSecret 直连，群聊（@触发）/单聊/频道

两种通道下行为一致：

• 每个 QQ 会话一个持久 Agent：私聊、每个群、每个频道各自独立上下文，历史跨重启保留 （会话日志持久化到 $DSH_HOME/sessions）；
• 完整工具链：Agent 挂载部署的 Agent 预设（web profile 下为 standard）， 拥有文件读写、Shell/PowerShell、网页搜索、子代理、任务清单等 DSH 全部能力；
• Agent 可主动发消息：注册 qq_send 工具，Agent 可以主动向对话方汇报进度、 提问或输出结果；
• 本地命令 #help / #status / #reset，长回复自动分块，断线自动重连。

工作原理

QQ 消息 ──► OneBot 实现 / QQ 官方开放平台
                │  正向 WebSocket / 官方 WS 长连接（q.qq.com）
                ▼
        dsh-qqbot 插件（web profile 内）
                │  ctx.agents.create / resume（每个 QQ 会话一个 Agent）
                ▼
        DeepSeek Harness Agent（模型 + 工具 + 预设）
                │  回复文本
                ▼
        send_*_msg / 官方 OpenAPI ──► QQ

安装

1. 准备 QQ 接入端

OneBot 通道（默认）：任选一个协议实现，例如 NapCat： 登录机器人 QQ 号，开启「网络监听 → WebSocket 客户端（正向 WS）」，记下地址 （默认 ws://127.0.0.1:3001），可选设置 access token。

QQ 官方通道：到 QQ 开放平台 创建机器人，在「开发设置」 拿到 AppID 与 AppSecret；在「沙箱配置」添加测试群/私聊用户（或发布后使用）。 群聊中机器人只会收到 @它的消息；单聊需用户主动发起。

2. 安装插件到 DSH web profile

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

等价于在 $DSH_HOME/profiles/web 下执行 pnpm add file:...， 并把 dsh-qqbot 加入该 profile 的 bundle 列表。

然后重启 dsh web（先 Ctrl+C 停掉旧进程再启动）。启动日志出现 qqbot: connected to ... 即成功。

3. 配置

OneBot 通道：默认连接 ws://127.0.0.1:3001，可设环境变量：

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

QQ 官方通道（任选其一）：

方式 A —— 环境变量：

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

方式 B —— profile 的 cordis.patch.yml（$DSH_HOME/profiles/web/cordis.patch.yml）：

- id: qqbot
  config:
    transport: official
    appId: '你的AppID'
    clientSecret: '你的AppSecret'
    # sandbox: true          # 沙箱域名（默认正式环境）
    # groupMentionOnly: true # 群聊只在 @机器人 时回复（官方通道天然只收 @）
    # allowedUsers: ['xxx']  # 只允许这些用户 openid（空 = 全部）
    # allowedGroups: ['xxx'] # 只回复这些群 openid（空 = 全部）

配置项见插件 Config（lib/index.js）与下方「配置项一览」。

使用

命令	作用
任意消息	交给本会话的 Agent 处理并回复
#help	显示帮助
#status	显示接入通道、连接与会话状态
#reset	重置当前会话（清空上下文）

每个 QQ 会话的工作目录位于 <dsh 启动目录>/qqbot-chats/<会话键>（可在 workspaceRoot 配置中改；建议保持在 DSH 沙箱根内，否则文件类工具会被拦截）。

Agent 主动发消息（qq_send）

插件向所有 Agent（包括 web GUI 会话）注册 qq_send 工具：把文本发送给 “当前正在与这个 Agent 对话的 QQ 会话”。例如 Agent 在长时间任务中可以汇报进度， 或向用户提问。非 QQ 会话调用会得到明确报错。

注意：QQ 官方开放平台自 2025-04-21 起已停用主动消息能力，因此官方通道中的 qq_send 会明确报错；OneBot 通道不受此限制。官方被动回复仍受平台窗口和 “同一条入站消息最多回复 5 次”等限制，插件会在分块超过 5 条时拒绝发送，避免静默丢尾。

配置项一览

键	默认	说明
transport	onebot	onebot（OneBot 11）或 official（QQ 官方）
url	ws://127.0.0.1:3001	OneBot 正向 WS 地址
accessToken	''	OneBot token（Bearer）
reconnectDelayMs	3000	重连初始延迟，指数退避封顶 60s
appId	''	QQ 官方机器人 AppID
clientSecret	''	QQ 官方机器人 AppSecret
apiBase	https://api.sgroup.qq.com	官方 OpenAPI 域名
tokenUrl	https://bots.qq.com/app/getAppAccessToken	access_token 接口
sandbox	false	使用沙箱域名 sandbox.api.sgroup.qq.com
gatewayUrl	''	强制指定官方 WS 网关；留空自动获取
replyMaxChars	4500	单条回复字符上限，超出分块（官方通道另限 3000 字节）
workspaceRoot	<cwd>/qqbot-chats	会话工作目录根
persona	内置默认	附加到每个 QQ Agent 的系统提示词
preset	''（部署默认）	QQ Agent 挂载的 Agent 预设 id
allowedUsers	[]	允许私聊的 QQ 号/openid（空=全部）
allowedGroups	[]	允许回复的群号/群 openid/频道键 <guild_id>-<channel_id>（空=全部）
groupMentionOnly	false	群聊仅 @机器人 时回复
maxTurnMs	600000	单轮回复最长等待，超时后取消当前任务并提示
httpTimeoutMs	15000	QQ 官方 token/OpenAPI HTTP 请求超时（ms）
registerSendTool	true	是否注册 qq_send 工具

卸载

dsh plugin --profile web remove dsh-qqbot

安全注意

• QQ 机器人是无认证的入口：任何能向你机器人发消息的人都能使用 DSH 的 Agent 能力（包括 Shell）。请务必通过 allowedUsers / allowedGroups 限制可用范围，并只登录可信的 QQ 号。
• 审批（approval）弹窗仍会出现在 web GUI 中（policy 为 ask 时）；如果 需要 QQ 内审批，请自行扩展（例如把 qq_send 接到审批 answerer）。
• 工作目录默认位于 DSH 沙箱根内；改到别处时请同步调整 fs-sandbox.workspaceRoot，否则文件类工具会被沙箱拦截。

License

MIT