DotCraft QQ 渠道适配器

@dotcraft/channel-qq 通过 WebSocket 外部渠道协议将 QQ 接入 DotCraft。适配器连接 DotCraft AppServer，并在本地提供 OneBot v11 反向 WebSocket 服务，供 NapCat 等 OneBot 实现连接。

功能概览

• 通过 WebSocket 连接 DotCraft AppServer
• 提供 OneBot v11 反向 WebSocket 服务
• 支持 QQ 私聊和群聊
• 群聊默认仅在 @机器人 时响应
• 每个 QQ 私聊用户或群聊映射到独立 DotCraft thread
• 支持 QQ 会话内审批
• 提供语音、视频、文件相关 Runtime 工具

使用第三方 QQ 协议框架存在账号风险，请自行评估。

前置条件

需求	说明
QQ 账号	用作机器人的 QQ 号，建议使用小号
OneBot v11 实现	推荐 NapCat，负责登录 QQ 并连接反向 WebSocket
DotCraft AppServer	需要启用 WebSocket 模式
QQ 渠道包	发布包中位于 resources/modules/channel-qq，开发环境中位于 sdk/typescript/packages/channel-qq

1）工作区配置（.craft/config.json）

在工作区 .craft/config.json 中启用 AppServer WebSocket，并注册 QQ 外部渠道：

{
  "AppServer": {
    "Mode": "WebSocket",
    "WebSocket": {
      "Host": "127.0.0.1",
      "Port": 9100,
      "Token": ""
    }
  },
  "ExternalChannels": {
    "qq": {
      "enabled": true,
      "transport": "websocket"
    }
  }
}

2）适配器配置（.craft/qq.json）

在目标工作区创建 .craft/qq.json：

{
  "dotcraft": {
    "wsUrl": "ws://127.0.0.1:9100/ws",
    "token": ""
  },
  "qq": {
    "host": "127.0.0.1",
    "port": 6700,
    "accessToken": "",
    "adminUsers": [123456789],
    "whitelistedUsers": [],
    "whitelistedGroups": [],
    "approvalTimeoutMs": 60000,
    "requireMentionInGroups": true
  }
}

字段说明：

配置项	说明	默认值
dotcraft.wsUrl	DotCraft AppServer WebSocket 地址	ws://127.0.0.1:9100/ws
dotcraft.token	AppServer WebSocket Token	空
qq.host	OneBot 反向 WebSocket 监听地址	127.0.0.1
qq.port	OneBot 反向 WebSocket 监听端口	6700
qq.accessToken	OneBot 鉴权 Token，需与 NapCat 一致	空
qq.adminUsers	管理员 QQ 号列表	[]
qq.whitelistedUsers	白名单用户 QQ 号列表	[]
qq.whitelistedGroups	白名单群号列表	[]
qq.approvalTimeoutMs	操作审批超时，毫秒	60000
qq.requireMentionInGroups	群聊是否必须 @ 机器人	true

如果 adminUsers、whitelistedUsers、whitelistedGroups 都为空，适配器不会响应任何 QQ 用户。请至少配置一个管理员。

3）配置 NapCat

在 NapCat WebUI 中创建 WebSocket 客户端（反向 WS）：

1. URL 填写 ws://127.0.0.1:6700/。
2. Token 填写与 qq.accessToken 相同的值。
3. 消息格式选择 array。

如果 NapCat 运行在 Docker 或另一台机器上，请把 127.0.0.1 替换为 QQ 适配器所在机器的可访问地址。

4）启动

Desktop 会从打包资源中识别 qq-standard 外部渠道，可在渠道管理界面启动。

开发环境可以直接运行：

cd sdk/typescript
npm run build --workspace @dotcraft/channel-qq
npx dotcraft-channel-qq --workspace F:\dotcraft

也可以在包目录下运行：

cd sdk/typescript/packages/channel-qq
npm run build
npm start -- --workspace F:\dotcraft

使用说明

• 群聊默认只响应 @ 机器人的消息。
• 私聊会进入对应用户的独立会话。
• 每个 QQ 群或私聊用户映射到独立 DotCraft thread。
• 管理员触发需要审批的操作时，适配器会在 QQ 会话里发送审批提示。
• 回复 同意、允许、yes、approve 会通过审批；回复 拒绝、no、reject、deny 会拒绝审批。

Runtime 工具

QQ 渠道提供以下工具，供 Agent 执行显式跨目标投递：

工具	目标	来源
QQSendGroupVoice	QQ 群	本地路径、HTTP URL、base64://...
QQSendPrivateVoice	QQ 用户	本地路径、HTTP URL、base64://...
QQSendGroupVideo	QQ 群	本地路径、HTTP URL
QQSendPrivateVideo	QQ 用户	本地路径、HTTP URL
QQUploadGroupFile	QQ 群	本地绝对路径
QQUploadPrivateFile	QQ 用户	本地绝对路径

这些工具由适配器通过 external channel capabilities 暴露。工具名保持 PascalCase。