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)

integration
Searching Database…

1.2K ·GitHub
Qq-bridge
What is this?qq-bridge connects a QQ account (via the SnowLuma OneBot v11 client) to a DeepSeek Harness (DSH) AI agent: messages from QQ friends or groups become DSH chat turns, and the agent's replies (including questions and tool approvals) get sent back to QQ.
Is this a standalone app or a library I import?It's a standalone Node.js bridge process you run yourself: it opens a WebSocket connection to SnowLuma's OneBot API, relays messages to a running DSH instance, and exposes a local web console for configuration.
How do I get it running?Copy config.example.json to config.json, fill in your DSH/SnowLuma URLs and whitelist, then run `node src/bridge.js` (or start.bat on Windows) once DSH and SnowLuma are already running.
What do I need running before I start the bridge?A running DeepSeek Harness Web instance, a running SnowLuma client with its OneBot WebSocket and HTTP API enabled, and Node.js 22.13 or newer.
Any catches once it's set up?Replies are sent in one shot at the end of a turn (no streaming), images/voice/video become placeholder text, Markdown gets flattened to plain text, long replies over 4000 characters are auto-split, and only one bridge instance can run at a time.
What modes can the bridge run in?Four modes: chat (whitelisted groups/DMs get safe scripted chat), closed-agent (the owner's DMs get full tool access to control DSH from QQ), reserved (first-gen group-member simulation with an idle/active/probe/exit state machine), and reserved2 (second-gen simulation where the agent actively polls and sends messages via MCP tools).
What is SnowLuma?SnowLuma is the independent third-party OneBot v11 client that actually logs into QQ; qq-bridge talks to it over WebSocket/HTTP and is not affiliated with Tencent or QQ.
Can the agent search the web or control SnowLuma itself?Yes - besides the QQ messaging tools, the bridge ships a read-only web-search-safe MCP server with SSRF protection, and a snowluma-host MCP server that can start/stop SnowLuma, though process control is off by default and only works in closed-agent mode.
How does it handle quoted replies in group chats?Quoted/replied messages are parsed into 'quoted user + original text' and injected into the DSH context so the agent can tell who a message is really directed at, and quotes of the bot itself are treated as something it must respond to.
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
11.7 MB
Stars
1.2K
Updated
CommitOct 03Releasev0.2.0-r3Oct 03
Age
1mo
Commits · 90 Days