62 lines
3.7 KiB
Markdown
62 lines
3.7 KiB
Markdown
---
|
||
name: serial-assistant
|
||
description: 常驻串口助手（采集层）：daemon + 薄 CLI + 日志文件即接口。ports/open/send/log/clear/wait-idle/status 全套命令；RX/TX 全量历史落盘可直接 Read/Grep；一台机单 daemon 跨进程共享，自动拉起。serial-boot-test 等串口工作流的底座。
|
||
whenToUse: 需要打开/关闭串口、发送命令或字节、查询串口历史日志、等 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：
|
||
|
||
```powershell
|
||
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=用法）
|
||
|
||
```powershell
|
||
& $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 封顶。
|