OkFile

要解决什么问题

Agent 在对话里经常需要把本地或生成的文件交给用户：一张图、一段视频、一份 PDF，或整包静态站点。自己搭对象存储、签 URL、处理大文件分片，既重复又容易在 prepare / complete 阶段传错字段。OkFile 把这套流程收成固定 API，让技能侧只关心「上传什么、要什么链接」。

技能如何工作

OkFile 是 agent-first 的上传与发布后端，典型单文件流程是：

1. POST /api/upload/prepare 拿到 uploadUrl 或分片 parts[].uploadUrl
2. 对对应 URL 执行 PUT 上传内容
3. POST /api/upload/complete 用 prepare 返回的 同一 id 收尾
4. 需要时可 GET /api/upload/status/{id} 查状态

完成后优先用 url 作直链；需要预览时用 playUrl（也可通过 GET /i/{id}?play=1）。静态站点走 POST /api/site/prepare → 按普通文件流逐个上传 → POST /api/site/complete，并保留 prepare 里的 siteId / siteToken 直到 complete 成功。

静态站还有几条行为值得记：若所有路径都在同一个顶层目录下，OkFile 会 自动剥掉该顶层目录，内容当作站点根；有根目录 index.html 则直接渲染；没有则根路径展示 目录列表（含文件名、大小、上传时间），图片和视频可在列表内联打开，其它文件走下载链接，嵌套子目录（如 /docs/getting-started.md）会原样保留。不要 为了 listing 自己伪造根 index.html。

分片与鉴权：apiKey 只在 prepare 时发送；complete 只传 id。expiresIn 只描述签名 upload URL 的有效期，不是单独的 Worker 会话 TTL。若 complete 返回 missingParts，只需重传缺失分片。匿名模式受 IP 限流；带 API Key 由后端配额控制。单文件上限 500MB，超过后端阈值会自动走 multipart。

适用边界

适合「上传并返回公开链接 / 预览 / 发布文件夹为子域站点」类任务；不适合把 OkFile 当成通用 CDN 配置工具或离线同步盘。大文件务必按 prepare → PUT → complete 闭环，并遵守上述字段规则，否则容易卡在半截上传。