mirrors/pikasTech-agentrun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 固化运行时装配SPEC

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+1 -1
View File
@@ -55,7 +55,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-runtime-assembly.md`：v0.1 runner/backend 启动前的装配 SPEC，覆盖 BackendImageRef、ProfileRef、SessionRef、Git-only ResourceBundleRef 和 tool credential SecretRef scope。
- `docs/reference/spec-v01-queue.md`：v0.1 AgentRun Queue 直接吸收 UniDesk Code Queue 的 RESTful API、CLI、数据模型、Session 边界和验收规格。
- `docs/reference/spec-v01-hwlab-manual-dispatch.md`：v0.1 通过手动调度 API 为 HWLAB v0.2 提供 canary Code Agent 服务的目标、缺口和增强计划。
- `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。
docs/reference/spec-v01-cli.md
+2 -1
View File
@@ -91,7 +91,8 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
- CLI 配置必须显式校验；部署关键值不得静默 fallback。
- CLI 调用 manager REST API；不得直接连 Postgres 或读 Kubernetes Secret value。
- CLI 可以显示 SecretRef 名称、key、credential source 和 readiness，但不得显示 Secret value、Codex `auth.json`、Codex `config.toml`、DSN password、token 或 URL credential。
- CLI 可以显示 SecretRef 名称、key、credential source、tool credential scope 和 readiness，但不得显示 Secret value、Codex `auth.json`、Codex `config.toml`、DSN password、token、SSH private key 或 URL credential。
- CLI 不得把 GitHub token、provider key 或长期 SSH key 通过 `transientEnv` 传入 runner；涉及 agent shell/tool 授权时，必须先按 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md) 的 `toolCredentials` 装配路径实现，再提供 CLI 参数。
- Debug 子命令可以用于开发，但综合联调和测试规格不得用 debug 子命令作为通过证据。
## 测试规格
docs/reference/spec-v01-runtime-assembly.md
+60 -8
View File
@@ -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` 绕过。 |
docs/reference/spec-v01-secret-distribution.md
+7 -4
View File
@@ -2,7 +2,7 @@
本文定义 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)。
在装配 SPEC 中，本文承担 SecretRef、projection、rotation 和 redaction 规则；运行时 credential 必须先归入 `ProfileRef`、`ResourceBundleRef.credentialRef` 或 `executionPolicy.secretScope.toolCredentials[]`，再由 runner Job 装配。权威装配模型见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
## 设计目标
@@ -20,7 +20,8 @@
| Codex stdio profile 凭据文件 | 真实 Code Agent backend 调上游模型 | runner 或 backend adapter | `codex` 与 `deepseek` 均使用 `auth.json`/`config.toml` 文件形态，只通过 profile-scoped Kubernetes SecretRef 文件投影注入，不写入 run payload。 |
| Git SSH deploy key | Tekton checkout source/GitOps promotion，Argo 读取 GitOps branch | Tekton、Argo CD | 只存在于 `agentrun-ci` 或 `argocd` Secret；不进入 runtime Pod。 |
| Registry credential | push/pull private registry | Tekton、runtime imagePullSecret | 只作为 ServiceAccount/imagePullSecret 引用。 |
| Future tenant credential | tenant 专属工具或外部服务 | runner/backend adapter | 必须先定义 SecretRef 和 secret scope，再允许 run 引用。 |
| Tool credential | GitHub PR、issue、artifact registry 等 agent shell/tool 授权 | runner/backend adapter | 必须通过 `executionPolicy.secretScope.toolCredentials[]` 的 SecretRef 装配进入运行时；不是 Queue integration，也不能用 `transientEnv` 承载长期 credential。 |
| Future tenant credential | tenant 专属工具或外部服务 | runner/backend adapter | 必须先扩展装配 SPEC 的 SecretRef 和 secret scope，再允许 run 引用。 |
## 固定命名建议
@@ -64,7 +65,7 @@ Secret 创建和轮换必须通过 Kubernetes 密钥管理完成。`deploy/deplo
## Run secretScope 合同
Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例形态：
Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。provider credential 使用 `providerCredentials[]`；GitHub PR 等 agent shell/tool 授权使用装配 SPEC 定义的 `toolCredentials[]`，不得混入 `transientEnv`。示例形态：
```json
{
@@ -101,10 +102,11 @@ Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例
- runner/backend adapter 只能选择与 run `backendProfile` 同名的 provider credential；`backendProfile=deepseek` 缺少 `deepseek` SecretRef 时必须 `secret-unavailable`，不得 fallback 到 `codex`。
- Secret projection 不能直接作为 `CODEX_HOME`。Codex app-server 会读取并可能维护默认配置、PATH 或运行态文件；把只读 Secret volume 直接挂到 `CODEX_HOME` 会造成启动期写入失败。v0.1 的固定边界是：Secret volume 只读、`/home/agentrun` 由 `emptyDir` 提供可写 runtime home、复制动作只发生在 runner/backend 容器内且不打印文件内容。
- SecretRef 不存在或 RBAC 不允许时，run 必须失败为结构化 `failureKind=secret-unavailable` 或等价错误，不得降级成无凭证重试风暴。
- `toolCredentials` 的 SecretRef/projection/redaction 规则以 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md) 为准；本文只约束 Secret value 不落库、不输出、不进入 Git source 或 GitOps Secret data。
## runner-job transientEnv
`transientEnv` 用于承接调度方生成的短期、单次 runner Job 运行上下文，例如 HWLAB Code Agent 的 device-pod session token 和 API URL。它不是 provider credential，也不是 run durable fact。
`transientEnv` 用于承接调度方生成的短期、单次 runner Job 运行上下文，例如 HWLAB Code Agent 的 device-pod session token 和 API URL。它不是 provider credential、tool credential，也不是 run durable fact。
规则：
@@ -113,6 +115,7 @@ Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。示例
- response、runner job status、event 和 dry-run manifest 只能展示 env name、count 和 `valuesPrinted=false`；dry-run manifest 中的 transient env value 必须显示为 `REDACTED`。
- 正式 Kubernetes Job manifest 会把 value 注入到本次 runner container env；该 token 必须由调度方控制 TTL、权限和业务授权范围。
- AgentRun 不解释 HWLAB device-pod 权限，也不把业务鉴权做成通用 policy；AgentRun 只负责不持久化、不回显、不扩散这类短期 env value。
- GitHub token、SSH private key、provider API key、registry token 等可复用 credential 不得通过 `transientEnv` 注入；必须先进入装配 SPEC 的 SecretRef 路径。
## 分发路径
docs/reference/spec-v01-services.md
+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 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)。
- RuntimeAssembly 是 runner/backend 启动前的装配 SPEC，负责把 backend image、profile credential、session、Git-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 projection；source、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 scope；ProfileRef、SessionRef 和 ResourceBundleRef 已具备 v0.1 最小实现，tool credential 待实现。 | `spec-v01-runtime-assembly.md` |
| HWLAB 手动调度接入 | canary 集成目标 | 保留，P0 规格 | HWLAB `hwlab-cloud-api` 显式创建 run/command 并调用 runner Job API；AgentRun 提供 durable facts、events、cancel、bundle 和 session 能力。 | `spec-v01-hwlab-manual-dispatch.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` |
@@ -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 合同