terminal

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkUndeclared1 observation, not in its own description
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

with socket.create_connection(("127.0.0.1", int(record["tcp_port"])), timeout=timeout) as sock:

payload = bytes.fromhex(data) if request.get("hex") else str(data).encode(request.get("encoding") or "utf-8")

network use found in code, not declared in the description

Audit 0.4.1 · source sha 674ae8bca880 · 28 Oct 2026Report an issue or request a re-scan

• Publisherzhinkgit GitHub userOwner of the repository this skill is read from
• Source folderzhinkgit/embeddedskills/terminalThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict674ae8bca880A new audit runs when the source changes
• Repository statusNot archivedLast push 8 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

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

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

Excerpt, first 3,472 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-28
   ✓SAFE B 89 / 100

   first audit · source 674ae8bca880

Questions about terminal

• github.com/zhinkgit/embeddedskills/tree/main/terminal — the audited source at commit 674ae8bca880 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology