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 需求规格模板
上级规格	PJ2026-0106 平台运维
规格治理索引	规格治理

本文采用 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编排。
• 用户身份、API key、额度、账本和租户策略归 用户管理。
• Web、CLI 和 HTTP API 的用户入口体验归 客户端。
• 具体容量、冷却时间、退避窗口、账号优先级、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 配置真相	平台运维

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编排、客户端

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 口径误用为当前运行面。

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

编号	短名	主责模块	关联模块
OPS-YAML-REQ-003	密钥绑定	PJ2026-01060303 密钥绑定	用户管理、Agent编排

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 暴露渲染	客户端、用户管理、Agent编排

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编排、用户管理

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 公共原语	平台运维

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

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