pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md

PJ2026-010601 发布流水

修改历史

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

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

正文

PJ2026-010601 发布流水需求规格

1. 文档控制

字段	内容
编号	PJ2026-010601
短名	发布流水
层级	L2 课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0106 平台运维
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留受控发布、版本 lane、CI/CD、运行面发布判定和发布入口的通用稳定使命、范围、术语、系统边界、内部分工和原子需求。

2. 目的和范围

2.1 目的

发布流水负责把 HWLAB 平台服务从 source commit 通过受控 CI/CD、镜像、GitOps 和 rollout 交付到目标 runtime，使发布状态、运行版本、镜像来源和发布判定可追踪、可恢复、可审查。具体服务的固定 branch、namespace、pipeline、镜像、验证组合和 lane 数值只进入对应服务专项规格，不写成通用发布规则。

2.2 范围内

• HWLAB 各服务 lane 的通用发布模型、runtime namespace、CI pipeline、GitOps promotion 和 rollout 入口。
• Tekton PipelineRun、Argo CD sync、runtime image、env image reuse、digest-pinned image 和 artifact promotion。
• 发布候选判定中 source revision、GitOps desired state、runtime live state、Postgres migration、SecretRef presence 和 workload readiness 的一致性。
• UniDesk 受控 CI/CD CLI、服务自有 CLI 和服务 health/readiness 在发布验收中的正式入口边界。
• 自测试和综合联调在发布决策中的分层口径：自测试允许 mock，综合联调必须使用真实运行面。

2.3 范围外

• Git mirror、source commit authority、bundle/mirror URL 和 artifact catalog 的来源真相归 源码同步。
• YAML 配置、SecretRef sourceRef/targetKey、fingerprint 和受控下发归 YAML运维。
• 具体服务的业务执行事实归对应业务规格；AgentRun run、command、event、runner job 和 terminal status 归 AgentRun核心，AgentRun v0.1 专项发布 lane 归 AgentRun发布Lane。
• RuntimeAssembly、AipodSpec、gitbundle 和 Secret projection 归 Runtime装配。
• Backend adapter、provider profile 和真实 provider turn 语义归 后端Profile。
• 一次性排障、长日志、PR 过程、证据堆叠和文档治理规则不进入本规格正文。

3. 术语表

术语	定义
发布流水	从 source commit 到目标 runtime 的受控构建、promotion、GitOps sync、rollout 和发布状态查询链路。
版本 lane	按版本隔离的 source branch、runtime namespace、GitOps branch、CI pipeline 和发布验收集合。
PipelineRun	Tekton 中执行构建、镜像发布或 GitOps promotion 的一次流水线运行。
GitOps desired state	GitOps branch 中声明的目标运行面资源状态。
runtime live state	目标 namespace 中实际运行的 workload、image、config、health 和 readiness 状态。
env image reuse	基础执行环境镜像按 env identity 复用，普通业务源码变更只改变 boot commit。
综合联调	在真实目标运行面、真实 SecretRef、真实 backend/provider 或服务入口上完成的发布候选验证。

4. 系统边界和接口

本规格把发布流水作为平台运维内的服务交付系统看待；本章只描述输入、输出和责任边界。

边界项	内容
外部使用者	平台管理员、发布操作人员、服务维护者、CI/CD 自动化任务和需要发布状态的业务模块。
外部输入	source commit、deploy 配置、lane 选择、镜像构建请求、GitOps promotion 请求、rollout 请求、SecretRef presence 和验证请求。
受控资源	Tekton PipelineRun、Argo Application、runtime namespace、workload、image、release status、health/readiness 和发布判定结果。
外部输出	PipelineRun 状态、image digest、promotion revision、Argo sync 状态、runtime readiness、发布候选结论和 redacted 失败信息。
用户接口	UniDesk CI/CD CLI、服务自有 CLI 发布/验证相关入口、服务 health/readiness、Tekton/Argo 受控状态查询入口。
系统边界	发布流水负责让变更以可追踪、可恢复、可判定的方式进入运行面；不替代业务功能实现，不绕过受控 CLI，不把 mock 或 source-only 结果当作发布通过。

5. 内部分工与规格索引

本规格前四个 L3 只承载服务无关的通用发布规则。AgentRun 固定 branch、namespace、Pipeline、GitOps path、真实 provider turn 等内容只在 AgentRun 专项 L3 中展开，通用发布条款只保留可复用的发布边界。

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-01060101	Lane发布	本规格 6.1	source/GitOps/runtime namespace、CI pipeline 和 rollout 入口	源码同步、YAML运维	全部 runtime 服务
PJ2026-01060102	镜像Promotion	本规格 6.2	env image reuse、digest-pinned image、artifact promotion 和 image readiness	Source commit、Containerfile、registry	需要运行镜像的服务
PJ2026-01060103	发布判定	本规格 6.3	source/GitOps/runtime 一致性、health/readiness 和 migration/SecretRef presence	CI/CD、GitOps、YAML运维	平台管理员、业务模块
PJ2026-01060104	验证分层	本规格 6.4	自测试、综合联调、CLI/API 交互和真实运行面通过口径	目标 runtime、业务模块测试需求	发布决策
PJ2026-01060105	AgentRun发布	PJ2026-01060105 AgentRun发布Lane	AgentRun v0.1 的发布 lane、Pipeline、runtime namespace 和真实联调细则	源码同步、YAML运维、Agent编排	AgentRun runtime

6. 原子需求

6.1 OPS-RELEASE-REQ-001 版本 Lane 发布

编号	短名	主责模块	关联模块
OPS-RELEASE-REQ-001	Lane发布	PJ2026-01060101 Lane发布	源码同步、YAML运维、Agent编排

发布流水应为 HWLAB 平台服务提供版本 lane 发布能力，使 source branch、runtime namespace、GitOps branch、CI pipeline 和 rollout 入口相互隔离。

具体服务的 lane 固定值、历史口径废弃项和运行面名称应写入对应服务专项规格；通用发布流水只定义隔离、受控入口、可追溯和不可绕过原则。

CI/CD 目标必须由当前 issue、PR、CLI 参数或受控 lane 配置解析为明确 node + lane。G14 DEV/PROD、G14 v0.2、D601 v0.3 和后续 lane 都只是实例，不得把某个节点、namespace、GitOps path、FRP 端口或历史 dev/prod 口径写成通用默认。发布流水只能作用于被选中的 node/lane，不接管其他运行面。

6.2 OPS-RELEASE-REQ-002 镜像与 Promotion

编号	短名	主责模块	关联模块
OPS-RELEASE-REQ-002	镜像Promotion	PJ2026-01060102 镜像Promotion	源码同步、Runtime装配

发布流水应提供镜像构建、env image reuse、digest-pinned image 和 GitOps promotion 能力，使运行面使用的镜像能够追溯到 source commit、Containerfile、env identity 和 artifact 摘要。

需要 work-ready env image 的服务应在自身专项规格中声明工具和依赖要求；通用发布流水只保证镜像来源、digest、promotion 和运行面引用可追溯，不替业务模块定义运行时功能。

Artifact catalog 的 per-service provenance 是镜像 digest 的身份证明，必须能说明 source commit、component input hash、Containerfile hash、build args hash、base image identity、reuse/build 状态和最终 digest。复用旧 artifact 前必须能证明旧 digest 对应的 source tree 与本轮输入一致；缺 digest、缺 provenance 或 hash 不一致时应重新发布，不得用旧 guard、历史 PipelineRun 成功或 mutable tag 伪装通过。

6.3 OPS-RELEASE-REQ-003 发布一致性判定

编号	短名	主责模块	关联模块
OPS-RELEASE-REQ-003	发布判定	PJ2026-01060103 发布判定	源码同步、YAML运维、Agent编排

发布流水应以 source revision、GitOps desired state、runtime live state、image digest、workload readiness、Postgres migration、SecretRef presence 和 service health/readiness 的一致性判断发布候选。

PipelineRun 成功、Argo Synced、health 可访问或 source check 通过都不能单独替代业务运行面通过。发布判定只能输出 redacted 状态和摘要，不得包含 provider credential、Postgres DSN password、token、URL credential 或 Secret value。

6.4 OPS-RELEASE-REQ-004 两层验证口径

编号	短名	主责模块	关联模块
OPS-RELEASE-REQ-004	验证分层	PJ2026-01060104 验证分层	Agent编排、客户端、HarnessRL

发布流水应区分组件自测试和综合联调：自测试允许 mock，用于快速反馈；综合联调必须在真实目标运行面、真实依赖、真实配置和服务原入口上完成。

mock、fake dependency、source-only、dry-run、缺关键配置时的 skip、只读 health 成功或没有真实业务终态的运行面状态，都不能作为综合联调或发布通过证据。具体服务需要哪些真实依赖和终态，由对应服务专项规格定义。