# PJ2026-010601 发布流水

## 修改历史

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

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

## 正文

## PJ2026-010601 发布流水需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010601 |
| 短名 | 发布流水 |
| 层级 | 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 需求规格模板的项目裁剪版：正文只保留受控发布、版本 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 的来源真相归 [源码同步](PJ2026-010602-source-sync.md)。
- YAML 配置、SecretRef sourceRef/targetKey、fingerprint 和受控下发归 [YAML运维](PJ2026-010603-yaml-first-ops.md)。
- 具体服务的业务执行事实归对应业务规格；AgentRun run、command、event、runner job 和 terminal status 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)，AgentRun `v0.1` 专项发布 lane 归 [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)。
- RuntimeAssembly、AipodSpec、gitbundle 和 Secret projection 归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。
- Backend adapter、provider profile 和真实 provider turn 语义归 [后端Profile](PJ2026-010204-backend-profile.md)。
- 一次性排障、长日志、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](PJ2026-01060105-agentrun-v01-release-lane.md) | 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发布 | [源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

发布流水应为 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 | [源码同步](PJ2026-010602-source-sync.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |

发布流水应提供镜像构建、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 发布判定 | [源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

发布流水应以 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编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

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

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