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 与 minimax-m3 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
POST /api/v1/queue/tasks/:taskId/dispatch
POST /api/v1/queue/tasks/:taskId/refresh
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?state=default&readerId=<reader>&backendProfile=<profile>&cursor=<cursor>&limit=<limit>
GET  /api/v1/sessions/:sessionId/output?afterSeq=<seq>&limit=<limit>
GET  /api/v1/sessions/:sessionId/trace?afterSeq=<seq>&limit=<limit>
POST /api/v1/sessions/:sessionId/read
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>]
./scripts/agentrun queue dispatch <taskId> [--json-file <dispatch.json>]
./scripts/agentrun queue refresh <taskId>

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

./scripts/agentrun sessions ps [--state default|running|unread|terminal|idle|all] [--profile codex|deepseek|minimax-m3|M3] [--reader-id <reader>]
./scripts/agentrun sessions show <sessionId> [--reader-id <reader>]
./scripts/agentrun sessions turn [sessionId] --json-file <run-base.json> --prompt-file <file> [--profile codex|deepseek|minimax-m3|M3]
./scripts/agentrun sessions steer <sessionId> --prompt-file <file>
./scripts/agentrun sessions cancel <sessionId> [--reason <text>]
./scripts/agentrun sessions output <sessionId> [--after-seq <seq>] [--limit <limit>]
./scripts/agentrun sessions trace <sessionId> [--after-seq <seq>] [--limit <limit>]
./scripts/agentrun sessions read <sessionId> [--reader-id <reader>]

不得新增 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 后通过受控 `queue dispatch` 产生 attempt，并创建真实 Core run/command/runner job；`queue refresh` 从 Core run/command 终态回写 Queue attempt；自动 Scheduler 仍 deferred。
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 Q2 的真实手动验收必须覆盖以下稳定边界：

queue submit 只创建 Queue task，不触发自动 scheduler。
queue dispatch 是受控手动调度入口，必须创建 Core run、command 和 runner job，并把 attempt 引用写回 Queue task。
queue refresh 只读取 Queue task 保存的 run/command 引用，将 Core 终态回写到 Queue task 和 latestAttempt；不得读取 Core trace、Session trace 或 events 来反推 Queue stats/commander。
queue show/list/stats/commander 的统计口径必须来自 Queue 模型；输出、trace 和会话控制继续由 Session API/CLI 承接。
综合联调里的 workspaceRef 必须是 runner 实际可访问且能启动 backend command 的工作区。opaque workspace 可用于不依赖 Git checkout 的最小 Queue dispatch 验收；host-path 只有在该 path 在 runner 容器/进程内可访问且不破坏 Codex command resolution 时才能作为通过证据。
因 workspace 形态导致的 backend command spawn 失败，应归类为 runtime workspace/command 一致性问题，不能误判为 Queue dispatch 或 Queue refresh 失败。

首版通过标准：

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 首版能力；MiniMax-M3 只能作为 Codex-compatible minimax-m3 profile 使用。
旧 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`。
Queue dispatch/refresh	已实现/Q2	`queue dispatch` 受控创建 Core run/command/runner job；`queue refresh` 从 Core run/command 终态回写 Queue task/latestAttempt；自动 Scheduler 仍 deferred。
Session API/CLI	已实现/Q3	Queue 只返回 `sessionPath`；Session 层已承接 `ps/show/turn/steer/cancel/output/trace/read`，默认列表只显示 running/unread。
Scheduler 接入	待实现	旧 Code Queue scheduler 不保留；AgentRun Scheduler 是唯一调度方向。
OA/Event/integrations	不采用	首版不做，后续如需外部 connector/sink 必须单独立规格。
历史迁移	不采用	旧 Code Queue 历史数据不迁移到 AgentRun。

14 KiB Raw Blame History Unescape Escape