pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md

# PJ2026-0102 Agent编排

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#1204 迁移到 UniDesk 项目管理目录。 |

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

## 正文

## PJ2026-0102 Agent编排需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-0102 |
| 短名 | Agent编排 |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 Agent编排 的稳定使命、范围、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执行生命周期，并把运行上下文、资源装配、会话连续性和执行事实以稳定合同暴露给 HWLAB 其他模块。

### 2.2 范围内

- HWLAB 入口到 AgentRun run、command、runner job 的提交、短返回、轮询和终态管理。
- Queue task、run、command、runner job、session、thread、conversation、cancel、timeout、恢复和 read cursor 语义。
- RuntimeAssembly 装配，包括 BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、gitbundle、promptRefs、skills、tools、workspaceFiles、SecretRef、provider profile 和模型配置。
- Backend adapter、Codex stdio backend、provider profile、profile 管理和 profile 隔离。
- workspace 物化、source commit、bundle 摘要、运行输入证明和下游可消费的执行事实指针。
- HWLAB 与 AgentRun 的职责边界、错误语义消费和跨模块交接。

### 2.3 范围外

- HWPOD 资源身份、inventory、租约、健康和硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。
- CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- Web、CLI 和 HTTP API 的用户体验归 [客户端](PJ2026-0104-client.md)。
- 用户身份、API key、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。
- 发布流水、Git mirror、source truth、Secret sync、rollout、namespace 和日志指标基础设施归 [平台运维](PJ2026-0106-platform-ops.md)，其中 AgentRun `v0.1` 发布细则见 [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)，源码真相见 [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)。
- AgentRun 仓库中的实现、代码组织和运行面部署操作不替代本文档中的需求规格；仓库本地 SPEC 只保留到 OA 规格的交叉引用。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| run | AgentRun 中承载一次 Agent 执行生命周期的顶层资源。 |
| command | run 内的一次用户或系统指令，具备独立终态和结果语义。 |
| runner job | 实际执行 Agent command 的运行单元。 |
| Queue task | AgentRun Queue 中的任务资源，可被 dispatch 为 run/command/runner job。 |
| SessionRef | 指向可续跑 Agent session/thread 的引用。 |
| RuntimeAssembly | HWLAB 为 runner 准备镜像、profile、资源包、workspace、工具、Secret 和执行参数的装配结果。 |
| ResourceBundleRef | 指向 gitbundle、工具、prompt、skill 和 workspaceFiles 的资源装配引用。 |
| Backend Profile | AgentRun 中选择具体 Codex-compatible provider/profile 的配置边界。 |

## 4. 系统边界和接口

本规格把 Agent编排作为 HWLAB 内部的 Agent 执行子系统看待；本章只描述该子系统的输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 客户端、HarnessRL、用户管理、硬件池、平台运维和训练任务。 |
| 外部输入 | 用户任务、conversation、session/thread、project/workspace/ref、HWPOD hint 或分配结果、provider profile、ResourceBundleRef、prompt、skills、tools 和 SecretRef。 |
| 受控资源 | HWLAB Agent task、AgentRun run/command/runner job、session、RuntimeAssembly、workspace materialization 和执行事实指针。 |
| 外部输出 | runId、commandId、runnerJobId、sessionId、trace pointer、terminal status、liveness、failure kind、materialized commit 摘要和 artifact/tool 摘要。 |
| 用户接口 | HWLAB Agent API、Cloud Web/CLI Agent 入口、AgentRun 资源原语、provider profile 管理入口。 |
| 系统边界 | Agent编排负责执行生命周期和资源装配正确性；不定义硬件事实、Harness 评分、用户账本、客户端布局或平台发布流程。 |

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

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-010201 | AgentRun核心 | [PJ2026-010201 AgentRun核心](PJ2026-010201-agentrun-core.md) | run、command、event、runner job、durable facts、terminal status 和 failureKind | 客户端入口、用户权限、平台运行面 | 队列会话、HWLAB接入、HarnessRL、客户端 |
| PJ2026-010202 | Runtime装配 | [PJ2026-010202 Runtime装配](PJ2026-010202-runtime-assembly.md) | BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、SecretRef、gitbundle、AipodSpec 和 runtime home | [源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、硬件资源提示 | AgentRun核心、后端Profile、HWLAB接入 |
| PJ2026-010203 | 队列会话 | [PJ2026-010203 队列会话](PJ2026-010203-queue-session.md) | Queue task、attempt、Session API、read cursor、commander 和 scheduler deferred 边界 | AgentRun核心、Runtime装配 | 客户端、UniDesk Code Queue 迁移、HWLAB接入 |
| PJ2026-010204 | 后端Profile | [PJ2026-010204 后端Profile](PJ2026-010204-backend-profile.md) | Backend adapter、Codex stdio backend、provider profile、profile 管理、failureKind 和 redaction | Runtime装配、YAML运维、provider SecretRef | AgentRun核心、HWLAB接入 |
| PJ2026-010205 | HWLAB接入 | [PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md) | HWLAB dispatcher 到 AgentRun run/command/runner job 的映射、手动调度和结果转换 | 客户端、用户管理、硬件池、AgentRun核心、Runtime装配 | HWLAB Agent API、HarnessRL、客户端 |

## 6. 原子需求

### 6.1 AGENT-L1-REQ-001 AgentRun 执行核心

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-001 | 执行核心 | [PJ2026-010201 AgentRun核心](PJ2026-010201-agentrun-core.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[发布流水](PJ2026-010601-controlled-release.md) |

Agent编排应通过 AgentRun durable resource 模型创建和跟踪 Agent 执行，使 run、command 和 runner job 能短返回、可轮询、可取消、可超时收口并进入明确终态。

该能力定义任务从 HWLAB 入口进入执行面后的生命周期事实。客户端展示生命周期，用户管理提供提交前后的权限与额度约束，平台运维提供运行支撑；这些模块不重写 run/command/runner job 的执行事实。

### 6.2 AGENT-L1-REQ-002 Runtime 装配

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-002 | Runtime装配 | [PJ2026-010202 Runtime装配](PJ2026-010202-runtime-assembly.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

Agent编排应按 RuntimeAssembly 装配 BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、workspace、tools、skills、promptRefs、provider profile 和 SecretRef。

资源装配必须能说明 runner 实际使用了哪个 repo/ref、actual commit、bundle、profile、session 和工具输入。硬件池提供 HWPOD hint 或分配结果，平台运维提供 Git mirror、Secret 和运行面支撑，HarnessRL 消费执行上下文。

### 6.3 AGENT-L1-REQ-003 队列与会话

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-003 | 队列会话 | [PJ2026-010203 队列会话](PJ2026-010203-queue-session.md) | [客户端](PJ2026-0104-client.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |

Agent编排应提供 Queue task、attempt、Session API、read cursor、commander 和 session send 能力，使用户任务可以进入队列、派发到 AgentRun 执行，并在受控会话中读取输出、trace、follow-up 和终态。

Queue 只管理 task、attempt、summary 和 Session 引用，不代理完整输出或 trace；Session 负责输出、trace、read、cancel 和 send。会话连续性不得通过拼接历史 prompt 或伪造 resume 实现，无法续接时必须给出明确失败事实。

### 6.4 AGENT-L1-REQ-004 Backend Profile

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-004 | Backend Profile | [PJ2026-010204 后端Profile](PJ2026-010204-backend-profile.md) | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[用户管理](PJ2026-0105-user-management.md)、[客户端](PJ2026-0104-client.md) |

Agent编排应提供 backend adapter、Codex stdio backend、provider profile 管理、profile 隔离、failureKind 和 redaction 能力，使不同 Codex-compatible provider 能共享同一执行合同并保持凭据、模型和 runtime home 隔离。

Backend Profile 不承担 HWLAB 用户鉴权，不保存 Secret value，不因某个 profile 缺失或失败 fallback 到另一个 profile。HWLAB 后端完成自身鉴权后可以委托 AgentRun 管理 profile Secret/config 和 canary validation。

### 6.5 AGENT-L1-REQ-005 HWLAB 与 AgentRun 合同边界

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AGENT-L1-REQ-005 | HWLAB接入 | [PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) |

Agent编排应原样消费 AgentRun 的 run、command、runner job、event、terminal status、liveness 和 failure kind 合同，并把这些事实映射为 HWLAB 可消费的执行语义。

HWLAB 不应在客户端、adapter 或 prompt 中推断或补造 AgentRun 没有发出的事实。AgentRun 已正确输出时，HWLAB 负责消费和业务映射；AgentRun 合同缺失或行为错误时，应回到 AgentRun 实现与对应 OA 规格修复。

[PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 要求 Agent编排只把 AgentRun run、command、event、terminal status、failureKind 和 result envelope 交给 HWLAB接入的 projection writer/finalizer。Agent编排不得让 Web、CLI、Workbench GET、trace polling 或 legacy conversation path 分别读取 AgentRun 并各自推断 session running、assistant final response、turn terminal 或 trace terminal；同一 AgentRun 事实只能形成一份 HWLAB Workbench durable projection。