Qq Bridge

qq-bridge

English · 安装指南 · 问题反馈

qq-bridge 是一个本地消息桥接工具，在 SnowLuma 提供的 OneBot v11 接口与 DeepSeek Harness（DSH） 之间转发消息事件和 AI 回复。

当前候选版本：v0.2.2-rc1（GitHub prerelease），适配目标为 DSH 0.2.2-rc.1。

[!IMPORTANT] qq-bridge 是独立维护的第三方工具，不是 SnowLuma 的子项目，也不隶属于 SnowLuma、DeepSeek 或腾讯 / QQ。 本项目通过 SnowLuma 提供的 OneBot v11 接口互通；桥接与 SnowLuma 后端分别部署、独立维护，无隶属、合作或背书关系。OneBot v11 是公开协议，并非 SnowLuma 专有协议。

术语与边界：本项目不向 QQ 客户端或 SnowLuma 进程注入、挂钩，不修改 SnowLuma 本体或其原生组件；但会读取本机 OneBot 配置与接入令牌、连接 OneBot 接口，并在 npm install 时修补本机 @snowluma/sdk 的 ESM 导入。文档中的“人格注入”指提示词写入，“提示注入”指不可信内容攻击；上游 [Hook] 仅指 SnowLuma 的接入机制，不是本项目的行为。

QQ ↔ SnowLuma ↔ qq-bridge ↔ DeepSeek Harness ↔ 模型服务
             OneBot v11

能做什么

快速开始

准备好 Windows 10 / 11、Node.js ≥ 22.13（与 DSH 0.2.2 同机部署需 ≥24.9），以及以下两个独立运行的服务：

• DSH Web：当前有 0.2.2-rc.1 的验证记录（上一版为 0.2.1-rc.2），其他版本见兼容范围。
• SnowLuma：请自行按上游文档安装、启动并登录，开启 OneBot WebSocket 服务端和 HTTP API。

1. 获取项目

在 PowerShell 中运行：

git clone https://github.com/Derpyu520/qq-bridge.git
cd qq-bridge
npm install
Copy-Item config.example.json config.json

默认分支 main 为正式发布线；dev 用于开发与测试。

2. 填写配置

编辑 config.json，至少核对这些字段：

同机运行时，dsh.authToken 通常留空，由桥接使用本机 DSH 凭据完成鉴权。完整配置与连接排查见安装指南。

3. 安装 DSH 插件

node scripts/setup-dsh.mjs

这一步会把聊天预设和 MCP 工具接入 DSH，首次安装也必须执行。完成后重启 DSH；使用非 web profile 时见安装指南。

4. 启动并测试

npm start

打开 本地控制台 并输入控制台令牌。自动生成的令牌保存在 state/console-token；如果已在 config.json 配置 consoleToken，则使用该值。启动日志不会打印令牌。新装默认使用二代仿真模式（reserved2），会选择性发言；测试收发时可先切到 chat，再从白名单会话发送消息。

Windows 也可双击 start.bat 以守护模式运行，关闭窗口即停止。

文档与开发

开发基于 dev，提交 PR 前运行离线回归：

npm run test:audit

使用边界与许可

• 仅在知情并获准的会话中使用，遵守平台规则；使用非官方 QQ 后端可能导致账号受限。
• 聊天内容会经 DSH 发送给所配置的模型服务；黑话自动研究默认开启，可能将提取的关键词发送给搜索服务。数据流与关闭方式见 NOTICE。
• 保护 config.json、state/ 与控制台令牌，保持服务仅在本机可访问。
• DSH 离线期间的消息队列仅保存在内存中，每个会话最多 50 条；桥接进程退出后队列丢失，不保证送达。
• 本工具不实现 QQ 登录或底层协议，不安装、打包或启停 SnowLuma 后端；当前客户端仍依赖 @snowluma/sdk 等包，第三方组件适用各自条款。

当前代码按 PolyForm Noncommercial 1.0.0 提供，限非商业用途；v0.2.1-r1 及更早已发布版本沿用其发布时的 MIT 许可。第三方组件、独立关系与使用风险见 NOTICE。