pikasTech-HWLAB/docs/reference/agentrun-code-agent-dispatch.md

# AgentRun Code Agent Dispatch

本文定义 HWLAB Code Agent 通过 AgentRun `v0.1` 手动调度 API 执行时的装配边界。它只描述稳定的 payload、SecretRef 和 credential 归属，不替代当前 G14 DEV `/v1/agent/chat` 的真实 completed 判定。

## 装配入口

- 源码入口是 `internal/agent/agentrun-dispatch.mjs`。
- `createHwlabAgentRunDispatchAssembly()` 生成 AgentRun `POST /api/v1/runs`、`POST /api/v1/runs/:runId/commands` 和 `POST /api/v1/runs/:runId/runner-jobs` 三段 payload。
- `dispatchHwlabAgentRun()` 使用同一 assembly 顺序调用 AgentRun manager；调用方可以注入 `fetchImpl` 做合同测试或接入真实 manager。
- 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`，默认 namespace 是 `agentrun-v01`，默认 providerId 是 `G14`，默认 workspace branch 是 `v0.2`。
- 人工和 agent 触发 HWLAB Code Agent 任务时，优先使用已成型的 `hwlab-cli client agent session create/send/result/trace`、Workbench 同路径 API 或 CaseRun 封装入口；只有在修 adapter/dispatcher/合同测试时才手写 AgentRun payload。排查 provider、API key、session 或 trace 问题时，先用这些 CLI 原入口确认 runtime config、SecretRef、session、trace 和 result，再定位具体组件，不把问题绕成 generic provider API、runner shell、直连 Cloud API 或临时脚本路径。

## 会话和执行边界

- HWLAB `conversationId` / `sessionId` / `threadId` 是用户可见业务会话 authority；AgentRun `runId` / `commandId` / `runnerJobId` 是执行尝试 identity；AgentRun `SessionRef` 和 per-session PVC 承载 backend/profile 的续接状态。不要把新建 AgentRun run/job 等同于新建 HWLAB session，也不要把复用 workspace selection 当作 session state。
- AgentRun `type=steer` command 是作用在既有 target trace/target command 上的控制命令，不创建新的 HWLAB session，也不改变业务 `conversationId/sessionId/threadId`。HWLAB closeout 和 UI 展示必须同时保留 target command identity 与 `steerCommandId`，并从原 target trace 观察 `agentrun:steer:accepted` / `agentrun:steer:command-created`。steer command 创建成功只证明短连接控制动作已被 AgentRun 接收；目标 turn 后续 terminal 状态按原 command/result 判定。
- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`、`providerId=G14`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef` 子字段保存，不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染，临时处理是修 adapter 的字段归一化并重放最小真实请求，不放宽 AgentRun tenant policy。
- `providerProfile` 由显式 HWLAB session 负责。`client agent session create --provider-profile <profile>` 建立 session 的 provider profile，并映射为 AgentRun `backendProfile`；后续 `client agent send --session-id <sessionId>` 在未显式传 `--provider-profile` 时必须继承该 session 的 `providerProfile`。账号 workspace 的 provider profile 只在 workspace 当前 selected session 与本次目标 session 完全一致时作为 fallback；旧 workspace 状态不得覆盖显式 session。
- 同一 HWLAB session 的 resume 判定看同一个 `sessionId`、`threadId`、`providerProfile/backendProfile`、AgentRun `SessionRef` 和 PVC，而不是只看是否复用了同一个 AgentRun `runId` 或 runner Job。runner pod 被删、Job 被重建或 lease 失效后的临时恢复可以创建 replacement run/job，但只有在复用同一 `SessionRef`/PVC/thread、没有拼接历史 prompt 且 assistant 能看到前序上下文时，才算 session 持久化恢复证据；它不替代 runner reuse window 内复用同一 run/runner 的长期目标。

## 架构混乱处理

- 临时处理：排查 CLI/Web/Cloud API/AgentRun 对 session、project、provider 或 run/job 的口径不一致时，先收集 HWLAB session status、workspace selection、trace/result、AgentRun run/job env、`SessionRef`、PVC phase 和 command events；以单变量热补丁证明最小链路，再回到源码 PR/CI/CD/原入口复测。不得通过长 prompt、历史 messages、fake `thread/resume:completed`、放宽 tenant policy 或手工改 DB lease 来掩盖缺口。
- 长期建议：跨仓库 schema 必须把 `hwlabProjectId` / `agentRunProjectId`、`providerProfile` / `backendProfile`、`hwlabSessionId` / `agentRunSessionId`、`runId` / `sessionId` 分成不同字段；Web 和 CLI 应同时展示业务 session/thread/provider 与执行 run/job/command，避免 operator 把执行尝试误判为业务会话迁移。

## Credential 边界

- Provider credential 只通过 `executionPolicy.secretScope.providerCredentials[]` 的 AgentRun provider SecretRef 引用，默认随 `backendProfile` 选择 `agentrun-v01-provider-deepseek`、`agentrun-v01-provider-codex` 或 `agentrun-v01-provider-minimax-m3`。
- Provider API Key 的 Web 配置面归属 HWLAB `v0.2` 管理页，HWLAB Cloud API 通过已鉴权的管理接口委托 AgentRun 后端更新 profile Secret/配置；dispatch 路径只消费 AgentRun 返回的 SecretRef，不接收浏览器提交的 API Key 原文。完整管理规格见 [spec-v02-provider-management.md](spec-v02-provider-management.md)。
- GitHub PR/issue 能力通过 `toolCredentials[].tool=github` 注入，默认 SecretRef 是 `agentrun-v01-tool-github-pr` key `GH_TOKEN`。
- 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 -> 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` 会把 `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/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`。

## 验收

- 源码合同测试：`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；“检查 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 或诊断镜像作为替代验收。