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。

Credential 边界

• Provider credential 只通过 executionPolicy.secretScope.providerCredentials[] 的 AgentRun provider SecretRef 引用，默认随 backendProfile 选择 agentrun-v01-provider-deepseek、agentrun-v01-provider-codex 或 agentrun-v01-provider-minimax-m3。
• 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 需要的短期执行上下文，例如 HWLAB_DEVICE_POD_API_KEY 和 UNIDESK_MAIN_SERVER_IP；HWLAB_DEVICE_POD_API_KEY 必须标记 sensitive，不得承载 GitHub token、UniDesk SSH client token、provider key、长期 SSH key 或 registry token。
• HWLAB v0.2 device-pod 能力在 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 不把 HWLAB_DEVICE_POD_API_KEY 发往 Cloud Web，也不以 Cloud Web 代理替代设备 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/device-pod-cli.mjs 暴露为 hwpod，并把 tools/unidesk-ssh.mjs 暴露为 runner shell 内的 unidesk-ssh 命令。Device Pod、D601-F103-V2、Keil build/download、job status/output 和 UART/debug-probe 操作必须优先走 hwpod；unidesk-ssh 只用于 UniDesk passthrough 任务，不能替代 Device Pod 正式路径。
• Device Pod lease 不是独立 runner 控制命令；标准 hwpod surface 只提交命名 Device Pod job。需要 lease 时，token 只能作为 --lease-token 跟随实际 mutating job 请求转发给 cloud-api。Agent 不得调用 hwpod lease ...，也不得新增 gateway shell 或其他 fallback 来绕过 job authority。
• 默认 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，都为 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；“编译 D601-F103-V2”应触发 hwpod Device Pod 路径，若失败则报告正式 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 或诊断镜像作为替代验收。