first commit

autonomous-ai-agents/hermes-agent/references/qqbot-media-api.md

@@ -0,0 +1,61 @@
+# QQ Bot Rich Media API Reference
+
+Source: https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/send-receive/rich-media.html
+
+## Endpoints
+
+| Scope | Endpoint | Method |
+|-------|----------|--------|
+| 单聊 | `/v2/users/{openid}/files` | POST |
+| 群聊 | `/v2/groups/{group_openid}/files` | POST |
+
+## Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| file_type | int | Yes | 1=图片, 2=视频, 3=语音, 4=文件 |
+| url | string | Yes* | 媒体资源 URL（*url 或 file_data 二选一） |
+| file_data | string | No | base64 二进制数据 |
+| srv_send_msg | bool | Yes | true=直接发送（占用主动消息频次），false=仅上传获取 file_info |
+| file_name | string | No | 文件名（file_type=4 时建议传） |
+
+## Supported Formats
+
+- 图片: png/jpg
+- 视频: mp4
+- 语音: silk/wav/mp3/flac
+- 文件: 无限制（群场景暂不开放 file_type=4）
+
+## Response
+
+```json
+{
+  "file_uuid": "...",
+  "file_info": "...",   // 用于发送消息接口的 media 字段
+  "ttl": 3600           // 剩余秒数，0=长期有效
+}
+```
+
+## Sending with file_info
+
+```json
+{
+  "msg_type": 7,
+  "media": {"file_info": "<file_info_from_upload>"},
+  "msg_seq": 1
+}
+```
+
+## Notes
+
+- `file_info` 不受目标端影响，可复用到多个群/用户
+- 用 `/v2/users/{openid}/files` 上传的仅能发单聊，群上传的仅能发群聊
+- 建议 `srv_send_msg=false`，先获取 file_info 再发送
+- 文件大小限制：~100MB（分块上传），~10MB（inline base64）
+
+## Hermes Adapter Implementation
+
+- Gateway adapter: `gateway/platforms/qqbot/adapter.py` → `_send_media()` (line ~2690)
+- Chunked upload: `gateway/platforms/qqbot/chunked_upload.py`
+- Media types defined in `gateway/platforms/qqbot/constants.py` (MEDIA_TYPE_IMAGE=1, VIDEO=2, VOICE=3, FILE=4)
+- send_message tool gap: `_send_qqbot()` in `tools/send_message_tool.py:1677` is text-only