From 7b8f5ae51898cc3de6688315b9105c8c55de0e26 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 2 Jun 2026 00:06:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E8=BF=90=E8=A1=8C?= =?UTF-8?q?=E6=97=B6=E8=A3=85=E9=85=8DSPEC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- docs/reference/spec-v01-cli.md | 3 +- docs/reference/spec-v01-runtime-assembly.md | 68 ++++++++++++++++--- .../reference/spec-v01-secret-distribution.md | 11 +-- docs/reference/spec-v01-services.md | 6 +- 5 files changed, 73 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c5fc9d3..e143e25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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% 真实。 diff --git a/docs/reference/spec-v01-cli.md b/docs/reference/spec-v01-cli.md index 7dd3786..04e07cf 100644 --- a/docs/reference/spec-v01-cli.md +++ b/docs/reference/spec-v01-cli.md @@ -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 子命令作为通过证据。 ## 测试规格 diff --git a/docs/reference/spec-v01-runtime-assembly.md b/docs/reference/spec-v01-runtime-assembly.md index 6f29d45..6d65489 100644 --- a/docs/reference/spec-v01-runtime-assembly.md +++ b/docs/reference/spec-v01-runtime-assembly.md @@ -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` 绕过。 | diff --git a/docs/reference/spec-v01-secret-distribution.md b/docs/reference/spec-v01-secret-distribution.md index 38d8c2f..dc3e241 100644 --- a/docs/reference/spec-v01-secret-distribution.md +++ b/docs/reference/spec-v01-secret-distribution.md @@ -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 路径。 ## 分发路径 diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md index 91a5cc9..36a92e0 100644 --- a/docs/reference/spec-v01-services.md +++ b/docs/reference/spec-v01-services.md @@ -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 合同