Lyon
14 KiB
PJ2026-0102 Agent编排
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|---|---|---|
| v0.3 | b5d8cee438 |
2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721 |
2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653 |
2026-06-14 | 从迁移来源 pikasTech/HWLAB#1204 迁移到 UniDesk 项目管理目录。 |
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-0102 Agent编排需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-0102 |
| 短名 | Agent编排 |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-serve-session-aggregate-authority; draft-2026-06-25-p0-session-warm-runner-contract |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-01 HWLAB 总规格 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 Agent编排 的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执行生命周期，并把运行上下文、资源装配、会话连续性和执行事实以稳定合同暴露给 HWLAB 其他模块。
2.2 范围内
- HWLAB 入口到 AgentRun run、command、runner job 的提交、短返回、轮询和终态管理。
- Web CaseRun 中 Code Agent 执行部分的 run、command、trace、subject worktree、diff 和 final response 指针。
- 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、租约、健康和硬件事实归 硬件池。
- CaseRun 评价、pass/fail、回放和训练反馈归 HarnessRL。
- Web、CLI 和 HTTP API 的用户体验归 客户端。
- 用户身份、API key、额度、账本和租户策略归 用户管理。
- 发布流水、Git mirror、source truth、Secret sync、rollout、namespace 和日志指标基础设施归 平台运维，其中 AgentRun
v0.1发布细则见 AgentRun发布Lane，源码真相见 AgentRun源码真相。 - 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 的配置边界。 |
| session execution lane | 将一个用户可见会话内连续 command 映射到同一 AgentRun run、session runner lease 或等价 warm runner channel 的执行通道。 |
4. 系统边界和接口
本规格把 Agent编排作为 HWLAB 内部的 Agent 执行子系统看待；本章只描述该子系统的输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | 客户端、HarnessRL、用户管理、硬件池、平台运维和训练任务。 |
| 外部输入 | 用户任务、CaseRun execution request、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 摘要、diff/final response 指针和 artifact/tool 摘要。 |
| 用户接口 | HWLAB Agent API、Cloud Web/CLI Agent 入口、AgentRun 资源原语、provider profile 管理入口。 |
| 系统边界 | Agent编排负责执行生命周期和资源装配正确性；不定义硬件事实、Harness 评分、用户账本、客户端布局或平台发布流程。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-010201 | AgentRun核心 | PJ2026-010201 AgentRun核心 | run、command、event、runner job、durable facts、terminal status 和 failureKind | 客户端入口、用户权限、平台运行面 | 队列会话、HWLAB接入、HarnessRL、客户端 |
| PJ2026-010202 | Runtime装配 | PJ2026-010202 Runtime装配 | BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、SecretRef、gitbundle、AipodSpec 和 runtime home | 源码同步、YAML运维、硬件资源提示 | AgentRun核心、后端Profile、HWLAB接入 |
| PJ2026-010203 | 队列会话 | PJ2026-010203 队列会话 | Queue task、attempt、Session API、read cursor、commander 和 scheduler deferred 边界 | AgentRun核心、Runtime装配 | 客户端、UniDesk Code Queue 迁移、HWLAB接入 |
| PJ2026-010204 | 后端Profile | PJ2026-010204 后端Profile | Backend adapter、Codex stdio backend、provider profile、profile 管理、failureKind 和 redaction | Runtime装配、YAML运维、provider SecretRef | AgentRun核心、HWLAB接入 |
| PJ2026-010205 | HWLAB接入 | PJ2026-010205 HWLAB接入 | 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核心 | 客户端、用户管理、发布流水 |
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装配 | 硬件池、源码同步、YAML运维、HarnessRL |
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 消费执行上下文。
Web CaseRun 使用 AgentRun 时，RuntimeAssembly 必须能说明 subject worktree、case bundle、provider profile、required skills/tools、HWPOD context 指针和可脱敏输入证明。AgentRun 可以给出 Code Agent trace、diff、final response 和 terminal/failureKind；它不判断 HWPOD operation result 是否满足 case，也不生成 CaseRun aggregate。
6.3 AGENT-L1-REQ-003 队列与会话
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AGENT-L1-REQ-003 | 队列会话 | PJ2026-010203 队列会话 | 客户端、AgentRun核心、Runtime装配 |
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 | Runtime装配、用户管理、客户端 |
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接入 | 硬件池、HarnessRL、客户端、用户管理 |
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唯一投影 要求 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。
Serve/session aggregate authority 要求职责进一步分离：AgentRun 拥有 run、command、runner job、cancel delivery、terminal report 和 execution diagnostic；HWLAB Workbench 拥有用户态 session aggregate、input/command fact、message/part、trace/timing、sealed final response 和 projection diagnostic。AgentRun 应暴露稳定 runId、commandId、event/result id、terminal status、failureKind、cancel/no-op 和 stale/blocked diagnostic，使 Workbench input/command fact 能回绑执行事实；AgentRun 不拥有 Workbench message/final/timing 显示权，也不通过旧 conversation/session 路径覆盖 Workbench read model。
Agent编排必须为 Workbench 多 turn 提供可验证的 session execution lane。若选择同一 run 多 command 模型，runner 在普通 command 完成后应继续 poll 同一 run 的后续 command，直到 idle timeout、run cancel、lease 冲突或不可恢复失败；若选择跨 run warm runner lease 或 session command channel，AgentRun 必须把 lease/channel identity、handoff、cancel fencing、idle timeout 和诊断状态作为 durable facts 暴露。每个 Workbench turn 都新建独立 run-scoped runner Job 的实现，只能作为 fresh-run diagnostic，不能满足 runner reuse、10x canary 或 120s 性能红线验收。
Web CaseRun 的 Agent 执行部分同样遵守该合同边界。CaseRun service 可以引用 AgentRun runId、commandId、traceId、terminal status、diff 和 final response，但不得通过 stdout 尾部、partial assistant、runner pod phase 或用户手工 steer 推断 CaseRun 成功。硬件动作、operation result 和 aggregate 仍由硬件池与 HarnessRL 生产，Agent编排只交付可引用的执行事实。