RunLab 设计原则
这些原则约束 RunLab 的稳定设计。实现状态、命令名和依赖版本不属于本页。
Run 是核心资产
Run 是一条执行输入、执行事实和执行结果都被明确记录,因而能够被理解和比较的程序执行。RunLab 负责为执行建立身份、管理生命周期并保存资产。Agent Loop 是典型场景,但不定义底层协议。
执行协议与资产管理分离
Run Protocol 只定义 RunInput → RunEngine::run → Result<RunOutput, EngineError>。run_id、接受状态、幂等创建、持久化和恢复由 RunLab 在协议之外负责。执行引擎不因数据库模型而改变语义,存储层也不解释程序结果。
忠实记录执行边界
RunLab 明确保存执行输入、自己直接观察到的执行事实和能够取得的结果。无法观察或无法保真的信息必须标为不可用或失败,不能猜测、补齐或静默近似。
程序内部语义不进入协议
RunLab 不理解 tool call、message、Trace、任务阶段或其他内部步骤。程序把所需信息写入 stdout、stderr 或受控文件系统。RunLab 保存原始结果,但不解释其语义。
只声明受控边界
RunLab 对自己控制的环境和 Program 作出执行与捕获承诺,也完整保存调用方提供的 OCI Runtime Configuration。配置引用的宿主资源和外部服务不由 RunLab 控制。RunLab 记录引用和直接观察到的事实,不把外部世界声明为 Run 的完整状态。
标准对象优先
公开边界优先使用 OCI Image、OCI Runtime Configuration、文件、进程、网络和 digest 等已有概念。RunLab 只在确有语义缺口时增加自己的模型。
标准拥有自己的细节
OCI 已经定义的字段、默认值、options 和冲突处理继续由 OCI 及所使用的 Runtime 解释。Run Protocol 完整接收这些标准对象,但不复制细则,不证明不同写法语义等价,也不为了统一外观而改写它们。
输入最小,组合外置
单次执行的输入是每个 Program 的初始环境、OCI Runtime Configuration 和标准输入,以及执行超时和网络控制。参数扫描、重复采样、调度、评分和跨 Run 编排由上层系统完成。
名称用于发现,digest 用于内容身份
可变名称帮助使用者找到 OCI Image。构造 RunInput 时必须解析为不可变 Descriptor。digest 证明确切字节身份,但不等于内容仍被某个存储保留。
无法忠实执行就返回错误
Run Engine 不静默忽略、改写或降级输入。在任何 Program 启动前发现输入无效或能力不足时返回 EngineError。执行开始后发生的非零退出、超时、取消和捕获问题应尽力成为 RunOutput 中的事实。
初始与最终环境都是完整 OCI 对象
初始环境和可取得的最终环境都是完整 OCI Image。OCI Runtime Configuration 中引用的外部文件系统不进入这两个环境对象。
失败事实也是资产
RunLab 保存非零退出、信号、超时、取消、截断、不可用结果和引擎错误,不用“成功执行”筛选样本。发生中断时,已经持久化的输入与恢复证据也必须保留。
事实与判断分离
RunLab 记录发生了什么,外部系统判断结果意味着什么。原始事实必须先于成功率、分数或排名等派生判断。
单机优先
RunLab 首先建立单机上的可信数据面,不把分布式调度、全局控制面或远端文件透明性纳入核心协议。
设计不由当前实现反向决定
实现可以暂时缺少设计能力,也可以暴露缺陷。差距应被明确记录,不能通过修改协议来美化当前行为。
新能力由真实工作流证明
新增公开词汇、扩展点或抽象前,必须先说明真实使用者、现有对象无法表达的缺口,以及它对执行语义、持久化和恢复的影响。