Codex
124 lines
6.3 KiB
Markdown
124 lines
6.3 KiB
Markdown
# v0.1 Runtime Assembly 最简规格
|
||
|
||
本文定义 AgentRun `v0.1` runner/backend 启动前的最简四要素装配模型。`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend 镜像、哪个 profile、哪份 session、哪份代码。其他能力只作为四要素的 policy 或 metadata，不扩展成新的运行时要素。
|
||
|
||
## 最简四要素
|
||
|
||
`v0.1` 只保留四个一等要素：
|
||
|
||
| 要素 | 最小字段 | v0.1 含义 | 不包含 |
|
||
| --- | --- | --- | --- |
|
||
| `BackendImageRef` | `image` | digest-pinned backend/runner 镜像。 | API KEY、profile config、用户代码、session 文件。 |
|
||
| `ProfileRef` | `profile`、`secretRef` | provider profile 和 API KEY/配置 SecretRef。 | backend 镜像、session、repo 文件。 |
|
||
| `SessionRef` | `sessionId` 或 `null` | backend 会话文件持久化引用；P0 可以为 `null`。 | API KEY、完整 `CODEX_HOME`、Git workspace。 |
|
||
| `ResourceBundleRef` | `repoUrl`、`commitId` | 初始代码/文件输入；P0 固定 Git-only。 | 上传文件、对象存储 artifact、inline env、Secret value。 |
|
||
|
||
P0 最小 JSON 形态：
|
||
|
||
```json
|
||
{
|
||
"backendImageRef": {
|
||
"image": "127.0.0.1:5000/agentrun/agentrun-mgr@sha256:..."
|
||
},
|
||
"profileRef": {
|
||
"profile": "codex",
|
||
"secretRef": { "name": "agentrun-v01-provider-codex", "keys": ["auth.json", "config.toml"] }
|
||
},
|
||
"sessionRef": null,
|
||
"resourceBundleRef": {
|
||
"repoUrl": "git@github.com:pikasTech/unidesk.git",
|
||
"commitId": "<full commit sha>"
|
||
}
|
||
}
|
||
```
|
||
|
||
`executionPolicy`、`observabilityPolicy`、tenant identity、network、GC、failureKind、provenance 和 resource limit 都不是新的要素；它们分别挂在四要素或 run policy 上。
|
||
|
||
## 四要素边界
|
||
|
||
### BackendImageRef
|
||
|
||
- `image` 必须是 digest-pinned image。
|
||
- image 来源必须是 CI/CD artifact catalog、GitOps manifest 或 manager allowlist；客户端不能在 run payload 中传任意镜像。
|
||
- v0.1 可以继续使用现有 agentrun runner 镜像，不要求立即拆独立 backend image。
|
||
- 验收时只需要能追溯实际 Deployment/Job image digest 和 source commit。
|
||
|
||
### ProfileRef
|
||
|
||
- `profile` 在 v0.1 只允许 `codex` 或 `deepseek`。
|
||
- `secretRef` 只保存 Secret 名称和 key，不保存值。
|
||
- 当前 profile 只能读取当前 profile 的 SecretRef；缺失必须 `secret-unavailable`，不能 fallback 到另一个 profile。
|
||
- profile Secret 只读投影，backend 需要可写目录时复制到 per-run/profile runtime home。
|
||
|
||
### SessionRef
|
||
|
||
- P0 允许 `sessionRef=null`，表示不持久化 backend session 文件。
|
||
- 一旦启用 session，必须只保存 backend session/cache，不保存 API KEY、`auth.json`、`config.toml` 或完整 `CODEX_HOME`。
|
||
- session 文件目录必须和 profile credential、Git workspace 分开。
|
||
- v0.1 先定义边界，不要求实现 PVC/session restore。
|
||
|
||
### ResourceBundleRef
|
||
|
||
- P0 固定 Git-only，由 `repoUrl + full commitId` 决定内容身份。
|
||
- `commitId` 必须是不可变 full commit sha，不能是 branch、tag 或 `HEAD`。
|
||
- 可选扩展只允许 `subdir`、`sparsePaths`、`submodules=false`、`lfs=false`、`credentialRef`；默认不启用。
|
||
- `credentialRef` 只用于拉取私有 Git repo，不等同于 backend API KEY。
|
||
- 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋或 inline env；后续需要时另写版本规格。
|
||
|
||
## 最简装配顺序
|
||
|
||
1. Manager 根据 run 解析四要素引用。
|
||
2. Manager 或 runner Job render 只使用解析后的 image、SecretRef、sessionRef 和 Git commit。
|
||
3. Runner materialize profile Secret 到 writable runtime home。
|
||
4. Runner materialize Git-only resource bundle 到 workspace；P0 未实现时必须显式记录为 deferred 或 null，不能猜测 host path。
|
||
5. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、sessionRef、repoUrl/commitId 的脱敏摘要。
|
||
|
||
任何一个要素缺失或不合法，都必须按该要素失败；不得静默 fallback。
|
||
|
||
## v0.1 验收标准
|
||
|
||
### A1 BackendImageRef 验收
|
||
|
||
- 实际 manager Deployment 和 runner Job 使用 digest-pinned image。
|
||
- event、CLI 或诊断输出能看到 image digest 或可追溯到 GitOps/catalog。
|
||
- run payload 不能传任意 image 字符串。
|
||
|
||
### A2 ProfileRef 验收
|
||
|
||
- `codex` run 只挂载 `agentrun-v01-provider-codex`。
|
||
- `deepseek` run 只挂载 `agentrun-v01-provider-deepseek`。
|
||
- `codex -> deepseek -> codex` 切换后，`CODEX_HOME`、SecretRef、backend_status 不互相污染。
|
||
- 删除或缺失 `deepseek` SecretRef 时必须 `secret-unavailable`，不能 fallback 到 `codex`。
|
||
- 所有输出不得包含 Secret value、`auth.json` 或 `config.toml` 明文。
|
||
|
||
### A3 SessionRef 验收
|
||
|
||
- P0 若未启用 session，run/manifest 必须显式表现为 `sessionRef=null` 或 equivalent deferred 状态。
|
||
- runner Job 不得把完整 `CODEX_HOME`、Secret projection 或 host path 当成 session store。
|
||
- 后续启用 session 前，必须补充真实验收：session 目录不包含 API KEY 或 profile credential。
|
||
|
||
### A4 ResourceBundleRef 验收
|
||
|
||
- P0 ResourceBundle 只能是 Git-only：`repoUrl + full commitId`。
|
||
- `commitId` 不是 branch/tag/HEAD。
|
||
- checkout 只能进入允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。
|
||
- run payload 不携带文件正文、env dump、Secret value 或大型 artifact。
|
||
|
||
### A5 综合验收
|
||
|
||
一次真实 runner Job 或 dry-run manifest 必须能同时回答：
|
||
|
||
1. 用哪一个 image digest。
|
||
2. 用哪一个 profile 和 SecretRef。
|
||
3. 是否使用 session；若不用，必须明确为 `null`/deferred。
|
||
4. 使用哪一个 Git repo 和 full commit；若 P0 尚未 materialize，必须明确为 deferred，不能隐式使用 host path。
|
||
|
||
## 实现状态
|
||
|
||
| 要素 | v0.1 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| `BackendImageRef` | 部分实现 | CI/CD 已使用 digest-pinned runtime image；当前 runner/backend 仍复用 agentrun 镜像。 |
|
||
| `ProfileRef` | 已实现/已通过主闭环 | `codex` 与 `deepseek` 已通过 SecretRef、writable runtime home 和真实 stdio turn 验证。 |
|
||
| `SessionRef` | 规格已定义/P0 未实现 | 当前只持久化 run facts，不持久化 backend session 文件。 |
|
||
| `ResourceBundleRef` | 规格已定义/P0 Git-only/待实现 | 已明确最简 Git-only 模型，runner materialization 后续实现。 |
|