fix: add aipod imageRef work-ready runner reuse

2026-06-11 01:21:56 +08:00
parent 59272f8edb
commit 5a6e5a4bbd
22 changed files with 598 additions and 32 deletions
@@ -52,9 +52,21 @@ CI 的最小检查应覆盖：
 - Bun/TS 单元自测试，包括 manager schema、adapter mock、Codex fake app-server stdio client 和 CLI JSON 输出。
 - `deploy/deploy.json` 与 GitOps render 只读校验。

-容器镜像必须区分 env identity 与 source commit。`agentrun-mgr-env:<envIdentity>` 只包含 Bun runtime、生产依赖、Codex CLI、git/kubectl/node 等系统依赖和 boot 脚本，不 bake `src/`、`scripts/` 或某个业务 source commit。运行时通过 `AGENTRUN_BOOT_COMMIT` 从 git mirror 按完整 SHA 做 `git fetch --depth=1 origin <sha>`，再用 env image 内的 `node_modules` 启动 manager 或 runner。CI/CD 仍然只允许纯 Tekton + Argo CD，不因 Bun 工具链引入自定义 runner、长期 poller 或源分支生成物提交。
+容器镜像必须区分 env identity 与 source commit。`agentrun-mgr-env:<envIdentity>` 只包含 Bun runtime、生产依赖、Codex CLI、git/kubectl/node 等系统依赖和 boot 脚本，不 bake `src/`、`scripts/` 或某个业务 source commit。AipodSpec 通过 `spec.imageRef` 引用 env image Dockerfile source（`repoUrl`、`commitId`、`dockerfilePath`），运行时通过 `AGENTRUN_BOOT_COMMIT` 从 git mirror 按完整 SHA 做 `git fetch --depth=1 origin <sha>`，再用 env image 内的 `node_modules` 启动 manager 或 runner。CI/CD 仍然只允许纯 Tekton + Argo CD，不因 Bun 工具链引入自定义 runner、长期 poller 或源分支生成物提交。

-Env identity 的输入至少包含：Bun base image、系统包列表、`deploy/container/Containerfile`、`deploy/runtime/boot/*.sh`、`package.json`、`bun.lock` 和 `tsconfig.json`。只改业务 TS、文档、模板中不影响 runtime env 的内容时，planner 必须输出 `build=0 reuse=1 unsafeReuse=0`，并只复用上一版 catalog 中同一 `envIdentity` 的 digest。若 GitOps catalog 因 mirror flush lag 暂时不可见，即使 G14 registry 中已有同名 `agentrun-mgr-env:<envIdentity>`，也必须先通过 `agentrun v01 git-mirror sync|flush` 或新的 PipelineRun 恢复 catalog provenance；不能把 registry HEAD 当作第二条发布真相。
+Env identity 的输入至少包含：`imageRef.repoUrl`、`imageRef.commitId`、`imageRef.dockerfilePath`、Bun base image、系统包列表、`deploy/runtime/boot/*.sh`、`package.json`、`bun.lock` 和 `tsconfig.json`。只改业务 TS、文档、模板中不影响 runtime env 的内容时，planner 必须输出 `build=0 reuse=1 unsafeReuse=0`，并只复用上一版 catalog 中同一 `envIdentity` 的 digest。若 GitOps catalog 因 mirror flush lag 暂时不可见，即使 G14 registry 中已有同名 `agentrun-mgr-env:<envIdentity>`，也必须先通过 `agentrun v01 git-mirror sync|flush` 或新的 PipelineRun 恢复 catalog provenance；不能把 registry HEAD 当作第二条发布真相。
+
+## Aipod env image reuse
+
+`AipodSpec.spec.imageRef` 是 Aipod 启动时选择 work-ready env image 的 source truth。Queue dispatch、Session turn 和 runner Job 创建不得直接信任 prompt、payload 或 CLI 临时传入的可变 image tag；它们必须先把 `imageRef` 映射到 artifact catalog 中的 env image identity 和 digest-pinned repository digest。
+
+规则：
+
+- `imageRef.kind` 固定为 `env-image-dockerfile`，最小字段为 `repoUrl`、完整 `commitId` 和仓库内相对 `dockerfilePath`。
+- `repoUrl + commitId + dockerfilePath` 指向的 Dockerfile source 必须能通过 Git mirror 或受控 Git credential 读取；不能依赖 runner 任务内手工 clone 和 build。
+- 启动 Aipod 时若 catalog 中存在匹配 env identity 且 digest 合法，必须复用该 digest-pinned image，并在 response/event 中标记 `status=reused`。
+- catalog 未命中时，CLI/API 只能返回明确 `build-required` 计划或触发受控 Tekton PipelineRun；不得让 runner task 进入后再运行 `apt`、`apk`、`bun install`、`npm install` 补环境。
+- catalog 记录必须包含 `imageRef` source 摘要、`envIdentity`、env image tag、digest、repository digest、build/reuse 状态和 provenance。SecretRef、token、SSH key 和 provider config 不进入 catalog。

 ## 真相源

@@ -132,7 +144,7 @@ Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired st

 - `v0.1` env image tag 使用 `envIdentity`，而不是 source commitId。source commitId 通过 `AGENTRUN_BOOT_COMMIT` 和 catalog `bootCommit` 进入 runtime。
 - Runtime manifest 必须使用 digest pin 作为部署身份；G14 本地 registry 对同一 tag 的默认 HEAD 可能返回 Docker schema1 compatibility digest，Tekton 必须用 `Accept: application/vnd.docker.distribution.manifest.v2+json` 采集 containerd 可直接拉取的 schema2 manifest digest，并在写入 catalog 前按 digest HEAD 验证。
- Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、env image tag、digest、env identity、boot commit、toolchain inputs 和 build/reuse 状态。
+- Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、imageRef source 摘要、env image tag、digest、env identity、boot commit、toolchain inputs 和 build/reuse 状态。
 - 同一 env identity 对同一 service 应生成同一镜像；lane 差异放在 manifest、env、SecretRef、namespace、RBAC 和 runtime config 中，不 bake 进镜像。普通 source commit 差异由 boot checkout 选择。
 - `deploy/deploy.json` 只承载人写 runtime intent，不承载 digest、publish state 或 reuse evidence。
 - Source branch 不得因为 promotion 出现自动提交；若发布后 source branch 变化，必须是人工修改源码、测试、文档、模板或 `deploy/deploy.json`。