Device Pod CLI MVP 计划

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

目标

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

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 语法为：

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 子命令。已跑通的 CLI MVP 先开放 ls、cat、rg、apply-patch 和 build；stat、find、head、tail、wc、upload、download、clean 和 artifact list 作为后续扩展进入同一白名单模型。所有文件路径必须限制在 profile 声明的 workspace root 内。

示例：

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 调用长期阻塞。

开发方式

先实现 profile schema、loader、locator parser 和 JSON 输出合同，用 fake profile 在本地单元测试覆盖成功、缺 profile、坏 profile、路径越界和未知 surface。
实现 workspace busybox 操作和 fake gateway adapter，先在不接硬件时证明路径裁剪、输出截断和错误结构稳定。
实现 debug-probe 与 io-probe 的 adapter 接口，先用 fake device-host-cli 返回 chip ID、UART 样例和下载 job 状态。
在 D518 Windows 上开发自包含 device-host-cli，通过 D518:win 做真实 DAPLink、串口或下载器 smoke；Keil、串口监控、mklink 和文件编辑 skill 只能作为实现参考，不作为运行时依赖。D518 侧只承载硬件上位机逻辑，不改变 G14 source truth。
在 G14 code agent pod 中开发和验证 device-pod-cli，code agent pod 不放完整 HWLAB 源码和 Git key；CLI 通过 skill 分发到预装位置，并在 skill 说明中写清仅适用于 HWLAB 内部 code agent。
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 在受控 root 内可用，路径越界、过大输出和未知命令有结构化失败；artifact list 进入后续扩展。
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 外部开发者工作区。

6.4 KiB Raw Blame History Unescape Escape