【免费下载链接】qq-bridge
Bridge between QQ (SnowLuma OneBot v11) and DeepSeek Harness agents: social simulation, safe MCP tools, slang learning and more.
qq-bridge 是一个开源的「AI 仿真群友」桥接项目：它把 QQ 群消息接入 DeepSeek Harness（DSH），让 DeepSeek 以群友身份潜水、接梗、吐槽，甚至主动开口。本文带你从零完成 qq-bridge 安装部署、人格卡定制，并讲清它的安全边界，让 AI 真正「像真人一样混进 QQ 群」。
一、AI仿真群友是怎么工作的？先看懂桥接架构
一句话概括数据流：QQ 消息 → SnowLuma（OneBot v11 WebSocket）→ qq-bridge 桥接进程 → DSH Web API → agent 回复发回 QQ。
QQ 消息 ──► SnowLuma（OneBot v11 WS）──► qq-bridge ──► DSH Web API (127.0.0.1:3080/api)
▲ │
└── agent 回复/提问/审批 ┘
几个关键设计，决定了它「像真人」的程度：
- 一会话一会话隔离：每个 QQ 私聊/群对应一个独立的 DSH 会话，统一归组到「QQ 聊天」工作区，映射持久化在
state/sessions.json； - AI 自主收发消息：二代仿真模式下文本不再自动转发，DeepSeek 通过
qq_get_unread_messages、qq_send_message等 MCP 工具自己「看消息 → 决定回不回 → 分条发送 → 设置潜水与唤醒」，就像真人刷群一样； - 联网查资料有防护：查网络用语统一走只读的
web_search/web_fetch（带 SSRF 防护），实现见 src/mcp-web-search-safe.js。
主程序入口是 src/bridge.js，整体架构与配置全解可参考权威文档 docs/guides/PROJECT_GUIDE.md 索引中的指南目录。
二、4种运行模式：从普通聊天到「真人感」
qq-bridge 提供 4 种运行模式，在本地控制台顶部按钮一键切换（每 5 秒生效，无需重启）：
| 模式 | 名称 | 行为特点 |
|---|---|---|
chat | 安全聊天 | 白名单群/私聊，DeepSeek 作为安全聊天伙伴回复 |
closed-agent | 封闭 Agent | 仅 owner 私聊，完整工具，可在 QQ 上远程操控 DSH |
reserved | 一代仿真 | 状态机驱动：观望/活跃/试探/退场，选择性参与、按空格分句、[SILENT] 表示潜水 |
reserved2 | 二代仿真（默认） | 「一切皆工具」：AI 自主读未读、发言、等待、设置唤醒与潜水 |
🐋 二代仿真是重点：默认 diving（潜水）唤醒模式，被 @、被点名、命中关键词（如「小鲸鱼」「DeepSeek」）或提问时会醒来；普通消息唤醒概率默认只有 0.05，所以它不会每条都回——这正是「真人感」的核心：少而精，而非有求必应。所有节奏参数（潜水时长、发送频率上限、连发间隔等）都在 config.example.json 的 socialV2 段里，模板已给出可直接抄的默认值。
三、人格卡定制教程：一条命令让DeepSeek换个性
这是 qq-bridge 最有意思的部分。人格由 Markdown「人格卡」定义，放在 roles/ 目录，文件名即角色名。仓库自带两个示例：
- roles/小鲸鱼.md：傲娇嘴硬的 DeepSeek 小鲸鱼，会潜水、会接梗、被叫「大肥鱼」会炸毛
- roles/傲娇助手.md：傲娇系助手人设
- roles/README.md：人格卡写作规范（只写人设，不写工具用法）
DeepSeek 娘（小鲸鱼）形象参考，即 roles/小鲸鱼.md 人格卡描述的角色
怎么换人格？ 两种方式任选：
- QQ 群内管理命令（桥接硬执行，不经模型）：群里发
/role 傲娇助手，发/role off清除； - 控制台操作：打开本地控制台「人格与角色」页，点选启用、编辑、新建、另存为副本，保存后下一条消息即生效。
📌 提示词其实是两层结构，互不干扰：
| 层 | 位置 | 管什么 |
|---|---|---|
| 仿真提示词 | dsh/agent-presets/qq-chat-v2/agent.cordis.yml 的 persona.prefix | 怎么干活：工具协议、分条、潜水/唤醒规则 |
| 人格提示词 | roles/<角色名>.md | 你是谁：身份、性格、说话风格、梗、雷点 |
以「小鲸鱼」人格卡为例，它规定了「默认一句话 1~10 字」「不要总结、不要升华」「被叫蓝色大肥鱼要炸毛」，还有一份「AI 味黑名单」——出现「综上所述」「希望对你有帮助」之类句式即视为失败。这套去 AI 味的写法，是它读起来像群友的关键。
四、从零部署qq-bridge：完整6步流程
前置条件
- DeepSeek Harness Web 已在运行（默认
http://127.0.0.1:3080） - SnowLuma 已安装并配置 OneBot WebSocket 与 HTTP API
- Node.js ≥ 22.13
步骤
第 1 步：克隆并安装依赖
git clone https://gitcode.com/gh_mirrors/qq/qq-bridge
cd qq-bridge
npm install
第 2 步：创建配置文件
cp config.example.json config.json
重点填三处：snowluma.wsUrl / httpUrl（WS 与 HTTP 两个不同端口）、ownerQQ、allow.private / allow.groups（白名单必填，空白名单默认不响应任何消息，这是刻意的 fail-closed 设计）。字段含义详解见 config.example.json 与 docs/guides/DSH_SETUP.md。
第 3 步：安装 DSH 端 preset + MCP（最容易被漏掉的一步）
node scripts/setup-dsh.mjs
安装完 必须重启 DSH。跳过这步 QQ 上会毫无反应——群聊会话拿不到 qq-chat / qq-chat-v2 preset 时，桥接会直接拒绝建会话（防止回退到带 bash/文件工具的默认 preset，属于有意的安全设计）。详细说明见 scripts/setup-dsh.mjs。
第 4 步：配置 SnowLuma
下载 SnowLuma 的 win-x64 完整版（自带 Node 运行时），解压后双击 launcher.bat 启动，在 WebUI 里扫码登录 QQ，开启 OneBot 的 WebSocket 服务端（默认端口 3001）和 HTTP API（默认端口 3000），记下各自端口与 accessToken。
⚠️ 最常见的坑：
httpUrl填成了 WebSocket 端口，发送消息会报 HTTP 426。wsUrl填ws://端口，httpUrl填http://端口，别混。
第 5 步：填写桥接配置并启动
npm start
看到 SnowLuma 已连接 即成功；Windows 用户建议双击 start.bat（守护模式，崩溃 5 秒自动拉起）。
第 6 步：验证与自检
npm run self-test：验证 DSH 链路是否打通（创建独立测试会话，不影响现有会话）npm run test:audit：离线安全回归，不需要 SnowLuma / QQ 也能跑- QQ 上给机器人账号发条消息，看到回复就大功告成 ✅
五、本地控制台：10页管理面板一览
桥接自带 Web 控制台，默认 http://127.0.0.1:3100（访问需 config.json 的 consoleToken，未配置时启动日志自动生成并打印；页面源码见 public/console.html）。左侧按操作任务分为 10 个页面：
- 运行总览 / 会话与审批：查看会话、处理 agent 的提问与工具审批（回复「通过」/「拒绝」即可决策）
- 人格与角色：管理人格卡，两层提示词（仿真层/人格层）可分别查看与修改
- 令牌与花费：实时 token 消耗看板，可下钻到每个群/每个好友/每一轮对话，区分高峰/空闲单价（高峰为空闲 2 倍，内置法定节假日），详见 docs/guides/TOKEN_USAGE_CONSOLE.md
- 访问与安全 / 调试与运维 / 工具参考：改管理员令牌、看活动日志、查工具清单
此外，AI 通过 ask_user_question 提问或请求工具审批时，问题会直接转发到 QQ，你在群里回复就是应答——不用盯着电脑屏幕。
六、安全边界详解：为什么AI「跑不掉」
把 AI 接进 QQ 群等于把账号话语权交给模型，qq-bridge 用多层硬边界把风险压住（完整威胁模型见 docs/guides/SECURITY_BASELINE.md，权限承诺见 RULES.md）：
| 边界 | 机制 |
|---|---|
| 无本地工具 | qq-chat / qq-chat-v2 预设不挂载 bash、文件读写、子代理——群友如何诱导，agent 物理上无法操作本机 |
| 工具白名单 | 只放行 mcp__snowluma__*（安全子集）、mcp__snowluma-host__*（只读探活）、mcp__web-search-safe__*（只读联网），其余执行期被 qq-tool-restrict.mjs 拒绝 |
| 发送强制白名单 | 所有发送工具的目标必须命中 allow.groups / allow.private，否则拒绝执行 |
| 回复审计 | 回复若含本机路径或 token/凭据特征，整条拦截不发送 |
| 人格不可被群友篡改 | 角色由桥接注入，群友口头要求改角色直接被拦截；提示词端点带 agent 令牌一律 403 |
| 静默开关 | /silent 一键让群友消息不再投递给 agent，只留管理员可对话 |
QQ 动作安全子集的实现见 src/mcp-snowluma-safe.js：查状态/查群/查消息/发消息，且不含禁言、踢人、文件上传下载等管理操作。
七、常见问题速查（FAQ）
- QQ 上发消息没反应？ 先查桥接日志是否有
⛔ 群聊/仿真会话缺少 preset—— 大概率是第 3 步setup-dsh.mjs没跑或没重启 DSH；也可运行node scripts/check-onebot-status.mjs诊断 OneBot 连接。 - 报 HTTP 426？
snowluma.httpUrl误填了 WebSocket 端口，改回 HTTP API 端口（如http://127.0.0.1:3000）。 - 发送报 unauthorized / 401？
accessToken与 SnowLuma WebUI 里配置的不一致，两端设为相同值再重启桥接。 - AI 烧了多少钱？ 控制台「令牌与花费」页，按 24 小时/3 天/7 天/30 天看消耗走势图，金色柱子就是 2 倍价的高峰时段。
- 想彻底关掉？ 停止桥接进程（start.bat 窗口 Ctrl+C）或停掉 SnowLuma 即可。
写在最后
qq-bridge 把「AI 仿真群友」从概念做成了可落地的完整链路：桥接层管通路与安全，preset 管行为协议，人格卡管灵魂。跟着上面的 6 步部署 + 人格卡定制，你也能让 DeepSeek 用自己的人格在群里潜水、接梗、偶尔冒一句怪话。
📎 更多文档：docs/README.md（全部文档一句话索引）、docs/FOLDER_MAP.md（目录与脚本命名约定）、docs/guides/PRIVACY.md（发布前隐私检查）。
⚖️ 合规提醒：SnowLuma 是独立第三方项目，仅供学习与技术研究；使用前请阅读其 EULA 与《QQ 用户协议》，把 AI 接入公共群聊请遵守社区规范。
【免费下载链接】qq-bridge
Bridge between QQ (SnowLuma OneBot v11) and DeepSeek Harness agents: social simulation, safe MCP tools, slang learning and more.
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/gitblog_00176/article/details/168326770
