跳转到主要内容
Artifact 是从 Run 工作区导出的文件快照。它归控制平面存储管理,能够在 Session 的云资源关闭后继续下载。 本页接续首个 Session。你需要已授权的 Run ID 和客户端。

要求任务导出文件

在指令中要求 Agent 把交付文件放入其收到的 Run artifact directory。当前工作区路径为 artifacts/<run-id>/,每轮独立。不要仅要求“保存到项目目录”,否则文件可能存在但没有被导出。 worker 在 Harness 退出后导出产物,再完成对应 Run。超出限制会显式失败,不会默默丢弃超限文件。最终回答声称创建了文件不等于导出成功;查询实际 Artifact 列表。

下载与校验

Python:
TypeScript:
每次执行创建独立私有临时目录,并使用生成的文件名排他写入。打印出的目录保留供检查;核对后将文件移入应用存储,使用完毕清理临时副本。示例写出 manifest.json,将生成文件名映射到 Artifact ID、原始名称、Run ID、大小与 hash。只有全部列出产物下载并通过完整性检查后才写清单;此前若执行中断,目录可能留下部分下载,没有清单表示本批未完成。空清单仍不满足要求交付文件的任务。不要直接使用远端名称作为本地路径。 元数据包括 name、size、sha256、Session ID、Run ID 和创建时间。API 以二进制内容提供下载。交付给浏览器时,应用仍需检查业务权限,并选择安全的内容类型和下载文件名。

判断交付是否完整

hash 一致证明下载字节与导出快照一致,不证明代码正确、报告准确或 Agent 实际执行了要求的测试。执行前定义必需产物名称和任务专有检查;即使 Run 为 completed,空列表也不满足这些要求。最终回答、Run 结果和产物验证应分别记录。 worker 对未中断的终态 invocation 尝试导出,包括失败或取消的执行。这些文件可能只是有用的部分结果,不应直接作为已验收交付。Runtime 中断会跳过该导出路径,不能假定未导出的工作区已经成为 Artifact。导出错误也可能使 Harness 本身成功的任务最终失败。决定是否重做前,先检查 Run 错误和时间线。 通过应用交付时,先认证请求者,再通过其业务任务定位 Artifact ID,由后端下载并核对字节,再返回下载响应。使用受控文件名和 Content-Disposition: attachment;不要在应用可信 origin 上直接渲染生成的 HTML。运行生成页面应使用独立的私有预览机制。

限制与保留

当前每个 Run 最多 64 个文件,每文件 4 MiB,总计 8 MiB。导出不接受符号链接或非普通文件。具体校验见产物实现与 Runtime 导出逻辑。 导出内容存储于 PostgreSQL,Session close 不删除这些内容。后续 Run 修改同名工作区文件不会覆盖前一 Run 的快照。这不是无限容量或永久归档保证:数据库备份、存储容量和你部署的保留政策仍需管理。

常见问题与验收

空列表时先看 Run 是否终态、文件是否写在正确目录、Harness 是否实际执行、导出是否失败。不要为了查文件重新提交任务。跨租户的 Artifact ID 不应可读;业务应用也必须验证接收者。 完成验证应包含:列表存在、hash 与长度正确、文件内容符合任务、关闭 Session 后相同 Artifact ID 仍可下载。关闭失败时保留 Session 和资源记录,不能把产物成功当作云清理成功。

两个文件的留存练习

使用专用 Session 提交任务:在提供的本轮产物目录生成 message.txt,内容精确为 Hello from Hexagon 加换行;另生成 status.json,内容精确为 {"ok":true} 加换行。按后端接入保存提交意图与 Run ID。等待 Run 终态;本成功练习要求 completed,其他结果应先检查错误。 使用上文下载循环,并额外核对必需文件名及预期字节。如果任务合理地导出了其他文件,不必要求列表只能包含这两个文件。保存两个 Artifact ID 与 hash,显式关闭 Session 并确认资源清理,再用相同 ID 下载。字节应与关闭前一致;下载成功证明留存,不证明资源删除已经完成。 从仓库根目录运行完整的 Python 程序或 TypeScript 程序。先完成首个 Session 指南中的 SDK 安装,设置已启用的连接 ID。两个程序分别创建独立云 Session,会消耗 Provider 和模型资源:
每个程序要求两个精确文件名与精确字节,核对全部导出文件的大小和 hash,等待 completed,显式关闭 Session,再用每个原 Artifact ID 重新下载比较字节。允许额外产物,但同样检查。下载文件使用生成的本地名称;原始元数据与 ID 保存在私有日志中。本练习使用日志作为下载记录,上文可复用片段则独立写出 manifest.json。 Python 记录在 .local/docs-artifacts-python/,TypeScript 记录在 .local/docs-artifacts-typescript/。成功时日志阶段为 closed_and_retention_checked。十分钟观察超时不会取消任务;出错后保留日志,检查原 Session、Run 和资源操作,按首个 Session 的恢复表继续。程序拒绝覆盖现有日志,不要删除日志重试;确认清理后,先归档目录再开始独立实验。 2026-11-20,两个程序分别通过 Vercel、内置 Pi 1.5.2 与配置的 Messages 端点(deepseek-ai/DeepSeek-V4-Flash)真实云执行。两个文件的执行记录确认了两个文件的精确字节与 hash、Run 完成、Session 关闭、资源删除记录完成以及关闭后下载字节一致。这不证明其他组合、无限留存,也不代表本轮进行了超限云测试。可运行的项目教程提供更完整的实现:带日期的双 SDK 记录核对每轮六个必需导出文件,包括代码与固定测试结果,并在所记载 Vercel/Pi/Messages 组合关闭后检查留存字节一致。

理解导出失败

Runtime 快照与控制平面捕获是两个边界。Runtime 错误可能通过 worker 的 Run 错误呈现,不一定是直接下载产物接口返回的同名公共错误码。参见限制与错误。 依据:捕获与下载存储、字节存储迁移、Runtime 导出。下一步:私有预览、持久化边界、备份恢复。