DeepSeek Harness 插件：dsh-im-qq（QQ 官方机器人接入）

前言¶

DeepSeek Harness（DSH）将大模型能力封装为本地可运行的 Agent。在本地运行 Agent 的常见场景中，往往需要通过 IM 渠道与其交互。接入 QQ 官方机器人（q.qq.com）通常涉及处理 WebSocket 长连接、消息路由、会话隔离以及复杂的权限审批逻辑。

dsh-im-qq 插件解决了上述问题。它作为一个中间层，将 QQ 的消息流转换为 DSH 的标准事件，并反向将 Agent 的思考结果发回 QQ。通过该插件，用户可以直接在 QQ 私聊、群聊或频道中调用 Harness 的完整能力（工具调用、记忆、子代理等）。

插件简介¶

名称：dsh-im-qq
维护者：988hj7tczd-oss
核心价值：将 QQ 官方机器人协议接入 DSH，实现全功能 Agent 的 IM 交互。
许可协议：MIT

核心功能¶

该插件实现了以下核心能力：

消息接入：支持私聊（C2C）、群聊 @机器人、频道 @机器人。
会话隔离：自动为每人/每群建立独立会话，消息前缀统一为 qq:。
Agent 能力：完整支持工具调用、记忆管理、子代理和文件系统操作。
连接机制：基于 WebSocket 长连接，支持心跳、断线重连（RESUME）和自动识别。
消息处理：支持回复合并、超长分段、去除内部标签及错误兜底。
安全与频控：白名单机制（Fail-closed）与消息频率控制。
审批桥：通过 QQ 内联按钮（✅/⭐/❌）实现高权限操作的审批，支持 /revoke 撤销。
斜杠命令：支持 /help、/ping、/me、/new、/approve、/always、/revoke 等指令。

安装与配置¶

安装¶

在插件目录下执行安装脚本：

./install.sh

安装完成后，重启 harness-desktop。

配置¶

方式 A（推荐）：桌面端设置
1. 打开 设置 → 插件 → 插件配置。
2. 找到 QQ 机器人 卡片。
3. 填入 AppID 和 AppSecret，点击保存并启动。凭据将写入 $DSH_HOME/.credentials.yaml。

方式 B（手动）：编辑配置文件
编辑 $DSH_HOME/cordis.patch.yml，添加如下配置块（id 必须加引号以防 YAML 解析为数字）：

- insert:
    - id: dsh-im-qq
      name: dsh-im-qq
      config:
        id: '你的AppID'
        secret: '你的AppSecret'
        sandbox: true
        transport: 'websocket'
        provider: 'deepseek-official'
        model: 'deepseek-v4-flash'
        agentPreset: 'standard'
        cwd: '~/qq-workspace'
        workspaceIsolation: true
        allowFrom: ['*']
        groupAllowFrom: ['*']
        deliverWindowMs: 900
        textChunkLimit: 4000
        replyPassiveLimit: 4
        approval: true
        slashCommands: true
        debug: false

使用方法¶

私聊：直接发送消息给机器人。
群聊/频道：@机器人后跟消息内容。
斜杠命令：
- /help：查看帮助
- /ping：检查连接状态
- /me：发送用户信息
- /new：创建新会话
- /approve / /always：审批相关
- /revoke：撤销审批权限
审批流程：当 Agent 需要执行高权限操作时，会在 QQ 消息中弹出内联按钮。
- ✅ 允许一次：临时授权。
- ⭐ 始终允许：永久授权（可用 /revoke 撤销）。
- ❌ 拒绝：拒绝该次请求。

注意事项与故障排查¶

1. 机器人类型与测试人员（必须核对）¶

公域 vs 私域：在 q.qq.com 创建机器人时，必须选择公域机器人。私域机器人无法调用群组接口，会导致永久报错 11255。
测试人员：必须在 测试人员管理 中添加你的 QQ 号。非测试人员发消息也会导致 11255 错误。
Sandbox 模式：建议先开启 sandbox: true 验证，稳定后再切换为 false。

2. 常见错误处理¶

WS Close Code 4009：日志中出现此代码是正常行为（QQ 服务器约每 30 分钟主动断连），插件会自动 RESUME/重连，无需干预。
消息回复慢/无回复：
- 开启 debug: true 查看日志。
- 检查入站管线是否被 ACL 拒绝。
- 检查 Agent 是否报错（会有兜底文本提示）。
回复带 URL 发送失败：QQ 平台要求消息中的 URL 必须在后台 消息 URL 配置 中预先添加，否则整条消息发送失败。
缺少凭据：检查 id 是否被解析为数字（必须加引号），secretEnv 指向的环境变量是否已导出。
审批按钮无反应：确认平台侧已订阅按钮互动事件（intent 1<<26）。

3. 主动消息配额¶

QQ 官方限制主动消息每月 4 条/人/群。插件默认优先使用被动回复（在 msg_id 有效期内），正常对话不消耗配额。只有当回复长度超过被动上限（默认 4 条/消息）时，才会转为消耗配额的主动消息。若遇到 50015014 错误，说明触发了频控，插件已实现指数退避重试，但高频主动推送仍可能受限。

4. 已知边界¶

图片/流式/Typing：接口预留了配置项，但代码尚未实现（P4/P5 级别）。
Webhook：官方长期方向是 Webhook（需公网 HTTPS + IP 白名单）。当前架构已抽象双模式，未来仅需实现 platform/transport/webhook.js 即可切换。