HWPOD Harness 规格

本文是 HWLAB v0.2 向 HWPOD Harness 迁移的长期规格。概念体系和实施 issue 见 pikasTech/HWLAB#897。旧 Device Pod 规格和实现仍作为迁移对照保留在 spec-device-pod.md，但新的业务方向以本文为准。

当前阶段只设计核心业务闭环，不把鉴权、安全、并发、计量、复杂调度或完整 Evidence 体系作为前置条件。目标是让 Code Agent 在自己的 workspace 内先获得可观察、可修改、可快速改进的 HWPOD harness 闭环，再逐步把稳定部分平台化。

分阶段口径

快速迭代阶段

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

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 HTTP / injected handler

这一阶段的核心边界：

hwpod-spec 存放在 Code Agent workspace 内，是当前 hwpod 的本地声明式定义。
hwpod-cli 是用户和 Code Agent 执行研发动作的入口。
hwpod-ctl 是和 hwpod-cli 平级的管理入口，用于初始化、修改、检查 hwpod-spec，以及 smoke/node 状态类操作。
hwpod-compiler-cli 是本地编译器，把高层 intent 和 hwpod-spec 编译为 hwpod-node-ops。
hwlab-api 只接收 hwpod-node-ops plan，负责转发和返回结果，不承担业务翻译。初版通过 HWLAB_HWPOD_NODE_OPS_URL 转发到 node，或在测试/嵌入场景注入 node-ops handler。
hwpod-node 只维护少量稳定 op handler，不保存完整 hwpod-spec，也不解释高层 hwpod intent。初版 hwpod-node 可以作为本地 HTTP executor 运行，只保证基础 workspace/cmd ops，debug/io 需要后续绑定真实工具。

云端平台阶段

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

将 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 保持轻量：

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
  debugProbe:
    type: stlink
    adapter: 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 必须存在。

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 调试

标准 plan 形态：

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

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

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 可以把这些入口暴露为短命令：

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 链路。

v0.2 迁移映射

现有 v0.2 对象	HWPOD 迁移归属	迁移说明
`devicePodId` / server profile	workspace-local `hwpod-spec`	先把 profile 内容迁移成 `.hwlab/hwpod-spec.yaml`，后续再上云
`device-pod-cli` / 旧 `hwpod` alias	`hwpod-cli`	旧 selector/REST 入口作为迁移参考，新任务入口使用 HWPOD intent -> compiler -> node-ops
profile 管理脚本	`hwpod-ctl`	变成 workspace-local spec 管理和 smoke 工具
`hwlab-device-pod` executor 中的 intent -> host argv	`hwpod-compiler-cli`	高层业务翻译先下放到 workspace-local compiler-cli 快速迭代
`device-host-cli.mjs` 中的高层业务拼接	`hwpod-compiler-cli`	能上收的命令编排和 profile 解释上收到 compiler-cli
`device-host-cli.mjs` 中的基础执行能力	`hwpod-node`	稳定 op handler 留在 node 侧
`hwlab-gateway` / `devicepod-gateway`	`hwpod-node` 内部 transport/gateway	不再作为产品主概念
cloud-api device-pod job route	`hwlab-api` node-ops 转发面	快速阶段只做 plan submit/result，不做业务翻译

验收标准

快速阶段最小验收：

Code Agent workspace 内存在 .hwlab/hwpod-spec.yaml，并能通过 hwpod-ctl spec validate。
hwpod-compiler-cli compile 能把同一个 spec 和高层 intent 编译为稳定 hwpod-node-ops-v1 plan。
hwpod-cli --dry-run 输出的 plan 不需要云端 spec，也不读取旧 .device-pod/*.json profile authority。
hwlab-api 的 node-ops 入口能接收 plan，返回 JSON result；无可用 node 时必须返回结构化 blocker，而不是静默伪造 DEV-LIVE。
旧 Device Pod 路径仍可作为迁移对照，但新增业务翻译应优先进入 hwpod-compiler-cli，不要继续堆在 hwlab-device-pod executor 或 device-host-cli.mjs 中。

8.9 KiB Raw Blame History Unescape Escape