STM32F4-Base/.dsh/skills/serial-assistant/SKILL.md

name, description, whenToUse

name	description	whenToUse
serial-assistant	常驻串口助手（采集层）：daemon + 薄 CLI + 日志文件即接口。ports/open/send/log/clear/wait-idle/status 全套命令；RX/TX 全量历史落盘可直接 Read/Grep；一台机单 daemon 跨进程共享，自动拉起。serial-boot-test 等串口工作流的底座。	需要打开/关闭串口、发送命令或字节、查询串口历史日志、等 RX 静默（抓开机日志）、排查串口占用或端口参数问题时。

serial-assistant — 串口助手（项目级 skill，采集层）

单脚本 .dsh/skills/serial-assistant/scripts/serial_tool.py（Python + pyserial）。 架构：CLI（短命进程，硬超时）→ HTTP JSON → daemon（detached 单实例，127.0.0.1:18765）； daemon = 串口读线程（唯一 I/O 者）+ 日志写线程（唯一文件写者）。 历史 = scripts/state/serial.log（纯文本、只含完整行；绝对路径以 status 的 log.path 为准，直接 Read/Grep 即是历史，无采集窗口仪式）。

前置条件

解释器需装有 pyserial：优先项目自己的 venv；否则一次性建 skill 专用 venv：

python -m venv ".dsh\skills\serial-assistant\venv"
& ".dsh\skills\serial-assistant\venv\Scripts\python.exe" -m pip install pyserial

下文 $PY = 选定解释器，$TOOL = .dsh\skills\serial-assistant\scripts\serial_tool.py。 所有命令在项目根目录下运行（cwd 决定配置源解析）。

命令（全部 JSON 输出；退出码 0=成功 1=领域错误 2=daemon 不可达/超时 3=用法）

& $PY $TOOL ports                 # 枚举 COM 口 + configured 标注 + 唯一候选 hint
& $PY $TOOL open                  # 开串口（幂等；daemon 未跑自动拉起）；--port/--baud 可覆盖
& $PY $TOOL send "help"           # 发文本；send --hex 0D0A --nl 发字节并追加 CRLF
& $PY $TOOL log --tail 40         # 读日志；--grep P [-i] [--regex]（先过滤后截尾）
& $PY $TOOL clear                 # 清空日志（代际 +1，会话边界）
& $PY $TOOL wait-idle             # 等 RX 静默：--settle-ms 8000 --max-ms 30000 --first-timeout-ms 12000
& $PY $TOOL status                # 全状态 JSON（daemon 版本/端口/计数/rx_age_ms/log.path）
& $PY $TOOL start|stop|restart    # daemon 生命周期
& $PY $TOOL selftest              # 无头自检（行拆分/解码/截头/wait 判据，无需硬件）

抓开机日志铁律：open → clear → 烧录/复位 → wait-idle → 读日志校验标记 （采集必须先于烧录，否则错过开机头几行）。

配置源（串口参数单一配置源）

解析顺序：$DSH_SERIAL_CONFIG > <cwd>/.serialtest/config.json > <cwd>/.opencode/serial_config.json（旧位置）。用到的键：portName、baudRate、 httpPort（缺省 18765）。端口变化只改这个文件，改完必须 restart （daemon 启动时缓存配置）。

陷阱（实测教训）

• 一台机只有一个 daemon（HTTP 口 SO_EXCLUSIVEADDRUSE 独占绑定）。多个项目的 serial_tool 副本协议兼容、可互连：status 的 daemon.version 辨归属 （本 skill 版 = 1.1.0-skill），log.path 辨日志落点。
• open 报"拒绝访问/端口被占用"：先 status 查是不是残留旧 daemon 占着口 → stop（或 taskkill /F /PID）→ 重新 open。
• wait-idle 判据：no_data = 本次等待期间零字节；首字节到达前不启动静默计时； 返回的 rx_bytes 是本次增量。settle-ms 必须大于固件的自然静默间隙（常见 3~4s）。
• open 不带 --dtr/--rts = 保持当前线路状态；显式给才翻转。
• 日志 20MB 上限自动按行边界截头保尾 10MB；无换行残行 64KB 封顶。