Device Pod Server MVP 计划

本文描述 device-pod-cli 跑通后的第二阶段：实现真正的 device-pod-server。长期设备模型以 ../reference/device-pod.md 为准；本文只约束 server MVP 的开发、调试、目标和验收。

目标

device-pod-server 是一个与 device-pod 一一对应的服务实例，用来提供短同步 RESTful API、短异步 RESTful job API 和后台监控缓存。它解决 CLI 直连 profile/gateway 之后仍无法持续监控设备的问题。

MVP 对外目标是：

device-pod-cli 的稳定语义能力都能映射到 REST API。
server 后台维护 debug-probe 和 io-probe 的最新状态、freshness 和错误 blocker。
HWLAB cloud-api 代理 server API，前端只通过 cloud-api 查看设备状态，不直连 gateway 或用户 PC。
前端最小版本只显示 io-probe:/uart/1 的最新状态/日志尾部，以及 debug-probe 的 chip ID 和 probe 状态。

Profile 同步

server 阶段仍不引入中心 profile 注册表。HWLAB code agent workspace 的 .device-pod/ 目录继续作为 profile source-of-truth；device-pod-cli 或 code agent 每次连接 server 前读取 .device-pod/<devicePodId>.json，自动上传或刷新 profile。

server 只保存 active profile、profileHash、加载时间和校验结果，作为运行时缓存。profile 修改后不需要改 server 配置或重启服务；下一次 CLI/agent 同步即可更新 active profile。server 收到缺失、坏格式或能力不匹配的 profile 时返回 profile-missing、profile-invalid 或 capability-mismatch blocker，不回退到历史 profile 执行 mutating operation。

建议最小 profile API：

PUT /v1/profile
GET /v1/profile

CLI 可以提供调试入口：

device-pod-cli device-pod-71-freq:profile sync

profile 是 CLI/server 控制面同步动作，不属于 deviceTarget 四要素之一。

最小 REST API

同步 API 只返回短状态和缓存快照：

GET /health
GET /v1/status
GET /v1/capabilities
GET /v1/debug-probe/status
GET /v1/debug-probe/chip-id
GET /v1/io-probe/status
GET /v1/io-probe/uart/1
GET /v1/io-probe/uart/1/tail?maxBytes=12000

异步 API 用于下载、复位、workspace build、串口写入和采样窗口等动作：

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

cloud-api 代理最小口径：

GET /v1/device-pods
GET /v1/device-pods/{devicePodId}/status
GET /v1/device-pods/{devicePodId}/debug-probe/chip-id
GET /v1/device-pods/{devicePodId}/io-probe/uart/1
GET /v1/device-pods/{devicePodId}/io-probe/uart/1/tail?maxBytes=12000

所有响应必须包含 devicePodId、targetId、profileHash、traceId、operationId、status、freshness、blocker 和 evidence。server、cloud-api 和 frontend 不得把 fake、dry-run、SOURCE、LOCAL 或缓存过期状态标成 DEV-LIVE。

开发方式

从已跑通的 device-pod-cli profile schema、locator parser、operation adapter 和 JSON 输出合同中抽取共享模块，避免 CLI 与 server 两套语义分叉。
实现 server skeleton：health、profile sync、status、capabilities、job store、bounded output、lock 和 freshness 模型。
先接 fake device-host-cli adapter，稳定 chip ID、UART tail、job 状态和 blocker 行为。
再接 gateway/cmd/device-host-cli live adapter，保持 gateway 仍是 transport，不把 server 做成任意 shell 代理。
在 G14 DEV k3s 中部署单个 device-pod server 实例做 smoke，不改 PROD、不重启无关服务。
增加 cloud-api proxy 和前端最小展示，只显示 chip ID、probe 状态、UART1 最新片段和 freshness。

调试方式

GET /health 只验证进程、profile loader 和基础依赖，不触发硬件动作。
GET /v1/profile 展示脱敏后的 active profile 摘要、profileHash 和校验状态。
fake profile + fake host CLI 用于 server 单测和 G14 DEV 无硬件 smoke。
live 调试先看 server 结构化日志中的 profileHash、route、jobId、freshness 和 blocker，再到 D518 device-host-cli 单独复现硬件问题。
UART tail、job output 和日志都必须截断或分页；默认调试输出不能 dump 全量串口日志、源码或 secret。

验收标准

MVP 通过至少需要满足：

修改 .device-pod/<devicePodId>.json 后，无需重启 server，下一次 CLI/agent 同步即可看到新的 profileHash。
无 profile、坏 profile、过期 profile 和 capability mismatch 都有明确 blocker，不执行下载、复位或 I/O 写入。
GET /v1/debug-probe/chip-id 能通过 fake adapter 和至少一次 live smoke 返回 chip ID 或结构化硬件 blocker。
GET /v1/io-probe/uart/1 和 tail API 能显示 UART1 最新状态、freshness、截断信息和 evidence。
cloud-api 代理能返回同一组字段，前端最小页面能显示 chip ID、UART1 和 freshness，不直连 server/gateway。
mutating job 都是短 HTTP 创建、异步轮询、可取消、有 lock、有 approval reason。
server 与 CLI 的 operation 名称、错误码、profileHash 和 evidence 字段保持一致。

5.2 KiB Raw Blame History Unescape Escape