feat: add hwpod harness node-ops loop

2026-06-05 11:47:00 +08:00
parent 45bd95e9d1
commit c8a8aa505e
13 changed files with 1795 additions and 3 deletions
@@ -1,10 +1,12 @@
-# Device Pod 正式接入规格
+# Device Pod 迁移对照规格

-本文是 HWLAB `v0.2` 正式接入 `device-pod` 的规格说明。`device-pod` 是一个逻辑设备能力单元，不是 Kubernetes Pod 名称，也不是 code agent 本地 profile 文件。正式接入后，profile 定义 `device-pod`，因此 profile 必须由管理员和服务端权威存储管理，不能由 code agent 本地文件决定路由或资源边界。
+本文保留 HWLAB `v0.2` 既有 `device-pod` 正式接入口径，作为 HWPOD Harness 迁移对照。新的 HWPOD 业务方向以 [spec-hwpod-harness.md](spec-hwpod-harness.md) 和 [pikasTech/HWLAB#897](https://github.com/pikasTech/HWLAB/issues/897) 为准：快速迭代阶段先把 `hwpod-spec`、`hwpod-cli`、`hwpod-ctl` 和 `hwpod-compiler-cli` 放在 Code Agent workspace 内，`hwlab-api` 只做 `hwpod-node-ops` 转发，`hwpod-node` 只维护少量稳定 ops。
+
+旧 `device-pod` 是一个逻辑设备能力单元，不是 Kubernetes Pod 名称，也不是 HWPOD 目标状态下的产品主概念。旧 profile/server authority 路径仍可用于现有 v0.2 兼容和迁移对照，但新增业务翻译应优先进入 `hwpod-compiler-cli`，不要继续堆在 `hwlab-device-pod` executor 或 `device-host-cli.mjs` 中。

 实施跟踪见 [pikasTech/HWLAB#533](https://github.com/pikasTech/HWLAB/issues/533)，原 `docs/plan/v02-device-pod-spec-migration.md` 和旧 device-pod MVP 计划全文已迁入该 issue 评论。

-旧的 `device-pod-cli` 本地 profile 闭环只用于 CLI MVP 和真实硬件最小验证。进入正式多用户系统后，所有用户态设备访问必须收敛到：
+旧的 `device-pod-cli` 本地 profile 闭环只用于 CLI MVP 和真实硬件最小验证。既有正式多用户 device-pod 路径曾收敛到：

 ```text
 browser Cloud Web UI or hwpod/device-pod-cli
@@ -0,0 +1,198 @@
+# HWPOD Harness 规格
+
+本文是 HWLAB `v0.2` 向 HWPOD Harness 迁移的长期规格。概念体系和实施 issue 见 [pikasTech/HWLAB#897](https://github.com/pikasTech/HWLAB/issues/897)。旧 Device Pod 规格和实现仍作为迁移对照保留在 [spec-device-pod.md](spec-device-pod.md)，但新的业务方向以本文为准。
+
+当前阶段只设计核心业务闭环，不把鉴权、安全、并发、计量、复杂调度或完整 Evidence 体系作为前置条件。目标是让 Code Agent 在自己的 workspace 内先获得可观察、可修改、可快速改进的 HWPOD harness 闭环，再逐步把稳定部分平台化。
+
+## 分阶段口径
+
+### 快速迭代阶段
+
+快速迭代阶段先把 harness 的业务翻译权放在 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 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 保持轻量：
+
+```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
+  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 形态：
+
+```json
+{
+  "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 的结果第一版保持简单：
+
+```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 链路。
+
+## 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，不做业务翻译 |
+
+## 验收标准
+
+快速阶段最小验收：
+
+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，也不读取旧 `.device-pod/*.json` profile authority。
+4. `hwlab-api` 的 node-ops 入口能接收 plan，返回 JSON result；无可用 node 时必须返回结构化 blocker，而不是静默伪造 DEV-LIVE。
+5. 旧 Device Pod 路径仍可作为迁移对照，但新增业务翻译应优先进入 `hwpod-compiler-cli`，不要继续堆在 `hwlab-device-pod` executor 或 `device-host-cli.mjs` 中。