qq-bridge安装最容易漏的2步:DSH端preset与MCP挂载完全指南
qq-bridge安装最容易漏的2步:DSH端preset与MCP挂载完全指南
qq-bridge 是一个把 QQ 接入 DeepSeek Harness(DSH)agent 的桥接工具:QQ 好友和群里发来的消息会变成 DSH 会话里的用户消息,AI 的回复、提问和工具审批又会发回 QQ。很多新手安装 qq-bridge 后反馈「QQ 上发消息毫无反应」,原因几乎都出在最容易漏的 2 步:DSH 端 preset 安装与 MCP 挂载——本文带你用一条命令完成这两步,并教你会后自检。
为什么 QQ 机器人毫无反应:漏了哪一步?
qq-bridge 的完整链路是这样的:
QQ 消息 ──► SnowLuma(OneBot v11 WS)──► 桥接进程 ──► DSH Web API
桥接进程本身能启动,不代表链路打通。DSH 端还需要两样东西:
| 缺的东西 | 表现 |
|---|---|
聊天 preset(qq-chat / qq-chat-v2) |
桥接直接拒绝建会话,QQ 上发了消息没人回 |
| MCP 工具挂载 | AI 只能被动回复,无法主动查看消息、发消息、联网查黑话 |
注意第一种情况不是 bug:这是有意的 fail-closed 安全设计——没有 preset 时回落到 DSH 默认 preset(通常含 bash、文件读写工具),等于把本地工具暴露给群里任何人,所以桥接宁可拒绝建会话。详见 docs/guides/DSH_SETUP.md 的「QQ preset 挂载失败」一节。
一键安装:运行 setup-dsh.mjs 完成 preset 与 MCP 挂载
安装桥接本体只需 3 条命令(Windows CMD 下把 cp 换成 copy):
git clone https://gitcode.com/gh_mirrors/qq/qq-bridge
cd qq-bridge
npm install
然后是全文最关键的一步——在仓库根目录运行 DSH 端安装脚本:
node scripts/setup-dsh.mjs
就这一条命令,scripts/setup-dsh.mjs 会替你完成下面所有事:
- 安装两套 agent preset:
qq-chat(一代)和qq-chat-v2(二代仿真)。preset 的权威源在 dsh/agent-presets/qq-chat/ 与 dsh/agent-presets/qq-chat-v2/,由 plugins/qq-agent-presets/ 这个 DSH bundle 以 patch 形式插入你的 profile - 挂载三个 MCP server 到
~/.dsh/profiles/web/cordis.patch.yml(见下一节) - 注册两个 DSH 插件(
qq-mode-console与qq-agent-presets)到 profile 的package.json,并维护node_modules下的链接 - 设置默认模式为
reserved2(二代仿真),并写入本地state/mode.json兜底;全新环境才会写入,已有的设置不会被覆盖
💡 脚本幂等可重复运行:重建 preset patch、更新 MCP 路径、修复失效的插件链接,且首次修改前会自动备份
cordis.patch.yml。如果之后把 qq-bridge 目录移动或重新 clone,请再跑一次,否则 DSH 里的绝对路径会指向旧位置。
三个 MCP server 各管什么?
preset 决定 AI「是谁」,MCP 决定 AI「能干什么」。setup 脚本挂载的三个 MCP server 全部是桥接自带的安全实现:
| MCP server | 源文件 | 作用 |
|---|---|---|
snowluma |
src/mcp-snowluma-safe.js | QQ 动作安全子集:查状态、查群、查消息、发消息(发送走白名单,支持引用回复) |
snowluma-host |
src/mcp-host-server.js | 只读探活,仅一个 snowluma_status 工具,只探测、不部署 SnowLuma |
web-search-safe |
src/mcp-web-search-safe.js | 只读 web_search / web_fetch(带 SSRF 防护),供 AI 查网络用语和资料 |
⚠️ 隐私提示:
web-search-safe会把搜索关键词发给 Bing 并按模型抓取公网 URL,黑话自动学习默认开启。不需要可在配置里关掉slang.autoResearch,数据出机清单见仓库的LICENSE。
装完必做:重启 DSH(第 2 个最容易被漏的动作)
preset 和 MCP 只在 DSH 启动时加载——装完不重启,等于没装。这是「2 步」之外的隐藏第 3 步,也是漏装率最高的动作:
- 完全退出 DSH,再重新启动
- 启动时如果报
cannot resolve profile bundle "qq-mode-console",说明插件依赖没装好,运行dsh plugin --profile web install(web换成你的实际 profile 名)后重启 - 如果报
failed to parse overlay cordis.patch.yml,多为历史脚本残留的多余[],重跑一次最新版node scripts/setup-dsh.mjs即可自动清理
装好了吗?3 个自检信号
重启 DSH 后,用下面三个信号确认 preset 与 MCP 都生效了:
- preset 列表:在 DSH 新建会话时,agent preset 下拉里应能看到
QQ 聊天角色(qq-chat)和QQ 聊天角色(二代仿真)(qq-chat-v2) - 工具列表:QQ 会话中应出现
mcp__snowluma__*、mcp__snowluma-host__*、mcp__web-search-safe__*前缀的工具,且不应看到dev_*等开发工具 - 一键自检:在桥接目录运行
npm run self-test,预期依次输出:连接成功 → 创建测试会话 → prompt 被接受 → 打印 agent 回复(会创建独立测试会话,不影响现有会话)
想更彻底,可运行 npm run verify:adaptation,它对运行中的 DSH 做 65 项断言(preset 清单、工具守卫、协议形状等)。
常见问题速查
| 症状 | 原因与修复 |
|---|---|
| 群里发消息 AI 完全没反应 | 桥接日志有 ⛔ 群聊/仿真会话缺少 preset:preset 没装上。检查 profile package.json 的 dsh.profile.bundles 是否含 qq-agent-presets,重跑 node scripts/setup-dsh.mjs 并重启 DSH |
| AI 不会主动看消息、发消息 | MCP 没挂上。确认 cordis.patch.yml 里三个 MCP 条目的路径指向当前仓库位置,然后重启 DSH |
| 发送消息报 HTTP 426 | config.json 的 snowluma.httpUrl 误填成了 WebSocket 端口。httpUrl 填 OneBot HTTP API 地址(如 http://127.0.0.1:3000),wsUrl 才填 WebSocket 地址;也可运行 node scripts/check-onebot-status.mjs 诊断 |
| 启动 DSH 报 YAMLException | 历史脚本残留空数组 [],重跑最新版 setup 脚本会自动剥离 |
| 升级 DSH 后插件条目被重置 | 升级可能重置 profile 的 package.json,重跑 setup 脚本 + dsh plugin --profile web install + 重启 |
更多细节(含 DSH_HOME 自定义、离线跳过安装等)见 docs/guides/DSH_SETUP.md。
总结:完整的 2 步清单
node scripts/setup-dsh.mjs—— 一条命令装好qq-chat/qq-chat-v2两套 preset、挂载三个安全 MCP server、注册 DSH 插件- 重启 DSH —— preset 与 MCP 只在启动时加载,不重启等于白装
装完看到 DSH 的 preset 列表里出现「QQ 聊天角色」、工具列表里出现 mcp__snowluma__*,你的 qq-bridge 才算真正安装完成——这时 QQ 里的 AI 群友才会上线。
