serial-shell

# 串口 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`。 ## 平台说明 - 串口命名规则复用 [shared/platform-compatibility.md](../../shared/platform-compatibility.md)。 - 自带脚本使用 `pyserial`，跨 Linux、macOS、Windows 三种宿主平台。 - Windows 下端口名使用 `COMn` 格式，输出中保留完整端口名。 - Linux 下常见权限问题表现为 `PermissionError`，需检查用户组成员资格或 udev 规则。 - macOS 下优先关注 `/dev/cu.*` 端口，`/dev/tty.*` 作为次级候选。 ## 输出约定 - 输出选中的串口、波特率、编码、执行模式，以及命令执行结果或交互会话的关键观察结论。 - 用 `serial_port`、`baud_rate` 更新 `Project Profile`。 - 若使用了 `--log`，记录日志文件路径。 - 若使用了 `--init`，记录初始化命令及其执行结果。 - 当命令输出表明目标固件发生崩溃、断言或异常复位时，推荐 `debug-gdb-openocd` 或 `debug-jlink`。 ## 交接关系 - 当交互会话完成后，需要持续监视设备运行日志时，将结果交给 `serial-monitor`。 - 当 Shell 输出表明固件崩溃、需要断点或回溯分析时，将结果交给 `debug-gdb-openocd` 或 `debug-jlink`。 - 当串口 Shell 缺少所需工具，需要重新构建并烧录固件时，将结果交给对应的 `build-*` 和 `flash-*` 技能。