mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: YAML-first 治理 CI/CD target (#919)

Browse Source 
* docs: specify cicd yaml target governance

* fix: resolve cicd targets from yaml

---------

Co-authored-by: Codex <codex@noreply.local>
This commit is contained in:
Lyon
2026-06-26 01:14:38 +08:00
committed by GitHub
parent 3777577df4
commit edfddd2445
35 changed files with 1079 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md
+13
View File
@@ -92,6 +92,7 @@ YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染
| PJ2026-01060305 | 执行策略 | 本规格 6.5 | AgentRun control-plane default、session policy、provider profile 和 workspace 策略配置 | Agent编排语义、lane 配置 | Agent编排、平台发布 |
| PJ2026-01060306 | 公共原语 | 本规格 6.6 | 字段解析、fingerprint、摘要输出、Secret 引用和 YAML path 捕获复用 | 各平台 CLI 实现 | 全部平台运维 CLI |
| PJ2026-01060307 | 控制面模块化 | [PJ2026-01060307 控制面模块化](PJ2026-01060307-control-plane-modularity.md) | CI/CD、YAML-first 和平台运维 CLI 源码入口的职责拆分、兼容入口和模块边界 | 发布流水、源码同步、公共原语 | 全部平台运维 CLI |
| PJ2026-01060308 | YAML目标治理 | [PJ2026-01060308 CI/CD YAML目标治理](PJ2026-01060308-cicd-yaml-first-target-governance.md) | CI/CD、HWLAB lane、AgentRun、platform-infra、Secret 和 public exposure 的 target/configRef/sourceRef 解析治理 | 控制面模块化、发布流水、源码同步 | CI、deploy、artifact-registry、HWLAB、AgentRun、platform-infra、secrets |
## 6. 原子需求
@@ -180,3 +181,15 @@ YAML运维应沉淀公共 ops primitive，使字段解析、YAML path 捕获、f
YAML运维应约束 CI/CD、YAML-first 和平台基础设施 CLI 的源码入口，使超过 3000 行的控制面文件先按职责拆入领域子目录，再继续沉淀公共 ops primitive。
原 `scripts/src/*.ts` 同名入口应只保留兼容 re-export、命令路由或极薄 adapter。配置解析、manifest 渲染、远端脚本、Secret/public exposure、git-mirror、Tekton/Argo、status summary 和 bounded output 等职责应进入领域模块或共享 helper。新增平台运维逻辑不得继续追加到已超限入口文件。
### 6.8 OPS-YAML-REQ-008 CI/CD YAML目标治理
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-008 | YAML目标治理 | [PJ2026-01060308 CI/CD YAML目标治理](PJ2026-01060308-cicd-yaml-first-target-governance.md) | [发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md)、[控制面模块化](PJ2026-01060307-control-plane-modularity.md) |
YAML运维应约束 CI、deploy、artifact-registry、HWLAB node/lane、AgentRun、platform-infra、Secret 分发和 public exposure 的目标解析，使 node、lane、target、namespace、route、workspace、registry endpoint、public URL、SecretRef、gitops path 和 CI/CD 参数来自 owning YAML 或显式参数。
公共 option parser 不得内置 domain target 默认。未显式传入目标时，调用 domain 可以从自身 YAML default 解析，并必须输出默认来源路径；已显式传入 node/lane/target 时，解析器只校验和解释该目标，不得用全局 default 覆盖。
跨 YAML 的运行目标事实应使用 `path/to/file.yaml#object.path` configRef，CLI `plan/status --full` 应显示引用链、resolved target、presence、摘要 hash 和缺失字段，不打印 Secret 值。代码中保留的 `G14`、`D601`、`v02`、`v03` 等目标名必须被 hardcode inventory 分类为 legacy adapter、help example、test fixture 或真实领域特例；隐藏默认必须迁移到 YAML。
project-management/PJ2026-01/specs/PJ2026-01060308-cicd-yaml-first-target-governance.md
+234
View File
@@ -0,0 +1,234 @@
# PJ2026-01060308 CI/CD YAML目标治理
## 修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
## 正文
## PJ2026-01060308 CI/CD YAML目标治理需求规格
## 1. 文档控制
| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01060308 |
| 短名 | YAML目标治理 |
| 层级 | L3 子课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) |
| 关联规格 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md)、[PJ2026-010602 源码同步](PJ2026-010602-source-sync.md)、[PJ2026-01060307 控制面模块化](PJ2026-01060307-control-plane-modularity.md)、[PJ2026-010604 公开入口](PJ2026-010604-public-entry.md)、[PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) |
| 实现引用版本 | draft-2026-06-25-cicd-yaml-targets |
| 规格治理索引 | [规格治理](spec-governance.md) |
本文采用 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 配置引用图
```mermaid
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 解析数据流
```mermaid
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 同步链路
```mermaid
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 链路
```mermaid
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 状态链路
```mermaid
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运维](PJ2026-010603-yaml-first-ops.md) |
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目标治理 | [公共原语](PJ2026-010603-yaml-first-ops.md#66-ops-yaml-req-006-公共-ops-primitive) |
跨 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目标治理 | [控制面模块化](PJ2026-01060307-control-plane-modularity.md) |
公共 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目标治理 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
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目标治理 | [发布流水](PJ2026-010601-controlled-release.md) |
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目标治理 | [平台运维](PJ2026-0106-platform-ops.md) |
每轮治理必须维护 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](https://github.com/pikasTech/unidesk/issues/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 | lane id 改为 YAML 声明 string，新增 lane 不要求改 TypeScript union。 |
| `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 标注。 |