Merge pull request #510 from pikasTech/codex/device-pod-reference-20260527

docs: clarify device-pod bench abstraction
2026-05-27 19:55:55 +08:00
parent 704e3104ad 3ffee1899d
commit 5b118052af
1 changed files with 17 additions and 2 deletions
@@ -1,6 +1,6 @@
 # Device Pod 设备目标能力模型

-本文是 HWLAB `device-pod` 的长期参考口径。`device-pod` 是一个以单副本 k8s Pod 运行的设备目标代理单元，用于把一个可开发、可下载、可复位、可观测 I/O 的设备目标封装成统一 REST/job API。对外稳定身份由 Service/Deployment 承载，不依赖实际 Pod name。
+本文是 HWLAB `device-pod` 的长期参考口径。`device-pod` 是一个逻辑实验台抽象，用于把一个可开发、可编译、可下载、可复位、可观测 I/O 的设备目标封装成统一能力单元。进入 server 阶段后，该能力单元可以由单副本 k8s Pod 承载，并对外提供统一 REST/job API；对外稳定身份由 Service/Deployment 承载，不依赖实际 Pod name。

 `device-pod` 不等同于裸物理设备，也不是泛化远程 shell。它是以下四个要素的运行时组合：

@@ -12,6 +12,19 @@ device-pod
 + ioInterface
 ```

+## 设计抽象
+
+`device-pod` 可以理解成云端可拥有和调度的一张嵌入式实验台。云端拥有的是 `device-pod` 这个逻辑能力单元，不是直接拥有某一块裸板、某一根探针或某一台用户 PC。只要 profile 能把 `deviceTarget`、`debugInterface`、`projectWorkspace` 和 `ioInterface` 四要素绑定清楚，code agent 就可以围绕同一个 `devicePodId` 完成源码修改、构建、下载、复位、状态读取和 I/O 观察，从而覆盖嵌入式开发的完整闭环。
+
+四要素的物理落点可以不同，也可以复用同一个硬件实体的不同能力：
+
+- `deviceTarget` 是被调试和被验证的目标设备。
+- `debugInterface` 提供下载、烧录、复位、debug probe 状态和芯片识别等调试能力。
+- `projectWorkspace` 承载源码、工程、Keil/GCC 等工具链和编译产物。
+- `ioInterface` 提供 AI、AO、DI、DO、UART、截图、日志和其他实时或近实时观测/控制能力。
+
+`device-pod` 因此是逻辑打包关系，而不是一对一物理设备关系。一个 DAPLink/MKLink 类探针可以同时拆出 `debugInterface` 的 SWD/CMSIS-DAP 能力和 `ioInterface` 的 UART 能力；同一个 `device-pod` 也可以把该探针与调试 box、USB 摄像头、串口工具或厂商上位机组合起来，共同形成对同一个 `deviceTarget` 的完整访问能力。
+
 ## 实施计划

 长期模型以本文为准；分阶段实现计划单独维护，避免把一次性开发步骤写进长期参考：
@@ -78,7 +91,7 @@ projectWorkspace.build

 ### `ioInterface`

-`ioInterface` 是设备的实时或近实时 I/O 观测与控制接口，代表 UART、AI、AO、DI、DO、状态采样、日志抓取等能力。典型实现包括 DAPLink 自带串口、独立串口工具、USB/WiFi/厂商协议上位机或 `device-host-cli`。
+`ioInterface` 是设备的实时或近实时 I/O 观测与控制接口，代表 UART、AI、AO、DI、DO、状态采样、日志抓取、截图等能力。典型实现包括 DAPLink/MKLink 自带串口、独立串口工具、调试 box、USB 摄像头、USB/WiFi/厂商协议上位机或 `device-host-cli`。

 MVP 推荐路径为：

@@ -160,4 +173,6 @@ projectWorkspace: STM32F103 源码、Keil 工程和编译工具链
 ioInterface: DAPLink UART 串口
 ```

+最小真实闭环也可以表述为：STM32F103 最小系统板作为 `deviceTarget`，一只 MKLink/DAPLink 类探针同时提供 `debugInterface` 和第一版 `ioInterface`，其中 debug 侧负责下载、复位和芯片识别，I/O 侧先只开放 UART；`projectWorkspace` 映射到用户 PC 上的源码目录、Keil 工程和工具链，再通过 gateway/device-host-cli 暴露受控构建和 artifact 能力。这样四要素齐备后，云端 code agent 就能围绕同一个 `device-pod` 完成改源码、编译、下载、复位、读串口的最小嵌入式开发闭环。
+
 该模型后续可以扩展到更多 target 或更复杂 I/O probe，但每个 `device-pod` 仍只代表一个明确的设备目标能力单元。