pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md

PJ2026-010203 队列会话

修改历史

版本	对应 commit id	更新日期	变更说明

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

正文

PJ2026-010203 队列会话需求规格

1. 文档控制

字段	内容
编号	PJ2026-010203
短名	队列会话
层级	L2 课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0102 Agent编排
规格治理索引	规格治理

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

2. 目的和范围

2.1 目的

队列会话负责把 UniDesk Code Queue 的新任务入口收敛到 AgentRun Queue，并把用户可见任务队列、attempt、Session 输出、trace、read cursor 和 commander 聚合分层管理，避免 Queue、Session 和 Core execution trace 互相替代。

2.2 范围内

• AgentRun Queue task、attempt、priority、retry policy、judge、summary、stats、read cursor 和 commander 聚合。
• Session API/CLI 的输出、trace、命令流、debug/audit 详情、read 状态和会话控制。
• Queue task 到 Core run/command/runner job/session 的引用关系和 sessionPath 输出。
• sessions send、session continuation、unread/default/all 状态和 terminal projection。
• 自动 scheduler 的 deferred 边界、future pending scan、capacity selection、runner assignment 和 stale lease recovery 方向。

2.3 范围外

• run、command、event、runner job 和 terminal status 的执行事实归 AgentRun核心。
• RuntimeAssembly、AipodSpec、gitbundle 和 SecretRef 装配归 Runtime装配。
• Codex backend、provider profile 和 backend capability 归 后端Profile。
• 旧 UniDesk Code Queue API/UI/CLI 长期兼容层不属于本规格范围；旧数据只读归档由 UniDesk 侧单独处理。
• GitHub sink、OA sink、notification sink、Event System 或外部 integrations 表不是 Queue 首版能力。

3. 术语表

术语	定义
AgentRun Queue	AgentRun 内部任务队列基础设施，承载 task、attempt、summary、stats、read cursor 和 commander 聚合。
Queue task	用户或系统提交到 AgentRun Queue 的任务资源，可 dispatch 为 Core run/command。
attempt	Queue task 的一次执行尝试，引用 runId、commandId、runnerJobId 和 sessionId。
Session	面向用户的执行会话控制面，承载 output、trace、read、send、cancel 和 terminal projection。
sessionPath	Queue task 返回的 Session API 路径，用于读取输出和 trace。
read cursor	按 readerId 记录的已读水位，用于默认列表只显示 running 或 unread session/task。
commander	Queue 侧的聚合视图，用于展示队列状态、最新 attempt 和下一步操作摘要。
Scheduler	后续自动调度器，负责 pending scan 和 runner assignment；v0.1 第一阶段不作为发布前置。

4. 系统边界和接口

本规格把队列会话作为 AgentRun 的任务队列和用户会话控制系统看待；本章只描述输入、输出和责任边界。

边界项	内容
外部使用者	UniDesk 用户、HWLAB Agent 入口、CLI 操作者、Artificer/Aipod、AgentRun 核心和平台运维。
外部输入	Queue task JSON、dispatch body、sessionId、prompt、run base、readerId、backendProfile、resourceBundleRef、cancel/read/send 控制请求。
受控资源	Queue task、attempt、summary、stats、read cursor、Session projection、session trace/output 和 scheduler deferred 状态。
外部输出	taskId、attemptId、sessionId、sessionPath、queue stats、commander summary、unread/default/all 列表、output/trace cursor 和控制结果。
用户接口	AgentRun REST Queue/Session API、./scripts/agentrun queue ...、./scripts/agentrun sessions ...。
系统边界	队列会话负责任务队列和会话控制语义；不代理 Core trace 为 Queue output，不直接执行 backend，不决定 tenant 业务授权，不维护旧 Code Queue 兼容入口。

5. 内部分工与规格索引

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-01020301	Queue任务	本规格 6.1	task、attempt、summary、stats、read cursor 和 commander	UniDesk/HWLAB 提交入口	AgentRun Core、Session API
PJ2026-01020302	Session控制	本规格 6.2	output、trace、send、read、cancel、default/unread/all 视图	Core events、Runtime session	CLI、客户端、用户
PJ2026-01020303	分层边界	本规格 6.3	Queue、Session、Core 和 Scheduler 的职责分离	Queue任务、Session控制	发布流水、客户端
PJ2026-01020304	Scheduler边界	本规格 6.4	自动调度 deferred、future scan/assignment/recovery	Queue pending facts、capacity	Runner job、AgentRun Core

6. 原子需求

6.1 AR-QUEUE-REQ-001 Queue Task 与 Attempt

编号	短名	主责模块	关联模块
AR-QUEUE-REQ-001	Queue任务	PJ2026-01020301 Queue任务	AgentRun核心、Runtime装配

队列会话应提供 AgentRun Queue task 和 attempt 模型，使新任务能够直接进入 AgentRun Queue，并通过 dispatch 生成 Core run、command、runner job 和 Session 引用。

AgentRun Queue 直接吸收 UniDesk Code Queue 的新任务入口，不做 adapter 过渡、双写或长期兼容旧 Code Queue API/CLI/UI。旧 UniDesk Code Queue 只保留历史归档或只读查询，不再接收新任务。

6.2 AR-QUEUE-REQ-002 Session 输出与控制

编号	短名	主责模块	关联模块
AR-QUEUE-REQ-002	Session控制	PJ2026-01020302 Session控制	Runtime装配、AgentRun核心、客户端

队列会话应提供 Session API 和 CLI，使用户能够查看执行输出、trace、debug/audit 摘要，发送 follow-up，执行 read/cancel，并按 default、running、unread、terminal、idle 或 all 状态读取会话。

Queue task 详情只能返回 sessionPath 和有界摘要，不代理完整输出或 trace。输出、trace 和会话控制必须从 Session API/CLI 进入，避免 Queue 列表视图反推 Core event stream 或展开执行细节。

6.3 AR-QUEUE-REQ-003 Queue/Session/Core 分层

编号	短名	主责模块	关联模块
AR-QUEUE-REQ-003	分层边界	PJ2026-01020303 分层边界	AgentRun核心、后端Profile

队列会话应保持 Queue、Session、Core 和 Scheduler 分层：Queue 管 task/attempt/summary，Session 管输出和会话控制，Core 管 run/command/runner facts，Scheduler 未来只做 pending scan 和 runner assignment。

Queue 不维护 OA、notification、GitHub action 或外部协作 sink，不从 Session trace 反推 overview，也不把 Core event stream 暴露成 Queue output。需要执行详情时，调用方必须用 sessionId 或 runId 进入对应正式 API。

6.4 AR-QUEUE-REQ-004 Scheduler Deferred 边界

编号	短名	主责模块	关联模块
AR-QUEUE-REQ-004	Scheduler	PJ2026-01020304 Scheduler边界	AgentRun核心、发布流水

队列会话应保留自动 scheduler 的规格边界，但 v0.1 第一阶段不得因为 scheduler 未实现而阻塞最小真实闭环。

在 scheduler 启用前，CLI/manual dispatch 必须能启动真实 runner，manager durable facts、runner claim、backend turn、events 和 terminal status 必须真实可用。未来 scheduler 只能通过 manager API 和 Kubernetes runner Job 改变调度状态，不得直接写 Postgres 或直接执行 backend。