docs: 固化 UniDesk SSH endpoint 装配合同

This commit is contained in:
Codex
2026-06-09 22:02:15 +08:00
parent 5ff882005b
commit 3daaa32427
3 changed files with 8 additions and 5 deletions
@@ -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 hashresponse、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 hashresponse、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 映射