Codex
100 lines
6.0 KiB
Markdown
100 lines
6.0 KiB
Markdown
# v0.1 服务总体规格
|
||
|
||
本文是 AgentRun `v0.1` 服务总览和取舍规格。它定义 `v0.1` lane 中哪些组件必须保留，哪些只作为 deferred 方向，以及单服务规格的后续拆分边界。
|
||
|
||
`docs/reference/spec-v01-*.md` 是 `v0.1` 服务、CLI、CI/CD 和系统能力的权威出处。代码开发和测试编写必须先对齐对应 spec，再修改实现或测试。
|
||
|
||
## 在系统中的职责划分
|
||
|
||
AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`v0.1` 只做最小纵向闭环，不替换 UniDesk Code Queue，也不替换 HWLAB 现有 Code Agent 路径。
|
||
|
||
- `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` 只要求一个真实 Agent backend 形成闭环；其他 backend 不进入第一波实现。
|
||
- AgentRun CLI 是受控操作入口，负责创建 run、提交 command、轮询 events、手动启动 runner 和查看 backend capability；CLI 不等待完整模型 turn。
|
||
- Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。
|
||
|
||
## 内部架构
|
||
|
||
`v0.1` 的最小链路如下：
|
||
|
||
```text
|
||
UniDesk or HWLAB client
|
||
-> agentrun-mgr REST API
|
||
-> durable run / command / event store
|
||
-> manual runner start
|
||
-> agentrun-runner
|
||
-> one backend adapter
|
||
-> normalized events / terminal status
|
||
-> agentrun-mgr
|
||
```
|
||
|
||
Runner inbound API 只允许本地或私有诊断，不作为业务客户端入口。业务客户端只能调用 `agentrun-mgr`。
|
||
|
||
## 服务总表
|
||
|
||
| 对象 | 类型 | v0.1 处理 | 说明 | 后续单独 spec |
|
||
| --- | --- | --- | --- | --- |
|
||
| `agentrun-mgr` | 长驻服务 | 保留，P0 | 公共 RESTful API、durable facts、idempotency、runner claim、event append 和 status authority。 | `spec-v01-agentrun-mgr.md` |
|
||
| `agentrun-runner` | 短生命周期执行入口 | 保留，P0 | per-run/per-attempt executor；claim run、poll command、调用 backend、写回 events/status。 | `spec-v01-agentrun-runner.md` |
|
||
| Backend adapter | 执行适配层 | 保留，P0 | 统一 backend capability、event normalization、error mapping 和 credential boundary。 | `spec-v01-backend-adapter.md` |
|
||
| First real backend | 具体 Agent backend | 保留，P0 | `v0.1` 必须至少证明一个真实 Agent backend；默认候选是 Codex。 | `spec-v01-backend-codex.md` |
|
||
| AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` |
|
||
| Durable store | 数据存储 | 保留，P0 | 保存 runs、commands、events、runners、backends、leases；具体存储可从 file/sqlite/Postgres 起步，但必须有迁移边界。 | `spec-v01-state-store.md` |
|
||
| Tenant policy boundary | 系统能力 | 保留，P0 | 显式承载 tenantId、projectId、workspaceRef、providerId、backendProfile、executionPolicy、traceSink。 | `spec-v01-tenant-policy.md` |
|
||
| Observability | 系统能力 | 保留，P1 | event、trace、log、redaction、terminal status 和 failure kind 统一观察。 | `spec-v01-observability.md` |
|
||
| `agentrun-scheduler` | 长驻调度器 | Deferred | M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 | `spec-v01-scheduler.md` |
|
||
| 多 backend 路由 | 系统能力 | Deferred | `v0.1` 不做完整多 backend 调度，只保留 capability 模型。 | 后续版本 spec |
|
||
| UI | 前端 | Deferred | `v0.1` 不要求独立 UI；UniDesk/HWLAB canary 可通过 CLI/API 验证。 | 后续版本 spec |
|
||
| judge/retry 自动化 | 系统能力 | Deferred | `v0.1` 只定义基础 terminal 和 failure visibility，不实现复杂 judge。 | 后续版本 spec |
|
||
|
||
## API 接口说明
|
||
|
||
Manager 公共 API 的 `v0.1` 初始范围：
|
||
|
||
```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 的 `v0.1` 初始范围：
|
||
|
||
```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
|
||
```
|
||
|
||
`v0.1` 禁止用 SSE、WebSocket、long-polling 或长同步 `turn` 请求替代 durable resource 模型。客户端通过分页轮询观察进度。
|
||
|
||
## MVP 分期
|
||
|
||
| 阶段 | 目标 | 验收重点 |
|
||
| --- | --- | --- |
|
||
| M0 | 契约骨架 | Run/Command/Event/Runner/Backend 资源模型和状态机可读。 |
|
||
| M1 | 最小 runner + 一个 backend | 一个 turn 经过真实 backend，assistant/output/error/terminal events 被归一化。 |
|
||
| M2 | manager + runner claim | run create/query durable，claim 拒绝双 owner，events append-only。 |
|
||
| M3 | 手动 dispatch CLI | CLI 快速返回 runner process/job identity、log path 和轮询命令。 |
|
||
| M4 | 自动 scheduler | Deferred；pending 自动派发和 stale lease recovery 进入后续实现。 |
|
||
| M5 | UniDesk/HWLAB canary | Deferred；只在核心生命周期稳定后接入窄范围 canary。 |
|
||
|
||
## 规格的实现情况
|
||
|
||
| 规格项 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| `v0.1` 服务总体规格 | 已定义 | 本文定义服务总览和取舍表。 |
|
||
| 文档治理规格 | 已定义 | 见 [spec-v01-documentation-governance.md](spec-v01-documentation-governance.md)。 |
|
||
| CI/CD lane 规格 | 已定义 | 见 [spec-v01-cicd.md](spec-v01-cicd.md)。 |
|
||
| `agentrun-mgr` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 |
|
||
| `agentrun-runner` 实现 | 未实现 | 需后续单服务 spec 和代码实现。 |
|
||
| 第一真实 backend | 未实现 | 默认候选 Codex，需后续 backend spec。 |
|
||
| 自动 scheduler | Deferred | 不作为 `v0.1` 第一阶段验收目标。 |
|