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 需求规格模板
上级规格	PJ2026-010601 发布流水
规格治理索引	规格治理

本文采用 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 和验证分层规则归 发布流水。
• AgentRun source branch、fixed worktree、Git mirror、GitOps branch 和 artifact catalog source truth 归 AgentRun源码真相。
• AgentRun run、command、runner job、event 和 terminal status 归 AgentRun核心。
• RuntimeAssembly、AipodSpec、gitbundle 和 Secret projection 归 Runtime装配。

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源码真相、YAML运维

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装配、源码同步

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核心、队列会话、后端Profile

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核心、后端Profile、Runtime装配

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核心、HWLAB接入、Workbench唯一投影、运维监控

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 通过。