Serial 是一个嵌入式串口调试工具，用于扫描串口、实时监控、发送数据、记录日志和 Hex 查看。当用户提到串口、COM 口、UART、AT 命令调试、波特率、Hex 串流、串口抓日志、串口监控、查看 MCU 输出、二进制协议联调时自动触发，也兼容 /serial 显式调用。
用途
统一封装端口发现、实时监控、数据发送、日志记录和 Hex 查看能力，面向嵌入式开发中的串口调试场景。
配置
环境级配置（skill/config.json）目前为空对象 {}，因为串口参数属于工程级配置，统一在工作区的 .embeddedskills/config.json 中管理。
工程级配置（.embeddedskills/config.json）存放工程级串口配置，字段包括：port（串口号，如 COM3，默认 ""）、baudrate（波特率，默认 115200）、bytesize（数据位，默认 8）、parity（校验位：none/even/odd/mark/space，默认 none）、stopbits（停止位：1/1.5/2，默认 1）、encoding（文本编码，默认 utf-8）、timeout_sec（读写超时秒数，默认 1.0）、log_dir（日志输出目录，默认 .embeddedskills/logs/serial）。
参数解析优先级：CLI 参数（--port、--baudrate 等）最高，其次工程级配置，再次状态文件（.embeddedskills/state.json 中的历史记录），最后默认值。
自动扫描行为：未指定 port 时脚本自动扫描系统串口。若只找到一个串口，自动使用该端口并写入工程配置；若找到多个串口，返回候选列表让用户选择（通过 --port 指定）；若未找到串口，提示错误。
主要能力
子命令包括：scan（扫描可用串口，低风险）、monitor（实时查看文本输出，低风险）、send（发送文本或 Hex 数据，中风险）、hex（实时查看二进制流，低风险）、log（保存串口日志到文件，低风险）。
执行流程：检查 pyserial 是否可用，未安装时提示 pip install pyserial；按优先级解析参数；无子命令时默认执行 scan；monitor/send/hex/log 使用解析后的连接参数；未指定 port 时自动扫描；成功执行后将确认的参数写回工程配置；运行对应脚本并输出结构化结果；失败时优先反馈端口占用、驱动、波特率和编码问题。
使用方式
所有脚本位于 skill 目录的 scripts/ 下，通过 python 直接调用，脚本会按优先级从 CLI 参数、工程级配置、状态文件中读取参数。
扫描串口：python scripts/serial_scan.py [--filter <关键词>] [--json]
实时监控：python scripts/serial_monitor.py [--port <串口>] [--baudrate <波特率>] [--timestamp] [--filter <regex>] [--timeout <秒>] [--json]
发送数据：python scripts/serial_send.py [--port <串口>] [--baudrate <波特率>] <data> [--hex] [--crlf] [--repeat <次>] [--wait-response] [--json]
Hex 查看：python scripts/serial_hex.py [--port <串口>] [--baudrate <波特率>] [--width <列>] [--timeout <秒>] [--json]
日志记录：python scripts/serial_log.py [--port <串口>] [--baudrate <波特率>] [--output <文件>] [--duration <秒>] [--format text|csv|json] [--json]
输出格式：单次命令返回标准 JSON，包含 status、action、summary、details 字段。持续命令（monitor --json、hex --json）输出 JSON Lines，结束摘要写入 stderr。错误输出包含 status、action、error（code、message）。
串口多路复用（Mux）
当需要同时使用 minicom（或其他串口工具）和 skill 脚本访问同一个串口设备时，可以通过 mux 后台服务实现多路复用。依赖 socat（apt install socat / pacman -S socat）。
架构分三层：Layer 1 为 Python mux 进程独占打开真实串口，暴露 TCP server，并把串口 RX 广播给所有客户端；Layer 2 为 socat 作为 TCP 客户端创建虚拟 PTY /tmp/serial_mux_vserial，供 minicom 使用；Skill 脚本自动检测 mux 状态，仅当本次串口配置与 mux 匹配时通过 socket:// 连接 TCP 端口。数据流为串口 RX 广播到所有 TCP 客户端，任一客户端 TX 转发到真实串口。
Mux 管理命令：启动多路复用 python scripts/serial_mux.py start --port /dev/ttyUSB0 [--baudrate 115200]；查询状态 python scripts/serial_mux.py status；停止多路复用 python scripts/serial_mux.py stop。启动后，skill 脚本（monitor/hex/log/send）自动通过多路复用连接，无需额外参数。若命令显式指定了不同串口或串口参数，则不会复用当前 mux。
使用流程：先启动 mux，再用 minicom -D /tmp/serial_mux_vserial 进行用户侧交互，同时用 python scripts/serial_monitor.py 进行模型侧监控，两个终端同时看到串口数据，最后用 stop 停止复用（终止 socat 进程并清理 /tmp/serial_mux_vserial 符号链接）。
写入冲突警告：多客户端同时写入会导致串口数据错乱。监控/hex/log 脚本在通过 mux 连接时输出警告到 stderr，send 脚本输出更强的冲突警告。如需直连真实串口（跳过 mux），使用 --direct 参数。
Mux 状态持久化：mux 进程 PID 保存到 .embeddedskills/state.json 的 serial_mux 段。脚本退出后下次调用 status 会检测进程是否仍存活，自动清理僵尸 PID。start 成功后会把已确认的串口配置写回 .embeddedskills/config.json，方便后续无参命令复用。stop 命令会终止 mux 与 socat PTY 进程，并删除残留的 /tmp/serial_mux_vserial 符号链接。
核心规则
不自动猜测波特率；发现多个候选串口时不自动选择端口。参数解析优先级：CLI > 工程级配置 > 状态文件 > 默认值。未指定 port 时自动扫描，唯一候选自动写入配置，多候选需用户选择。成功执行后，确认的参数自动写回 .embeddedskills/config.json。未明确说明用途时不主动发送任何串口数据。--json 输出的持续流使用 JSON Lines，摘要写 stderr 不污染数据流。正则过滤失败不应导致监控退出。Mux 运行中发送数据前提示用户避免同时写入。
参考
references/common_devices.json：常见 USB 转串口芯片 VID/PID 映射。