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 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 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核心](PJ2026-010201-agentrun-core.md)。
- RuntimeAssembly、AipodSpec、gitbundle 和 SecretRef 装配归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。
- Codex backend、provider profile 和 backend capability 归 [后端Profile](PJ2026-010204-backend-profile.md)。
- 旧 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核心](PJ2026-010201-agentrun-core.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |

队列会话应提供 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装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md)、[客户端](PJ2026-0104-client.md) |

队列会话应提供 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核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md) |

队列会话应保持 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核心](PJ2026-010201-agentrun-core.md)、[发布流水](PJ2026-010601-controlled-release.md) |

队列会话应保留自动 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。