pikasTech-agentrun/docs/reference/spec-v01-cicd.md

# v0.1 CI/CD 与版本 Lane 规格

本文是 AgentRun `v0.1` 独立 CI/CD、GitOps、namespace、registry 和发布验收规格。AgentRun 从 `v0.1` 开始废弃 `dev/prod` 管理口径，改为按 `v0.1`、`v0.2`、`v0.3` 版本 lane 滚动。

## 设计目标

- `v0.1` 是独立 lane，不复用 `agentrun_dev` 或 `agentrun_prod` 作为当前运行面。
- 每条版本 lane 拥有独立 source branch、source worktree、GitOps branch、runtime namespace、artifact catalog、runtime path、CI pipeline 和发布验收。
- `v0.1` 只能部署到 `agentrun-v01` namespace；`v0.2`、`v0.3` 后续使用自己的 namespace 和 GitOps 路径。
- CI/CD 必须使用 G14 原生 k3s、纯 Tekton Pipeline/Task/PipelineRun 和 Argo CD；不得引入自定义 runner、CI.json runner、长期自研 poller/reconciler、D601 legacy、临时 clone、手工 Pod patch 或本地镜像作为发布真相。
- `v0.1` 的 CD 唯一手写真相源是 source branch 内的 `deploy/deploy.json`；Tekton 生成的 artifact catalog 和 Argo desired state 必须与 source branch 分离，只写入 `v0.1-gitops`。
- Source checkout 与 GitOps promotion 必须优先走 `devops-infra` git mirror/relay；Pipeline 不直接依赖 GitHub SSH fetch/push。
- Runtime image 采用 env reuse：依赖、Bun/Node、系统包、lockfile、Containerfile 和 boot 脚本构成 env identity；普通 TS/文档/CLI 业务源码变更只改变 boot commit，不重建 env image。
- 发布证据以 live runtime、Argo desired state、GitOps branch、Tekton 证据和干净 source worktree 顺序判断。

## 固定命名

| 对象 | v0.1 规格 |
| --- | --- |
| Source repo | `git@github.com:pikasTech/agentrun.git` |
| Source branch | `v0.1` |
| Source worktree | `G14:/root/agentrun-v01` |
| Worktree root | `G14:/root/agentrun-v01/.worktree/{task}` |
| Runtime namespace | `agentrun-v01` |
| GitOps branch | `v0.1-gitops` |
| Git mirror read URL | `http://git-mirror-http.devops-infra.svc.cluster.local/pikasTech/agentrun.git` |
| Git mirror write URL | `http://git-mirror-write.devops-infra.svc.cluster.local/pikasTech/agentrun.git` |
| Git mirror cache | `devops-infra:/cache/pikasTech/agentrun.git` |
| Artifact catalog | `v0.1-gitops:deploy/artifact-catalog.v01.json` |
| Runtime path | `v0.1-gitops:deploy/gitops/g14/runtime-v01` |
| Tekton namespace | `agentrun-ci` |
| Tekton Pipeline | `agentrun-v01-ci-image-publish` |
| Tekton ServiceAccount | `agentrun-v01-tekton-runner` |
| PipelineRun prefix | `agentrun-v01-ci-<short12>` |
| Env image repository | `127.0.0.1:5000/agentrun/agentrun-mgr-env:<envIdentity>` |
| Boot script | `deploy/runtime/boot/agentrun-boot.sh` |
| Argo CD AppProject | `argocd/agentrun-v01` |
| Argo CD Application | `argocd/agentrun-g14-v01` |

公网入口暂不作为 `v0.1` 必备规格。若后续需要 UniDesk/HWLAB 跨服务入口，必须在本仓库新增受审查的 ingress/FRP/edge spec，不得临时固化 NodePort、host port、pod IP 或一次性 port-forward。

## Bun + TypeScript CI 边界

`v0.1` 自研代码的 CI/CD 工具链以 Bun + TypeScript 为准。Tekton task 必须在受控容器内安装或使用固定 Bun 运行时，执行依赖安装、类型检查、自测试和镜像构建；不得把 master server、G14 固定 source worktree 或手工 host shell 作为构建机。

G14 依赖拉取和镜像发布沿用 HWLAB 成熟 lane 的运行面假设：`PipelineRun.spec.taskRunTemplate.podTemplate.hostNetwork=true` 且 `dnsPolicy=ClusterFirstWithHostNet`。因此 Tekton task 内的 `127.0.0.1:10808` 指向 G14 host bootstrap proxy，`127.0.0.1:5000` 指向 G14 host-managed registry；`NO_PROXY` 必须保留 `hyueapi.com`、`.hyueapi.com`、cluster service CIDR、`.svc` 和 `.cluster.local`。如果未来改成 cluster Service proxy 或 registry DNS，必须同步更新 Tekton template、render 脚本和本文规格，不得只改某个 PipelineRun 实例。

CI 的最小检查应覆盖：

- `bun install` 或等价 frozen lockfile 安装。
- TypeScript 类型检查。
- 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。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 的输入至少包含：`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。

该规则是 `#146`/`#156` 的长期决策：Aipod 启动应复用 work-ready env image，基础工具、Bun/Node/npm、AgentRun 生产依赖和必要系统包在 env image 或受控预装层准备；普通任务运行时不能默认执行 `apt`、`apk`、`bun install`、`npm install` 来补齐基础环境。

规则：

- `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。

## 真相源

`v0.1` 发布真相按以下顺序判断：

1. Live runtime：`agentrun-v01` namespace 中 Deployment/Job/Pod ready、事件、日志和 service health。
2. Argo desired state：`argocd/agentrun-g14-v01` 的 revision、sync、health、source branch 和 runtime path。
3. GitOps branch：`v0.1-gitops` 中的 `deploy/artifact-catalog.v01.json` 与 `deploy/gitops/g14/runtime-v01/**`。
4. Tekton 执行证据：PipelineRun、TaskRun result、env identity、build/reuse summary、image digest 和 promotion 终态。
5. 干净 source worktree：`G14:/root/agentrun-v01`、`origin/v0.1`、render 脚本、deploy intent 和 `--no-write` 输出。

`devops-infra` git mirror 是 CI/CD source 与 GitOps relay，不是新的 source truth。source truth 仍是 GitHub `v0.1`，GitOps truth 仍是 `v0.1-gitops`；mirror 只负责降低 Pipeline 中的外网 fetch/push 抖动，并让 exact commit fetch 可在集群内稳定命中。受控入口是 UniDesk CLI：`agentrun v01 git-mirror status|sync|flush`。`status` 必须展示 `localV01`、`githubV01`、`localGitops`、`githubGitops`、`pendingFlush` 和 exact full-SHA fetch 结果；`trigger-current` 在创建 PipelineRun 前必须先检查 `localV01`，必要时同步 mirror，再继续。

旧 `master` 记忆、`/root/agentrun` 历史固定目录、`agentrun_dev`、`agentrun_prod`、D601 legacy 路径、临时 worktree 或本地容器只能作为线索，不能作为 `v0.1` 发布通过证据。

## Source 与 GitOps 分层

`v0.1` source branch 可以包含：

- 源码、测试、长期参考文档、人写配置和模板。
- `deploy/deploy.json`，这是 `v0.1` CD 唯一手写真相源。
- Kubernetes 模板、render 脚本、CI/CD helper 和 catalog schema。

`v0.1` source branch 不得跟踪：

- `deploy/artifact-catalog.v01.json`。
- `deploy/gitops/g14/runtime-v01/**`。
- Argo 实际消费的 rendered runtime desired state。
- image digest、publish state、reuse evidence 或 CI 生成 rollout metadata。

`v0.1-gitops` branch 必须包含：

- `deploy/artifact-catalog.v01.json`，记录 env image tag、digest、source commit、env identity、service identity、build/reuse 状态和 provenance。
- `deploy/gitops/g14/runtime-v01/**`，作为 Argo CD 消费的 desired state。
- 必要 generated metadata，但不得包含 Secret 值。

首次初始化时，如果 `v0.1-gitops:deploy/artifact-catalog.v01.json` 尚不存在，只允许由 `v0.1` lane 的正式初始化步骤创建第一版 catalog。不得 fallback 到 `master`、`agentrun_dev`、`agentrun_prod` 或 source branch 生成物。

## CD 唯一手写真相源

`deploy/deploy.json` 是 `v0.1` CD 的唯一手写真相源。它只承载人写 runtime intent，不承载任何 CI 构造物。

允许写入 `deploy/deploy.json` 的内容：

- service id、组件类型和是否参与 `v0.1` runtime。
- replica、resource request/limit、health path、ports、env key、ConfigMap/SecretRef 名称和 key。
- runtime namespace、ServiceAccount、RBAC intent、PVC intent、NetworkPolicy intent。
- Postgres 和 Code Agent provider 的 SecretRef 名称、key 名称与 mount/env intent；Secret 值不在 source 或 GitOps 中出现。
- public/ingress intent 的声明占位；`v0.1` 默认不要求公网入口。

禁止写入 `deploy/deploy.json` 的内容：

- image tag、image digest、publish status、reuse evidence、PipelineRun id、TaskRun id。
- GitOps branch revision、Argo sync revision、runtime generated manifest。
- Secret 值、token、kubeconfig、SSH key 或任何 credential value。

Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired state，但不得回写 source branch 或修改 `deploy/deploy.json`。所有自动构造物只允许写入 `v0.1-gitops` 的 `deploy/artifact-catalog.v01.json` 和 `deploy/gitops/g14/runtime-v01/**`。

## CI/CD 链路

标准链路如下：

1. 人工或受控 GitHub/UniDesk 入口为某个 `origin/v0.1` source commit 创建 Tekton `PipelineRun`；触发器可以是 Tekton Triggers 或手动 `PipelineRun`，但不能是长期自定义 runner。
2. `prepare-source` 通过 git mirror read URL 按完整 SHA checkout `v0.1` source，不使用 branch tip 近似 checkout。
3. 原语校验 task 只覆盖当前发布链路必需的 source checkout、`bun run check` 和 GitOps render check；不再把仓库级 self-test 当作 `v0.1` 发布门禁，旧 `dev/prod` gate 也不进入 lane。
4. Plan task 通过 git mirror read URL 读取上一版 `v0.1-gitops:deploy/artifact-catalog.v01.json`，计算 `envIdentity` 并判断 affected/reused services；planner 只能输出 TaskRun result 或临时 workspace 文件，不回写 source。
5. Affected env image 通过 Tekton Task 内的 BuildKit 发布到 G14 本地 registry；reused service 直接复用 catalog digest。不得使用 Docker daemon、DIND 或仓库外自定义 runner。
6. Promotion task 用 publish/reuse results 刷新 `deploy/artifact-catalog.v01.json`，并用 `deploy/deploy.json` render `deploy/gitops/g14/runtime-v01/**`，只通过 git mirror write URL 推送到本地 `v0.1-gitops` relay。发布收口再用 `agentrun v01 git-mirror flush --confirm` 把 GitOps branch 快进回 GitHub。
7. Argo CD Application `agentrun-g14-v01` 从 `v0.1-gitops:deploy/gitops/g14/runtime-v01` 同步到 `agentrun-v01`。
8. 验收只观察 `agentrun-v01` runtime、Argo revision/sync/health 和对应 service health。

## Artifact 与镜像身份

镜像身份同时是 RuntimeAssembly 的 `BackendImageRef` 来源；四要素总模型见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。本文只定义 image digest、artifact catalog 和 GitOps promotion 边界，不定义 profile、session 或 resource bundle 字段。

- `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、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`。

## Kubernetes 与 Argo 边界

- `agentrun-v01` namespace 只能由 `v0.1` GitOps lane 管理。
- `argocd/agentrun-v01` AppProject destination 只能包含 `agentrun-v01`。
- `argocd/agentrun-g14-v01` source 必须指向 `v0.1-gitops:deploy/gitops/g14/runtime-v01`，destination 必须是 `agentrun-v01`。
- `v0.1` Secret、ServiceAccount、RBAC、PVC、ConfigMap 和 runtime config 必须独立命名或 namespace scope；文档、issue、trace 和 report 只记录 SecretRef 名称与 key，不记录值。
- `agentrun-mgr` 和 runner Job 只能通过 `spec-v01-secret-distribution.md` 定义的 SecretRef 注入 Postgres DSN 和 Codex stdio profile auth/config 文件；`codex` 默认 SecretRef 为 `agentrun-v01-provider-codex`，`deepseek` 默认 SecretRef 为 `agentrun-v01-provider-deepseek`，`minimax-m3` 默认 SecretRef 为 `agentrun-v01-provider-minimax-m3`。测试凭据来自 profile 专属 `auth.json` 与 `config.toml` 的 Kubernetes Secret projection，不得从 `deploy/deploy.json`、artifact catalog 或 generated manifest 中读取明文。
- Postgres `DATABASE_URL` Secret 必须使用实际创建的数据库名，v0.1 默认为 `agentrun_v01`；密码或其他 URL credential 必须 URL encode 后写入 DSN。Secret 值不进入 source/GitOps，runtime bootstrap 或 secret-management 流程负责创建与轮换。
- Codex provider Secret 在 GitOps manifest 中只能表现为 SecretRef 和只读 volume projection；runner Job manifest 还必须包含 writable runtime home，用于把 Secret projection 复制到 `CODEX_HOME` 后运行 Codex。
- `agentrun_dev` 和 `agentrun_prod` 不得作为 `v0.1` namespace、Argo destination、Pipeline target 或验收目标。

## 手动和热修边界

- 只读诊断可以通过 UniDesk route `G14:k3s` 查询 `agentrun-v01`。
- 写操作必须走 Tekton PipelineRun、GitOps promotion、Argo CD 或仓库内受控 CLI；不得长期使用手工 `kubectl apply/patch/delete` 维持运行态。
- 任何需要临时 live hotfix 的情况，必须先记录 issue/PR，说明原因、影响范围、回滚方式和后续固化路径。
- 不得在 master server 构建镜像、运行重型测试或把本地 Docker image 当作发布真相。

## 验收标准

- `G14:/root/agentrun-v01` source worktree 为 `v0.1...origin/v0.1` 且 clean；`/root/agentrun-v01/.worktree/` 是受控并行 worktree 根，必须被 `.gitignore` 忽略，不得污染固定 source worktree 状态。
- `AGENTS.md` 和 `docs/reference/` 不得把 `agentrun_dev` 或 `agentrun_prod` 写成 `v0.1` 当前 namespace、Argo destination、Pipeline target 或验收目标；只允许在废弃说明和历史背景中提及。
- `agentrun-v01` namespace 存在，且 `agentrun_dev`/`agentrun_prod` 不参与 `v0.1` 发布判定。
- `v0.1-gitops` branch 和 `deploy/gitops/g14/runtime-v01` 成为 Argo desired state 来源。
- `deploy/deploy.json` 是 CD 唯一手写真相源；source branch 不跟踪 artifact catalog、runtime generated manifests、digest 或 publish state。
- Tekton/Argo 路径不包含自定义 runner、CI.json runner、长期自研 poller 或 control-plane reconciler。
- Runtime manifest 使用 digest pin，catalog 记录完整 source commit、env identity、build/reuse summary 与 digest。
- `agentrun v01 git-mirror status` 中 `sourceInSync=true`、`exactFetch.localV01=true`，并能用 mirror 对当前 full SHA 执行 shallow fetch。
- 小的业务源码变更完成后，PipelineRun `planArtifacts.summary` 应为 `build=0 reuse=1 unsafeReuse=0`，`image-publish` task result `status=reused`，且不出现新的 env image build。
- 发布完成后可通过 `G14:k3s` 读取 `agentrun-v01` Pod ready、service health 和对应 image digest。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| `v0.1` source branch | 已建立 | `origin/v0.1` 存在。 |
| `G14:/root/agentrun-v01` source worktree | 已建立/待保持 clean | 固定 source worktree 使用 `v0.1` 分支；`.worktree/` 必须忽略，确保并行 worktree 不让固定 source worktree 变 dirty。 |
| `agentrun-v01` namespace | 已实现/已通过主闭环 | GitOps lane 已同步 manager、Postgres、ServiceAccount、SecretRef 和 runner Job 所需对象；发布前仍按 [spec-v01-validation.md](spec-v01-validation.md) 手动复验。 |
| `v0.1-gitops` branch | 已实现 | Tekton promotion 生成 artifact catalog 与 runtime desired state，Argo 从 `deploy/gitops/g14/runtime-v01` 同步。 |
| 纯 Tekton/Argo lane | 已实现/已通过主闭环 | `agentrun-ci` Pipeline、BuildKit 镜像发布、GitOps promotion 和 Argo Application 已形成闭环；不得回退到自定义 runner 或 dev/prod。 |
| git mirror/relay | 已实现 | UniDesk `agentrun v01 git-mirror status|sync|flush` 管理 `devops-infra:/cache/pikasTech/agentrun.git`；Pipeline read/write 默认使用 mirror URL，`trigger-current` 会在创建 PipelineRun 前 pre-sync `v0.1`。 |
| env reuse | 已实现/待持续验收 | Pipeline 计算 `envIdentity`，命中上一版 catalog 时输出 `build=0 reuse=1 unsafeReuse=0` 并复用 env image digest；首次 env identity 或依赖/Containerfile/boot 变化才构建 `agentrun-mgr-env:<envIdentity>`。 |
| `dev/prod` 废弃口径 | 已定义 | 本文明确 `agentrun_dev` 和 `agentrun_prod` 不作为当前规格目标。 |