# 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 引用、有界默认输出和命令输出约束。

### 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 命令集合。 |

## 4. 系统边界和接口

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

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 平台管理员、发布操作人员、Agent编排维护者、Sub2API/Codex pool 维护者和自动化运维任务。 |
| 外部输入 | YAML 配置文件、target/lane/node/service 声明、Secret sourceRef、providerCredential、publicExposure、运行目标选择和配置解释请求。 |
| 受控资源 | 配置解析器、公共 ops helper、Sub2API/Codex pool 配置、AgentRun lane 配置、Kubernetes Secret 声明、FRP/Caddy 渲染、public health 和 CLI 输出摘要。 |
| 外部输出 | 配置解释结果、计划摘要、同步摘要、Secret presence/fingerprint、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 |

## 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。
