Qq Bridge

Bridge between QQ (SnowLuma OneBot v11) and DeepSeek Harness agents: social simulation, safe MCP tools, slang learning and more.

LLM Mart
1 views 74 listing impressions
0 Visit tool

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

📘 详细内外核说明书见 docs/PROJECT_GUIDE.md（架构、数据流、配置全解、调试与改进指南）。

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

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

⚠️ 当前版本 v0.1.5，适配 DSH 0.1.5-rc.1（在该版本上逐项实测）。使用 Cookie 鉴权、斜杠 RPC 和 /api/remote.mux 事件流；这一代协议自 DSH 0.1.2-alpha.1 起引入，与更早的点号 endpoint 协议不兼容——DSH 0.1.1-rc.2 及更早请改用 tag v0.1.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.1.5 复核通过的协议——launch token 换 Cookie 鉴权、/api/<namespace>/<method> 斜杠 RPC、/api/remote.mux + session/follow 事件流；复用 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（默认只读探活）；start_snowluma / stop_snowluma 需显式开启 snowluma.allowProcessControl: true 且仅在 closed-agent 模式可用
    • web-search-safe（桥接自带 src/mcp-web-search-safe.js）：只读 web_search / web_fetch（带 SSRF 防护），供 agent 查网络用语/资料
  • 会话模型：每个 QQ 会话（私聊/群）对应一个独立的 DSH 会话，统一归组到「QQ 聊天」工作区（不再散落未分组）；映射持久化在 state/sessions.json
  • 性格定制：QQ 会话默认使用 qq-chat agent preset（~/.dsh/.agent-presets/qq-chat/agent.cordis.yml），reserved2 使用 qq-chat-v2（~/.dsh/.agent-presets/qq-chat-v2/agent.cordis.yml）；人格与默认 DSH 一致（coding agent），仅附加 QQ 场景规则；角色扮演是可选机制——由控制台或管理端设置 state/current-role.json 注入（群友无法更改）
  • 本地控制台：桥接自带 Web 控制台 http://127.0.0.1:3100——切换运行模式（chat / closed-agent / reserved / reserved2）、设置角色、静默开关、查看活动日志、修改管理员/控制台令牌，全部即时生效；访问需要令牌（config.json 的 consoleToken，未配置时自动生成并打印在启动日志；控制台内可手动修改或重新生成）
  • 运行模式：
    • 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

From the project's README.

Comments (0)

Sign in to join the conversation.

No comments yet.