terminal

# Terminal — 双向交互终端会话 统一封装串口、SSH 和本地 Shell 的双向交互会话。它补齐 `serial` 的“监控/发送是分离命令”和 `ssh` 的“远程命令多为一次性执行”之间的空白：当目标需要保持登录状态、菜单状态、REPL 状态或设备 CLI 上下文时，使用本 skill。 ## 定位 - `serial`：扫描、监控、单次发送、日志、Hex 查看。 - `ssh`：OpenSSH 配置、远程命令、传输、隧道。 - `terminal`：保持一个可持续读写的交互式会话，并通过 `send/read` 驱动下一步判断。 ## 配置 ### 环境级配置 (`config.json`) terminal skill 的环境级配置目前为空对象 `{}`。交互终端的关键参数通常和具体会话绑定，优先通过 `start` 命令显式传入，避免误连设备或误用凭据。 ### 会话状态 (`.embeddedskills/state.json`) 后台会话运行时状态保存到工作区的 `.embeddedskills/state.json`，使用 `terminal_sessions` 字段记录会话名、后端、PID、TCP 控制端口和日志路径。 ### 参数优先级 1. **CLI 参数** (`--port`, `--baudrate`, `--host`, `--name` 等) - 最高优先级 2. **会话状态** (`.embeddedskills/state.json` 中已启动的 `terminal_sessions`) 3. **默认值** - 最低优先级 ## 子命令 | 子命令 | 用途 | 风险 | |--------|------|------| | `start` | 启动一个后台交互会话 | 中 | | `list` | 列出现有会话 | 低 | | `status` | 查询单个会话状态 | 低 | | `send` | 向会话写入文本或 Hex 数据 | 中 | | `read` | 读取并清空会话输出缓冲 | 低 | | `attach` | 前台行模式接入会话 | 中 | | `stop` | 停止会话并清理状态 | 中 | ## 后端 | 后端 | 适用场景 | 依赖 | |------|----------|------| | `serial` | MCU UART 控制台、AT 命令、Bootloader 菜单、板卡 CLI | `pyserial` | | `ssh` | Linux 开发板交互 Shell、登录后持续操作 | OpenSSH 客户端 | | `local` | 本机临时 Shell、REPL、CLI 程序交互 | Python 标准库 | ## 脚本调用 所有脚本位于 skill 目录的 `scripts/` 下，通过 `python` 直接调用。命令示例均以当前 skill 目录为基准。 ```bash # 启动串口终端 python scripts/terminal_session.py start serial --port COM11 --baudrate 115200 --name board # 启动 SSH 终端，host 使用 ~/.ssh/config 中的 Host 别名 python scripts/terminal_session.py start ssh --host 1380-P904 --name devboard # 启动本地 Shell python scripts/terminal_session.py start local --name local-shell # 发送一行命令并追加 CRLF python scripts/terminal_session.py send board "help" --crlf # 读取输出，最多等待 1 秒 python scripts/terminal_session.py read board --timeout 1 # 前台行模式接入 python scripts/terminal_session.py attach board # 查询与停止 python scripts/terminal_session.py list python scripts/terminal_session.py status board python scripts/terminal_session.py stop board ``` ## 会话状态详情 会话元数据保存到工作区： ```text .embeddedskills/state.json ``` 使用 `terminal_sessions` 字段记录： ```json { "terminal_sessions": { "board": { "backend": "serial", "tcp_port": 23145, "pid": 1234, "started_at": "2026-05-26T10:00:00+08:00" } } } ``` 后台进程日志保存到： ```text .embeddedskills/logs/terminal/ ``` ## 输出格式 脚本默认输出 JSON： ```json { "status": "ok", "action": "read", "summary": "读取 42 字节", "details": { "session": "board", "text": "help\r\n..." } } ``` 错误输出： ```json { "status": "error", "action": "send", "error": { "code": "session_unreachable", "message": "会话不可达，可能已退出" } } ``` ## 操作流程 1. 判断是否真的需要保持交互状态；若只是一次性远程命令，优先使用 `ssh`；若只是串口抓日志，优先使用 `serial`。 2. 选择后端：串口控制台用 `serial`，远程 shell 用 `ssh`，本机交互程序用 `local`。 3. `start` 后先 `read --timeout 1` 获取启动横幅、登录提示或 shell prompt。 4. 每次 `send` 后都用 `read --timeout <秒>` 观察反馈，再决定下一步。 5. 完成后执行 `stop`，避免后台进程长期占用串口、SSH 连接或本地 Shell。 ## 核心规则 - 不自动猜测串口端口、波特率、SSH Host 或登录凭据。 - 未明确用途时不主动发送任何会改变设备状态的命令。 - 多个会话必须使用不同 `--name`，避免输出混淆。 - `read` 会清空当前输出缓冲；重要输出需要及时记录到最终回复。 - `attach` 是行模式，不等同于完整 TTY/raw 模式；需要全屏程序、vim、top、交互式密码输入时，优先让用户使用真实终端工具。 - 串口会话会独占真实串口；如果需要和外部串口工具共享端口，先使用 `serial` skill 的 mux 能力。 - SSH 后端使用 `~/.ssh/config` 的 Host 别名；配置主机、跳板机、传输文件仍交给 `ssh` skill。 - 失败时保留真实错误：端口占用、缺少 `pyserial`、`ssh` 不存在、Host 别名无法解析、进程已退出等都不要吞掉。