pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-01060308-cicd-yaml-first-target-governance.md

PJ2026-01060308 CI/CD YAML目标治理

修改历史

版本	对应 commit id	更新日期	变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-01060308 CI/CD YAML目标治理需求规格

1. 文档控制

字段	内容
编号	PJ2026-01060308
短名	YAML目标治理
层级	L3 子课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-010603 YAML运维
关联规格	PJ2026-010601 发布流水、PJ2026-010602 源码同步、PJ2026-01060307 控制面模块化、PJ2026-010604 公开入口、PJ2026-010605 运维监控
实现引用版本	draft-2026-06-25-cicd-yaml-targets; draft-2026-07-01-cicd-source-snapshot
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 CI/CD、YAML-first 和平台运维控制面中 target、lane、Secret、public exposure、PipelineRun/Argo/git-mirror 与公共 ops primitive 的稳定治理口径。

2. 目的和范围

2.1 目的

YAML目标治理负责把 CI、deploy、artifact-registry、HWLAB node/lane、AgentRun、platform-infra、Secret 分发和 public exposure 中的运行目标事实收敛到 owning YAML 或显式参数，使新增 node/lane/target 时不需要发布 TypeScript 代码来改变默认目标、namespace、route、registry endpoint 或 SecretRef。

本规格建立在控制面模块化完成后的领域目录边界上。代码可以保留 legacy adapter、测试夹具、错误消息和帮助示例中的历史目标名，但主路径不得继续通过隐藏默认值把 G14、D601、v02、v03、namespace、route、registry endpoint 或工作目录写死在解析逻辑中。

2.2 范围内

• config/hwlab-node-lanes.yaml、config/agentrun.yaml、config/platform-infra/*.yaml、config/secrets-distribution.yaml、config/cicd/targets.yaml 和 config/artifact-registry.yaml 的 target/lane/configRef/sourceRef 职责。
• scripts/src/ops/ 中的 configRef、target resolver、Secret redaction、public exposure、K8s/CI-CD 和 bounded output 公共原语。
• ci、deploy、artifact-registry、hwlab g14、hwlab nodes、agentrun、platform-infra observability 和 secrets CLI 对目标来源、配置引用图和脱敏状态的解释输出。
• hardcode inventory 的分类：remove-code-default、keep-domain-special、legacy-adapter、test-fixture 和 help-example。

2.3 范围外

• 不把所有配置合并成单一超级 YAML。
• 不删除必要的 legacy 安全阻断；legacy 入口必须隔离并在输出中标注。
• 不把运行面 Secret、pod env、日志或数据库状态反向写成本地配置真相。
• 不绕过 UniDesk 受控 CLI 使用原生 kubectl、argo、tkn、curl 或临时 shell 作为正式控制入口。
• 不为业务策略数值新增合同测试、硬编码范围或 schema 数值限制。

3. 术语表

术语	定义
target	YAML 中描述部署目标、运行节点、route、kubeRoute、namespace、workspace、registry、public URL 或 CI/CD 参数的对象。
lane	YAML 中描述一条 runtime 或 control-plane 运行线的对象，通常包含 node、source truth、runtime namespace、gitops、CI、Secret 和 publicExposure。
configRef	path/to/file.yaml#object.path 形式的跨 YAML 引用，解析器只校验引用存在性、类型和摘要，不把合并结果写成第二真相。
sourceRef	Secret 来源声明。输出只能显示来源标识、key 名、presence、fingerprint、字节数和 valuesPrinted=false。
source snapshot	CI/CD 触发时由 k8s 托管 git-mirror 解析出的不可变源码快照，至少包含 repository、branch、selectedCommit、stageRef、mirrorCommit、objectPresent、resolver job 和 YAML 来源。
host workspace	operator host 或目标节点上的固定源码 checkout。正式 CI/CD 只能把它作为开发便利或显式 legacy/debug adapter，不得作为发布 source truth。
hidden default	代码在未显式参数或未读取 YAML 时自动选择固定目标、namespace、route、registry、lane 或工作目录。
legacy adapter	为历史入口保留的隔离兼容路径。它可以拒绝 mutation 或提示替代命令，但不得污染主 runtime lane 解析。
ops primitive	跨领域复用的配置引用、目标解析、Secret redaction、K8s apply/status、public exposure 和 bounded output helper。

4. 系统边界和接口

边界项	内容
外部使用者	平台维护者、发布操作人员、AgentRun/HWLAB lane 运维者、自动化任务和后续代码维护者。
外部输入	CLI 参数、YAML 配置、configRef/sourceRef、node/lane/target、desired-state manifest、Git commit 和运行面只读状态。
受控资源	target resolver、配置引用图、CI/CD manifest 渲染、Secret 同步摘要、public exposure 渲染、PipelineRun/Argo/git-mirror 状态和 CLI 输出。
外部输出	有界 plan/status/dry-run、配置来源路径、resolved target、redacted Secret evidence、drill-down 命令和 legacy adapter 提示。
用户接口	bun scripts/cli.ts ci ...、artifact-registry ...、deploy ...、hwlab ...、agentrun ...、platform-infra observability ... 和 secrets ...。
系统边界	本规格定义配置如何成为运行目标真相；不定义业务能力语义、不替代发布/源码/公开入口/监控规格，也不让运行面状态成为配置来源。

5. 内部分工与架构

5.1 配置引用图

flowchart LR
  CICD[config/cicd/targets.yaml] --> OpsTarget[ops/targets.ts]
  Artifact[config/artifact-registry.yaml] --> OpsTarget
  Hwlab[config/hwlab-node-lanes.yaml] --> OpsTarget
  AgentRun[config/agentrun.yaml] --> OpsTarget
  Observability[config/platform-infra/observability.yaml] --> ConfigRef[ops/config-refs.ts]
  Secrets[config/secrets-distribution.yaml] --> OpsSecret[ops/secrets.ts]
  ConfigRef --> Hwlab
  ConfigRef --> AgentRun
  OpsTarget --> DomainCLI[domain CLI plan/status/dry-run]
  OpsSecret --> DomainCLI
  DomainCLI --> Runtime[controlled runtime or bounded output]

5.2 target/lane 解析数据流

flowchart TD
  Args[explicit --target/--node/--lane] --> Select[selection]
  Defaults[YAML defaults] --> Select
  Select --> Resolver[ops target resolver]
  Resolver --> Validate[shape and reference validation]
  Validate --> Plan[resolved target summary]
  Plan --> Domain[CI/deploy/artifact/HWLAB/AgentRun/platform-infra]
  Domain --> Output[bounded summary + drill-down]

命令行或 issue 已明确 node/lane/target 时，resolver 只校验和解释该目标，不得用全局 default 覆盖。未显式传入目标时，resolver 可以读取 domain YAML default，并在输出中说明默认来源路径。

5.3 Secret sourceRef 同步链路

sequenceDiagram
  participant YAML as owning YAML
  participant CLI as controlled CLI
  participant Source as local sourceRef
  participant Runtime as runtime Secret
  YAML->>CLI: sourceRef + sourceKey + targetKey
  CLI->>Source: inspect presence and fingerprint
  Source-->>CLI: presence/fingerprint only
  CLI-->>CLI: valuesPrinted=false
  CLI->>Runtime: sync only when --confirm
  Runtime-->>CLI: object/key presence
  CLI-->>YAML: no reverse write-back

缺少 sourceRef、targetKey、providerCredential 或 tool credential 时，CLI 必须暴露 YAML/AipodSpec binding 缺口，不得通过复制其他 lane Secret、手工创建 legacy Secret 或 patch runtime namespace 规避。

5.4 publicExposure/Caddy/FRPC 链路

flowchart LR
  PublicYaml[publicExposure YAML] --> PublicHelper[ops/public-exposure.ts]
  PublicHelper --> Frpc[FRPC Secret/render]
  PublicHelper --> Caddy[PK01 Caddy managed block]
  PublicHelper --> Probe[HTTPS public health probe]
  Probe --> Summary[public URL + diagnostic endpoint summary]

正式用户入口来自 YAML 中的 public URL 和 publicExposure；FRP remote port、Caddy backend、本地 service DNS、direct port 或历史 nip.io 域名只能作为实现细节、诊断入口或 legacy 对照。

5.5 CI PipelineRun/Argo/git-mirror 状态链路

sequenceDiagram
  participant CLI
  participant Target as YAML target
  participant Mirror as git-mirror
  participant Tekton
  participant Argo
  participant Runtime
  CLI->>Target: resolve CI/CD target
  CLI->>Mirror: read source authority
  Mirror-->>CLI: refs and source summary
  CLI->>Tekton: PipelineRun status or read-only plan
  Tekton-->>CLI: PipelineRun/TaskRun bounded summary
  CLI->>Argo: Application sync/health status
  Argo-->>Runtime: desired runtime state
  Runtime-->>CLI: readiness/public probe summary

状态输出必须区分 PR merge commit、current source head、PipelineRun、Argo revision、git-mirror pendingFlush 和 runtime readiness；不得只用一个当前 head 推断所有阶段完成。

5.6 k8s source snapshot 链路

sequenceDiagram
  participant CLI
  participant Target as YAML target
  participant Resolver as k8s git-mirror resolver
  participant Mirror as git-mirror cache
  participant Tekton
  CLI->>Target: resolve node/lane/sourceAuthority
  CLI->>Resolver: read selected commit and calculate plan
  Resolver->>Mirror: read selected commit and object presence
  Mirror-->>Resolver: selectedCommit + objectPresent
  Resolver-->>CLI: env reuse + build scope
  CLI->>PaC: manual webhook after plan review
  Resolver->>Mirror: create immutable stageRef
  PaC->>Tekton: create PipelineRun with sourceSnapshot
  Tekton->>Mirror: fetch/checkout immutable stageRef or snapshot artifact

正式 CI/CD 的源码身份以 source snapshot 为准。只读 plan 不得同步 mirror、创建 snapshot 或修改运行面；手动 trigger 在完成当前 plan 审阅后才可创建本轮不可变 snapshot。trigger-current、image publish、GitOps render 和 closeout 不得再从 operator host 的 dirty/stale worktree、当前 branch tip 或 GitHub direct fetch 推导本轮 source identity。upstream fetch 只允许发生在受控 k8s git-mirror resolver/sync 组件内；PipelineRun 只消费 node-local mirror 的不可变 stageRef、PVC 或 bundle artifact。

6. 原子需求

6.1 OPS-TARGET-REQ-001 YAML target 真相

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-001	目标真相	PJ2026-01060308 YAML目标治理	YAML运维

CI/CD、deploy、artifact-registry、HWLAB node/lane、AgentRun 和 platform-infra 的 target、lane、namespace、route、workspace、registry endpoint、public URL、SecretRef、gitops path 和 CI/CD 参数必须来自 owning YAML 或显式参数。

代码不得在主路径中新增隐藏默认 G14、D601、v02、v03、namespace、route、registry endpoint 或工作目录。缺少配置时应报出 YAML 路径、字段名和下一步配置入口。

6.2 OPS-TARGET-REQ-002 configRef 解析

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-002	配置引用	PJ2026-01060308 YAML目标治理	公共原语

跨 YAML 目标事实必须通过 path/to/file.yaml#object.path configRef 表达。configRef parser 只负责读取、校验存在性、生成摘要 hash、展示引用链和暴露缺失字段；不得把解析后的大对象写回另一个 YAML 成为第二真相。

platform-infra observability 的 serviceConnection 不得复制 HWLAB/AgentRun 的 node/lane/namespace 事实，必须通过 configRef 指向对应 lane 配置，并在 plan/status --full 中展示解析链。

6.3 OPS-TARGET-REQ-003 公共 resolver 和 domain 注入默认

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-003	resolver	PJ2026-01060308 YAML目标治理	控制面模块化

公共 option parser 不允许内置 domain target 默认。公共 parser 可以返回 targetId: null，由调用 domain 把 YAML default 注入并输出 default 来源路径。ciTarget()、deploy provider resolver、artifact-registry options 和 platform-infra common options 都必须遵循该规则。

6.4 OPS-TARGET-REQ-004 Secret 与 credential 脱敏一致性

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-004	Secret脱敏	PJ2026-01060308 YAML目标治理	用户管理、Agent编排

Secret plan/status 只允许输出对象名、key 名、sourceRef、targetKey、presence、fingerprint、字节数、缺失项和 valuesPrinted=false。AgentRun provider credential、tool credential、HWLAB bootstrap Secret、platform-infra Secret 和通用 secrets 命令必须使用同一类 redacted sourceRef/fingerprint 语义。

6.5 OPS-TARGET-REQ-005 legacy adapter 隔离

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-005	legacy隔离	PJ2026-01060308 YAML目标治理	发布流水

D601 maintenance deploy、G14 DEV/PROD retirement、v02-only runtime migration、Code Queue compat path 等历史入口可以保留为 legacy adapter，但必须在代码和输出中标注原因、替代命令和是否允许 mutation。legacy adapter 不得成为主 runtime lane 的 fallback，也不得补齐缺失 YAML/Secret。

6.6 OPS-TARGET-REQ-006 hardcode inventory 与验收

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-006	inventory	PJ2026-01060308 YAML目标治理	平台运维

每轮治理必须维护 hardcode inventory，并把命中分类为 remove-code-default、keep-domain-special、legacy-adapter、test-fixture 或 help-example。代码中保留的目标名必须属于后四类之一；remove-code-default 必须迁移到 YAML 或公共 helper。

验收至少覆盖 ci plan/status --target <id>、artifact-registry plan/status --target <id>、deploy apply --dry-run 目标来源说明、hwlab nodes control-plane status --node <node> --lane <lane> 的 YAML-declared lane、platform-infra observability plan/status --full 的 configRef 解析链和 secrets status --config ... --full 的脱敏输出。

6.7 OPS-TARGET-REQ-007 source snapshot 与 host worktree 禁用

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-007	源码快照	PJ2026-01060308 YAML目标治理	源码同步、发布流水

CI/CD source authority 必须由 owning YAML 声明。主路径应支持 sourceAuthority.mode=gitMirrorSnapshot 或等价字段，使受控 CLI 通过 k8s git-mirror resolver 选择本轮 selectedCommit 并创建不可变 snapshot/stageRef。sourceAuthority.allowHostGit=false 时，正式 trigger-current、image publish、GitOps render 和 closeout 不得执行 operator host git ls-remote、git fetch、git clone、git rev-parse HEAD 或读写固定 host workspace。

PipelineRun source step 不得以 mutable refs/heads/<branch> 作为本轮源码身份。它只能从 source snapshot 的 stageRef、commit-pinned mirror ref、PVC 或 bundle artifact checkout；若对象缺失，应返回 source-snapshot-missing，并输出受控 git-mirror sync/ensure-snapshot 下一步，不得回退到 GitHub direct clone、host workspace repair 或第二套 source resolver。

status/closeout 必须同时展示 selected snapshot、PipelineRun snapshot、latest mirror head、GitOps revision 和 runtime provenance。branch 在发布过程中前进只能标记为 latest-drift 或 superseded，不得把 selected commit 的成功发布误判为本轮失败。

6.11 OPS-TARGET-REQ-011 L2/L3手动触发配置

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-011	手动触发	PJ2026-01060308 YAML目标治理	发布流水、NC01 CI资源治理

CI/CD owning YAML 必须为 L2/L3 target 声明 deliveryTrigger.mode=manual-plan-confirm 和 deliveryTrigger.mechanism=pac-webhook。这些字段是发布触发方式的唯一真相；PaC webhook 接收端保留，Gitea 自动 hook 必须移除。代码、环境变量、Repository annotation 和 consumer 私有配置不得恢复自动 push、PR merge、branch update、poll 或 follow 发送行为。

只读 plan 必须从 YAML 和精确 source commit 解析 env reuse、待构建镜像、rollout 服务、全部受影响服务、范围基线和新增范围。发现新增范围时必须先修复配置或 planner 后重新 plan，不得使用强制参数越过。

受控手动 trigger 必须同时接收 target、consumer 或 lane、精确 source commit 和 pipeline intent，并向 PaC 发送 webhook；CLI 不得直接创建 PipelineRun。输入、YAML、env identity 或构建/rollout 范围变化后必须重新 plan。PR merge 后不自动 trigger，L0/L1 操作也不得调用该 mutation。

6.8 OPS-TARGET-REQ-008 k3s server 重启门禁非阻塞

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-008	k3s重启	PJ2026-01060308 YAML目标治理	平台运维、控制面模块化

k3s server 受控重启不得以派生凭据文件与 datastore 的 mtime 或 freshness 预判阻断 YAML-first 变更。入口应在停止服务后备份派生 server/cred/passwd，并以 blocking=false warning 披露；只有真实启停、 节点就绪或期望状态收敛失败才可使 apply 失败。不得重新引入凭据新旧 preflight、CI gate 或人工确认门禁。

6.9 OPS-TARGET-REQ-009 CI 工具镜像默认能力

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-009	工具镜像能力	PJ2026-01060308 YAML目标治理	发布流水、平台运维

• CI tools image 必须默认包含 kubectl；
• kubectl 必须由 owning YAML 声明的 Dockerfile 在镜像构建阶段安装和自检；
• 使用 tools image 的有界 CI helper、cleanup 和 bootstrap 可以调用镜像内的 kubectl；
• 禁止在 PipelineRun、Pod 或 Job 启动后临时安装 kubectl；
• 该默认能力只属于 CI tools image，不得隐式扩大为产品业务镜像或长期 controller 的运行时依赖。

6.10 OPS-TARGET-REQ-010 发布观测证据适用性

编号	短名	主责模块	关联模块
OPS-TARGET-REQ-010	观测证据适用性	PJ2026-01060308 YAML目标治理	发布流水、运维监控

PaC consumer 必须通过 owning YAML 的 deliveryObservation.runtimeEvidence 声明发布观测是否需要 workload 证据。

• required consumer 必须观察到与 source commit 精确匹配且 ready 的 workload；
• not-applicable 只适用于配置或控制面交付，没有独立业务 workload 的 consumer；
• not-applicable consumer 仍必须满足 source commit 匹配、PipelineRun 成功和 Argo Synced/Healthy；
• 非核心字段缺失时可以回退到 required，但必须输出配置路径、回退值、原因和 blocking=false warning；
• 观测模式不得改变 PipelineRun、GitOps、Argo 或 runtime authority，也不得新增第二状态源。

7. 过程控制

本规格的执行 issue 为 #911。源码文件头部应标注 SPEC: PJ2026-01060308 cicd-yaml-targets draft-2026-06-25-cicd-yaml-targets；自动生成文件、纯配置、锁文件和无法承载注释头的二进制产物可例外。

首轮 hardcode inventory：

命中	分类	治理动作
ciTarget()、d601ProviderId、CI pipeline manifest、node label、host/root/workspace	remove-code-default	迁入 config/cicd/targets.yaml，CI resolver 读取 YAML。
artifact-registry 默认 D601、127.0.0.1:5000、runtime image、storageDir	remove-code-default	迁入 config/artifact-registry.yaml。
deploy artifact consumer provider 默认 D601	remove-code-default	从 artifact-registry YAML default 解析；compat path 显式 legacy。
`HwlabRuntimeLane = "v02"	"v03"和isSupportedLaneId()`	remove-code-default
platform-infra observability 复制 targetNode/lane/namespace	remove-code-default	改为 serviceConnection configRef 并输出解析链。
D601 maintenance deploy、Code Queue compat path、v02 runtime migration	legacy-adapter	保留安全阻断和替代命令，不作为主路径默认。
帮助示例、错误消息、历史说明中的 G14/D601/v02/v03	help-example	允许保留，必要时补 configTruth 或 legacy 标注。