terminal

name	terminal
description	双向交互终端会话工具，用于串口终端、SSH 交互 Shell、本地 Shell、设备控制台、AT/CLI 菜单、需要保持上下文的交互式调试；当用户提到交互终端、串口终端、SSH 终端、打开 shell、发送命令后继续读输出、保持会话、登录后操作、菜单式命令行时触发，也兼容 /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 目录为基准。

# 启动串口终端
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

会话状态详情

会话元数据保存到工作区：

.embeddedskills/state.json

使用 terminal_sessions 字段记录：

{
  "terminal_sessions": {
    "board": {
      "backend": "serial",
      "tcp_port": 23145,
      "pid": 1234,
      "started_at": "2026-05-26T10:00:00+08:00"
    }
  }
}

后台进程日志保存到：

.embeddedskills/logs/terminal/

输出格式

脚本默认输出 JSON：

{
  "status": "ok",
  "action": "read",
  "summary": "读取 42 字节",
  "details": {
    "session": "board",
    "text": "help\r\n..."
  }
}

错误输出：

{
  "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 别名无法解析、进程已退出等都不要吞掉。