Derpyu520/qq-bridge

解决的问题

该项目将 QQ 消息系统与 DeepSeek Harness (DSH) 代理框架连接，使用户可以通过 QQ 私聊或群聊与 AI 代理进行交互。它将 QQ 消息转换为 DSH 会话，并将代理的回复、问题和工具审批结果返回给 QQ 用户。

工作原理

该桥接器作为 SnowLuma（一个 OneBot v11 WebSocket 客户端）与 DSH Web API 之间的中间件。它将每个 QQ 聊天（私聊或群组）映射到专用的「QQ 聊天」工作区内的唯一 DSH 会话。

关键技术组件包括：

• 通信：使用 WebSocket 通过 SnowLuma 连接 QQ，使用 REST/Event-stream API 与 DSH 通信。
• MCP 集成：集成 Model Context Protocol (MCP) 服务器，为代理提供安全能力，例如发送消息、检查群组状态、执行带 SSRF 保护的网络搜索。
• 运行模式：支持多种模式，包括 chat（标准安全聊天）、closed-agent（仅所有者拥有完整工具访问权限）、reserved（通过状态机模拟群成员行为，支持活跃与静默状态）。
• 交互逻辑：处理复杂的 QQ 交互，如消息引用（回复）、斜杠命令（例如 /reset）以及为模拟角色拆分多部分消息。

适用人群

• 希望将 AI 代理引入 QQ 的 DeepSeek Harness 用户。
• 想要创建“AI 模拟群成员”以自主观察和参与聊天的开发者。
• 希望通过 QQ 远程控制其 DSH 实例的高级用户。

核心亮点

• 多模式运行：可在标准聊天、所有者专属代理控制和自主模拟模式之间自由切换。
• 安全工具：通过 MCP 限制 QQ 操作子集，防止未经授权的账户控制。
• 会话管理：自动管理并持久化 QQ ID 与 DSH 会话之间的映射关系。
• 交互式反馈：将代理请求的用户问题和工具审批请求直接转发至 QQ，实现实时决策。
• 内置控制台：提供基于 Web 的控制面板，支持实时切换模式和配置角色。