Codex
12 KiB
PJ2026-010202 Runtime装配
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010202 Runtime装配需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010202 |
| 短名 | Runtime装配 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0102 Agent编排 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 RuntimeAssembly、SecretRef、AipodSpec、gitbundle、session 和工具凭据装配的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
Runtime装配负责把一次 AgentRun 执行需要的镜像、provider profile、session、Git 资源、prompt、skills、tools 和工具凭据统一为受控 RuntimeAssembly，使 runner/backend 启动前的所有运行输入都有可追溯来源和明确边界。
2.2 范围内
BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef四个一等运行时要素。- provider credential、Git resource credential、tool credential 和 short-lived execution context 的 SecretRef/projection/redaction 归属。
- Git-only
ResourceBundleRef.kind="gitbundle"、bundles[]、promptRefs[]、requiredSkills[]、workspace materialization 和实际 commit 摘要。 - AipodSpec YAML、
imageRef、env image reuse、Artificer 默认装配和--aipodrender 入口。 - AipodSpec render 对目标 node/lane 的 backendProfile、provider credential SecretRef、tool credential SecretRef、workspaceRef 和 bundle 绑定。
- SessionRef 到 PVC 直接挂载、
CODEX_HOME、profile runtime home 和 Secret projection 分离。
2.3 范围外
- run、command、event、runner lease 和 terminal status 的 durable authority 归 AgentRun核心。
- Codex app-server stdio、backend adapter 和 provider profile 管理归 后端Profile。
- Queue task、Session API 和 scheduler 归 队列会话。
- YAML-first 平台配置真相、Secret sourceRef 下发和公共 ops primitive 归 YAML运维。
- GitOps、CI/CD、lane 和发布验收归 发布流水，source truth 和 mirror 归 源码同步。
3. 术语表
| 术语 | 定义 |
|---|---|
| RuntimeAssembly | runner/backend 启动前的装配模型，声明一次执行使用的镜像、profile、session、资源包和凭据范围。 |
| BackendImageRef | 描述 env/backend/runner 镜像来源和 digest-pinned image 的运行时要素。 |
| ProfileRef | 描述 backend profile 与 provider credential SecretRef 的运行时要素。 |
| SessionRef | 描述 backend 会话、thread、PVC 和续跑状态的运行时要素。 |
| ResourceBundleRef | 描述 Git-only 资源包、工具、skill、prompt 和实际物化 commit 的运行时要素。 |
| AipodSpec | 声明式 agent 装配 YAML，用于集中描述 imageRef、backendProfile、executionPolicy、resourceBundleRef 和 payloadDefaults。 |
| AipodSpec lane binding | AipodSpec render 时将声明式装配与目标 node/lane 的 YAML SecretRef、workspaceRef、bundle 和 provider profile 绑定的过程。 |
| toolCredentials | 运行时工具授权的 SecretRef 装配项，例如 GitHub PR token、GitHub SSH key 或 UniDesk SSH passthrough token。 |
| transientEnv | 单次 runner job 的短期运行上下文，通过短期 Secret 投影，不作为 run durable fact。 |
4. 系统边界和接口
本规格把 Runtime装配作为 AgentRun 运行输入的装配系统看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | AgentRun核心、队列会话、HWLAB接入、后端Profile、runner job 和平台运维。 |
| 外部输入 | AipodSpec、run executionPolicy、backendProfile、SecretRef、gitbundle repo/ref、promptRefs、requiredSkills、sessionRef、toolCredentials 和 transientEnv。 |
| 受控资源 | RuntimeAssembly、Secret projection intent、git materialization、workspace、runtime home、session PVC、image identity 和 redacted assembly summary。 |
| 外部输出 | backend image digest/source、profile SecretRef 摘要、session/PVC 摘要、actual commit、bundle/skill/tool 摘要、projection intent 和 valuesPrinted=false。 |
| 用户接口 | AgentRun run 创建、Queue dispatch、Session send、AipodSpec render/apply 和 runner job dry-run。 |
| 系统边界 | Runtime装配负责运行输入的受控声明、解析和投影；不执行 backend turn，不决定业务授权，不把 Secret value、host path 或 prompt 内隐式环境变成运行事实。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01020201 | 四要素模型 | 本规格 6.1 | BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef 字段和边界 | AgentRun 核心 run policy | Runner、Backend、HWLAB 接入 |
| PJ2026-01020202 | Secret投影 | 本规格 6.2 | provider/tool/Git credential、projection 和 redaction | YAML运维、平台 Secret 来源 | Runner、Backend、Provider Profile |
| PJ2026-01020203 | GitBundle物化 | 本规格 6.3 | repo/ref、actual commit、bundles、promptRefs、skills、tools | Git mirror、AipodSpec、HWLAB repo | Backend、HarnessRL、Agent 执行 |
| PJ2026-01020204 | Session持久 | 本规格 6.4 | SessionRef、threadId、PVC 直接挂载和 profile 隔离 | AgentRun 核心 session facts | Queue会话、HWLAB接入 |
| PJ2026-01020205 | AipodSpec | 本规格 6.5 | imageRef、backendProfile、executionPolicy、resourceBundleRef 和 payloadDefaults | 发布流水 env image、源码同步 source truth | Queue会话、Session send、Artificer |
6. 原子需求
6.1 AR-RUNTIME-REQ-001 四要素装配模型
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-RUNTIME-REQ-001 | 四要素模型 | PJ2026-01020201 四要素模型 | AgentRun核心、后端Profile |
Runtime装配应将一次执行收敛为 BackendImageRef、ProfileRef、SessionRef 和 ResourceBundleRef 四个一等要素，使 runner/backend 启动前能够明确镜像、profile、session 和资源来源。
executionPolicy、observabilityPolicy、tool credential、initial prompt、skill 注入、network 和 GC 不应成为第五个杂项运行时路径；它们必须归属到四要素或 run policy，并可追溯到 Git、SecretRef、配置引用或显式 null。
6.2 AR-RUNTIME-REQ-002 SecretRef 与敏感输出
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-RUNTIME-REQ-002 | Secret投影 | PJ2026-01020202 Secret投影 | YAML运维、后端Profile、发布流水 |
Runtime装配应通过 SecretRef 和 projection intent 分发 provider credential、Git resource credential、tool credential 和短期 transientEnv，使 Secret value 不进入 Git source、GitOps branch、Postgres、event、trace、日志或 CLI 输出。
输出只能包含 SecretRef 名称、key 名、projection kind、presence、hash/fingerprint、ownerReference 状态和 valuesPrinted=false。provider API key、Codex auth.json、config.toml、DSN、token、SSH private key 和 transientEnv value 都不得以明文形式出现在响应、dry-run、event 或日志中。
RuntimeAssembly 或 AipodSpec render 缺少目标 lane 所需的 provider credential SecretRef、tool credential SecretRef 或 sourceRef 时，应报告为 YAML/AipodSpec binding 缺口。修复路径是补齐 YAML/sourceRef、受控 Secret 同步和重新 render，不允许通过手工创建 legacy Secret、复制其他 lane Secret 或 patch runtime namespace 规避装配缺陷。
6.3 AR-RUNTIME-REQ-003 GitBundle 资源物化
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-RUNTIME-REQ-003 | GitBundle | PJ2026-01020203 GitBundle物化 | HWLAB接入、源码同步、AgentRun源码真相 |
Runtime装配应以 ResourceBundleRef.kind="gitbundle" 物化代码、工具、skill 和 prompt，使 runner 使用的 repo URL、requested ref、actual commit、tree、bundles、promptRefs 和 requiredSkills 都能被查询。
gitbundle 不得引用 host path、Secret volume、用户上传临时目录、inline skill manifest 或旧 inline seed。required skill 缺失必须在 backend 启动前结构化失败，不能通过模型默认 skill、prompt 猜测或运行时补文件绕过。
6.4 AR-RUNTIME-REQ-004 SessionRef 持久化
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-RUNTIME-REQ-004 | Session持久 | PJ2026-01020204 Session持久 | 队列会话、AgentRun核心、后端Profile |
Runtime装配应支持 SessionRef 到 backend thread/cache 的稳定映射，并在启用持久会话时使用 per-session RWO PVC 直接挂载到 ${CODEX_HOME}/<codex_rollout_subdir>。
Session PVC 只保存 Codex rollout 会话文件；provider Secret、完整 CODEX_HOME、Git workspace、auth/config、state sqlite、tmp 和 skills 不进入 PVC。runner replacement 必须复用同一 sessionId、threadId、profile 和 PVC；不得通过新 session、拼接历史 prompt 或伪造 resume 形成续跑表象。
SessionRef 是 Web、CLI、Queue 和 HWLAB接入共享的会话连续性 authority。普通 follow-up、steer 和 result 轮询必须沿用同一 sessionId/threadId/profile/PVC 映射；session 不存在、failed、stale、canceled 或 PVC 不可用时，应返回结构化 blocker。Runtime装配不得自动创建替代 session，也不得把业务 conversationId、workspace project 或浏览器缓存当作 AgentRun session truth。
6.5 AR-RUNTIME-REQ-005 AipodSpec 声明式装配
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-RUNTIME-REQ-005 | AipodSpec | PJ2026-01020205 AipodSpec | 队列会话、发布流水、源码同步 |
Runtime装配应提供 AipodSpec YAML，使 imageRef、backendProfile、executionPolicy、resourceBundleRef、model 和 payloadDefaults 可以从声明式规格进入 Queue submit 或 Session send。
AipodSpec 只声明装配意图，不保存 API key、SSH private key、token、auth.json、config.toml 或其他 Secret 明文。imageRef 必须指向可追溯的 env image Dockerfile source 和完整 commit，最终 runner job 只能使用解析后的 digest-pinned image 或结构化报告 build-required。
当 Queue submit、Session send 或 CLI --aipod render 已指定 node/lane 时，AipodSpec 必须使用该目标 lane 的 YAML 事实绑定 backendProfile、provider credential SecretRef、tool credential SecretRef、workspaceRef 和 resource bundle。除非 YAML 明确声明继承，AipodSpec 不得从其他 lane 或全局默认 lane 隐式继承 provider、tool credential、workspace 或 namespace。