SKILL.md
串口 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时才切换为非交互模式。 - 若存在多个同样合理的串口候选，列出候选项并阻塞，不要静默猜测。
执行步骤
- 确认
pyserial已安装（pip install pyserial），若缺失则返回environment-missing并指导安装。 - 运行自带脚本 [shellproxy.py](shellproxy.py)，根据用户意图选择模式：
- 交互模式（默认）：python shellproxy.py -p <端口> -b <波特率>，进入交互式终端，按 Ctrl+] 退出。 - 单命令模式：python shellproxy.py -p <端口> -b <波特率> --cmd "<命令>"，等待响应后自动退出。 - 批量脚本模式：python shell_proxy.py -p <端口> -b <波特率> --script <脚本文件>，逐条执行并打印每条的响应。
- 若设备 Shell 需要先登录或进入特定目录，使用
--init "<命令>"（可重复多次），按顺序在连接后自动发送。 - 若设备回显乱码，先用
--encoding gbk尝试；若仍无法识别，用--hex查看原始字节辅助诊断。 - 若设备使用 RS-485 半双工，启用
--rs485；若需捕获逐字符回显，进一步启用--rs485-byte。 - 若需要将输出保存到文件，使用
--log <文件路径>。 - 读取脚本输出时，重点关注命令执行结果、错误信息和 Shell 提示符返回状态，而不是只转述原始文本。
- 将确认有效的串口、波特率和编码写回
Project Profile。
失败分流
- 当缺少
pyserial时，返回environment-missing。 - 当指定串口无法打开（端口不存在、被其他程序占用、设备掉线）时，返回
connection-failure。 - 当宿主机没有权限访问串口设备时，返回
permission-problem。 - 当命令发送后超时无响应，且编码和换行符均已尝试仍未恢复时，返回
target-response-abnormal。 - 当存在多个合理串口候选，或工作区中隐含互相冲突的波特率时，返回
ambiguous-context。 - 当脚本文件不存在或无法解析时，返回
project-config-error。
平台说明
- 串口命名规则复用 [shared/platform-compatibility.md](../../shared/platform-compatibility.md)。
- 自带脚本使用
pyserial，跨 Linux、macOS、Windows 三种宿主平台。 - Windows 下端口名使用
COMn格式，输出中保留完整端口名。 - Linux 下常见权限问题表现为
PermissionError，需检查用户组成员资格或 udev 规则。 - macOS 下优先关注
/dev/cu.端口，/dev/tty.作为次级候选。
输出约定
- 输出选中的串口、波特率、编码、执行模式，以及命令执行结果或交互会话的关键观察结论。
- 用
serialport、baudrate更新Project Profile。 - 若使用了
--log，记录日志文件路径。 - 若使用了
--init，记录初始化命令及其执行结果。 - 当命令输出表明目标固件发生崩溃、断言或异常复位时，推荐
debug-gdb-openocd或debug-jlink。
交接关系
- 当交互会话完成后，需要持续监视设备运行日志时，将结果交给
serial-monitor。 - 当 Shell 输出表明固件崩溃、需要断点或回溯分析时，将结果交给
debug-gdb-openocd或debug-jlink。 - 当串口 Shell 缺少所需工具，需要重新构建并烧录固件时，将结果交给对应的
build-和flash-技能。