pikasTech-HWLAB/docs/reference/spec-hwpod-harness.md

# HWPOD Harness 规格

本文是 HWLAB `v0.2` 的 HWPOD Harness 长期规格。概念体系和实施跟踪见 [pikasTech/HWLAB#897](https://github.com/pikasTech/HWLAB/issues/897)。当前实现只打通单线程核心业务闭环，不把鉴权、安全、并发、计量、复杂调度或 Evidence 体系作为前置条件。

本规格不保留旧设备执行路径作为迁移对照；新任务只按 HWPOD 单通道实现和验收。

## 快速迭代阶段

快速迭代阶段把业务翻译权放在 Code Agent workspace 内：

```text
Code Agent workspace
  .hwlab/hwpod-spec.yaml
  hwpod-cli
  hwpod-ctl
  hwpod-compiler-cli

hwpod-cli / hwpod-ctl
  -> hwpod-compiler-cli
    -> hwpod-node-ops plan
      -> hwlab-api
        -> hwpod-node
```

核心边界：

- `hwpod-spec` 存放在 Code Agent workspace 内，是当前 hwpod 的本地声明式定义。
- `hwpod-cli` 是用户和 Code Agent 执行研发动作的入口。
- `hwpod-ctl` 是和 `hwpod-cli` 平级的管理入口，用于初始化、修改、检查 `hwpod-spec`，以及 smoke/node 状态类操作。
- `hwpod-compiler-cli` 是 workspace-local 编译器，把高层 intent 和 `hwpod-spec` 编译为 `hwpod-node-ops`。
- `hwlab-api` 只接收 `hwpod-node-ops` plan，负责转发和返回结果，不承担业务翻译。
- `hwpod-node` 是靠近硬件的薄执行节点，只维护少量稳定 op handler，不保存完整 `hwpod-spec`，也不解释高层 hwpod intent。

## 云端平台阶段

快速闭环跑通后，再逐步迁移为云端平台能力：

- 将 workspace-local `hwpod-spec` 注册或同步到云端，形成云端 hwpod source of truth。
- 将 `hwpod-ctl spec` 从本地文件管理迁移为云端 hwpod/spec 管理，同时保留本地导入、导出和调试能力。
- 将 `hwpod-compiler-cli` 服务化为云端 `hwpod-compiler`，供 Web、Code Agent、batch harness 和 CI/HIL gate 共用。
- 将 `hwlab-api` 从薄转发面扩展为 hwpod run 管理面，承载 run 状态、计划版本、结果归档和后续 Evidence。
- 只在多个任务反复需要同一类基础动作时扩展 `hwpod-node-ops`，避免把业务变化下沉到 node。

## 核心概念

| 概念 | 定义 | 当前阶段含义 |
| --- | --- | --- |
| `hwpod` | 硬件研发执行逻辑实体 | 由 target device、workspace、debug probe、io probe 四要素组成 |
| `hwpod-spec` | hwpod 的声明式定义 | 先存放在 Code Agent workspace 内，后续迁移到云端维护 |
| `hwpod-cli` | 用户和 Code Agent 的任务入口 | 发起 inspect、workspace、build、download、reset、UART、JSON-RPC 和 closeout |
| `hwpod-ctl` | workspace 内的管理入口 | 初始化/检查/修改 spec、绑定 node、执行 smoke 和临时维护动作 |
| `hwpod-compiler-cli` | workspace-local HWPOD 编译器 | 把高层 intent + spec 编译为 `hwpod-node-ops` plan |
| `hwpod-compiler` | 云端化后的编译服务 | 由 `hwpod-compiler-cli` 成熟后服务化而来 |
| `hwpod-node-ops` | node 最小操作协议 | `hwlab-api` 和 `hwpod-node` 之间的稳定执行契约 |
| `hwpod-node` | 靠近硬件的薄执行节点 | PC host、AI 网关、调试器边缘设备或实验室控制盒上的 executor |
| `hwlab-api` | HWPOD node-ops 转发面 | 快速阶段只转发 node-ops plan 并返回 result |

`hwpod` 的四个本体要素固定为：

- target device：被研发或调试的目标设备。
- workspace：项目源码、工程、构建工具链和 artifact 边界。
- debug probe：下载、复位、chip-id、调试连接等能力。
- io probe：UART、JSON-RPC、GPIO/relay 或其他 I/O 观测与交互能力。

`nodeBinding` 是 `hwpod-spec` 的部署字段，不属于 hwpod 四个本体要素。

## hwpod-spec

快速迭代阶段的默认 spec 路径是 `.hwlab/hwpod-spec.yaml`。CLI 也可以通过 `--spec <path>` 显式指定。第一版 spec 保持轻量：

```yaml
apiVersion: hwlab.dev/v0alpha1
kind: Hwpod
metadata:
  uid: hwpod-local-demo
  name: demo
spec:
  targetDevice:
    board: D601-F103-V2
    mcu: STM32F103
  workspace:
    path: /workspace/project
    toolchain: keil-mdk
    keilProject: firmware/demo.uvprojx
    keilTarget: Debug
  debugProbe:
    type: daplink
    adapter: keil
    probeUid: 3FD750C63E342E24
    programBackend: keil
  ioProbe:
    uart:
      id: uart/1
      port: COM9
      baudrate: 115200
  nodeBinding:
    nodeId: node-d601-pc-host
    nodeType: pc-host
```

最低校验要求：

- `kind` 必须为 `Hwpod`。
- `spec.targetDevice`、`spec.workspace`、`spec.debugProbe`、`spec.ioProbe` 必须存在。
- `spec.nodeBinding.nodeId` 必须存在。
- `spec.workspace.path` 必须存在。

Keil MDK 装配规则：当 `spec.workspace.toolchain` 为 `keil-mdk`、`keil`、`mdk` 或 `uv4` 时，`hwpod-compiler-cli` 可以直接从 `hwpod-spec` 生成 `debug.build` / `debug.download` 的 node-side command。`spec.workspace.keilProject` 或 `spec.workspace.projectPath` 指向 `.uvprojx`，相对路径按 `spec.workspace.path` 解析；`spec.workspace.keilTarget` 或 `spec.workspace.targetName` 指向 Keil target。`spec.debugProbe.probeUid` 用于固定 DAP-Link/CMSIS-DAP 选择，`spec.debugProbe.programBackend` 默认按 Keil UV4 工程链路下载。下载前若存在 `probeUid`，compiler 会先生成 Keil probe-binding 写回命令，再生成 `program --program-backend keil` 命令，以保持旧 host profile 中 probe 绑定与 Keil 下载语义在新 hwpod 概念系统内收敛。

`spec.workspace.buildCommand`、`spec.debugProbe.downloadCommand` 和 `spec.debugProbe.resetCommand` 仍是调试覆盖出口；标准 case 和 Code Agent runner 不应依赖这些字段长期手写 Keil 主流程。旧 `device-host-cli` / device pod profile 不再作为 compiler 输入权威，相关工程、target、probe 和下载 backend 信息必须迁入 `hwpod-spec`。

## hwpod-node-ops

`hwpod-node-ops` 不表达用户意图，只表达 node 可执行的基础动作。第一版最小集合：

| op | 用途 |
| --- | --- |
| `node.health` | 查询 node 存活和基础状态 |
| `node.version` | 查询 node runtime 版本 |
| `node.inventory` | 查询 workspace/probe/io 能力 |
| `workspace.ls` | 列目录 |
| `workspace.cat` | 读文件 |
| `workspace.rg` | 搜索文件内容 |
| `workspace.apply-patch` | 应用源码补丁 |
| `debug.build` | 编译工程 |
| `debug.download` | 下载或烧录目标设备 |
| `debug.reset` | 复位目标设备 |
| `io.uart.read` | 读取 UART |
| `io.uart.write` | 写入 UART |
| `io.uart.jsonrpc` | 通过 UART 做 JSON-RPC |
| `cmd.run` | 临时维护命令透传，仅用于 `hwpod-ctl` 或早期薄 node 调试 |

`hwpod-node` 是 HWPOD 的唯一受控节点执行器。`cmd.run` 的命令解析、PATH 稳定性和跨平台差异必须在 `hwpod-node` 本体内处理；当 Windows service、后台进程或 D601 host 的环境变量与交互 shell 不一致时，不得用 gateway shell、手工 PowerShell、预先手工创建 worktree 或其他旁路代替 `hwpod-node-ops -> hwpod-node`。D601/Windows 实地调试应使用 UniDesk SSH 透传 `D601:win` 观察进程、PATH、工具安装位置和日志，但修复必须回到 `hwpod-node` 源码、配置或启动入口，并用 `/v1/hwpod-node-ops` 原链路复测。

标准 plan 形态：

```json
{
  "contractVersion": "hwpod-node-ops-v1",
  "planId": "plan_xxx",
  "hwpodId": "hwpod-local-demo",
  "nodeId": "node-d601-pc-host",
  "intent": "workspace.ls",
  "ops": [
    { "opId": "op_001", "op": "workspace.ls", "args": { "path": "." } }
  ]
}
```

每个 op 的结果第一版保持简单：

```ts
type HwpodNodeOpResult = {
  opId: string;
  op: string;
  ok: boolean;
  status: "completed" | "blocked" | "failed";
  exitCode?: number;
  stdout?: string;
  stderr?: string;
  summary?: string;
  blocker?: { code: string; summary: string } | null;
};
```

## CLI 入口

快速阶段的源码入口使用 Bun 直接运行 TypeScript 文件；runner 或 skill 可以把这些入口暴露为短命令：

```bash
bun tools/hwpod-ctl.ts spec init --spec .hwlab/hwpod-spec.yaml
bun tools/hwpod-ctl.ts spec validate --spec .hwlab/hwpod-spec.yaml
bun tools/hwpod-compiler-cli.ts compile --spec .hwlab/hwpod-spec.yaml --intent workspace.ls --args '{"path":"."}'
bun tools/hwpod-cli.ts inspect --spec .hwlab/hwpod-spec.yaml --dry-run
bun tools/hwpod-node.ts serve --host 127.0.0.1 --port 19678
```

`hwpod-cli` 的正常任务路径是：读取 spec、调用 compiler、把 node-ops plan 交给 `hwlab-api`，最后输出 closeout/result。`hwpod-ctl` 的管理路径可以在本地直接修改 spec，也可以生成 smoke plan 交给 `hwlab-api` 验证 node 链路。

## CaseRun 无服务阶段

第一阶段 CaseRun 不引入常驻调度服务，由 `hwlab-cli case` 组合 case registry repo、本地 `.state`、`hwpod-cli`、`hwpod-compiler-cli`、`hwlab-api` 和在线 `hwpod-node` 完成单次运行。标准 case registry repo 是 `pikasTech/hwlab-case-registry`，本地默认 checkout 路径是 `/root/hwlab-case-registry`；历史 `pikasTech/hwpod-cases` 只作为迁移前来源。case registry repo 提供 `cases/<caseId>/case.json` 与同目录 `hwpod-spec.yaml`；每次运行会先在 subject repo 本地 checkout 下创建隔离 Git worktree，再把 spec 复制到 `.state/hwlab-cli/caserun/<runId>/.hwlab/hwpod-spec.yaml` 并把 `spec.workspace.path` 改写到该隔离 worktree，形成 run-local spec。

CaseRun 的 case registry repo 与 subject repo 必须分离。标准 registry repo 是 `pikasTech/hwlab-case-registry`，G14 标准 checkout 是 `/root/hwlab-case-registry`；历史 `pikasTech/hwpod-cases` 和 `/root/hwpod-cases` 只作为迁移前来源，不再作为新 CaseRun 入口或写入目标。case registry repo 只保存 `case.json`、HWPOD spec 或 spec 引用、`subject` 引用、期望结果和 `runs/<caseId>/<runId>/` 审计产物；它不保存或替代实际固件、工程、测试样例或产品代码库。subject repo 是被开发、被测试、被编译或被下载验证的真实源码仓库，`case.json.subject` 必须明确写入 `repoLocalPath` 和 `commitId`，其中 `repoLocalPath` 是绑定 HWPOD node 上的本地 Git checkout，`commitId` 是完整 40 字符 subject commit id。`case run` 准备阶段只能从 `repoLocalPath` 执行 `git worktree add --detach <worktree> <commitId>`，不得 clone/fetch GitHub，也不得把 branch、tag 或当前 HEAD 作为执行依据或 fallback。`subdir` 只描述 subject repo 内的 case 关注区域，不能替代 `spec.workspace.path` 的隔离 worktree。`evidence.json` 必须记录 subject repo 本地路径、subject commit、subdir 和 run-local worktree，避免把 floating ref 或外部脏 workspace 当作可审计证据。

标准 `case.json` 的 subject 字段形态如下：

```json
{
  "subject": {
    "repoLocalPath": "F:\\Work\\HWLAB-CASE-F103",
    "commitId": "df7a4e6e551fa90d64bde5537cc000f89d63dd20",
    "subdir": "projects/01_baseline"
  }
}
```

### CaseRun 当前实现边界

当前 `d601-f103-v2-compile` 是 compile-only smoke，用于验证 case registry repo 与 subject repo 分离、`repoLocalPath` 加 `commitId` 的 subject provenance、隔离 subject worktree、run-local spec rewrite 和 D601 Keil 编译证据。它不创建 HWLAB Code Agent session，不调用 DS/DeepSeek/provider，不向 Code Agent 下发任务 prompt，不等待 agent trace，也不验证 agent 在源码仓库内完成修改。因此，compile-only CaseRun 是 HWPOD runner 和 Keil 编译底座 smoke，不是 Code Agent 能力评测。

### CaseRun 目标边界：布置舞台与任务 prompt

目标形态中，`case run` 的职责是布置 subject worktree、HWPOD spec、工具入口、上下文包和任务 prompt，再创建或调用 HWLAB Code Agent / AgentRun session，让 Code Agent 在隔离 worktree 内完成源码修改、分析或调试任务。`case run` 可以等待 agent terminal state、读取 workspace diff、执行 build/download/UART smoke、收集 evidence 和判定验收；不得替 Code Agent 生成补丁、直接修改 subject source 或把 deterministic runner 实现当作任务答案。对于“增加一行打印代码”这类 case，源码 diff 必须来自 Code Agent session，runner 只能验收该 diff。边界跟踪见 [pikasTech/HWLAB#976](https://github.com/pikasTech/HWLAB/issues/976)。

agent-task CaseRun 的 evidence 必须至少记录：subject repo 本地路径、subject commit、隔离 worktree、任务 prompt 来源、Code Agent session/trace/provider/model、agent 产生的 workspace diff、验证动作和验证结果。compile-only smoke 的 evidence 不得伪造或补写 agent provenance。

Agent compile-only 阶段必须走 HWLAB Code Agent / AgentRun 的成熟入口：CaseRun 负责生成 prompt/context、创建或调用显式 Code Agent session，并通过 `case run start/status/result/logs` 轮询终态；prompt 必须要求 agent 在自己的 AgentRun workspace 内使用标准 `hwpod` / `hwpod-ctl` 执行 compile-only 验证，例如 `hwpod-ctl spec validate`、`hwpod inspect` 和 `hwpod build`。CaseRun 可以保留 runner 后置 compile 作为收尾或对照证据，但 evidence 必须把 agent trace 中的 HWPOD commandExecution 与 runner 后置 `hwpod-cli build` 分开记录，不得把 runner 直接编译伪装成 agent 编译。

CaseRun 是强化学习 Harness 的最小执行单元，但它本身不是完整 epoch。完整 epoch 还需要样本选择、策略生成、奖励/评价、批量调度、跨 run 归因和自动训练闭环；第一阶段只要求一个 `caseId` 能从 case registry repo 进入真实 HWPOD 编译闭环，并把可审计产物稳定落盘。

最小入口：

```bash
bun tools/hwlab-cli/bin/hwlab-cli.ts case prepare d601-f103-v2-compile --case-repo /root/hwlab-case-registry
bun tools/hwlab-cli/bin/hwlab-cli.ts case build d601-f103-v2-compile --case-repo /root/hwlab-case-registry --run-dir .state/hwlab-cli/caserun/<runId>
bun tools/hwlab-cli/bin/hwlab-cli.ts case collect d601-f103-v2-compile --case-repo /root/hwlab-case-registry --run-dir .state/hwlab-cli/caserun/<runId>
bun tools/hwlab-cli/bin/hwlab-cli.ts case run d601-f103-v2-compile --case-repo /root/hwlab-case-registry
bun tools/hwlab-cli/bin/hwlab-cli.ts case run start d601-f103-v2-compile --case-repo /root/hwlab-case-registry --run-id <runId>
bun tools/hwlab-cli/bin/hwlab-cli.ts case run status <runId>
bun tools/hwlab-cli/bin/hwlab-cli.ts case run result <runId>
bun tools/hwlab-cli/bin/hwlab-cli.ts case run logs <runId> --tail 8000
```

`case run` 在当前版本只负责编排流程和记录原始证据，不做 evidence 自动评价、自动打分或门禁判断。流程是：prepare 先在 subject repo 本地 checkout 下创建 `.worktree/caserun-<runId>` 隔离 worktree并写入 run-local spec，然后生成 Code Agent prompt/context，创建或调用 HWLAB Code Agent session，把 isolated worktree、run-local HWPOD spec、任务目标和约束交给 Code Agent；agent 阶段结束或超时后，CaseRun 采集 agent trace/terminal state/commandExecution 摘要、subject worktree 的 `git status` / `git diff --stat` / `git diff --binary`，再按 case 定义执行 runner 后置 `hwpod-cli build` 和 `cmd.run` Keil 异步 job-status 查询，最后把 `evidence.json`、`summary.md`、`run.json`、`result.json`、`agent-prompt.md`、`agent-diff.patch`、run-local `.hwlab/hwpod-spec.yaml`、worker stdout/stderr 和 `artifact-manifest.json` 归档到 case registry repo 的 `runs/<caseId>/<runId>/`。下载不作为 compile-only CaseRun 的隐式步骤；后续需要下载时，应作为独立 action 显式加入 case 定义和流程记录。

长时间 CaseRun 必须优先使用 `case run start/status/result/logs` 短连接形态，而不是用 shell/nohup 包装同步 `case run`。`start` 只负责创建 `.state/hwlab-cli/caserun/<runId>/`、启动后台 worker 并立即返回 `runId`、PID、stdout/stderr 路径和下一条查询命令；`status`、`result`、`logs` 都是短查询。`run.json` 是阶段状态权威，阶段开始时就要刷新 `status`、`stage`、`traceId/sessionId/conversationId/threadId`、AgentRun/trace 轮询信息、stdout/stderr byte count 和下一条轮询命令；长等待期间不得出现无输出、无 trace、无状态文件更新的黑洞窗口。

当前标准 smoke case 是 `d601-f103-v2-compile`。它绑定已发现并预装的 `D601-F103-V2` HWPOD spec，目标是让 CaseRun 通过 Web 等价入口或 AgentRun runner 布置 Code Agent 舞台，再调用 `hwlab-cli case run d601-f103-v2-compile` 跑完整流程，而不是由操作员手工编译后代替运行。当前版本的结果只要求记录：subject provenance、agent prompt/session/trace/conversation/provider、subject worktree diff 文件、HWPOD build invocation、Keil job/status/artifact 字段、`compileOnly=true` 和 `downloadSkipped=true`；不得把这些 evidence 自动归纳为 Code Agent 通过/失败。

产物归属按两条线分开：

- case registry repo 的 `runs/<caseId>/<runId>/` 是 CaseRun 审计产物权威入口；`.state/hwlab-cli/caserun/<runId>/` 只保留短连接控制和轮询所需状态，不作为长期产物入口。registry run 目录必须包含 trace manifest，manifest 只记录文件哈希、agent trace/session、subject provenance、diff 和 Keil job 字段，不引入自动评价或门禁结论。
- HWLAB repo 的 harness、`hwpod-cli`、`hwpod-ctl`、`hwpod-compiler-cli` 或文档改进可以按风险进入 `v0.2` 分支；单纯文档和轻量 CLI/helper 变更可直接提交，业务代码、运行面或发布链路变更走 PR 工作流。

当前边界：CaseRun 仍是无服务化短连接 CLI 编排，不负责排队、并发、评分、自动合并、长期 run retention 或 epoch 汇总；这些能力属于后续强化学习 Harness 层。CaseRun 也不负责代替 HWLAB Code Agent 完成研发任务，后续 agent-task CaseRun 必须把 prompt/session/trace/diff/evidence 作为一等输出。AgentRun 私有 GitHub repo git transport 必须具备有界失败和可观测性后，才能把单次 CaseRun 扩展为批量 runner 或 epoch 系统。

## 验收标准

快速阶段最小验收：

1. Code Agent workspace 内存在 `.hwlab/hwpod-spec.yaml`，并能通过 `hwpod-ctl spec validate`。
2. `hwpod-compiler-cli compile` 能把同一个 spec 和高层 intent 编译为稳定 `hwpod-node-ops-v1` plan。
3. `hwpod-cli --dry-run` 输出的 plan 不需要云端 spec，也不读取其他本地旧 profile authority。
4. `hwlab-api` 的 node-ops 入口能接收 plan，返回 JSON result；无可用 node 时必须返回结构化 blocker，而不是静默伪造 DEV-LIVE。
5. 真实 CLI 验收必须证明 `hwpod-cli -> hwpod-compiler-cli -> hwlab-api /v1/hwpod-node-ops -> hwpod-node` 全链路走通。
6. CaseRun 流程必须能用 `hwlab-cli case run <caseId>` 从 case registry repo 读取 case 定义，按 `subject.repoLocalPath` 和 `subject.commitId` 创建隔离 subject worktree，生成 Code Agent prompt/context，记录 agent session/trace/conversation/provider，采集 subject worktree diff，执行 compile-only smoke，并产出 isolated run state 和 case registry repo 全量产物归档；当前版本只记录流程证据和 trace manifest，不设置通过条件、不自动评价 evidence，并明确记录 downloadSkipped。
7. 长任务验收必须覆盖 `hwlab-cli case run start <caseId>` 立即返回，以及 `status/result/logs <runId>` 在 worker 运行中能短查询到阶段、耗时、stdout/stderr byte count、trace/session/conversation/thread 信息和下一条轮询命令；不得把同步命令长时间无输出视为有效 CaseRun 操作体验。
8. `d601-f103-v2-compile` 的真实流程只覆盖当前编排链路和 compile-only smoke；操作员直接运行 `hwpod-cli build`、直接调用 Keil 或只检查 node 侧 job，不等同于 CaseRun 流程跑完。
9. agent-task CaseRun 的真实流程必须证明 `case run` 已创建或调用 Code Agent / AgentRun session，任务 prompt 已进入 agent 上下文，CaseRun 已采集隔离 subject worktree diff，并已继续执行编译、下载或 I/O smoke 等后续动作；当前版本只记录这些事实，不自动判断 agent 是否完成任务。