client 和 session。
上传项目文件
Python 接受相对路径到 bytes 的映射:hello.py,例如内容为 print("hello")。返回的 hash 和 size 验证控制平面保存的输入;它们并不单独证明云工作区已经准备好。下一次 Run 中要求 Agent 读取 src/hello.py、运行它并报告结果,以验证实际执行环境。
路径与上传时机
目录通过显式相对路径列表表达;该 API 不会 clone Git 仓库或解压归档。小项目优先使用允许列表,不要递归上传.env、.git、构建输出和已安装依赖。下面继续使用同一个尚未开始执行的 Session:
.、.. 和 NUL。单次请求中不能重复相同路径。首次执行前再次上传同一路径会更新保存的输入。
当前实现每请求允许 1—100 个文件,base64 字段每文件最多 2 MiB 字符,解码后总量最多 8 MiB。这不是“每个源文件 2 MiB”的承诺;base64 编码会增加长度。路径最多 500 字符。数值依据当前输入实现,后续版本需重新核对。
首个 Run 提交后,或 Sandbox 已经关联后,上传返回 workspace_already_started。后续修改通过 Agent 执行完成;需要一份全新的原始项目时创建新 Session。启用了初始化配置时,SOUL.md 是保留路径,不能通过该接口覆盖。
文件与模型上下文
普通上传让文件存在于工作区。是否读取、如何理解,由任务指令和 Harness 的工具能力决定。不要把整个目录压入文本 prompt,也不要假设上传后模型已经逐字阅读全部内容。 Session 的context.files 可以引用文件路径和预期 SHA-256。提交时控制平面核对文件存在、hash、大小和 UTF-8 内容,防止被引用的上下文在初始化后发生变化。当前被引用文本文件上限为 32768 bytes,拒绝 NUL 与无效 UTF-8;这与普通文件上传上限不同。详情见初始化契约。
如果上下文引用缺失或不匹配,先解决 context_file_missing / context_file_changed,不要反复提交相同的无效配置。
创建 Session 前固定引用文档
先计算实际字节的 hash,将其写入创建请求,再向返回的 Session 上传相同字节。以下片段需要已初始化的客户端、已验证的连接 ID,以及支持初始化的 Harness。它们会创建一个新 Session;上传前先保存其 ID。准备一份简短的 UTF-8brief.md,确认其中内容适合作为参考材料。
brief.md 不会更新 Session 定义。可以在首个 Run 被接受前恢复原字节;如果确实要更换内容,则用新 hash 创建新 Session。此流程不提供原地修改 context 的操作。最多允许八个文件引用;单文件均未超限也不代表合并后的初始化和任务输入未超限。
处理上传与上下文失败
单个上传请求的文件写入一起提交;多个上传请求不构成原子的完整项目上传。文件列表按路径排序,应按路径核对,不能依赖上传顺序。上传空文件会将内容替换为零字节,不会删除路径;该 API 未提供初始输入删除操作。
三种边界情况
分批改变的是请求大小,不会改变下游 Runtime 或 Provider 容量。这里检查的是每请求上限,不能据此承诺 Session 工作区容量无限。多批上传中途失败时,执行前必须根据清单完成对账。
对于固定引用的
brief.md,假设创建时保存 digest A,随后上传内容的 digest 是 B。提交会返回 context_file_changed,不会自动把 B 当作新的参考文档。应在首个 Run 被接受前恢复 A 对应字节,或者创建固定 B 的新 Session。项目文件和参考文档中的指令属于需要审阅的任务数据,不是访问凭据或修改业务权限的授权。
用完整项目验证实际执行
项目任务教程提供完整 fixture 与可运行的 Python、TypeScript 入口。日期实云记录覆盖 Vercel、内置 Pi 1.5.2 与已配置的 Messages 兼容 DeepSeek-V4-Flash 端点:两种客户端均在两轮 Run 中修改项目、执行未改变的固定测试,并在关闭 Session 后保留导出文件。它验证了实际读写执行,不只检查上传回执。 三个检查仍需区分:上传回执描述保存的输入,Runtime 输入验证描述云工作区交付,下载产物描述导出结果。记录没有为每个追问 Run 标记新的workspace.inputs_verified 事件;继续已有工作区本来就不等于重新上传。该记录也不证明全部非法上传的真实拒绝行为、所有 Provider,或本页短片段的新一次执行。
环境与凭据
env / variables 用于普通配置,例如运行模式。Sandbox 代码可以读取这些值。模型、Provider 和 Tool 的受保护凭据应通过相应连接配置,不应为了“方便”复制进项目文件或环境值。