docs: 固化 UniDesk SSH endpoint 装配合同
This commit is contained in:
Codex
@@ -53,7 +53,7 @@ AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执
|
||||
| skill discovery 与 skill facts | `internal/cloud/skills-store.ts`、`internal/cloud/codex-stdio-session-helpers.ts` 的 `discoverSkillsForStdio()` 和 `codexSidecarSkillsPrompt()` | HWLAB 把完整 `skills/` 子树通过 `kind="gitbundle"` 复制到 workspace `.agents/skills`；AgentRun 发现多文件 skill 并向 Codex 暴露有界 skill facts | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md) |
|
||||
| provider profile 隔离和 Secret 不泄露 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | `ProfileRef/SecretRef` profile-scoped 投影、缺失为 `secret-unavailable`、禁止 fallback 和泄露值 | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-backend-adapter.md](spec-v01-backend-adapter.md) |
|
||||
| HWPOD/HWLAB runtime 短期 env 注入 | HWLAB Cloud API 的 Code Agent env assembly（历史实现名可能含 device-pod） | `runner-jobs.transientEnv` 只在本次 Kubernetes Job env 中生效；只记录 name/count，不保存或输出 value | [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) |
|
||||
| UniDesk SSH passthrough | HWLAB Code Agent 通过 `tran` 访问 G14/D601/HWLAB/GitHub 维护面 | `toolCredentials[].tool=unidesk-ssh` 注入 `UNIDESK_SSH_CLIENT_TOKEN`，`transientEnv` 只注入非敏感 `UNIDESK_MAIN_SERVER_IP`；UniDesk frontend 负责 route allowlist | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) |
|
||||
| UniDesk SSH passthrough | HWLAB Code Agent 通过 `tran` 访问 G14/D601/HWLAB/GitHub 维护面 | `toolCredentials[].tool=unidesk-ssh` 注入 `UNIDESK_SSH_CLIENT_TOKEN`；非敏感 endpoint 由调度方 `transientEnv` 显式提供，或由 manager 受控默认值自动补齐；UniDesk frontend 负责 route allowlist | [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)、[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) |
|
||||
| provider/backend/cancel 等失败可区分 | `scripts/src/code-agent-response-contract.mjs`、`internal/cloud/code-agent-chat.ts` | failureKind 最小矩阵和 JSON 错误响应 | [spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)、[spec-v01-backend-adapter.md](spec-v01-backend-adapter.md) |
|
||||
| stdout/stderr/tool 输出必须有界 | `docs/reference/code-agent-chat-readiness.md`、`internal/cloud/code-agent-trace-store.ts` | `command_output`/`tool_call` 记录摘要、字节数、截断标记和必要引用 | [spec-v01-backend-adapter.md](spec-v01-backend-adapter.md) |
|
||||
| runner/job 失败需要定位证据 | `internal/cloud/server-code-agent-http.ts` 的 trace/result 可见性 | runner job identity、attempt、jobName、pod/log identity 和最小 phase/exit 摘要 | [spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)、[spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md) |
|
||||
@@ -75,7 +75,7 @@ AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执
|
||||
|
||||
响应必须短返回 JSON，不等待完整模型 turn，至少包含：`runId`、`commandId`、`attemptId`、`jobName`、`namespace`、`runnerId`、`logPath` 或 `podIdentity`、后续 `commands show` 与 `events` 轮询入口。重复提交若 payload 不同，必须结构化失败，不能创建第二个同名业务 attempt。
|
||||
|
||||
`transientEnv` 是 runner-job 层的临时执行上下文，不是 AgentRun run 的 durable fact。manager 不对条目数量设固定上限，只校验数组形态、env name 合法且唯一、value 非空和单值长度；payload hash 只保存 value hash，response、event、dry-run manifest 和错误详情不得输出明文 value。业务授权仍由 HWLAB 自己负责，AgentRun 只把调度方明确提供的短期 env 交给本次 runner。UniDesk SSH passthrough 的长期 token 不得放入 `transientEnv`；HWLAB dispatcher 只能把 `UNIDESK_MAIN_SERVER_IP` 这类非敏感定位信息放入 `transientEnv`，并通过 run `executionPolicy.secretScope.toolCredentials[]` 请求 `tool=unidesk-ssh`。
|
||||
`transientEnv` 是 runner-job 层的临时执行上下文，不是 AgentRun run 的 durable fact。manager 不对条目数量设固定上限，只校验数组形态、env name 合法且唯一、value 非空和单值长度；payload hash 只保存 value hash，response、event、dry-run manifest 和错误详情不得输出明文 value。业务授权仍由 HWLAB 自己负责，AgentRun 只把调度方明确提供或 manager 受控默认补齐的短期 env 交给本次 runner。UniDesk SSH passthrough 的长期 token 不得放入 `transientEnv`；HWLAB dispatcher 可以把 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL` 这类非敏感定位信息放入 `transientEnv`，也可以只通过 run `executionPolicy.secretScope.toolCredentials[]` 请求 `tool=unidesk-ssh` 让 manager 默认补齐 endpoint。
|
||||
|
||||
## Run / Command 映射
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ P0 最小 JSON 形态：
|
||||
| Provider credential | `ProfileRef` / `executionPolicy.secretScope.providerCredentials[]` | profile-scoped 只读 Secret projection，再复制到 per-run writable `CODEX_HOME` | 只服务 `codex`/`deepseek`/`minimax-m3`/`dsflash-go` backend profile；`dsflash-go` 额外包含 `model-catalog.json`；缺失为 `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、UniDesk SSH passthrough、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 生成的短期或 owner-scoped runtime context，例如 HWLAB HWPOD runtime API key、runtime URL 和非敏感服务地址；不得承载 provider credential、GitHub token、UniDesk SSH client token 或长期 SSH key。 |
|
||||
| Short-lived execution context | runner-job `transientEnv` | 单次 Job env，response/dry-run/event 只显示 name/hash | 只用于业务 dispatcher 生成的短期或 owner-scoped runtime context，以及 manager 受控默认值补齐的非敏感服务地址；不得承载 provider credential、GitHub token、UniDesk SSH client token 或长期 SSH key。 |
|
||||
|
||||
`toolCredentials` 是装配 SPEC 中的受控扩展槽位，用于把 agent 运行时需要的外部工具授权从“临时 env”收敛为 SecretRef。`v0.1` 支持 GitHub PR/issue 与 UniDesk SSH passthrough 所需的最小 env projection，例如：
|
||||
|
||||
@@ -89,6 +89,8 @@ P0 最小 JSON 形态：
|
||||
- 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。
|
||||
- `tool=unidesk-ssh` 只允许投影 Secret key `UNIDESK_SSH_CLIENT_TOKEN` 到同名 env。该 token 是 UniDesk frontend `/ws/ssh` 的 scoped client token，route allowlist 由 UniDesk frontend 配置约束；它不得携带 provider token、主 server SSH key 或完整 frontend 登录态。
|
||||
- `tool=unidesk-ssh` 所需的 UniDesk endpoint 不属于 SecretRef。runner-job env 必须具备 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL` 三者之一；调用方可以通过 `transientEnv` 显式传入，若未传入，manager 可以从受控默认配置自动补齐非敏感 endpoint env。
|
||||
- manager 自动补齐 endpoint 时只追加 env name/value 到本次 runner Job，不把 value 写入 run、command、event 或 result 明文；trace/response 只能显示 env name、count、hash 和 `valuesPrinted=false`。若 run 请求了 `tool=unidesk-ssh`，但调用方和 manager 默认都没有 endpoint，runner-job 创建必须在装配阶段返回结构化 `schema-invalid`，不能让 agent 进入 turn 后靠 prompt 猜 endpoint。
|
||||
- 发现 agent shell 缺少 `gh`、`curl`、UniDesk SSH passthrough token 或其他工具凭证时，只能记录为装配能力缺口；不得用 `transientEnv` 或 issue 评论里的明文 token 绕过。
|
||||
|
||||
## HWLAB v0.2 承接口径
|
||||
@@ -168,7 +170,7 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也
|
||||
|
||||
runner 对 workspace `tools/` 做统一装配：顶层带 shebang 的脚本会被 `chmod +x`，`tools/` 会暴露到 `PATH`。如果 runtime 配置了单独的 `AGENTRUN_RESOURCE_BIN_PATH`，runner 只能在该目录写入执行原始 workspace tool 的 shim，不能复制 tool 文件导致 `dirname "$0"`、相对 import 或辅助源码解析到 bin 目录。非 shebang 文件是随 bundle 复制的源码、测试或辅助文件，不作为可执行工具发现，也不触发 schema-invalid。短命令名称来自 repo 内真实文件，例如 `tools/hwpod`，repo tool 本身承担业务 wrapper 语义。
|
||||
|
||||
AgentRun 自身仓库必须提供 `tools/tran` 与 `tools/trans`，用于承接 UniDesk frontend `/ws/ssh` 的 scoped client-token 透传。runner 只通过 `executionPolicy.secretScope.toolCredentials[]` 投影 `UNIDESK_SSH_CLIENT_TOKEN`，并通过 `transientEnv` 注入非敏感 `UNIDESK_MAIN_SERVER_IP` / `UNIDESK_FRONTEND_URL`；工具不得读取 provider token、主 server SSH key 或完整 frontend 登录态。`tran --help` 必须输出 JSON，并列出当前支持的最小开发面：host/host workspace `script`、`argv`、普通 ssh-like 命令、`k3s kubectl`、`k3s script` 和 k3s workload `argv/script`。未实现的 `apply-patch`、`upload`、`download` 和 Windows route 必须显式 `unsupported-operation`，不能静默改走不受控 shell 拼接或 token fallback。
|
||||
AgentRun 自身仓库必须提供 `tools/tran` 与 `tools/trans`，用于承接 UniDesk frontend `/ws/ssh` 的 scoped client-token 透传。runner 只通过 `executionPolicy.secretScope.toolCredentials[]` 投影 `UNIDESK_SSH_CLIENT_TOKEN`，并通过调用方 `transientEnv` 或 manager 受控默认值注入非敏感 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL`；工具不得读取 provider token、主 server SSH key 或完整 frontend 登录态。`tran --help` 必须输出 JSON，并列出当前支持的最小开发面：host/host workspace `script`、`argv`、普通 ssh-like 命令、`k3s kubectl`、`k3s script` 和 k3s workload `argv/script`。未实现的 `apply-patch`、`upload`、`download` 和 Windows route 必须显式 `unsupported-operation`，不能静默改走不受控 shell 拼接或 token fallback。
|
||||
|
||||
#### promptRefs
|
||||
|
||||
|
||||
@@ -132,12 +132,13 @@ Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。provid
|
||||
|
||||
## runner-job transientEnv
|
||||
|
||||
`transientEnv` 用于承接调度方生成的短期、单次 runner Job 运行上下文，例如 HWLAB Code Agent 的 owner-scoped HWPOD/runtime API key、runtime URL 和非敏感 UniDesk frontend 地址。它不是 provider credential、tool credential，也不是 run durable fact。
|
||||
`transientEnv` 用于承接调度方生成的短期、单次 runner Job 运行上下文，例如 HWLAB Code Agent 的 owner-scoped HWPOD/runtime API key、runtime URL 和非敏感 UniDesk frontend 地址。它也可以承接 manager 因 `tool=unidesk-ssh` 自动补齐的受控默认 endpoint env。它不是 provider credential、tool credential，也不是 run durable fact。
|
||||
|
||||
规则：
|
||||
|
||||
- `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、权限和业务授权范围。
|
||||
- AgentRun 不解释 HWLAB HWPOD 权限，也不把业务鉴权做成通用 policy；AgentRun 只负责不持久化、不回显、不扩散这类短期 env value。
|
||||
|
||||
Reference in New Issue
Block a user