pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md

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 的核心执行语义。

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 推断。
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

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。