qq-bridge README

The project's README from github.com/Derpyu520/qq-bridge. As one markdown file: README.md.

QQ ↔ DeepSeek Harness 桥接

English: README.en.md | 中文: README.md

📘 详细内外核说明书见 docs/PROJECT_GUIDE.md（架构、数据流、配置全解、调试与改进指南）。

把 QQ 消息接入 DSH agent：QQ 好友/群发来的消息会变成 DSH 会话里的用户消息，agent 的回复（含提问、工具审批）会发回 QQ。

QQ 消息 ──► SnowLuma（OneBot v11 WS）──► 本桥接进程 ──► DSH Web API (127.0.0.1:3080/api)
                                                ▲                      │
                                                └── agent 回复/提问/审批 ┘

项目展示

📽️ AI 仿真群友 - 项目介绍视频

视频文件位于 assets/project-intro.mp4，可直接下载观看。

架构

前置条件

  1. 运行中的 DeepSeek Harness Web（默认 http://127.0.0.1:3080）
  2. 运行中的 SnowLuma，且配置好 OneBot WebSocket 与 HTTP API（默认 ws://127.0.0.1:3001 / http://127.0.0.1:3000，accessToken 视配置填写）
  3. Node.js ≥ 22.13

安装与配置

npm install        # 安装依赖（postinstall 会自动修补 @snowluma/sdk 的 ESM 打包 bug）

复制 config.example.json 为 config.json 后编辑：

Windows CMD 用户请用：copy config.example.json config.json

⚠️ 真实 config.json 与 state/ 不会进入公开仓库，仓库只提供脱敏的 config.example.json 模板。

字段 说明
dsh.baseUrl DSH Web 地址，默认 http://127.0.0.1:3080
dsh.provider / dsh.model / dsh.reasoningEffort DSH 会话使用的模型/推理强度；若你的 DSH 没有示例中的模型，改成 DSH 设置页里可用的模型即可（选择失败只打日志，不阻塞启动）
snowluma.wsUrl SnowLuma OneBot WebSocket 地址（如 ws://127.0.0.1:3001）
snowluma.httpUrl OneBot HTTP API 地址（如 http://127.0.0.1:3000）；不要填 WebSocket 端口，否则会报 HTTP 426
snowluma.accessToken OneBot accessToken，未配置留空
snowluma.launcherPath / homeDir SnowLuma 启动脚本与安装目录（供 agent 自动启动/停止）
agentPreset QQ 会话使用的 DSH agent preset，默认 qq-chat（改性格见下文）
socialV2.agentPreset reserved2 模式使用的 DSH agent preset，默认 qq-chat-v2
workspaceTitle QQ 会话在 DSH 界面中的归组名称，默认「QQ 聊天」
allow.private / allow.groups 白名单（QQ 号/群号数组）；留空且 allowAllWhenEmpty: true 时放行全部
deny.* 黑名单，优先于白名单
ackMessage 消息投递后的立即回复，空字符串关闭
sendDelayMs QQ 连续发送间隔，防止触发频率限制
consolePort 本地控制台端口，默认 3100
consoleToken 控制台访问令牌；留空时启动自动生成并保存到 state/console-token

⚠️ allowAllWhenEmpty: true 表示「白名单没填就全部放行」——把 agent 接入 QQ 等于把账号控制权交给了模型，建议先填白名单。

DSH 端安装（另一台设备 / 新环境）

桥接和控制台能跑起来还不够，DSH 端还需要安装两个聊天 preset（qq-chat / qq-chat-v2）并挂载 MCP：

node scripts/setup-dsh.mjs

全新环境下脚本会把 DSH 默认模式设为 reserved2（二代仿真），并创建本地 state/mode.json 兜底；这样 AI 使用 qq_send_message 等工具收发消息时，DSH 会自动使用 qq-chat-v2 模式。如果本机已存在旧的 state/mode.json 或 DSH 设置值，脚本会保留不覆盖，可手动在 DSH 设置页的 qq-mode 卡片切换。

详细步骤见 docs/DSH_SETUP.md。

完整启动流程（从零开始）

共 5 步，DSH 和桥接都已就绪，缺的只是 SnowLuma 本体：

  1. DSH（已运行，无需操作） 确认 http://127.0.0.1:3080 能打开即可。

  2. 下载并解压 SnowLuma

  3. 首次引导（WebUI）

    • 打开启动日志里的 WebUI 地址（README 写的是 http://localhost:5099，以你启动日志里实际打印的为准）
    • 用启动日志中的初始密码登录，按引导：同意条款 → 设置密码 → 接入 QQ 进程（扫码登录）
    • 在 WebUI 里配置 OneBot 连接：开启 WebSocket 服务端 和 HTTP API，分别记下端口（默认 WS 3001、HTTP 3000）和 accessToken（若配置了）

  4. 填写桥接配置（config.json）

    "snowluma": {
  "wsUrl": "ws://127.0.0.1:3001",
  "httpUrl": "http://127.0.0.1:3000",
  "accessToken": "你在 WebUI 里配置的 token（没配置就留空）"
}

    wsUrl 是 OneBot WebSocket 端口，httpUrl 是 OneBot HTTP API 端口（不要填成同一个 WS 端口，否则 MCP 工具会报 HTTP 426）。 建议顺手把 allow.private / allow.groups 白名单填上。

  5. 启动桥接

    cd qq-bridge
npm start          # 或双击 start.bat

    看到 SnowLuma 已连接 即成功；然后 QQ 上给机器人账号发条消息测试。

运行与运维

npm start          # 或双击 start.bat（守护模式：崩溃自动重启，关闭窗口即停止）

⚠️ 重要：

日志示例：

12:00:01 [bridge] SnowLuma 已连接：ws://127.0.0.1:3001
12:00:02 [bridge] 新会话 private:12345678 -> sess_xxxx
12:00:02 [bridge] 已投递 private:12345678: 你好
12:00:20 [bridge] agent 回复 (private:12345678) 42 字


## 自测（不需要 SnowLuma / QQ）

验证 DSH 侧链路是否打通（会创建一个独立测试会话，不影响现有会话）：

```bash
npm run self-test

预期输出：连接成功 → 测试会话创建 → prompt 被接受 → 打印 agent 回复。

目录结构

qq-bridge/
  config.example.json   # 配置模板（脱敏占位符；真实 config.json 不入库）
  docs/
    PROJECT_GUIDE.md    # 公开版项目说明书
  dsh/agent-presets/    # qq-chat / qq-chat-v2 的 DSH agent preset 模板
  plugins/qq-mode-console  # DSH 设置页 qq-mode 卡片插件
  src/
    bridge.js           # 主程序
    dsh-client.js       # Node 版 DSH API 客户端（WS 下行）
    md-to-plain.js      # Markdown → QQ 纯文本
    self-test.js        # DSH 侧自测
  scripts/              # 测试/运维脚本（含 postinstall 的 patch-snowluma-sdk.mjs）
    patch-snowluma-sdk.mjs  # 修补 SDK 的 ESM 打包 bug（postinstall 自动执行）
  state/                # 运行时数据（不入库）

已知限制

合规提醒

SnowLuma 是独立第三方项目，与腾讯/QQ 无隶属关系，仅供学习与技术研究；使用前请阅读其 EULA 与《QQ 用户协议》。

qq-bridge (Derpyu520/qq-bridge)

Searching Database…

1.1K ·GitHub
Qq-bridge
Что это?qq-bridge соединяет аккаунт QQ (через клиент SnowLuma OneBot v11) с ИИ-агентом DeepSeek Harness (DSH): сообщения от друзей или из групп QQ превращаются в ходы чата DSH, а ответы агента (включая вопросы и подтверждения инструментов) отправляются обратно в QQ.
Это отдельное приложение или библиотека, которую я подключаю?Это отдельный процесс-мост на Node.js, который вы запускаете сами: он открывает WebSocket-соединение с OneBot API SnowLuma, передаёт сообщения запущенному экземпляру DSH и предоставляет локальную веб-консоль для настройки.
Как его запустить?Скопируйте config.example.json в config.json, укажите свои URL-адреса DSH/SnowLuma и белый список, затем выполните `node src/bridge.js` (или start.bat в Windows), когда DSH и SnowLuma уже работают.
Что должно работать перед запуском моста?Работающий экземпляр DeepSeek Harness Web, работающий клиент SnowLuma с включёнными OneBot WebSocket и HTTP API, а также Node.js 22.13 или новее.
Есть ли подводные камни после настройки?Ответы отправляются одним сообщением в конце хода (без потоковой передачи), изображения/голос/видео превращаются в текст-заполнитель, Markdown упрощается до обычного текста, длинные ответы свыше 4000 символов автоматически разбиваются, и одновременно может работать только один экземпляр моста.
В каких режимах может работать мост?Четыре режима: chat (в группах и личных сообщениях из белого списка — безопасный сценарный чат), closed-agent (в личных сообщениях владельца — полный доступ к инструментам для управления DSH из QQ), reserved (симуляция участников группы первого поколения с конечным автоматом idle/active/probe/exit) и reserved2 (симуляция второго поколения, где агент активно опрашивает и отправляет сообщения через MCP-инструменты).
Что такое SnowLuma?SnowLuma — это независимый сторонний клиент OneBot v11, который непосредственно входит в QQ; qq-bridge общается с ним по WebSocket/HTTP и не связан с Tencent или QQ.
Может ли агент искать в интернете или управлять самим SnowLuma?Да — помимо инструментов для обмена сообщениями в QQ, мост включает безопасный для веб-поиска MCP-сервер (только для чтения, с защитой от SSRF) и MCP-сервер snowluma-host, который может запускать и останавливать SnowLuma, но управление процессами по умолчанию выключено и работает только в режиме closed-agent.
Как обрабатываются цитаты и ответы в групповых чатах?Цитируемые сообщения и ответы разбираются в формат «пользователь + исходный текст» и добавляются в контекст DSH, чтобы агент понимал, кому на самом деле адресовано сообщение, а цитаты самого бота считаются тем, на что он обязан ответить.
What are similar projects?dsh-bridge, WhaleIsle, dsh-tavern, dsh-our-free-model, dsh-antibrow, evenfire, DSH-Plugins-Marketplace, dsh-crew
Which topics is it in?qq-bot, integration, dsh, deepseek-harness, websocket, chatbot, deepseek, proxy, china, mcp-server, ai-agent, agent
Creator
Derpyu520
Size
12.1 MB
Stars
1.1K
Updated
CommitOct 03Releasev0.2.0-r3Oct 03
Age
1mo
Commits · 90 Days