新增 Python 串口助手 serial_tool（常驻 daemon+全量日志文件即接口）取代 serial-mcp-server：@test 采集链改写 + 全库文档迁移
This commit is contained in:
+24
-24
@@ -6,21 +6,21 @@ agent: build
|
||||
Run the full automated test loop: **build → download → capture serial debug → verify markers → report/iterate**.
|
||||
|
||||
Prerequisites (checked in step 0):
|
||||
- `serial-mcp-server` CLI installed at `%LOCALAPPDATA%\serial-mcp-server\serial-mcp-server.exe` (Adancurusul/serial-mcp-server, v0.3.0).
|
||||
- Repo `.venv` exists with `pyserial` installed (rebuild per AGENTS.md "Python 环境" if missing).
|
||||
- ST-Link probe connected; target powered. The USB-serial (CH340) may stay idle while flashing — ST-Link download does not conflict with the serial port.
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0 — Pre-flight: serial-mcp-server binary + port
|
||||
### Step 0 — Pre-flight: serial assistant + port
|
||||
|
||||
Verify the capture binary and target port exist:
|
||||
Verify the serial assistant works and the target port exists:
|
||||
|
||||
```powershell
|
||||
Test-Path "$env:LOCALAPPDATA\serial-mcp-server\serial-mcp-server.exe"
|
||||
& "$env:LOCALAPPDATA\serial-mcp-server\serial-mcp-server.exe" list-ports --json
|
||||
& '.venv\Scripts\python.exe' 'tools/serial_tool/serial_tool.py' selftest # SELFTEST PASS
|
||||
& '.venv\Scripts\python.exe' 'tools/serial_tool/serial_tool.py' ports # JSON: 端口列表 + configured 标注
|
||||
```
|
||||
|
||||
Read `.opencode/serial_config.json` for the authoritative `portName` (COM6) and match it in the list. If the binary is missing, build it from source (see `docs/测试说明/serial-mcp-server_串口调试.md`).
|
||||
Read `.opencode/serial_config.json` for the authoritative `portName` (COM6) and confirm it appears in the `ports` output. If the port is missing, the CH340 driver or the cable is the problem — do not continue.
|
||||
|
||||
### Step 1 — Build verify
|
||||
|
||||
@@ -34,41 +34,41 @@ Interpretation (per AGENTS.md): exit code 0 = PASS (0 errors, 0 warnings). 1/2+
|
||||
|
||||
### Step 2 — Flash + capture boot log (one orchestrated call)
|
||||
|
||||
Use `test/run_boot_test.ps1` which starts the capture (waits for first byte),
|
||||
then flashes, then collects and verifies — all in one call so the capture never
|
||||
times out before flashing:
|
||||
Use `test/run_boot_test.ps1` which opens the port + clears the log (arming),
|
||||
flashes, waits for RX silence, extracts the boot log and verifies — all in one
|
||||
call. The serial daemon buffers the full stream in `tools/serial_tool/state/serial.log`,
|
||||
so nothing can be lost between steps:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File "test\run_boot_test.ps1" `
|
||||
-Port COM6 -BaudRate 115200 `
|
||||
-DurationMs 30000 -InitialTimeoutMs 90000 -IdleTimeoutMs 8000 -MaxBytes 65536 `
|
||||
-SettleMs 8000 -MaxWaitMs 30000 `
|
||||
-FlashCmd "MDK-ARM\download.bat" `
|
||||
-Required "App init OK;Network Init;net init: OK" `
|
||||
-Forbidden "FAIL;ERROR;HardFault" `
|
||||
-OutDir "C:\Users\16241\AppData\Local\Temp\opencode"
|
||||
-Forbidden "FAIL;ERROR;HardFault"
|
||||
```
|
||||
|
||||
Exit codes: **0 = PASS**, 1 = FAIL (marker miss / forbidden hit), 2 = capture/flash/parse error.
|
||||
`-Port` defaults to `.opencode/serial_config.json`; override only if needed.
|
||||
Exit codes: **0 = PASS**, 1 = FAIL (marker miss / forbidden hit), 2 = capture/flash error, 3 = preflight/usage error.
|
||||
|
||||
### Step 3 — Iterate
|
||||
|
||||
- **PASS** → report the verdict and which markers matched; done.
|
||||
- **FAIL** → the `[MISS]`/`[HIT]` lines + the log tail show what went wrong. Fix the code, then loop again from **Step 1**. Do not skip the build step.
|
||||
|
||||
## Alternative: manual MCP capture (interactive debug)
|
||||
## Alternative: interactive serial debug
|
||||
|
||||
For interactive command/response (not boot-log capture):
|
||||
For interactive command/response (not boot-log capture), drive the serial assistant directly:
|
||||
|
||||
1. `serial_list_ports` → match `portName` from `.opencode/serial_config.json` (COM6).
|
||||
2. `serial_open` (port=COM6, baud_rate=115200) → note the returned `connection_id`.
|
||||
3. `serial_write` / `serial_read` (connection_id, timeout_ms) for command-response.
|
||||
4. `serial_close` to release the port.
|
||||
1. `ports` → confirm the target port.
|
||||
2. `open --port COM6 --baud 115200` (idempotent; auto-starts the daemon).
|
||||
3. `send "text"` / `send --hex 0D0A` to transmit; `log --tail 20` (or Read the log file directly) to see RX history.
|
||||
4. `close` when done (the daemon itself keeps running; `stop` only if the port must be freed for another tool).
|
||||
|
||||
## Notes
|
||||
|
||||
- **串口端口**：以 `.opencode/serial_config.json` 为准（本机为 COM6）。每次连接前先读它。
|
||||
- **⚠️ 无历史缓冲**：serial-mcp-server 的 `read` 只能读调用后的字节。抓开机日志必须走 `run_boot_test.ps1`（先采集等 first-byte → 再烧录触发）。
|
||||
- **⚠️ EOF 陷阱**：COM 刚释放立即重开会报 `UnexpectedEof`（tokio-serial 读 0 字节）。`serial_capture.ps1` 内置自动重试；别裸跑 CLI capture。
|
||||
- **参数**：`IdleTimeoutMs` 需 ≥ boot 自然静默间隙（本机 ~3-4s，用 8000）；`InitialTimeoutMs` 需覆盖编译+烧录耗时（用 90000）。
|
||||
- **全量历史 = 日志文件**：daemon 把 RX/TX/SYS 持续写入 `tools/serial_tool/state/serial.log`，直接 Read/Grep 即可，无需采集窗口仪式。
|
||||
- **⚠️ 静默判据**：boot 任务间有 ~3-4s 自然静默间隙，`-SettleMs` 必须 ≥ 8000（默认已如此），否则日志截断。
|
||||
- **daemon 生命周期**：任何命令自动拉起 daemon（无需显式 start）；`restart` 保证加载最新代码；强杀 daemon 后下条命令自动恢复（串口需重新 `open`）。
|
||||
- UI (LVGL) task `ui_task` 已有 `UI port init: OK` / `UI menu init: OK` 打印，可用 `-Required "UI port init: OK;UI menu init: OK"` 自动回归 UI 初始化。
|
||||
- Full capture/analysis details: `docs/测试说明/serial-mcp-server_串口调试.md` and `docs/测试说明/自动化测试流程.md`.
|
||||
- Full command contract / daemon behavior / known traps: `docs/测试说明/串口助手设计说明.md` and `docs/测试说明/自动化测试流程.md`.
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
"portName": "COM6",
|
||||
"portHint": "USB 串行设备",
|
||||
"baudRate": 115200,
|
||||
"note": "MCU 调试串口（USART1 → CH340 → 本机枚举为 COM6）。执行 @test 前先读取本文件，再用 serial_list_ports 匹配 portName 选择端口；如本机端口变化，请人工修改此文件。"
|
||||
"note": "MCU 调试串口（USART1 → CH340 → 本机枚举为 COM6）。Python 串口助手（tools/serial_tool）与 @test 均以此文件为端口/波特率默认值（单一配置源）；执行前先读取。如本机端口变化，请人工修改此文件。"
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user