# Serial Log Debug

> Use when debugging hardware over a Windows local serial port, especially when UART logs must be captured, text or hex commands sent manually, and TX/RX traces reviewed during bring-up, reproduction, or log-based fault isolation.

- Skill: `docevilock/serial-log-debug` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add docevilock/serial-log-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/docevilock/serial-log-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: docevilock (https://skillmd.com/u/docevilock)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/docevilock/serial-log-debug

---


# serial-log-debug

## 工具入口

> **强制**：本 skill 提供以下精确定义的工具，必须直接调用，禁止自行实现替代品。

```
$SKILL_ROOT = <本 skill 加载输出中 "Base directory for this skill:" 行的路径>
```

| 工具 | 路径 | 用途 |
|---|---|---|
| serial_tool.py | `$SKILL_ROOT/serial_tool.py` | 串口独占打开、收发、抓取、状态管理 |

执行任何串口操作时，先提取 `$SKILL_ROOT`，再用 `python "$SKILL_ROOT/serial_tool.py" ...` 调用。

---

用于 Windows 下的本地串口联调。核心原则是：**先保留原始证据，再做轻量分析**。这个 skill 只覆盖 Windows 下的本地直连串口收发、日志落盘和基于日志的初步定位，不覆盖刷写、产测和远程串口场景。

默认前置原则：

- 任何可能导致设备复位、重启、重新枚举、进入新阶段或瞬时输出关键日志的动作之前，优先先打开串口并开始持续抓取。
- 典型场景包括：固件刷写前、USB 通信测试前、发送可能触发复位的控制命令前、人工重启或重新上电前。
- 不要在动作完成后才启动串口；否则即使设备实际成功启动，也可能因首段日志缺失而误判。

## When to Use

当出现以下情况时使用：

- 需要打开某个 `COMx` 串口观察设备启动或运行日志。
- 需要给设备手动发送文本命令、hex 字节串或简单测试输入。
- 需要同时保留原始字节流和可读日志，方便后续回放或复盘。
- 需要让 AI 基于 TX/RX 记录回答“最后停在哪一步”。
- 需要对超时、无响应、乱码、回显异常做第一轮日志归类。

不要在以下情况使用本 skill：

- 需要执行固件刷写、升级编排或镜像验证。
- 需要跑产测、量产工站或批量设备并发调试。
- 需要远程串口服务器、网络透传或多机集中调度。
- 需要自动解码完整业务协议、还原状态机或直接判定业务根因。

## Preconditions

使用前必须确认：

- 宿主机环境为 **Windows**。
- 设备通过 **本地直连串口** 接入。
- 目标串口必须能被当前工具 **独占打开**。
- 调试设备已上电，且具备输出日志或接收串口输入的条件。
- 串口驱动正常、日志输出目录可写。

TP807 HTTPS 联调已知约定：

- 串口参数使用 `115200 8N1`。
- **必须开启 `RTS/CTS` 硬件流控**；不要默认按“无流控”打开串口。
- 若 AI 工具未显式支持 `RTS/CTS`，应先补齐参数支持，再开始抓取。

如果任何一条不满足，先报告前置条件不成立，不要假装 skill 已具备对应能力。

## Quick Reference

## 工程位置

```text
<skill-root>/
```

## 快速使用

```bash
# 查看总帮助
python <serial_tool.py 路径> --help

# 检查串口是否可独占打开
python <serial_tool.py 路径> connect-test --port COM3 --baudrate 115200 --json

# 发送文本
python <serial_tool.py 路径> send-text --port COM3 --text reboot --line-ending crlf --json

# 发送 hex
python <serial_tool.py 路径> send-hex --port COM3 --hex "AA 55 01 02" --json

# 抓取 3 秒日志
python <serial_tool.py 路径> capture --port COM3 --duration 3 --output-dir serial_logs --json

# 打开后台串口会话，持续落盘
python <serial_tool.py 路径> open --port COM3 --output-dir serial_logs --json

# 打开后台串口会话，默认 5 分钟空闲自动关闭
python <serial_tool.py 路径> open --port COM3 --output-dir serial_logs --json

# 如需覆盖默认值，可显式指定空闲超时
python <serial_tool.py 路径> open --port COM3 --output-dir serial_logs --idle-timeout 600 --json

# 查看会话状态
python <serial_tool.py 路径> status --session-path serial_logs\\20260513_xxx\\session.json

# 查看最近日志
python <serial_tool.py 路径> peek --session-path serial_logs\\20260513_xxx\\session.json --lines 50

# 只读取新增日志，按游标推进
python <serial_tool.py 路径> read-new --session-path serial_logs\\20260513_xxx\\session.json --cursor-name ai

# 停止后台串口会话
python <serial_tool.py 路径> stop --session-path serial_logs\\20260513_xxx\\session.json

# TP807 HTTPS 联调：115200 8N1 + RTS/CTS
python <serial_tool.py 路径> open --port COM6 --baudrate 115200 --bytesize 8 --parity N --stopbits 1 --rtscts --output-dir serial_logs --json
```

说明：

- 示例中的 `<serial_tool.py 路径>` 是占位符，应该替换成当前运行环境解析到的实际脚本路径。
- 不要假设该 skill 固定安装在 `agents/skills/`、仓库根目录或某个用户目录下。

### 输入参数

优先使用以下参数口径：

- `--port`
- `--baudrate`
- `--timeout`
- `--parity`
- `--bytesize`
- `--stopbits`
- `--output-dir`
- `--json`

### 建议支持的动作

| 动作 | 目的 |
|---|---|
| `connect-test` | 验证目标串口是否能独占打开 |
| `send-text` | 发送文本命令，可选编码和行尾 |
| `send-hex` | 发送十六进制字节串 |
| `listen` | 持续监听串口输出 |
| `capture` | 按时长或字节数抓取一段日志 |
| `session` | 完成一次监听 → 发送 → 接收 → 落盘闭环 |
| `open` | 启动后台串口会话并持续落盘 |
| `status` | 查询后台串口会话状态 |
| `peek` | 读取最近日志片段，供 AI 判断是否继续 |
| `read-new` | 按游标读取新增日志，避免重复读历史内容 |
| `stop` | 停止后台串口会话 |

### 结果要求

每次执行都应尽量返回 machine-readable 结果，至少包含：

- `ok`
- `command`
- `port`
- `baudrate`
- `timeout`
- `log_path_raw`
- `log_path_text`
- `tx_bytes`
- `rx_bytes`
- `error_type`
- `error_message`

`error_type` 至少区分：`port_not_found`、`port_busy`、`invalid_param`、`read_timeout`、`write_failed`、`log_write_failed`。

## Operating Pattern

1. 先确认场景属于“Windows + 本地直连串口 + 独占访问”。
2. 明确串口参数，不自动猜测端口号、波特率或协议。
3. 任何会触发设备状态变化的外部动作之前，先建立连接或启动监听。
   - 包括但不限于：刷写、USB 测试、发送复位命令、人工重启或重新上电。
   - 目标是连续覆盖动作前、动作中、动作后的完整日志窗口，避免丢失首段证据。
   - 默认直接以目标波特率（例如 `115200`）打开串口；若现场存在异常，应按真实日志和错误类型继续排查，而不是在 skill 内隐式切换波特率重试。
   - 若仓库或现场已有明确串口约定，必须显式传入对应流控参数；对 TP807 HTTPS 联调，默认使用 `115200 8N1 + RTS/CTS`。
   - 若未显式提供 `--port`，可以先枚举本机可见串口，并优先尝试 USB 串口设备（例如 CH340）。
4. 推荐优先使用状态驱动模式：
   - `open`
   - `status`
   - `peek`
   - `read-new`
   - `stop`
5. 同时保留两类日志：
   - 原始日志：完整字节流
   - 可读日志：时间戳 + TX/RX + text/hex + 摘要
6. 分析时只基于实际日志片段做轻量归纳，不补全不存在的证据。

## Logging Rules

- 不因文本解码失败而丢弃原始字节。
- 不可打印字符优先转为 hex 展示。
- 摘要允许截断，但原始日志文件必须完整保留。
- 会话应有独立 ID、文件名和输出目录。
- 长时间监听应有显式停止方式，例如 `Ctrl+C`，必要时支持时长或字节上限。

## Analysis Boundaries

允许做的事：

- 标记 TX / RX。
- 总结最后一个可见状态。
- 抽取关键错误片段。
- 将异常初步归类为超时、无响应、乱码、参数错误、端口占用等。

不要做的事：

- 不把日志自动解释成完整业务协议语义。
- 不在证据不足时臆测设备内部状态。
- 不把串口观测结果直接升级成“根因已确定”。

## Common Mistakes

- 端口被其他串口助手占用却继续重试，导致误判设备无响应。
- 只保存文本日志，导致二进制数据丢失。
- 把乱码直接当协议异常，而不是先检查波特率或参数。
- 在没有证据时把“无回显”直接解释成死机。
- 把本 skill 与固件刷写 skill 混用，扩散了范围。

## Current Implementation

当前 skill 已包含 supporting CLI 和示例文件：

- `serial_tool.py`
- `examples/send_text.txt`
- `examples/sample_log.txt`
- `README.md`

这些名称表示当前 skill 目录内的实现文件；迁移到其他目录时，应按实际落点定位，不要写死父目录结构。

当前实现已经覆盖参数解析、统一 JSON 输出、错误分类、日志双文件落盘和最小子命令骨架。若宿主机未安装 `pyserial`，工具会返回结构化 `dependency_missing` 错误，而不是伪造串口执行结果。

当前实现还包含以下打开策略：

- 未传 `--port` 时，自动枚举当前可见串口，并优先选择 USB 串口设备。
- 实际打开串口时，直接按请求的目标波特率打开，并保留有限次重试。
- Windows 下 `PermissionError` / `access is denied` 会映射为 `port_busy`，避免误报成 `port_not_found`。
- `open` 会创建后台 worker 持续写入日志文件，并通过 `session.json` 暴露状态。
- `open` 默认启用 300 秒 idle 超时；若持续未收到新的 RX 数据，会自动关闭并写入关闭原因。
- AI 可在测试过程中的任意阶段反复执行 `status`、`peek`、`read-new`，不需要预先固定抓取窗口。