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
规格治理索引	规格治理

本文采用 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。
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/sync/flush via controlled entry
  Mirror-->>CLI: refs and pendingFlush summary
  CLI->>Tekton: PipelineRun status or dry-run manifest
  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 推断所有阶段完成。

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 的脱敏输出。

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 标注。