【免费下载链接】qq-bridge
Bridge between QQ (SnowLuma OneBot v11) and DeepSeek Harness agents: social simulation, safe MCP tools, slang learning and more.
项目地址：
https://gitcode.com/gh_mirrors/qq/qq-bridge
点击查看 免费下载
qq-bridge 是一个把 QQ 接入 DeepSeek Harness（DSH）agent 的开源桥接工具：QQ 好友/群里的消息会变成 DSH 会话中的用户消息，agent 的回复、提问和工具审批再发回 QQ。跟着这份部署教程，新手大约 30 分钟就能在 QQ 群里养出一位会聊天、会潜水、还会学网络黑话的 AI 群友。
为什么选 qq-bridge：让 AI 真正「住进」QQ 群
qq-bridge 的核心价值，是不写一行代码就把本地运行的 DeepSeek Harness 变成 QQ 里一个真实的群成员。整体链路如下：
QQ 消息 ──► SnowLuma（OneBot v11 WS）──► qq-bridge 进程 ──► DSH Web API（127.0.0.1:3080）
▲ │
└── agent 回复/提问/审批 ┘
功能亮点一览：
| 独立会话 | 每个 QQ 私聊/群对应一个独立 DSH 会话，统一归组到「QQ 聊天」工作区 |
| 4 种运行模式 | 安全聊天 / 封闭 agent / 一代仿真 / 二代仿真，控制台一键切换 |
| AI 自主收发 | 二代仿真模式下 AI 自主看消息、决定何时发言、何时潜水 |
| 本地控制台 | 10 个页面的 Web 控制台，带实时 token 花费看板 |
| 人格定制 | roles/ 目录下一个 Markdown 文件就是一套人格，改完下条消息生效 |
| 黑话学习 | 自动提取群聊新词并联网研究，让 AI 的梗更「接地气」 |
部署前准备：先备齐 3 个前提条件
开始安装前，请确认本机已具备：
⚠️ 合规提醒：SnowLuma 是独立的第三方 QQ 接入程序，它的下载、启动、扫码登录都由你自己完成——qq-bridge 只探测、不部署，权限边界详见 RULES.md。
第 1 步：安装 qq-bridge 并创建配置文件（约 5 分钟）
git clone https://gitcode.com/gh_mirrors/qq/qq-bridge.git
cd qq-bridge
npm install
npm install 会自动修补 @snowluma/sdk 的 ESM 打包 bug（由 postinstall 钩子完成，见 scripts/patch-snowluma-sdk.mjs），无需额外操作。
接着复制模板配置文件：
cp config.example.json config.json
Windows CMD 用户请改用：copy config.example.json config.json
config.example.json 字段较多，新手只需先弄懂这几个核心项：
| dsh.baseUrl | DSH Web 地址，默认 http://127.0.0.1:3080 |
| dsh.model | 会话模型，默认 deepseek-flash（多模态）即可 |
| snowluma.wsUrl | OneBot WebSocket 地址，如 ws://127.0.0.1:3001 |
| snowluma.httpUrl | OneBot HTTP API 地址，如 http://127.0.0.1:3000 |
| allow.private / allow.groups | 白名单：你自己的 QQ 号 / 群号数组 |
🔒 安全默认值：模板里白名单为空，且 allowAllWhenEmpty 为 false，桥接会拒绝响应任何消息（刻意的 fail-closed 设计）。建议先填好白名单再启动，等于把账号控制权交给模型前加一道锁。
第 2 步：一键安装 DSH 端 preset 与 MCP（最容易漏的一步）
只有桥接进程跑起来还不够——DSH 端还需要安装两个聊天 preset（qq-chat / qq-chat-v2）并挂载 3 个安全 MCP 工具。漏掉这一步，桥接会拒绝建会话（绝不回退到带 bash/文件工具的默认 preset），表现就是 QQ 上发了消息毫无反应。
在 qq-bridge 根目录执行：
node scripts/setup-dsh.mjs
scripts/setup-dsh.mjs 会一次性完成：
- 安装 qq-chat / qq-chat-v2 两个 preset（模板在 dsh/agent-presets/）；
- 挂载 mcp-snowluma（QQ 收发安全子集：查状态/查群/查消息/发消息，发送强制白名单）、mcp-snowluma-host（只读探活）、mcp-web-search-safe（带 SSRF 防护的只读搜索）；
- 把默认运行模式设为二代仿真（reserved2），并创建本地 state/mode.json 兜底。
脚本是幂等的，重复执行不会破坏已有配置。执行完必须重启 DSH——preset 与 MCP 只在 DSH 启动时加载。
完整步骤与 DSH 端疑难杂症排查，看官方指南 docs/guides/DSH_SETUP.md。
第 3 步：SnowLuma 登录与白名单配置
如果 SnowLuma 还没做过首次引导：
回到 config.json 填好 snowluma 段和白名单：
"snowluma": {
"wsUrl": "ws://127.0.0.1:3001",
"httpUrl": "http://127.0.0.1:3000",
"accessToken": ""
},
"allow": {
"private": [12345678],
"groups": [876543210]
}
⚠️ 高频踩坑：httpUrl 别填成 WebSocket 端口，否则发送消息会报 HTTP 426（Upgrade Required）。拿不准时跑一下诊断脚本 node scripts/check-onebot-status.mjs。
启动桥接：30 分钟见证 AI 群友上线
前台启动：
npm start
Windows 用户更推荐双击 start.bat（守护模式：崩溃 5 秒后自动拉起，关闭窗口即停止）；桥接卡住没反应时，双击 restart.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: 你好
现在去群里 @ 一下机器人账号，或私聊发条消息试试。不想动用 QQ 也能先自检（会创建独立测试会话，不影响现有会话）：
npm run self-test
预期输出：连接成功 → 测试会话创建 → prompt 被接受 → 打印 agent 回复。
4 种运行模式：给 AI 群友挑一个「人设」
启动后在控制台顶部按钮即时切换（每 5 秒轮询生效，无需重启）：
| chat | 白名单群 + 白名单私聊 → 安全聊天，来消息自动回复 |
| closed-agent | 仅 owner 私聊（config.json 的 ownerQQ）→ 完整工具面，可在 QQ 上操控 DSH |
| reserved（一代仿真） | 状态机决定「何时说」：观望/活跃/试探/退场，可只输出 [SILENT] 表示潜水 |
| reserved2（二代仿真） | 默认模式：一切皆工具——AI 用 qq_get_unread_messages、qq_send_message 等工具自主看消息、发言、潜水、设置唤醒 |
二代仿真是最有「真人感」的一档：AI 会先沉睡前观察 5 分钟，判断没人说话才设置唤醒沉睡，被 @、被点名或聊到关键词时才会醒来。
本地控制台：管理你的 AI 群友
桥接自带 Web 控制台：http://127.0.0.1:3100（访问令牌取 config.json 的 consoleToken，首次启动自动生成并打印在日志）。左侧 10 个页面、支持浅色/深色双主题：
- 运行总览 / 会话与审批：活动日志、会话列表；agent 要执行敏感操作时，QQ 上回复「通过」/「拒绝」即可决策；
- 人格与角色：管理 roles/ 下的人格卡，仓库自带 小鲸鱼.md（傲娇的 DeepSeek 娘）与 傲娇助手.md 两个模板，保存后下条消息即生效；
- 令牌与花费：实时 token 消耗与折算金额看板，可下钻到每个群 / 每个好友 / 每一轮对话，还有按时间的消耗走势图；
- 访问与安全：改白名单、更换管理员与控制台令牌，全部即时生效。
花费看板的数据来源与峰谷计价口径，详见 docs/guides/TOKEN_USAGE_CONSOLE.md。
常见问题速查：新手 4 大坑
| 群里发消息没反应 | 大概率漏装 preset：重跑 node scripts/setup-dsh.mjs 并重启 DSH。桥接日志里会打 ⛔ 群聊/仿真会话缺少 preset——这是刻意的安全设计 |
| 发送报 HTTP 426 | httpUrl 填成了 WebSocket 端口，改成 OneBot 的 HTTP API 地址 |
| 报 401 unauthorized | snowluma.accessToken 与 SnowLuma WebUI 配置不一致，两端设为相同值后重启桥接 |
| 回复里 Markdown 没了 | 正常现象：桥接自动把 Markdown 转成 QQ 纯文本（链接保留 文字 (url) 形式） |
另外不用担心的事：DSH 宕机时桥接会自动排队（每会话最多 50 条，满后丢最旧），DSH 恢复后尝试补投；DSH 重启通常不需要动桥接，它每 5 秒探活一次。
安全须知：把 AI 接进群之前必读
- 暴露给 agent 的 QQ 工具是安全子集：只允许查状态、查群、查消息、白名单内发送，dev_* 等开发工具全部隐藏；
- web-search-safe 会把搜索关键词发给搜索引擎、并按模型判断抓取公网 URL；不需要黑话自动研究时可关闭 slang.autoResearch，数据出机清单见 LICENSE；
- 完整的权限边界与安全承诺见 RULES.md，威胁模型与已实现边界见 docs/guides/SECURITY_BASELINE.md；
- 真实的 config.json 与 state/ 不进入公开仓库，仓库只提供脱敏模板，可放心分享项目本身。
参考资料
- 桥接主程序：src/bridge.js
- DSH 端安装脚本：scripts/setup-dsh.mjs
- DSH 端安装指南：docs/guides/DSH_SETUP.md
- 文档总索引：docs/README.md
- 人格卡模板：roles/小鲸鱼.md
赞
【免费下载链接】qq-bridge
Bridge between QQ (SnowLuma OneBot v11) and DeepSeek Harness agents: social simulation, safe MCP tools, slang learning and more.
项目地址：
https://gitcode.com/gh_mirrors/qq/qq-bridge
点击查看 免费下载
相关推荐
不花一分API钱！3种方式让JustHireMe离线使用大模型：Ollama、Claude Code与Codex CLI配置指南
Antigravity Manager 是什么：一款面向 Gemini 与 Claude 的专业 AI 多账号管理工具
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
