dsh-qq-bot

English | 中文

面向模型的 qq_send_message 工具：通过 QQ 机器人开放平台（api.bot.qq.com）向 QQ 单聊用户或群聊发送文本消息。配置 inbound: true 时，还能通过 WebSocket 网关接收 QQ 消息并驱动 agent。它是一个实现包——只把工具注册进 ctx.tools，不拥有 ctx.tools 键，也不注册任何服务键。

作用

在 ctx.tools 上注册 qq_send_message(channel, openid, content, format?)。channel 为 "user" 表示单聊（目标是用户 openid），"group" 表示群聊（目标是群 openid）。format 为 "text"（默认）或 "markdown"。一次调用会先换取 Access Token（POST /app/getAppAccessToken，携带 AppID/AppSecret），再发送消息（POST /v2/users/{openid}/messages 或 /v2/groups/{openid}/messages，请求头 Authorization: QQBot ；文本请求体 { content, msg_type: 0 }，Markdown 请求体 { markdown: { content }, msg_type: 2 }）。

Access Token 有效期为 2 小时；QqBotClient 会缓存并在到期前 60 秒窗口内刷新。Markdown 支持 QQ 文档列出的子集——标题、加粗/斜体/删除线、链接、图片（公网 URL）、有序/无序列表、块引用与水平分割线；代码块与表格不在文档列表中。富媒体与内置键盘未由本工具投射。

配置 inbound: true 时，本包会启动一条出站的 WebSocket 网关连接（QqBotGateway）。它将每个 QQ 单聊 / 群聊映射到一个专属 agent 会话，把入站的 C2C_MESSAGE_CREATE / GROUP_AT_MESSAGE_CREATE 文本经 followup 灌入，并把该轮最终提交的 assistant 文本回推给发送者。鉴权复用同一对 AppID/AppSecret——Identify 的 token 为 QQBot ，intents 为 `1 add github:gushiaoke/dsh-qq-bot

2. 挂载：在 profile 的补丁层 `~/.dsh/profiles//cordis.patch.yml` 追加一条 `insert` 条目：

```yaml
- insert:
    - id: qq-bot
      name: 'dsh-qq-bot'
      config:
        appId: !!js process.env.QQBOT_APP_ID ?? ''
        appSecret: !!js process.env.QQBOT_APP_SECRET ?? ''
        inbound: true
        inboundProvider: deepseek-official
        inboundModel: deepseek-v4-flash
        inboundFormat: markdown
        inboundCwd: /absolute/working/directory

3. 配置凭证（见下文「凭证」章节）并启动：

dsh --profile 

凭证（AppID + AppSecret）

在 QQ 机器人开发者后台 创建机器人，复制其 AppID（机器人 ID）和 AppSecret（密钥）。旧的 Token 凭证已废弃，无需配置。

按优先级（环境变量 > 项目 .env > harness-home .env）三选一提供：

方式一：环境变量（生产推荐）：