> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # File 数据结构 > Files API 复用的数据结构和上传限制。 ## 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 产出的文件。