qq-bridge

QQ ↔ DeepSeek Harness 桥接

English: [README.en.md](README.en.md) | 中文: [README.md](README.md)

> 🗂️ 文档索引（全部文档一句话说明 + 是否仍然有效）见 [docs/README.md](docs/README.md)；仓库目录/脚本命名约定见 [docs/FOLDER_MAP.md](docs/FOLDER_MAP.md)。

>

> 🔒 QQ 会话的权限边界与安全承诺见 [RULES.md](RULES.md)。

>

> 🎤 独立的「发语音」工具已拆到仓库上一级的 ../voice-tool/（命令行 voice-cli.mjs / 图形界面 voice-gui.mjs），不再依赖 qq-bridge 运行。

把 QQ 消息接入 DSH agent：QQ 好友/群发来的消息会变成 DSH 会话里的用户消息，agent 的回复（含提问、工具审批）会发回 QQ。

> ⚠️ 当前版本 v0.2.1-r1，适配 DSH 0.2.1-rc.2（0.2.0-rc.2 亦兼容；两个版本上都逐项实测：npm run verify:adaptation）。

> 鉴权用 ~/.dsh 里持久化的浏览器会话签名密钥离线铸造 Cookie —— DSH 0.1.7 起进程启动 token

> 只存在于内存、不再落盘，旧版「从 guard 日志里读 token」的方式已失效。agent preset 是 DSH 0.1.7 起的

> @deepseek-ai/dsh-agent-preset Cordis 行（~/.dsh/.agent-presets/ 目录机制已废）。协议代次

> （Cookie 鉴权 / 斜杠 RPC / /api/remote.mux 事件流）自 DSH 0.1.2-alpha.1 起引入，与更早的点号

> endpoint 协议不兼容 —— DSH 0.1.1-rc.2 及更早请改用 tag

> [v0.1.0](https://github.com/Derpyu520/qq-bridge/releases/tag/v0.1.0)；DSH 0.1.5-rc.1 用

> [v0.1.5](https://github.com/Derpyu520/qq-bridge/releases/tag/v0.1.5)；DSH 0.1.7-rc.2 用

> [v0.1.7](https://github.com/Derpyu520/qq-bridge/releases/tag/v0.1.7)。

>

> v0.2.0 修的主要是会话待处理队列读不出来：桥接退役/重置 QQ 会话时要先清掉 DSH 侧没跑的队列，

> 而那段解析认的是一个从来不存在的字段（session/control baseline 的 value.queues[]）——

> 于是每一次退役都抛 invalid session/control baseline，队列清不掉、旧任务继续在 DSH 里跑，

> 而日志里只有一行警告。注意：这不是 0.2.0 引入的——该代码随 v0.1.7 发布，报错日志早于

> 0.2.0-rc.2 的发布，0.2.0 只是把它翻了出来。现在读队列以一元 RPC session/projections 为主路径、

> 以 projections[].values.inbox 为回退形状，并补了两条回归网。

> 同一轮还按 0.2.0 的真实工具清单重新对账了 QQ 安全守卫（新增 15 个必须隐藏的工具名，

> 含全局层默认启用的 read_mcp_resource、plugin_manager、subagent_codex 等）。

>

> 逐条改动说明见 [docs/guides/DSH_020_ADAPTATION.md](docs/guides/DSH_020_ADAPTATION.md)（0.2.0）

> 与 [docs/guides/DSH_021_ADAPTATION.md](docs/guides/DSH_021_ADAPTATION.md)（0.2.1）。

>

> r4 主要改动：QQ 表情包/动图链路（表情 CDN 优先、emoji_id 兜底、DNS 多地址故障切换）、

> 联网搜索改用与 DSH 同源的 DeepSeek 搜索（Bing 仅兜底）、qq_wait_for_messages 改 5 分钟长轮询、

> 控制台切模式被 5 秒轮询改回去、回合永久「繁忙」、机器人身份未注入等 issue 修复，外加一轮整体体检。

> 逐条见 [Release v0.2.0-r4](https://github.com/Derpyu520/qq-bridge/releases/tag/v0.2.0-r4)。

>

> v0.2.1-r1 主要改动：适配 DSH 0.2.1-rc.2。修掉一处 P0——persona 里的 {{cwd}}

> 提示词变量在 0.2.1 被删除，导致每个回合在系统提示词装配阶段直接 error、模型一次都不跑

> （QQ 侧表现为「发消息完全没反应」）；同时把 0.2.1 新进全局层的 working_directory

> 与 terminal / session-query / plugin_market 一族补进安全守卫名单。

> 逐条见 [docs/guides/DSH_021_ADAPTATION.md](docs/guides/DSH_021_ADAPTATION.md)。

>

> 默认分支 main 就是本版本，git clone 直接拿到，无需切换分支。

QQ 消息 ──► SnowLuma（OneBot v11 WS）──► 本桥接进程 ──► DSH Web API (127.0.0.1:3080/api)
                                                ▲                      │
                                                └── agent 回复/提问/审批 ┘

项目展示

📽️ [AI 仿真群友 - 项目介绍视频](https://github.com/Derpyu520/qq-bridge/releases/download/v0.1.5/project-intro.mp4)（约 11 MB）

> 视频改由 Release 附件托管，不在仓库里——只想安装桥接的人不必再下载这 11 MB（它此前占整个仓库体积的 88%）。

架构

• QQ 侧：@snowluma/sdk 的 SnowLumaWebSocketClient（OneBot v11 WebSocket 客户端，自动重连）
• DSH 侧：适配 DSH 0.1.2 起引入、0.2.1-rc.2 上逐项复核的协议——用本机持久化签名密钥铸造会话 Cookie 鉴权、/api// 斜杠 RPC、/api/remote.mux + session/follow 事件流（session/control 的队列读 value.projections[].values.inbox，另有一元 session/projections 主路径）；复用 AbstractApiClient 传输层但不再依赖旧版 zod value schema。会话模型由桥接按 config.json 的 dsh.model 逐会话 session.selectModel 固定（默认 deepseek-flash = DeepSeek-V41-Flash，多模态）
• agent 自主收发 QQ：DSH 的 MCP 客户端（~/.dsh/profiles/web/cordis.patch.yml 配置）接入三个 MCP server：
• snowluma（桥接自带 src/mcp-snowluma-safe.js）：QQ 动作安全子集（查状态/查群/查消息/发消息，发送强制白名单；发送工具支持可选 replyToMessageId 引用回复）
• snowluma-host（桥接自带 src/mcp-host-server.js）：只有 snowluma_status（只读探活 get_login_info）。

⚠️ v0.1.5 起移除了 start_snowluma / stop_snowluma（以及 snowluma.allowProcessControl 配置项）——

原因是 SnowLuma EULA §5.4 规定「将其并入第三方安装包或 Docker 镜像、通过自动化脚本部署」

须事先取得书面授权，而原生组件属专有组件。本程序只探测、不部署：SnowLuma 的安装、启动与扫码

始终由你自己完成（详见 [LICENSE](LICENSE) 与 [RULES.md](RULES.md)）。

• web-search-safe（桥接自带 src/mcp-web-search-safe.js）：只读 web_search / web_fetch（带 SSRF 防护），供 agent 查网络用语/资料。

搜索优先复用 DSH 原本的联网搜索（同一个 DeepSeek Anthropic 兼容端点 + web_search 服务端工具，凭据按 config.webSearch.apiKey → 环境变量 DEEPSEEK_API_KEY → DSH 的 .credentials.yaml 顺序解析），

因而结果质量与 DSH 内的搜索一致、且不再默认把群聊关键词发给 Bing（Bing RSS 只在 DeepSeek 不可用时兜底）。

抓取仍由桥接自己做 SSRF 校验并限制正文大小；黑话学习默认开启，会把群聊里提取的词条交给所选的搜索后端。