dsh-qqbot：将 QQ 消息作为 DSH Agent 的前端协议驱动

前言¶

DeepSeek Harness (DSH) 的核心理念之一是“一切皆插件”。当需要通过即时通讯软件与 Agent 交互时，需要一个标准化的驱动层。dsh-qqbot 插件提供了这样的能力，将 QQ 消息平台作为 dsh agent 的前端协议驱动。用户可以在 QQ 私聊或群聊中与 Agent 对话，执行工具、切换模型、管理会话或工作区，并通过 QQ 消息完成审批。

插件定位¶

dsh-qqbot 是一个开源的 DeepSeek Harness (dsh) QQ Bot IM 插件。该项目由 cafeawa 维护，遵循 MIT 许可证。

本插件从零重写，不包含腾讯内部插件代码，也不依赖 UNLICENSED 的 @tencent-connect/qqbot-connector。其底层协议使用 MIT 许可的 @tencent-connect/qqbot-nodejs。

核心功能¶

插件具备以下核心能力：

消息接入与展示：支持 QQ 私聊（C2C）与群聊消息接入。支持流式回复与 Markdown 分块发送，确保长文本在 QQ 平台上的正常展示。
会话管理：支持会话隔离、空闲回收与重启恢复，以及工作区隔离与跨会话切换。
模型路由：支持 per-peer（单聊对象）偏好配置，或通过 settings.yaml 配置，亦可继承宿主默认设置。
上下文处理：支持群聊历史上下文、引用消息处理及文件附件下载。
内置命令：提供 dsh、goal、/bot-model、/bot-reset、/bot-status、/bot-workspace 等命令。
审批桥接：提供 dsh 审批桥接功能，支持通过 QQ 按钮/文字审批，WebUI 同时给予提示。
任务通知：支持 goal 长任务完成通知。

安装与配置¶

环境要求¶

Node.js >= 18，且 dsh 环境已可用。

构建与安装¶

在 dsh-qqbot 项目目录下，执行以下命令进行构建并安装到 dsh profile：

# 1. 安装依赖并构建
corepack pnpm install
corepack pnpm build

# 2. 安装插件（使用本地路径）
dsh plugin --profile qqbot add /path/to/dsh-qqbot

安装后，可通过 --patch 方式通过 cordis.patch.yml 加载。

配置文件¶

在 profile 的 cordis.patch.yml 中，需配置 QQ Bot 的凭证及部分运行参数：

- id: im-qqbot
  config:
    appId: __FROM_ENV__
    appSecret: __FROM_ENV__
    requireMention: true
    textChunkLimit: 4500
    sessionIdleTimeout: 1800000
    maxQueue: 20
    processingTimeoutMs: 120000
    historyLimit: 10
    access:
      c2cMode: open
      c2cAllow: []
      groupMode: open
      groupAllow: []
    debug: false

主要配置项说明：
* appId / appSecret：QQ Bot 凭据，支持从环境变量 QQBOT_APPID / QQBOT_SECRET 读取。
* requireMention：群聊模式下是否需要被 @bot 才能触发对话。
* sessionIdleTimeout：会话闲置回收时间（毫秒）。
* access：访问控制模式（open 为开放）。

启动与使用¶

配置完成后，通过以下方式启动 dsh 并加载插件：

export QQBOT_APPID="你的AppID"
export QQBOT_SECRET="你的AppSecret"
dsh --profile qqbot

架构说明¶

插件的消息处理流程如下：

QQ 用户 → QQ WebSocket → @tencent-connect/qqbot-nodejs → 中间件链
                                                              ↓
                                                     handleInbound
                                                              ↓
                                                     SessionManager → dsh agent
                                                              ↓
                                              session/event → outbound → QQ Markdown

注意事项¶

插件以当前 dsh 进程的权限运行，请确保安装前检查源码与许可证。
生态背景：DSH 理念是“一切皆插件”，社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。

总结¶

dsh-qqbot 为 DSH Agent 提供了标准化的 QQ 接入层。通过会话管理、模型路由和审批桥接等功能，它使得在 QQ 平台上构建复杂工作流成为可能。项目地址：https://github.com/cafeawa/dsh-qqbot