docs: 固化运行时装配SPEC

This commit is contained in:
Codex
2026-06-02 00:06:25 +08:00
parent bae2e97139
commit 7b8f5ae518
5 changed files with 73 additions and 17 deletions
+3 -3
View File
@@ -12,7 +12,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`
- `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 capabilityCLI 不等待完整模型 turn。
- RuntimeAssembly 是 runner/backend 启动前的四要素装配模型,负责把 backend image、profile、sessionGit-only resource bundle 统一成受控 Job 输入;四要素权威规格见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
- RuntimeAssembly 是 runner/backend 启动前的装配 SPEC,负责把 backend image、profile credential、sessionGit-only resource bundle 和 tool credential scope 统一成受控 Job 输入;装配权威规格见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
- AgentRun Queue 是吸收 UniDesk Code Queue 的任务队列层,负责 task、attempt、retry、judge、summary、stats、read cursor 和 commander 聚合;Queue 查询只返回 Session 引用,输出和 trace 进入 Session API/CLI。权威规格见 [spec-v01-queue.md](spec-v01-queue.md)。
- Scheduler 是后续自动派发能力;`v0.1` 可以保留规格和状态字段,但不把自动调度作为第一阶段验收目标。
@@ -84,7 +84,7 @@ Runner inbound API 只允许本地或私有诊断,不作为业务客户端入
| 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 projectionsource、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` |
| RuntimeAssembly | 系统能力 | 保留,P0 规格 | runner/backend 启动前的四要素装配模型`BackendImageRef``ProfileRef``SessionRef`Git-only `ResourceBundleRef`ProfileRef、SessionRef 和 ResourceBundleRef 已具备 v0.1 最小实现。 | `spec-v01-runtime-assembly.md` |
| RuntimeAssembly | 系统能力 | 保留,P0 规格 | runner/backend 启动前的装配 SPEC`BackendImageRef``ProfileRef``SessionRef`Git-only `ResourceBundleRef` 和 tool credential SecretRef scopeProfileRef、SessionRef 和 ResourceBundleRef 已具备 v0.1 最小实现tool credential 待实现。 | `spec-v01-runtime-assembly.md` |
| HWLAB 手动调度接入 | canary 集成目标 | 保留,P0 规格 | HWLAB `hwlab-cloud-api` 显式创建 run/command 并调用 runner Job APIAgentRun 提供 durable facts、events、cancel、bundle 和 session 能力。 | `spec-v01-hwlab-manual-dispatch.md` |
| Tenant policy boundary | Run schema 合同 | 保留,P0 | 作为 `Run` 的必填字段和最小校验存在,不做独立 policy enginetenant 的业务授权仍由 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` |
@@ -138,7 +138,7 @@ Run create 的最小字段合同:
| `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 不把这些业务规则内建成通用门禁。
Manager 负责校验、保存和返回这些字段;runner 只能消费已保存的 run policy,不能自行扩大 workspace、network 或 secret scope。`executionPolicy.secretScope` 只能引用装配 SPEC 和 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 定义的 SecretRef 或 credential source,不能携带 provider/tool credential 明文。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定,AgentRun 不把这些业务规则内建成通用门禁。
## 最小 Observability 合同