serial

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared1 observation
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

return bytes.fromhex(clean)

Audit 0.4.1 · source sha 674ae8bca880 · 28 Oct 2026Report an issue or request a re-scan

• Publisherzhinkgit GitHub userOwner of the repository this skill is read from
• Source folderzhinkgit/embeddedskills/serialThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict674ae8bca880A new audit runs when the source changes
• Repository statusNot archivedLast push 7 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: 嵌入式串口调试工具,用于扫描串口、实时监控、发送数据、记录日志和 Hex 查看。 当用户提到串口、COM 口、UART、AT 命令调试、波特率、Hex 串流、串口抓日志、 串口监控、查看 MCU 输出、二进制协议联调时自动触发,也兼容 /serial 显式调用。 即使用户只是说"看看串口输出"、"发个 AT 命令"或"抓一下日志",只要上下文涉及 串口通信就应触发此 skill。

---
name: serial
description: >-
  嵌入式串口调试工具,用于扫描串口、实时监控、发送数据、记录日志和 Hex 查看。
  当用户提到串口、COM 口、UART、AT 命令调试、波特率、Hex 串流、串口抓日志、
  串口监控、查看 MCU 输出、二进制协议联调时自动触发,也兼容 /serial 显式调用。
  即使用户只是说"看看串口输出"、"发个 AT 命令"或"抓一下日志",只要上下文涉及
  串口通信就应触发此 skill。
argument-hint: "[scan|monitor|send|hex|log] ..."
---

# Serial — 嵌入式串口调试工具

统一封装端口发现、实时监控、数据发送、日志记录和 Hex 查看能力。

## 配置

### 环境级配置 (`skill/config.json`)

serial skill 的环境级配置目前为空对象 `{}`,因为串口参数属于工程级配置,统一在工作区的 `.embeddedskills/config.json` 中管理。

### 工程级配置 (`.embeddedskills/config.json`)

工作区下的 `.embeddedskills/config.json` 存放工程级串口配置:

```json
{
  "serial": {
    "port": "",
    "baudrate": 115200,
    "bytesize": 8,
    "parity": "none",
    "stopbits": 1,
    "encoding": "utf-8",
    "timeout_sec": 1.0,
    "log_dir": ".embeddedskills/logs/serial"
  }
}
```

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `port` | 串口号,如 `COM3` | `""` |
| `baudrate` | 波特率 | `115200` |
| `bytesize` | 数据位 | `8` |
| `parity` | 校验位:none/even/odd/mark/space | `none` |
| `stopbits` | 停止位:1/1.5/2 | `1` |
| `encoding` | 文本编码 | `utf-8` |
| `timeout_sec` | 读写超时(秒) | `1.0` |
| `log_dir` | 日志输出目录 | `.embeddedskills/logs/serial` |

### 参数解析优先级

1. **CLI 参数** (`--port`, `--baudrate` 等) - 最高优先级
2. **工程级配置** (`.embeddedskills/config.json` 中的 `serial` 部分)
3. **状态文件** (`.embeddedskills/state.json` 中的历史记录)
4. **默认值** - 最低优先级

### 自动扫描行为

当未指定 `port` 时,脚本会自动扫描系统串口:
- 若只找到一个串口,自动使用该端口并写入工程配置
- 若找到多个串口,返回候选列表让用户选择(通过 `--port` 指定)
- 若未找到串口,提示错误

## 子命令

| 子命令 | 用途 | 风险 |
|--------|------|------|
| `scan` | 扫描可用串口 | 低 |
| `monitor` | 实时查看文本输出 | 低 |
| `send` | 发送文本或 Hex 数据 | 中 |
| `hex` | 实时查看二进制流 | 低 |
| `log` | 保存串口日志到文件 | 低 |

## 执行流程

1. 检查 `pyserial` 是否可用,未安装时提示 `pip install pyserial`
2. 按优先级解析参数:CLI > 工程级配置 > 状态文件 > 默认值
3. 无子命令时默认执行 `scan`
4. `monitor / send / hex / log` 使用解析后的连接参数
5. 若未指定 `port`,自动扫描系统串口:
   - 唯一候选:自动使用并写入工程配置
   - 多候选:返回列表让用户选择
6. 成功执行后,将确认的参数写回工程配置
7. 运行对应脚本并输出结构化结果
8. 失败时优先反馈端口占用、驱动、波特率和编码问题

## 脚本调用

所有脚本位于 skill 目录的 `scripts/` 下,通过 `python` 直接调用。
脚本会按优先级从 CLI 参数、工程级配置、状态文件中读取参数。

```bash
# 扫描串口
python scripts/serial_scan.py [--filter <关键词>] [--json]

# 实时监控
python scripts/serial_monitor.py [--port <串口>] [--baudrate <波特率>] [--timestamp] [--filter <regex>] [--timeout <秒>] [--json]

# 发送数据
python scripts/serial_send.py [--port <串口>] [--baudrate <波特率>] <data> [--hex] [--crlf] [--repeat <次>] [--wait-response] [--json]

# Hex 查看
python scripts/serial_hex.py [--port <串口>] [--baudrate <波特率>] [--width <列>] [--timeout <秒>] [--json]

# 日志记录
python scripts/serial_log.py [--port <串口>] [--baudrate <波特率>] [--output <文件>] [--duration <秒>] [--format text|csv|json] [--json]
```

## 输出格式

单次命令返回标准 JSON:
```json
{
  "status": "ok",
  "action": "scan",
  "summary": "发现 2 个串口",
  "details": { ... }
}
```

持续命令(monitor --json、hex --json)输出 JSON Lines,结束摘要写入 stderr。

错误输出:
```json
{
  "status": "error",
  "action": "monitor",
  "error": { "code": "port_busy", "message": "串口被其他程序占用" }
}
```

## 串口多路复用 (Mux)

当需要同时使用 minicom(或其他串口工具)和 skill 脚本访问同一个串口设备时,可以通过 mux 后台服务实现多路复用。

### 依赖

- **socat** — `apt install socat` / `pacman -S socat`

### 架构

```
                   ┌──────────────────┐
                   │   Real Hardware   │
                   │   /dev/ttyUSB0    │
                   └────────┬─────────┘
                            │
                   ┌────────▼─────────┐
                   │ Python mux server │
                   │ TCP-LISTEN:20001  │  单串口读者 + 广播
                   └────────┬─────────┘
                            │
            ┌───────────────┼───────────────┐
            │               │               │
   ┌────────▼──────┐ ┌─────▼──────┐ ┌──────▼────────┐
   │  socat PTY    │ │ skill      │ │ skill         │
   │ /tmp/serial_  │ │ monitor    │ │ send/log/hex  │
   │ mux_vserial   │ │ socket://  │ │ socket://     │
   └───────┬───────┘ └────────────┘ └───────────────┘
           │
   ┌───────▼───────┐
   │   minicom     │
   │  (用户侧)      │
   └───────────────┘
```

- **Layer 1**: Python mux 进程独占打开真实串口,暴露 TCP server,并把串口 RX 广播给所有客户端
- **Layer 2**: socat 作为 TCP 客户端创建虚拟 PTY `/tmp/serial_mux_vserial`,供 minicom 使用
- **Skill 脚本**: 自动检测 mux 状态,仅当本次串口配置与 mux 匹配时通过 `socket://` 连接 TCP 端口
- **数据流**: 串口 RX → 广播到所有 TCP 客户端;任一客户端 TX → 转发到真实串口

### Mux 管理命令

```bash
# 启动多路复用
python scripts/serial_mux.py start --port /dev/ttyUSB0 [--baudrate 115200]

# 查询状态
python scripts/serial_mux.py status

# 停止多路复用
python scripts/serial_mux.py stop
```

启动后,skill 脚本(monitor/hex/log/send)自动通过多路复用连接,无需额外参数。若命令显式指定了不同串口或串口参数,则不会复用当前 mux。

### 使用流程

1. `python scripts/serial_mux.py start --port /dev/ttyUSB0`
2. `minicom -D /tmp/serial_mux_vserial`(用户侧交互)
3. `python scripts/serial_monitor.py`(模型侧监控,自动走 mux)
4. 两个终端同时看到串口数据
5. `python scripts/serial_mux.py stop` 停止复用(终止 socat 进程并清理 `/tmp/serial_mux_vserial` 符号链接)

### 写入冲突警告

**多客户端同时写入会导致串口数据错乱。** 监控/hex/log 脚本在通过 mux 连接时输出警告到 stderr。send 脚本输出更强的冲突警告。如需直连真实串口(跳过 mux),使用 `--direct` 参数。

### Mux 状态持久化

mux 进程 PID 保存到 `.embeddedskills/state.json` 的 `serial_mux` 段。脚本退出后下次调用 `status` 会检测进程是否仍存活,自动清理僵尸 PID。`start` 成功后会把已确认的串口配置写回 `.embeddedskills/config.json`,方便后续无参命令复用。`stop` 命令会终止 mux 与 socat PTY 进程,并删除残留的 `/tmp/serial_mux_vserial` 符号链接。

## 核心规则

- 不自动猜测波特率;发现多个候选串口时不自动选择端口
- 参数解析优先级:CLI > 工程级配置 > 状态文件 > 默认值
- 未指定 `port` 时自动扫描,唯一候选自动写入配置,多候选需用户选择
- 成功执行后,确认的参数自动写回 `.embeddedskills/config.json`
- 未明确说明用途时不主动发送任何串口数据
- `--json` 输出的持续流使用 JSON Lines,摘要写 stderr 不污染数据流
- 正则过滤失败不应导致监控退出
- Mux 运行中发送数据前提示用户避免同时写入

## 参考

- `references/common_devices.json`:常见 USB 转串口芯片 VID/PID 映射

Excerpt, first 5,495 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-28
   ✓SAFE B 89 / 100

   first audit · source 674ae8bca880

Questions about serial

• github.com/zhinkgit/embeddedskills/tree/main/serial — the audited source at commit 674ae8bca880 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology