docs: add yaml ops l2 spec

2026-06-14 20:33:38 +00:00
parent bfc9ac7b31
commit f8521d2e25
2 changed files with 154 additions and 2 deletions
@@ -82,7 +82,7 @@
 | --- | --- | --- | --- | --- | --- |
 | PJ2026-010601 | 发布流水 | 本规格 6.1 | CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态 | Git commit、镜像配置、各 L1 发布需求 | 全部 L1 |
 | PJ2026-010602 | 源码同步 | 本规格 6.2 | Git mirror、source commit authority、bundle/mirror URL 和 lane source truth | Git remote、运行 lane、Agent 资源装配需求 | Agent编排、HarnessRL、客户端 |
-| PJ2026-010603 | YAML-first运维 | 本规格 6.3 | YAML-first 自动化分布式运维；SecretRef、targetKey、fingerprint 是其密钥分发子项 | 各 L1 配置需求、密钥来源 | 全部 L1 |
+| PJ2026-010603 | YAML-first运维 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) | YAML-first 自动化分布式运维；SecretRef、targetKey、fingerprint 是其密钥分发子项 | 各 L1 配置需求、密钥来源 | 全部 L1 |
 | PJ2026-010604 | 公开入口 | 本规格 6.4 | FRP、Caddy、domain、TLS、public health 和入口漂移处理 | 客户端/API 服务、运行 lane | 客户端、用户管理、Agent编排 |
 | PJ2026-010605 | 运维监控 | 本规格 6.5 | Prometheus metrics、scrape target、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、各 L1 服务健康指标 | 全部 L1 |

@@ -112,7 +112,7 @@

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| OPS-L1-REQ-003 | YAML-first运维 | PJ2026-010603 YAML-first运维 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[硬件池](PJ2026-0101-hardware-pool.md) |
+| OPS-L1-REQ-003 | YAML-first运维 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[硬件池](PJ2026-0101-hardware-pool.md) |

 平台运维应提供 YAML-first 自动化分布式运维能力，使 HWLAB 自有配置、target、lane、node、service 声明、render、validate 和受控下发通过 YAML 真相源进入运行面。

@@ -0,0 +1,152 @@
+# 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 读取、解释、计划和下发。
+- 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 绑定关系的配置项。 |
+| publicExposure | YAML 中描述 FRP、Caddy、domain、TLS、public URL 和 health 目标的公开入口声明。 |
+| ops primitive | 平台运维 CLI 共享的底层能力，例如字段解析、fingerprint、Secret 引用、摘要输出和 YAML path 捕获。 |
+| 配置解释输出 | CLI 将 YAML 解析后的默认值、来源和目标以非敏感摘要展示给操作人员的输出。 |
+
+## 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 |
+
+## 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 名称；新增服务应复用同一类解析模式。
+
+### 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 观测对象，不能被用来反推本地配置真相。
+
+### 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运维只保证这些入口被正确投递到声明的目标运行面。
+
+### 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 提供配置读取与解释，使 AgentRun 运维入口不依赖代码内固定 profile、namespace 或执行策略。
+
+本需求只约束执行策略如何作为平台配置进入运行面。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 缺失处理规则。