@@ -4,19 +4,19 @@
## 在系统中的职责划分
- HWLAB `hwlab-cloud-api` 是业务 dispatcher：继续负责用户登录、session owner、device-pod 授权、Workbench `/v1/agent/chat` 合同、result/trace/cancel 对外接口和业务权限判断。
- HWLAB `hwlab-cloud-api` 是业务 dispatcher：继续负责用户登录、session owner、HWPOD 授权、Workbench `/v1/agent/chat` 合同、result/trace/cancel 对外接口和业务权限判断。
- AgentRun `agentrun-mgr` 是执行事实 authority：负责 run、command、event、runner job、backend profile、SecretRef、terminal status 和手动调度 API。
- Provider profile API Key 管理由 HWLAB Cloud API 鉴权后委托 AgentRun manager； spec-v01-provider-profile-management.md ](spec-v01-provider-profile-management.md )。
- `agentrun-runner` 是手动启动的执行者：从 manager claim run、poll command、调用 backend adapter、append events、ack command、上报 command terminal，并在同一 runner Job 生命周期内继续等待同 run 的后续 command；
- HWLAB 不直接写 AgentRun Postgres、不读取 AgentRun Secret、不直接创建 Kubernetes Job；所有跨服务操作只走 AgentRun RESTful API。
- AgentRun 不内建 HWLAB device-pod /gateway 业务授权；涉及硬件、用户授权或 device lease 的判断仍由 HWLAB 自己完成。
- AgentRun 不内建 HWLAB HWPOD /gateway 业务授权；涉及 HWPOD 四要素、用户授权或硬件访问凭证 的判断仍由 HWLAB 自己完成。
## 非目标
- 本阶段不要求自动 scheduler、pending scan、capacity selection 或长驻调度器。
- 不改变 HWLAB 对外 `/v1/agent/chat` 、`/result` 、`/trace` 、`/cancel` 用户合同。
- 不使用 SSE、WebSocket、long-polling 或长同步 `turn` 请求替代 durable resource 模型。
- 不把 HWLAB 的 provider Secret、device token、gateway route 或 kubeconfig 复制给业务客户端。
- 不把 HWLAB 的 provider Secret、HWPOD token、gateway route 或 kubeconfig 复制给业务客户端。
- 不把 mock、fixture、source-only smoke 或 dry-run 结果当作 HWLAB canary 通过证据。
- 不把 trace、日志、诊断文案、降级原因或“已观测到缺口”当作功能完成。若 HWLAB v0.2 原有 Code Agent 需要的能力在 AgentRun v0.1 中缺失，必须补齐 AgentRun 自身能力；若实现未修复，必须修复实现本身，观测只作为定位和验收证据。
@@ -25,7 +25,7 @@
``` text
HWLAB Workbench
-> hwlab-cloud-api /v1/agent/chat
-> HWLAB 用户/session/device 权限判断
-> HWLAB 用户/session/HWPOD 权限判断
-> AgentRun POST /api/v1/runs
-> AgentRun POST /api/v1/runs/:runId/commands
-> AgentRun POST /api/v1/runs/:runId/runner-jobs
@@ -39,7 +39,7 @@ HWLAB 应保存 `traceId -> runId/commandId/attemptId/jobName` 映射。用户
## HWLAB v0.2 Code Agent 能力吸收基线
AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执行能力，不吸收 HWLAB 的用户鉴权、device-pod 授权、Workbench UI 或业务 trace schema。下表是后续实现时的代码追溯入口，目的是复用 HWLAB 已验证的边界和判定标准，而不是重新发明一套 Agent 行为。
AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执行能力，不吸收 HWLAB 的用户鉴权、HWPOD 授权、Workbench UI 或业务 trace schema。下表是后续实现时的代码追溯入口，目的是复用 HWLAB 已验证的边界和判定标准，而不是重新发明一套 Agent 行为。
| HWLAB v0.2 原有能力 | HWLAB 代码/文档追溯入口 | AgentRun 自身承接点 | SPEC 归属 |
| --- | --- | --- | --- |
@@ -52,7 +52,7 @@ AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执
| 初始业务 prompt 注入 | `internal/cloud/codex-stdio-session.ts` 的 boundary instructions、`internal/cloud/codex-stdio-session-helpers.ts` 的 `buildCodexUserPrompt()` | HWLAB 把稳定业务 instruction 文件放入同一 Git bundle，并通过 `ResourceBundleRef.promptRefs` 指定；AgentRun 只在新 thread 首轮注入，resume 不重复注入 | [spec-v01-runtime-assembly.md ](spec-v01-runtime-assembly.md )、[spec-v01-backend-codex.md ](spec-v01-backend-codex.md ) |
| skill discovery 与 skill facts | `internal/cloud/skills-store.ts` 、`internal/cloud/codex-stdio-session-helpers.ts` 的 `discoverSkillsForStdio()` 和 `codexSidecarSkillsPrompt()` | HWLAB 把 required skill manifest 放入同一 Git bundle，并通过 `ResourceBundleRef.skillRefs` 指定；AgentRun 聚合到 runner workspace skill registry 并向 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 ) |
| device-pod 短期会话 env 注入 | `internal/cloud/server-code-agent-http.ts` 的 `c odeAgentDevicePodAuthEnv()` `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 ) |
| HWPOD/HWLAB runtime 短期 env 注入 | HWLAB Cloud API 的 C ode 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` ； 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 ) |
@@ -71,7 +71,7 @@ AgentRun `v0.1` 承接 HWLAB v0.2 时，只吸收原有 Code Agent 的通用执
| `idempotencyKey` | HWLAB 必须用 `traceId` 、`messageId` 或等价稳定 key；相同 key 和相同 payload 返回既有 job/attempt。 |
| `image` / `backendImageRef` | 只能来自 manager allowlist、GitOps/catalog 或受控默认值；客户端不能传任意镜像扩大执行面。 |
| `retention` / `ttlSecondsAfterFinished` | 可选；默认遵循 runner Job TTL 规格。 |
| `transientEnv` | 可选，只用于本次 runner Job 的 Kubernetes env 渲染；不得写入 run/command/result/event 明文。用于承接 HWLAB 原 Code Agent 的短期 device-pod session token 和 API URL。 |
| `transientEnv` | 可选，只用于本次 runner Job 的 Kubernetes env 渲染；不得写入 run/command/result/event 明文。用于承接 HWLAB dispatcher 生成的 owner-scoped HWPOD/runtime context，例如 `HWLAB_API_KEY` 、 `HWLAB_RUNTIME_ API_ URL` 、 `HWLAB_RUNTIME_WEB_URL` 和 endpoint metadata 。 |
响应必须短返回 JSON，不等待完整模型 turn，至少包含：`runId` 、`commandId` 、`attemptId` 、`jobName` 、`namespace` 、`runnerId` 、`logPath` 或 `podIdentity` 、后续 `commands show` 与 `events` 轮询入口。重复提交若 payload 不同，必须结构化失败，不能创建第二个同名业务 attempt。
@@ -88,8 +88,8 @@ HWLAB canary 创建 run 时应使用以下字段口径：
| `providerId` | `G14` ，只表示目标 provider，不授予 HWLAB 业务权限。 |
| `backendProfile` | `deepseek` 、`codex` 或 `minimax-m3` ，由 HWLAB 或调度方显式选择；缺少 matching SecretRef 必须失败，不 fallback。 |
| `workspaceRef` | 必须引用 ResourceBundleRef 中的 Git-only full commit；不得由 runner 猜 host path。 |
| `resourceBundleRef.promptRefs[]` | 用于承接 HWLAB 稳定初始 prompt，例如 `hwlab-v02-runtime` 、device-pod/no-fallback policy；必须来自同一 full commit， `inject=thread-start` ，新 thread 首轮注入，resume 不注入。 |
| `resourceBundleRef.skillRefs[]` | 用于承接 HWLAB required skills，例如 `device- pod-cli ` ；必须来自同一 full commit 的 `SKILL.md` ，
| `resourceBundleRef.promptRefs[]` | 用于承接 HWLAB 稳定初始 prompt，例如 `hwlab-v02-runtime` 、`hwpod-runtime- policy` ， `inject=thread-start` ，新 thread 首轮注入，resume 不注入。 |
| `resourceBundleRef.skillRefs[]` | 用于承接 HWLAB required skills，例如 `hwpod-cli` 、 `hw pod-ct l``SKILL.md` ，
| `resourceBundleRef.toolAliases[]` | 用于暴露短入口，例如 `hwpod` ；缺 alias 时修 runner/bundle，不改走长路径 wrapper。 |
| `executionPolicy` | sandbox、network、timeout、secretScope 必须显式，不得由 HWLAB 扩大 AgentRun Secret 范围。 |
| `executionPolicy.secretScope.toolCredentials[]` | 需要 UniDesk SSH passthrough 时必须声明 `tool=unidesk-ssh` 、`purpose=ssh-passthrough` 、SecretRef `agentrun-v01-tool-unidesk-ssh` 、projection env `UNIDESK_SSH_CLIENT_TOKEN` ；不得把 token 放入 command payload 或 runner-job transientEnv。 |
@@ -97,7 +97,7 @@ HWLAB canary 创建 run 时应使用以下字段口径：
`tenantId` / `projectId` 是 AgentRun manager 的 policy 边界，不是 HWLAB Workbench project。HWLAB adapter 可以把业务 project/workspace 写入 `metadata.hwlabProjectId` 、`metadata.hwlabWorkspaceId` 或 `workspaceRef` ，但不得覆盖 AgentRun `projectId=pikasTech/HWLAB` ；否则 manager 必须按 `tenant-policy-denied` 拒绝。`providerProfile` 是 HWLAB 入口字段，进入 AgentRun 后必须映射为 `backendProfile` ；同一个 HWLAB session 的后续 turn 应继承 session provider profile，不能被 stale workspace provider 覆盖。
Command 第一阶段要求 `type=turn` 和 `type=steer` 。`turn` 保存用户原始 prompt、conversation metadata、profile 选择和 HWLAB trace correlation；稳定业务 prompt、skill 清单和工具入口不写入 command payload，而是通过 `ResourceBundleRef.promptRefs` 、`skillRefs` 和 `toolAliases` 装配。`steer` 保存运行中引导文本，并由 runner 在同 run active turn 期间转发到 backend。业务 cancel 仍走 run/command cancel API，不用 `steer` 伪装。不得把 cookie、session token、provider credential、device internal token、Secret value、历史消息或大段 skill manifest 写入 payload。
Command 第一阶段要求 `type=turn` 和 `type=steer` 。`turn` 保存用户原始 prompt、conversation metadata、profile 选择和 HWLAB trace correlation；稳定业务 prompt、skill 清单和工具入口不写入 command payload，而是通过 `ResourceBundleRef.promptRefs` 、`skillRefs` 和 `toolAliases` 装配。`steer` 保存运行中引导文本，并由 runner 在同 run active turn 期间转发到 backend。业务 cancel 仍走 run/command cancel API，不用 `steer` 伪装。不得把 cookie、session token、provider credential、HWPOD internal token、Secret value、历史消息或大段 skill manifest 写入 payload。
## 需要补齐的能力
@@ -160,20 +160,21 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceB
"repoUrl" : "git@github.com:pikasTech/HWLAB.git" ,
"commitId" : "<full commit sha>" ,
"toolAliases" : [
{ "name" : "hwpod" , "path" : "tools/device- pod-cli.mj s" , "kind" : "node -script" }
{ "name" : "hwpod" , "path" : "tools/hw pod-cli.t s" , "kind" : "bun -script" }
] ,
"promptRefs" : [
{ "name" : "hwlab-v02-runtime" , "path" : "internal/agent/prompts/hwlab-v02-runtime.md" , "inject" : "thread-start" , "required" : true } ,
{ "name" : "device-pod -policy" , "path" : "internal/agent/prompts/device-pod -policy.md" , "inject" : "thread-start" , "required" : true }
{ "name" : "hwpod-runtime -policy" , "path" : "internal/agent/prompts/hwpod-runtime -policy.md" , "inject" : "thread-start" , "required" : true }
] ,
"skillRefs" : [
{ "name" : "device- pod-cli" , "path" : "skills/device- pod-cli/SKILL.md" , "required" : true , "aggregateAs" : "device- pod-cli" }
{ "name" : "hw pod-cli" , "path" : "skills/hw pod-cli/SKILL.md" , "required" : true , "aggregateAs" : "hw pod-cli" } ,
{ "name" : "hwpod-ctl" , "path" : "skills/hwpod-ctl/SKILL.md" , "required" : true , "aggregateAs" : "hwpod-ctl" }
]
}
}
```
这些 prompt 文件只写稳定规则，例如 HWLAB Cloud Workbench Code Agent 身份、Device Pod/ D601-F103-V2/Keil/build/download/UART/debug-probe 的标准 `hwpod` 路径、禁止 lease、禁止 Cloud Web device-pod AP I、禁止 session-token fallback、禁止长路径 wrapper，以及历史上下文只走 Codex stdio 原生 `thread/resume` 。它们不写用户本轮任务、不写会话历史、不写 Secret 或一次性 issue 过程。
这些 prompt 文件只写稳定规则，例如 HWLAB Cloud Workbench Code Agent 身份、HWPOD 四要素（target device、workspace、debug probe、io probe）、 D601-F103-V2/Keil/build/download/UART 的标准 `hwpod` 路径、禁止旧 Device Pod/profile/device-pod-cli fallback、禁止 Cloud Web 业务 API 替代 runner 内 HWPOD CL I、禁止 session-token fallback、禁止长路径 wrapper，以及历史上下文只走 Codex stdio 原生 `thread/resume` 。它们不写用户本轮任务、不写会话历史、不写 Secret 或一次性 issue 过程。
首轮新 thread 必须自动注入这些 prompt 和 skill facts，使 Web 简短 prompt 也能识别 HWLAB 标准能力。后续 turn/resume 不重复注入；若 resume 失败，按 AgentRun Codex stdio 规则失败，不拼接历史 prompt 模拟继续。
@@ -187,7 +188,7 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceB
| 4 | ResourceBundleRef materialization | Git-only checkout、workspace 前缀、commit/tree 摘要、failureKind | 使用 full commit；不接受 branch/tag/HEAD；不覆盖 Secret/session/runtime home。 |
| 5 | Resource prompt/skill assembly | `promptRefs` thread-start 注入、`skillRefs` registry 聚合、required blocker、hash/bytes 可见 | 简短 HWLAB prompt 能看到业务 instruction 和 required skill；
| 6 | SessionRef 持久化与 runner 多 turn | session record/store、thread resume、runner command loop、TTL/GC、profile 隔离 | 同一 conversation 连续两轮复用同一 run/runner Job；第二轮不重新 materialize bundle、不重复注入 initial prompt；不同 profile 不污染。 |
| 7 | HWLAB v0.2 canary | HWLAB dispatcher adapter、traceId 映射、result/trace 转换 | 普通自然语言最短 turn 真实 completed 且 reply 非空；device-pod 仍由 HWLAB 授权。 |
| 7 | HWLAB v0.2 canary | HWLAB dispatcher adapter、traceId 映射、result/trace 转换 | 普通自然语言最短 turn 真实 completed 且 reply 非空；HWPOD 仍由 HWLAB 授权。 |
## 测试规格
@@ -217,15 +218,15 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceB
### T7 HWLAB prompt/skill 装配
阅读本文和 [spec-v01-runtime-assembly.md ](spec-v01-runtime-assembly.md )，然后用 HWLAB canary `ResourceBundleRef` 指定 `promptRefs` 、`skillRefs` 和 `toolAliases` 。首轮 Web/CLI 简短 prompt 只写“编译 D601-F103-V2”或等价自然语言，确认 Codex turn 能看到 HWLAB runtime prompt、`device- pod-cli ` skill facts 和 `hwpod` alias；第二轮 continuation 使用同一 thread resume，确认 `initialPromptInjected=false` ，没有手工拼接历史；删除 required skill/prompt 后确认 blocked 而不是 fallback 到默认 Codex 5 个系统 skill。
阅读本文和 [spec-v01-runtime-assembly.md ](spec-v01-runtime-assembly.md )，然后用 HWLAB canary `ResourceBundleRef` 指定 `promptRefs` 、`skillRefs` 和 `toolAliases` 。首轮 Web/CLI 简短 prompt 只写“编译 D601-F103-V2”或等价自然语言，确认 Codex turn 能看到 HWLAB runtime prompt、`hwpod-cli` / `hw pod-ct l``hwpod` alias；第二轮 continuation 使用同一 thread resume，确认 `initialPromptInjected=false` ，没有手工拼接历史；删除 required skill/prompt 后确认 blocked 而不是 fallback 到默认 Codex 5 个系统 skill。
### T8 DS 短 prompt 真实验收
阅读本文、[spec-v01-backend-codex.md ](spec-v01-backend-codex.md ) 和 HWLAB `spec-v02-hwlab-cli.md` ，然后必须用正式 HWLAB CLI/Web 等价短连接入口提交真实 `backendProfile=deepseek` 的短 prompt 到 AgentRun runtime，不允许用长提示词把规则补给模型。验收至少包含三条 prompt：
1. “不调用工具的情况下，你可见的 skill 有哪些？”确认回复包含 `ResourceBundleRef.skillRefs` 中的 HWLAB required skill，例如 `device- pod-cli ` ，并且不只返回 Codex 默认 5 个系统 skill。
2. “你当前 HWLAB 初始规则里，D601-F103-V2 应该走哪个标准入口？请只回答入口和禁止路径。”确认回复能说出 `hwpod` 、Cloud API/assembled env、禁止 lease、禁止 Cloud Web device-pod API 、禁止 session-token fallback 和禁止长路径 wrapper。
3. “编译 D601-F103-V2。”确认短 prompt 能按注入规则触发 `hwpod` /Device Pod 标准路径 ，而不是要求用户补充长 prompt。
1. “不调用工具的情况下，你可见的 skill 有哪些？”确认回复包含 `ResourceBundleRef.skillRefs` 中的 HWLAB required skill，例如 `hwpod-cli` 和 `hw pod-ct l`
2. “你当前 HWLAB 初始规则里，D601-F103-V2 应该走哪个标准入口？请只回答入口和禁止路径。”确认回复能说出 `hwpod` 、`hwpod-cli` / `hwpod-ctl` 、assembled runtime env、禁止旧 Device Pod/profile/device-pod-cli fallback 、禁止 session-token fallback 和禁止长路径 wrapper。
3. “编译 D601-F103-V2。”确认短 prompt 能按注入规则触发 `hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node` 正向链路 ，而不是要求用户补充长 prompt。
上述三条必须来自真实 DS/DeepSeek profile 的 Codex stdio `thread/start` /`turn/start` 和后续 `thread/resume` 事件；trace/result 必须显示 `initialPromptInjected=true` 的首轮、skill refs 摘要、真实 provider profile、terminal status，以及 continuation 时 `initialPromptInjected=false` 。如果回复只列出 Codex 默认系统 skill、不能识别 HWLAB 初始规则或需要用户长 prompt 才能触发 `hwpod` ，验收失败。
@@ -238,6 +239,6 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须迁移为 `ResourceB
| cancel | 已实现最小闭环 | 已提供 run/command cancel API； ，
| SessionRef | 已实现最小持久化 | run 可携带 `sessionRef` ， ， ，
| SessionRef | v0.1.1 已实现/已通过 HWLAB v0.2 原入口复测 | 在「metadata-only 最小持久化」基础上把 session 真实持久化：每个 session 绑 RWO PVC（ `agentrun-v01-session-<sessionId>` ），runner Job 把 PVC 直接挂到 `${CODEX_HOME}/<codex_rollout_subdir>` ，
| ResourceBundleRef | 已实现 Git-only materialization/待 promptRefs 与 skillRefs | run 可携带 `repoUrl + full commitId` ， `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录并记录 commit/tree/workspace 摘要；`toolAliases` 已实现；上传文件和对象存储仍不进入 v0.1；HWLAB 初始 prompt 与 skill 注入按本规格待补齐 。 |
| ResourceBundleRef | 已实现 Git-only materialization/promptRefs/ skillRefs 装配 | run 可携带 `repoUrl + full commitId` ， `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录并记录 commit/tree/workspace 摘要；`toolAliases` 、 `promptRefs` thread-start 注入和 `skillRefs` registry 聚合已实现；上传文件和对象存储仍不进入 v0.1 。 |
| 同 run/runner 多 turn | 已实现最小闭环 | runner Job 在 idle timeout 内持续 poll 同一 run 的后续 command；普通 turn completed 不终结 run，
| HWLAB v0.2 canary | 已实现/已通过 HWLAB v0.2 原入口复测 | HWLAB dispatcher adapter 已调 AgentRun 手动调度 API，并能转换 result/trace；
Codex