给 Hermes QQ 机器人补上发文件能力:hermes send 不支持 qqbot 附件的绕过实录

手头有个 23MB 的 APK 要发到自己 QQ 上(详见上一篇文章里的短剧 App,v0.2.3 发版了)。服务器上跑着 Hermes Agent 网关,QQ Bot 适配器一直在线,按理说一条命令的事,结果 hermes send 直接告诉我:不支持给 qqbot 发附件。

这篇文章记录了从碰壁到翻适配器源码、再到绕过限制把文件真正发出去的全过程。结论先说:Hermes 的 QQ 适配器本来就具备完整的文件发送能力,只是 CLI 的 send 命令没把它接上。补三十行胶水代码就能用。

一、现状盘点

服务器(甲骨文 ARM)上跑着 Hermes 网关,QQ Bot 平台已接入。先确认可用的发送目标:

$ hermes send --list
Available messaging targets:

Qqbot:
  qqbot:<OPENID> (dm)

Telegram:
  telegram:默然 (dm)

<OPENID> 是我和机器人的私聊会话 ID。目标明确,直接发:

$ hermes send --to qqbot:<OPENID> $'短剧 v0.2.3 安装包\nMEDIA:/www/wwwroot/duanju-release/duanju-v0.2.3-release.apk'
Sent to qqbot home channel (chat_id: <OPENID>)

返回 Sent,看似成功。但翻网关日志,一条媒体上传的记录都没有——QQ 里收到的只是纯文本,MEDIA: 那行被当成了普通文字。

二、第一跳翻车:CLI 的媒体白名单

换 --json 模式重发,拿到了明确的报错:

{
  "error": "send_message MEDIA delivery is currently only supported for
           telegram, discord, matrix, weixin, signal, yuanbao, feishu,
           whatsapp and slack; target qqbot had only media attachments"
}

也就是说 hermes send 的媒体发送是一份硬编码的平台白名单,qqbot 不在名单里。这解释了为什么第一次返回 Sent——文本走通了,MEDIA: 附件被静默忽略。

三、翻源码:能力都在,只是没接线

顺着报错看适配器源码(gateway/platforms/qqbot/adapter.py),发现它不仅有媒体能力,还相当完整:

  • send_document() / send_video() / send_voice() / send_image() 一应俱全,全部汇入 _send_media();
  • _send_media() 实现了三种上传策略:HTTP(S) URL 直传(把 URL 丢给 QQ 平台,让它自己来拉)、本地文件分块上传(prepare → PUT parts → finish 三步式,官方号称支持到 ~100MB/文件)、以及旧的 base64 内联(~10MB 上限);
  • _upload_media() 带瞬时失败重试;
  • 还有一层 file_info 上传缓存(同一文件短时间内重复发送不重传)。

历史日志也印证了这条路是通的——9 月发过图片成功,也试过一次 512KB 的 .tar.gz:

INFO gateway.platforms.qqbot.chunked_upload: Chunked upload start: file=momo2026-template.tar.gz size=512.5 KB type=4
ERROR gateway.platforms.qqbot.adapter: Media send failed: QQ Bot API error [400]
  /v2/users/<OPENID>/upload_part_finish: 文件上传失败,请重试

那次失败是个坏信号(后面还会遇到它),但也说明整条链路是被真实调用过的,卡点只在最后一步的 finish 接口。

真正的障碍在代码里的一行门槛:

@property
def is_connected(self) -> bool:
    """Return True only when the QQ WebSocket transport is usable."""
    return bool(self._running and self._ws and not self._ws.closed)

_send_media() 开头就检查 is_connected,不通就走 _wait_for_reconnection() 等重连。而如果我想写个独立脚本脱离网关跑,就不会有 WebSocket 连接——这个检查永远过不去。

但注意:token 获取和媒体上传、消息发送全是 REST 调用,根本不依赖 WebSocket。WebSocket 只用来收消息、维持心跳。这行检查是防御性的,不是功能性的。

四、绕过方案:三十行胶水代码

思路:不完整初始化适配器(省掉 BasePlatformAdapter 的状态目录、平台锁等一堆东西),用 __new__ 跳过 __init__,手工补齐 _send_media 链路真正用到的状态,再把两个连接检查打上补丁:

#!/usr/bin/env python3
"""Send a file to a QQ user via Hermes qqbot adapter's REST path (no WS)."""
import asyncio
import os
import sys
from pathlib import Path

sys.path.insert(0, "/usr/local/lib/hermes-agent")

# 加载 ~/.hermes/.env 里的 QQ_APP_ID / QQ_CLIENT_SECRET(凭据不进代码)
for line in Path("/root/.hermes/.env").read_text().splitlines():
    line = line.strip()
    if line and not line.startswith("#") and "=" in line:
        k, _, v = line.partition("=")
        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))

import httpx  # noqa: E402
from gateway.platforms.qqbot.adapter import QQAdapter  # noqa: E402

CHAT_ID = "<OPENID>"
URL = "/www/wwwroot/duanju-release/duanju-v0.2.3-release.apk"
CAPTION = "文件说明文字"


async def _fake_wait(self, timeout: float = 30.0) -> bool:
    return True


async def main() -> int:
    ad = QQAdapter.__new__(QQAdapter)
    ad._app_id = os.environ["QQ_APP_ID"]
    ad._client_secret = os.environ["QQ_CLIENT_SECRET"]
    ad._http_client = httpx.AsyncClient(trust_env=True)
    ad._access_token = None
    ad._token_expires_at = 0.0
    ad._token_lock = asyncio.Lock()
    ad._chat_type_map = {}
    ad._upload_cache = {}
    ad._last_msg_id = {}
    ad._typing_sent_at = {}

    QQAdapter.is_connected = property(lambda self: True)
    QQAdapter._wait_for_reconnection = _fake_wait

    result = await ad.send_document(CHAT_ID, URL,
                                    caption=CAPTION,
                                    file_name="duanju-v0.2.3-release.apk")
    print("success:", result.success)
    print("error:", getattr(result, "error", None))
    return 0 if result.success else 1


if __name__ == "__main__":
    sys.exit(asyncio.run(main()))

几个细节:

  • __new__ 而不是 QQAdapter(config):完整初始化要构造 PlatformConfig、触发平台锁、写运行时状态目录,独立脚本没必要。手工补的这几个字段就是 _send_media → _upload_media → _api_request → _ensure_token 这条链路的全部依赖。
  • 补丁只改行为,不改数据:is_connected 和 _wait_for_reconnection 是仅有的两处 WebSocket 依赖,直接替换成恒真。
  • chat_type 不用管:_guess_chat_type() 查不到映射时默认返回 "c2c",私聊场景刚好命中。
  • 凭据零拷贝:QQ_APP_ID / QQ_CLIENT_SECRET 运行时从 Hermes 的 .env 读,脚本里没有任何密钥,可以随便存随便传。

五、踩坑记录:URL 直传是不归路

第一版脚本传的是 HTTP URL——让 QQ 服务器直接从我的下载站拉 APK,理论上最快(本机零流量):

error: QQ Bot API error [400] /v2/users/<OPENID>/files: 富媒体文件下载失败

被 400 拒了。「富媒体文件下载失败」是 QQ 平台侧拉取 URL 失败——大概率是平台出口访问不了我的域名(7998888.xyz 走灰云直连甲骨文),或者对来源域名有白名单限制。这条路放弃。

改传本地路径,走分块上传:23.2MB 按 10MB 一片切成 3 片,prepare → PUT → finish,一次成功:

success: True
error: None

QQ 里立刻收到文件消息,带说明文字。9 月那次 512KB 分块上传失败应该是平台瞬时故障,这次 23MB 反而顺畅——分块上传本身是可靠的,遇到失败重试即可。

最后补一条纯文字消息(这个 hermes send 是支持的)把 MD5 发过去方便核对,闭环。

六、复用方法

把脚本存成 qq_send_file.py,要改的只有三处:

  • CHAT_ID:目标私聊 openid(用 hermes send --list 查);
  • URL:本地文件路径(URL 直传在多数自建域名上会被 QQ 拒,别抱侥幸);
  • CAPTION / file_name:说明文字与文件名。

运行:

sudo /usr/local/lib/hermes-agent/venv/bin/python qq_send_file.py

顺带一提,中途还踩了一个小坑:给适配器实例赋值 ad._log_tag = "..." 会报 AttributeError: property has no setter——基类把它定义成了只读 property,删掉即可,logger 会用默认 tag。

七、技术要点备忘

  • Token:POST {TOKEN_URL},body 为 {"appId": ..., "clientSecret": ...},返回的 access_token 默认 2 小时有效,适配器里有单飞(singleflight)刷新;
  • 媒体上传:POST /v2/users/{openid}/files,file_type=4 表示普通文件(1=图片 2=视频 3=语音);srv_send_msg=false 表示只拿 file_info 不直接发送,之后再发 msg_type=7(媒体消息)引用它——两步式,这样才能带说明文字、复用 file_info;
  • 分块上传:prepare 返回 upload_id 和 block_size(10MB),按片 PUT,最后 upload_part_finish;单文件上限 ~100MB;
  • msg_seq:同一 msg_id 下多次回复要递增 msg_seq,否则会被去重;主动消息无 msg_id 时用自增序号;
  • CLI 白名单位置:报错文案在 hermes_cli 的 send 命令实现里,硬编码平台列表。升级 Hermes 时留意这里可能变化,但适配器层的 send_document 接口是稳定的;
  • 安全:appSecret 只存在于 ~/.hermes/.env;openid 属于半公开标识,写文章时替换掉即可。

结语

这次的完整路径:CLI 报错 → 读报错找白名单 → 翻适配器源码确认能力存在 → 找出唯一的依赖(WebSocket 连接检查)→ 补状态 + 打补丁 → URL 直传失败退回分块上传 → 成功。本质上就是「先确认能力,再找卡点,卡点通常只挡在门口,不挡在路上」。

如果之后 Hermes 官方把 qqbot 加进 send 的媒体白名单,这篇脚本就可以退休了;在那之前,它就是短剧 App 发版流程里的最后一公里。

© 版权声明
THE END
喜欢就支持一下吧
点赞5 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容