# Serial Shell

当需要通过串口与嵌入式设备建立交互式 Shell 会话、执行单条命令或批量脚本时使用。

- Repository: https://github.com/LeoKemp223/embed-ai-tool (1055 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-08-20
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add LeoKemp223/embed-ai-tool --skill serial-shell -g -a claude-code -y`
Codex: `npx skills add LeoKemp223/embed-ai-tool --skill serial-shell -g -a codex -y`
Cursor: `npx skills add LeoKemp223/embed-ai-tool --skill serial-shell -g -a cursor -y`
Gemini CLI: `npx skills add LeoKemp223/embed-ai-tool --skill serial-shell -g -a gemini-cli -y`

## Description

当需要通过串口与嵌入式设备建立交互式 Shell 会话、执行单条命令或批量脚本时使用。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 串口 Shell 交互

## 适用场景

- 用户需要登录嵌入式 Linux / RTOS 设备的串口 Shell，进行命令行交互。
- 用户需要通过串口向设备发送单条命令并捕获响应，供脚本或自动化流程使用。
- 用户有一组命令需要在设备上按顺序执行，希望从文件批量导入。
- 设备运行在 RS-485 半双工总线上，需要用 RTS 控制收发切换。
- 设备 Shell 使用非 UTF-8 编码，或需要 CR+LF 换行符才能正常解析命令。
- 烧录或复位已完成，下一步需要在设备端 Shell 中手动验证或配置。

## 必要输入

- 一个串口设备路径（Windows 下为 `COMn`，Linux 下为 `/dev/ttyUSBn` 或 `/dev/ttyACMn`）。
- 波特率（常见：115200、9600）。
- 若为单命令模式，需提供要执行的命令字符串。
- 若为批量模式，需提供命令脚本文件路径。
- 可选参数：编码、换行风格、RS-485 模式、超时时间、Shell 提示符正则、日志文件路径。

## 自动探测

- 串口优先级为：显式用户输入、`Project Profile` 中的 `serial_port`、脚本自动检测结果，否则阻塞并要求用户指定。
- 波特率优先级为：显式用户输入、`Project Profile` 中的 `baud_rate`、工作区文档或代码常量，最后回落到 `115200`。
- 编码默认为 `utf-8`；若设备回显出现乱码，优先尝试 `gbk`，其次 `latin-1`。
- 换行符默认为 `LF`；若命令发送后设备无响应，尝试 `--crlf`。
- 模式默认为交互式终端；只有在用户显式提供 `--cmd` 或 `--script` 时才切换为非交互模式。
- 若存在多个同样合理的串口候选，列出候选项并阻塞，不要静默猜测。

## 执行步骤

1. 确认 `pyserial` 已安装（`pip install pyserial`），若缺失则返回 `environment-missing` 并指导安装。
2. 运行自带脚本 [shell_proxy.py](shell_proxy.py)，根据用户意图选择模式：
   - **交互模式（默认）**：`python shell_proxy.py -p <端口> -b <波特率>`，进入交互式终端，按 `Ctrl+]` 退出。
   - **单命令模式**：`python shell_proxy.py -p <端口> -b <波特率> --cmd "<命令>"`，等待响应后自动退出。
   - **批量脚本模式**：`python shell_proxy.py -p <端口> -b <波特率> --script <脚本文件>`，逐条执行并打印每条的响应。
3. 若设备 Shell 需要先登录或进入特定目录，使用 `--init "<命令>"`（可重复多次），按顺序在连接后自动发送。
4. 若设备回显乱码，先用 `--encoding gbk` 尝试；若仍无法识别，用 `--hex` 查看原始字节辅助诊断。
5. 若设备使用 RS-485 半双工，启用 `--rs485`；若需捕获逐字符回显，进一步启用 `--rs485-byte`。
6. 若需要将输出保存到文件，使用 `--log <文件路径>`。
7. 读取脚本输出时，重点关注命令执行结果、错误信息和 Shell 提示符返回状态，而不是只转述原始文本。
8. 将确认有效的串口、波特率和编码写回 `Project Profile`。

## 失败分流

- 当缺少 `pyserial` 时，返回 `environment-missing`。
- 当指定串口无法打开（端口不存在、被其他程序占用、设备掉线）时，返回 `connection-failure`。
- 当宿主机没有权限访问串口设备时，返回 `permission-problem`。
- 当命令发送后超时无响应，且编码和换行符均已尝试仍未恢复时，返回 `target-response-abnormal`。
- 当存在多个合理串口候选，或工作区中隐含互相冲突的波特率时，返回 `ambiguous-context`。
- 当脚本文件不存在或无法解析时，返回 `project-config-error`。

## 平台说明

The rest: https://github.com/LeoKemp223/embed-ai-tool/blob/HEAD/skills/serial-shell/SKILL.md