docs: 固化 AgentRun Queue 吸收 Code Queue 规格
This commit is contained in:
Codex
@@ -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 自动化。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user