# Device Pod CLI MVP 计划

本文描述 `device-pod-cli` 第一阶段实现计划。长期设备模型以 [../reference/device-pod.md](../reference/device-pod.md) 为准；本文只约束如何开发、调试和验收 CLI MVP。

## 目标

`device-pod-cli` 是给 HWLAB code agent 使用的独立硬件能力 CLI，不并入 `hwlab-cli`，也不继承 `hwlab-cli` 的广泛管理权限。第一版目标是先不实现真正的 `device-pod-server`，而是把 `device-pod` 当作 profile 驱动的抽象能力单元，通过以下路径跑通最小真实闭环：

```text
code agent -> device-pod-cli -> hwlab cloud-api/gateway -> device-host-cli -> debug probe / serial / WiFi / vendor protocol -> target
```

gateway 保持单纯 cmd 转发；硬件协议、串口、下载器和厂商工具复杂度隔离在用户 PC 上的 `device-host-cli` 后面。`device-pod-cli` 只暴露 workspace、debug-probe、io-probe 的受控语义能力，不提供泛化远程 shell。

## Profile 来源

CLI 每次执行都从 HWLAB code agent workspace 的 `.device-pod/` 目录读取 profile。推荐文件名为 `.device-pod/<devicePodId>.json`；后续可以兼容 YAML，但 MVP 优先使用 JSON，方便 schema 校验和 trace 记录。

profile 是灵活 source-of-truth，不做中心注册。CLI 输出必须包含 `profilePath`、`profileHash`、`devicePodId` 和 `targetId`，便于确认每次操作实际使用的是哪个 profile。profile 中只允许描述 route、受控 workspace root、debug-probe 能力、io-probe 能力和 host CLI 能力；不得写入 Git key、云端 token、kubeconfig、数据库 URL 或长期 secret。

## 命令口径

统一 locator 语法为：

```text
device-pod-cli <devicePodId>:<surface>[:<resourcePath>] <operation> [args...]
```

MVP surface 固定为：

- `workspace`：源码、工程、构建产物和受控文件操作。
- `debug-probe`：下载、复位、探针状态和芯片 ID。
- `io-probe`：UART、GPIO、AI/AO/DI/DO、状态采样和日志读取。

workspace 操作采用 busybox 风格白名单，不提供 `cmd` 子命令。第一版建议只开放 `ls`、`cat`、`stat`、`rg`、`find`、`head`、`tail`、`wc`、`apply-patch`、`upload`、`download`、`build`、`clean` 和 `artifact list`。所有文件路径必须限制在 profile 声明的 workspace root 内。

示例：

```text
device-pod-cli device-pod-71-freq:workspace:/firmware ls
device-pod-cli device-pod-71-freq:workspace:/firmware/main.c cat --max-bytes 12000
device-pod-cli device-pod-71-freq:workspace:/firmware/main.c apply-patch < fix.patch
device-pod-cli device-pod-71-freq:workspace:/firmware build --profile debug
device-pod-cli device-pod-71-freq:debug-probe download --artifact build/app.hex --approved --reason "DEV smoke"
device-pod-cli device-pod-71-freq:debug-probe reset --approved --reason "DEV smoke"
device-pod-cli device-pod-71-freq:debug-probe chip-id
device-pod-cli device-pod-71-freq:io-probe:/uart/1 read --max-bytes 12000
device-pod-cli device-pod-71-freq:io-probe:/inner/gpio/pa1 read
```

`io-probe:/inner/...` 必须显式表示从 target 内部状态读取，例如寄存器、全局变量、debug memory 或固件导出的状态。默认 `io-probe:/gpio/pa1`、`io-probe:/uart/1` 等路径表示外部真实 I/O probe、仪器或另一个设备观测到的物理信号。验收证据中不得混淆 inner 和外部 I/O。

## 输出与权限

CLI 默认输出 JSON。成功和失败都必须包含 `devicePodId`、`targetId`、`surface`、`operation`、`traceId`、`operationId`、`profileHash`、`route`、`status`、`blocker`、`evidence` 和截断元数据。输出文本、串口日志和命令日志必须有 `maxBytes` 或分页边界。

下载、复位、写 I/O、修改 workspace 等动作属于 mutating operation，必须要求显式 approval 参数，并写入 reason。长耗时操作返回 `jobId`，CLI 轮询或拉取 job output，不让一次 HTTP/gateway 调用长期阻塞。

## 开发方式

1. 先实现 profile schema、loader、locator parser 和 JSON 输出合同，用 fake profile 在本地单元测试覆盖成功、缺 profile、坏 profile、路径越界和未知 surface。
2. 实现 workspace busybox 操作和 fake gateway adapter，先在不接硬件时证明路径裁剪、输出截断和错误结构稳定。
3. 实现 debug-probe 与 io-probe 的 adapter 接口，先用 fake `device-host-cli` 返回 chip ID、UART 样例和下载 job 状态。
4. 在 D518 Windows 上开发 `device-host-cli`，通过 `D518:win` 做真实 DAPLink、串口或下载器 smoke；D518 侧只承载硬件上位机逻辑，不改变 G14 source truth。
5. 在 G14 code agent pod 中开发和验证 `device-pod-cli`，code agent pod 不放完整 HWLAB 源码和 Git key；CLI 通过 skill 分发到预装位置，并在 skill 说明中写清仅适用于 HWLAB 内部 code agent。
6. fake 闭环通过后再做 G14 -> gateway -> D518 -> 硬件的最小 live smoke，然后把修复固化到源码、测试和长期参考。

## 调试方式

- `--dry-run` 只解析 profile、locator 和路由计划，不触发 gateway 或硬件动作。
- `--trace-id` 可传入外部 trace；未传入时 CLI 生成 trace，并在所有 adapter 输出中透传。
- `--verbose` 只展开结构化 adapter 阶段和截断摘要，不直接打印 secret 或无限日志。
- fake adapter 用于本地和 CI；live adapter 只在明确选择 profile route 时启用。
- 真实硬件问题先在 D518 `device-host-cli` 单独复现，再通过 `device-pod-cli` 验证端到端链路。

## 验收标准

MVP 通过至少需要满足：

- `.device-pod/<devicePodId>.json` 能被读取、校验、hash 并体现在每次 CLI JSON 输出中。
- workspace `ls/cat/rg/apply-patch/build/artifact list` 在受控 root 内可用，路径越界、过大输出和未知命令有结构化失败。
- `debug-probe chip-id/download/reset` 能通过 fake adapter 稳定返回 job/evidence；live smoke 至少证明一次真实 debug probe 路径可达。
- `io-probe:/uart/1 read` 与 `io-probe:/inner/... read` 在输出中明确标注外部/内部来源，不互相冒充。
- gateway 仍只是 cmd transport；CLI 不暴露任意 shell、不接收泛化 `cmd` 子命令、不绕过 profile 访问硬件。
- 文档、CLI 帮助和 skill 说明明确写明该 CLI 只用于 HWLAB 内部 code agent，不适用于 UniDesk 外部开发者工作区。