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 webQQ 官方通道（任选其一）：
方式 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