From c97e21b734968e2cbd7eb7734216e55bbb7c4b94 Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Wed, 27 May 2026 16:26:37 +0800
Subject: [PATCH] docs: define device pod model

---
 AGENTS.md                      |   1 +
 docs/reference/architecture.md |   5 ++
 docs/reference/device-pod.md   | 118 +++++++++++++++++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 docs/reference/device-pod.md

diff --git a/AGENTS.md b/AGENTS.md
index 0cd30fd4..a500df43 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -61,6 +61,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
 - Code Agent 对话就绪与真实回复判定：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
 - DEV runtime hotfix runbook 与只读审计：[docs/reference/dev-runtime-hotfix-runbook.md](docs/reference/dev-runtime-hotfix-runbook.md)
 - Gateway 主动出站 demo、poll/result 和本地 smoke：[docs/reference/gateway-outbound-demo.md](docs/reference/gateway-outbound-demo.md)
+- Device Pod 四要素、debug/io 接口拆分和最小 REST/job 口径：[docs/reference/device-pod.md](docs/reference/device-pod.md)
 - MVP E2E 验收测试与带编号测试报告 issue 规则：[docs/reference/MVP-e2e-acceptance.md](docs/reference/MVP-e2e-acceptance.md)
 - 指挥官协作、PR 和 runner 交接：[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
 - M3 闭环发布运行手册：[docs/reference/m3-loop-rollout-runbook.md](docs/reference/m3-loop-rollout-runbook.md)
diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md
index 1a2a5ffc..9a665682 100644
--- a/docs/reference/architecture.md
+++ b/docs/reference/architecture.md
@@ -35,6 +35,11 @@ For M3 hardware proof, the required runtime participants are:
 - two distinct `hwlab-gateway-simu` identities;
 - one `hwlab-patch-panel` that owns the route decision.
 
+真实设备目标以 `device-pod` 作为运行时能力单元。`device-pod`
+统一封装 `deviceTarget`、`debugInterface`、`projectWorkspace` 和
+`ioInterface` 四要素，并通过拆分的 debug/io 接口提供受控 REST/job
+能力；权威模型见 [device-pod.md](device-pod.md)。
+
 ## M3 Trusted Loop
 
 M3 DEV-LIVE requires this specific path:
diff --git a/docs/reference/device-pod.md b/docs/reference/device-pod.md
new file mode 100644
index 00000000..b13b27f6
--- /dev/null
+++ b/docs/reference/device-pod.md
@@ -0,0 +1,118 @@
+# Device Pod 设备目标能力模型
+
+本文是 HWLAB `device-pod` 的长期参考口径。`device-pod` 是一个以单副本 k8s Pod 运行的设备目标代理单元，用于把一个可开发、可下载、可复位、可观测 I/O 的设备目标封装成统一 REST/job API。对外稳定身份由 Service/Deployment 承载，不依赖实际 Pod name。
+
+`device-pod` 不等同于裸物理设备，也不是泛化远程 shell。它是以下四个要素的运行时组合：
+
+```text
+device-pod
+= deviceTarget
++ debugInterface
++ projectWorkspace
++ ioInterface
+```
+
+## 四要素
+
+### `deviceTarget`
+
+`deviceTarget` 是被测设备目标本身，可以是一个 MCU 最小系统板、完整业务板卡、仪器模块或其他可被 HWLAB 操作的目标对象。它必须有稳定的 `targetId`，用于锁、trace、evidence 和用户界面归因。
+
+### `debugInterface`
+
+`debugInterface` 是设备的开发和调试接口，代表下载、烧录、复位、debug probe 状态等能力。典型物理实现包括 DAPLink、J-Link、ST-Link 或厂商下载器。
+
+第一版路径固定为：
+
+```text
+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 推荐路径为：
+
+```text
+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 串口：
+
+```text
+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 只用于短状态和短探测：
+
+```text
+GET /health
+GET /v1/profile
+GET /v1/status
+GET /v1/capabilities
+GET /v1/debug/status
+GET /v1/io/status
+```
+
+异步 API 用于下载、复位、采样等动作；每个 HTTP 调用必须短，长耗时由 job 轮询表达：
+
+```text
+POST /v1/debug/jobs
+POST /v1/io/jobs
+GET /v1/jobs/{jobId}
+GET /v1/jobs/{jobId}/output
+POST /v1/jobs/{jobId}/cancel
+```
+
+第一版可接受的 intent 示例：
+
+```text
+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`：
+
+```text
+deviceTarget: STM32F103 最小系统
+debugInterface: DAPLink SWD/CMSIS-DAP
+projectWorkspace: STM32F103 源码、Keil 工程和编译工具链
+ioInterface: DAPLink UART 串口
+```
+
+该模型后续可以扩展到更多 target 或更复杂 I/O probe，但每个 `device-pod` 仍只代表一个明确的设备目标能力单元。