mirrors/pikasTech-agentrun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 固化 AgentRun Queue 吸收 Code Queue 规格

Browse Source
This commit is contained in:
Codex
2026-06-01 21:41:21 +08:00
parent 7a152d3061
commit 1a92951324
10 changed files with 234 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+2 -1
View File
@@ -26,7 +26,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓
- P0: AgentRun 必须按纵向 MVP 开发，不能一开始并行铺开成多服务大重写。
- P0: 先证明最小 `runner + 一个 backend`；再加入 `agentrun-mgr` 的 durable facts 和手动启动 runner；最后再加入自动 scheduler。
- P0: 现有 UniDesk Code Queue 和 HWLAB Code Agent 路径默认不被 AgentRun 替换。AgentRun 先作为新的共享执行面，通过 canary 集成逐步验证。
- P0: UniDesk Code Queue 的下一阶段收敛方向是被 AgentRun Queue 直接吸收；不得做长期 adapter 过渡、双写或旧 API/UI/CLI 兼容层。旧 Code Queue 只保留冻结/归档语义，新任务进入 AgentRun Queue。
- P0: `v0.1` 面向 HWLAB v0.2 的下一阶段目标是先通过 `agentrun-mgr` 手动调度 API 提供 canary 服务；HWLAB `hwlab-cloud-api` 负责显式创建 run/command 并启动 runner Job，自动 scheduler 不作为前置条件。
## Critical RESTful MVP Rule
@@ -55,6 +55,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓
- `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。
- `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent provider credential 和运行时 Secret 分发规格。
- `docs/reference/spec-v01-runtime-assembly.md`：v0.1 runner/backend 启动前的四要素 RuntimeAssembly 装配模型，覆盖 BackendImageRef、ProfileRef、SessionRef 和 Git-only ResourceBundleRef。
- `docs/reference/spec-v01-queue.md`：v0.1 AgentRun Queue 直接吸收 UniDesk Code Queue 的 RESTful API、CLI、数据模型、Session 边界和验收规格。
- `docs/reference/spec-v01-hwlab-manual-dispatch.md`：v0.1 通过手动调度 API 为 HWLAB v0.2 提供 canary Code Agent 服务的目标、缺口和增强计划。
- `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。
- `docs/reference/spec-v01-agentrun-mgr.md`：v0.1 manager REST API、tenant boundary、runner claim 和 event/status authority。
docs/reference/architecture.md
+16 -11
View File
@@ -1,6 +1,6 @@
# AgentRun 架构参考
AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行面。它不是 UniDesk Code Queue 的改名，也不能默认替换现有 Code Queue 行为。Code Queue 仍是当前 UniDesk 任务队列；AgentRun 是新的基础设施线，重点是 Agent run 生命周期、runner 隔离和可插拔执行 backend。
AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行面。它包含执行内核、Session、Scheduler 和 Queue。UniDesk Code Queue 的下一阶段收敛方向是被 AgentRun Queue 直接吸收；不做 adapter 过渡、双写或旧 Code Queue API/UI/CLI 兼容层。旧 Code Queue 只保留冻结/归档语义，新任务进入 AgentRun Queue。
## 产品边界
@@ -11,9 +11,10 @@ AgentRun 负责通用执行基础设施：
- 将 run 分配给短生命周期 runner；
- 归一化 backend event、stdout/stderr、assistant message、tool call 和 terminal status；
- 管理 lease、heartbeat、基础设施恢复导致的 retry 语义和 run 可观测性；
- 注册 backend capability，并定义 credential 注入边界。
- 注册 backend capability，并定义 credential 注入边界；
- 提供 Queue task、attempt、summary、stats、read cursor 和 commander 聚合，替代 UniDesk Code Queue 的新任务入口。
UniDesk 与 HWLAB 是 tenant/client。UniDesk 负责平台入口、provider 清单、CLI/frontend 集成和现有 Code Queue 兼容。HWLAB 负责实验室任务 policy、设备/硬件语义、operation/audit/evidence 模型和 HWLAB workspace 规则。AgentRun 不判断某个 HWLAB live device mutation 是否被授权，也不判断某个 UniDesk production deployment 是否允许执行；它只执行 tenant policy 已授权的 run。
UniDesk 与 HWLAB 是 tenant/client。UniDesk 负责平台入口、provider 清单和旧 Code Queue 归档；新任务队列能力进入 AgentRun Queue。HWLAB 负责实验室任务 policy、设备/硬件语义、operation/audit/evidence 模型和 HWLAB workspace 规则。AgentRun 不判断某个 HWLAB live device mutation 是否被授权，也不判断某个 UniDesk production deployment 是否允许执行；它只执行 tenant policy 已授权的 run 或 Queue task。
每个 run 都必须显式携带隔离字段：
@@ -21,7 +22,7 @@ UniDesk 与 HWLAB 是 tenant/client。UniDesk 负责平台入口、provider 清
- `projectId`，例如 `pikasTech/unidesk` 或 `pikasTech/HWLAB`；
- `workspaceRef`，用于定位 source/worktree/workspace；
- `providerId`，例如 `G14` 或 `D601`；
- `backendProfile`，`v0.1` allowlist 为 `codex` 与 `deepseek`；后续可以扩展 `opencode`、`claudecode`、`host-native` 或 `windows-native`；
- `backendProfile`，`v0.1` allowlist 为 `codex` 与 `deepseek`；Queue 首版废弃 MiniMax/OpenCode，只允许 Codex/Codex-compatible profile；
- `executionPolicy`，包含 sandbox、approval、timeout、network 和 secret scope；
- `traceSink`，说明标准化 event 镜像到哪里。
@@ -37,7 +38,10 @@ agentrun-runner
短生命周期 per-run 或 per-attempt executor；claim 一个 run，连接一个 backend，写回 events/status
agentrun-backend-*
Codex、Claude Code、OpenCode、host-native 或 Windows-native 执行适配器
Codex/Codex-compatible 执行适配器；Queue 首版不接 MiniMax/OpenCode
agentrun-queue
task、attempt、summary、stats、read cursor、commander 聚合；输出和 trace 只返回 Session 引用
agentrun-scheduler
后续自动 dispatcher；扫描 pending runs，选择 backend/profile/capacity，创建 runner Jobs
@@ -45,7 +49,7 @@ agentrun-scheduler
Manager 是稳定 API 和审计点。Runner 是执行者，不应成为业务客户端直接调用的公共 API。MVP 阶段 operator 可以人工启动 runner 进程或 Kubernetes Job，但 runner 仍必须从 `agentrun-mgr` claim run，并把所有事实写回 manager。
Backend adapter 隐藏具体工具协议。Codex stdio JSON-RPC、OpenCode JSON events、Claude Code、host-native process 和 Windows-native execution 可以使用不同内部协议，但 AgentRun 公共 API 必须保持稳定且与 backend 无关。
Backend adapter 隐藏具体工具协议。`v0.1` 和 AgentRun Queue 首版只把 Codex app-server stdio 作为正式执行路径，`codex` 与 `deepseek` 是同一 backend kind 下的 profile/config/SecretRef 选择。跨 backend kind 路由属于后续规格；MiniMax/OpenCode 不作为 Queue 首版能力。
## v0.1 实现技术栈
@@ -69,7 +73,7 @@ AgentRun 必须按纵向切片推进，不要一开始大规模并行开发。
- `Runner`
- `Backend`
第一切片只要求 `turn`、`interrupt`、`status` 和分页 `events`。不要一开始就做 `steer`、`resume`、judge/retry、UI、跨 backend kind 的自动路由或自动调度。`v0.1` 可做同一 Codex stdio backend kind 下的显式 profile 选择。
第一切片只要求 `turn`、`interrupt`、`status` 和分页 `events`。不要一开始就做 UI、跨 backend kind 的自动路由、OA/Event/integrations 或自动调度。`v0.1` 可做同一 Codex stdio backend kind 下的显式 profile 选择；Queue 首版可以定义 task/attempt/retry/judge 的数据边界，但最终交互验收必须走真实 CLI。
### M1: 最小 Runner 加一个 Backend
@@ -118,11 +122,11 @@ AgentRun 必须按纵向切片推进，不要一开始大规模并行开发。
- stale lease recovery 留下显式 audit event；
- scheduler rollout 不等同于 active run failure。
### M5: Tenant Canary 集成
### M5: Queue 与 Tenant Canary 集成
核心生命周期证明后，再接入 UniDesk 和 HWLAB canary：
- UniDesk 可以新增 `agentrun` CLI/API route，同时保持现有 Code Queue 不变。
- UniDesk Code Queue 新任务入口直接收敛到 AgentRun Queue，旧 Code Queue 只归档或只读。
- HWLAB 可以把一个窄范围 Code Agent canary 路由到 AgentRun。
- 每个 run 都必须显式带 tenant policy、workspace、secret scope 和 trace sink。
@@ -207,6 +211,7 @@ Event 是 append-only，并按 seq 分页：
- `agentrun_runners`：registered runner identity、placement 和 heartbeat；
- `agentrun_backends`：backend profile、capabilities、capacity 和 health；
- `agentrun_leases`：当前 ownership 和 expiry。
- `agentrun_queue_tasks`、`agentrun_queue_attempts`、`agentrun_task_summaries`、`agentrun_attempt_summaries`、`agentrun_queue_stats`、`agentrun_queue_read_cursors` 和 `agentrun_queue_judge_runs`：Queue task、attempt、summary、stats、read cursor 和 judge durable facts；完整边界见 [spec-v01-queue.md](spec-v01-queue.md)。
Postgres DSN、provider credential 和未来 tenant credential 的分发边界见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)；Codex 测试凭据通过 Kubernetes Secret projection 注入 `~/.codex/auth.json` 与 `~/.codex/config.toml`，source、GitOps、event、trace、日志和 CLI 输出都不得保存 Secret 明文。
@@ -222,14 +227,14 @@ Control-plane service 应是长驻服务；runner 应是短生命周期 Job 或
第一版 MVP 不包含：
- 迁移 UniDesk Code Queue；
- 全局替换 HWLAB Code Agent；
- 跨 backend kind 的自动多 backend 路由；
- 最小诊断之外的 UI；
- judge/retry 自动化；
- 自动扩缩容；
- 跨集群调度；
- SSE/WebSocket 流式输出；
- Event System、OA Event Flow、OA sink、GitHub sink、notification sink 或 integrations 表；
- 迁移旧 Code Queue 历史数据；
- 完整权限系统；
- production rollout 自动化。
docs/reference/spec-v01-backend-adapter.md
+1 -1
View File
@@ -1,6 +1,6 @@
# v0.1 Backend Adapter 规格
Backend adapter 是 runner 与具体 Code Agent 工具之间的适配层。它隐藏 Codex、OpenCode、Claude Code、host-native 或 Windows-native 的内部协议，把输入、事件、错误和 terminal status 归一化为 AgentRun 公共模型。
Backend adapter 是 runner 与具体 Code Agent 工具之间的适配层。`v0.1` 的正式执行路径只保留 Codex/Codex-compatible backend profile；MiniMax/OpenCode 废弃，不作为 fallback、judge backend 或 Queue 首版能力。Adapter 把输入、事件、错误和 terminal status 归一化为 AgentRun 公共模型。
## 在系统中的职责划分
docs/reference/spec-v01-cli.md
+20
View File
@@ -5,6 +5,8 @@ AgentRun CLI 是 `v0.1` 的受控人工操作和验收入口。它必须遵循 U
## 在系统中的职责划分
- 创建 run、查询 run、提交 command、查询 command、分页读取 events。
- 创建和查询 Queue task，查看 Queue stats/read/commander，并从 Queue task 获取 Session 引用。
- 查询 Session 输出、trace 和会话控制；Queue 命令不得代理输出或 trace。
- 手动启动 runner，本地 process 或 Kubernetes Job 均必须快速返回 job/process identity 和 logPath。
- 查询 backend capability 和 manager health。
- 为综合联调提供 CLI 交互面；不得替代 RESTful API 合同测试。
@@ -49,6 +51,17 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
./scripts/agentrun secrets codex render --dry-run [--profile codex|deepseek] [--codex-home <dir>]
./scripts/agentrun backends list
./scripts/agentrun server start|status
./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 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>
```
具体参数可以在实现时按代码结构微调，但行为必须保持：
@@ -61,6 +74,8 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
- `server logs` 返回有界日志摘要，并指向完整日志文件或 Kubernetes pod identity。
- `secrets codex render --dry-run` 返回 Codex stdio profile Secret 创建计划、输入文件 bytes/hash、SecretRef、manifest 摘要和 apply 命令形状；`--profile codex` 默认 Secret name 为 `agentrun-v01-provider-codex`，`--profile deepseek` 默认 Secret name 为 `agentrun-v01-provider-deepseek`；它不得输出 Secret value 或执行 Kubernetes 写操作。
- `backends list` 必须显示 `codex` 与 `deepseek` profile 的 backendKind、protocol、transport、command、requiredSecretKeys 和状态；不得因为 `deepseek` 尚未配置 Secret 就隐藏 capability。
- `queue show` 必须返回 task/attempt summary、state、read cursor、stats 相关字段和 `sessionPath`；不得返回或代理完整 output/trace。
- `sessions output` 与 `sessions trace` 是输出和 trace 的唯一 CLI 查询入口；不得新增 `queue output` 或 `queue trace` 兼容命令。
## 配置与 Secret 边界
@@ -91,6 +106,10 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
阅读本文、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) 和 [spec-v01-validation.md](spec-v01-validation.md)，然后用正式 CLI 分别创建 `backendProfile=codex` 与 `backendProfile=deepseek` 的 run，按 `codex -> deepseek -> codex` 顺序执行真实 runner。确认 CLI 输出非空 JSON，backend_status 显示正确 profile/backendKind/protocol，缺失 `deepseek` SecretRef 时返回 `secret-unavailable`，不会 fallback 到 `codex`。
### T6 Queue 与 Session CLI 分层
阅读本文和 [spec-v01-queue.md](spec-v01-queue.md)，然后用正式 CLI 创建一个 Queue task，轮询 `queue list/show/stats/commander/read`，再使用 `queue show` 返回的 `sessionPath` 调用 `sessions output/trace`。确认 Queue 命令只返回 summary/stats/read/sessionPath，不代理 output/trace；Session 命令能查询输出和 trace。最终交互验收必须使用真实 runtime，不使用 mock，不写自动交互脚本。
## 规格的实现情况
| 规格项 | 状态 | 说明 |
@@ -101,5 +120,6 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
| runner start/job | 已实现 | `runner start` 可执行 host process runner；`runner job --dry-run` 可渲染 Kubernetes Job JSON；`runner job` 正式路径通过 manager REST 创建 Kubernetes Job，支持 `--idempotency-key` 并快速返回 job identity、SecretRef、retention 和轮询命令。 |
| runner jobs/job-status | 已实现 | CLI 通过 manager REST 查询 runner Job 持久记录和最小状态摘要，不直连 Kubernetes、不读取 Secret 值。 |
| result/cancel CLI | 已实现 | `runs result`、`commands result`、`runs cancel` 和 `commands cancel` 均调用 manager REST，不维护独立状态。 |
| Queue/Session CLI | 待实现 | 规格见 [spec-v01-queue.md](spec-v01-queue.md)；Queue 命令只返回 sessionPath，输出和 trace 进入 Session 命令。 |
| CLI 测试规格 | 已定义/已验证主闭环 | 综合联调见 [spec-v01-validation.md](spec-v01-validation.md)；每次发布仍按手动交互验收复跑。 |
| `deepseek` profile CLI | 已实现/已通过主闭环 | `secrets codex render --profile deepseek`、`backends list`、`runner start --backend`、`runner job` 和 JSON 错误可见性已实现；真实 CLI/RESTful 联调已通过 `codex -> deepseek -> codex` 切换主闭环。 |
docs/reference/spec-v01-documentation-governance.md
+3 -1
View File
@@ -30,6 +30,7 @@
- `spec-v01-postgres.md`：Postgres durable store、schema migration 和 DB SecretRef。
- `spec-v01-secret-distribution.md`：Code Agent provider credential、Postgres DSN 和运行时 Secret 分发。
- `spec-v01-runtime-assembly.md`：runner/backend 启动前的四要素 RuntimeAssembly 装配模型；其他 spec 只交叉引用，不重复定义四要素字段。
- `spec-v01-queue.md`：AgentRun Queue 直接吸收 UniDesk Code Queue 的 RESTful API、CLI、数据模型、Session 分层和验收规格。
- `spec-v01-validation.md`：两层验证模型、自测试和综合联调验收。
- `spec-v01-agentrun-mgr.md`：manager REST API、tenant boundary、runner claim、event/status authority。
- `spec-v01-agentrun-runner.md`：短生命周期 runner、claim/poll/report、日志和 failureKind。
@@ -60,6 +61,7 @@
- 服务总览规格：[spec-v01-services.md](spec-v01-services.md)。
- Postgres durable store 规格：[spec-v01-postgres.md](spec-v01-postgres.md)。
- Secret/provider credential 分发规格：[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。
- Queue 吸收规格：[spec-v01-queue.md](spec-v01-queue.md)。
- 验证模型规格：[spec-v01-validation.md](spec-v01-validation.md)。
- Manager 服务规格：[spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)。
- Runner 服务规格：[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)。
@@ -71,7 +73,7 @@
## 验收标准
- `AGENTS.md` 索引本文和其他 `spec-v01-*` 规格。
- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md`、`spec-v01-secret-distribution.md`、`spec-v01-runtime-assembly.md`、`spec-v01-validation.md`、`spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`、`spec-v01-backend-adapter.md`、`spec-v01-backend-codex.md`、`spec-v01-cli.md` 和 `spec-v01-scheduler.md`。
- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md`、`spec-v01-secret-distribution.md`、`spec-v01-runtime-assembly.md`、`spec-v01-queue.md`、`spec-v01-validation.md`、`spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`、`spec-v01-backend-adapter.md`、`spec-v01-backend-codex.md`、`spec-v01-cli.md` 和 `spec-v01-scheduler.md`。
- `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前 source worktree、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。
- `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。
- 仓库根目录不存在 `TEST.md`；测试场景维护在对应 `spec-v01-*.md` 的“测试规格”小节。
docs/reference/spec-v01-postgres.md
+9 -2
View File
@@ -4,7 +4,7 @@
## 在系统中的职责划分
- 保存 `agentrun-mgr` 的 durable facts：runs、commands、events、runners、runner_jobs、sessions、backends、leases 和 migration ledger。
- 保存 `agentrun-mgr` 的 durable facts：runs、commands、events、runners、runner_jobs、sessions、backends、leases、Queue facts 和 migration ledger。
- 为 runner claim、command ack、event append、heartbeat 和 terminal status 提供事务边界。
- 与 `agentrun-v01` namespace 绑定；不复用未来 `v0.2`、`v0.3` 或旧 dev/prod 数据库。
- 不向公网开放，不允许普通 runner 直连写入不属于自己的 run facts。
@@ -36,10 +36,17 @@ Secret 名称和 key 可以在实现时按 Kubernetes 命名限制微调，但
- `agentrun_runners`：registered runner identity、placement、heartbeat 和 capability snapshot。
- `agentrun_runner_jobs`：手动 runner Job 的 idempotency key、payload hash、attempt/job identity 和创建响应。
- `agentrun_sessions`：SessionRef 到 backend thread/cache identity 的最小映射，不保存 credential 文件或 Secret 值。
- `agentrun_queue_tasks`：AgentRun Queue task identity、queue/lane、tenant/project、priority、state、backendProfile、workspace/resource 引用和 version。
- `agentrun_queue_attempts`：task attempt identity、runId、commandId、runnerJobId、sessionId、state、failureKind、retry index 和 timestamps。
- `agentrun_task_summaries` / `agentrun_attempt_summaries`：Queue 列表、详情和 commander 使用的轻量摘要；不能从 Core trace 反推 overview。
- `agentrun_queue_stats`：按 queue/lane/state/backendProfile 聚合的统计水位。
- `agentrun_queue_read_cursors`：按 user/agent/client 记录 Queue 已读水位。
- `agentrun_queue_judge_runs`：judge 请求、结果、failureKind、重试建议和 attempt 关联。
- `agentrun_task_references`：任务的显式 issue/PR/repo/commit/doc 引用，不保存 UniDesk 隐式环境提示。
- `agentrun_backends`：backend profile、capabilities、capacity 和 health。
- `agentrun_leases`：run ownership、expiry 和 stale recovery marker。
第一版实现可以把 backend-specific payload 存在 JSONB 字段中，但 run、command、event、runner、backend 和 lease 的主键、状态、时间戳和索引字段必须是一等列，不能把所有事实塞进一个不可查询 JSON blob。
第一版实现可以把 backend-specific payload 存在 JSONB 字段中，但 run、command、event、runner、backend、lease 和 Queue 的主键、状态、时间戳和索引字段必须是一等列，不能把所有事实塞进一个不可查询 JSON blob。Queue 首版不得新增 OA/Event/integrations/notification 这类外部动作表；如后续需要 connector/sink，必须另立规格。
## 访问边界
docs/reference/spec-v01-queue.md
+169
View File
@@ -0,0 +1,169 @@
# 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 请求和轻量轮询：
```http
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 和会话控制：
```http
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：
```json
{
"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 命令只操作队列资源：
```bash
./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 和会话控制：
```bash
./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 | 待实现 | 计划通过 `agentrun-mgr` 暴露，仍使用短请求和轻量轮询。 |
| Queue CLI | 待实现 | 计划加入 `queue ...` 和 `sessions ...` 命令族。 |
| Session API/CLI | 待实现 | Queue 只返回 `sessionPath`；Session 层承接输出、trace 和控制。 |
| Scheduler 接入 | 待实现 | 旧 Code Queue scheduler 不保留；AgentRun Scheduler 是唯一调度方向。 |
| OA/Event/integrations | 不采用 | 首版不做，后续如需外部 connector/sink 必须单独立规格。 |
| 历史迁移 | 不采用 | 旧 Code Queue 历史数据不迁移到 AgentRun。 |
docs/reference/spec-v01-scheduler.md
+2 -1
View File
@@ -1,11 +1,12 @@
# v0.1 Scheduler Deferred 规格
`agentrun-scheduler` 是 AgentRun 后续自动调度器。它扫描 pending runs，选择 backend/profile/capacity，创建 runner Jobs，并处理 stale lease recovery。`v0.1` 保留该规格用于边界收敛，但自动 scheduler 不作为第一阶段交付和发布通过条件。
`agentrun-scheduler` 是 AgentRun 后续自动调度器。它扫描 pending runs 或 Queue task attempts，选择 backend/profile/capacity，创建 runner Jobs，并处理 stale lease recovery。`v0.1` 保留该规格用于边界收敛，但自动 scheduler 不作为第一阶段交付和发布通过条件。
## 在系统中的职责划分
- 只在 M1-M3 稳定后进入实现；MVP 先通过 CLI/manual dispatch 启动 runner。
- 未来负责 pending run scan、capacity selection、runner Job creation、stale lease recovery 和 scheduler restart recovery。
- AgentRun Queue 吸收 UniDesk Code Queue 后，Scheduler 是唯一长期调度方向；旧 UniDesk Code Queue scheduler 不保留。
- 不直接执行 backend，不直接写 provider events，不绕过 `agentrun-mgr` claim/report。
- 不替代 tenant 业务授权；只能消费 manager 已保存的 run policy。
docs/reference/spec-v01-services.md
+6 -3
View File
@@ -6,13 +6,14 @@
## 在系统中的职责划分
AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`v0.1` 只做最小纵向闭环，不替换 UniDesk Code Queue，也不替换 HWLAB 现有 Code Agent 路径。
AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`v0.1` 先完成最小纵向闭环；下一阶段 UniDesk Code Queue 的队列产品能力直接吸收到 AgentRun Queue，不做 adapter 过渡、双写或旧 API/UI/CLI 兼容层。HWLAB 现有 Code Agent 路径仍按 canary 节奏接入，不由 Queue 吸收规格替代 HWLAB 业务路由。
- `agentrun-mgr` 是公共 RESTful API 和 durable facts authority，负责 run、command、event、runner、backend、lease 的持久状态和鉴权前置边界。
- `agentrun-runner` 是短生命周期 per-run 或 per-attempt 执行者，必须从 manager claim run，并把 event、heartbeat 和 terminal status 写回 manager。
- Backend adapter 隐藏具体 Agent 工具协议，`v0.1` 使用一个真实 Codex stdio backend kind 形成闭环，并在该 kind 下支持 `codex` 与 `deepseek` profile；其他 backend kind 不进入第一波实现。
- AgentRun CLI 是受控操作入口，负责创建 run、提交 command、轮询 events、手动启动 runner 和查看 backend capability；CLI 不等待完整模型 turn。
- RuntimeAssembly 是 runner/backend 启动前的四要素装配模型，负责把 backend image、profile、session 和 Git-only resource bundle 统一成受控 Job 输入；四要素权威规格见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
- AgentRun Queue 是吸收 UniDesk Code Queue 的任务队列层，负责 task、attempt、retry、judge、summary、stats、read cursor 和 commander 聚合；Queue 查询只返回 Session 引用，输出和 trace 进入 Session API/CLI。权威规格见 [spec-v01-queue.md](spec-v01-queue.md)。
- Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。
## HWLAB 手动调度服务目标
@@ -38,7 +39,7 @@ AgentRun `v0.1` 的自研组件优先使用 Bun + TypeScript 实现：`agentrun-
| `codex` | `codex-app-server-stdio` | 保留，P0 | `agentrun-v01-provider-codex` | 现有 GPT/Codex profile，必须保持默认行为不回归。 |
| `deepseek` | `codex-app-server-stdio` | 新增，P0 | `agentrun-v01-provider-deepseek` | DeepSeek-compatible Codex profile；通过 profile 专属 `auth.json`/`config.toml` 或等价 SecretRef 配置上游、模型和 base URL。 |
完整多 backend 路由仍然 deferred，含 OpenCode、Claude Code、host-native、Windows-native、scheduler capacity selection 和跨 backend 自动选择。`v0.1` 只允许 manager/runner 按 run 中的 `backendProfile` 显式选择 `codex` 或 `deepseek`，并在 capability 中报告两者共享同一个 `protocol=codex-app-server-jsonrpc-stdio` 与 `transport=stdio`。
完整多 backend 路由仍然 deferred。`v0.1` 只允许 manager/runner 按 run 中的 `backendProfile` 显式选择 `codex` 或 `deepseek`，并在 capability 中报告两者共享同一个 `protocol=codex-app-server-jsonrpc-stdio` 与 `transport=stdio`。MiniMax/OpenCode 废弃，不进入 AgentRun Queue 首版，也不作为 fallback 或 judge backend。
`codex` 与 `deepseek` 之间不得隐式 fallback：缺少 `deepseek` SecretRef 时必须失败为 `secret-unavailable`，不能改用 `codex` Secret；`deepseek` 运行失败也不能重试到 `codex`。同一轮发布的综合联调必须证明 `codex -> deepseek -> codex` 的切换不会污染彼此的 SecretRef、`CODEX_HOME`、模型或 upstream 配置。
@@ -88,7 +89,8 @@ Runner inbound API 只允许本地或私有诊断，不作为业务客户端入
| Tenant policy boundary | Run schema 合同 | 保留，P0 | 作为 `Run` 的必填字段和最小校验存在，不做独立 policy engine；tenant 的业务授权仍由 UniDesk/HWLAB 判定。 | 并入 `spec-v01-agentrun-mgr.md` |
| Observability | 最小事件/日志合同 | 保留，P1 子项 | 作为 manager/runner 的 event、terminal status、failureKind、logPath 和 redaction 最小合同，不拆独立观测系统。 | 并入 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md` |
| `agentrun-scheduler` | 长驻调度器 | Deferred | M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 | `spec-v01-scheduler.md` |
| 多 backend 路由 | 系统能力 | Deferred | `v0.1` 不做跨 backend kind 的自动路由和调度；仅支持同一 Codex stdio backend kind 下的 `codex`/`deepseek` profile 手动选择。 | 后续版本 spec |
| AgentRun Queue | 系统能力 | 新增，P0 规格 | 直接吸收 UniDesk Code Queue 的队列能力；第一版只做 RESTful API、CLI 和轻量轮询，不做 Event/OA/integrations，不迁移历史数据。 | `spec-v01-queue.md` |
| 多 backend 路由 | 系统能力 | Deferred | `v0.1` 不做跨 backend kind 的自动路由和调度；仅支持同一 Codex stdio backend kind 下的 `codex`/`deepseek` profile 手动选择。MiniMax/OpenCode 不进入 Queue 首版。 | 后续版本 spec |
| UI | 前端 | Deferred | `v0.1` 不要求独立 UI；UniDesk/HWLAB canary 可通过 CLI/API 验证。 | 后续版本 spec |
| judge/retry 自动化 | 系统能力 | Deferred | `v0.1` 只定义基础 terminal 和 failure visibility，不实现复杂 judge。 | 后续版本 spec |
@@ -184,6 +186,7 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保
| Postgres durable store 规格 | 已定义 | 见 [spec-v01-postgres.md](spec-v01-postgres.md)。 |
| Secret 分发规格 | 已定义 | 见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 |
| RuntimeAssembly 规格 | 已定义 | 见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。 |
| AgentRun Queue 规格 | 已定义 | 见 [spec-v01-queue.md](spec-v01-queue.md)。 |
| HWLAB 手动调度接入规格 | 已定义 | 见 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)。 |
| 两层验证规格 | 已定义 | 见 [spec-v01-validation.md](spec-v01-validation.md)。 |
| `agentrun-mgr` 服务规格 | 已定义 | 见 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)。 |
docs/reference/spec-v01-validation.md
+6
View File
@@ -23,6 +23,7 @@
- CLI：默认 JSON、空 stdout 失败、长操作短返回、错误结构化。
- Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。
- Secret 分发：SecretRef schema、missing secret failure、redaction。
- AgentRun Queue：task schema、attempt 状态机、summary/stats/read cursor、Queue 与 Session 引用边界、MiniMax/OpenCode 废弃入口和 redaction。
- HWLAB v0.2 基线承接：可以用 fake backend/临时 manager 做组件自测试，覆盖 event contract、result completed 防误判、bounded output、runner job status、SessionRef profile 隔离、ResourceBundleRef 失败分类和 backend preflight redaction；这些自测试不能替代真实 `agentrun-v01` CLI 交互验收。
自测试应使用 Bun + TypeScript 运行，Codex 相关自测试可以使用 fake app-server JSON-RPC client 模拟 `initialize`、`thread/start`、`thread/resume`、`turn/start`、assistant 输出、协议错误、timeout 和 transport close。
@@ -184,6 +185,10 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
阅读本文和 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)，然后在真实 `agentrun-v01` runtime 中模拟 HWLAB dispatcher：创建 `tenantId=hwlab` 的 run，提交 `turn` command，调用 `POST /api/v1/runs/:runId/runner-jobs`，轮询 command、events 和 result 到 terminal。确认 API 全部短返回 JSON，runner Job identity 可见，events/result 能转换为 HWLAB result/trace，并验证 runner job idempotency、cancel、SessionRef 和 ResourceBundleRef 的真实路径；不能用 mock pass 替代真实 canary。
### T11 Queue 吸收 Code Queue 手动验收
阅读本文和 [spec-v01-queue.md](spec-v01-queue.md)，然后在真实 `agentrun-v01` runtime 中用正式 CLI 手动验证 Queue 首版闭环：创建 Queue task，轮询 `queue list/show/stats/commander/read`，触发真实 Codex/Codex-compatible attempt 到 terminal，确认 `queue show` 返回 `sessionPath`，再通过 `sessions output/trace` 查询输出和 trace。该验收不得使用 mock，不写自动交互脚本，不做 Web/Playwright。确认 Queue overview、stats、read 和 commander 均来自 Queue summary/stats/read 模型，不从 Core trace 或 Session trace 反推；确认不存在首版 OA/Event/OA sink/integrations/notification/GitHub sink 依赖；确认 MiniMax/OpenCode 不作为 Queue 首版能力；确认旧 UniDesk Code Queue 不接收新任务且历史数据不迁移到 AgentRun。
## 规格的实现情况
| 规格项 | 状态 | 说明 |
@@ -198,4 +203,5 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend
| `deepseek` profile 切换验收 | 已通过主闭环 | 自测试和 CLI smoke 已覆盖 profile registry、Secret render、fake stdio turn、无 fallback 和结构化错误；真实 `agentrun-v01` 已按 T8 完成 `codex -> deepseek -> codex` 切换综合联调。后续涉及 backend profile 的发布仍必须按 T8 复验。 |
| RuntimeAssembly 四要素验收 | 已定义 | T9 收敛为四个最简问题：image digest、profile/SecretRef、session null/deferred、Git-only repo/full commit；session/resource materialization 后续实现时必须补真实联调。 |
| HWLAB 手动调度 canary 验收 | 已定义 | T10 规定 HWLAB dispatcher 通过手动 runner Job API 使用 AgentRun 的真实联调口径；自动 scheduler 不是前置条件。 |
| Queue 吸收 Code Queue 验收 | 已定义 | T11 规定 Queue RESTful/CLI/Session 分层的真实手动交互验收；mock 只允许在自测试层。 |
| mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |