pikasTech-agentrun/docs/reference/spec-v01-queue.md

v0.1 AgentRun Queue 规格

本文定义 AgentRun Queue 直接吸收 UniDesk Code Queue 的长期规格。AgentRun Queue 是 AgentRun 内部任务队列基础设施，不是 UniDesk Code Queue 的适配层、代理层或兼容层。

核心决策

• 直接吸收 UniDesk Code Queue 的队列产品能力，不做 adapter 过渡、不双写、不长期兼容旧 Code Queue API、CLI 或 UI。
• 新任务只写入 AgentRun Queue；旧 UniDesk Code Queue 停止接收新任务，历史数据不迁移到 AgentRun，只在 UniDesk 侧保留归档或只读查询。
• 第一版只做 RESTful API、CLI 和轻量轮询，不做 Event System、OA Event Flow、OA sink、GitHub sink、notification sink 或 integrations 表。
• Queue 和 Session 分层：Queue 查询返回 sessionPath；输出、trace、debug 和会话控制统一转到 Session API/CLI。
• Queue 列表、统计、已读状态和 commander 视图必须直接查询 Queue summary/stats/read 模型，不从 Core execution trace 或 Session trace 反推。
• 废弃 MiniMax 和 OpenCode 支持。第一版只保留 Codex/Codex-compatible backend profile，例如现有 codex 与 deepseek profile。
• 不吸收 UniDesk 环境提示。执行上下文必须显式来自 workspace/resource/profile/tool/SecretRef 等 AgentRun 合同，不能继承旧 Code Queue 的隐式 env hint。

职责边界

层	负责	不负责
AgentRun Queue	task、queue/lane、attempt、priority、retry policy、judge、task summary、attempt summary、queue stats、read cursor、commander 聚合	输出、trace、session 详情、OA、notification、GitHub action、旧 Code Queue 兼容
AgentRun Session	execution session、输出、trace、命令流、debug/audit 详情、会话控制	queue 列表、queue 统计、read cursor、commander 聚合
AgentRun Core	run、command、runner job、lease、terminal status、backend 执行事实	业务队列产品语义、queue overview、外部协作 sink
AgentRun Scheduler	pending task/attempt 扫描、capacity、runner assignment、backoff、stale lease recovery	直接执行 backend、维护旧 UniDesk scheduler、决定 tenant 业务授权
UniDesk Legacy Code Queue	旧数据只读归档和停用期排障	新任务入口、长期兼容层、执行 authority

Queue 可以保存 attempt 与 Core run/command/runner job 的引用，但 Queue 不直接暴露 Core trace。需要看输出或 trace 时，调用方必须从 Queue 返回的 sessionPath 进入 Session API。

RESTful API

第一版 Queue 公共 API 只使用短 HTTP JSON 请求和轻量轮询：

POST /api/v1/queue/tasks
GET  /api/v1/queue/tasks?queue=<queue>&state=<state>&cursor=<cursor>&limit=<limit>&updatedAfter=<seq>
GET  /api/v1/queue/tasks/:taskId
POST /api/v1/queue/tasks/:taskId/cancel
POST /api/v1/queue/tasks/:taskId/read
GET  /api/v1/queue/stats?queue=<queue>
GET  /api/v1/queue/commander?queue=<queue>

Session 公共 API 承接输出、trace 和会话控制：

GET  /api/v1/sessions/:sessionId
GET  /api/v1/sessions/:sessionId/output?cursor=<cursor>&limit=<limit>
GET  /api/v1/sessions/:sessionId/trace?cursor=<cursor>&limit=<limit>
POST /api/v1/sessions/:sessionId/control

Queue task 详情必须返回 session 引用，而不是代理输出或 trace：

{
  "taskId": "qt_123",
  "state": "running",
  "summary": "正在修改队列规格",
  "version": 42,
  "latestAttempt": {
    "attemptId": "qa_456",
    "state": "running",
    "runId": "run_789",
    "commandId": "cmd_001",
    "sessionId": "sess_abc",
    "sessionPath": "/api/v1/sessions/sess_abc"
  }
}

version、changeSeq、updatedAt 或 cursor 是 Queue 自身的轮询水位，不是 Event System。它只服务于 RESTful 增量查询和 CLI 轮询。

CLI 命令族

AgentRun CLI 必须提供 Queue 和 Session 两组命令。Queue 命令只操作队列资源：

./scripts/agentrun queue submit --json-file <task.json>
./scripts/agentrun queue list [--queue <queue>] [--state <state>] [--cursor <cursor>] [--limit <limit>]
./scripts/agentrun queue show <taskId>
./scripts/agentrun queue stats [--queue <queue>]
./scripts/agentrun queue commander [--queue <queue>]
./scripts/agentrun queue read <taskId>
./scripts/agentrun queue cancel <taskId> [--reason <text>]

Session 命令负责输出、trace 和会话控制：

./scripts/agentrun sessions show <sessionId|sessionPath>
./scripts/agentrun sessions output <sessionId|sessionPath> [--cursor <cursor>] [--limit <limit>]
./scripts/agentrun sessions trace <sessionId|sessionPath> [--cursor <cursor>] [--limit <limit>]
./scripts/agentrun sessions control <sessionId|sessionPath> --json-file <control.json>

不得新增 queue output、queue trace 或 queue session/* 这类子路径代理。queue show 最多打印 sessionPath 和下一步 sessions ... 命令。

数据模型方向

Queue 首版新增或扩展的稳定表方向：

• agentrun_queue_tasks：任务 identity、tenant/project、queue/lane、title、priority、state、backendProfile、workspace/resource 引用、创建者、version 和 timestamps。
• agentrun_queue_attempts：attempt identity、taskId、runId、commandId、runnerJobId、sessionId、state、failureKind、retry index 和 timestamps。
• agentrun_task_summaries：task 级摘要、当前状态、最新 attempt、最新 sessionPath、最后用户可见摘要和统计字段。
• agentrun_attempt_summaries：attempt 级摘要、terminalStatus、failureKind、runner identity、耗时和有界输出摘要引用。
• agentrun_queue_stats：按 queue/lane/state/backendProfile 聚合的轻量统计，可由 Queue 写入或按 Queue 表查询生成。
• agentrun_queue_read_cursors：按 user/agent/client 和 queue/task 记录已读水位。
• agentrun_queue_judge_runs：judge 请求、结果、failureKind、重试建议和与 attempt 的关联。
• agentrun_task_references：issue、PR、repo、commit、文档或外部上下文的显式引用，不保存 UniDesk 隐式环境提示。

第一版不得新增 integrations、notification_deliveries、observability_exports、oa_events、oa_sinks 或类似外部动作表。GitHub、notification、OA、外部审计和协作动作如果后续需要，必须作为独立 connector/sink 规格追加，不能混入 Queue 首版数据模型。

Code Queue 吸收映射

旧 Code Queue 能力	AgentRun 目标	吸收方式	不保留内容
task 记录	agentrun_queue_tasks	直接建模为 Queue task	旧 API 字段兼容
queueId、move、merge	queue/lane 字段和 Queue API	保留队列归类与移动语义	旧 UI 操作合同
attempt	agentrun_queue_attempts + Core run/command/runner job	attempt 引用真实执行资源	旧 attempt 输出结构
processQueue / runTask	AgentRun Scheduler	由 Scheduler 扫描 pending task/attempt 并创建 runner job	UniDesk Code Queue scheduler
runCodexTurn	Codex app-server stdio backend	复用协议和 failure 分类经验	环境专用路径和明文凭据
MiniMax/OpenCode 执行	无	废弃	fallback、兼容配置、judge backend
activeRuns / active slot	Scheduler capacity 和 lease	合并进 AgentRun 调度/lease 模型	旧内存状态 authority
judge	agentrun_queue_judge_runs	使用 Codex-compatible judge profile 或规则 judge	MiniMax judge
prompt history / steer / resume / cancel	Queue audit + Session/Core control	Queue 记录任务级控制意图，执行细节走 Session/Core	直接向旧 runner 写进程状态
output / trace view	Session API	Queue 只返回 sessionPath 和 summary	Queue 代理输出或 trace
readAt	agentrun_queue_read_cursors	保留已读水位	从 trace 推导已读
commander	agentrun_queue_stats + agentrun_task_summaries	直接从 Queue summary/stats 聚合	从 Core trace 反推 commander
task references	agentrun_task_references	保留显式引用	隐式环境提示
GitHub / notification / OA	deferred connector/sink	首版不做	首版 integrations 表
旧 Postgres task 表	UniDesk archive	不迁移历史数据	作为 AgentRun source of truth
UniDesk Web UI	deferred client surface	首版不做	Web/Playwright 验收

实施顺序

阶段	目标	验收重点
Q0	固化 Queue SPEC 和 schema migration 计划	文档与旧 Code Queue 兼容口径不冲突。
Q1	Queue RESTful API 和 CLI 骨架	submit/list/show/stats/read/cancel 全部短返回 JSON，不触发真实执行也能保存 task。
Q2	attempt 到 Core run/command/runner job 的真实闭环	Queue submit 产生 attempt，Scheduler 或受控 dispatch 创建真实 runner job。
Q3	Session 引用边界	queue show 返回 sessionPath，输出和 trace 只能通过 sessions ... 查询。
Q4	summary/stats/read/commander	Queue overview、stats、read cursor、commander 全部直接查 Queue 模型。
Q5	retry/judge/cancel	retry/backoff、judge、cancel 与 attempt/session/core 状态一致。
Q6	冻结旧 UniDesk Code Queue 新任务入口	新任务只进入 AgentRun Queue；旧系统只归档或只读。

验收规格

单元测试和组件自测试可以使用 mock、fake backend 或内存 store。最终 CLI 交互验收必须在真实 AgentRun runtime 上手动执行，不使用 mock，不写自动交互脚本，不做 Web 或 Playwright 验收。

首版通过标准：

• queue submit/list/show/stats/read/cancel 均通过正式 CLI 和 RESTful API 返回非空 JSON。
• 至少一个真实 task 通过 Queue attempt 触发真实 Codex/Codex-compatible backend，并进入 terminal 状态。
• queue show 返回 sessionPath；输出、trace 和会话控制只能通过 Session API/CLI 完成。
• Queue overview、stats、read cursor 和 commander 视图来自 Queue summary/stats/read 表或等价 Queue 查询，不读取 Core trace 反推。
• 不存在 OA/Event/OA sink/GitHub/notification/integrations 首版表和首版必需流程。
• MiniMax/OpenCode 相关入口、配置、fallback 和 judge 路线不作为 AgentRun Queue 首版能力。
• 旧 UniDesk Code Queue 不接收新任务；历史数据不迁移到 AgentRun。
• CLI、API、日志、summary、trace 和 Session 输出不泄露 Secret value、token、DSN password 或 URL credential。

规格的实现情况

规格项	状态	说明
AgentRun Queue 直接吸收规格	已定义	本文为 Queue 吸收 Code Queue 的首版权威规格。
Queue RESTful API	已实现/Q1	已通过 agentrun-mgr 暴露 submit/list/show/stats/read/cancel/commander，使用短请求和 Queue version/cursor 轻量轮询；Q2 再接入 attempt 与真实执行。
Queue CLI	已实现/Q1	已加入 queue submit/list/show/stats/commander/read/cancel；Queue 命令只返回 task summary、stats、read cursor 和 sessionPath。
Session API/CLI	待实现	Queue 只返回 sessionPath；Session 层承接输出、trace 和控制。
Scheduler 接入	待实现	旧 Code Queue scheduler 不保留；AgentRun Scheduler 是唯一调度方向。
OA/Event/integrations	不采用	首版不做，后续如需外部 connector/sink 必须单独立规格。
历史迁移	不采用	旧 Code Queue 历史数据不迁移到 AgentRun。