pikastech
24 KiB
PJ2026-010201 AgentRun核心
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010201 AgentRun核心需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010201 |
| 短名 | AgentRun核心 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0102 Agent编排 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AgentRun 核心执行面的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
AgentRun核心负责把 HWLAB Agent 任务转化为可持久查询、可调度执行、可恢复收口的 run、command、runner job、event 和 terminal status。它是 Agent编排内部的 durable execution authority，业务客户端、CLI、Queue、runner 和后端适配层都不得绕过它直接改写执行事实。
2.2 范围内
agentrun-mgr的公共 REST API、Runner 私有 API、run/command/event/result 查询和手动 runner job API。agentrun-runner的 register、claim、lease heartbeat、command poll、ack、event append 和 terminal status 上报。- Postgres durable store 中 runs、commands、events、runner jobs、sessions、backends、leases、Queue 引用和 migration ledger 的事实持久化。
- command 终态、run 终态、failureKind、result envelope、event 分页和日志/trace 脱敏边界。
- runner job identity、attempt、logPath、pod identity、stale lease recovery 和 runner replacement 的核心执行语义。
- task、run、command、session 取消请求落到 AgentRun 核心后的 command/run 级取消状态机、cancel epoch、runner abort、terminal
canceled和迟到写回 fencing。
2.3 范围外
- BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef 和 SecretRef 的装配模型归 PJ2026-010202 Runtime装配。
- Queue task、attempt、read cursor、commander 和 Session 用户控制面归 PJ2026-010203 队列会话。
- Codex stdio backend、profile 隔离和 provider profile 管理归 PJ2026-010204 后端Profile。
- HWLAB 业务任务如何映射到 AgentRun run/command 归 PJ2026-010205 HWLAB接入。
- CI/CD、版本 lane 和综合联调发布判定归 发布流水，AgentRun
v0.1专项发布细则归 AgentRun发布Lane，source truth 归 AgentRun源码真相。
3. 术语表
| 术语 | 定义 |
|---|---|
| agentrun-mgr | AgentRun 的长驻管理服务，提供 REST API、durable facts authority、runner claim 和 event/status authority。 |
| agentrun-runner | 执行单元，以 Kubernetes Job 或受控进程形态 claim run、调用 backend 并回写事件和状态。 |
| run | AgentRun 中承载一次 Agent 执行生命周期的顶层 durable resource。 |
| command | run 内的一次 turn、steer、interrupt 或 cancel 指令，具备独立状态和终态。 |
| event | 单 run 内 append-only、按 seq 单调递增的执行事实记录。 |
| terminal status | command 或 run 的权威终态，不由 partial output、stdout、transport close 或 idle timeout 推断。 |
| cancel request | 由 Queue、Session、run 或 command 控制入口提交的取消意图，必须持久化 requestId、targetRef、reason、requestedBy 和作用范围。 |
| cancel epoch | AgentRun 用于隔离取消前后写入的单调 fencing token；runner、terminal report 和 late write 必须携带或接受该 epoch 校验。 |
| canceled terminal | 取消成功后的权威终态，区别于 completed、failed、timeout 和 transport close。 |
| failureKind | AgentRun 对 schema、tenant policy、Secret、runner、backend、provider、infra 和 cancel 等失败的结构化分类。 |
| durable facts | Postgres 中可重启后查询的 run、command、event、runner、job、session、backend、lease 和 migration 事实。 |
4. 系统边界和接口
本规格把 AgentRun核心作为 Agent编排内的执行事实系统看待；本章只描述外部输入、外部输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | HWLAB Agent API、AgentRun CLI、Queue/Session 控制面、runner job、backend adapter 和平台运维。 |
| 外部输入 | run 创建请求、command payload、executionPolicy、backendProfile、workspaceRef、traceSink、runner claim、heartbeat、event 和 status 上报。 |
| 受控资源 | AgentRun REST API、durable store、runner lease、runner job record、event stream、command result 和 failureKind。 |
| 外部输出 | runId、commandId、runnerJobId、attemptId、event cursor、terminal status、result envelope、failureKind、logPath 和 redacted health/readiness。 |
| 用户接口 | agentrun-mgr REST API、AgentRun CLI 中的 runs/commands/runner 查询与调度命令。 |
| 系统边界 | AgentRun核心负责执行事实的创建、持久化、调度入口和终态收口；不负责业务授权、硬件事实、provider 协议细节、GitOps 发布或客户端展示。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01020101 | Manager API | 本规格 6.1、6.2 | run、command、event、result、runner job 和 health/readiness API authority | 客户端请求、Queue、HWLAB 接入 | Runner、CLI、HarnessRL、客户端 |
| PJ2026-01020102 | Runner执行 | 本规格 6.3 | runner register、claim、lease、poll、ack、append events 和 terminal status | Manager API、Runtime 装配、Backend Profile | Manager、HWLAB 接入、Queue 会话 |
| PJ2026-01020103 | Durable事实 | 本规格 6.4 | Postgres 表、migration ledger、事务和重启后查询 | Manager API、平台运维数据库支撑 | 全部 AgentRun 查询和恢复 |
| PJ2026-01020104 | 终态结果 | 本规格 6.5 | command/run 终态分离、result envelope、failureKind 和 event 分页 | Runner执行、Backend Profile | HWLAB 接入、客户端、HarnessRL |
| PJ2026-01020105 | 控制面恢复 | 本规格 6.6 | manager boot/background reconciler、runner job observation 和 active command 收敛 | Durable事实、Kubernetes Job/Pod | HWLAB 接入、发布Lane、运维监控 |
| PJ2026-01020106 | 终态Outbox | 本规格 6.7 | runner terminal fact 的幂等提交、重试和可恢复 artifact | Runner执行、Backend Profile | 控制面恢复、HWLAB 投影 |
| PJ2026-01020107 | 清理安全 | 本规格 6.8 | cleanup、Job TTL、runner 上限与 active runner 保护 | 控制面恢复、发布Lane | 平台运维、运行面 GC |
| PJ2026-01020108 | 取消生命周期 | 本规格 6.9 | cancel request、cascade scope、epoch fencing、runner abort 和 canceled terminal | Queue会话、Manager API、Runner执行 | 客户端、运维监控、HWLAB接入 |
5.1 控制面恢复目标架构图
flowchart LR
Submit[HWLAB / CLI submit] --> API[agentrun-mgr REST]
API --> DB[(Postgres durable ledger)]
DB --> Run[run / command / event / lease]
DB --> RJ[runner_job identity]
RJ --> K8S[Kubernetes Job / Pod]
K8S --> Runner[agentrun-runner data plane]
Runner --> Outbox[terminal outbox / retry artifact]
Outbox --> API
API --> DB
Boot[manager boot/background reconciler] --> DB
Boot --> K8S
Boot --> Obs[observation facts]
Obs --> DB
DB --> Result[result / diagnosis API]
AgentRun核心的目标状态是控制面无状态、runner 数据面可独立运行、Postgres durable ledger 是执行事实 authority。agentrun-mgr 重启或滚动后只能从 DB active facts、runner job identity 和 Kubernetes Job/Pod observation 重新接管控制权；进程内内存、stdout tail、Kubernetes Job completed、人工 resubmit 或重新创建 runner job 都不能替代恢复控制权。
5.2 runner 滚动数据流图
flowchart TD
CMD[durable command] --> Claim[runner claim + lease]
Claim --> Job[runner job record + Kubernetes Job]
Job --> Work[backend turn execution]
Work --> Events[best-effort progress events]
Work --> Terminal[command terminal fact]
Events --> Store[(durable ledger)]
Terminal --> Outbox[durable terminal outbox / retry]
Outbox --> Store
Store --> Reconcile[manager reconciler]
Reconcile --> Result[result / liveness / diagnosis]
progress event 可以 best-effort；command terminal、run terminal、final assistant response、failureKind 和可恢复 artifact 必须通过 durable commit 或可被 reconciler 找回的 outbox/artifact 进入 ledger。runner 不得因为 manager HTTP 短暂不可用而静默退出并丢失 terminal fact。
5.3 manager rolling 关键时序图
sequenceDiagram
participant M1 as manager before rolling
participant DB as durable ledger
participant K8S as Kubernetes Job/Pod
participant R as runner
participant M2 as manager after rolling
M1->>DB: create run/command/runner_job
M1->>K8S: create runner Job
R->>M1: claim/heartbeat/events
M1--xR: rolling / temporarily unavailable
R->>R: continue backend work
R->>DB: terminal outbox artifact is durable or retryable
M2->>DB: scan active command + runner_job + lease
M2->>K8S: observe Job/Pod phase and metadata
M2->>DB: update observation / terminal report state
R->>M2: retry terminal report
M2->>DB: idempotent terminal commit
恢复时序要求 manager rolling 只造成短暂控制面不可用，不造成 runner job 删除、run 重建、command resubmit、terminal fact 丢失或 read-side 推断 completed。
5.4 rolling failure matrix
| 场景 | 权威输入 | 正确收敛 | 禁止替代 |
|---|---|---|---|
| manager down during claim | command pending/claimed、lease、runnerJob、Kubernetes Job phase | reconciler 重新观察 claim/lease/job 并恢复 runner 控制或写 blocker | 按 stale lease 直接判 runner lost |
| manager down during backend turn | heartbeat、events、Job/Pod running、runner job record | 保留 active，继续观察，暴露 temporary diagnostic | 删除 Job 或人工 resubmit |
| manager down during event append | event cursor、runner retry、Job/Pod running | progress 可降级，terminal 仍需 durable | 用 stdout tail 当正式 event stream |
| manager down during terminal report | terminal outbox/artifact、commandId、attemptId、runnerId | 幂等 terminal commit 或不可恢复 blocker | 静默保持 running |
| Job completed before terminal commit | Job/Pod phase、outbox/artifact、logs retention | reconciler 恢复 terminal fact 或写不可恢复 blocker | 把 Job completed 单独当 command completed |
| cleanup/TTL race | DB terminal state、runnerJob observation、TTL config | terminal durable 后再清理可恢复证据 | 只按 Pod 列表或年龄清理 active runner |
5.5 cancel lifecycle 关键时序图
sequenceDiagram
participant C as Queue / Session / CLI
participant M as agentrun-mgr authority
participant DB as durable ledger
participant R as runner
participant B as backend/tool/process
C->>M: cancel targetRef + reason
M->>DB: persist cancelRequest + next cancel epoch
M->>R: deliver cancel epoch for active command/run
R->>B: abort stream/tool/process
R->>DB: terminal report canceled with epoch
M->>DB: seal command/run canceled
R-->>DB: late write with old epoch
DB-->>R: reject fenced write
cancel lifecycle 必须把“接受取消请求”和“运行器已经中止”分成可观测阶段。用户或上游只能把 canceled terminal 作为取消完成事实；cancel requested、HTTP 连接关闭、runner pod 消失、timeout/watchdog 或缺少新输出都不能单独代表取消完成。
6. 原子需求
6.1 AR-CORE-REQ-001 Durable Resource 模型
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-001 | Durable Resource | PJ2026-01020101 Manager API | 队列会话、HWLAB接入、AgentRun发布Lane |
AgentRun核心应以 run、command、event、runner job、session projection、backend 和 lease 等 durable resource 表达 Agent 执行事实，使创建、查询、轮询、取消、恢复和审计都通过同一资源模型完成。
run 和 command 必须短返回并可后续轮询。业务客户端不得依赖长同步 turn、临时进程 stdout 或 Kubernetes Job 名称推断执行事实；这些运行面信息只能作为 durable resource 的 redacted identity 或状态摘要出现。
6.2 AR-CORE-REQ-002 Manager Authority
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-002 | Manager Authority | PJ2026-01020101 Manager API | Runtime装配、后端Profile、发布流水 |
agentrun-mgr 应作为 AgentRun 公共 API、Runner 私有 API、durable facts、tenant policy boundary、runner claim、event append 和 terminal status 的唯一 authority。
Manager 只执行通用 schema、allowlist、idempotency、secret scope 和 executionPolicy 范围检查，不内建 HWLAB 用户角色、HWPOD 授权或 UniDesk 业务策略。业务授权由调用方完成后再委托 AgentRun，AgentRun 保存可审计字段和失败事实。
Manager 公共 API 应采用短连接 JSON resource 形态表达 runs、commands、events、results、sessions、backends 和 health。长时间模型工作通过资源状态和分页 events 查询，不通过 SSE、WebSocket、长同步 HTTP 或 runner stdout 作为唯一完成信号。CLI 和业务客户端应调用同一 REST resource API；debug 命令可以暴露更小切片，但不得维护平行 mock-only 路径。
6.3 AR-CORE-REQ-003 Runner Claim 与回写
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-003 | Runner回写 | PJ2026-01020102 Runner执行 | Runtime装配、后端Profile |
agentrun-runner 应先 register、claim run 并取得 lease，再 poll command、ack command、调用 backend、append events、续租 heartbeat 并上报 command terminal status。
Runner 不得直连 Postgres，不得从本地文件、临时参数或 prompt 伪造正式 command。普通 command 完成后 runner 应在 idle timeout 内继续 poll 同一 run 的后续 command；只有 run cancel、lease 冲突、idle timeout 或 runner 级不可恢复失败才结束 runner loop。
6.4 AR-CORE-REQ-004 Postgres Durable Store
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-004 | Durable Store | PJ2026-01020103 Durable事实 | 发布流水、Runtime装配 |
AgentRun核心应使用 Postgres 作为 v0.1 唯一 durable store，保存 runs、commands、events、runners、runner jobs、sessions、backends、leases、Queue facts 和 migration ledger。
file、sqlite、JSONL、内存对象或 Pod 本地目录只能用于自测试或临时诊断，不能成为运行面事实来源。Manager readiness 必须能说明数据库 reachable、migration ready、adapter 类型和 redacted DSN 状态；缺 migration 或数据库不可用时应 fail fast。
6.5 AR-CORE-REQ-005 终态与结果语义
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-005 | 终态结果 | PJ2026-01020104 终态结果 | HWLAB接入、后端Profile、客户端 |
AgentRun核心应分离 command terminal 与 run terminal，并以 result envelope、event cursor、terminal status 和 failureKind 提供可判定的执行结果。
partial assistant 文本、stdout 存在、transport close、idle timeout 或日志尾部都不能单独升级为 completed。成功和失败都必须能通过 command record 与 command-scoped events 查询；run 级终态只用于 run cancel、runner 级不可恢复失败或明确 run terminal。
6.6 AR-CORE-REQ-006 控制面恢复 Reconciler
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-006 | 控制面恢复 | PJ2026-01020105 控制面恢复 | AgentRun发布Lane、运维监控、HWLAB接入 |
AgentRun核心应提供 manager boot/background reconciler，从 Postgres active run/command/runnerJob/lease facts 扫描需要恢复控制的执行对象，并查询 Kubernetes Job/Pod observation 写回 durable observation facts。reconciler 至少应表达 runner job phase、lastK8sObservedAt、terminalReportState、lease health、recoverable blocker 和不可恢复 blocker，字段命名可等价但职责不得省略。
stale lease 不能单独推断 runner lost。runner lost、still running、completed pending terminal report、terminal committed 和 unrecoverable blocker 必须由 heartbeat、Kubernetes phase、runner job identity、terminal report state 和受控时间窗口共同判定，并由 AgentRun 写侧收敛。HWLAB、Web、CLI、result renderer 和 Workbench GET 只能消费这些 durable facts 和 diagnostics。
runner 启动和 backend 执行故障必须由 manager/reconciler 统一归类并写入 durable event ledger。故障事件至少包含以下字段：
failureDomain=upstream|infrastructure、component、code和脱敏后的summary；retryable、attempt、maxAttempts、backoffMs和nextRetryAt；firstObservedAt、observedAt、runId、commandId、runnerJobId和traceId。
有限重试必须形成 failureObserved、retryScheduled、retryStarted、retryRecovered 和 retryExhausted 等可回放阶段，字段命名可等价但语义不得合并。manager/reconciler 是执行生命周期和重试状态的唯一写侧；Kubernetes kubelet 或 backend adapter 可以执行具体恢复动作，但不得建立第二套重试计数、终态或用户可见状态。
重试策略属于核心执行配置，必须由 owning YAML 声明基础退让、倍数、最大退让、最大次数或总截止时间以及 jitter。连接拒绝、临时 DNS、超时和上游 5xx 等瞬时故障可以指数退让；镜像不存在、鉴权拒绝、非法镜像名和缺失必需 Secret 等确定性故障必须立即形成不可重试终态。重试耗尽必须在策略窗口内结束 command/run，禁止继续依赖通用 retention 或 stale GC 让用户长时间停留在无解释的 running 状态。
6.6.1 L1 native manager
AgentRun 必须提供不依赖 CI/CD、GitOps rollout 或集群 manager Deployment 的 L1 native manager 生命周期。
启动、停止、重启、状态和日志统一由 UniDesk 受控 CLI 管理，并从 config/agentrun.yaml 解析固定 workspace、端口、状态目录、公开 HTTPS 入口、Secret sourceRef、Kafka topic 和 runner 装配参数。
L1 manager 必须使用独立 store 和独立 runner job 前缀，禁止与 development 或 release 集群 manager 共用 durable queue、lease 或 reconciler 写侧。 L1 可以复用既有 Kubernetes Job runner 执行模型和 Kafka event topic，但不得引入 host-native runner、第二套终态或第二套用户可见事件路径。 Workbench L1 必须直连 AgentRun L1；AgentRun L1 的启动和基础健康不得依赖 PaC、镜像发布或集群 manager rollout。
L1 使用内存 store 时只允许作为显式 native development 模式，并且仍必须启用 Kafka outbox，保证 PostgreSQL/outbox -> Kafka 在开发态对应为 memory/outbox -> Kafka，前端继续只消费 Kafka 重放与纯 SSE。
runner 回调 manager 必须使用 owning YAML 声明且 Pod 可达的固定公开地址，不能使用 127.0.0.1。
固定 HTTPS 用户入口由共享 public-edge owning YAML 聚合；其 reconcile 未完成时只能形成非阻塞 warning，不能阻塞 L1 通过固定公网 IP 和 port 完成业务回归。
6.7 AR-CORE-REQ-007 runner terminal durable outbox
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-007 | 终态Outbox | PJ2026-01020106 终态Outbox | 后端Profile、HWLAB接入、Workbench实时权威 |
runner 对 command terminal、run terminal、final assistant response、failureKind、threadId/turnId 和 terminal artifact 摘要必须使用 durable outbox、retry-until-ack 或等价可恢复提交协议。manager HTTP 短暂不可用时，runner 可以延迟上报，但不能把 terminal fact 只保留在进程内内存或易丢 stdout 中。
terminal 上报必须幂等。同一 runId + commandId + attemptId + runnerId 或等价稳定键重复上报时，应返回既有 terminal commit 或结构化冲突，不得创建重复 terminal event、重复 final response 或覆盖已 sealed 结果。若 runner 已退出且 terminal fact 无法从 outbox/artifact/Job logs 恢复，manager reconciler 必须写入明确不可恢复 blocker，不能静默停留 running。
6.8 AR-CORE-REQ-008 cleanup/TTL/runner 上限安全
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-008 | 清理安全 | PJ2026-01020107 清理安全 | AgentRun发布Lane、YAML运维、运维监控 |
AgentRun cleanup、Job TTL 和 runner 上限治理必须以 DB active facts 与 Kubernetes observation 双确认作为判断基础。默认 cleanup 不得杀 active runner；确需强制终止 active runner 时必须使用显式 force 语义，并写入原因、操作者、对象和 observed facts。
Job TTL 和日志/termination metadata 保留窗口不得早于 terminal facts durable commit 所需的最低恢复窗口。runner 上限治理应优先清理 idle、terminal、expired 或不可恢复对象；不得只根据 Pod 列表、Job age、进程内计数或旧 lease 单字段清理 runner。
6.9 AR-CORE-REQ-009 Cancel lifecycle 与 fencing
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| AR-CORE-REQ-009 | 取消生命周期 | PJ2026-01020108 取消生命周期 | 队列会话、YAML运维、运维监控 |
AgentRun核心应提供 task/run/command/session 控制入口落到核心执行面后的统一取消生命周期。Manager 接受取消请求时必须持久化 cancel request、targetRef、cascade scope、reason、requestedBy、requestId 和 cancel epoch；重复取消同一目标应幂等返回既有或更高 epoch 的取消事实。
取消必须通过 runner 可执行的 abort 信号兑现。runner 收到 cancel epoch 后应中止 provider stream、tool call、后台任务和子进程，并用 grace kill 与强制 kill 或等价机制完成资源释放；中止结果必须以 command/run terminal canceled、failureKind 或 cancellation classification 写回 durable store。partial output、transport close、idle timeout、missing terminal watchdog 或 runner pod 消失不得冒充 completed 或 canceled。
Manager 和 durable store 必须用 cancel epoch 对迟到写回做 fencing。取消请求后的旧 epoch event、terminal report、result envelope 或 runner heartbeat 不得覆盖 sealed canceled terminal；被拒绝的迟到写回应产生可查询的 low-noise event、diagnostic 或 span attribute，使 CLI 能判断 cancel 在 accepted、delivered、aborting、terminalized、fenced 或 late-write-rejected 哪个阶段。