# 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` 使用一个真实 Codex stdio backend kind 形成闭环，并在该 kind 下支持 `codex` 与 `deepseek` profile；其他 backend kind 不进入第一波实现。
- AgentRun CLI 是受控操作入口，负责创建 run、提交 command、轮询 events、手动启动 runner 和查看 backend capability；CLI 不等待完整模型 turn。
- Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。

## 语言与协议选型

AgentRun `v0.1` 的自研组件优先使用 Bun + TypeScript 实现：`agentrun-mgr`、`agentrun-runner`、backend adapter、Codex backend、AgentRun CLI 和后续 scheduler 都属于该边界。官方 TypeScript CLI 入口固定为 `scripts/agentrun-cli.ts`，入口只做参数解析和路由，复杂逻辑拆到 `scripts/src/` 与 `src/`；G14/CI/人工非交互命令使用 `./scripts/agentrun` launcher 启动同一入口。Postgres、Kubernetes、Tekton、Argo CD、YAML manifest 和 shell 级容器启动命令属于外部运行面或部署面，不受“必须 TypeScript 实现”的约束。

`backendProfile=codex` 与 `backendProfile=deepseek` 的 `v0.1` 协议固定为同一个 Codex CLI app-server JSON-RPC over stdio backend kind：runner/backend adapter 启动受控 `codex app-server --listen stdio://` 子进程，经 stdin/stdout 发送换行分隔 JSON-RPC，请求顺序至少覆盖 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`。`backendProfile` 只选择 profile/config/SecretRef；`backendKind`、`protocol` 和进程生命周期仍是 `codex-app-server-stdio`。直接调用 Responses HTTP、OpenAI SDK、`codex exec` 一次性输出或文本 fallback 只能作为诊断/自测试辅助，不能作为 Codex backend 综合联调通过证据。

实现参考必须优先读取并吸收两个成熟代码路径：UniDesk Code Queue 的 Bun/TS `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 复用的是 stdio JSON-RPC、session/turn 生命周期、trace、redaction、Secret projection、profile overlay、DeepSeek/Moon Bridge 分层诊断和 failureKind 经验，不复制 UniDesk/HWLAB 的环境专用路径、业务 prompt、bridge host、namespace 或明文凭据。

## Backend Profile 边界

`v0.1` 需要支持两个可手动选择的 backend profile，但不引入完整多 backend 调度：

| backendProfile | backendKind | v0.1 处理 | SecretRef | 说明 |
| --- | --- | --- | --- | --- |
| `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`。

`codex` 与 `deepseek` 之间不得隐式 fallback：缺少 `deepseek` SecretRef 时必须失败为 `secret-unavailable`，不能改用 `codex` Secret；`deepseek` 运行失败也不能重试到 `codex`。同一轮发布的综合联调必须证明 `codex -> deepseek -> codex` 的切换不会污染彼此的 SecretRef、`CODEX_HOME`、模型或 upstream 配置。

## 内部架构

`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` 默认会由多个 agent 并行实现 manager、runner、backend、Secret、Postgres、CLI 和 CI/CD。架构必须主动降低并行冲突，而不是把所有组件都写进同一个入口文件、总表或巨型测试文件。

并行开发的长期规则：

- 组件实现按目录分层：manager 写入 `src/mgr/**`，runner 写入 `src/runner/**`，backend 写入 `src/backend/**`，CLI 写入 `scripts/src/**`，部署写入 `deploy/**`。跨组件共享类型和工具只放 `src/common/**`，且变更必须保持小而稳定。
- 自测试采用可发现 case 模型：`src/selftest/run.ts` 只负责发现和调度，公共 fixture 放 `src/selftest/harness.ts`，组件测试放 `src/selftest/cases/*.ts`。新增组件自测试应优先新增 case 文件，不应反复修改总入口。
- 长期文档状态归属到对应 spec：组件实现状态优先维护在 `spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`、`spec-v01-backend-codex.md` 等组件 spec 中；`spec-v01-services.md` 只保留总览和跨组件边界，避免成为并行改动热点。
- 对并行冲突的处理优先优化模块边界：如果多个 PR 反复冲突在同一文件或同一段状态表，应拆出可独立追加的模块、case、manifest、helper 或 spec 子项；只有确认边界已经合理后，才做普通冲突解析。
- 共享 API 合同要先稳定再并行扩展：`RunRecord`、`CommandRecord`、`ExecutionPolicy`、`SecretRef`、`FailureKind` 等跨组件类型改动必须兼顾 manager、runner、backend、CLI、self-test 和 GitOps render，不得为单个组件引入临时字段绕开合同。
- 过程性合并、冲突解析和临时验证证据进入 PR/issue；长期参考文档只记录稳定的并行开发原则、边界和判断标准。

## 服务总表

| 对象 | 类型 | 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` |
| Codex stdio backend profiles | 具体 Agent backend | 保留，P0 | `v0.1` 使用一个真实 Codex app-server stdio backend kind，必须支持 `codex` 与 `deepseek` 两个 profile；完整多 backend 路由仍 deferred。 | `spec-v01-backend-codex.md` |
| AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` |
| Postgres durable store | 稳定外部服务 | 保留，P0 | 使用 `agentrun-v01-postgres` 保存 runs、commands、events、runners、backends、leases 和 migration ledger；不使用 file/sqlite 作为 v0.1 durable store。 | `spec-v01-postgres.md` |
| Secret distribution | 系统能力 | 保留，P0 | Provider credential 只通过 Kubernetes SecretRef、ServiceAccount/RBAC 和 runner env/file projection 分发；Codex 测试凭据使用 `~/.codex/auth.json` 与 `~/.codex/config.toml` 生成 Secret projection；source、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` |
| 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 |
| 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 模型。客户端通过分页轮询观察进度。

## Run Schema 和 Tenant 边界

`v0.1` 不实现复杂 tenant policy engine，但每个 run 必须显式承载租户边界字段，避免后续 UniDesk/HWLAB canary 接入时无法追责或隔离。

Run create 的最小字段合同：

| 字段 | v0.1 规则 |
| --- | --- |
| `tenantId` | 必填，例如 `unidesk`、`hwlab`；只做 allowlist/schema 校验。 |
| `projectId` | 必填，例如 `pikasTech/unidesk`、`pikasTech/HWLAB`。 |
| `workspaceRef` | 必填，描述 source/worktree/workspace，不由 runner 猜测。 |
| `providerId` | 必填，例如 `G14`、`D601`；只表示目标 provider，不直接授予权限。 |
| `backendProfile` | 必填，`v0.1` allowlist 为 `codex` 与 `deepseek`；两者共享 `codex-app-server-stdio` backend kind。 |
| `executionPolicy` | 必填或由 manager 显式写入默认值，至少包含 sandbox、approval、timeout、network 和 secret scope。 |
| `traceSink` | 字段必须存在；可以为 `null` 或显式 sink，表示标准事件是否需要镜像给 tenant。 |

Manager 负责校验、保存和返回这些字段；runner 只能消费已保存的 run policy，不能自行扩大 workspace、network 或 secret scope。`executionPolicy.secretScope` 只能引用 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 定义的 SecretRef 或 credential source，不能携带 provider credential 明文。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。

## 最小 Observability 合同

`v0.1` 不拆出独立观测规格文件，也不建设通用日志平台。可观察性只作为 run 生命周期的一部分：

- `events` 必须 append-only，并按 `seq` 分页读取。
- 每个 run 必须最终写出 `terminal_status` 或明确的 non-terminal status。
- runner 启动失败、backend 失败、policy/schema 失败必须写入结构化 `failureKind`。
- CLI 启动本地 process 或 Kubernetes Job 时必须返回 `logPath` 或 Kubernetes job/pod identity。
- event 和日志不得打印 Secret/token 值；只能记录 SecretRef、credential source 或 redacted marker。
- redaction 规则只覆盖明显 credential、token、Authorization header 和 URL credential；复杂审计、集中 trace、metrics dashboard 推迟到后续版本。

## 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。 |

## 测试规格

### T1 最小 Run 生命周期

阅读 `AGENTS.md`、本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后使用 AgentRun CLI 手动测试创建 run、为该 run 启动 runner、轮询 events 并观察 terminal status。确认每个 CLI 命令都返回 JSON，包含 id 和后续命令，并且不会在单个请求中等待完整模型 turn。

### T2 Command 与 Event 轮询

阅读 `AGENTS.md`、本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后创建 run command，并轮询 command status 与 run events。确认 command state 可见，event pagination 使用 `afterSeq`，重复轮询不会产生重复 event。

### T3 日志与失败可见性

阅读 `AGENTS.md`、本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后用一个故意无效的 backend profile 启动本地服务或 runner。确认 CLI 返回结构化失败，输出 log path，并且日志文件包含足够定位失败原因的信息。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| `v0.1` 服务总体规格 | 已定义 | 本文定义服务总览和取舍表。 |
| 文档治理规格 | 已定义 | 见 [spec-v01-documentation-governance.md](spec-v01-documentation-governance.md)。 |
| CI/CD lane 规格 | 已定义 | 见 [spec-v01-cicd.md](spec-v01-cicd.md)。 |
| Postgres durable store 规格 | 已定义 | 见 [spec-v01-postgres.md](spec-v01-postgres.md)。 |
| Secret 分发规格 | 已定义 | 见 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。 |
| 两层验证规格 | 已定义 | 见 [spec-v01-validation.md](spec-v01-validation.md)。 |
| `agentrun-mgr` 服务规格 | 已定义 | 见 [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)。 |
| `agentrun-runner` 服务规格 | 已定义 | 见 [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)。 |
| Backend adapter 规格 | 已定义 | 见 [spec-v01-backend-adapter.md](spec-v01-backend-adapter.md)。 |
| Codex backend 规格 | 已定义 | 见 [spec-v01-backend-codex.md](spec-v01-backend-codex.md)。 |
| AgentRun CLI 规格 | 已定义 | 见 [spec-v01-cli.md](spec-v01-cli.md)。 |
| Scheduler deferred 规格 | 已定义 | 见 [spec-v01-scheduler.md](spec-v01-scheduler.md)。 |
| `agentrun-mgr` 实现 | 已实现/已通过主闭环 | 已有 REST API、Postgres durable store、migration ledger、runner claim/lease/report、health/readiness 和 self-test memory 模式；真实 `agentrun-v01` runtime 已通过 Postgres/GitOps/readiness 和 run lifecycle 主闭环。 |
| `agentrun-runner` 实现 | 已实现/已通过主闭环 | host process runner 与 Kubernetes Job 共用 `runOnce`，runner 通过 manager API claim/poll/report，不直连 Postgres；真实 Kubernetes Job 已完成 Codex turn。 |
| `codex` profile | 已实现/已通过主闭环 | Codex app-server stdio backend 已有协议、失败分类、脱敏和 fake self-test；真实 Codex provider turn 已通过 RESTful API 与 CLI 主闭环。 |
| `deepseek` profile | 已定义/待实现 | 规格要求 DeepSeek 作为同一 Codex stdio backend kind 的 profile/config/SecretRef 选择进入 v0.1；实现和真实联调尚未完成。 |
| 自动 scheduler | Deferred | 不作为 `v0.1` 第一阶段验收目标。 |