QQ 官方机器人适配器 (adapter-qq)

为 DeepSeek Harness 提供 QQ 官方机器人的接入能力。

功能特性

• 消息收发：支持频道 @机器人、群聊 @机器人 和单聊消息。
• 会话管理：按频道、群或单聊用户创建或恢复独立的 Agent 会话。
• 沙箱支持：开启后使用 QQ 官方沙箱 OpenAPI 接入点。
• 自动重连：维持 WebSocket 心跳，并在连接断开后重连。
• 模型自定义：支持在配置中指定默认使用的 AI 提供方和模型。

接入指南

1. 安装依赖

在项目根目录执行：

pnpm install

2. 配置插件

在你的 cordis.yml 或 cordis.patch.yml 中添加以下配置：

- id: adapter-qq
  name: 'file://D:/dev/dsh/plugins/adapter-qq/src/index.ts'
  config:
    id: '你的 AppID'
    secret: '你的 AppSecret'
    sandbox: true # 调试阶段建议开启
    # 默认同时订阅频道 @ 消息、群聊 @ 消息和单聊消息。
    # 如需自定义，保留 PUBLIC_GUILD_MESSAGES (1 << 30) 与 USER_MESSAGE (1 << 25)。
    # intents: 1107296256
    provider: 'deepseek' # 可选，默认为 deepseek
    model: 'deepseek-chat' # 可选，默认为 deepseek-chat
    cwd: 'D:/dev/your-project' # 新建 QQ 会话运行的绝对目录

3. 启动项目

确保使用正确的配置文件启动。如果你在根目录编辑了 cordis.yml，请使用以下命令启动：

pnpm dsh web --patch cordis.yml

或者将配置直接添加到你正在使用的 profile 中（例如 ~/.dsh/profiles/web/cordis.patch.yml）。

注意事项

• 权限要求：机器人需要在 QQ 开放平台开通相应消息权限。默认订阅“公域消息”与“用户消息”；群聊和单聊使用用户消息事件。未获批的事件不会推送到网关。
• 自定义订阅：intents 会完整替换默认掩码。若只配置其他事件而遗漏 PUBLIC_GUILD_MESSAGES 或 USER_MESSAGE，对应的频道、群聊和单聊消息不会到达适配器。
• 回复规则：适配器会按收到事件的来源调用频道、群聊或单聊发送接口，并携带原始消息 ID 作为被动回复关联。
• 工作目录：cwd 必须是绝对目录，并写入新建会话的持久化元数据。已恢复的 QQ 会话保留原有目录；要为旧会话切换目录，请新建会话。
• 调试日志：设置 debug: true 后会记录网关事件和会话恢复失败，便于确认 QQ 是否已推送消息。