# HWLAB Cloud SPEC / 云平台开发目标 20260601

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#644 迁移到 UniDesk 项目管理目录。 |

## 正文

## HWLAB Cloud SPEC / 云平台开发目标 20260601

## 背景

HWLAB 2026-05 已经在 16666/16667 live 上跑通用户工作台、Code Agent 真实对话和 M3 虚拟硬件可信闭环（`7f38d17` live，`DC-DCSN-P0-2026-003` MVP 纠偏口径已收敛），下一阶段要把云平台从"单用户本地验证"扩张到"多人多端云端开箱即用"。本 SPEC 集中登记 2026-06-01 起的 5 个云平台开发目标，作为 v0.2 之后的下一段路线，并在 HWLAB 长期总面板中取代旧的 MVP 单线叙述。

## 目标

### 1. 吸收本地嵌入式 AI Coding 的最佳实践

吸收本地嵌入式 AI Coding 的最佳实践，包括 SKILL/Pipeline/docs/TODO 管理等，做到云端开箱即用。做到用户免本地配置开箱即用。

### 2. 增强对 ARM2D 的开发能力

增强对 ARM2D 的开发能力，包括吸收已有的 SKILL。

### 3. 增强监管 AGENT

增强监管 AGENT，专门负责对抗监督，降低 AI 不按预定的技术路线写的问题，在 ARM2D 的移植任务上做优化和验证。

### 4. 提高云平台的云端协同能力

提高云平台的云端协同能力，支持多用户同时访问同一个 Code Agent。提供远程协作 AI Coding。

### 5. 提高对硬件的接入能力

提高对硬件的接入能力，包括：

- **定义可接入硬件设备的标准和接口**：即 HWPOD 设备应该具备哪些能力，提供哪些接口
- **接入调试盒子**：调试盒子先用开发板代替进行固件和云开发
- **接入接线盘**：接线盘暂时不接入，等接线盘硬件搭建后再接入

## 关联

- 承接：HWLAB 长期总看板当前阶段"Code Agent 真实可用 + M3 虚拟硬件可信闭环"已收敛
- 取代：DC-DCSN-P0-2026-003 在 v0.2 / 16666-16667 范围的"MVP 优先"口径（云端协同 / HWPOD / 监管 AGENT 部分超出口径时回到本 SPEC）
- 关联历史主题：
  - v0.2 Workbench 会话随用户账号持久化（多用户 / 跨设备恢复，目标 4）
  - Playwright/Chromium 运行环境与 Workbench browser smoke 防回归治理（云端开箱即用，关联目标 1）
  - PR 自动 CI / 自动 merge / deploy.json CD 分层（监管 AGENT 的工程护栏，关联目标 3）
  - v0.2 Device Pod 正式接入规格（被本 SPEC 目标 5 的"HWPOD 设备标准"包含并展开）

## 阶段（2026-06-01 起）

| 阶段 | 焦点 | 验收 |
| --- | --- | --- |
| Phase A 2026-06 | HWPOD 设备能力 / 接口标准 v1 起草 + 监管 AGENT 边界稿 | HWPOD v1 SPEC issue 发布；监管 AGENT 边界定义 v1 |
| Phase B 2026-07 | 调试盒子用开发板替代接入 v0 + 多用户同 Code Agent 最小可用 | 公开 demo 多人会话；HWPOD v1 在调试盒子上跑通最小 IO |
| Phase C 2026-08 | ARM2D 移植任务优化与监管 AGENT 闭环 + SKILL/Pipeline/docs/TODO 统一收口 | ARM2D 一次完整移植成功由监管 AGENT 留痕；本地 SKILL 全部上云 |

## 签发

- 签发日期：2026-06-01
- 签发人：staff
- 适用版本：HWLAB v0.2 之后
- 维护：HWLAB 长期总面板"下一阶段路线"段落

## 2026-06-05 设计补充：HWPOD Harness 单线程闭环与远景

### 当前定稿：先打通单线程 Harness 闭环

本阶段不先做批量训练、分级调度、虚拟/真实硬件分层治理或完整 eval registry。优先打通一个 profile、一类硬件执行节点、一次 Code Agent harness run、一组 evidence 的单线程闭环。

当前三层命名与职责定稿如下：

| 名称 | 职责 | 边界 |
| --- | --- | --- |
| `hwpod` | Code Agent / 用户运行时 Harness 入口，用于 workspace、patch、build、download、UART/JSON-RPC、evidence 和 closeout | 不管理 profile，不更新执行节点，不绕过工具协议直接做临时 shell/cmd 维护 |
| `hwpodctl` | 管理入口，用于 profile 管理、node 绑定、临时 cmd 透传维护、更新 `hwpod-node`、readiness/smoke 和 selector 生成 | 是管理员/平台侧能力，不作为 Code Agent 常规运行时入口 |
| `hwpod-node` | 靠近硬件的边缘执行节点，承接 build/download/uart/evidence 等真实动作 | 不等同于用户 PC host，也不是 USB/内核 driver；只执行受控命令并返回结构化 JSON |

`hwpod-node` 可以运行在用户 PC、实验室控制盒、AI 网关、调试器边缘设备或其他靠近硬件的计算端点上；因此不使用 `hwpod-host` 作为主名。`hwlab-gateway` / tunnel / outbound poll 连接属于 `hwpod-node` 的 transport 或连接组件，不作为用户侧主抽象。

与现有 v0.2 名称的映射：

- `device-pod-cli` / 当前 `hwpod` alias -> `hwpod`
- profile SOP、gateway 启动、host 文件同步、临时维护脚本 -> `hwpodctl`
- D601 Windows `device-host-cli.mjs` 及后续 AI 网关/调试器边缘执行器 -> `hwpod-node`
- `hwlab-device-pod` cloud service / executor -> 云端执行适配层，负责把 Cloud API 请求路由到对应 `hwpod-node`

### Kubernetes 语义对齐

本命名借用 Kubernetes 调度词汇，但不把 `hwpod` 等同于 Kubernetes Pod：

| Kubernetes | HWPOD Harness |
| --- | --- |
| `kubectl` | `hwpodctl` |
| Pod | `hwpod`，硬件研发执行上下文 |
| Node | `hwpod-node`，靠近硬件的执行节点 |
| kubelet | `hwpod-node` runtime/agent |
| manifest / CRD | profile / harness spec |
| Job | 一次 harness run |
| Namespace | project / tenant / lab lane |

`hwpod` 表示可被 Agent 或用户调用的硬件研发执行上下文，绑定 profile、workspace、toolchain、node capability 和 evidence 流。它可以由 Kubernetes Pod 承载，但产品语义不是 Kubernetes workload object。

### 单线程 MVP 验收闭环

第一版闭环建议固定为：

1. `hwpodctl apply -f <profile.yaml>`：注册或更新一个 HWPOD profile。
2. `hwpodctl get nodes` / `hwpodctl node status <node>`：确认 `hwpod-node` 在线、版本、能力和 gateway/transport 状态。
3. `hwpodctl update node <node>`：把节点执行器更新到期望版本，解决当前 v0.2 中 cloud rollout 成功但 D601 host-side CLI 未同步的断点。
4. `hwpodctl smoke <profile>`：用只读或 echo 级动作证明 cloud-api -> executor -> hwpod-node -> hardware-adjacent runtime 可达。
5. Code Agent 使用 `hwpod` 执行一次真实任务：workspace inspect / apply-patch / build / download / UART 或 JSON-RPC smoke。
6. `hwpod evidence` 或等价 closeout 输出 build log、download log、UART tail、node version、profile id、run id 和失败分类。

本阶段最重要的产品约束：

- `hwpod` 只做运行时 harness 操作，不做运维维护。
- `hwpodctl` 可以做临时 cmd 透传和节点更新，但必须留下版本、命令、smoke 和 evidence 记录。
- `hwpod-node` 只执行受控动作并输出结构化 JSON，不拥有云端用户、项目、Agent 策略或 CI/CD 决策。
- 云端 runtime version、profile version、`hwpod-node` version 和 smoke result 必须能被同一条状态命令看见，避免“云端成功、边缘执行器仍旧”的假绿。

### 远景：云 Harness 训练与用户开发平台

单线程闭环跑通后，HWPOD Harness 的远景不是单纯远程调试硬件，而是云端硬件研发训练与用户开发平台：

- 云端批量起 sandbox，对同一个硬件研发任务并行运行不同模型、prompt、tool schema 和 Agent 策略。
- 真实 `hwpod-node` / 设备池作为稀缺资源，由云端统一排队、锁定、审计和计量。
- 每次 run 留下统一 trace/evidence，包括代码 diff、build/download/UART、tool call、node/profile 版本和失败分类。
- 内部先用 HWLAB 自身 issue dogfood：每个修复任务都沉淀为 harness case，成功路径进入回归/eval，失败路径进入训练样本和产品缺口。
- 对外用户看到的是“导入项目 -> 选择 profile -> 运行 harness -> 查看成功率/失败原因/evidence -> 复用为 CI/HIL gate”的开发平台，而不是裸容器日志或远程 shell。

因此云端的核心价值不是替代本地调试手感，而是把硬件研发过程变成可重复、可审计、可训练、可协作、可计量的平台能力。本地 PC、AI 网关和调试器边缘设备都作为 `hwpod-node` 接入云端控制面；用户开发体验先由单线程闭环打磨，再演进到批量 harness 和训练平台。

## 2026-06-05 关联补充：HWPOD Harness 概念体系

- 专门概念体系历史主题：`HWPOD Harness 概念体系与 v0.2 架构映射`。
- 该历史主题将本阶段规格中的 HWPOD 方向从命名扩展为完整概念体系，详细定义 `hwpod`、`hwpodctl`、`hwpod-node`、Profile、Transport/Gateway、Harness Run、Evidence，以及它们和当前 v0.2 `device-pod-cli`、`cloud-api`、`hwlab-device-pod executor`、`hwlab-gateway`、`device-host-cli.mjs` 的对应关系。

## 2026-06-05 修订：HWPOD Harness 以最新四要素口径为准

- HWPOD Harness 概念体系已修订为核心业务概念体系：`hwpod` 是由 target device、workspace、debug probe、io probe 四个硬件研发要素组成的实体。
- Profile 只作为记录/声明这四个要素的配置方式，不作为独立平级概念，也不是 hwpod 的四要素之一。
- Code Agent / 用户运行时入口统一命名为 `hwpod-run`；管理入口统一命名为 `hwpod-ctl`；边缘执行节点统一命名为 `hwpod-node`。
- 本阶段规格上方 2026-06-05 设计补充中的早期 `hwpod`/`hwpodctl`/Evidence 摘要只保留为讨论历史，后续实现和文档以 HWPOD Harness 最新口径为准。

## 2026-06-05 修订：HWPOD Harness 快速迭代阶段以最新口径为准

- HWPOD Harness 概念体系已更新为当前快速迭代阶段的权威口径。
- 快速迭代阶段先做 Code Agent workspace 内可完整自用、可随时自改进的 harness：`hwpod-spec`、`hwpod-cli`、`hwpod-ctl`、`hwpod-compiler-cli` 都放在 Code Agent workspace 内，以 skill/CLI 形态迭代。
- `hwlab-api` 第一版只做 `hwpod-node-ops` 转发和结果返回，不承载 hwpod 业务翻译。
- `hwpod-node` 只维护少量稳定 ops；原 `devicepod-gateway` / `hwlab-gateway` 迁移为 `hwpod-node` 内部 transport/gateway；原 `device-host-cli.mjs` 中的业务翻译迁移到 `hwpod-compiler-cli`，基础执行能力迁移到 `hwpod-node`。
- 本阶段规格上方 2026-06-05 早期 `hwpod`/`hwpodctl`/`hwpod-run`/Profile/Evidence 摘要只保留为讨论历史，后续实现和文档以 HWPOD Harness 最新口径为准。
