qqbridge-dot-backend

让你在 ChatGPT 中的真实 Dot 通过 SnowLuma + QQBridge 接收 QQ 消息，并使用 MCP 工具回复。

已验证真实事件唤醒，以及私聊的自动领取、读取、发送和收尾。支持纯 Dot 后端：全部显式白名单会话由 Dot 接管，不需要运行 DSH；也保留按会话混合后端的兼容方式。0.4.0 新增按消息读取图片、原图转发和发送 ChatGPT 图片文件；Dot 生成的新图片也通过文件发送入口传回 QQ。图片的真实账号识图与生成回传需按下方指南另行验收。

先理解这条链路

你发 QQ 消息
  → SnowLuma 收到消息
  → QQBridge 入库并生成唤醒
  → MCP 网关把事件发送给已订阅的 Dot
  → ChatGPT Dot 领取、读取、判断是否回复
  → 调用 QQ 工具发送，最后显式收尾

本机运行的是桥接、工具和事件服务，负责思考和回复的是 ChatGPT Dot。工具调用通过官方 Secure MCP Tunnel 抵达本机，事件通过签名 HTTPS 回调抵达 ChatGPT；本地网关不调用模型 API。

本机服务启动、隧道连接、插件连接、事件订阅、实际回复是五个检查点。 只看到“插件已连接”还需要继续完成订阅和收发验证。

Related MCP server: QQ MCP

新手接入：先跑通自己的私聊

下面以 Windows + PowerShell 为例，工作目录使用 C:\bots。示例 QQ 号 10001、群号 123456789 和目录都必须替换成自己的实际配置。

1. 准备环境和 QQ 消息入口

你需要：

• Node.js 24 和 Git，确认 node --version、git --version 能运行。

• 一套已登录 QQ、能正常运行的 SnowLuma。按你使用的发行版说明配置 OneBot HTTP / WebSocket；本例分别为 127.0.0.1:3000 和 127.0.0.1:3001。

• 能创建自定义 MCP 插件、能使用 Dot 事件任务的 ChatGPT 账号或工作区。相关功能受账号和工作区权限限制。

• Windows 原生管理器需要 .NET 10 SDK 构建；运行机器需要 .NET 10 Desktop Runtime。它能把各服务和日志放在同一窗口，不为每个组件打开终端。

先确认 QQ 登录正常，记下 SnowLuma 的实际安装目录、OneBot 地址和访问令牌。本仓库不分发 QQ 客户端或 SnowLuma；这些组件的安装与登录以其发行说明为准。

2. 下载项目并应用固定基线补丁

新建工作目录后执行：

New-Item -ItemType Directory -Path C:\bots -Force | Out-Null
Set-Location C:\bots
git clone https://github.com/UyNewNas/qqbridge-dot-backend.git
if ($LASTEXITCODE -ne 0) { throw '本仓库下载失败，请先检查目标目录和网络。' }
git clone -c core.autocrlf=false https://github.com/Derpyu520/qq-bridge.git
if ($LASTEXITCODE -ne 0) { throw 'QQBridge 下载失败，请先检查目标目录和网络。' }
git -C .\qq-bridge checkout --detach a49877f4e58d04e47532d44b803360d0f001160d
if ($LASTEXITCODE -ne 0) { throw '固定版本检出失败。' }

Set-Location .\qq-bridge
npm ci
if (-not (Test-Path .\config.json)) {
    Copy-Item .\config.example.json .\config.json
}

Set-Location ..\qqbridge-dot-backend
npm ci
node .\scripts\apply-qqbridge-patch.mjs --source ..\qq-bridge --check
node .\scripts\apply-qqbridge-patch.mjs --source ..\qq-bridge

这组命令用于全新副本。已有 QQBridge 配置或本地源码修改时，先保留原安装，按 适配指南 准备副本；安装器会校验固定 commit 和文件内容，不覆盖不匹配的源码，也不修改配置或会话状态。

QQBridge 仍会安装其原有 npm 依赖，但纯 Dot 模式不需要启动 DSH 程序。

3. 初始化凭据，配置自己的私聊

在 qqbridge-dot-backend 目录运行，先把 10001 替换成你的 QQ 号：

npm run setup:mcp -- --bridge-config ../qq-bridge/config.json --conversation private:10001

生成的文件都在本机 state/ 中：

已有配置不会被 setup 覆盖，后续修改直接编辑本机配置。打开 QQBridge 的 config.json，把以下字段合并进去，并保留其他配置：

{
  "ownerQQ": 10001,
  "allow": { "private": [10001], "groups": [] },
  "allowAllWhenEmpty": false,
  "socialV2": { "enabled": true },
  "dot": {
    "enabled": true,
    "only": true,
    "conversations": ["private:10001"],
    "tokenFile": "../qqbridge-dot-backend/state/dot-api-token",
    "leaseMs": 600000
  }
}

同时将原有 snowluma 配置中的 homeDir、wsUrl、httpUrl、accessToken 改成步骤 1 的实际值。tokenFile 相对 QQBridge 目录解析，必须指向本仓库生成的同一个 dot-api-token。

only=true 会把显式白名单中的全部会话交给 Dot，固定使用 reserved2 消息流程，停用 DSH 客户端、探活、设置同步、事件流和旧 DSH 黑话学习任务。还需确认 state/mcp-config.json 中的 conversations 是你刚配置的私聊。

4. 在管理器里启动服务

在本仓库的 PowerShell 窗口执行：

.\launcher\windows\build.ps1
$env:QQB_BRIDGE_DIR = 'C:\bots\qq-bridge'
$env:QQB_DOT_BACKEND_DIR = 'C:\bots\qqbridge-dot-backend'
$env:QQB_SNOWLUMA_DIR = 'C:\bots\SnowLuma'
Start-Process '.\launcher\windows\publish\GPTBot管理器.exe'

将 SnowLuma 目录换成实际目录，点击管理器的“一键启动”。纯 Dot 模式应只显示 SnowLuma、QQ Bridge、Dot MCP 三项。检查日志和“接入状态”，再回到 PowerShell 执行：

npm run check:mcp

此时应有 localMcpReady=true、bridgeReady=true，工具数量为 6，事件包含 qq.wake.available。subscriptions=0 在尚未创建订阅时是正常状态。

按各自方式启动 SnowLuma；在 QQBridge 目录运行 npm start，在本仓库运行 npm start，保持两个服务持续运行。Linux 可使用自己的服务管理器；Windows 管理器详细说明见 这里。

5. 创建并连接官方 Secure MCP Tunnel

按 官方隧道说明 在 Platform 隧道设置 创建或复用隧道，确认它关联到你要使用的 ChatGPT 工作区。记下自己的 tunnel_id。

创建或修改隧道需要 Tunnels Read + Manage；运行隧道客户端及在 ChatGPT 中选择隧道需要 Tunnels Read + Use。运行密钥使用 OpenAI Platform 中具有相应权限的凭据，不能拿 DeepSeek 或其他模型代理密钥替代。

从 官方 tunnel-client 仓库 下载与你系统架构匹配的发行包，按其校验文件验证下载。Windows 辅助脚本要求下列文件存在：

qqbridge-dot-backend/tools/tunnel-client/bin/tunnel-client.exe

在本仓库执行：

.\scripts\connect-tunnel.ps1 -CheckLocal
.\scripts\enter-tunnel-key.ps1 -TunnelId 'tunnel_your_id'

将示例 ID 替换成自己的完整隧道 ID。在弹出的 GPTBot 密码输入窗口填写运行密钥，点击 Verify and connect；看不到窗口时可用 Alt+Tab 查找。密钥只在进程内存中，脚本不保存到磁盘，也不要求你发到聊天里。

连接成功后，检查本机 state/tunnel-last-connect.json：processRunning、healthy、ready、remoteVerified 应全部为 true。保持隧道客户端运行。它与本地 Dot MCP 服务是不同进程；重启机器或隧道进程退出后，需要重新输入运行密钥连接。

6. 在 ChatGPT 添加 QQBridge Dot 插件

打开 ChatGPT 插件页：

1. 点击“添加 → 添加自定义 MCP 服务器”。

2. 名称填 QQBridge Dot，连接选择“隧道 / Tunnel”，填写同一个 tunnel_id。

3. 当前私有 stdio 接入没有 OAuth 服务，身份验证选择“无 / No authentication”。本地 Bearer 已由 stdio 适配器从本机文件读取。

4. 创建插件，确认能发现九个工具和事件 qq.wake.available。

5. 在 ChatGPT 调用 qq_get_status，确认 bridgeReachable=true，且会话列表包含自己的私聊。

平台和工作区权限仍然适用。插件显示“已连接”后，继续执行下一步；此时 subscriptions 仍可能为 0。

7. 在真正的 Dot 对话中创建订阅

下面这段发到 ChatGPT 中你的 Dot 对话窗口。 QQ 里的机器人此时负责接收普通消息，不能代替你在 ChatGPT 侧创建事件任务。

将以下示例中的 10001 换成自己的 QQ 号后发送：

使用 QQBridge Dot 插件。先调用 qq_get_status，并重新发现 qq.wake.available，确认 conversationKey 包含 private:10001。先列出任务避免重复；如果没有这个私聊的同类任务，创建精确过滤 {"conversationKey":"private:10001"} 的事件订阅。

我授权你正常处理这个私聊：收到唤醒后，用稳定 claimId 领取；分页读取当前会话消息；需要回复时用稳定 sendId 调用 qq_send_message，确认发送结果；最后用实际 readThroughSeq 作为 throughSeq，调用 qq_finish_turn，以 replied 或 silent 收尾。发送结果未知时不要换 ID 重发。保留其他已有订阅，先报告创建结果和状态。

确认 qq_get_status 返回该会话 subscribed=true。只有一个私聊订阅时，subscriptions 应为 1；这个数字是订阅总数，不是 QQ 消息数。

如果 Dot 说任务创建返回异常，先列出任务并检查实际订阅是否已保存，再决定重试，避免重复任务。

8. 发一条新 QQ 私聊，确认自动完成整轮

现在回到 QQ，给机器人发一条普通测试消息。首次唤醒按现有合并策略可能有延迟；它需要经过事件投递和 Dot 的处理，并不保证即时回复。

完整成功的证据是：

只在 Dot 对话里手动要求“处理待领取唤醒”后收到回复，可以验证工具链路；还需要发一条新 QQ 消息，确认事件订阅能自动唤醒 Dot。webhook 2xx 或 subscribed=true 也不能单独证明整轮完成。

图片输入、输出与生成图片

升级到 0.4.0 后，在当前回合收尾时重启 QQ Bridge 与 Dot MCP，然后到 ChatGPT 插件的“管理” → “管理应用” → “刷新工具”。原有事件订阅继续使用，不要重复创建任务。

让 Dot 重新列出工具，确认多出 qq_read_image、qq_forward_image、qq_send_image。随后给 Dot 这段补充指令：

对已经授权的 QQ 会话，读取消息后检查 images；用 messageSeq 和 imageIndex 调用 qq_read_image 看图，再回答。需要原图回传时调用 qq_forward_image。用户要求画图时，先使用你自己的图片生成能力，获得实际图片文件，再通过 qq_send_image 的原生 file 参数发送；不要手写 Base64、下载地址或本机路径。确认 send.status=confirmed 后，用实际 readThroughSeq 正常收尾。若图片生成或文件传递不可用，请如实说明，不能把文字描述当成已发图片。

在 QQ 私聊分别测试：发一张图并询问内容、要求把该图发回来、要求新画一张图并发回来。三项测试均要核对自动唤醒、图片工具调用、QQ 图片实际到达与 finished；工具列表出现不代表真实识图和生成已经验证。

支持 PNG、JPEG、GIF、WebP，单张最多 4 MiB、20 百万像素，单边最多 8192。图片链接不直接交给 QQ 下载；文件由本地网关安全下载并验证后发送。生成使用 Dot 本身的能力，本后端不另行调用图片生成 API 或使用隧道密钥计费生图。完整流程与限制见 图片接入指南。

角色卡与 QQ 人格

Dot 每轮领取时会拿到 QQBridge 当前选择的角色卡，并按该角色组织 QQ 回复。用 qq_get_status 的 persona 检查：configured 表示已选择角色，available 表示实际读到了有效内容，promptChars 是二代模式筛选后的注入长度。选了角色但 available=false 时，检查角色文件、名称和模式小节；人设行为仍需要通过真实回复验收。

如果某次模型身份回答不符合预期，先核对卡片本身是否要求披露模型身份。群聊口吻、角色自称和技术信息的回应范围可在本地卡片中设置；角色名不等于已核实的实际模型型号。卡片内容与旧会话的回复习惯是两个层面。详见 人格接入说明。

私聊跑通后，增加群聊或其他会话

以增加 group:123456789 为例：

1. QQBridge 的 allow.groups 增加目标群；本仓库 state/mcp-config.json 的 conversations 同时保留原私聊并加入目标群。

2. 当前回合收尾后，重启 QQ Bridge 和 Dot MCP。纯 Dot 模式会从白名单派生桥接归属。

3. 在 ChatGPT 打开 QQBridge Dot → 右上“管理” → 页面下方“管理应用” → “刷新工具”。

4. 让 Dot 重新发现事件，核对 schema 的 conversationKey 枚举已同时包含群聊和私聊。

5. 保留原私聊任务，去重后新增 {"conversationKey":"group:123456789"} 的订阅，并授权正常处理该群。

两个会话各有一个订阅时，应看到 subscriptions=2，两个 subscribed 都为 true。可访问范围、实际事件 schema 和订阅覆盖要同时核对。

常见问题：按证据定位

诊断字段 serverVersion、lastMetadataScan、lastEventDiscovery 和 lastSubscriptionAttempt 用于确认“刷新或订阅请求是否真的到达当前服务”。操作后只更新工具扫描记录，不代表事件扫描也已更新；服务器返回新 schema 而 Dot 仍显示旧 schema 时，继续核对应用版本和事件来源。

工具、限制和开发验证

九个工具为 qq_get_status、qq_list_wakes、qq_claim_turn、qq_read_messages、qq_read_image、qq_send_message、qq_forward_image、qq_send_image、qq_finish_turn。消息文本是待处理数据，不授予工具或跨会话权限。发送使用稳定 ID，读取和已读确认分开，静默也需要收尾。

当前支持文本与图片收发，尚未迁移 DSH 模型配置、完整对话历史、独立研究、语音和独立贴纸库工具。网关使用加密 SQLite 保存订阅、outbox 和发送预留，但 QQBridge 的运行账本仍在进程内，未知发送需要核实。

npm run format:check
npm test
npm run demo
$env:QQBRIDGE_SOURCE_DIR = 'C:\bots\qq-bridge'
npm run test:integration

组件测试使用真实 bridge.js，并用本地替身隔离 QQ、DSH 和回调服务，不发送真实 QQ 消息；缺少源码或补丁时会失败，不会跳过。真实联调和测试结果见 验证记录，各提交的 CI 见 GitHub Actions。

凭据与许可

state/、运行日志、环境文件和下载的隧道二进制已从 Git 排除。令牌、隧道运行密钥、数据库及其 .key 文件保留在本机；提交前仍应检查暂存区。初始化脚本不覆盖已有凭据，隧道密码窗口不保存运行密钥。

本仓库原创内容使用 MIT 许可，QQBridge 原始许可完整保存在 UPSTREAM-LICENSE，包含上游公开署名及其原有联系信息。本项目与 QQBridge、SnowLuma 或 OpenAI 无官方关联。package.json 的 private=true 只防止误发布到 npm。

协议和产品操作参考：MCP Events、Secure MCP Tunnel、插件连接与刷新。工作区策略和界面变化时，以官方文档与当前实际界面为准。