Embedded USB control plane

Embedded USB control plane 表示把 MCU 的 USB CDC / USB Serial-JTAG 当成本地设备控制面，而不是普通调试串口。它要求运行态控制协议、设备身份、日志/trace、secret 脱敏、串口 ownership，以及 flash/reset/monitor 等生命周期操作被同一个本地 owner 模型管理。这个 Topic 关注“USB 线接上以后 host 与设备如何安全协作”，包括 Web Serial 直连和本地 daemon 桥接；它不覆盖 USB 大吞吐数据传输、USB PD 协商本身，也不替代 MCU flashing integration 对 backend、chip、artifact 和 selector 配置的要求（projects/mains-aegis.md）。

它也不覆盖完整的设备级多入口控制面。若问题已经扩展到 ESP32-S3 的板载 USB 与 Wi‑Fi 如何一起承载 CLI、Web App、可选 desktop/local agent、Web Serial 与 native USB 的统一控制面 contract，应改看 Embedded device control plane；本 Topic 只负责其中“本地 USB 接入口”这一窄而关键的子问题（skills/style-playbook/references/topics/embedded-device-control-plane/TOPIC.md）。

当嵌入式设备需要通过 USB 提供本地维护、配网、日志、状态读取、受限设置、firmware identity 或 Web/CLI 控制入口时使用本 Topic。若项目只有一次性串口日志或 README 里的一条 flash 命令，应继续归入 MCU flashing integration、Embedded Rust 或项目快照，不要声称已经形成 USB control plane。若 USB 只是充电、DPDM 检测或 USB PD sink/source 角色，也不命中本 Topic；只有当 host 侧协议和设备生命周期 ownership 已经成为维护约束时才使用（mains-aegis:docs/usb-cdc-web-serial-protocol.md）。

如果审查重点已经变成 USB 与 Wi‑Fi / HTTP / SSE / GUI / desktop bridge 如何共同构成设备级控制面，则应优先命中 Embedded device control plane，不要把两层问题都塞回 USB Topic 里（skills/style-playbook/references/topics/embedded-device-control-plane/TOPIC.md）。

• CDC 上层协议默认结构化，优先使用 JSONL、request_id、response/error 和异步 status/log，避免裸文本命令与日志混流后无法归因（mains-aegis:docs/usb-cdc-web-serial-protocol.md）。
• hello 不只是连接探活，应返回 protocol、framing、capabilities、identity、firmware build/features 和 log decode 元数据；host 侧在能力判断和 artifact 解码前先检查这些身份信息（mains-aegis:firmware/README.md）。
• USB 写入面保持窄：配网、日志级别、低风险偏好和 identity/status 读取可以进入 CDC；输出启停、故障清除、强制充电等高风险动作不应混进本地便利通道（mains-aegis:docs/usb-cdc-web-serial-protocol.md）。
• Host 解析器默认 CDC 流不纯净，必须容忍 ROM log、plain serial、defmt、半截行和 malformed JSON；只有合法协议 frame 进入状态机，其余写入 raw/ignored trace（mains-aegis:web/src/serial/transport.ts）。
• 如果项目已经选择本地 daemon 作为 owner，应由它统一协调 scan/bind/connect、firmware artifact 选择与校验、flash/reset/monitor、CDC lease、日志/trace 缓存和 safe-control localhost API，避免 Web Serial、monitor 和烧录工具抢同一个 USB 资源；是否设为唯一 owner，仍应由更高一层的 Embedded device control plane 风险边界决定（mains-aegis:tools/mains-aegis-devd/src/main.rs、skills/style-playbook/references/topics/embedded-device-control-plane/TOPIC.md）。
• Secret 在 trace 入库前脱敏；WiFi PSK 可出现在 TX command，但不能出现在 response、error、structured log 或 developer trace 中（mains-aegis:web/src/serial/transport.ts）。

• projects/mains-aegis.md：设备 mono-repo 同时包含 ESP32-S3 firmware、Web 管理界面和本地设备控制面；项目内 docs/usb-cdc-web-serial-protocol.md 展示运行态 CDC JSONL、安全写入边界、devd safe-control API 与 trace 规则。
• mains-aegis:tools/mains-aegis-devd/src/main.rs：展示更贴近设备产品的 owner：设备扫描、绑定、连接、artifact 匹配、flash/reset/monitor、serial lease 和 CDC safe-control bridge 在同一进程内协调。
• skills/style-playbook/references/topics/embedded-device-control-plane/TOPIC.md：展示当 USB 本地入口只是更大设备控制面的一部分时，哪些边界应该留给上层 Topic，而不在这里混写。

把 CDC 当纯净 JSON 通道会在 ESP ROM 输出、plain serial 或 defmt 混入时断线；host 端必须降级为 raw/ignored trace，而不是把非协议行当 fatal。没有 request_id 会让命令响应、异步状态和日志无法配对。没有本地 owner 会让 Web Serial、devd monitor、flash/reset 工具互相抢口，错误表现成随机超时或端口占用。Web App 直接调用 flash 工具会绕过绑定、artifact 校验和 identity 匹配。只在 UI 层隐藏 secret 会让 trace、log 或 error 泄漏 PSK。最危险的是把 USB 的“本地便利”误解成无边界授权，把输出启停、故障清除等保护链动作塞进普通 CDC command（mains-aegis:docs/usb-cdc-web-serial-protocol.md）。

另一种常见误用是把整个设备级控制面都塞进 USB Topic，导致 Wi‑Fi、GUI/CLI 对等、desktop/local agent、PNA/CORS 或状态流回退等问题无处安放。修正方式是回到 Embedded device control plane，把 USB 仅保留为本地入口层（skills/style-playbook/references/topics/embedded-device-control-plane/TOPIC.md）。

• projects/mains-aegis.md
• mains-aegis:docs/usb-cdc-web-serial-protocol.md
• mains-aegis:firmware/README.md
• mains-aegis:firmware/src/usb_cdc_protocol.rs
• mains-aegis:firmware/src/main.rs
• mains-aegis:web/src/serial/transport.ts
• mains-aegis:tools/mains-aegis-devd/src/main.rs
• mains-aegis:docs/web-management-ui.md
• mains-aegis:docs/hardware-collaboration-workflow.md
• skills/style-playbook/references/topics/embedded-device-control-plane/TOPIC.md