Files

T

Codex c97e21b734 docs: define device pod model

2026-05-27 16:26:37 +08:00

4.6 KiB

Raw Blame History

Device Pod 设备目标能力模型

本文是 HWLAB device-pod 的长期参考口径。device-pod 是一个以单副本 k8s Pod 运行的设备目标代理单元，用于把一个可开发、可下载、可复位、可观测 I/O 的设备目标封装成统一 REST/job API。对外稳定身份由 Service/Deployment 承载，不依赖实际 Pod name。

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

device-pod
= deviceTarget
+ debugInterface
+ projectWorkspace
+ ioInterface

四要素

`deviceTarget`

deviceTarget 是被测设备目标本身，可以是一个 MCU 最小系统板、完整业务板卡、仪器模块或其他可被 HWLAB 操作的目标对象。它必须有稳定的 targetId，用于锁、trace、evidence 和用户界面归因。

`debugInterface`

debugInterface 是设备的开发和调试接口，代表下载、烧录、复位、debug probe 状态等能力。典型物理实现包括 DAPLink、J-Link、ST-Link 或厂商下载器。

第一版路径固定为：

device-pod -> cloud-api -> gateway -> cmd -> skill/downloader -> debug probe -> target

debugInterface 只暴露设备语义能力，例如 debug.probe、debug.download、debug.reset。不得把它退化成任意 shell 执行入口。

`projectWorkspace`

projectWorkspace 是设备对应的源码、工程文件和编译工具链上下文，例如 Keil 工程、target 名称、构建脚本和 workspace root。它描述如何从源码生成可下载产物，也为 debug/download job 提供工程路径和工具链边界。

projectWorkspace 可以和 debugInterface 位于同一台用户 PC，也可以只通过 gateway 暴露受控 CLI。HWLAB 不直接读取 secret、kubeconfig、DB URL 或完整源码内容；探测必须有界。

`ioInterface`

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

MVP 推荐路径为：

device-pod -> cloud-api -> gateway -> cmd -> device-host-cli -> serial/WiFi/USB/vendor protocol -> target

这里 cmd 只作为启动受控 PC 侧 CLI 的 transport；串口、WiFi、厂商协议和硬件细节必须隔离在 device-host-cli 或等价上位机 CLI 后面。

接口拆分

debugInterface 和 ioInterface 必须在模型和 API 中拆开，即使它们由同一个物理探针提供。例如 DAPLink 可以同时提供 SWD/CMSIS-DAP 下载调试口和 UART 串口：

DAPLink physical probe
-> debugInterface: SWD/CMSIS-DAP
-> ioInterface: UART

拆分原因：

debug.download、debug.reset 是低频强副作用动作，通常需要 approval 和 target 互斥锁。
io.status.read、io.sample 是短读或短窗口采样，关注 freshness、采样窗口和输出有界性。
io.write 类能力属于硬件 I/O 控制，未来也需要 approval，但不能和下载/烧录混成同一类风险。
trace、audit、evidence 必须能区分 debug 路径和 io 路径。

MVP 不拆成两个 k8s Pod；同一个 device-pod 内保留两个一等接口，共享 deviceTarget、projectWorkspace、锁、job 和 evidence 归因。

最小 REST 口径

同步 API 只用于短状态和短探测：

GET /health
GET /v1/profile
GET /v1/status
GET /v1/capabilities
GET /v1/debug/status
GET /v1/io/status

异步 API 用于下载、复位、采样等动作；每个 HTTP 调用必须短，长耗时由 job 轮询表达：

POST /v1/debug/jobs
POST /v1/io/jobs
GET /v1/jobs/{jobId}
GET /v1/jobs/{jobId}/output
POST /v1/jobs/{jobId}/cancel

第一版可接受的 intent 示例：

debug.probe
debug.build
debug.download
debug.reset
io.status.read
io.sample
io.uart.fetch

所有响应必须保留 devicePodId、targetId、traceId、operationId、gatewaySessionId、interface、intent、route、status 和 blocker/evidence 字段。真实控制动作不得用 SOURCE、LOCAL、DRY-RUN 或前端状态冒充 DEV-LIVE。

最小系统示例

一个 STM32F103 最小系统加 DAPLink 可以完整构成一个 device-pod：

deviceTarget: STM32F103 最小系统
debugInterface: DAPLink SWD/CMSIS-DAP
projectWorkspace: STM32F103 源码、Keil 工程和编译工具链
ioInterface: DAPLink UART 串口

该模型后续可以扩展到更多 target 或更复杂 I/O probe，但每个 device-pod 仍只代表一个明确的设备目标能力单元。

4.6 KiB Raw Blame History Unescape Escape

Device Pod 设备目标能力模型

四要素

deviceTarget

debugInterface

projectWorkspace

ioInterface