pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md

# PJ2026-010603 YAML运维

## 修改历史

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

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

## 正文

## PJ2026-010603 YAML运维需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010603 |
| 短名 | YAML运维 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 YAML运维的稳定使命、范围、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染和受控下发，使 target、lane、node、service、Secret 绑定、公开入口和执行策略从 YAML 进入运行面，而不是散落在代码常量、运行面手补或一次性脚本中。

当前实现已经将 Sub2API Codex pool 的 target、publicExposure、sentinelImageBuild 和 manualAccounts.bindingSources，以及 AgentRun controlPlane default、client.sessionPolicy、lane secret providerCredential profile 和部分 fingerprint/helper 收敛到 YAML 与公共 ops helper。后续能力应在该基线上扩展，保持 YAML 为可审查、可版本化、可解释的配置真相。

### 2.2 范围内

- UniDesk 自有平台配置的 YAML 真相源、字段读取、必填项校验和类型校验。
- target、lane、node、service、namespace、endpoint、publicExposure 和运行目标解析。
- Secret sourceRef、targetKey、providerCredential、manual binding source 和敏感输出约束。
- Sub2API、Codex pool、AgentRun control-plane、session policy 和平台基础设施配置的受控 CLI 读取、解释、计划和下发。
- AgentRun lane 的 runner retention、idle timeout、egress proxy 和 cancel lifecycle policy 等运行策略配置读取、解释和下发。
- FRP、Caddy、public URL、public health、Kubernetes Secret 和平台资源渲染所需的配置投递边界。
- 可复用 ops primitive，包括 YAML path 捕获、字段解析、fingerprint、摘要输出、Secret 引用、有界默认输出和命令输出约束。
- 新节点 host bootstrap 的 0 依赖出网代理、`trans` 分发、host route 注入和 k3s 安装前置控制。
- YAML 配置的基线继承、configRef 组合、变量渲染和节点覆盖治理，避免为不同 node/lane 重复复制大段配置。

### 2.3 范围外

- Code Agent、AgentRun run、command、workspace 和 session 的业务生命周期语义归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- 用户身份、API key、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。
- Web、CLI 和 HTTP API 的用户入口体验归 [客户端](PJ2026-0104-client.md)。
- 具体容量、冷却时间、退避窗口、账号优先级、provider 选择和公开入口数值不写成代码常量或规格硬编码；这些数值由对应 YAML 配置承载。
- 从运行面 Secret、pod env、日志或数据库反推、解码、回填本地配置真相不属于本课题允许能力。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| YAML 真相源 | UniDesk 自有平台配置的版本化 YAML 文件，代码只负责读取、校验结构、解释和下发。 |
| 受控 CLI | 通过 UniDesk CLI 暴露的配置读取、计划、同步、解释和状态入口，避免手写脚本直接操作运行面。 |
| target | YAML 中描述服务部署目标、运行节点、namespace、公开入口和相关渲染参数的对象。 |
| lane | YAML 中描述某条运行线的目标节点、namespace、source truth、Secret 和执行策略的对象。 |
| sourceRef | YAML 中指向密钥来源的声明，输出时只能显示来源标识和摘要，不显示密钥值。 |
| targetKey | YAML 中声明运行面 Secret 或配置对象接收某项密钥的 key 名。 |
| providerCredential | AgentRun lane 中声明 provider profile 与运行面 Secret 绑定关系的配置项。 |
| cancel lifecycle policy | AgentRun lane 中声明取消投递、runner abort、kill escalation、stale fencing 和事件阶段输出的配置块；具体数值以 YAML 为准。 |
| publicExposure | YAML 中描述 FRP、Caddy、domain、TLS、public URL 和 health 目标的公开入口声明。 |
| ops primitive | 平台运维 CLI 共享的底层能力，例如字段解析、fingerprint、Secret 引用、摘要输出和 YAML path 捕获。 |
| 配置解释输出 | CLI 将 YAML 解析后的默认值、来源和目标以非敏感摘要展示给操作人员的输出。 |
| 有界默认输出 | CLI 在未显式请求机器输出或完整输出时返回的短摘要、表格和 drill-down 命令集合。 |
| host proxy client | 新节点 k3s 安装前由 `trans` 分发的 0 依赖出网代理客户端，用于给 Docker、k3s、containerd、包管理器、Git 和 git-mirror 提供初始出网。 |
| 配置组合 | 通过 baseline、configRef、继承、覆盖和变量渲染生成有效计划的配置方式；组合结果是执行视图，不是第二份可编辑真相源。 |
| 稳定工作负载选择器 | 由 namespace 和 Kubernetes labels 组成、跨 Pod 重建保持不变的工作负载身份；Pod UID 只能是运行面解析结果。 |
| 精确 cgroup 回收 | 受控 CLI 将稳定工作负载选择器解析为当前 Running Pod cgroup，并在执行前重新解析身份后请求有界 `memory.reclaim`。 |

## 4. 系统边界和接口

本规格把 YAML运维作为平台运维内的配置真相和受控下发课题看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 平台管理员、发布操作人员、Agent编排维护者、Sub2API/Codex pool 维护者和自动化运维任务。 |
| 外部输入 | YAML 配置文件、target/lane/node/service 声明、Secret sourceRef、providerCredential、publicExposure、host proxy 声明、baseline/configRef、运行目标选择和配置解释请求。 |
| 受控资源 | 配置解析器、公共 ops helper、Sub2API/Codex pool 配置、AgentRun lane 配置、host proxy client 分发和 systemd 渲染、Kubernetes Secret 声明、FRP/Caddy 渲染、public health 和 CLI 输出摘要。 |
| 外部输出 | 配置解释结果、计划摘要、同步摘要、Secret presence/fingerprint、host proxy health、publicExposure 渲染结果、运行目标解析结果、有界默认输出和错误诊断。 |
| 用户接口 | `bun scripts/cli.ts platform-infra ...`、`bun scripts/cli.ts agentrun ...`、受控 Secret 同步命令、配置解释命令和平台状态查询命令。 |
| 系统边界 | YAML运维负责让配置从 YAML 可解释、可校验并受控进入运行面；不定义业务策略数值、不替代 Agent/用户/客户端语义，也不把运行面观测反向变成本地配置真相。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01060301 | 配置真相 | 本规格 6.1 | YAML 文件、字段读取、必填项和类型校验 | 平台配置需求、服务 owner 输入 | 平台 CLI、运行面渲染 |
| PJ2026-01060302 | 目标解析 | 本规格 6.2 | target、lane、node、service、namespace 和默认目标解析 | 配置真相、运行 lane 约定 | Sub2API、AgentRun、公开入口 |
| PJ2026-01060303 | 密钥绑定 | 本规格 6.3 | sourceRef、targetKey、providerCredential、manual binding 和敏感输出约束 | 凭据来源、服务 Secret 需求 | 用户管理、Agent编排、Sub2API |
| PJ2026-01060304 | 暴露渲染 | 本规格 6.4 | publicExposure、FRP、Caddy、public URL 和 health 渲染 | 目标解析、服务入口需求 | 客户端、用户管理、Agent编排 |
| 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 |
| PJ2026-01060309 | 跨节点代理基准 | [PJ2026-01060309 跨节点代理CI基准](PJ2026-01060309-cross-node-proxy-ci-benchmark.md) | 通过基准验证代理方案和跨节点依赖拉取能力 | public egress、proxy source | host proxy、k3s deps、CI/CD |
| PJ2026-01060310 | 真实依赖基准 | [PJ2026-01060310 Real K3s Dependency Proxy Benchmark](PJ2026-01060310-real-k3s-deps-proxy-benchmark.md) | 使用真实 k3s 镜像、apk、npm、Go 和 Git mirror 依赖验证代理路径 | 跨节点代理基准、platform-infra proxy | k3s 构建、git-mirror、节点引导 |
| PJ2026-01060311 | Host引导代理 | 本规格 6.9 | 0 依赖 host proxy client、`trans` 分发、host route 注入和 k3s 安装前出网控制 | 代理基准、目标解析、密钥绑定 | 新节点纯净 k3s 部署、package manager、git-mirror |
| PJ2026-01060312 | 配置组合 | 本规格 6.10 | baseline、configRef、继承、覆盖、变量渲染和重复块治理 | 配置真相、目标解析、公共原语 | 多节点 YAML 复用、长期维护 |
| PJ2026-01060313 | K3s本地Registry | 本规格 6.11 | node-local registry 的 k3s workload/PVC、零种子迁移、镜像预加载和 Docker 依赖分类 | Host引导代理、目标解析、发布流水 | 纯净 k3s bring-up、HWLAB/AgentRun 构建 |
| PJ2026-01060314 | Hyper-V Ubuntu虚拟机 | [PJ2026-01060314 Hyper-V Ubuntu虚拟机](PJ2026-01060314-hyperv-ubuntu-vm.md) | Windows Hyper-V 宿主上的 Ubuntu VM、网络、初始化、常驻和 Provider 接入 | 配置真相、目标解析、Host引导代理 | Docker、k3s、provider-gateway、trans |
| PJ2026-01060315 | 精确工作负载回收 | 本规格 6.12 | 稳定工作负载选择器、当前 Pod cgroup 解析和有界内存回收 | 配置真相、目标解析、公共原语 | 平台 GC、核心运行面保护 |

## 6. 原子需求

### 6.1 OPS-YAML-REQ-001 YAML 配置真相

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-001 | 配置真相 | PJ2026-01060301 配置真相 | [平台运维](PJ2026-0106-platform-ops.md) |

YAML运维应将 UniDesk 自有平台配置维持为 YAML 真相源，使平台服务的 target、lane、node、service、Secret、公开入口和策略字段都能从版本化配置读取。

代码只负责解析、类型校验、必填项校验、路径定位和错误说明，不得把容量、冷却时间、endpoint、namespace、账号候选、provider 选择或公开入口数值固化为隐藏默认值。缺少配置时应暴露明确缺口，由 YAML 或上游密钥来源修正。

### 6.2 OPS-YAML-REQ-002 Target 与 lane 解析

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-002 | 目标解析 | PJ2026-01060302 目标解析 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md) |

YAML运维应提供 target、lane、node、service、namespace 和默认目标解析能力，使平台 CLI 在未显式传入目标时也能从 YAML 找到当前受控目标。

目标解析必须把默认值来源解释清楚，并允许操作人员显式指定 node 或 lane 覆盖默认选择。不同服务不得各自维护一套硬编码 G14、v0.1、namespace 或 service 名称；新增服务应复用同一类解析模式。

当 issue、PR 或 CLI 已经明确 node/lane 时，YAML 解析只负责校验和解释该目标，不得用全局默认覆盖用户选择。没有明确目标时，CLI 可以读取 YAML default，但输出必须说明 default 来源、目标 node/lane、namespace、source truth 和公开入口，避免把历史 G14/v0.2、D601 legacy 或旧 `dev/prod` 口径误用为当前运行面。

AgentRun `send session`、`explain session-policy`、resource primitives 和 AipodSpec render 都属于 node/lane 敏感入口。命令行或请求体已明确 node/lane 时，这些入口必须使用目标 lane 的 YAML 事实解析 backendProfile、providerId、workspaceRef、executionPolicy、provider credential SecretRef、tool credential SecretRef、namespace 和 source truth；不得在解释、dry-run、短命令或 JSON body 路径中回退到 control-plane default 或历史全局 sessionPolicy。

### 6.3 OPS-YAML-REQ-003 Secret 绑定与敏感输出

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-003 | 密钥绑定 | PJ2026-01060303 密钥绑定 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

YAML运维应通过 sourceRef、targetKey、providerCredential 和 manual binding source 描述密钥来源与运行面目标，使 Sub2API、Codex pool、AgentRun 和后续平台服务可以按声明同步凭据。

密钥相关输出只能展示对象名、key 名、sourceRef、presence、fingerprint、字节数和执行摘要，不得打印 base64 payload、解码值、完整 DSN、API key 或可复制凭据。运行面只能作为 presence 和 health 观测对象，不能被用来反推本地配置真相。

目标 lane 缺少 providerCredential、tool credential、targetKey 或 sourceRef 时，应作为 YAML 配置或 AipodSpec binding 缺口暴露。受控 CLI 可以显示缺失对象名、key 名、YAML path、presence=false、fingerprint 缺失和 `valuesPrinted=false`，但不得用手工 Secret、复制其他 lane 凭据、读取运行面 Secret value 或 patch namespace 的方式修复配置缺口。

### 6.4 OPS-YAML-REQ-004 公开入口渲染

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-004 | 暴露渲染 | PJ2026-01060304 暴露渲染 | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

YAML运维应从 publicExposure 和 target 声明渲染 FRP、Caddy、public URL、TLS 和 public health 所需配置，使公开入口由 YAML 控制并能被 CLI 解释。

公开入口渲染负责入口目标、健康探针和运行面配置的一致性。页面行为、API 契约、用户登录和 Agent 任务语义由关联 L1 定义；YAML运维只保证这些入口被正确投递到声明的目标运行面。

每个 node/lane 的正式用户入口必须由 YAML 中的 `public.webUrl`、`public.apiUrl` 和 `publicExposure` 共同声明。FRP remote port、Caddy backend、本地 service DNS、旧 direct port、历史 nip.io 域名或仓库 generic deploy 默认值只能作为实现细节、诊断入口或 legacy 对照，不能反向覆盖 node/lane 的正式入口真相。

受控 CLI、文档生成和验收提示应优先输出正式 public URL，并把实现端口标注为诊断用途。缺少正式 public URL、DNS 与 `expectedA` 不一致、Caddy/FRP 渲染目标不一致或运行面 health 不匹配时，应暴露为 publicExposure 配置或投递缺口，而不是让调用方回退到旧端口继续验收。

### 6.5 OPS-YAML-REQ-005 AgentRun 执行策略配置

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-005 | 执行策略 | PJ2026-01060305 执行策略 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md) |

YAML运维应为 AgentRun control-plane default、client sessionPolicy、lane secret providerCredential、workspace、execution policy 和 cancel lifecycle policy 提供配置读取与解释，使 AgentRun 运维入口不依赖代码内固定 profile、namespace、取消超时或执行策略。

cancel lifecycle policy 至少应能声明取消信号投递方式、runner graceful abort、kill escalation、stale heartbeat fencing window、late write fencing 和默认事件阶段输出开关。CLI 只校验字段结构、类型、必填项和可渲染性；具体窗口、超时和开关值由 YAML 承载，不在代码或 SPEC 中写成第二真相。

sessionPolicy 的解释、Session follow-up 的 run body、AipodSpec render 结果和 resource primitive 的 dry-run/JSON 形态必须来自同一套 YAML 目标解析。非默认 lane 的 backendProfile、providerId、workspaceRef、executionPolicy 和 provider credential SecretRef 不得被全局 default lane 覆盖；输出中应明确目标 lane 与 policy 来源，使操作者能在创建 run/command 前发现 lane 绑定错误。

本需求只约束执行策略如何作为平台配置进入运行面。Agent run、command、session 状态机、任务恢复、取消语义和 provider 业务语义由 Agent编排负责，用户身份和 API key 约束由用户管理负责。

### 6.6 OPS-YAML-REQ-006 公共 ops primitive

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-006 | 公共原语 | PJ2026-01060306 公共原语 | [平台运维](PJ2026-0106-platform-ops.md) |

YAML运维应沉淀公共 ops primitive，使字段解析、YAML path 捕获、fingerprint、Secret 引用、摘要输出和配置错误说明在 Sub2API、AgentRun 和后续平台 CLI 中复用。

公共 ops primitive 的职责是减少重复硬编码和输出口径漂移。领域 CLI 仍负责自身命令形态和服务语义，但不得复制一套不同的敏感输出、fingerprint、字段解析或 YAML 缺失处理规则。

受控 CLI 的默认输出必须是有界摘要、关键字段表格和下一步 drill-down 命令；`/tmp/unidesk-cli-output` dump 只能作为异常兜底，不能成为正常交互路径。完整 JSON、raw payload、完整 task/result/log、长 plan 和机器消费输出只能在显式 `--full`、`--raw`、`-o json` 或等价机器消费参数下返回，并仍须遵守 Secret 脱敏规则。

### 6.7 OPS-YAML-REQ-007 控制面模块化

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-007 | 控制面模块化 | [PJ2026-01060307 控制面模块化](PJ2026-01060307-control-plane-modularity.md) | [发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md)、[平台运维](PJ2026-0106-platform-ops.md) |

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。

### 6.9 OPS-YAML-REQ-009 Host 引导代理

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-009 | Host引导代理 | PJ2026-01060311 Host引导代理 | [发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md)、[平台运维](PJ2026-0106-platform-ops.md) |

YAML运维应为新节点提供 k3s 安装前可用的 host proxy client 能力。该 client 必须是 0 依赖分发对象，不能依赖 Docker、k3s、containerd、Node、Python、Bun、Go、Rust 或需要出网的包管理器安装步骤；它通过 `trans` 进入目标 host，并从 YAML 渲染本地监听、上游代理、Secret sourceRef、systemd 或等价 host 控制、健康探针和环境注入目标。

host proxy client 的职责是给 k3s installer、containerd image pull、包管理器、Git、git-mirror sync/flush 和受控 host 依赖安装提供初始出网。provider-gateway 和 `trans` 是控制通道，不应承载大二进制和大量依赖下载的长期数据通道。k3s 安装、Argo/git-mirror/web-probe/哨兵等后续运行面必须通过 YAML 声明是否使用 host proxy route、in-cluster proxy Service 或 direct egress。

host proxy 输出必须保持敏感信息边界。CLI 可以展示监听地址、端口、service 状态、sourceRef、fingerprint、probe 摘要和 `NO_PROXY` 覆盖状态；不得打印代理凭据、订阅内容、完整 URL credential、API key 或可复制密钥。`NO_PROXY` 必须保留本地、集群、metadata 和显式直连域，包括 `hyueapi.com` 与 `.hyueapi.com`。

### 6.10 OPS-YAML-REQ-010 YAML 配置组合

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-010 | 配置组合 | PJ2026-01060312 配置组合 | [控制面模块化](PJ2026-01060307-control-plane-modularity.md)、[YAML目标治理](PJ2026-01060308-cicd-yaml-first-target-governance.md) |

YAML运维应支持可复用、可继承、可组合的配置结构，使多个 node/lane 可以从公共 baseline、共享 configRef 和短 override 得到具体运行计划，而不是复制整段配置到每个节点文件。组合后的 effective plan 只作为执行和解释视图存在，不得写回为第二份可编辑真相源。

变量渲染只能把 node、lane、service 等作为数据变量传入模板。YAML 文件名、解析函数名、渲染函数名、helper 名和 schema 名不得带具体 node/lane 名；具体 node/lane 只能出现在 YAML value、CLI 参数、外部系统要求的运行对象名或已分类 legacy adapter 中。

当配置文件因重复 node/lane 块持续膨胀时，YAML运维应先拆出职责和公共 baseline，再继续新增目标。拆分边界包括 host bootstrap、proxy、k3s install、platform-infra、HWLAB lane、AgentRun lane、Secret sourceRefs、publicExposure、probes 和 sentinel schedules。超过 3000 行的代码、运维脚本或配置文件应先按职责拆分，再继续承载新能力。

### 6.11 OPS-YAML-REQ-011 K3s 本地 Registry

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-011 | K3s本地Registry | PJ2026-01060313 K3s本地Registry | [发布流水](PJ2026-010601-controlled-release.md)、[YAML目标治理](PJ2026-01060308-cicd-yaml-first-target-governance.md) |

YAML运维应允许新节点在没有旧 registry 数据和没有长期 host Docker registry 容器的前提下建立 node-local registry。registry 的 namespace、Deployment、Service、PVC、endpoint、image source、hostNetwork/bind 策略和 readiness probe 必须来自 owning YAML 或显式参数；host Docker registry 只能作为 legacy 或迁移前状态，不能作为新平台从零部署 registry 的依赖。

当迁移目标是证明从零部署能力时，受控 CLI 应先停止旧 host Docker registry，并在状态中明确 `seededFromOldRegistry=false`、`zeroSeeded=true`、PVC bound、workload ready 和 endpoint ready。迁移后所需的 BuildKit、runtime/base、tools image 和 service build artifact 必须通过 YAML-first `runtime-image preload`、tools image build/status 或等价 k3s 构建入口补齐，不能通过旧 registry 拷贝伪装成从零成功。

YAML运维状态输出应区分三类依赖：必须保留的 host bootstrap 面（provider-gateway/trans、0 依赖 host proxy、k3s installer/systemd）、待迁移的 host Docker/one-shot build 面，以及已经进入 k3s 的长期服务。后续减少 Docker 依赖时，应优先把长期服务、registry、git-mirror cache、web-probe/哨兵和构建执行迁入 k3s；host proxy client 不属于迁移目标。

### 6.12 OPS-YAML-REQ-012 精确工作负载内存回收

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-YAML-REQ-012 | 精确工作负载回收 | PJ2026-01060315 精确工作负载回收 | [平台运维](PJ2026-0106-platform-ops.md)、[NC01 CI资源治理](PJ2026-01060107-nc01-ci-resource-governance.md) |

平台 GC 应允许 owning YAML 使用稳定工作负载选择器声明精确 cgroup 回收目标。选择器至少包含 namespace、非空 labels 和最大匹配 Pod 数；目标可用内存、单 Pod 回收上限、swappiness、inactive anonymous memory 下限和 swap 保留线继续由 YAML 声明。YAML 不得保存 Pod UID、容器 ID、当前 cgroup 路径或从运行面反解出的可调数值。

受控 plan 只选择 Running Pod，并披露 selector、解析出的 namespace、Pod、UID、cgroup、当前内存、inactive anonymous memory 和保护原因。零匹配、超过最大匹配数、API 不可读、cgroup 缺失、symlink、内存下限不足或 swap 保留线不足时必须保护，禁止回退到父 cgroup、按名称猜测或扩大 selector。

执行前必须使用同一 YAML selector 重新解析当前 Running Pod，并逐项核对 Pod UID、cgroup 路径和全部回收参数。身份变化、目标已满足或候选不再合格时跳过且结构化披露；只有身份闭合的当前 cgroup 才能写入有界 `memory.reclaim`。执行不得停止、重启、驱逐或迁移 workload，也不得把内核请求上限宣称为实际收益；终态继续分别披露 cgroup 下降、宿主 `MemAvailable` 变化、目标缺口和 swap 排除状态。