手头有个 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 发版流程里的最后一公里。





暂无评论内容