File 数据结构 - Qoder

File 对象

上传、查询和列表接口都会返回 File 对象。

字段	类型	说明
`id`	string	File ID，前缀为 `file_`
`type`	string	固定为 `"file"`
`filename`	string	存储后的文件名
`size_bytes`	integer	文件大小，单位 byte
`mime_type`	string	上传时提供或根据文件名检测出的 MIME type
`downloadable`	boolean	是否可通过 `GET /api/v1/cloud/files/{file_id}/content` 下载
`scope`	object \| null	文件关联到其他资源时的 scope，例如 `{ "id": "sess_...", "type": "session" }`
`metadata`	object	上传时传入的自定义元数据对象；省略时为 `{}`
`created_at`	string	UTC 创建时间，RFC 3339 格式

File content link

GET /api/v1/cloud/files/{file_id}/content 返回该结构。

字段	类型	说明
`url`	string	预签名下载 URL
`expires_at`	string	URL 的 UTC 过期时间，RFC 3339 格式

上传表单字段

POST /api/v1/cloud/files 使用 multipart/form-data。

字段	类型	必填	说明
`file`	file	是	文本类文件内容
`name`	string	否	存储文件名。不传时使用上传文件名。服务端清理后长度必须为 1-255 byte，且不能是 `.` 或 `..`
`metadata`	JSON string	否	作为表单字段传入的合法 JSON。原始长度最大 8 KB，省略时为 `{}`

支持上传的文件类型

上传接口只接受文本类文件。

类别	支持的值
MIME type	任意 `text/*` MIME type，以及 `application/json`、`application/xml`、`application/javascript`、`application/x-yaml`、`application/x-toml`
文件扩展名	`.txt`、`.md`、`.csv`、`.json`、`.xml`、`.yaml`、`.yml`、`.toml`、`.ini`、`.conf`、`.cfg`、`.env`、`.log`、`.html`、`.htm`、`.css`、`.scss`、`.less`、`.js`、`.jsx`、`.ts`、`.tsx`、`.vue`、`.svelte`、`.py`、`.go`、`.rs`、`.java`、`.kt`、`.scala`、`.c`、`.cpp`、`.cc`、`.h`、`.hpp`、`.rb`、`.php`、`.swift`、`.r`、`.lua`、`.pl`、`.sh`、`.bash`、`.zsh`、`.fish`、`.ps1`、`.sql`、`.graphql`、`.gql`、`.proto`、`.dockerfile`、`.makefile`、`.gitignore`、`.editorconfig`、`.eslintrc`、`.prettierrc`、`.tex`、`.rst`、`.adoc`、`.org`、`.svg`
无扩展名文件名	`dockerfile`、`makefile`、`gemfile`、`rakefile`、`procfile`、`vagrantfile`、`justfile`、`brewfile`

相关

附加与下载文件

上传文件为 Agent 提供上下文，并下载 Agent 产出的文件。

删除文件列出 Memory Stores