串口/COM/UART 调试时用统一脚本完成扫描、监控…

当需要扫描串口、实时监控 MCU/AT 输出、发送文本或 Hex 数据、记录日志，或让 minicom 与脚本共用同一串口时使用。

适用场景

解决思路

1. 在有工作区时，将工程级串口配置写入 `.embeddedskills/config.json` 的 `serial` 段，可设置 `port`、`baudrate`、`bytesize`、`parity`、`stopbits`、`encoding`、`timeout_sec`、`log_dir`，默认值分别为空字符串、`115200`、`8`、`none`、`1`、`utf-8`、`1.0`、`.embeddedskills/logs/serial`。
2. 环境级配置 `skill/config.json` 保持为空对象 `{}`，串口参数统一放在工作区的 `.embeddedskills/config.json` 中管理。
3. 解析串口参数时按优先级：CLI 参数（`--port`、`--baudrate` 等）> 工程级配置 `.embeddedskills/config.json` 的 `serial` 部分 > 状态文件 `.embeddedskills/state.json` 中的历史记录 > 默认值。
4. 执行前检查 `pyserial` 是否可用；未安装时提示 `pip install pyserial`。
5. 无子命令时默认执行 `scan`。
6. `monitor`、`send`、`hex`、`log` 使用解析后的连接参数。
7. 未指定 `port` 时自动扫描系统串口：若只找到一个串口，自动使用该端口并写入工程配置；若找到多个串口，返回候选列表让用户通过 `--port` 指定；若未找到串口，提示错误。
8. 成功执行后，将确认的参数写回工程配置 `.embeddedskills/config.json`。
9. 运行对应脚本并输出结构化结果。
10. 失败时优先反馈端口占用、驱动、波特率和编码问题。
11. 用 `scan` 扫描可用串口：`python scripts/serial_scan.py [--filter <关键词>] [--json]`。
12. 用 `monitor` 实时查看文本输出：`python scripts/serial_monitor.py [--port <串口>] [--baudrate <波特率>] [--timestamp] [--filter <regex>] [--timeout <秒>] [--json]`。
13. 用 `send` 发送文本或 Hex 数据：`python scripts/serial_send.py [--port <串口>] [--baudrate <波特率>] <data> [--hex] [--crlf] [--repeat <次>] [--wait-response] [--json]`。
14. 用 `hex` 实时查看二进制流：`python scripts/serial_hex.py [--port <串口>] [--baudrate <波特率>] [--width <列>] [--timeout <秒>] [--json]`。
15. 用 `log` 保存串口日志到文件：`python scripts/serial_log.py [--port <串口>] [--baudrate <波特率>] [--output <文件>] [--duration <秒>] [--format text|csv|json] [--json]`。
16. 单次命令返回标准 JSON，包含 `status`、`action`、`summary`、`details` 字段。
17. 持续命令 `monitor --json`、`hex --json` 输出 JSON Lines，结束摘要写入 stderr。
18. 错误输出 JSON，包含 `status`、`action`、`error`，`error` 内有 `code` 和 `message`。
19. 当需要同时使用 minicom（或其他串口工具）和 skill 脚本访问同一个串口设备时，通过 mux 后台服务实现多路复用。
20. 安装 mux 依赖 `socat`：`apt install socat` / `pacman -S socat`。
21. 按 mux 架构操作：Python mux 进程独占打开真实串口并暴露 TCP server，把串口 RX 广播给所有客户端；socat 作为 TCP 客户端创建虚拟 PTY `/tmp/serial_mux_vserial` 供 minicom 使用；skill 脚本自动检测 mux 状态，仅当本次串口配置与 mux 匹配时通过 `socket://` 连接 TCP 端口；任一客户端 TX 转发到真实串口。
22. 启动多路复用：`python scripts/serial_mux.py start --port /dev/ttyUSB0 [--baudrate 115200]`。
23. 查询多路复用状态：`python scripts/serial_mux.py status`。
24. 停止多路复用：`python scripts/serial_mux.py stop`。
25. 启动 mux 后，`monitor`、`hex`、`log`、`send` 脚本自动通过多路复用连接，无需额外参数；若命令显式指定了不同串口或串口参数，则不会复用当前 mux。
26. Mux 使用流程：先 `python scripts/serial_mux.py start --port /dev/ttyUSB0`；再 `minicom -D /tmp/serial_mux_vserial`；再 `python scripts/serial_monitor.py`；两个终端可同时看到串口数据；最后 `python scripts/serial_mux.py stop` 停止复用（终止 socat 进程并清理 `/tmp/serial_mux_vserial` 符号链接）。
27. 写入冲突处理：多客户端同时写入会导致串口数据错乱；监控/hex/log 脚本通过 mux 连接时输出警告到 stderr，send 脚本输出更强的冲突警告；如需直连真实串口（跳过 mux），使用 `--direct` 参数。
28. Mux 状态持久化：mux 进程 PID 保存到 `.embeddedskills/state.json` 的 `serial_mux` 段；脚本退出后下次调用 `status` 会检测进程是否仍存活并自动清理僵尸 PID；`start` 成功后把已确认的串口配置写回 `.embeddedskills/config.json`；`stop` 终止 mux 与 socat PTY 进程，并删除残留的 `/tmp/serial_mux_vserial` 符号链接。
29. 核心规则：不自动猜测波特率；发现多个候选串口时不自动选择端口。
30. 核心规则：参数解析优先级为 CLI > 工程级配置 > 状态文件 > 默认值。
31. 核心规则：未指定 `port` 时自动扫描，唯一候选自动写入配置，多候选需用户选择。
32. 核心规则：成功执行后，确认的参数自动写回 `.embeddedskills/config.json`。
33. 核心规则：未明确说明用途时不主动发送任何串口数据。
34. 核心规则：`--json` 输出的持续流使用 JSON Lines，摘要写 stderr，不污染数据流。
35. 核心规则：正则过滤失败不应导致监控退出。
36. 核心规则：Mux 运行中发送数据前提示用户避免同时写入。
37. 参考 `references/common_devices.json`：常见 USB 转串口芯片 VID/PID 映射。

适用边界 · 注意事项

• 没有真实串口设备、未安装 `pyserial`，或未确认端口/波特率时，不要直接执行监控、发送、Hex、日志等连接类操作。
• 未明确调试目的或协议时，不要主动发送串口数据；多客户端同时写入同一串口会导致数据错乱，应避免或改用 mux 并提示冲突。
• 不要自动猜测波特率；发现多个候选串口时不要自动选择端口，应让用户指定。