| name | qq_file |
| description | 通用文件上传 — 通过 PushQueue 向 QQ(OneBot)或 Telegram 上传文件。当 Agent 需要分享文档、图片、PDF 等文件到外部平台时使用。 |
| version | 1.1 |
| category | messaging |
| enabled | true |
| tags | ["qq","telegram","file","upload","push"] |
上传文件 (QQ File)
通过消息路由的 PushQueue 机制,向 QQ 或 Telegram 上传文件。文件通过异步队列发送,支持私聊和群聊。
插件路径
plugins/qq_file/
注册工具
| 工具 | 用途 |
|---|
upload_qq_file | 向 QQ(OneBot)或 Telegram 上传文件 |
参数
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|---|
target | string | 是 | — | 目标 ID:QQ 号 / TG 用户 ID / 群号 |
chat_type | string | 是 | — | private(私聊)或 group(群聊) |
file_path | string | 是 | — | 要上传的本地文件绝对路径 |
platform | string | 否 | "onebot" | 平台:onebot(QQ)或 telegram。由智能体根据用户消息来源或用户指令决定 |
结果说明
- 成功:返回
OK: 文件上传任务已入队, ID: <task_id> + 平台/文件/目标信息
- 失败:返回
ERROR: 前缀的错误信息
平台差异
| 特性 | QQ (OneBot) | Telegram |
|---|
| 私聊文件 | upload_private_file | sendDocument |
| 群聊文件 | upload_group_file | sendDocument |
| 最大文件 | NapCat 限制 | 50MB (Bot API) |
典型场景
- 分享生成的报告/文档到 QQ/Telegram
- 发送下载的文件给用户
- 群聊共享文件
常见规范
file_path 需为本地存在的文件绝对路径
- 智能体生成的文件默认在
users/<user>/download/,上传时使用该路径
platform 由智能体根据用户消息来源判断
常见处理办法
- 文件不存在:检查
file_path 路径是否正确,文件是否已生成
- 上传失败:检查文件大小是否超过平台限制
- 平台不支持:确认
platform 为 onebot 或 telegram
常见教训
- Telegram Bot API 限制文件大小 50MB,超过会失败
- QQ 的文件上传能力取决于 OneBot/NapCat 实现,不同版本限制不同
- 文件上传是异步操作,入队成功不代表对方已收到