From 63ae9e2543d0cc5213dc285654d96c7b6fd3259d Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 9 Jun 2026 23:42:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20transient=20env=20?= =?UTF-8?q?SecretRef=20=E5=90=88=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/spec-v01-runtime-assembly.md | 3 ++- docs/reference/spec-v01-secret-distribution.md | 10 ++++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/reference/spec-v01-runtime-assembly.md b/docs/reference/spec-v01-runtime-assembly.md index b854a82..b14f981 100644 --- a/docs/reference/spec-v01-runtime-assembly.md +++ b/docs/reference/spec-v01-runtime-assembly.md @@ -240,7 +240,7 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills//SKILL.m - GitHub PR、issue、UniDesk SSH passthrough 或其他 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、UniDesk SSH client token、长期 SSH key、provider API key 或其他 provider/tool 可复用 credential。HWLAB dispatcher 生成并限定 owner/HWPOD/runtime scope 的 `HWLAB_API_KEY` 可以作为单次 runner Job runtime context 进入 `transientEnv`，但 AgentRun 不保存、不解释、不回显其明文。 +- `transientEnv` 不得用于 GitHub token、UniDesk SSH client token、长期 SSH key、provider API key 或其他 provider/tool 可复用 credential。HWLAB dispatcher 生成并限定 owner/HWPOD/runtime scope 的 `HWLAB_API_KEY` 可以作为单次 runner Job runtime context 进入 `transientEnv`，但正式 Kubernetes Job 必须通过 per-job Secret 和 `valueFrom.secretKeyRef` 投影，不能作为 pod spec plain env value；AgentRun 不保存、不解释、不回显其明文。 ### A3 SessionRef 验收 @@ -279,3 +279,4 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills//SKILL.m | `SessionRef` | v0.1.1 已实现/已通过 HWLAB v0.2 原入口复测 | manager 持久化 `sessionId/conversationId/threadId` + 每个 session 绑 RWO PVC（`agentrun-v01-session-`），runner Job 把 PVC 直接挂到 `${CODEX_HOME}/`，codex app-server 自己落盘；runner pod 删除后 replacement runner 仍复用同一 SessionRef/PVC/thread，禁止 copy/restore、replacement threadId 和 fake resume。 | | `ResourceBundleRef` | 已实现 `kind="gitbundle"` materialization/promptRefs/tools/skillDirs 装配 | `repoUrl + ref/materialized commit + bundles[]` 已进入 run schema 和 runner checkout，workspace 受 `AGENTRUN_WORKSPACE_ROOT` 限制，event/result 记录 requested ref/commit、actual commit、tree/workspace/bundles 摘要；`tools/` PATH、`promptRefs` thread-start 注入和 `.agents/skills` 目录发现已实现。 | | `toolCredentials` | 已实现最小 env projection | GitHub PR 和 UniDesk SSH passthrough 等 agent shell/tool 授权通过装配 SPEC 的 SecretRef 进入 runner；v0.1 支持 `tool=github` 与 `tool=unidesk-ssh`、`projection.kind=env`，runner Job 使用 `valueFrom.secretKeyRef` 注入，不用 `transientEnv` 绕过。 | +| `transientEnv` | 已实现 per-job SecretRef 投影 | Queue dispatch 和 runner-job API 支持短期 runtime env；正式 Kubernetes Job 先创建本次 Job 专属 Secret，再用 `valueFrom.secretKeyRef` 注入 runner env，response/event/trace 只显示 env names、Secret metadata 和 `valuesPrinted=false`。 | diff --git a/docs/reference/spec-v01-secret-distribution.md b/docs/reference/spec-v01-secret-distribution.md index 8f63398..1030357 100644 --- a/docs/reference/spec-v01-secret-distribution.md +++ b/docs/reference/spec-v01-secret-distribution.md @@ -139,8 +139,10 @@ Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。provid - `transientEnv` 只能出现在 `POST /api/v1/runs/:runId/runner-jobs` 请求中；不得写入 `CreateRunInput`、command payload、event payload 或 result envelope 的 value 明文。 - manager 不对 `transientEnv` 条目数量设固定上限，只校验数组形态、env name 合法且唯一、value 非空和单值长度；runner job payload hash 只纳入 env name 与 value hash。 - 当 run 请求 `executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh` 且调用方未提供 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL` 时，manager 可以从受控默认配置自动补齐一个非敏感 endpoint env。该自动补齐必须遵守同一 redaction 规则，只显示 name/count/hash 和 `valuesPrinted=false`。 -- 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、权限和业务授权范围。 +- response、runner job status、event 和 dry-run manifest 只能展示 env name、count、SecretRef metadata 和 `valuesPrinted=false`；dry-run manifest 中的 transient env value 必须显示为 `REDACTED`。 +- 正式 Kubernetes runner Job 不得把 `transientEnv` value 作为 pod spec plain env value。manager 必须先创建本次 Job 专属的短期 Kubernetes Secret，再在 runner container env 中使用 `valueFrom.secretKeyRef` 引用对应 key。Secret name、namespace、keys、ownerReference attached 状态和 `valuesPrinted=false` 可以出现在 response/event/trace 中，Secret data 和 env value 不得出现。 +- 本次 Job 专属 transient env Secret 必须带有 run/command/attempt/runner/job metadata，创建 Job 失败时清理已创建 Secret；Job 创建成功后尽量给 Secret 加上 ownerReference，让 Kubernetes 随 Job GC。ownerReference patch 失败必须以 warning 暴露，不能回退为 plain env value。 +- `transientEnv` token 必须由调度方控制 TTL、权限和业务授权范围；AgentRun 只负责本次 runner Job 的短期投影和 redaction，不把它升级为长期 credential。 - AgentRun 不解释 HWLAB HWPOD 权限，也不把业务鉴权做成通用 policy；AgentRun 只负责不持久化、不回显、不扩散这类短期 env value。 - GitHub token、UniDesk SSH client token、SSH private key、provider API key、registry token 等 provider/tool 可复用 credential 不得通过 `transientEnv` 注入；必须先进入装配 SPEC 的 SecretRef 路径。HWLAB dispatcher 生成并限定 owner/HWPOD/runtime scope 的 `HWLAB_API_KEY` 属于业务运行上下文，可以作为单次 runner Job env 透传，但不得变成 AgentRun durable fact 或通用授权。 @@ -206,6 +208,10 @@ Secret 创建和轮换不由 source branch 自动生成；source branch 只声 阅读本文，然后用一个不存在的 provider SecretRef 创建 run，确认 run 失败为结构化 `secret-unavailable`，不会打印 Secret 值，也不会无限重试。 +### T4 transientEnv SecretRef 投影 + +阅读本文，然后通过正式 `runner-jobs` 或 Queue dispatch 路径创建带 `transientEnv` 的真实 runner Job。检查 runner job response、event、dry-run manifest 和 Kubernetes Pod spec：response/event 只能输出 env names、Secret name/namespace/keys、ownerReference 状态和 `valuesPrinted=false`；Pod spec 中对应 env 必须是 `valueFrom.secretKeyRef`，不能包含 `value`；Secret data 只能通过 Kubernetes Secret 保存，验证时只允许读取 key 列表和 metadata，不得输出 value。 + ## 规格的实现情况 | 规格项 | 状态 | 说明 |