pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-01060105-agentrun-v01-release-lane.md

# PJ2026-01060105 AgentRun发布Lane

## 修改历史

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

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

## 正文

## PJ2026-01060105 AgentRun发布Lane需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01060105 |
| 短名 | AgentRun发布 |
| 层级 | L3 子课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AgentRun `v0.1` 作为发布流水具体消费对象的 lane、CI/CD、运行面和真实联调要求。

## 2. 目的和范围

### 2.1 目的

AgentRun发布Lane负责定义 AgentRun `v0.1` 在 G14 上的专用发布 lane，使 `v0.1` source、GitOps、runtime、CI/CD、镜像和验证入口不与旧 dev/prod 口径或其他版本 lane 混用。

### 2.2 范围内

- AgentRun `v0.1` runtime namespace、GitOps branch、Tekton namespace、Pipeline、ServiceAccount、PipelineRun 命名和 runtime path。
- Env image reuse、digest-pinned image、artifact promotion 和 runner/backend work-ready image 要求。
- AgentRun manager、runner、Postgres、SecretRef、provider profile、Queue/Session 和 backend real turn 在综合联调中的发布判定。
- AgentRun CLI 在发布验收中的正式操作入口，包括 runs、commands、runner jobs、queue、sessions、provider profiles、backends、secrets 和 server lifecycle 命令。
- manager rolling、runner terminal outbox、reconciler re-attach 和 HWLAB Workbench projection recovery 的 rolling/chaos 发布验收。

### 2.3 范围外

- 通用发布流水、镜像 promotion 和验证分层规则归 [发布流水](PJ2026-010601-controlled-release.md)。
- AgentRun source branch、fixed worktree、Git mirror、GitOps branch 和 artifact catalog source truth 归 [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)。
- AgentRun run、command、runner job、event 和 terminal status 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。
- RuntimeAssembly、AipodSpec、gitbundle 和 Secret projection 归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| AgentRun v0.1 lane | AgentRun `v0.1` 的 runtime namespace、GitOps branch、CI pipeline、image registry 和发布验收集合。 |
| AgentRun CI | G14 上用于 AgentRun `v0.1` 构建、promotion 和 GitOps 更新的 Tekton pipeline。 |
| env image | AgentRun runner/backend 的 work-ready 基础执行环境镜像。 |
| real provider turn | 通过真实 Codex app-server stdio backend 和真实 provider SecretRef 完成的一次 Code Agent turn。 |
| rolling recovery canary | 在真实 runner 执行期间滚动 HWLAB cloud-api 或 AgentRun manager，并证明同一 run/command/runnerJob 被恢复控制且最终投影到 Workbench 的发布验收切片。 |

## 4. 系统边界和接口

本规格把 AgentRun发布Lane作为发布流水下的 AgentRun 专项发布切片看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | AgentRun 维护者、平台运维、HWLAB Agent 维护者和 CI/CD 自动化任务。 |
| 外部输入 | AgentRun source commit、deploy/deploy.json、lane 配置、SecretRef presence、Tekton trigger、GitOps sync 和验证请求。 |
| 受控资源 | `agentrun-v01` runtime namespace、AgentRun Tekton Pipeline、Argo Application、runtime image、manager/runner workload 和 provider profile SecretRef。 |
| 外部输出 | PipelineRun 状态、image digest、promotion revision、runtime readiness、AgentRun CLI JSON、真实 turn 结果和 redacted failureKind。 |
| 用户接口 | UniDesk AgentRun CI/CD CLI、`./scripts/agentrun ...`、AgentRun REST API 和 service health/readiness。 |
| 系统边界 | AgentRun发布Lane只定义 AgentRun `v0.1` 的发布和验证细则；不替代 AgentRun 功能规格，也不把 mock、dry-run 或 source-only 结果当作发布通过。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-0106010501 | RuntimeLane | 本规格 6.1 | namespace、GitOps path、Pipeline、ServiceAccount 和 rollout 目标 | AgentRun源码真相、YAML运维 | AgentRun runtime |
| PJ2026-0106010502 | EnvImage | 本规格 6.2 | env image identity、digest-pinned image、work-ready 工具和 promotion | Source commit、registry、Containerfile | Runtime装配、runner job |
| PJ2026-0106010503 | CLI验收 | 本规格 6.3 | AgentRun CLI JSON、短返回、redaction 和正式命令入口 | AgentRun REST API | HWLAB 接入、队列会话 |
| PJ2026-0106010504 | 真实联调 | 本规格 6.4 | real provider turn、Postgres durable facts、SecretRef 和 terminal status | AgentRun核心、后端Profile | 发布判定 |
| PJ2026-0106010505 | Rolling验收 | 本规格 6.5 | manager/cloud-api rolling、runner 不中断、reconciler re-attach 和 Workbench projection recovery | AgentRun核心、HWLAB接入、Workbench实时权威 | 发布判定、运维监控 |

## 6. 原子需求

### 6.1 AR-RELEASE-REQ-001 v0.1 Runtime Lane

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RELEASE-REQ-001 | RuntimeLane | PJ2026-0106010501 RuntimeLane | [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) |

AgentRun `v0.1` 应使用独立 runtime lane，固定部署到 `agentrun-v01` namespace，并通过 AgentRun 专用 Tekton Pipeline、GitOps path 和 Argo Application 进入运行面。

`v0.1` 不复用旧 `dev/prod` 管理口径，不使用临时 clone、本地镜像、手工 Pod patch、自研 poller 或直接运行副本作为发布真相。后续 `v0.2`、`v0.3` 应使用各自独立 namespace、GitOps path 和 lane 配置。

### 6.2 AR-RELEASE-REQ-002 Env Image 与 Work-ready Runtime

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RELEASE-REQ-002 | EnvImage | PJ2026-0106010502 EnvImage | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[源码同步](PJ2026-010602-source-sync.md) |

AgentRun `v0.1` 的 runner/backend image 应按 env image reuse 模型构建和 promotion，最终运行面只使用 digest-pinned image。

AgentRun env image 必须包含 runner/backend 执行所需基础工具和生产依赖，使普通 Queue task、Session send 或 HWLAB canary 不在任务运行时默认安装基础环境。RuntimeAssembly 的 BackendImageRef 应能追溯 source commit、Dockerfile path、env identity、reuse/build 状态和 digest 摘要。

### 6.3 AR-RELEASE-REQ-003 AgentRun CLI 发布验收入口

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RELEASE-REQ-003 | CLI验收 | PJ2026-0106010503 CLI验收 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[队列会话](PJ2026-010203-queue-session.md)、[后端Profile](PJ2026-010204-backend-profile.md) |

AgentRun `v0.1` 发布验收应使用 `./scripts/agentrun` 作为正式 CLI 入口，覆盖 runs、commands、runner jobs、queue、sessions、provider profiles、backends、secrets 和 server lifecycle。

CLI 默认输出 JSON，stdout 不得为空伪成功，长时间模型 turn 必须短返回后通过 status/events 观察。发布验收不得用 debug/mock 路径、数据库直连或临时 kubectl 操作替代正式 CLI/API。

### 6.4 AR-RELEASE-REQ-004 AgentRun 真实综合联调

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RELEASE-REQ-004 | 真实联调 | PJ2026-0106010504 真实联调 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |

AgentRun `v0.1` 综合联调必须在真实 `agentrun-v01` 运行面完成，使用真实 Postgres、真实 Kubernetes SecretRef、真实 manager/runner/backend、真实 RuntimeAssembly 和至少一个真实 Code Agent provider turn。

mock backend、fake provider、source-only、dry-run、缺 provider credential 时的 skip、只读 health 成功或没有真实 command terminal status 的运行面状态，都不能作为 AgentRun 发布通过证据。涉及 profile 的变更还必须覆盖相关 backendProfile 的真实切换与隔离。

### 6.5 AR-RELEASE-REQ-005 rolling/chaos 发布验收

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RELEASE-REQ-005 | Rolling验收 | PJ2026-0106010505 Rolling验收 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md)、[运维监控](PJ2026-010605-observability-monitoring.md) |

AgentRun `v0.1` 发布验收应包含 rolling recovery canary。验收在 D601 v0.3 HWLAB 用户入口或等价受控 CLI 发起长程 Code Agent session，记录 `sessionId`、`traceId`、`runId`、`commandId`、`runnerJobId` 和 Kubernetes `jobName`；runner 正在执行时滚动 HWLAB cloud-api，runner 继续执行时滚动 AgentRun manager。滚动结束后，同一 run/command/runnerJob 必须被 manager reconciler 恢复控制并进入 Workbench projection，不重建 run、不人工 resubmit、不切 session repair。

rolling recovery canary 的通过证据至少包含：runner Job 未被删除或重建、terminal fact 通过 AgentRun durable ledger/outbox/reconciler 进入 DB、Workbench list/detail/messages/turn/trace 对同一 turn 状态一致、sealed final response 不被后续 diagnostic 覆盖，以及 CLI/web-probe/trace evidence 可关联同一运行对象。滚动期间允许短暂服务不可用或 diagnostic，但不得出现任务丢失、重复消息、session 跳转、状态回退或读侧 repair 通过。