QQ ↔ DeepSeek Harness 桥接

English: README.en.md | 中文: README.md

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

🔒 QQ 会话的权限边界与安全承诺见 RULES.md。

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

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

⚠️ 当前版本 v0.2.0，适配 DSH 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；DSH 0.1.5-rc.1 用 v0.1.5；DSH 0.1.7-rc.2 用 v0.1.7。

v0.2.0 修的主要是会话待处理队列读不出来：桥接退役/重置 QQ 会话时要先清掉 DSH 侧没跑的队列， 而那段解析认的是一个从来不存在的字段（session/control baseline 的 value.queues[<id>]）—— 于是每一次退役都抛 invalid session/control baseline，队列清不掉、旧任务继续在 DSH 里跑， 而日志里只有一行警告。注意：这不是 0.2.0 引入的——该代码随 v0.1.7 发布，报错日志早于 0.2.0-rc.2 的发布，0.2.0 只是把它翻了出来。现在读队列以一元 RPC session/projections 为主路径、 以 projections[<id>].values.inbox 为回退形状，并补了两条回归网。 同一轮还按 0.2.0 的真实工具清单重新对账了 QQ 安全守卫（新增 15 个必须隐藏的工具名， 含全局层默认启用的 read_mcp_resource、plugin_manager、subagent_codex 等）。

逐条改动说明见 docs/guides/DSH_020_ADAPTATION.md。

本次更新的完整说明见 Release v0.2.0。

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

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

项目展示

📽️ AI 仿真群友 - 项目介绍视频（约 11 MB）

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

架构

• QQ 侧：@snowluma/sdk 的 SnowLumaWebSocketClient（OneBot v11 WebSocket 客户端，自动重连）
• DSH 侧：适配 DSH 0.1.2 起引入、0.2.0-rc.2 上逐项复核的协议——用本机持久化签名密钥铸造会话 Cookie 鉴权、/api/<namespace>/<method> 斜杠 RPC、/api/remote.mux + session/follow 事件流（session/control 的队列读 value.projections[<id>].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 与 RULES.md）。
  • web-search-safe（桥接自带 src/mcp-web-search-safe.js）：只读 web_search / web_fetch（带 SSRF 防护），供 agent 查网络用语/资料。 ⚠️ 它会把搜索关键词发给 Bing、并按模型决定抓取公网 URL；黑话学习默认开启，会拿群聊里提取的词条去搜。 数据出机清单见 LICENSE 的「数据出机清单」，不需要就关掉黑话自动研究（slang.autoResearch）。
• 会话模型：每个 QQ 会话（私聊/群）对应一个独立的 DSH 会话，统一归组到「QQ 聊天」工作区（不再散落未分组）；映射持久化在 state/sessions.json
• 性格定制：QQ 会话默认使用 qq-chat agent preset，reserved2 使用 qq-chat-v2。DSH 0.1.7 起 preset 不再是 ~/.dsh/.agent-presets/<名>/ 目录，而是 plugins/qq-agent-presets/ bundle 生成并插入 profile 的一条 @deepseek-ai/dsh-agent-preset 行（重启 DSH 后生效）；人格与默认 DSH 一致（coding agent），仅附加 QQ 场景规则；角色扮演是可选机制——由控制台或管理端设置 state/current-role.json 注入（群友无法更改）
• 本地控制台：桥接自带 Web 控制台 http://127.0.0.1:3100——左侧按操作任务分为「运行总览 / 会话与审批 / 人格与角色 / 二代仿真 / 一代仿真 / 黑话词库 / 令牌与花费 / 访问与安全 / 调试与运维 / 工具参考」十个页面，右上角搜索框可跨页定位任意功能项；支持浅色 / 深色双主题（顶栏一键切换，未选择时跟随系统）；切换运行模式（chat / closed-agent / reserved / reserved2）、设置角色、静默开关、查看活动日志、修改管理员/控制台令牌，全部即时生效；访问需要令牌（config.json 的 consoleToken，未配置时自动生成并打印在启动日志；控制台内可手动修改或重新生成）
  • 令牌与花费看板：实时显示 AI 的 token 消耗与折算金额（元），可下钻到每个群 / 每个好友 / 每一轮对话（轮次、步数、缓存命中/未命中输入、输出、命中率、花费、峰谷时段），并有按时间的消耗走势图（24 小时 / 3 天 / 7 天 / 30 天，柱子按高峰/空闲着色，一眼看出什么时候烧得凶、哪几个小时是 2 倍价）。累计总量取自 DSH 的 tokenUsage 投影（精确，含桥接启动前的历史），逐轮明细由 assistant/message 的 usage 折叠而来；金额按 DeepSeek 官方价目表折算并区分高峰 / 空闲时段（高峰单价为空闲的 2 倍，已内置中国法定节假日）。详见 docs/guides/TOKEN_USAGE_CONSOLE.md
  • 人格（角色扮演）管理：列表点选即可载入查看/编辑提示词，支持新建、保存修改、改名（自动重命名文件）、另存为副本、删除；超过注入上限或含一代专用指令会实时提示
  • 两层提示词可分别查看与修改：「仿真提示词」（预设内置，管行为与协议，保存后同步到 DSH，需重启生效）与「人格提示词」（roles/*.md，管人设与语气，保存即生效）；仿真层保存前做安全不变量校验与自动备份，可一键还原
  • DSH 思考强度：默认 max，可选 high / low，档位从 DSH 实际公布的能力读取，保存后下一条消息生效；控制台会明示该设置同时写入 DSH 全局默认（~/.dsh/settings.yaml）
• 运行模式：
  • chat：白名单群 + 白名单私聊 → qq-chat 安全聊天
  • closed-agent：仅私聊 owner（config.json 的 ownerQQ，可在控制台设置）→ 完整工具（默认用 DSH 自己声明的默认 preset，即 standard；可在控制台「closed-agent preset」下拉改为任意 DSH preset），可在 QQ 上操控 DSH
  • reserved（一代仿真）：仿真群友，观望/活跃/试探/退场状态机，选择性参与、按空格分句发送、主动收尾
  • reserved2（二代仿真，运行 setup-dsh.mjs 后 DSH 默认）：文本不自动转发，AI 通过 qq_get_unread_messages / qq_send_message 等工具自主看消息、发言、等待、设置唤醒/潜水；DSH 端使用 qq-chat-v2 preset
• 交互增强：
  • agent 通过 ask_user_question 提问时，问题会转发到 QQ，回复即自动应答
  • agent 请求工具审批时，转发到 QQ，回复「通过」/「拒绝」即可决策
  • 支持 DSH 斜杠命令（如 /model）与 /reset（重置会话上下文）
  • 群聊引用/回复会解析成「被引用人 + 原文」注入 DSH（如 [引用 Derp：El Psy Kongroo是啥]机关的走狗），让 AI 判断这句话是对谁说的，不会把群友之间引用第三方的对话误当成指向自己；引用机器人自己时会被视为必回
  • MCP 发送工具支持可选 replyToMessageId，并新增专用 qq_reply 工具：AI 可以先用 qq_get_group_history 拿到真实消息 id，再引用/回复某条消息（是否允许 AI 主动使用由人格/策略决定；桥接会检测发送类工具调用并自动跳过该回合的重复自动转发）
  • 一代仿真模式（reserved）下，AI 可以只输出 [SILENT] 表示“潜水/不接话”，桥接会静默不发送
  • 一代仿真模式（reserved）按空格分句：AI 用空格表示拆成多条消息；中英文/数字之间的空格也会被当成分条信号，不想分条就不要加空格（reserved2 不适用，分条请用 qq_send_message 数组）

前置条件

1. 运行中的 DeepSeek Harness Web（默认 http://127.0.0.1:3080）
2. 运行中的 SnowLuma，且配置好 OneBot WebSocket 与 HTTP API（默认 ws://127.0.0.1:3001 / http://127.0.0.1:3000，accessToken 视配置填写）
3. Node.js ≥ 22.13

安装与配置

npm install        # 安装依赖（postinstall 会自动修补 @snowluma/sdk 的 ESM 打包 bug）

复制 config.example.json 为 config.json 后编辑：

Windows CMD 用户请用：copy config.example.json config.json

⚠️ 真实 config.json 与 state/ 不会进入公开仓库，仓库只提供脱敏的 config.example.json 模板。

⚠️ allowAllWhenEmpty: true 表示「白名单没填就全部放行」——把 agent 接入 QQ 等于把账号控制权交给了模型，建议先填白名单。

DSH 端安装（必做：装 preset + 挂 MCP）

桥接和控制台能跑起来还不够，DSH 端还需要安装两个聊天 preset（qq-chat / qq-chat-v2）并挂载 MCP。单机新装同样必须执行这一步（不是只有「另一台设备」才需要），装完还要重启 DSH：

node scripts/setup-dsh.mjs

全新环境下脚本会把 DSH 默认模式设为 reserved2（二代仿真），并创建本地 state/mode.json 兜底；这样 AI 使用 qq_send_message 等工具收发消息时，DSH 会自动使用 qq-chat-v2 模式。如果本机已存在旧的 state/mode.json 或 DSH 设置值，脚本会保留不覆盖。之后可在桥接控制台（默认 http://127.0.0.1:3100）顶部按钮切换模式，控制台会同时写入 DSH 设置与本地兜底文件。

详细步骤见 docs/guides/DSH_SETUP.md。

完整启动流程（从零开始）

共 6 步。DSH 已安装并运行，缺的是 SnowLuma 本体 + 桥接侧的 DSH 端安装（第 2、3 步最容易漏，漏了 QQ 上会毫无反应）：

1. DSH（已运行，无需操作） 确认 http://127.0.0.1:3080 能打开即可。

2. 装桥接并复制配置

   git clone https://github.com/Derpyu520/qq-bridge.git
   cd qq-bridge
   npm install
   

   Windows CMD 用 copy config.example.json config.json，其他平台用 cp config.example.json config.json。 示例模板里 allow.private / allow.groups 是空数组——空白名单 + allowAllWhenEmpty: false 时桥接不响应任何消息（这是刻意的 fail-closed 默认值）。白名单在第 5 步填。

3. 装 DSH 端（preset + MCP），然后重启 DSH

   node scripts/setup-dsh.mjs
   

   装完必须重启 DSH——preset 与 MCP 只在 DSH 启动时加载。 跳过这步桥接不会崩，但群聊会话拿不到 qq-chat preset，桥接会拒绝建会话（有意的安全设计：绝不回退到带 bash/文件工具的默认 preset），表现同样是 QQ 上没反应。

4. 下载并解压 SnowLuma

   • 下载：https://github.com/SnowLuma/SnowLuma/releases/latest 选 SnowLuma-v<版本>-win-x64.zip（完整版，自带 Node 运行时；Lite 版需本机 Node 22.13+）
   • 解压到任意目录（例如 C:\SnowLuma），双击 launcher.bat

5. **首次引导（W