qq-bridge安装最容易漏的2步:DSH端preset与MCP挂载完全指南

原创2026-10-17 19:13:273,668 阅读
文章标签:即时通讯AI Agent人工智能工具调用MCP 服务MCP Clients后端dsh-plugin

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-bridge 项目 AI 角色示例:基于 DeepSeek 的 QQ 仿真群友

为什么 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 步,也是漏装率最高的动作:

  1. 完全退出 DSH,再重新启动
  2. 启动时如果报 cannot resolve profile bundle "qq-mode-console",说明插件依赖没装好,运行 dsh plugin --profile web install(web 换成你的实际 profile 名)后重启
  3. 如果报 failed to parse overlay cordis.patch.yml,多为历史脚本残留的多余 [],重跑一次最新版 node scripts/setup-dsh.mjs 即可自动清理

装好了吗?3 个自检信号

重启 DSH 后,用下面三个信号确认 preset 与 MCP 都生效了:

  1. preset 列表:在 DSH 新建会话时,agent preset 下拉里应能看到 QQ 聊天角色(qq-chat)和 QQ 聊天角色(二代仿真)(qq-chat-v2)
  2. 工具列表:QQ 会话中应出现 mcp__snowluma__*、mcp__snowluma-host__*、mcp__web-search-safe__* 前缀的工具,且不应看到 dev_* 等开发工具
  3. 一键自检:在桥接目录运行 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 步清单

  1. node scripts/setup-dsh.mjs —— 一条命令装好 qq-chat / qq-chat-v2 两套 preset、挂载三个安全 MCP server、注册 DSH 插件
  2. 重启 DSH —— preset 与 MCP 只在启动时加载,不重启等于白装

装完看到 DSH 的 preset 列表里出现「QQ 聊天角色」、工具列表里出现 mcp__snowluma__*,你的 qq-bridge 才算真正安装完成——这时 QQ 里的 AI 群友才会上线。

登录后查看全文
qq-bridge