File API 的共享数据结构、枚举值及上传约束。
上传、获取和列表接口返回 File 对象。
上传接口仅接受文本类文件。
File 对象
上传、获取和列表接口返回 File 对象。
| 字段 | 类型 | 说明 |
|---|---|---|
file_id | string | 文件 ID，前缀 file_ |
filename | string | 存储的文件名 |
size_bytes | integer | 文件大小（字节） |
mime_type | string | 上传时提供或根据文件名检测的 MIME 类型 |
purpose | string | 文件用途。参见 File purpose |
status | string | 文件状态。参见 File status |
metadata | object | 上传时提供的元数据 JSON；默认 {} |
created_at | string | UTC 创建时间（RFC 3339 格式） |
updated_at | string | UTC 更新时间，仅当与 created_at 不同时返回 |
session_id | string | 文件关联的 Session ID（关联时返回） |
File purpose
| 值 | 说明 |
|---|---|
user_upload | 用户上传的文件，供后续使用 |
tool_output | 工具产生的文件 |
skill_output | Skill 产生的文件 |
session_resource | 作为 Session 资源附加的文件 |
agent_output | Agent 输出的文件 |
File status
| 值 | 说明 |
|---|---|
uploading | 上传记录已创建，内容上传进行中 |
ready | 文件内容可用 |
error | 记录创建后上传失败 |
deleted | 文件已删除；仅在显式包含已删除文件的列表请求中返回 |
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 字节，不能为 . 或 .. |
purpose | string | 否 | 默认为 user_upload。参见 File purpose |
metadata | JSON string | 否 | 编码为表单字段的有效 JSON。最大原始长度 8 KB。默认 {} |
支持的上传文件类型
上传接口仅接受文本类文件。
| 类别 | 支持的值 |
|---|---|
| MIME 类型 | 所有 text/* MIME 类型，以及 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 |