企业官网建设流程全解析

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 回复/提问/审批 ┘

功能亮点一览：

部署前准备：先备齐 3 个前提条件

开始安装前，请确认本机已具备：

1. DSH Web 已运行（默认http://127.0.0.1:3080）：当前qq-bridge v0.2.0适配 DSH0.2.0-rc.2；
2. SnowLuma QQ 接入程序：需配置好 OneBot WebSocket（默认ws://127.0.0.1:3001）与 HTTP API（默认http://127.0.0.1:3000）；
3. Node.js ≥ 22.13。

⚠️ 合规提醒：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 字段较多，新手只需先弄懂这几个核心项：

🔒 安全默认值：模板里白名单为空，且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 还没做过首次引导：

1. 解压 SnowLuma（完整版自带 Node 运行时），双击launcher.bat启动；
2. 打开启动日志里的 WebUI 地址，用日志中的初始密码登录：同意条款 → 设置密码 → 扫码登录 QQ；
3. 在 WebUI 的 OneBot 设置中开启WebSocket 服务端和HTTP API，记下两者的端口（默认 WS3001、HTTP3000）与 accessToken。

回到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 秒轮询生效，无需重启）：

二代仿真是最有「真人感」的一档：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 大坑

另外不用担心的事：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