file_transfer

在插件与框架之间分片上传、下载和读取文件。

适用协议

框架接口，不受 QQ 登录协议限制。

调用方式

{
  "type": "action",
  "id": "file_transfer-1",
  "action": "file_transfer",
  "params": {
    "operation": "start_upload",
    "filename": "hello.txt",
    "size": 5,
    "sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
  }
}

参数

参数	类型	必填	说明
operation	string	是	start_upload、write、finish、start_download、read、status 或 cleanup。

返回值

start_upload、write、finish、start_download、status 返回：

字段	类型	说明
token	string	当前服务专用传输标识
file	string	transfer:// 引用；完成后可传给媒体上传等接口
filename	string	文件显示名
size、offset	number	总大小与已接收位置，单位字节
status	string	uploading 或 ready
expires_at	string	UTC RFC3339 失效时间
max_chunk_size	number	最大分片 1048576 字节
sha256	string	完成后返回的文件摘要
width、height	number	识别为图片时可返回尺寸

read 返回 { token, offset, next_offset, data, eof, size, sha256 }，data 为标准 Base64。cleanup 返回 { removed: true }。

注意事项

此接口不接收 self_id 或 protocol_id，传输绑定当前插件服务。单文件上限 128 MiB，单分片上限 1 MiB；单服务最多 4 个传输、预留 256 MiB，全局最多 32 个、512 MiB。传输保存 10 分钟，finish 与下载完成后重新计时；重启后令牌不可复用。用完请 cleanup。

transfer:// 是框架中的临时文件引用，不是 QQ 媒体 file_id；要发送图片、语音或视频，仍须调用对应媒体上传接口。

分片上传

operation	参数	说明
start_upload	filename?: string、size: number、sha256: string	size 可为 0；sha256 为原始完整文件的 64 位十六进制摘要
write	token: string、offset: number、data: string	标准 Base64，按 offset 顺序提交；允许相同内容的完整重复分片，不允许缺口或覆盖不同内容
finish	token: string	校验完整长度及 SHA256 后才标记 ready；可重复查询已完成结果
status	token: string	查询状态与已接收位置
cleanup	token: string	删除临时文件与传输记录

上方创建示例为 5 字节的 hello。拿到 token 后依次发送：

{"operation":"write","token":"创建返回的token","offset":0,"data":"aGVsbG8="}

{"operation":"finish","token":"创建返回的token"}

下载与读取

参数	类型	必填	说明
operation	string	是	start_download
source	string	是	公网 HTTP(S) 地址、允许读取的本地路径／file:// 路径，或当前服务的已完成 transfer:// 引用
filename	string	否	文件显示名
sha256	string	否	可选预期摘要，提供时须匹配最终文件
kind	string	否	file（默认）、image、record
out_format	string	否	仅 kind=record 时可传 mp3 或 wav；转换失败会返回错误
headers	object 或 string[]	否	下载请求头；禁止 Host、Connection、Content-Length、Transfer-Encoding、Proxy-Authorization、Proxy-Connection；对象值为字符串或字符串数组，数组项为“名称: 值”

远端下载最长 2 分钟，禁止访问本机、内网和保留网段。本地路径仍受框架文件访问限制，并非任意文件读取。

下载 ready 后分片读取：

{"operation":"read","token":"下载返回的token","offset":0,"length":65536}

length 默认 65536，范围 1–1048576。按 next_offset 继续，直到 eof=true。