qq-file

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 实现，不同版本限制不同
• 文件上传是异步操作，入队成功不代表对方已收到