pikasTech-agentrun/docs/reference/spec-v01-services.md

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 的最小链路如下：

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
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	API Key 只通过 Kubernetes SecretRef、ServiceAccount/RBAC 和 runner env/file 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	最小事件/日志合同	保留，P0 子项	作为 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 调度，只保留 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 初始范围：

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 初始范围：

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	必填，例如 codex；v0.1 只要求一个真实 backend 闭环。
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 定义的 SecretRef 或 credential source，不能携带 API Key 明文。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。

最小 Observability 合同

v0.1 不拆出独立 spec-v01-observability.md，也不建设通用日志平台。可观察性只作为 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，然后使用 AgentRun CLI 手动测试创建 run、为该 run 启动 runner、轮询 events 并观察 terminal status。确认每个 CLI 命令都返回 JSON，包含 id 和后续命令，并且不会在单个请求中等待完整模型 turn。

T2 Command 与 Event 轮询

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

T3 日志与失败可见性

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

规格的实现情况

规格项	状态	说明
v0.1 服务总体规格	已定义	本文定义服务总览和取舍表。
文档治理规格	已定义	见 spec-v01-documentation-governance.md。
CI/CD lane 规格	已定义	见 spec-v01-cicd.md。
Postgres durable store 规格	已定义	见 spec-v01-postgres.md。
Secret 分发规格	已定义	见 spec-v01-secret-distribution.md。
agentrun-mgr 实现	未实现	需后续单服务 spec 和代码实现。
agentrun-runner 实现	未实现	需后续单服务 spec 和代码实现。
第一真实 backend	未实现	默认候选 Codex，需后续 backend spec。
自动 scheduler	Deferred	不作为 v0.1 第一阶段验收目标。