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。

规则：

• 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。本文只定义 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 手动复验。
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
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 不作为当前规格目标。