docs: 固化运行时装配SPEC
This commit is contained in:
Codex
@@ -1,6 +1,8 @@
|
||||
# v0.1 Runtime Assembly 最简规格
|
||||
# v0.1 装配 SPEC（RuntimeAssembly）
|
||||
|
||||
本文定义 AgentRun `v0.1` runner/backend 启动前的最简四要素装配模型。`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend 镜像、哪个 profile、哪份 session、哪份代码。其他能力只作为四要素的 policy 或 metadata，不扩展成新的运行时要素。
|
||||
本文是 AgentRun `v0.1` runner/backend 启动前的权威装配 SPEC。所有会进入运行时容器、进程、文件系统或环境变量的执行输入，都必须先落到本文定义的装配模型，再由 manager/runner 渲染为受控 Job 输入；不得在 CLI、Queue、runner Job、issue 过程或临时热补丁中绕过装配模型直接拼接 credential、host path 或隐式环境。
|
||||
|
||||
`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend 镜像、哪个 profile/credential scope、哪份 session、哪份代码和工具 credential。`BackendImageRef`、`ProfileRef`、`SessionRef`、`ResourceBundleRef` 仍是四个一等运行时要素；credential 注入不是第五个杂项要素，而是挂在 `ProfileRef`、`ResourceBundleRef` 或 tool scope 上的 SecretRef 装配引用。
|
||||
|
||||
## 最简四要素
|
||||
|
||||
@@ -9,7 +11,7 @@
|
||||
| 要素 | 最小字段 | v0.1 含义 | 不包含 |
|
||||
| --- | --- | --- | --- |
|
||||
| `BackendImageRef` | `image` | digest-pinned backend/runner 镜像。 | API KEY、profile config、用户代码、session 文件。 |
|
||||
| `ProfileRef` | `profile`、`secretRef` | provider profile 和 API KEY/配置 SecretRef。 | backend 镜像、session、repo 文件。 |
|
||||
| `ProfileRef` | `profile`、`secretRef` | provider profile 和 API KEY/配置 SecretRef。 | backend 镜像、session、repo 文件、GitHub/业务工具 credential。 |
|
||||
| `SessionRef` | `sessionId` 或 `null` | backend 会话文件持久化引用；P0 可以为 `null`。 | API KEY、完整 `CODEX_HOME`、Git workspace。 |
|
||||
| `ResourceBundleRef` | `repoUrl`、`commitId` | 初始代码/文件输入；P0 固定 Git-only。 | 上传文件、对象存储 artifact、inline env、Secret value。 |
|
||||
|
||||
@@ -32,7 +34,46 @@ P0 最小 JSON 形态：
|
||||
}
|
||||
```
|
||||
|
||||
`executionPolicy`、`observabilityPolicy`、tenant identity、network、GC、failureKind、provenance 和 resource limit 都不是新的要素；它们分别挂在四要素或 run policy 上。
|
||||
`executionPolicy`、`observabilityPolicy`、tenant identity、network、GC、failureKind、provenance、resource limit 和 tool credential scope 都不是新的运行时要素；它们分别挂在四要素或 run policy 上，并且必须能追溯到 SecretRef、配置引用或显式 null/deferred 状态。
|
||||
|
||||
## 装配对象与 credential 归属
|
||||
|
||||
任何 credential 注入都必须先归类，再进入对应装配路径：
|
||||
|
||||
| credential 类别 | 装配归属 | 运行时投影 | 规则 |
|
||||
| --- | --- | --- | --- |
|
||||
| Provider credential | `ProfileRef` / `executionPolicy.secretScope.providerCredentials[]` | profile-scoped 只读 Secret projection，再复制到 per-run writable `CODEX_HOME` | 只服务 `codex`/`deepseek` backend profile；缺失为 `secret-unavailable`，不得 fallback。 |
|
||||
| Git resource credential | `ResourceBundleRef.credentialRef` | 只服务 resource materialization 的 Git fetch/checkout | 只能用于拉取 `ResourceBundleRef.repoUrl` 对应代码，不得暴露给 agent shell 作为通用 GitHub token。 |
|
||||
| Tool credential | `executionPolicy.secretScope.toolCredentials[]` | 由 runner 按 tool scope 投影为文件或 env，并只暴露给当前 run/command 允许的工具 | 用于 GitHub PR、issue、artifact registry 等 agent shell 工具能力；不等同于 AgentRun integration，不触发 GitHub sink/OA/Event 之类外部动作记录。 |
|
||||
| Short-lived execution context | runner-job `transientEnv` | 单次 Job env，response/dry-run/event 只显示 name/hash | 只用于业务 dispatcher 生成的短期上下文，例如 HWLAB device-pod session token；不得承载 provider credential、GitHub token、长期 SSH key 或可复用 API key。 |
|
||||
|
||||
`toolCredentials` 是装配 SPEC 中的受控扩展槽位，用于把 agent 运行时需要的外部工具授权从“临时 env”收敛为 SecretRef。第一版实现可以只支持 GitHub PR 验收所需的最小形态，例如：
|
||||
|
||||
```json
|
||||
{
|
||||
"toolCredentials": [
|
||||
{
|
||||
"tool": "github",
|
||||
"purpose": "pull-request",
|
||||
"secretRef": {
|
||||
"namespace": "agentrun-v01",
|
||||
"name": "agentrun-v01-tool-github-pr",
|
||||
"keys": ["GH_TOKEN"]
|
||||
},
|
||||
"projection": { "kind": "env", "envName": "GH_TOKEN" }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- `toolCredentials` 只能保存 SecretRef、tool、purpose、projection intent 和 redacted metadata，不保存 Secret value。
|
||||
- manager 只校验引用形态和 tenant/policy 边界，不读取 Secret value 后存库。
|
||||
- runner 渲染 Job 时只能按当前 run 的 `secretScope` 投影被授权的 tool credential；不能枚举 namespace 内所有 Secret。
|
||||
- dry-run manifest、runner job record、event、trace、日志和 CLI 输出只能显示 tool、purpose、SecretRef 名称/key、projection kind 和 `valuesPrinted=false`。
|
||||
- GitHub PR 能力属于 agent shell/tool 运行能力，不是 AgentRun Queue integration，也不要求新增 GitHub sink、OA sink、notification 或 Event Flow。
|
||||
- 在 `toolCredentials` 实现前，发现 agent shell 缺少 `gh`、`curl`、SSH key 或 GitHub token，只能记录为装配能力缺口；不得用 `transientEnv` 或 issue 评论里的明文 token 绕过。
|
||||
|
||||
## HWLAB v0.2 承接口径
|
||||
|
||||
@@ -83,10 +124,12 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S
|
||||
## 最简装配顺序
|
||||
|
||||
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 的脱敏摘要。
|
||||
2. Manager 根据 `executionPolicy.secretScope` 解析 provider/tool SecretRef 和 resource credential 引用；只保存引用，不读取值。
|
||||
3. Manager 或 runner Job render 只使用解析后的 image、SecretRef、sessionRef、Git commit 和 projection intent。
|
||||
4. Runner materialize profile Secret 到 writable runtime home。
|
||||
5. Runner materialize tool credential 到该 run 允许的 env/file projection；未实现的 tool scope 必须显式 failed/blocked，不能静默跳过后让 agent 自己猜凭据。
|
||||
6. Runner materialize Git-only resource bundle 到 workspace；P0 未实现时必须显式记录为 deferred 或 null，不能猜测 host path。
|
||||
7. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl/commitId 的脱敏摘要。
|
||||
|
||||
任何一个要素缺失或不合法，都必须按该要素失败；不得静默 fallback。
|
||||
|
||||
@@ -106,6 +149,13 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S
|
||||
- 删除或缺失 `deepseek` SecretRef 时必须 `secret-unavailable`，不能 fallback 到 `codex`。
|
||||
- 所有输出不得包含 Secret value、`auth.json` 或 `config.toml` 明文。
|
||||
|
||||
### A2b Tool credential 验收
|
||||
|
||||
- GitHub PR、issue 或其他 shell/tool 授权只能通过 `executionPolicy.secretScope.toolCredentials[]` 的 SecretRef 装配进入 runner。
|
||||
- CLI、Queue task、runner job response、dry-run manifest、event 和日志不得输出 token、SSH private key 或 credential 文件正文。
|
||||
- 缺少 tool credential 时，run/command 必须返回可判定的 `secret-unavailable`、`tenant-policy-denied` 或明确 blocker，不能伪装成 agent 业务失败。
|
||||
- `transientEnv` 不得用于 GitHub token、长期 SSH key、provider API key 或其他可复用 credential。
|
||||
|
||||
### A3 SessionRef 验收
|
||||
|
||||
- P0 若未启用 session，run/manifest 必须显式表现为 `sessionRef=null` 或 equivalent deferred 状态。
|
||||
@@ -127,6 +177,7 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S
|
||||
2. 用哪一个 profile 和 SecretRef。
|
||||
3. 是否使用 session；若不用，必须明确为 `null`/deferred。
|
||||
4. 使用哪一个 Git repo 和 full commit；若 P0 尚未 materialize，必须明确为 deferred，不能隐式使用 host path。
|
||||
5. 是否装配 tool credential；若需要 GitHub PR 能力，必须能回答 tool、purpose、SecretRef 和 projection kind，不能只在运行时 shell 中偶然存在 token。
|
||||
|
||||
## 实现状态
|
||||
|
||||
@@ -136,3 +187,4 @@ HWLAB v0.2 原有 Code Agent 已经验证了 profile、session、workspace 和 S
|
||||
| `ProfileRef` | 已实现/已通过主闭环 | `codex` 与 `deepseek` 已通过 SecretRef、writable runtime home 和真实 stdio turn 验证。 |
|
||||
| `SessionRef` | 已实现最小持久化 | manager 持久化 `sessionId/conversationId/threadId`，run 创建会解析既有 session，runner 按 threadId resume；session 不保存 credential 文件，TTL/GC 后续细化。 |
|
||||
| `ResourceBundleRef` | 已实现 Git-only materialization | `repoUrl + full commitId` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 commit/tree/workspace 摘要。 |
|
||||
| `toolCredentials` | 已定义/待实现 | GitHub PR 等 agent shell/tool 授权必须通过装配 SPEC 的 SecretRef 进入 runner；当前发现缺 `gh`/token 时按装配缺口处理，不用 `transientEnv` 绕过。 |
|
||||
|
||||
Reference in New Issue
Block a user