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。
• send session follow-up 对 node/lane、backendProfile、providerId、workspaceRef、executionPolicy 和 provider credential SecretRef 的策略解析。
• Queue task、Session、run 和 command 取消入口的用户语义、级联边界、同 session 续跑和 canceled 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。
session policy	Session follow-up 创建下一次 run/command 时使用的 backendProfile、providerId、workspaceRef、executionPolicy 和 provider credential SecretRef 策略。
sessionPath	Queue task 返回的 Session API 路径，用于读取输出和 trace。
read cursor	按 readerId 记录的已读水位，用于默认列表只显示 running 或 unread session/task。
commander	Queue 侧的聚合视图，用于展示队列状态、最新 attempt 和下一步操作摘要。
cancel scope	用户发起取消时选择的资源边界，包括 task、session、run 或 command。
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、node/lane、backendProfile、providerId、workspaceRef、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
PJ2026-01020305	取消控制	本规格 6.5	task/session/run/command 取消语义、级联关系和 canceled projection	AgentRun核心取消生命周期	CLI、客户端、commander

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 或展开执行细节。

send session/<sessionId> 的短命令形态、显式 JSON body 形态和 --aipod 形态都必须使用目标 node/lane 的 YAML 事实解析 session policy。CLI 或 API 已显式给出 node/lane 时，backendProfile、providerId、workspaceRef、executionPolicy 和 provider credential SecretRef 不得回退到全局默认 lane；未显式给出目标时，输出必须披露使用的 YAML default 来源。

explain session-policy 是 send session 的同源预检入口，必须展示与实际 follow-up 创建相同的目标 node/lane、backendProfile、providerId、workspaceRef、executionPolicy、provider credential SecretRef 和脱敏来源摘要。若解释输出与目标 lane 不一致，应视为策略解析或渲染缺陷，不得通过复制其他 lane Secret、手工补 legacy Secret 或修改 runtime namespace 绕过。

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。

6.5 AR-QUEUE-REQ-005 取消控制语义

编号	短名	主责模块	关联模块
AR-QUEUE-REQ-005	取消控制	PJ2026-01020305 取消控制	AgentRun核心、客户端、运维监控

队列会话应把用户可见取消语义表达为明确的资源 scope。cancel command/<commandId> 只取消当前 command/runner job，并保留同一个 session 可继续 send session/<sessionId>；cancel run/<runId> 取消该 run 下 active command 和 runner job，并由 Core terminalize run；cancel session/<sessionId> 取消 session 当前 active work 和 session-scoped background work；cancel task/<taskId> 取消当前 task attempt/run，并按 Queue retry/resume 语义更新 task projection。

Queue 和 Session 只能提交取消意图、展示取消阶段和投影 canceled terminal，不得从 HTTP 成功、timeout、stdout 停止、runner job 删除或 Web 轮询无新增内容推断取消完成。取消完成事实必须来自 AgentRun核心 的 durable command/run terminal、cancel epoch fencing 和 result/event 证据。

CLI、commander 和客户端默认输出应展示 cancel scope、targetRef、cascade scope、request id 或等价关联字段、当前阶段和下一步查询命令；完整审计字段通过 machine output 或详细视图获取。取消后的 follow-up 必须显式引用仍可续跑的 sessionId，不得回退到旧 Code Queue resume/steer 或通过复制历史 prompt 伪造会话连续性。