dsh-qq-bot

DeepSeek Harness 插件：通过 QQ 开放平台官方 WebSocket 网关和 REST API，将 QQ 群聊与单聊连接到独立的 dsh Agent。

• 不依赖第三方机器人框架，使用 Node.js 内置 WebSocket 和 fetch
• 每个 QQ 群或用户拥有独立 Agent 会话
• 支持 /new、/stop、/tools、/help，并可用 /whoami 自助发现 OpenID
• 消息按 Harness turn 精确关联，网关重连事件自动去重
• 主动消息和被动回复使用不同的 QQ 请求格式
• QQ Agent 默认不继承宿主工具，qq_send 只能发送到当前会话

前置条件

1. Node.js 22.6 或更高版本。
2. 已能运行 DeepSeek Harness，并配置了默认 provider/model。
3. 在 QQ 开放平台 创建机器人，取得 AppID 与 AppSecret。
4. 机器人已上线，或将需要测试的群和用户加入沙箱。

安装与加载

安装固定版本的开发依赖：

npm ci

通过 Cordis overlay 加载源码插件：

# cordis.yml（已被 .gitignore 忽略，请勿提交 AppSecret）
- insert:
    - id: qq-bot
      name: '/absolute/path/to/dsh-qq-bot/src/index.ts'
      config:
        appId: 'YOUR_APP_ID'
        clientSecret: 'YOUR_APP_SECRET'
        sandbox: false
        publicMode: false
        allowGroups: ['GROUP_OPENID_1']
        allowUsers: ['USER_OPENID_1']
        enableWhoami: true
        allowedTools: []

pnpm dsh web --patch ./cordis.yml

安全默认值

publicMode 默认为 false。此时只有 allowGroups 和 allowUsers 中的 QQ 身份能够访问 Agent；两个列表均为空时，普通消息会被拒绝并输出警告。

为了方便首次配置，enableWhoami 默认开启。白名单外用户只能调用不经过 Agent 的固定 /whoami（或 /id）响应，不能访问模型或宿主工具。若不需要身份发现，可设置 enableWhoami: false。

获取 OpenID

1. 保持 publicMode: false、enableWhoami: true。
2. 私聊机器人发送 /whoami，取得当前机器人的 user_openid；或在群里 @机器人并发送 /whoami，取得 group_openid。
3. 直接复制回复中的 allowUsers 或 allowGroups 配置片段到 cordis.yml，然后重载插件。

OpenID 不是 QQ 号或群号，并且只对当前机器人 AppID 有效。

配置其他工具

QQ Agent 默认只拥有绑定到当前会话的 qq_send(text)。普通回答本身会自动回到 QQ；qq_send 成功调用后会直接结束本轮，不会再补发“已回复用户”一类确认消息。

allowedTools 是权限白名单，不负责安装工具。要开放联网搜索、文件读取等能力，需要：

1. 先在 DSH 宿主中安装并加载对应工具插件或 MCP 服务。
2. 将该工具注册到 DSH 时使用的准确名称逐项加入 allowedTools。
3. 重载本插件，在 QQ 中发送 /tools 检查它是“已放行并加载”还是“已配置但未加载”。

例如，只有当宿主中确实存在名为 web_search 的工具时，下面的配置才会生效：

allowedTools:
  - web_search

若 /tools 显示“已配置但未加载”，通常是工具名不一致，或提供该工具的插件/MCP 服务尚未加载。

不要在公开机器人上开放 Shell、文件写入、任意网络请求或凭据相关工具。即使工具被后续热加载，运行时 guard 仍会拒绝未列入 allowedTools 的调用。

配置

只有确认机器人和宿主工具适合公开访问时，才应设置 publicMode: true。

命令

可靠性策略

• Agent 创建采用 single-flight，避免并发首条消息重复创建相同会话。
• 入站消息使用 QQ msgId 去重，并按 userMessage.id → turn → assistantMessage 路由回复。
• 被动回复的 msg_seq 按 msgId 独立递增；主动消息不携带 msg_id/msg_seq。
• qq_send 仅在发送成功后结束当前 Agent turn，避免模型再次生成发送确认。
• 超长文本按 Unicode code point 分片，不再截断丢失。
• Token 并发刷新合并为一个请求；401 会清理 Token 并重试一次。
• 网关采用指数退避，处理失效 Token、失效会话、限流和致命关闭码；心跳 ACK 丢失会主动重连。
• 插件卸载时等待所有 Agent 完成销毁，空闲会话按 TTL 回收。

开发

npm run check
npm run pack:check

npm run check 会执行严格 TypeScript 检查、Node 22 原生 strip-only 导入检查和单元测试。erasableSyntaxOnly 会在提交前拦截参数属性、枚举等需要转译的 TypeScript 语法；CI 重复运行相同检查。

已知限制

• 当前仅处理文本，未解析图片、表情和富媒体。
• 网关 session/sequence 只保存在进程内；进程重启后重新 Identify。
• QQ 主动与被动消息均受开放平台配额和时效限制。
• DeepSeek Harness 仍在快速迭代，本包暂时将整套 DSH peer dependency 固定到同一 release candidate。

License

MIT