# tools/serial_tool/ — Python 串口助手

> **常驻 daemon + CLI** 架构的串口工具：后台持续收串口日志，CLI 按需查询/发送，
> 避免反复开关串口导致日志丢失（台架与测试的主力观测工具）。

## 文件一览

| 文件/目录 | 作用 |
|---|---|
| `serial_tool.py` | 串口助手主程序（daemon 与 CLI 合一） |
| `state/` | **运行时状态目录** |
| `state/serial.log` | 串口原始日志（`stack_report.py -s` 的输入之一） |
| `state/daemon.log` | daemon 自身运行日志 |
| `state/meta.json` | daemon 元数据（端口、状态等） |

## 使用方式

```bash
# 打开串口（daemon 自动拉起；端口缺省取 .opencode/serial_config.json，不必带参数）
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py open

# 看有哪些口 / 配置口是否还在位（单一候选时回 hint）
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py ports

# 读日志（先过滤后截尾）/ 发送 / 等静默
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py log --tail 50 --grep "App init OK"
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py send "<命令>"
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py wait-idle --settle-ms 8000 --max-ms 30000

# 状态 / 关闭
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py status
& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py close
```

> 全部命令输出 JSON、退出码 0/1/2/3；具体子命令以 `--help` 为准。
> 抓开机日志的顺序是 `open` → `clear` → 烧录/复位 → `wait-idle` → 读日志（采集必须先于烧录）。

## ⚠️ 注意

- **单写者**：串口同一时刻只能被一个进程占用——别同时用本工具和其它串口程序
- `state/serial.log` 是 `[STACK]` 运行时水位的来源，`scripts/stack_report.py -s` 直接读它
- `state/` 是运行时数据，**不入库**

## 相关文档

- `docs/测试说明/串口助手使用指南.md` — 命令用法 / 工作流 / 排障
- `docs/测试说明/串口助手设计说明.md` — 契约 / daemon 行为 / 陷阱