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

refactor: converge hwpod node-ops channel

Browse Source
This commit is contained in:
Codex Agent
2026-06-05 16:47:50 +08:00
parent 8a1cd5c725
commit 3e7131f6ab
117 changed files with 1056 additions and 19327 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/agentrun-code-agent-dispatch.md
+5 -12
View File
@@ -29,24 +29,17 @@
- UniDesk SSH passthrough 通过 `toolCredentials[].tool=unidesk-ssh` 注入，默认 SecretRef 是 `agentrun-v01-tool-unidesk-ssh` key `UNIDESK_SSH_CLIENT_TOKEN`。
- `UNIDESK_SSH_CLIENT_TOKEN` 只授予 UniDesk frontend `/ws/ssh` scoped client 能力；route allowlist 由 UniDesk frontend 配置控制。HWLAB 不持有 provider token、主 server SSH key 或完整 frontend 登录态。
- `runnerJob.transientEnv` 只能承接本次 runner job 需要的短期执行上下文，例如 owner-scoped `HWLAB_API_KEY`、`HWLAB_RUNTIME_API_URL` 和 `UNIDESK_MAIN_SERVER_IP`；敏感项必须标记 sensitive，不得承载 GitHub token、UniDesk SSH client token、provider key、长期 SSH key 或 registry token。
- HWLAB v0.2 HWPOD 能力在 runner 内只通过 `hwpod -> HWLAB_RUNTIME_API_URL -> hwlab-cloud-api` 进入。`HWLAB_RUNTIME_API_URL` 指向当前 namespace 的 `hwlab-cloud-api` Service；`HWLAB_RUNTIME_WEB_URL` 仅供需要浏览器同源语义的工具查看 Cloud Web。AgentRun 不以 Cloud Web 代理替代设备 API。
## 当前权限装配状态
- Runner 中的 HWLAB 用户凭据只允许是 cloud-api 为当前 Code Agent session owner 选择或创建的用户级 `HWLAB_API_KEY`。该 key 恢复为同一个 `users.id`，不等同于残留执行链路内部 service token、OpenFGA token、Keycloak token 或 Web cookie。
- Tool surface 由 OpenFGA tool capability 决定。缺少 `tool:hwpod#can_use` 时不暴露可用 `hwpod` 环境；缺少 `tool:unidesk_ssh#can_use` 时不注入 UniDesk SSH tool credential；缺少 `tool:trans_cmd#can_use` 时不暴露 trans cmd 透传入口。
- `tool:trans_cmd` 只允许进入 UniDesk 受控 passthrough 命令面；实际 route、operation、写操作和 Secret 可见性仍受 UniDesk CLI/route 边界以及当前任务授权限制。
- 即使 runner 侧误尝试调用未授权工具，cloud-api 仍是 HWPOD、Code Agent session 和 Admin Access 的最终 enforcement point，必须返回结构化 authorization blocker。
- HWLAB v0.2 HWPOD 能力在 runner 内只通过 `hwpod -> hwpod-compiler-cli -> HWLAB_RUNTIME_API_URL -> hwlab-cloud-api /v1/hwpod-node-ops` 进入。`HWLAB_RUNTIME_API_URL` 指向当前 namespace 的 `hwlab-cloud-api` Service；`HWLAB_RUNTIME_WEB_URL` 仅供需要浏览器同源语义的工具查看 Cloud Web。AgentRun 不以 Cloud Web 代理替代 HWPOD API。
## ResourceBundle
- AgentRun run 必须使用 Git-only `resourceBundleRef`，默认 repo 是 `http://git-mirror-http.devops-infra.svc.cluster.local/pikasTech/HWLAB.git`。
- `commitId` 必须是完整 40 字符小写 SHA，不接受 branch、tag、`HEAD` 或短 SHA。
- `workspaceRef` 只描述目标 repo/branch，默认 branch 是 `v0.2`；实际 checkout 身份以 `resourceBundleRef.repoUrl + commitId` 为准。
- 默认 `toolAliases` 会把迁移期 CLI shim 暴露为 `hwpod`，并把 `tools/unidesk-ssh.mjs` 暴露为 runner shell 内的 `unidesk-ssh` 命令。HWPOD、D601-F103-V2、Keil build/download、job status/output 和 UART/debug-probe 操作必须优先走 `hwpod`；`unidesk-ssh` 只用于 UniDesk passthrough 任务，不能替代 HWPOD 正式路径。
- HWPOD lease 不是独立 runner 控制命令；标准 `hwpod` surface 只提交命名 HWPOD job。需要 lease 时，token 只能作为 `--lease-token` 跟随实际 mutating job 请求转发给 cloud-api。Agent 不得调用 `hwpod lease ...`，也不得新增 gateway shell 或其他 fallback 来绕过 job authority。
- 默认 `toolAliases` 会把 `tools/hwpod-cli.ts` 暴露为 `hwpod`，把 `tools/hwpod-ctl.ts` 暴露为 `hwpod-ctl`，并把 `tools/unidesk-ssh.mjs` 暴露为 runner shell 内的 `unidesk-ssh` 命令。HWPOD inspect、workspace、Keil build/download、reset 和 UART/debug-probe 操作必须优先走 `hwpod`；`unidesk-ssh` 只用于 UniDesk passthrough 任务，不能替代 HWPOD 标准路径。
- HWPOD 快速阶段没有独立 lease 控制命令；标准 `hwpod` surface 只提交 HWPOD intent，经 compiler 生成 node-ops。Agent 不得新增 gateway shell 或其他 fallback 来绕过 `hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node`。
- 默认 `promptRefs` 指向 `internal/agent/prompts/hwlab-v02-runtime.md`，`inject=thread-start` 且 `required=true`。该 prompt 只在 AgentRun/Codex stdio 新 thread 首轮注入；后续 turn 必须依赖原生 `thread/resume`，不得在 command payload 中拼接历史、旧 skill 列表或长业务 prompt。
- 默认 `skillRefs` 仍可引用迁移期 `skills/device-pod-cli/SKILL.md` 和 `skills/hwlab-agent-runtime/SKILL.md`，但 runner 中的当前业务入口只暴露为 `hwpod`；这两个 skill 由 AgentRun 聚合到当前 workspace `.agents/skills/<name>/SKILL.md`。HWLAB 不再依赖 `/app/skills`、hostPath、默认 Codex skill registry、ConfigMap 或用户长 prompt 作为 skill 注入 fallback。
- 默认 `skillRefs` 指向 `skills/hwpod-cli/SKILL.md`、`skills/hwpod-ctl/SKILL.md` 和 `skills/hwlab-agent-runtime/SKILL.md`，都为 `required=true`，由 AgentRun 聚合到当前 workspace `.agents/skills/<name>/SKILL.md`。HWLAB 不再依赖 `/app/skills`、hostPath、默认 Codex skill registry、ConfigMap 或用户长 prompt 作为 skill 注入 fallback。
- AgentRun runtime image 已预装 `gh`，结合 `tool=github` 注入的 `GH_TOKEN` 即可访问 HWLAB/UniDesk PR 与 issue；不得把 GitHub token 放入 prompt 或 `transientEnv`。
## 验收
@@ -54,5 +47,5 @@
- 源码合同测试：`node --test internal/agent/agentrun-dispatch.test.mjs`。
- 语法检查：`node --check internal/agent/agentrun-dispatch.mjs && node --check internal/agent/agentrun-dispatch.test.mjs`。
- 合同必须证明 `UNIDESK_SSH_CLIENT_TOKEN` 不出现在 `transientEnv`，GitHub/UniDesk SSH 能力都通过 AgentRun `toolCredentials` SecretRef 装配，且 runner resource bundle 默认暴露 `hwpod`、`unidesk-ssh`、`promptRefs` 和 `skillRefs`。
- 真实 CLI 验收默认使用短 prompt 走 `backendProfile=deepseek`：首轮 prompt “不调用工具的情况下，你可见的 skill 有哪些？”应能回答 HWLAB bundle skill；同一会话 continuation 应显示 AgentRun 原生 resume 语义且不重复注入 initial prompt；“编译 D601-F103-V2”应触发 `hwpod` HWPOD 路径，若失败则报告正式 blocker，不切换 fallback。
- 真实 CLI 验收默认使用短 prompt 走 `backendProfile=deepseek`：首轮 prompt “不调用工具的情况下，你可见的 skill 有哪些？”应能回答 HWLAB bundle skill；同一会话 continuation 应显示 AgentRun 原生 resume 语义且不重复注入 initial prompt；“检查 HWPOD 状态”应触发 `hwpod inspect` 或等价 HWPOD node-ops 路径，若失败则报告正式 blocker，不切换 fallback。
- 如果 DeepSeek profile 的 trace 明确失败为 AgentRun `provider-auth-failed`，且上游错误码或消息是 `INSUFFICIENT_BALANCE` / account balance 不足，则该次 CLI 验收改用 `--provider-profile minimax-m3` 继续执行同一短 prompt 组。这个规则只替换 provider profile，不替换 AgentRun 装配标准：仍必须使用同一个 `ResourceBundleRef`、`promptRefs`、`skillRefs`、`toolAliases`、Codex stdio `thread/start` / `thread/resume`，不得拼接历史上下文，不得切回旧 HWLAB prompt/skill 注入方式，也不得用 codex-api、generic shell、gateway shell 或诊断镜像作为替代验收。