pikasTech-agentrun/docs/reference/architecture.md

# AgentRun 架构参考

AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行面。它包含执行内核、Session、Scheduler 和 Queue。UniDesk Code Queue 的下一阶段收敛方向是被 AgentRun Queue 直接吸收；不做 adapter 过渡、双写或旧 Code Queue API/UI/CLI 兼容层。旧 Code Queue 只保留冻结/归档语义，新任务进入 AgentRun Queue。

## 产品边界

AgentRun 负责通用执行基础设施：

- 创建和跟踪 run；
- 接收 `turn`、`steer`、`interrupt`、`resume` 等 durable command；
- 将 run 分配给短生命周期 runner；
- 归一化 backend event、stdout/stderr、assistant message、tool call 和 terminal status；
- 管理 lease、heartbeat、基础设施恢复导致的 retry 语义和 run 可观测性；
- 注册 backend capability，并定义 credential 注入边界；
- 提供 Queue task、attempt、summary、stats、read cursor 和 commander 聚合，替代 UniDesk Code Queue 的新任务入口。

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 都必须显式携带隔离字段：

- `tenantId`，例如 `unidesk` 或 `hwlab`；
- `projectId`，例如 `pikasTech/unidesk` 或 `pikasTech/HWLAB`；
- `workspaceRef`，用于定位 source/worktree/workspace；
- `providerId`，例如 `G14` 或 `D601`；
- `backendProfile`，`v0.1` allowlist 为 `codex`、`deepseek` 与 `minimax-m3`；Queue 首版废弃旧 MiniMax/OpenCode 直连路线，只允许 Codex/Codex-compatible profile；
- `executionPolicy`，包含 sandbox、approval、timeout、network 和 secret scope；
- `traceSink`，说明标准化 event 镜像到哪里。

HWLAB 接入时必须显式分离业务 identity 和执行 identity：HWLAB `conversationId` / `sessionId` / `threadId` 是业务会话，AgentRun `runId` / `commandId` / `runnerJobId` 是执行尝试，AgentRun `SessionRef` / PVC 是 backend profile 续接状态。HWLAB Workbench 的 project/workspace 字段只能作为 HWLAB metadata 或 `workspaceRef` 子字段，不得写入 AgentRun `projectId`；AgentRun `projectId` 仍固定表达 tenant policy 边界，例如 `pikasTech/HWLAB`。

架构混乱的临时处理原则：发现 HWLAB provider/session/project/workspace 与 AgentRun tenant/project/run/job 字段混用时，不放宽 manager tenant policy、不改成 fallback backend、不靠 prompt 历史模拟续接。先在目标 runtime 用最小真实请求核对 run payload、runner job env、`SessionRef`、PVC phase、lease 和 command events；必要时热补丁只用于证明单变量修复，随后必须回到源码、CI/CD 和原入口复测。

长期收敛建议：跨仓库 API/schema 应使用不同字段名表达不同层级，例如 `hwlabProjectId` / `agentRunProjectId`、`hwlabSessionId` / `agentRunSessionId`、`providerProfile` / `backendProfile`、`runId` / `sessionId`。客户端和 Web 应同时展示业务 session/thread/provider 与执行 run/job/command，避免 operator 把 replacement runner 当作新业务 session 或把业务 workspace project 当作 AgentRun tenant policy。

## 服务形态

AgentRun 应构建为小型服务族：

```text
agentrun-mgr
  公共 RESTful API、durable facts、tenant/policy/idempotency 检查

agentrun-runner
  短生命周期 per-run 或 per-attempt executor；claim 一个 run，连接一个 backend，写回 events/status

agentrun-backend-*
  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
```

Manager 是稳定 API 和审计点。Runner 是执行者，不应成为业务客户端直接调用的公共 API。MVP 阶段 operator 可以人工启动 runner 进程或 Kubernetes Job，但 runner 仍必须从 `agentrun-mgr` claim run，并把所有事实写回 manager。

Backend adapter 隐藏具体工具协议。`v0.1` 和 AgentRun Queue 首版只把 Codex app-server stdio 作为正式执行路径，`codex`、`deepseek` 与 `minimax-m3` 是同一 backend kind 下的 profile/config/SecretRef 选择。跨 backend kind 路由属于后续规格；旧 MiniMax/OpenCode 直连路线不作为 Queue 首版能力。

## v0.1 实现技术栈

AgentRun `v0.1` 自研 runtime 优先使用 Bun + TypeScript：manager、runner、backend adapter、Codex backend、CLI 和后续 scheduler 都按这一技术栈实现。`scripts/agentrun-cli.ts` 是官方 CLI 入口；复杂 CLI 逻辑进入 `scripts/src/`，服务和 runner 逻辑进入 `src/`。YAML manifest、Tekton/Argo CD 配置、Postgres 和 Kubernetes 仍按各自原生生态管理。

Codex stdio backend 固定采用 Codex CLI app-server JSON-RPC over stdio。实现必须启动受控 `codex app-server --listen stdio://`，执行 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`，并把 stdout/stderr、notification、tool lifecycle、assistant output 和 terminal/error 状态归一化为 AgentRun events。`codex`、`deepseek` 与 `minimax-m3` 是同一个 backend kind 下的 profile/config/SecretRef 选择；直接 Responses HTTP、OpenAI SDK wrapper、`codex exec` 一次性输出或文本 fallback 不能作为 `v0.1` Codex backend 的正式执行路径。

实现参考优先级：UniDesk Code Queue 的 `src/components/microservices/code-queue/src/code-agent/codex.ts`、`common.ts`，以及 HWLAB v0.2 的 `internal/cloud/codex-stdio-session.mjs`、`scripts/code-agent-chat-smoke.mjs`、`docs/reference/spec-v02-deepseek-proxy.md`、`docs/reference/code-agent-chat-readiness.md`。AgentRun 复用其协议、trace、redaction、Secret projection、profile overlay、DeepSeek/Moon Bridge 分层诊断和 failure 分类经验，但不复制 tenant 业务规则、环境专用路径、bridge host、namespace 或密钥材料。

## MVP 顺序

AgentRun 必须按纵向切片推进，不要一开始大规模并行开发。

### M0: 契约骨架

只定义最小资源模型和状态机：

- `Run`
- `Command`
- `Event`
- `Runner`
- `Backend`

第一切片只要求 `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

第一份可执行证明不依赖 manager 或 scheduler。Runner 读取本地 run spec，调用一个 backend，并输出标准化 events。

验收标准：

- 一个 `turn` 能通过 backend 执行；
- assistant/output/error events 被归一化；
- terminal status 被写出；
- interrupt 至少有 durable cancellation 路径，backend 支持时再传播到真实进程中断。

第一个 backend 固定选择 Codex app-server stdio，用最窄实现证明真实 Agent 原语。如果 Codex 上游或凭据短暂不可用，可以用 controlled process 或 fake app-server 做自测试，但不能替代综合联调，也不能据此宣称 `v0.1` backend 通过。

### M2: Manager 加 Runner Claim

加入 `agentrun-mgr` 作为 durable fact store 和公共 API。Client 创建 run；operator 或 CLI 用 run id 人工启动 runner；runner claim、poll commands、append events、heartbeat 并退出。

验收标准：

- run create/query 是 durable 的；
- runner claim 幂等，并拒绝双 owner；
- events 是 append-only，并按 seq 分页；
- command ack state 可见；
- heartbeat expiration 可观察。

### M3: 手动 Dispatch CLI

增加 CLI，为指定 run 启动本地 runner process 或 Kubernetes Job。这是 manual dispatch，不是 manager 侧同步编排。Manager 仍拥有事实，runner 仍拥有执行。

验收标准：

- CLI 快速返回 JSON；
- job/process identity 和 log path 可见；
- run status 可从 manager 轮询；
- runner 启动失败被报告为基础设施失败，不能静默写成任务成功。

### M4: 自动 Scheduler

只有 M1-M3 稳定后才加入 `agentrun-scheduler`。Scheduler 扫描 pending runs，应用 policy/capacity/backend selection，创建 runner Jobs，并处理 stale lease recovery。Scheduler 不直接执行 backend。

验收标准：

- pending run 自动变为 running；
- scheduler restart 不影响已经运行的 runner；
- stale lease recovery 留下显式 audit event；
- scheduler rollout 不等同于 active run failure。

### M5: Queue 与 Tenant Canary 集成

核心生命周期证明后，再接入 UniDesk 和 HWLAB canary：

- UniDesk Code Queue 新任务入口直接收敛到 AgentRun Queue，旧 Code Queue 只归档或只读。
- HWLAB 可以把一个窄范围 Code Agent canary 路由到 AgentRun。
- 每个 run 都必须显式带 tenant policy、workspace、secret scope 和 trace sink。

## RESTful MVP 契约

MVP 只使用短 RESTful HTTP/JSON 请求。长时间 Agent 工作用 durable command resource、run status 和分页 event polling 表示。不要让一个 HTTP 请求等待完整模型 turn。

Manager 公共 API：

```http
POST /api/v1/runs
GET  /api/v1/runs/:runId
GET  /api/v1/runs/:runId/events?afterSeq=0&limit=100
POST /api/v1/runs/:runId/commands
GET  /api/v1/runs/:runId/commands/:commandId
GET  /api/v1/backends
```

Runner 到 manager 的私有 API：

```http
POST  /api/v1/runners/register
POST  /api/v1/runs/:runId/claim
PATCH /api/v1/runs/:runId/lease
GET   /api/v1/runs/:runId/commands?afterSeq=0&limit=20
POST  /api/v1/runs/:runId/events
PATCH /api/v1/runs/:runId/status
POST  /api/v1/commands/:commandId/ack
```

Runner inbound API 应保持本地/私有且最小：

```http
GET /health
GET /debug/status
```

不要依赖客户端调用短生命周期 runner Pod 地址。该方式在 Job、namespace、host-native backend 和重启场景下都会变脆。

## Command 状态

Command 是 durable resource。`turn`、`steer`、`interrupt` 和 `resume` 不能实现为 client 到 runner 的同步进程调用。

初始 command 状态机：

```text
accepted -> delivered -> confirmed
accepted -> delivered -> failed
accepted -> expired
```

所有 command 写入都应支持 idempotency key。相同 idempotency key 且 payload hash 相同的重复请求返回既有 command；相同 key 但 payload hash 不同必须显式失败。

## Event 模型

Event 是 append-only，并按 seq 分页：

- `seq` 在单个 run 内单调递增。
- `eventId` 或 `(runId, seq)` 支持幂等去重。
- `GET /events?afterSeq=N&limit=M` 是第一阶段观察 API。
- 后续 SSE 可以流式传输相同 event resource，但不能替代 REST polling contract。

最小 event 类别：

- `system`
- `assistant_message`
- `tool_call`
- `command_output`
- `diff`
- `error`
- `backend_status`
- `terminal_status`

## 数据模型方向

`v0.1` 使用 Postgres 作为唯一 durable store；file、sqlite、JSONL 或 Pod 本地目录只能用于临时测试或日志，不作为运行面事实来源。第一版实现可以使用紧凑 schema，但不应把所有事实都隐藏在一个 JSON blob 中。稳定方向是：

- `agentrun_schema_migrations`：migration id、checksum 和 applied timestamp；
- `agentrun_runs`：run identity、tenant/project/workspace/backend policy、status 和 timestamps；
- `agentrun_commands`：command type、idempotency key、payload hash、state 和 ack timestamps；
- `agentrun_events`：按 run 和 seq 索引的 append-only event records；
- `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 明文。

## 部署方向

AgentRun 从 `v0.1` 开始按版本 lane 滚动，废弃 `dev/prod` 管理口径。`v0.1` 的固定 source worktree 是 `G14:/root/agentrun-v01`，固定 source branch 是 `v0.1`，固定运行目标是 G14 原生 k3s namespace `agentrun-v01`。后续 `v0.2`、`v0.3` 必须拥有自己的 branch、source worktree、namespace、GitOps branch、runtime path 和发布验收。

Control-plane service 应是长驻服务；runner 应是短生命周期 Job 或受控 host-native process。Backend adapter 可以作为 pod 或 host-native service 运行，但必须通过 AgentRun 注册 capability 和 health，不能通过临时地址被 ad hoc 调用。

广泛 tenant 使用前，需要先设计 namespace isolation、RBAC、Secret scope、NetworkPolicy 和 ResourceQuota。独立 cluster 是后续成熟选项；第一版应优先在 `agentrun-v01` namespace 内证明服务，除非出现明确隔离 blocker。`agentrun_dev` 和 `agentrun_prod` 不再作为当前架构规格或验收目标。

## MVP 非目标

第一版 MVP 不包含：

- 全局替换 HWLAB Code Agent；
- 跨 backend kind 的自动多 backend 路由；
- 最小诊断之外的 UI；
- 自动扩缩容；
- 跨集群调度；
- SSE/WebSocket 流式输出；
- Event System、OA Event Flow、OA sink、GitHub sink、notification sink 或 integrations 表；
- 迁移旧 Code Queue 历史数据；
- 完整权限系统；
- production rollout 自动化。

第一目标是稳定跑通一条纵向 run 生命周期：create run、人工启动 runner、执行一个 backend turn、append events、观察 final status，并能发出可见的 interrupt/cancel command。