# embed_zserial_cli

**Repository Path**: group_agent/embed_zserial_cli

## Basic Information

- **Project Name**: embed_zserial_cli
- **Description**: 面向 AI coding 工具的命令行串口工具。统一提供串口枚举、发送、接收、日志读取能力，并为 Claude Code、Cursor、Codex 提供各自可用的接入文件。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zserial

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

## 安装

```bash
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` | 目标工程根目录 |

一行复制：

```bash
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 调用：

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

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

## 命令参考

```bash
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 模式下错误输出：

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

## 配置文件

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

使用：

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