qq-bridge：把 DeepSeek Harness AI Agent 接入 QQ，打造会「装潜水」的仿真群友机器人｜部署与使用全指南

适用版本：基于官方仓库 Derpyu520/qq-bridge 当前版本 v0.2.1-r1（适配 DeepSeek Harness 0.2.1-rc.2 / 0.2.0-rc.2）撰写。仓库创建于 2026-08，最新提交 2026-10，持续活跃维护中（2.6k+ stars）。

qq-bridge 是一个 QQ ↔ DeepSeek Harness（DSH）桥接器：QQ 好友/群发来的消息会变成 DSH 会话里的用户消息，AI Agent 的回复（含提问、工具审批请求）会自动发回 QQ。它不只是「问答机器人」——它主打AI 仿真群友：AI 会选择性参与话题、主动潜水、按空格分句发言，行为像真人，而不是每条消息都机械秒回。

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

一、项目介绍与适用场景

1.1 它是什么

qq-bridge 位于三个组件中间，扮演「翻译与安全层」：

1.2 适用场景

• 个人 QQ 助手：私聊问问题、查资料、操控 Agent 干活（closed-agent 模式）。

• AI 仿真群友：在白名单群里养一个「像真人的群友」，它会观望、试探、偶尔接话、主动收尾（reserved / reserved2 仿真模式）。

• Agent 远程入口：在外面用手机 QQ 就能给自己电脑上的 Agent 发任务、审批工具调用。

• 研究学习：OneBot v11 协议接入、MCP 安全工具设计、Token 成本看板等工程实践的优秀参考。

1.3 重要前提（部署前必读）

• 本项目面向 Windows：上游 SnowLuma 原生组件只有 win32-x64 版本，QQ 挂机也在 Windows 上完成。

• 需要两个 QQ 号：一个给机器人登录（SnowLuma），一个是你的日常号（在白名单里和它聊）。

• 有封号风险：SnowLuma 是非官方协议实现，与腾讯/QQ 无隶属关系，仅供学习研究，请自行阅读其 EULA 与《QQ 用户协议》，不要用主力大号跑机器人。

二、核心功能逐条拆解

1. 四种运行模式（控制台一键切换）： - chat：白名单群+白名单私聊 → qq-chat 安全聊天 preset； - closed-agent：仅私聊 owner → 完整工具（可在 QQ 上操控 DSH，等于随身 Agent）； - reserved（一代仿真）：状态机驱动的仿真群友（观望/活跃/试探/退场），按空格分句发送，支持输出 [SILENT] 表示潜水； - reserved2（二代仿真，安装脚本后的 DSH 默认）：AI 通过 qq_get_unread_messages / qq_send_message 等工具自主看消息、发言、等待、设置唤醒/潜水。

2. 安全 MCP 工具集：snowluma（查状态/查群/查消息/发消息，发送强制白名单+引用回复）、snowluma-host（只读探活）、web-search-safe（只读联网搜索，带 SSRF 防护）。

3. 本地 Web 控制台（http://127.0.0.1:3100）：十个页面（运行总览/会话与审批/人格与角色/二代仿真/一代仿真/黑话词库/令牌与花费/访问与安全/调试与运维/工具参考），浅色/深色主题，令牌登录。

4. 令牌与花费看板：实时 Token 消耗与折算金额（元），下钻到每个群/好友/每一轮，24h/3d/7d/30d 消耗走势图，按 DeepSeek 官方价目表区分高峰/空闲时段（高峰 2 倍价，内置中国法定节假日）。

5. 人格/角色扮演管理：双层提示词（仿真层=行为协议，人格层=人设语气）分别查看与修改；群友无法自改角色（仅控制台可设）。

6. 审批与提问回流 QQ：Agent 通过 ask_user_question 提问、请求工具审批时直接转发到 QQ，回复「通过/拒绝」即可决策。

7. 图片/表情（含 GIF）多模态：表情包 CDN 直链优先 + emoji_id 兜底，IPv4 优先+逐地址故障切换；单条消息上限默认 8MB/64MP/5 张。

8. 引用消息理解：群聊引用解析成「被引用人+原文」注入 DSH，不会把群友之间的引用误当成指向自己；引用机器人必回。

9. 黑话学习：自动提取群聊网络用语交给搜索后端研究（可关闭）。

10. 上游健康监测：检测 SnowLuma [Hook] 退化（「连上了但收不到」），控制台告警并给出明确指向。

三、全套官方链接

许可说明：仓库 License 为自定义许可（GitHub 标记 NOASSERTION），核心约束是桥接只探测、不部署 SnowLuma——SnowLuma 的安装、启动、扫码必须由你自己完成（源自 SnowLuma EULA §5.4）。

四、硬件与环境前置要求

4.1 软件环境

4.2 硬件

qq-bridge 本身是纯 JS 桥接，几乎不耗资源；瓶颈在 DSH 与模型：

• CPU/内存：整机 8GB 起步（DSH + SnowLuma + 桥接同机运行）。

• GPU：不需要（模型调用走 DeepSeek 云端 API）。

• 网络：能访问 DeepSeek API；SnowLuma 需要保持 QQ 在线。

• 磁盘：1GB 以内（不含 DSH 自身）。

4.3 费用认知

AI 消耗的是 DeepSeek API Token，按量计费。用控制台「令牌与花费」看板盯紧消耗；高峰时段（含节假日）单价是空闲时段的 2 倍。

五、完整部署（Windows 为主线，共 6 步）

官方明确：第 2、3 步最容易漏，漏了 QQ 上会毫无反应。

第 1 步：确认 DSH 已运行

打开 http://127.0.0.1:3080 能访问即可（DSH 安装与 DeepSeek API Key 配置见其官方文档/docs/guides/DSH_SETUP.md）。

第 2 步：安装桥接并复制配置

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

（macOS/Linux 用户把 copy 换成 cp；npm install 的 postinstall 会自动修补 @snowluma/sdk 的 ESM 打包 bug。）

第 3 步：安装 DSH 端（preset + MCP），然后重启 DSH

node scripts/setup-dsh.mjs

这一步做两件事：安装 qq-chat / qq-chat-v2 两个聊天 preset、挂载三个 MCP server。装完必须重启 DSH（preset 与 MCP 只在 DSH 启动时加载）。

安全设计：跳过这步桥接不会崩，但会拒绝建会话——绝不回退到带 bash/文件工具的默认 preset。全新环境脚本会把 DSH 默认模式设为 reserved2 并创建本地 state/mode.json 兜底。

第 4 步：下载并解压 SnowLuma

1. 到 https://github.com/SnowLuma/SnowLuma/releases/latest 下载 SnowLuma-v<版本>-win-x64.zip（完整版，自带 Node 运行时；Lite 版需本机 Node 22.13+）。

2. 解压到任意目录（例如 C:\SnowLuma），双击 launcher.bat。

注意：这一步必须你亲手做。桥接不会也不会被允许替你部署 SnowLuma（EULA §5.4 禁止自动化部署/Docker 打包，见第十一章）。

第 5 步：SnowLuma 首次引导 + 填写桥接配置

1. 打开 SnowLuma 启动日志里的 WebUI 地址（README 写的是 http://localhost:5099，以实际日志为准）。

2. 用启动日志中的初始密码登录：同意条款 → 设置密码 → 接入 QQ 进程（用机器人 QQ 号扫码登录）。

3. 在 WebUI 里配置 OneBot 连接：开启 WebSocket 服务端 和 HTTP API，分别记下端口（默认 WS 3001、HTTP 3000）和 accessToken（若配置了）。

4. 回到 config.json 填好 snowluma 段：

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

5. 把 allow.private / allow.groups 换成你自己的 QQ 号 / 群号。

⚠️ 示例模板里这两个白名单是空数组：空白名单 + allowAllWhenEmpty: false 时桥接不响应任何消息（刻意的 fail-closed 设计）。

第 6 步：启动桥接

npm start          # 前台运行

看到 SnowLuma 已连接 即成功；用你的 QQ 给机器人发条消息测试。

首次启动日志出现 SnowLuma 连接断开（code=1006） → 自愈 WS token → SnowLuma 已连接 是正常序列（HTTP token 与 WS token 是两个不同的值，桥接会自动重发现），不是故障。

关于 Linux / macOS / Docker

• Linux/macOS：桥接代码本身是纯 JS 可跨平台，但上游 SnowLuma 原生组件只有 Windows 版，QQ 协议层跑不起来，整条链路目前只能 Windows。

• Docker：不可用，也不允许。SnowLuma EULA §5.4 明确禁止将其并入 Docker 镜像或通过自动化脚本部署（须事先书面授权）；本项目 LICENSE 与 RULES.md 同样约定桥接「只探测、不部署」。请勿尝试打包，尊重上游许可。

六、config.json 全部参数解释

七、启动、后台常驻、开机自启与改端口

7.1 日常启动（官方推荐方式）

npm start      REM 前台运行（崩溃不自动重启）
start.bat      REM 守护模式：崩溃 5 秒后自动拉起（官方推荐，窗口别关）
restart.bat    REM 异常时用：杀旧实例 → 清理锁 → 重新启动守护

• 桥接只能运行一个实例（单实例锁，重复启动会被拒绝）。

• 重启 DSH 通常不需要动桥接：每 5 秒探活，DSH 不可用期间 QQ 消息在进程内排队（最多 50 条/会话，满后丢最旧），恢复后补投；桥接进程退出会丢内存队列。

• 改 config.json / roles/ / state/current-role.json 后重启桥接生效；改 dsh/agent-presets/ 后先跑 node scripts/build-agent-preset-patches.mjs 再重启 DSH。

7.2 Windows 开机自启（任务计划程序）

官方未内置自启，用系统自带「任务计划程序」最稳妥：

1. Win+R 运行 taskschd.msc → 创建任务。

2. 常规：勾选「不管用户是否登录都要运行」「使用最高权限运行」。

3. 触发器：登录时 / 系统启动时。

4. 操作：程序 cmd.exe，参数 /c cd /d C:\path\to\qq-bridge && start.bat。

5. 条件：取消「只在交流电供电时」等限制。

SnowLuma 与 DSH 同理各建一条（或用它们各自启动器自带的自启选项）。启动顺序：DSH → SnowLuma → 桥接（桥接有探活与排队机制，顺序不严格但建议如此）。

7.3 端口一览与修改

控制台只监听本机，属安全设计；确需远程访问请用 SSH 隧道或反向代理，并务必改掉默认 consoleToken。

八、功能实操教程

8.1 验证部署（不需要 QQ）

npm run self-test      # DSH 侧链路自测：连接 → 建测试会话 → 收到 agent 回复
npm run test:audit     # 完整离线回归（模拟服务，不发 QQ 消息）

8.2 第一次聊天

用你的 QQ 给机器人发消息 → 日志出现：

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

8.3 切换运行模式

浏览器打开 http://127.0.0.1:3100，输入 consoleToken（在 state/console-token 文件或启动日志里）登录 → 顶部按钮切换 chat / closed-agent / reserved / reserved2，控制台会同时写入 DSH 设置与本地兜底文件。

8.4 closed-agent：把 QQ 当远程 Agent 入口

切到 closed-agent 后，私聊机器人可以完整操控 DSH：让 Agent 提问时会转发到 QQ（回复即应答），请求工具审批时回复「通过/拒绝」即可，还能用 DSH 斜杠命令（如 /model）与 /reset（重置上下文）。

8.5 仿真群友（reserved2 二代仿真）

• 控制台「二代仿真 → 初始提示词」给某个群预写环境说明（圈子主题、氛围、忌讳），AI 只在该会话第一次唤醒时收到一次；重置会话后重新生效。

• AI 通过 qq_get_unread_messages 自主看消息，qq_send_message 发言，自己决定唤醒/潜水；引用某条消息用 qq_reply（配合 qq_get_group_history 拿真实消息 id）。

8.6 一代仿真（reserved）的分句与潜水

AI 用空格表示拆成多条消息（中英文间的空格也会分条，不想分条就不要加空格）；输出 [SILENT] 表示潜水不发送。

8.7 人格定制

• 「仿真提示词」管行为协议（保存同步到 DSH，需重启；保存前自动校验+备份，可一键还原）。

• 「人格提示词」（roles/*.md）管人设语气，保存即生效；支持新建/改名/副本/删除，超注入上限会实时提示。

• 角色由 state/current-role.json 注入，群友改不了。

8.8 Token 花费监控

控制台「令牌与花费」：累计总量取自 DSH tokenUsage 投影（精确含历史），逐轮明细含步数、缓存命中率、花费；走势图按高峰/空闲着色，一眼看出哪几个小时在烧 2 倍价。

8.9 发语音（可选）

AI 发语音默认关闭。把音频放进 audio/，控制台打开 socialV2.voice.enabled。独立的「发语音」工具在仓库上一级 ../voice-tool/（voice-cli.mjs 命令行 / voice-gui.mjs 图形界面），可给任意群/私聊发语音。注意：收到的语音目前只显示占位文本，不转写。

九、全套报错与故障排查

9.1 QQ 上完全没反应（最高频）

按官方提示依次检查：

1. 第 3 步漏了：没跑 node scripts/setup-dsh.mjs → 桥接拒绝建会话（安全设计）。跑完重启 DSH。

2. 白名单是空的：allow.private/allow.groups 没填你的 QQ 号 → fail-closed 不响应。

3. SnowLuma [Hook] 退化（「连上了但收不到」）：桥接 WebSocket 正常、日志打过「已连接」，但 QQ 消息一条不来。SnowLuma 自己的日志有： WARN [Hook] receive path stale: PID=… silentFor=…ms; reporting good=false 排查顺序：桥接控制台「运行总览」的 SnowLuma 上游 卡片 → SnowLuma 的 logs/snowluma-*.log 里的 [Hook] 行 → 升级 SnowLuma 运行时。

   注意：升级 SnowLuma 运行时不会更换原生注入组件（实测 1.14.9 与 1.14.20 的 native/*.dll/.node 逐字节相同），「hook 挂不上 QQ」类问题要走 SnowLuma 自己的排查。

4. DSH 没在跑：确认 http://127.0.0.1:3080 可访问；DSH 不可用期间消息会排队（50 条/会话上限）。

9.2 连接类

9.3 模型与消息类

9.4 版本适配速查（DSH 与桥接必须配套）

协议代次（Cookie 鉴权/斜杠 RPC//api/remote.mux 事件流）自 DSH 0.1.2-alpha.1 引入，与更早点号 endpoint 协议不兼容。

十、升级、回滚与卸载

10.1 升级桥接

cd qq-bridge
git pull
npm install          # 依赖有变化时；postinstall 会重新打 SDK 补丁
# 若 DSH 版本也升级了，重跑并重启 DSH：
node scripts/setup-dsh.mjs
# 重启桥接（守护模式）
restart.bat

升级后会为没有权限元数据的历史映射自动重建一次 QQ 会话；模式或 preset 变化也会自动重建，避免保留旧权限。

10.2 回滚

按 9.4 的版本表切换 tag：

git fetch --tags
git checkout v0.1.7        # 回到适配 DSH 0.1.7-rc.2 的版本
npm install

回滚前备份 config.json 与 state/（运行时数据不入库，git pull 不会动它们，但保险起见）。

10.3 卸载

1. 关闭桥接窗口 / 停止计划任务。

2. 删除 qq-bridge 目录（含 config.json、state/、audio/）。

3. DSH 侧清理：删除 profile 里桥接插入的 @deepseek-ai/dsh-agent-preset Cordis 行与 MCP 配置（可用 docs/guides/DSH_SETUP.md 的说明对照），重启 DSH。

4. SnowLuma 按其官方方式退出并卸载（QQ 扫码下线）。

十一、商用许可与合规风险提示

11.1 许可证

• qq-bridge 采用自定义许可（GitHub 识别为 NOASSERTION），使用前务必阅读仓库 LICENSE 与 RULES.md。

• 核心条款：桥接只探测、不部署 SnowLuma——不能把它做成一键安装包/Docker 镜像去自动化部署 SnowLuma。

11.2 SnowLuma EULA 与 QQ 协议风险（重点）

• SnowLuma 是独立第三方项目，与腾讯/QQ 无隶属关系；其原生组件通过 hook 挂进 QQ 客户端进程，属专有组件。

• SnowLuma EULA §5.4：并入第三方安装包/Docker 镜像、通过自动化脚本部署须事先书面授权。

• 非官方协议客户端违反《QQ 用户协议》，存在封号风险：不要用主力号，不要在机器人群里大规模部署，仅供学习研究。

• qq-bridge 自身无任何原生/注入面（纯 JS、无 dll/FFI）——「QQ 注入失败」永远不是桥接造成的。

11.3 数据隐私（数据出机清单）

• 群聊/私聊文本会发送给 DeepSeek API（云端）；联网搜索优先复用 DSH 的 DeepSeek 搜索（Bing 仅兜底），黑话学习会把群聊提取的词条交给搜索后端。

• 不需要就把 slang.autoResearch 关掉，或把 webSearch.provider 设为 bing；具体数据出机清单见 LICENSE。

• 控制台含令牌与花费数据，consoleToken 保存好；桥接只监听本机回环，不要随意暴露到公网。

11.4 内容安全

• allowAllWhenEmpty: true 等于把账号控制权完全交给模型，官方强烈建议先填白名单。

• closed-agent 模式赋予完整工具（含 bash/文件），只对私聊 owner 开放；群聊 preset 特意不带危险工具，且 0.2.0 起新增 15 个必须隐藏的工具名进安全守卫名单。

附录：命令速查

git clone https://github.com/Derpyu520/qq-bridge.git && cd qq-bridge
npm install                          # 安装（postinstall 自动修 SDK bug）
copy config.example.json config.json # Windows CMD / 其余平台用 cp
node scripts/setup-dsh.mjs           # DSH 端安装（装完重启 DSH！）
npm start                            # 前台启动
start.bat / restart.bat              # 守护模式 / 清锁重启
npm run self-test                    # DSH 链路自测
npm run test:audit                   # 完整离线回归
npm run test:tokens / test:console-ui# 看板与控制台回归
node scripts/build-agent-preset-patches.mjs  # 改 preset 后重新生成 bundle

免责声明：本文为技术教程。非官方协议实现存在封号风险，免费/付费额度与价格以 DeepSeek 官方为准；请遵守当地法律法规、SnowLuma EULA 与《QQ 用户协议》。