QQ 任务桥 binlin0120/dsh-qq-bridge

DSH-QQ Bridge · DSH-QQ 任务桥（QQ ↔ DeepSeek Harness）

当前可迁移版本已包含持久化提醒、分层记忆、故障恢复、好友申请回读、群友图片日额度，以及区分海报/插画/照片的图片执行与原图复用。更新与升级注意事项见 发布说明，开发结构见 架构说明。首次部署、目录与记忆配置、图片服务协议和验证范围见 可迁移部署说明。私有配置、会话、记忆、音频和角色参考图不随仓库提供。

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

🗂️ 文档索引见 docs/README.md；目录/脚本命名约定见 docs/FOLDER_MAP.md。

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

一句话定位：把 QQ 变成 DSH（DeepSeek Harness）智能体的前台——你在 QQ 里说话、派活，DSH 在机器上真正干活，结果再回到 QQ。

一键部署（别人上手最短路径）

别人拿到这个仓库，按下面 6 步就能跑起来，完整说明见下文“完整启动流程（从零开始）”和 docs/guides/DSH_SETUP.md：

git clone https://github.com/binlin0120/dsh-qq-bridge.git
cd dsh-qq-bridge
npm ci
cp config.example.json config.json # Windows 用 copy config.example.json config.json
编辑 config.json：填 snowluma 的 wsUrl / httpUrl / accessToken，以及 allow.private / allow.groups（你自己的 QQ 号 / 群号）
node scripts/setup-dsh.mjs # 装 DSH 端 preset + MCP，装完必须重启 DSH
npm start # Windows 想崩溃自动重启，改双击 start.bat

配置说明：必填的就这几项，其他先不用动

config.example.json 里键很多，但第一次跑起来只用改下面这些，剩下的保持默认值就能用，后面想调再去控制台或对应文档里改：

- 必须填：snowluma.wsUrl（默认 ws://127.0.0.1:3001）、snowluma.httpUrl、snowluma.accessToken（SnowLuma 那边的接入地址和令牌）；ownerQQ（机主自己的 QQ 号）；allow.private（允许私聊的 QQ 号列表）、allow.groups（允许的群号列表）。
- 必须保持：allowAllWhenEmpty 保持 false。该兼容字段已停用：设为 true 时拒绝启动或拒绝保存，空名单不会放行普通会话。
- 一般不用改：dsh.baseUrl（默认 http://127.0.0.1:3080，本机 DSH）、consolePort（默认 3100）、consoleToken（留空时启动会自动生成并打印在日志里）。
- 先不用管：deny.（黑名单，默认空）、social / socialV2（群聊仿真、发送节奏、表情、语音等调优）、slang（黑话学习）、webSearch（联网搜索）、pricing（花费折算）这些都是调优项，默认值已经能跑，不用逐个解释完再启动。想调某个功能时看 docs/guides/CONFIGURATION.md，里面把所有已有功能、默认值、改哪里、改完要不要重启都写齐了，人设也在那篇第 3 节：改 roles/<角色名>.md，或控制台「人格与角色」页点选编辑。

注意：roles/小鲸鱼.md 是本仓库自带的示例人设，里面写了示例用的名字和称呼；别人部署时请把人设里的名字、称呼换成自己的，不要直接用示例人设里的名字。同样，preset 里的工作目录示例是 ~/qq-bridge，部署在别的路径时请按实际路径改。

与上游的关系：本项目是 DSH-QQ Bridge（DSH-QQ 任务桥），基于开源项目 qq-bridge（作者 Derpyu520，MIT 许可证）二次开发的个人维护版本，基线为上游 v0.2.0-r4。在上游基础上强化了：多任务编排（把活拆成目标分步执行）、口语急停（自然说法即可叫停并作废未发出的排队消息）、进度播报、投递守卫与任务状态管理。原作者版权与 LICENSE 保留在 LICENSE 中。

项目流程（一遍看懂）

QQ 好友/群消息 │ ▼ SnowLuma（QQ 接入层，OneBot v11 WebSocket） │ 消息事件推送 ▼ DSH-QQ Bridge 桥接进程（本项目） │ ① 过关：黑/白名单校验 + 当前模式决定权限大小 │ ② 机主私聊先过「紧急停止」识别（口语停令优先处理） │ ③ 每个 QQ 会话映射到一个独立的 DSH 会话 ▼ DSH（DeepSeek Harness Web，智能体运行时） │ 按预设权限干活：普通会话只有聊天 + 受限 QQ 工具 + 联网搜索； │ 机主在 closed-agent 模式下可用完整工具（文件/命令/代码） │ agent 也可反过来调用桥接提供的 QQ 工具自主收发消息 ▼ 结果回流 │ ④ 出站先过敏感审计（本机路径/凭据形态整条拦截） │ ⑤ 经投递队列按序分段发送；急停后排队内容作废、不再投递 ▼ 回到 QQ（文字 / 文件 / 图片 / 语音）

配套控制面：本机 Web 控制台（http://127.0.0.1:3100，令牌访问）负责切模式、管人格、看令牌花费、维护白名单与安全设置；运行状态与聊天归档落在本地 state/ 目录。

能做什么

- QQ 聊天接入 DSH：白名单内的好友私聊、群聊都能和 DSH 智能体对话，引用、图片、表情会被解析成上下文一起投递。
- 通过 QQ 给 DSH 派活（见下一节，本版本重点）。
- 智能体自主收发（二代仿真 reserved2）：AI 通过 qq_get_unread_messages / qq_send_message 等工具自己看消息、决定回不回、什么时候回。
- 群聊仿真（一代 reserved）与角色扮演：状态机式选择性参与；人格卡（roles/.md）可切换、可在控制台编辑。
- 提问与审批转发：智能体需要确认时，问题和工具审批会转发到 QQ，回「通过 / 拒绝」即可决策。
- 黑话学习与长期记忆：自动提取群聊黑话并联网考证；印象笔记/记忆手册让 AI 跨会话记住人。
- 表情、图片与语音：收藏表情同步与发送、图片理解、语音消息收发。
- 花费看板：控制台按群 / 好友 / 每一轮对话统计 token 消耗与折算金额。
- 安全守卫：工具白名单（QQ 会话拿不到本地执行工具）、出站敏感审计、发送限流、口语急停。

通过 QQ 给 DSH 派活（重点）

这是本项目最核心的用法：机主本人用 QQ 私聊发话，服务器上的 DSH 就去执行。

- 入口：机主 QQ 私聊 + closed-agent 模式（控制台可切换）。该模式只认机主账号，其他人进不来。
- 怎么派：直接用自然语言说任务即可——查资料、写文档、改代码、跑脚本、整理文件、盯一个长任务……不需要固定口令格式。DSH 在它的工作区里真正执行（读写文件、运行命令、调用工具）。
- 审批在 QQ 上完成：智能体要做敏感操作时会把审批请求转发到 QQ，你回「通过 / 拒绝」拍板。
- 多任务与编排：可以同时派多个活；编排器会把任务拆成目标（goals）分步执行、记录状态，后台任务和日常聊天互不阻塞。问一句进度，就会收到整理好的进度播报。
- 怎么叫停：说「不要给我发了 / 别发了 / 停下 / 全部停」这类口语即可触发急停——正在跑的任务被停、排队未发的消息全部作废、被停那一轮的迟到回复直接丢弃，桥接会回一条确认回执。（注意：已经发出去的消息无法撤回。）
- 结果怎么回来：文字分段发回；产出的文件、图片会作为消息发回（只允许白名单目录内的文件外发）。

限制（说清楚）

- 不是独立产品：本项目只是「桥」。必须先自备并跑起来 DSH 与 SnowLuma 两个外部组件，缺一不可；SnowLuma 需自行下载、扫码登录（其许可不允许被打包分发，本项目只连接、不部署它）。
- 版本绑定：适配 DSH 0.2.0-rc.2 的协议代次；DSH 大版本升级可能不兼容，需要等适配。运行环境要求 Node.js ≥ 22.13。
- 单实例、单账号：桥接同一时间只运行一个实例、只连接一个 QQ 账号。
- 派活 = 交出机器操作权：closed-agent 下智能体的工具权限等同于在服务器上以运行账号操作。机主 QQ 被盗 = 操作权敞口，所以白名单是 fail-closed 默认、模式门只认机主私聊，这两条不要关。
- 急停是规则识别：覆盖常见口语说法与否定/引用等防误触发情形，但极冷门的说法仍可能漏识别；没有正在运行的任务时急停不生效；多个任务在跑而你没说「全部」时，它不会盲停，会先跟你确认。
- 消息可靠性边界：桥接进程退出时，内存中的待投递队列会丢失；断线期间已经结束的回复不保证补发；已发送的 QQ 消息无法撤回。
- 安全是启发式 + 本地信任模型：出站审计能拦常见路径/凭据形态，拦不住所有形态的秘密；state/ 中的令牌在本地明文落盘，靠系统文件权限/ACL 保护（详见 docs/guides/SECURITY_BASELINE.md 的残余风险清单）。
- 成本与平台风险自担：跑任务消耗你自己的 DeepSeek 额度；QQ 侧发送频率受平台限制，高频使用有触发风控的可能。
- 内部代号保留：人格预设代号（如 dafeiyu、jingjing-）是代码按名加载的内部标识，为保持兼容未改名；它们只是代号，不含任何人的真实信息。

架构

- 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，多模态）
- 智能体自主收发 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 防护），供智能体查网络用语、资料。
搜索优先复用 DSH 原本的联网搜索（同一个 DeepSeek Anthropic 兼容端点 + web_search 服务端工具，凭据按 config.webSearch.apiKey → 环境变量 DEEPSEEK_API_KEY → DSH 的 .credentials.yaml 顺序解析），因而结果质量与 DSH 内的搜索一致，且不再默认把群聊关键词发给 Bing（Bing RSS 只在 DeepSeek 不可用时兜底）。
抓取仍由桥接自己做 SSRF 校验并限制正文大小；黑话学习默认开启，会把群聊里提取的词条交给所选的搜索后端。
数据出机清单见 LICENSE 的「数据出机清单」，不需要就关掉黑话自动研究（slang.autoResearch）或把 webSearch.provider 设为 bing。
- 会话模型：每个 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，管人设与语气，保存即生效）；仿真层保存前做安全不变量校验与自动备份，可一键还原
- 会话初始提示词（二代仿真）：「二代仿真 → 初始提示词」里可以给某个群/私聊预写一段环境说明（圈子主题、群内氛围、常见话题、忌讳），AI 只在该会话第一次唤醒时收到一次（之后已在会话上下文里，不再重复注入）。可在群还没说过话时提前写；AI 既读不到也改不了这份设置（仅控制台接口）。会话被重置（「会话映射」里的重置或「重置二代状态」）后，下一次首次唤醒会重新带上它。字数上限见 socialV2.initialPromptMaxChars
- 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
- 交互增强：
- 智能体通过 ask_user_question 提问时，问题会转发到 QQ，回复即自动应答
- 智能体请求工具审批时，转发到 QQ，回复「通过」/「拒绝」即可决策
- 支持 DSH 斜杠命令（如 /model）与 /reset（重置会话上下文）
- 群聊引用/回复会解析成「被引用人 + 原文」注入 DSH（如 [引用 Derp：El Psy Kongroo是啥]机关的走狗），让 AI 判断这句话是对谁说的，不会把群友之间引用第三方的对话误当成指向自己；引用机器人自己时会被视为必回
- 图片/表情（含动图 GIF）：表情包优先走 QQ 的 CDN 直链，get_image 失败时用 emoji_id 推出 CDN 地址兜底；媒体元数据保留 emoji_id/summary/sub_type 等字段。下载走同一套 SSRF 防护传输，并修掉了「DNS 先返回 IPv6、本机没有 IPv6 出口 → 每次白等 20 秒」的根因（改为 IPv4 优先 + 逐地址故障切换），动图表情不再时好时坏。单条消息上限默认 8MB / 64MP / 5 张（socialV2.media）
- 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 ci # 安装依赖（postinstall 会自动修补 @snowluma/sdk 的 ESM 打包 bug）

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

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

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

| 字段 | 说明 |
| dsh.baseUrl | DSH Web 地址，默认 http://127.0.0.1:3080 |
| dsh.provider / dsh.model / dsh.reasoningEffort | DSH 会话使用的模型/推理强度；若你的 DSH 没有示例中的模型，改成 DSH 设置页里可用的模型即可（选择失败只打日志，不阻塞启动） |
| dsh.authToken | DSH launch token（进程启动凭据）。通常应留空：留空时桥接用 ~/.dsh/.credentials.yaml 里持久化的签名密钥离线铸造会话 Cookie，不依赖任何进程期状态（DSH 0.1.7 起启动 token 只存在于内存、日志里那条是上一个进程的陈旧值，换 Cookie 只会 401）。只有显式填了才会优先走 token 交换 |
| dsh.authHeader / dsh.authPrefix | 保留字段，当前新版 DSH 链路使用 Cookie 交换，不再直接发送该鉴权头 |
| snowluma.wsUrl | SnowLuma OneBot WebSocket 地址（如 ws://127.0.0.1:3001） |
| snowluma.httpUrl | OneBot HTTP API 地址（如 http://127.0.0.1:3000）；不要填 WebSocket 端口，否则会报 HTTP 426 |
| snowluma.accessToken | OneBot accessToken，未配置留空 |
| snowluma.followDiscoveredEndpoint | 默认 true。换 QQ 账号后 token 与端口都会变，桥接会自愈：重新发现并跟随 SnowLuma 的端点（同时写回 config.json）。想跑第二个实例 / 指向另一份 SnowLuma 安装（多账号、测试）时设为 false —— 那时只自愈 token，绝不动 URL，也不写回 URL。详见「已知行为」 |
| snowluma.silenceWarnMs | 上游静默告警阈值（毫秒），默认 600000（10 分钟）。已连接但这么久没收到任何事件包（含心跳）时打警告；这只是提示，不确定性的判断交给 good |
| snowluma.launcherPath / homeDir | SnowLuma 安装目录（用于 token/端点自发现）。⚠️ 桥接不会启动或停止 SnowLuma（见 LICENSE） |
| agentPreset | QQ 会话使用的 DSH agent preset，默认 qq-chat（改性格见下文） |
| socialV2.agentPreset | reserved2 模式使用的 DSH agent preset，默认 qq-chat-v2 |
| socialV2.initialPromptMaxChars | 会话「初始提示词」（控制台为某个群/私聊预写的环境说明）的字数上限，默认 2000，允许 100~8000。越界值会在启动时收敛并保持原文件不动 |
| socialV2.media | 图片/表情的上限：maxBytes（单条消息总字节，默认 8MB）、maxPixels（单张像素，默认 64MP）、maxCount（单条最多处理几张，默认 5）。越界值启动时收敛 |
| webSearch.provider | 联网搜索后端：auto（默认，优先 DeepSeek、失败回退 Bing）/ deepseek（仅 DeepSeek，无凭据时报错）/ bing |
| webSearch.apiKeyEnv / apiKey | 搜索凭据的环境变量名（默认 DEEPSEEK_API_KEY）/ 直接写死 key（不推荐）。都不设置时读 DSH 的 $DSH_HOME/.credentials.yaml 里同名 ref |
| webSearch.baseURL / model / maxUses / maxResults | 搜索端点（默认 https://api.deepseek.com/anthropic/v1，必须 https 且解析到公网）、模型（默认 deepseek-v4-flash）、单次搜索最多用几次工具、返回条数上限 |
| workspaceTitle | QQ 会话在 DSH 界面中的归组名称，默认「QQ 聊天」 |
| allow.private / allow.groups | 白名单（QQ 号/群号数组）；空名单拒绝普通会话，拒绝名单优先 |
| deny. | 黑名单，优先于白名单 |
| ackMessage | 消息投递后的立即回复，空字符串关闭 |
| sendDelayMs | QQ 连续发送间隔，防止触发频率限制 |
| consolePort | 本地控制台端口，默认 3100 |
| consoleToken | 控制台访问令牌；留空时启动自动生成并保存到 state/console-token |

allowAllWhenEmpty: true 已不受支持，启动和名单更新都会拒绝该值；请显式填写允许名单。

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/binlin0120/dsh-qq-bridge.git
cd dsh-qq-bridge
npm ci

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. 首次引导（WebUI）+ 填写桥接配置
- 打开启动日志里的 WebUI 地址（README 写的是 http://localhost:5099，以你启动日志里实际打印的为准）
- 用启动日志中的初始密码登录，按引导：同意条款 → 设置密码 → 接入 QQ 进程（扫码登录）
- 在 WebUI 里配置 OneBot 连接：开启 WebSocket 服务端 和 HTTP API，分别记下端口（默认 WS 3001、HTTP 3000）和 accessToken（若配置了）
- 回到 config.json 填好 snowluma 段，并把 allow.private / allow.groups 换成你自己的 QQ 号 / 群号：

"snowluma": {
"wsUrl": "ws://127.0.0.1:3001",
"httpUrl": "http://127.0.0.1:3000",
"accessToken": "你在 WebUI 里配置的 token（没配置就留空）" }

wsUrl 是 OneBot WebSocket 端口，httpUrl 是 OneBot HTTP API 端口（不要填成同一个 WS 端口，否则 MCP 工具会报 HTTP 426）。

6. 启动桥接
npm start # 前台运行（崩溃不自动重启）

看到 SnowLuma 已连接 即成功；然后 QQ 上给机器人账号发条消息测试。
Windows 想要「崩溃自动重启」请改用 start.bat（见下节）。

运行与运维

npm start # 或双击 start.bat（守护模式：崩溃自动重启，关闭窗口即停止）

⚠️ 重要：
- 桥接只能运行一个实例（有单实例锁，重复启动会被拒绝并提示"已有实例在运行"）
- 用 start.bat 启动（守护模式），窗口别关——桥接崩溃会在 5 秒后自动拉起
- 桥接异常/消息无反应时：双击 restart.bat（自动杀旧实例 → 清理锁 → 重新启动守护）
- 重启 DSH 通常不需要动桥接：每 5 秒探活，DSH 不可用期间收到的 QQ 消息在桥接进程内排队（最多 50 条/会话，满后丢最旧项），恢复后尝试补投。桥接进程退出会丢失内存队列；断线期间已经结束的回复暂不保证补发。
- 修改 config.json / roles/ / state/current-role.json 后重启桥接生效；修改 dsh/agent-presets/（改完要跑 node scripts/build-agent-preset-patches.mjs 重新生成 bundle patch）或 MCP 配置后重启 DSH 生效

日志示例：

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: 你好
12:00:20 [bridge] agent 回复 (private:12345678) 42 字

自测（不需要 SnowLuma / QQ）

离线回归（使用临时目录和模拟服务，不读取真实配置、不发 QQ 消息）：

npm run test:audit

reserved2 的 token 开销优化、消息水位协议、升级及回退说明（该专项分析为本地文档，未随仓库发布。）专项离线回归可运行 npm run test:token，已包含在上面的完整回归中。

控制台「令牌与花费」看板的账本与价目表回归（峰谷分时、幂等折叠、基线合并、压缩与容错）：

npm run test:tokens # 单元测试
npm run test:console-ui # 离线浏览器回归（含看板渲染与逐轮下钻）

本轮审查与修复明细为本地审计文档，未随仓库发布。升级后会为没有权限元数据的历史映射重建一次 QQ 会话；模式或 preset 变化也会自动重建，避免保留旧权限。旧历史仍在 DSH 中。

验证 DSH 侧链路是否打通（会创建一个独立测试会话，不影响现有会话）：

npm run self-test

预期输出：连接成功 → 测试会话创建 → prompt 被接受 → 打印 agent 回复。

目录结构

qq-bridge/
config.example.json # 配置模板（脱敏占位符；真实 config.json 不入库） README.md / README.en.md / RULES.md # 根目录只留这三个文档，其余全在 docs/ docs/ README.md # 文档索引（每篇一句话 + 是否仍然有效） FOLDER_MAP.md # 目录结构与 scripts/ 命名约定 guides/ # 面向使用者/运维：PROJECT_GUIDE / DSH_SETUP / VOICE / TOKEN_USAGE_CONSOLE / CONSOLE-UI-TESTING design/ # 设计与规划：GEN2_SIMULATION_PLAN / SOCIAL_MODE_PLAN / DSH_QQ_TOOLS_PLAN / 真人语感策略 research/ # 调研：SnowLuma功能调研 / QQ消息免打扰 / 表情包能力 / 本地模型选型 audits/ # 审查与优化报告（体检、控制台、token） legacy/ # 历史归档（已被取代或问题已全部修复的旧报告） audio/ # 语音库：把准备好的音频放这里，可作 QQ 语音发出（用法见 docs/README.md 文档索引） dsh/agent-presets/ # qq-chat / qq-chat-v2 的 DSH agent preset 模板 plugins/qq-mode-console # DSH 插件：注册 qq-mode 设置命名空间（仅 host 半，UI 卡片未实现） src/ bridge.js # 主程序 dsh-client.js # Node 版 DSH API 客户端（WS 下行） md-to-plain.js # Markdown → QQ 纯文本 self-test.js # DSH 侧自测 scripts/ # 测试/运维脚本（含 postinstall 的 patch-snowluma-sdk.mjs） patch-snowluma-sdk.mjs # 修补 SDK 的 ESM 打包 bug（postinstall 自动执行） state/ # 运行时数据（不入库）

语音发送使用仓库内的 npm run send-voice。可选的 voice-cli.mjs / voice-gui.mjs 属于另行安装的独立工具，本仓库不提供对应 npm 启动命令；配置与可选工具检查见 语音说明。

SnowLuma 版本与上游健康（「连上了但收不到消息」）

「注入」在这个技术栈里只发生在一处：SnowLuma 用原生组件挂进 QQ 客户端进程（它自己日志里叫 [Hook]，载体是安装目录的 native/snowluma-win32-x64.{dll,node}）。本桥接没有任何原生/注入面（依赖全为纯 JS，源码里没有 .dll / .node / FFI / 进程注入），也不启动、不控制 SnowLuma 或 QQ ——所以「QQ 注入失败」不可能是本桥接造成的。但桥接过去无法把这个失败讲清楚，于是它经常被误报成「qq-bridge 的问题」。现在桥接会主动把上游健康报出来。

已知行为：连上了 ≠ 收得到

SnowLuma 的 [Hook] 会退化：它的进程和 OneBot WebSocket 都还活着，但收不到 QQ 侧的数据。
它自己的日志长这样：

WARN [Hook] receive path stale: PID=… UIN=… silentFor=136193ms; reporting good=false
WARN [Hook] process enumeration timed out after 4000ms (worker abandoned)

这时桥接这边一切正常：WebSocket 通、日志打过 SnowLuma 已连接、控制台没有异常，但群里一条消息都不来。
桥接现在对此做两件事：

1. 主信号：每 30 秒一次的 meta_event/heartbeat 载荷里的 status.good（SnowLuma 对「QQ → 原生 hook → 我」这条接收链路的自评，静默约 105 秒后翻 false）。心跳是 SnowLuma 自己的定时器无条件发的，所以这条信号免费且及时，且不需要较新的运行时。
兜底：每 60 秒问一次 get_status（{online, good}）。加分项：bot_status（账号会话上下线，SnowLuma 1.14.20 才真的有）+「距最近一个事件包的时长」（只能证明进程/WS 还活着，不能证明收得到 QQ 数据 —— 心跳会一直来）。
⚠️ 不要用 get_login_info 取 good：它只返回 {user_id, nickname}，而 SDK 不校验 data 载荷 ⇒ 不会报错、good 永远是 null、这条判断变成永不触发的死代码。（本功能的第一版实现正是这么写错的，回归里已加反面断言钉住。）
2. 判定退化时：日志打明确指向 SnowLuma [Hook] 的警告、控制台「运行总览」出现 SnowLuma 上游 卡片、「访问与安全」页出现告警条，GET /api/status 的 snowluma 字段给出 degraded / good / hint。

排查顺序：控制台看 SnowLuma 上游 卡片 → 看 SnowLuma 的 logs/snowluma-.log 里的 [Hook] 行 → 再考虑升级 SnowLuma（升级不换原生组件，见下）。

版本要求

| 组件 | 要求 | 说明 |
| SnowLuma 运行时（QQ 网关本体） | 1.14.20 已实测（1.14.9 亦兼容） | 实测记录（2026-10-03，SnowLuma 1.14.20 + QQ 在线）：包 SHA256 与官方发布摘要一致；心跳 status.good=true／interval=30000；桥接走完「首次 1006 → 自愈 WS token → 已连接」；收到群消息（lastPacketKind: message/group）；完整往返成功（唤醒 → DSH 建会话挂 qq-chat-v2 → 工具发送 1/1 条 → 实际发出两条回复）。 ⚠️ 升级运行时不会更换注入用的原生组件：实测 native/snowluma-win32-x64.{dll,node} 与 websocket-win32-x64.node 在 1.14.9 与 1.14.20 之间逐字节完全相同（三方对比：官方 1.14.9 包 == 本机安装 == 官方 1.14.20 包），变的只有 index.mjs（+414 KB）等 JS 层。所以升级能带来 OneBot 事件流水线、收发与新区块链路上的修复（bot_status、markdown 带 text、事件种类订阅更全），但不会修「原生 hook 挂不上 QQ」这类问题 —— 那种要走 SnowLuma 自己的排查。升级 SnowLuma 是使用者自己的事：本桥接只探测、不部署（见 LICENSE 与 RULES.md） |
| @snowluma/sdk / @snowluma/mcp（本仓库依赖） | 已钉 ^1.14.20 | 客户端库；OneBot v11 是稳定契约，新库可连旧运行时（本项目实测：库 1.14.20 + 运行时 1.14.9 可正常收发） |
| bot_status（账号上下线） | 1.14.20 有；1.14.9 没有 | 逐一核对的只有这两个版本：bot_status 在 1.14.9 的 index.mjs 里出现 0 次、1.14.20 里 3 次（带 sub_type/user_id）。具体从哪个版本引入未逐版核对。桥接对老运行时优雅降级：订阅不到就只靠心跳 good 与 get_status |

已知行为：HTTP token 与 WS token 是两个不同的值

SnowLuma 同一个账号的 HTTP token（默认 3000 端口）与 WebSocket token（默认 3001 端口）并不相同 （实测；snowluma.accessToken 里通常只能存一个 —— 存的是 HTTP 那个）。因此：

- 桥接每次启动的首次 WS 连接几乎必然失败一次（日志里 SnowLuma 连接断开（code=1006） → SnowLuma 首次连接未成功（将在后台自动重连并尝试自愈 WS token）），随后自愈重新发现 WS token、重连成功，才打出 SnowLuma 已连接。这条序列是正常的，不是故障。
- 真正会一直连不上的情况：自愈无从下手 —— snowluma.homeDir 没配 / 被移动 / 读不到 SnowLuma 的 config/onebot_<QQ号>.json，或权限不足。这时日志里会有 token 自愈失败，而 QQ 侧表现为完全收不到消息。先确认 homeDir 指向真正的 SnowLuma 安装目录。

已知行为：端点自愈会覆盖你写的 wsUrl

换 QQ 账号后 OneBot 端口与 token 都会变，所以桥接在连不上时会自愈：重新发现 SnowLuma 的端点并 写回 config.json。这在主场景下是对的，但它不区分「配置里是个过期值」和「你就是要指向别处」——想跑第二个实例或指向另一份 SnowLuma 安装时会连错账号。要关掉：

"snowluma": { "followDiscoveredEndpoint": false }
关掉后只自愈 token（换账号仍能恢复），绝不动 URL，也不写回 URL。

已知限制

- 智能体回复在回合结束时一次性发送（不做流式逐字转发）；回复超过 socialV2.send.maxMessageChars（默认 500 字，可用 social.maxReplyChars 调整）自动按句读/URL 边界分段
- 图片及部分表情可以通过安全下载接入多模态模型；语音/视频以及无法取得图片字节的消息仍使用占位文本
- 发语音是支持的（独立工具的图形界面 / 命令行 / AI 工具，见 docs/README.md 的文档索引）；但收到的语音目前只显示占位文本，不做语音转写入上下文
- AI 发语音默认关闭（socialV2.voice.enabled 与 tools.sendVoice 默认 false）：先把音频放进 audio/，再到控制台打开开关；你自己发语音不受这个开关影响
- 智能体的 Markdown 回复会转成纯文本（链接保留 文字 (url) 形式）
- @snowluma/sdk 的 npm 发布版存在 ESM 扩展名 bug，本仓库通过 postinstall 补丁修复（见 scripts/patch-snowluma-sdk.mjs）

合规提醒

SnowLuma 是独立第三方项目，与腾讯/QQ 无隶属关系，仅供学习与技术研究；使用前请阅读其 EULA 与《QQ 用户协议》。