zserial

面向 AI coding 工具的命令行串口工具。统一提供串口枚举、发送、接收、日志读取能力，并为 Claude Code、Cursor、Codex 提供各自可用的接入文件。

安装

pip install -e .

依赖：Python >= 3.7，pyserial >= 3.5

集成方式

这个项目不是“一份跨平台通用 skill 文件”。

• Claude Code 使用 skill 目录：.claude/skills/zserial/SKILL.md
• Cursor 使用 rule 文件：.cursor/rules/zserial.mdc
• Codex 使用仓库级指令文件：AGENTS.md

三者最终调用的都是同一个命令：zserial

平台	接入文件	放置位置
Claude Code	.claude/skills/zserial/	目标工程 .claude/skills/
Cursor	.cursor/rules/zserial.mdc	目标工程 .cursor/rules/
Codex	AGENTS.md	目标工程根目录

一行复制：

mkdir -p .claude/skills .cursor/rules && cp -R zserial源码目录/.claude/skills/zserial .claude/skills/ && cp zserial源码目录/.cursor/rules/zserial.mdc .cursor/rules/ && cp zserial源码目录/AGENTS.md .

用法

装好后，可以直接让 AI 调用：

查看有哪些串口
通过 COM3 发送 AT+RST，波特率 115200
读取 COM3 串口日志，等 5 秒
发 AT+VERSION 到 COM3，收到 OK 就停

也可以自己直接执行命令。

命令参考

zserial list
zserial list --json
zserial send -p COM3 -b 115200 "AT+RST"
zserial send -p COM3 -b 115200 --hex "FF 01 A3"
zserial recv -p COM3 -b 115200 --timeout 2
zserial recv -p COM3 -b 115200 --until "OK"
zserial recv -p COM3 -b 115200 --idle-timeout 0.5
zserial recv -p COM3 -b 115200 --max-bytes 1024
zserial sendrecv -p COM3 -b 115200 "AT+VERSION"
zserial sendrecv -p COM3 -b 115200 "AT+RST" --until "OK" --idle-timeout 0.5
zserial log -p COM3 -b 115200 --duration 10
zserial log -p COM3 -b 115200 --lines 100
zserial log -p COM3 -b 115200 --bytes 4096
zserial log -p COM3 -b 115200 --duration 5 --output serial.log

串口参数

参数	默认值	说明
-p, --port	必填	串口设备（Linux: /dev/ttyUSB0，Windows: COM3）
-b, --baudrate	115200	波特率（300 ~ 921600）
--bytesize	8	数据位（5/6/7/8）
--parity	N	校验（N/E/O）
--stopbits	1	停止位（1/1.5/2）
--flow	none	流控（none/xonxoff/rtscts）
--timeout	1	总超时（秒）
--hex	关	HEX 模式
--json	关	JSON 结构化输出
--config	无	JSON 配置文件路径
--encoding	utf-8	文本编解码
--errors	replace	编解码错误处理

接收终止条件

recv / sendrecv 支持：

• --idle-timeout <秒>：收到首包后，空闲超过此时间即停止
• --until <文本>：收到包含该文本的数据即停止
• --until-hex <HEX>：收到包含该 HEX 序列的数据即停止
• --max-bytes <字节数>：最多接收指定字节数

如果在超时窗口内完全没有收到数据，命令会以 TIMEOUT 退出。

日志读取

log 支持三种停止条件：

• --duration <秒>：读到指定时长停止
• --bytes <字节数>：最多输出指定字节数
• --lines <行数>：最多输出指定行数

使用 --output <文件> 时，结果会写入文件并保留该文件。

错误码

码	类型	含义
1	UNKNOWN	未知错误
2	PORT_NOT_FOUND	串口不存在
3	PORT_BUSY	串口被占用或权限不足
4	INVALID_PARAM	参数非法
5	TIMEOUT	超时无响应
6	HEX_ERROR	HEX 格式错误

JSON 模式下错误输出：

{"error": true, "error_type": "TIMEOUT", "message": "..."}

配置文件

{"port": "COM3", "baudrate": 115200}

使用：

zserial sendrecv --config serial.json "AT+RST"