terminal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Terminal — 双向交互终端会话

Terminal — Bidirectional Interactive Terminal Session

统一封装串口、SSH 和本地 Shell 的双向交互会话。它补齐

serial

的“监控/发送是分离命令”和

ssh

的“远程命令多为一次性执行”之间的空白：当目标需要保持登录状态、菜单状态、REPL 状态或设备 CLI 上下文时，使用本 skill。

Unified encapsulation of bidirectional interactive sessions for serial ports, SSH, and local shells. It fills the gap between

serial

's "monitoring/sending are separate commands" and

ssh

's "remote commands are mostly one-time executions": Use this skill when the target requires maintaining login status, menu status, REPL status, or device CLI context.

定位

Positioning

```
serial
```
：扫描、监控、单次发送、日志、Hex 查看。
```
ssh
```
：OpenSSH 配置、远程命令、传输、隧道。
```
terminal
```
：保持一个可持续读写的交互式会话，并通过
```
send/read
```
驱动下一步判断。

```
serial
```
: Scanning, monitoring, one-time sending, logging, Hex viewing.
```
ssh
```
: OpenSSH configuration, remote commands, file transfer, tunneling.
```
terminal
```
: Maintain a sustainable read-write interactive session, and drive subsequent judgments through
```
send/read
```
.

配置

Configuration

环境级配置 (

config.json

)

Environment-level Configuration (

config.json

)

terminal skill 的环境级配置目前为空对象

{}

。交互终端的关键参数通常和具体会话绑定，优先通过

start

命令显式传入，避免误连设备或误用凭据。

The environment-level configuration for the terminal skill is currently an empty object

{}

. Key parameters for interactive terminals are usually bound to specific sessions, and are preferably passed explicitly via the

start

command to avoid misconnecting devices or misusing credentials.

会话状态 (

.embeddedskills/state.json

)

Session State (

.embeddedskills/state.json

)

后台会话运行时状态保存到工作区的

.embeddedskills/state.json

，使用

terminal_sessions

字段记录会话名、后端、PID、TCP 控制端口和日志路径。

The runtime state of background sessions is saved to the workspace's

.embeddedskills/state.json

, using the

terminal_sessions

field to record session names, backends, PIDs, TCP control ports, and log paths.

参数优先级

Parameter Priority

CLI 参数 (
```
--port
```
,
```
--baudrate
```
,
```
--host
```
,
```
--name
```
等) - 最高优先级

会话状态 (

.embeddedskills/state.json

中已启动的

terminal_sessions

)

默认值 - 最低优先级

CLI Parameters (
```
--port
```
,
```
--baudrate
```
,
```
--host
```
,
```
--name
```
, etc.) - Highest priority

Session State (

terminal_sessions

already started in

.embeddedskills/state.json

)

Default Values - Lowest priority

子命令

Subcommands

子命令	用途	风险
`start`	启动一个后台交互会话	中
`list`	列出现有会话	低
`status`	查询单个会话状态	低
`send`	向会话写入文本或 Hex 数据	中
`read`	读取并清空会话输出缓冲	低
`attach`	前台行模式接入会话	中
`stop`	停止会话并清理状态	中

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`	Access the session in foreground line mode	Medium
`stop`	Stop the session and clean up state	Medium

后端

Backends

后端	适用场景	依赖
`serial`	MCU UART 控制台、AT 命令、Bootloader 菜单、板卡 CLI	`pyserial`
`ssh`	Linux 开发板交互 Shell、登录后持续操作	OpenSSH 客户端
`local`	本机临时 Shell、REPL、CLI 程序交互	Python 标准库

Backend	Applicable Scenarios	Dependencies
`serial`	MCU UART console, AT commands, Bootloader menus, board CLI	`pyserial`
`ssh`	Linux development board interactive shells, continuous operations after login	OpenSSH client
`local`	Local temporary shells, REPL, CLI program interaction	Python standard library

脚本调用

Script Invocation

所有脚本位于 skill 目录的

scripts/

下，通过

python

直接调用。命令示例均以当前 skill 目录为基准。

bash

undefined

All scripts are located in the

scripts/

directory of the skill, and can be called directly via

python

. Command examples are based on the current skill directory.

bash

undefined

启动串口终端

Start serial terminal

python scripts/terminal_session.py start serial --port COM11 --baudrate 115200 --name board

启动 SSH 终端，host 使用 ~/.ssh/config 中的 Host 别名

Start SSH terminal, use Host alias from ~/.ssh/config

python scripts/terminal_session.py start ssh --host 1380-P904 --name devboard

启动本地 Shell

Start local Shell

python scripts/terminal_session.py start local --name local-shell

发送一行命令并追加 CRLF

Send a command line with appended CRLF

python scripts/terminal_session.py send board "help" --crlf

读取输出，最多等待 1 秒

Read output, wait up to 1 second

python scripts/terminal_session.py read board --timeout 1

前台行模式接入

Access in foreground line mode

python scripts/terminal_session.py attach board

查询与停止

Query and stop

python scripts/terminal_session.py list python scripts/terminal_session.py status board python scripts/terminal_session.py stop board

undefined

python scripts/terminal_session.py list python scripts/terminal_session.py status board python scripts/terminal_session.py stop board

undefined

会话状态详情

Session State Details

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

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/

Session metadata is saved to the workspace:

text

.embeddedskills/state.json

Recorded using the

terminal_sessions

field:

json

{
  "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:

text

.embeddedskills/logs/terminal/

输出格式

Output Format

脚本默认输出 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": "会话不可达，可能已退出"
  }
}

Scripts output JSON by default:

json

{
  "status": "ok",
  "action": "read",
  "summary": "Read 42 bytes",
  "details": {
    "session": "board",
    "text": "help\r\n..."
  }
}

Error output:

json

{
  "status": "error",
  "action": "send",
  "error": {
    "code": "session_unreachable",
    "message": "Session unreachable, may have exited"
  }
}

操作流程

Operation Process

判断是否真的需要保持交互状态；若只是一次性远程命令，优先使用
```
ssh
```
；若只是串口抓日志，优先使用
```
serial
```
。
选择后端：串口控制台用
```
serial
```
，远程 shell 用
```
ssh
```
，本机交互程序用
```
local
```
。
```
start
```
后先
```
read --timeout 1
```
获取启动横幅、登录提示或 shell prompt。
每次
```
send
```
后都用
```
read --timeout <秒>
```
观察反馈，再决定下一步。
完成后执行
```
stop
```
，避免后台进程长期占用串口、SSH 连接或本地 Shell。

Determine whether interactive state retention is truly needed; if it's just a one-time remote command, prioritize using
```
ssh
```
; if it's just serial port log capturing, prioritize using
```
serial
```
.
Select the backend: use
```
serial
```
for serial consoles,
```
ssh
```
for remote shells, and
```
local
```
for local interactive programs.
After
```
start
```
, first use
```
read --timeout 1
```
to get the startup banner, login prompt, or shell prompt.
After each
```
send
```
, use
```
read --timeout <seconds>
```
to observe feedback before deciding the next step.
Execute
```
stop
```
after completion to avoid background processes occupying serial ports, SSH connections, or local shells for long periods.

核心规则

Core Rules

不自动猜测串口端口、波特率、SSH Host 或登录凭据。
未明确用途时不主动发送任何会改变设备状态的命令。
多个会话必须使用不同
```
--name
```
，避免输出混淆。
```
read
```
会清空当前输出缓冲；重要输出需要及时记录到最终回复。
```
attach
```
是行模式，不等同于完整 TTY/raw 模式；需要全屏程序、vim、top、交互式密码输入时，优先让用户使用真实终端工具。
串口会话会独占真实串口；如果需要和外部串口工具共享端口，先使用
```
serial
```
skill 的 mux 能力。
SSH 后端使用
```
~/.ssh/config
```
的 Host 别名；配置主机、跳板机、传输文件仍交给
```
ssh
```
skill。
失败时保留真实错误：端口占用、缺少
```
pyserial
```
、
```
ssh
```
不存在、Host 别名无法解析、进程已退出等都不要吞掉。

Do not automatically guess serial ports, baud rates, SSH Hosts, or login credentials.
Do not actively send any commands that change device status when the purpose is unclear.
Multiple sessions must use different
```
--name
```
to avoid output confusion.
```
read
```
will clear 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, prioritize letting users use real terminal tools.
Serial sessions will occupy the physical serial port exclusively; if sharing the port with external serial tools is needed, first use the mux capability of the
```
serial
```
skill.
The SSH backend uses Host aliases from
```
~/.ssh/config
```
; configuration of hosts, jump servers, and file transfer are still handled by the
```
ssh
```
skill.
Retain real errors when failures occur: do not swallow errors such as port occupation, missing
```
pyserial
```
, non-existent
```
ssh
```
, unresolvable Host aliases, exited processes, etc.

terminal

Original

Translation

Terminal — 双向交互终端会话

Terminal — Bidirectional Interactive Terminal Session

定位

Positioning

配置

Configuration

环境级配置 (config.json)

Environment-level Configuration (config.json)

会话状态 (.embeddedskills/state.json)

Session State (.embeddedskills/state.json)

参数优先级

Parameter Priority

子命令

Subcommands

后端

Backends

脚本调用

Script Invocation

启动串口终端

Start serial terminal

启动 SSH 终端，host 使用 ~/.ssh/config 中的 Host 别名

Start SSH terminal, use Host alias from ~/.ssh/config

启动本地 Shell

Start local Shell

发送一行命令并追加 CRLF

Send a command line with appended CRLF

读取输出，最多等待 1 秒

Read output, wait up to 1 second

前台行模式接入

Access in foreground line mode

查询与停止

Query and stop

会话状态详情

Session State Details

输出格式

Output Format

操作流程

Operation Process

核心规则

Core Rules

环境级配置 (
`config.json`
)

Environment-level Configuration (
`config.json`
)

会话状态 (
`.embeddedskills/state.json`
)

Session State (
`.embeddedskills/state.json`
)