terminal

Terminal — Bidirectional Interactive Terminal Session

A unified wrapper for bidirectional interactive sessions over serial, SSH, and local Shell. It fills the gap between serial 's "monitoring/sending are separate commands" and ssh 's "remote commands are mostly one-shot execution": when the target needs to maintain login state, menu state, REPL state, or device CLI context, use this skill.

Positioning

• serial: scanning, monitoring, single send, logs, Hex view.
• ssh: OpenSSH configuration, remote commands, transfer, tunneling.
• terminal: maintain a persistent interactive session that can be read from and written to continuously, and drive the next-step decision through send/read .

Configuration

Environment-level configuration (config.json)

The terminal skill's environment-level configuration is currently an empty object {}. The key parameters of an interactive terminal are usually bound to a specific session; prefer passing them explicitly via the start command to avoid connecting to the wrong device or misusing credentials.

Session state (.embeddedskills/state.json)

The background session runtime state is saved to the workspace's .embeddedskills/state.json, using the terminal_sessions field to record the session name, backend, PID, TCP control port, and log path.

Parameter priority

1. CLI parameters (--port, --baudrate, --host, --name , etc.) - highest priority
2. Session state (.embeddedskills/state.json already started in terminal_sessions)
3. Default values - lowest priority

Subcommand

Subcommand	Purpose	Risk
start	Start a background interactive session	Medium
list	List existing sessions	Low
status	Query the status of a single session	Low
send	Write text or Hex data to the session	Medium
read	Read and clear the session output buffer	Low
attach	Attach to the session in foreground line mode	Medium
stop	Stop the session and clean up state	Medium

Backend

Backend	Applicable scenarios	Dependencies
serial	MCU UART console, AT commands, Bootloader menu, board CLI	pyserial
ssh	Linux development board interactive Shell, continuous operation after login	OpenSSH client
local	Local temporary Shell, REPL, CLI program interaction	Python standard library

Script invocation

All scripts are located under the skill directory's scripts/ and are invoked directly via python . Command examples are all based on the current skill directory.

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

Session state details

Session metadata is saved to the workspace:

.embeddedskills/state.json

Use the terminal_sessions field to record:

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

Background process logs are saved to:

.embeddedskills/logs/terminal/

Output format

Scripts output JSON by default:

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

Error output:

{
  "status": "error",
  "action": "send",
  "error": {
    "code": "session_unreachable",
    "message": "会话不可达，可能已退出"
  }
}

Operation flow

1. Determine whether an interactive state really needs to be maintained; if it is just a one-off remote command, prefer using ssh; if it is just capturing logs over serial, prefer using serial。
2. Choose the backend: for a serial console use serial, for a remote shell use ssh, for a local interactive program use local。
3. start then first read --timeout 1 to get the startup banner, login prompt, or shell prompt.
4. Each time send then use read --timeout <秒> to observe the feedback before deciding the next step.
5. When finished, run stop, to avoid background processes occupying the serial port, SSH connection, or local shell for a long time.

Core rules

• Do not automatically guess the serial port, baud rate, SSH Host, or login credentials.
• When the purpose is unclear, do not proactively send any command that would change the device state.
• Multiple sessions must use different --name, to avoid output confusion.
• read clears the current output buffer; important output needs to be recorded in the final reply promptly.
• attach is line mode, not equivalent to full TTY/raw mode; when full-screen programs, vim, top, or interactive password input are needed, prefer having the user use a real terminal tool.
• A serial session exclusively occupies the real serial port; if the port needs to be shared with an external serial tool, first use the serial skill's mux capability.
• The SSH backend uses the Host alias of ~/.ssh/config ; configuring hosts, jump hosts, and transferring files are still left to ssh skill。
• When it fails, preserve the real error: port occupied, missing pyserial、ssh does not exist, Host alias cannot be resolved, process has exited, etc., must not be swallowed.