diff --git a/AGENTS.md b/AGENTS.md index da0fc1f..3cd5d38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、source worktree、namespace、GitOps、registry、CI/CD 和发布验收规格。 - `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。 - `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent provider credential 和运行时 Secret 分发规格。 +- `docs/reference/spec-v01-runtime-assembly.md`：v0.1 runner/backend 启动前的四要素 RuntimeAssembly 装配模型，覆盖 BackendImageRef、ProfileRef、SessionRef 和 Git-only ResourceBundleRef。 - `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。 - `docs/reference/spec-v01-agentrun-mgr.md`：v0.1 manager REST API、tenant boundary、runner claim 和 event/status authority。 - `docs/reference/spec-v01-agentrun-runner.md`：v0.1 短生命周期 runner、claim/poll/report、日志和 failureKind。 diff --git a/docs/reference/spec-v01-agentrun-runner.md b/docs/reference/spec-v01-agentrun-runner.md index 86a4cb9..99769f1 100644 --- a/docs/reference/spec-v01-agentrun-runner.md +++ b/docs/reference/spec-v01-agentrun-runner.md @@ -7,6 +7,7 @@ - 作为 Kubernetes Job 或受控 host process 启动；不作为普通业务客户端直接调用的长驻公共服务。 - 从 manager register、claim run、续租 lease、poll commands、ack command、append events、patch status。 - 根据 run 中的 `backendProfile` 和 `executionPolicy.secretScope` 调用 backend adapter。 +- 根据 manager 解析出的 RuntimeAssembly materialize backend image、profile Secret、session 和初始资源；四要素字段权威见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，本文只规定 runner 消费边界。 - 将 backend stdout/stderr、assistant message、tool call、error 和 terminal status 归一化为 manager event。 - 提供可定位的 job/process identity、logPath、attempt id 和 failureKind。 - 不直连 Postgres，不扩大 workspace、network、approval 或 secret scope。 @@ -29,6 +30,8 @@ Runner Secret 只能通过 Kubernetes Secret projection、ServiceAccount/RBAC Kubernetes Job runner 必须把 credential source 与 runtime home 分开：Secret volume 只读挂在 `/var/run/agentrun/secrets/...`，`/home/agentrun` 由 `emptyDir` 提供可写空间，`CODEX_HOME` 指向当前 run/profile 的 writable runtime home，`AGENTRUN_CODEX_SECRET_HOME` 指向当前 `backendProfile` 对应的只读 projection。runner/backend 在启动 provider 前只复制授权文件，不打印内容。`codex` 与 `deepseek` profile 不得共享同一个可写 runtime home，除非它们运行在不同的 per-run Kubernetes Job 且该目录由 Job 独占 emptyDir 提供。 +RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 Git-only；runner 后续实现资源 materialization 时只能 checkout 到允许 workspace 前缀，并记录 commit/tree 摘要，不能把用户上传文件或 env dump 混入 Git-only bundle。 + Kubernetes Job runner 必须设置有限保留时间。`v0.1` 默认 `ttlSecondsAfterFinished=86400`，用于保留最近完成 Job 的调试窗口，同时避免长期堆积 `Completed` runner Job 污染运行面观察。该 TTL 是 Job manifest 的运行面属性，不是 CI/CD 门禁；需要延长保留时间时必须通过受控 Job render/input 显式覆盖，并在 issue 或 PR 中说明原因。 ## Runner 生命周期 diff --git a/docs/reference/spec-v01-backend-adapter.md b/docs/reference/spec-v01-backend-adapter.md index 38f6315..c428c1f 100644 --- a/docs/reference/spec-v01-backend-adapter.md +++ b/docs/reference/spec-v01-backend-adapter.md @@ -26,6 +26,8 @@ redact(value) -> redacted value Adapter 输入必须来自 manager 保存的 run/command 和 Kubernetes Secret projection；不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。`resolveProfile(profile)` 必须返回 profile、backendKind、protocol、transport、command、requiredSecretKeys 和 isolation policy；不得把 unknown profile 静默映射到默认 `codex`。 +Backend adapter 消费 RuntimeAssembly 中的 `BackendImageRef` 和 `ProfileRef` 结果，但不定义四要素字段；四要素权威见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。 + `v0.1` 的第一真实 adapter 是 Codex stdio adapter。它必须走 Codex CLI app-server JSON-RPC over stdio；adapter 合同把 Codex 的 thread、turn、notification、tool lifecycle 和 stderr/exit 信息归一化为 AgentRun 标准 events。`codex` 与 `deepseek` 只是该 adapter 的 profile/config/SecretRef 选择，不允许复制两套协议实现。 ## Backend Profile Registry diff --git a/docs/reference/spec-v01-cicd.md b/docs/reference/spec-v01-cicd.md index 6d08452..5ed22c6 100644 --- a/docs/reference/spec-v01-cicd.md +++ b/docs/reference/spec-v01-cicd.md @@ -117,6 +117,8 @@ Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired st ## Artifact 与镜像身份 +镜像身份同时是 RuntimeAssembly 的 `BackendImageRef` 来源；四要素总模型见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。本文只定义 image digest、artifact catalog 和 GitOps promotion 边界，不定义 profile、session 或 resource bundle 字段。 + - `v0.1` 镜像 tag 使用完整 40 位 source commitId。 - Runtime manifest 必须使用 digest pin 作为部署身份；G14 本地 registry 对同一 tag 的默认 HEAD 可能返回 Docker schema1 compatibility digest，Tekton 必须用 `Accept: application/vnd.docker.distribution.manifest.v2+json` 采集 containerd 可直接拉取的 schema2 manifest digest，并在写入 catalog 前按 digest HEAD 验证。 - Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、image tag、digest、component identity 和 publish/reuse 状态。 diff --git a/docs/reference/spec-v01-documentation-governance.md b/docs/reference/spec-v01-documentation-governance.md index cb2f832..58b4053 100644 --- a/docs/reference/spec-v01-documentation-governance.md +++ b/docs/reference/spec-v01-documentation-governance.md @@ -29,6 +29,7 @@ - `spec-v01-cicd.md`：版本 lane、GitOps、namespace、registry 和发布验收。 - `spec-v01-postgres.md`：Postgres durable store、schema migration 和 DB SecretRef。 - `spec-v01-secret-distribution.md`：Code Agent provider credential、Postgres DSN 和运行时 Secret 分发。 +- `spec-v01-runtime-assembly.md`：runner/backend 启动前的四要素 RuntimeAssembly 装配模型；其他 spec 只交叉引用，不重复定义四要素字段。 - `spec-v01-validation.md`：两层验证模型、自测试和综合联调验收。 - `spec-v01-agentrun-mgr.md`：manager REST API、tenant boundary、runner claim、event/status authority。 - `spec-v01-agentrun-runner.md`：短生命周期 runner、claim/poll/report、日志和 failureKind。 @@ -70,7 +71,7 @@ ## 验收标准 - `AGENTS.md` 索引本文和其他 `spec-v01-*` 规格。 -- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md`、`spec-v01-secret-distribution.md`、`spec-v01-validation.md`、`spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`、`spec-v01-backend-adapter.md`、`spec-v01-backend-codex.md`、`spec-v01-cli.md` 和 `spec-v01-scheduler.md`。 +- `docs/reference/` 中存在 `spec-v01-documentation-governance.md`、`spec-v01-services.md`、`spec-v01-cicd.md`、`spec-v01-postgres.md`、`spec-v01-secret-distribution.md`、`spec-v01-runtime-assembly.md`、`spec-v01-validation.md`、`spec-v01-agentrun-mgr.md`、`spec-v01-agentrun-runner.md`、`spec-v01-backend-adapter.md`、`spec-v01-backend-codex.md`、`spec-v01-cli.md` 和 `spec-v01-scheduler.md`。 - `AGENTS.md` 和 `docs/reference/` 不得把旧 `agentrun_dev`、`agentrun_prod`、`G14:/root/agentrun` 或 `/root/agentrun` 写成当前 source worktree、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。 - `docs/` 根目录不新增临时 Markdown 报告或 JSON dump。 - 仓库根目录不存在 `TEST.md`；测试场景维护在对应 `spec-v01-*.md` 的“测试规格”小节。 diff --git a/docs/reference/spec-v01-runtime-assembly.md b/docs/reference/spec-v01-runtime-assembly.md new file mode 100644 index 0000000..ca06c15 --- /dev/null +++ b/docs/reference/spec-v01-runtime-assembly.md @@ -0,0 +1,229 @@ +# v0.1 Runtime Assembly 规格 + +本文定义 AgentRun `v0.1` runner Job 启动前的四要素装配模型。`RuntimeAssembly` 是 manager 侧把 run intent 转换成可执行 runner/backend runtime 的权威视图；它只表达引用、hash、路径、权限、生命周期和脱敏策略，不携带 Secret value 或大文件正文。 + +## 设计目标 + +- 把 backend 镜像、provider profile、会话持久化和初始资源注入收敛为四个一等要素。 +- 避免 runner 从隐式环境、host path、默认 home、可变 tag 或用户 payload 猜测运行时输入。 +- 让 CI/CD、Secret、session、workspace 和 resource 注入各自有边界，但统一进入同一个装配计划。 +- 把 identity、network、observability、GC、failureKind、provenance 等横切能力归并为四要素上的 policy、metadata、status 或 lifecycle 子项，不扩成并列的一等对象。 + +## 四要素模型 + +`RuntimeAssembly` 的一等要素固定为： + +| 要素 | 职责 | v0.1 P0 边界 | 权威/引用 | +| --- | --- | --- | --- | +| `BackendImageRef` | 决定用什么 backend runtime image 和 command 能力。 | 使用 CI/CD 产出的 digest-pinned image；当前可复用 agentrun runner image，后续可拆独立 backend image。 | [spec-v01-cicd.md](spec-v01-cicd.md) | +| `ProfileRef` | 决定 provider/profile 配置和 API KEY SecretRef。 | `codex`、`deepseek` 使用 profile-scoped Kubernetes SecretRef；Secret value 不进 run payload。 | [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) | +| `SessionRef` | 决定是否恢复或保存 backend 会话状态。 | P0 可以为 `null`；只定义边界，不把完整 `CODEX_HOME` 持久化。 | 本文 | +| `ResourceBundleRef` | 决定 backend 启动前 materialize 哪份代码和非敏感 repo 文件。 | P0 收敛为 Git-only，由 Git URL、full commit id 和 checkout policy 决定内容身份。 | 本文 | + +`executionPolicy` 和 `observabilityPolicy` 是装配规则，不是新的 runtime material。它们可以约束四要素如何被装配、观察和清理，但不得替代四要素本身。 + +最小形态： + +```json +{ + "backendImageRef": {}, + "profileRef": {}, + "sessionRef": null, + "resourceBundleRef": {}, + "executionPolicy": {}, + "observabilityPolicy": {} +} +``` + +## 装配顺序 + +Manager 创建或触发 runner Job 前必须按固定顺序解析装配计划： + +1. 根据 run 的 `backendProfile` 解析 `backendKind` 和 `ProfileRef`。 +2. 根据 `backendKind` 和 lane catalog 解析 `BackendImageRef`，得到 digest-pinned image。 +3. 根据 run/session intent 解析 `SessionRef`；P0 无持久 session 时显式为 `null`。 +4. 根据 run 的 workspace/resource intent 解析 `ResourceBundleRef`；P0 必须是 Git-only。 +5. 合并 `executionPolicy` 与 allowlist，生成 Kubernetes Job 的 env、volume、init/prepare intent 和 resource limit。 +6. 生成可写 runtime home、workspace 和可选 session mount；Secret projection 始终只读。 +7. runner/backend 启动后把 image digest、profile name、SecretRef 名称/key、session id、resource commit/hash 和 redaction 状态写入 event metadata，但不写入 Secret value。 + +Runner 不得自行选择不同 image、Secret、PVC、host path 或 Git ref；任何缺失或不匹配都应按对应要素失败，而不是 fallback 到默认值。 + +## BackendImageRef + +`BackendImageRef` 表达 backend runtime 能力和镜像身份。P0 允许 manager 和 runner/backend 共用同一镜像；即使共用，也必须在装配计划中把实际 image digest 作为 backend image identity 记录。 + +建议字段： + +```json +{ + "backendKind": "codex-app-server-stdio", + "image": "127.0.0.1:5000/agentrun/agentrun-mgr@sha256:...", + "sourceCommit": "<40-char source commit>", + "command": ["bun", "src/runner/main.ts"], + "backendCommand": ["codex", "app-server", "--listen", "stdio://"], + "resourceProfile": { "cpu": "2", "memory": "4Gi" }, + "provenance": { "catalog": "deploy/artifact-catalog.v01.json" } +} +``` + +规则： + +- image 必须来自 Tekton artifact catalog 或 manager allowlist；客户端 run payload 不得直接提供任意 image。 +- 正式 runtime manifest 必须使用 digest pin，不以 mutable tag 作为执行身份。 +- 镜像只表达 runtime 能力，不包含 API KEY、profile config、session 文件或用户 code。 +- image pull、digest 缺失或 capability 不匹配应归类为 image/infra failure，不得被记录为 provider auth failure。 + +## ProfileRef + +`ProfileRef` 表达 provider/profile 配置和 credential 边界。P0 中 `codex` 与 `deepseek` 都是 `codex-app-server-stdio` backend kind 的 profile/config/SecretRef 选择。 + +建议字段： + +```json +{ + "profile": "deepseek", + "backendKind": "codex-app-server-stdio", + "secretRefs": [ + { "name": "agentrun-v01-provider-deepseek", "keys": ["auth.json", "config.toml"] } + ], + "runtimeHome": "/home/agentrun/.codex-deepseek", + "redactionPolicy": "provider-credential-v1" +} +``` + +规则： + +- API KEY、Codex `auth.json`、Codex `config.toml` 和 provider token 只通过 SecretRef 注入。 +- 非敏感 provider config 可以保存在 profile registry、ConfigMap 或 Postgres capability 中；credential value 不得进入 ConfigMap。 +- Secret projection 是只读 credential source；需要 writable home 的 backend 必须复制到 per-run/profile runtime home。 +- profile 缺失或 SecretRef 不匹配必须 `secret-unavailable`；`deepseek` 不得 fallback 到 `codex`。 +- network、proxy、NO_PROXY、rate limit 和 provider readiness 默认归并到 `ProfileRef` 的 policy/status 子项。 + +## SessionRef + +`SessionRef` 表达可恢复的 backend 会话状态，不等同于 Postgres durable facts。Postgres 保存 run、command、event、terminal status、lease 和 session metadata；backend session 文件应保存到 PVC 或后续对象存储。 + +P0 允许无持久 session： + +```json +{ + "sessionRef": null, + "persistence": "none" +} +``` + +后续建议字段： + +```json +{ + "sessionId": "sess_...", + "tenantId": "unidesk", + "projectId": "pikasTech/unidesk", + "backendKind": "codex-app-server-stdio", + "backendProfile": "codex", + "pvcRef": { "namespace": "agentrun-v01", "name": "agentrun-session-sess-..." }, + "schemaVersion": "codex-stdio-session-v1", + "retentionPolicy": "debug-short" +} +``` + +规则： + +- `SessionRef` 不保存 API KEY；每次 run 的 credential 仍从 `ProfileRef` 重新投影。 +- 不直接持久化完整 `CODEX_HOME`，因为该目录可能混合 credential、config、session/cache。 +- session 文件、workspace、profile credential 必须是不同目录或 volume。 +- local-path/RWO PVC 会限制恢复节点；跨节点恢复需要 RWX 存储或对象存储，必须在后续 spec 中明确。 +- session 挂载失败、版本不兼容或 restore 失败应归类为 session failure，不得归为 provider failure。 + +## ResourceBundleRef + +`ResourceBundleRef` 表达 backend 启动前注入哪份代码和非敏感 repo 文件。P0 收敛为 Git-only，不支持上传文件、对象存储 artifact、inline env 或任意 ConfigMap/Secret 文件袋。 + +P0 字段： + +```json +{ + "type": "git", + "repoUrl": "git@github.com:pikasTech/unidesk.git", + "commitId": "", + "subdir": ".", + "checkoutPolicy": { + "submodules": false, + "lfs": false, + "sparsePaths": [] + }, + "credentialRef": null, + "materializedTreeHash": null +} +``` + +规则： + +- 内容身份由 `repoUrl + commitId + subdir + sparsePaths` 决定；commit id 必须是不可变 full commit sha。 +- `credentialRef` 只用于拉取私有仓库，不参与内容身份，也不得暴露给 backend。 +- `submodules` 和 `lfs` 默认 false；启用时必须进入验收和凭据边界。 +- checkout 后应记录 `materializedTreeHash` 或等价摘要，确认实际 workspace 与期望 commit/subdir 一致。 +- API KEY、provider token、Codex auth/config 属于 `ProfileRef`，不得放进 Git-only bundle。 +- backend session/cache 属于 `SessionRef`，不得放进 Git-only bundle。 +- 动态用户 env 属于 `executionPolicy` 的 allowlisted overlay，不作为 ResourceBundle 内容身份。 +- 大型外部 artifact、上传文件、对象存储和任意 ConfigMap 文件注入都 deferred；后续必须显式扩展，不得把 P0 Git-only 模型变成万能资源袋。 + +## 横切能力归并 + +横切能力必须挂到四要素或 run policy 上： + +| 横切能力 | 归并位置 | +| --- | --- | +| identity/tenant | run、session、resource 和 profile 的 owner/scope/grant 字段。 | +| scheduling/resource | `BackendImageRef.resourceProfile` 与 `executionPolicy`。 | +| network/egress | 主要属于 `ProfileRef`，少量属于 `ResourceBundleRef` fetch policy。 | +| observability | 四要素 materialization 的 event/status metadata。 | +| lifecycle/GC | session、resource、run/job 和 image artifact 各自的 retention policy。 | +| failureKind | 按失败发生在哪个要素归类。 | +| provenance | image digest、profile config hash、session snapshot version、resource commit/tree hash。 | + +## FailureKind 归属 + +| 失败位置 | 建议 failureKind | 说明 | +| --- | --- | --- | +| Backend image pull/capability | `infra-failed` 或后续 `image-unavailable` | 镜像不存在、digest 不可拉取、backendKind 不匹配。 | +| Profile SecretRef | `secret-unavailable` | Secret 缺失、RBAC 拒绝、缺 `auth.json`/`config.toml`。 | +| Provider auth/upstream | `provider-auth-failed`、`provider-unavailable` | 已成功 materialize profile，但上游拒绝或不可用。 | +| Session mount/restore | `infra-failed` 或后续 `session-unavailable` | PVC 不可挂载、schema 不兼容、restore 失败。 | +| Resource checkout/materialization | `schema-invalid`、`infra-failed` 或后续 `resource-unavailable` | Git URL/commit 非法、checkout 失败、tree hash 不匹配。 | + +新增细分 failureKind 前必须同步 manager、runner、backend、CLI、self-test 和 validation spec；P0 可以先用现有 failureKind 并在 event payload 中标明 `assemblyElement`。 + +## 测试规格 + +### T1 RuntimeAssembly 字段完整性 + +阅读本文和 [spec-v01-services.md](spec-v01-services.md)，然后检查 run/runner Job 创建路径是否能明确追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef`。P0 中尚未实现的 `SessionRef` 和 Git-only `ResourceBundleRef` 必须显式为 `null` 或 deferred 状态，而不是由 runner 隐式猜测。 + +### T2 BackendImageRef digest 固定 + +阅读本文和 [spec-v01-cicd.md](spec-v01-cicd.md)，然后检查 Tekton artifact catalog、GitOps runtime manifest 和实际 Deployment/Job image，确认 runner/backend 使用 digest-pinned image，并能追溯 source commit。 + +### T3 ProfileRef Secret 隔离 + +阅读本文、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 和 [spec-v01-backend-codex.md](spec-v01-backend-codex.md)，然后分别执行 `backendProfile=codex` 与 `backendProfile=deepseek` 的真实 runner Job。确认当前 run 只挂载匹配 profile 的 SecretRef，runtime home 独立，缺失 profile SecretRef 不 fallback。 + +### T4 SessionRef 与 credential 分离 + +阅读本文，然后在引入 session 持久化前确认 P0 runner Job 不把完整 `CODEX_HOME` 持久化到 PVC 或 hostPath。后续实现 session PVC 时，必须证明 session 目录不包含 API KEY、Codex auth/config 或 provider token。 + +### T5 Git-only ResourceBundle + +阅读本文，然后用 Git URL、full commit id 和 subdir 创建资源装配计划。确认 checkout 发生在允许 workspace 前缀内，记录 materialized tree 摘要，且 run payload 不携带文件正文、Secret value 或任意 env dump。 + +## 规格的实现情况 + +| 规格项 | 状态 | 说明 | +| --- | --- | --- | +| RuntimeAssembly 四要素模型 | 已定义 | 本文作为四要素装配模型权威；其他 spec 只引用，不重复定义。 | +| `BackendImageRef` | 部分实现 | 当前 runner/backend 复用 agentrun 镜像，CI/CD 已使用 digest-pinned runtime manifest；尚未拆独立 backend image registry。 | +| `ProfileRef` | 已实现/已通过主闭环 | `codex` 与 `deepseek` profile 已通过 Kubernetes SecretRef、writable runtime home 和真实 Codex stdio turn 验证。 | +| `SessionRef` | 已定义/P0 未持久化 | 当前 v0.1 只持久化 run facts，不持久化 backend session 文件；后续实现 PVC 或对象存储前必须保持 credential 分离。 | +| Git-only `ResourceBundleRef` | 已定义/待实现 | P0 规格收敛为 Git-only，尚未进入 runner Job materialization。 | +| 横切能力归并 | 已定义 | identity、network、observability、GC、failure 和 provenance 归并为四要素 policy/metadata/status/lifecycle 子项。 | diff --git a/docs/reference/spec-v01-secret-distribution.md b/docs/reference/spec-v01-secret-distribution.md index 8bd0856..b45b656 100644 --- a/docs/reference/spec-v01-secret-distribution.md +++ b/docs/reference/spec-v01-secret-distribution.md @@ -2,6 +2,8 @@ 本文定义 AgentRun `v0.1` 的 Secret 和 Code Agent provider credential 分发边界。真实 Code Agent backend 需要上游模型凭据；Codex stdio profile 测试凭据以 `~/.codex/auth.json` 与 `~/.codex/config.toml` 形态为输入源，通过 Kubernetes Secret 投影进入 runner/backend Pod。这些值不得进入 Git source、GitOps branch、artifact catalog、event、trace、日志或 CLI 输出。 +在 RuntimeAssembly 中，本文只承担 `ProfileRef` 的 SecretRef、projection、rotation 和 redaction 规则；四要素总模型见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。 + ## 设计目标 - API Key、Codex auth/config 等 provider credential 只通过 Kubernetes SecretRef 分发到需要它的 manager、runner 或 backend adapter。 diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md index bd7ec93..cfc44ca 100644 --- a/docs/reference/spec-v01-services.md +++ b/docs/reference/spec-v01-services.md @@ -12,6 +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 capability；CLI 不等待完整模型 turn。 +- RuntimeAssembly 是 runner/backend 启动前的四要素装配模型，负责把 backend image、profile、session 和 Git-only resource bundle 统一成受控 Job 输入；四要素权威规格见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。 - Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。 ## 语言与协议选型 @@ -76,6 +77,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 projection；source、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` | +| RuntimeAssembly | 系统能力 | 保留，P0 规格 | runner/backend 启动前的四要素装配模型：`BackendImageRef`、`ProfileRef`、`SessionRef` 和 Git-only `ResourceBundleRef`；P0 先定义模型，ProfileRef 已实现，SessionRef/ResourceBundleRef 按 deferred 子项推进。 | `spec-v01-runtime-assembly.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` | @@ -173,6 +175,7 @@ Manager 负责校验、保存和返回这些字段；runner 只能消费已保 | 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)。 | +| RuntimeAssembly 规格 | 已定义 | 见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.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)。 | diff --git a/docs/reference/spec-v01-validation.md b/docs/reference/spec-v01-validation.md index a80153f..1346176 100644 --- a/docs/reference/spec-v01-validation.md +++ b/docs/reference/spec-v01-validation.md @@ -57,6 +57,7 @@ 6. manager 可查询 command state、append-only events、terminal_status 和 redacted logPath/job identity。 7. 重启 `agentrun-mgr` 后，run、command、events 和 terminal_status 仍可从 Postgres 查询。 8. 日志、event、CLI 输出和 health 中没有 provider credential、DSN password、token 或 URL credential 明文。 +9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；P0 未实现的 session/resource 能力必须显式为 `null` 或 deferred，不能由 runner 隐式猜测。 ### CLI 交互联调标准 @@ -157,6 +158,10 @@ T7 只定义人工验收的检查面和判定口径。若后续为减少人工 T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend profile 的普通发布仍至少执行已有真实主闭环。 +### T9 RuntimeAssembly 四要素验收 + +阅读本文和 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)，然后检查一次真实 runner Job 或 dry-run manifest，确认 backend image 来自 digest-pinned `BackendImageRef`，provider credential 来自匹配 `ProfileRef` SecretRef，`SessionRef` 在 P0 下没有把完整 `CODEX_HOME` 持久化，`ResourceBundleRef` 若出现则必须是 Git-only 的 repo URL、full commit id 和 checkout policy。任何 Secret value、用户文件正文或 env dump 都不得进入 event、trace、log 或 run payload。 + ## 规格的实现情况 | 规格项 | 状态 | 说明 | @@ -168,4 +173,5 @@ T8 是涉及 backend profile 变更时的综合联调标准；不涉及 backend | RESTful API 交互联调标准 | 已定义 | 必须直连真实 manager HTTP JSON API，验证服务合同和 durable facts。 | | 真实主闭环 | 已通过 | 当前 v0.1 已通过真实 Tekton/Argo、Postgres、SecretRef、Kubernetes runner Job、Codex stdio turn、RESTful API 和 CLI 主闭环；每次发布仍需按本文手动复验。 | | `deepseek` profile 切换验收 | 已通过主闭环 | 自测试和 CLI smoke 已覆盖 profile registry、Secret render、fake stdio turn、无 fallback 和结构化错误；真实 `agentrun-v01` 已按 T8 完成 `codex -> deepseek -> codex` 切换综合联调。后续涉及 backend profile 的发布仍必须按 T8 复验。 | +| RuntimeAssembly 四要素验收 | 已定义 | T9 定义 backend image、ProfileRef、SessionRef 和 Git-only ResourceBundleRef 的装配验收；P0 当前主要验证 digest image 与 profile SecretRef，session/resource materialization 后续实现时必须补真实联调。 | | mock 作为发布证据 | 不采用 | mock 只能证明自测试通过。 |