Forward File API 复用的响应结构。
File 对象
上传、查询、列表接口都会返回该结构。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | File ID，前缀为 file_ |
type | string | 固定值 "file" |
filename | string | 存储后的文件名 |
size_bytes | integer | 文件大小，单位 byte |
mime_type | string | 上传时提供或根据文件名检测的 MIME type |
downloadable | boolean | 是否可通过 /content 端点下载 |
scope | object | null | 文件关联到其他资源时的 scope，例如 { "id": "sess_...", "type": "session" }；未挂载时为 null |
metadata | object | 上传时传入的自定义元数据对象；省略时为 {}。created_by 为 Forward 保留字段，调用方不可传入 |
identity_id | string | null | Forward 归属身份。归属为某个 Identity 时返回该 Identity ID，否则为 null。详见 Identity 归属 |
icon_url | string | null | Forward 关联的 icon URL |
binding_info | Binding info | 绑定信息（Template 引用计数等） |
created_at | string | 创建时间，RFC 3339 格式 |
updated_at | string | 最后更新时间，RFC 3339 格式 |
Identity 归属
一个账户（或 Workspace）下可以创建多个 Identity，每个 Identity 表示该账户（或 Workspace）接入产品中的一个终端用户。
File 可以归属于账户（或 Workspace），也可以归属于某个 Identity。归属决定了谁能看到、下载和删除该 File。
如何指定归属
| 调用方 | 归属 | 如何指定 |
|---|---|---|
| PAT | 账户 / Workspace | 不传 identity_id（默认，与此前行为一致） |
| PAT | 指定 Identity | 传查询参数 identity_id=<identity_id> |
| SAT（管理员） | Workspace | 自动解析，不能通过参数切换 |
| SAT（绑定 Identity） | 该 Identity | 自动解析，不能通过参数切换 |
identity_id 仅在操作 Identity 归属资源时使用，非必填；PAT 场景可显式传入，未传时为管理员视角；SAT 场景由凭证确定归属，请签发 Identity 维度凭证且不要显式携带该参数（包括传空值），否则返回 HTTP 400。
PAT 指定的 Identity 必须属于当前 PAT 所代表的账户或 Workspace，且处于启用状态。不存在、已禁用、已删除或不属于当前调用方时返回 404。
归属隔离
- 管理员 Scope 下（PAT 未传
identity_id或 Admin SAT）看不到归属于 Identity 的 File。 - 一个 Identity 看不到账户（或 Workspace）本身的 File，也看不到同账户下其他 Identity 的 File。
- 在有效 Identity Scope 下，跨 Scope 查询、下载或删除统一返回
404，不区分“不存在”与“不属于你”。 - 未传
identity_id的 PAT 和 Admin SAT 保持存量行为，Owner mismatch 返回403；下游服务的权限校验拒绝也可能返回403。 - 创建的幂等键按归属隔离；不同 Identity 可以复用相同
Idempotency-Key，不会互相回放。
支持的接口
上传、搜索、列出、查询、下载和删除 File 均支持 Identity Scope。
GET /api/v1/forward/resources/batch 不支持 identity_id，其可见性规则保持不变。支持上传的文件类型
上传接口只接受文本类文件。
| 类别 | 支持的值 |
|---|---|
| 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 |
File 下载响应对象
下载 File 接口返回该结构，包含短期有效的预签名 URL。
| 字段 | 类型 | 说明 |
|---|---|---|
url | string | 预签名下载 URL |
expires_at | string | URL 过期时间，RFC 3339 格式 |
filename | string | 建议的下载文件名（用于浏览器 Content-Disposition） |
Binding info
Forward 在 File 响应中携带的引用聚合。
| 字段 | 类型 | 说明 |
|---|---|---|
agent_template_count | integer | 当前绑定该 File 的 Template 数量 |
列表分页字段
| 字段 | 类型 | 说明 |
|---|---|---|
data | File 对象 数组 | 当前页记录 |
has_more | boolean | 是否还有下一页 |
next_page | string | null | 下一页向后游标（推荐使用）；has_more=true 时等于当前页 last_id，否则为 null |
first_id | string | null | 当前页第一条记录 ID |
last_id | string | null | 当前页最后一条记录 ID |
page / after_id / before_id 互斥，同时提供多个返回 400；推荐使用 page，语义等价于 after_id。