# SerialTerminal

**Repository Path**: trigger-cn/SerialTerminal

## Basic Information

- **Project Name**: SerialTerminal
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# <img src="assets/icon-512x512.png" width="48" height="48" align="center" alt="Icon" /> Serial Terminal

一个基于 Electron 的桌面串口终端工具，面向嵌入式开发、串口调试、设备联调、日志查看与关键字过滤场景。当前版本已支持主串口终端、过滤标签页、实时图表标签页、分屏工作区、Shell 标签页、多标签独立日志、多语言和在线更新。

[Gitee Releases 下载最新版](https://gitee.com/trigger-cn/SerialTerminal/releases)

![Serial Terminal Screenshot](assets/Snipaste_2026-04-18_22-22-44.png)

## 简介

Serial Terminal 使用 Electron 构建桌面应用，串口通信基于 `serialport`，终端显示基于 `xterm.js`。应用以单串口调试为核心，在同一主界面中集成：

- 主串口终端
- 多个过滤标签页
- 实时串口数据图表标签页
- 最多 2 个 pane 的分屏工作区
- 系统 Shell 标签页
- 左侧侧边栏工具区
- 左侧边栏支持收起为窄工具栏，顶部显示 RX/TX 实时速率，底部保留展开、连接/断开、清空日志、设置、输入栏和 Shell 栏快捷按钮；折叠状态会自动恢复
- 右侧 Shell 侧边栏
- 独立设置窗口

适合用于 MCU、模组、工业设备、AT 指令、协议联调与日志筛选分析等场景。

## 当前功能

### 串口连接与通信

- 自动枚举本机串口并支持手动刷新
- 支持标准波特率和自定义波特率
- 支持数据位、停止位、校验位配置
- 支持接收/发送换行模式切换：`CRLF / LF / CR`
- RX 显示模式保留在串口设置中；统一 TX 配置位于左侧“发送”页顶部，支持 `Text / Hex`、`UTF-8 / ASCII / GBK` 文本编码及追加 `CRLF / 0D 0A`
- 连接后自动保存最近一次串口参数，便于下次恢复
- 主终端支持像普通终端一样直接键入并逐键发送到串口

### 主终端与工作区

- 基于 `xterm.js` 的主终端显示区域
- 支持显示时间戳和行号
- 支持可配置滚动缓冲区大小
- 支持左右分屏与上下分屏
- 首版最多支持 2 个 pane
- 每个 pane 内支持独立 tabs
- 支持在 pane 之间移动过滤、图表与 Shell 标签页，并支持拖动标签调整 pane 内顺序或跨 pane 移动
- 支持拖动 pane 分隔条调整区域比例
- 工作区布局会自动持久化，并在下次启动时恢复
- 过滤、图表与 Shell 标签页支持双击标签自定义名称
- 串口输出在主进程和渲染进程中批量处理，终端显示刷新率最高为 30 FPS，降低高吞吐场景的 CPU 占用
- 默认保留 20,000 行滚动缓冲，可在设置中调整，最大 100,000 行；显示队列过载时优先丢弃旧的待显示内容，不影响日志保存和快捷指令自动触发
- 主 Log、过滤 Log 和 Shell 终端使用增强的 Unicode 11 字符宽度规则及系统 emoji 字体回退，天气、符号和其他 emoji 图标会按双宽单元格显示

### 过滤标签页

- 支持创建多个过滤标签页
- 每个过滤标签页拥有独立的：
  - 过滤文本输入框
  - 区分大小写开关
  - 正则开关
  - 终端显示区
- 支持过滤历史下拉复用
- 支持关闭应用后恢复已打开的过滤标签页
- 支持恢复过滤条件、大小写、整词、正则状态和所属 pane
- 过滤结果会对命中文本进行高亮显示
- 可从过滤结果右键定位到主终端；定位使用完整逻辑行精确匹配，并处理终端自动折行和重复内容，不依赖行号搜索

### 搜索

- 主终端、过滤标签页、Shell 标签页都可作为搜索目标
- 搜索目标跟随当前活动 pane 的活动 tab
- 支持普通文本、正则、区分大小写、整词匹配
- 左侧搜索面板显示当前匹配序号 / 总匹配数
- 匹配数基于本地终端 buffer 统计
- 在当前活动终端选中文本后按 `Ctrl+F` 或自定义搜索快捷键，会自动展开搜索侧栏、填入选中文本并立即搜索；无选区时只聚焦搜索框

### 发送能力

- 支持直接在主终端输入并发送串口数据
- 支持底部主输入框发送
- 主输入框支持：
  - 发送按钮
  - 将当前输入加入快捷发送
  - 历史命令记录和下拉菜单
  - 上下键切换历史命令
  - 按回车发送开关
- 发送后输入框内容不会自动清空
- 底部输入框会保存最近发送历史，默认 20 条；历史菜单可点击条目替换当前输入内容，保存数量可在设置窗口调整，达到上限时自动删除最老条目
- 左侧“发送”页顶部提供统一发送配置；底部输入、自动发送和右键整段发送使用当前统一模式、文本编码和追加选项。主终端 Text 逐键输入不应用“追加 CRLF”，Enter 只服从换行模式
- Text/Hex 切换时底部输入分别保留当前会话内的草稿
- 保留左侧自动发送能力，可配置内容和时间间隔；全局发送配置变化时会重新校验并安全重启
- 支持快捷发送列表
- 每条快捷发送保存稳定 ID、标签、内容、独立的 `Text / Hex` 模式和可选自动触发设置，支持新增、编辑、删除、拖动排序；手动发送和自动触发都使用该指令自身的模式
- 快捷发送支持自定义分组、组内排序、跨组移动、分组折叠、重命名和删除；删除分组会同时删除组内指令及对应的窄侧栏快捷入口
- 每条快捷发送可在编辑窗口单独启用自动触发，匹配文本支持正则、大小写匹配和全字匹配；默认关闭，开启后串口新接收内容按接收编码解码并匹配，命中后自动发送对应快捷指令
- 自动触发命中时，对应快捷发送按钮会以绿色闪烁提示
- 展开和收起侧栏共享快捷发送内容，但分别保存各自的排列顺序；收起侧栏可为快捷按钮配置文字和颜色

### 快捷键

- 设置窗口提供“快捷键”页，可查看、修改或恢复默认快捷键
- 默认快捷键包括：
  - `Ctrl+Enter`：发送底部输入框
  - `Alt+H`：打开/关闭发送历史菜单
  - `Alt+Up / Alt+Down`：切换发送历史
  - `Ctrl+F`：聚焦搜索
  - `Ctrl+L`：清空当前活动终端
  - `Ctrl+R`：刷新串口列表
  - `Ctrl+Shift+D`：连接/断开串口
- 搜索快捷键会自动展开左侧边栏并切换到搜索页
- 搜索快捷键在 Log 终端获得焦点时仍然有效，并优先搜索当前活动终端中的选中文本

### Hex 使用

- RX 显示配置与左侧“发送”页的统一 TX 配置互相独立。例如 RX 可查看 Hex dump，同时 TX 仍按 UTF-8 文本发送。
- Text 发送会按当前 TX 文本编码生成原始字节；对端串口工具必须使用相同编码显示，否则中文等非 ASCII 文本会乱码。排查时可让对端切到 Hex 显示：`中文` 在 UTF-8 下应为 `E4 B8 AD E6 96 87`，在 GBK 下应为 `D6 D0 CE C4`。
- TX 为 Hex 时，请使用底部输入框、快捷发送或自动发送；主终端逐键输入不会直接发送，粘贴内容会放入底部输入框校验。
- Hex 输入支持连续字节或使用空格、Tab、换行、逗号、冒号、连字符分隔，也支持两位字节的 `0x` 前缀和小写字母。例如 `AA5501FF`、`AA 55 01 FF`、`0xAA,0x55`、`aa:55-01`。
- Hex 校验是严格的：空输入、非法字符、奇数个数字、非两位的 `0x` token 和超限载荷不会发送。统一追加选项在 Hex 模式下追加真实字节 `0D 0A`，在 Text 模式下追加 CRLF。
- RX Hex dump 默认每行 16 字节，显示 8 位偏移与 ASCII 预览；不可打印字节显示为 `.`。每行字节数、偏移、ASCII、大小写和残余行空闲刷新时间可在设置窗口调整。
- Hex 搜索作用于终端中显示的偏移、字节和 ASCII 文本。过滤标签页创建时固定为当时的 RX 模式；模式不一致时暂停接收，Hex 正则/普通过滤作用于格式化后的单行文本。

### Shell 标签页

- 支持在工作区中新建系统 Shell 标签页
- 每个 Shell 标签页对应独立的 `node-pty` 会话
- 支持在两个 pane 中创建、切换、移动、关闭 Shell 标签页
- 支持右侧 Shell 侧边栏显示当前活跃会话
- 支持自定义 Shell Profiles：
  - 名称
  - 可执行文件路径
  - 逐项启动参数（含空格或引号的单个参数会按原始 argv 保存）
  - Shell 类型
- 支持设置默认 Shell Profile
- Shell Profile 使用稳定 ID；重命名不会改变默认选择，删除默认项后不会静默改用其他 Profile
- 当前默认内置 `CMD` 和 `PowerShell`
- Shell 标签页状态和布局可恢复，进程会在启动时重新创建

### 实时图表标签页

- 可在任一 pane 中新建、关闭、重命名、拖动和恢复图表标签页，图表配置与工作区布局会持久化
- 图表持续消费新收到的串口文本行，不会从终端滚动缓冲区回放历史，也不会在应用重启后恢复上次的数据点
- 提供三种解析方式：
  - 自动键值：识别常见的 `name=value` 和 `name:value`
  - 格式模板：使用 `{field}`、`{field:type}` 等占位符描述固定日志格式
  - 正则表达式：使用 JavaScript 正则命名捕获组提取字段
- 可设置接收编码和可选行标记，从混合日志中过滤目标样本；内置输入指导和样例字段发现
- 支持最多 16 个可见数值系列，每个系列可配置名称、颜色、原始单位、显示单位和小数精度
- 支持 `us / ms / s` 时间单位换算，缺失值以断点显示，不使用 `0` 填充
- 主图显示当前时间窗口，底部时间轴保留完整会话趋势；可拖动、缩放、点击定位并一键回到实时跟随
- 支持暂停/继续、清空、自动或固定 Y 轴、自动范围包含零点和 Y 轴边距
- 实时显示当前值、最小值、最大值和平均值；原始数据过期后使用降采样历史维持全局趋势
- 可限制原始点数和保留时长，解析在 Worker 中执行并带过载丢弃保护，避免高频日志阻塞主界面
- 可将当前可视窗口或全部仍保留的原始数据导出为 UTF-8 BOM CSV；降采样历史不作为精确原始数据导出

### 右键菜单

- 主终端、过滤标签页、Shell 标签页和图表标签页均支持右键菜单
- 已支持的常用操作包括：
  - 复制
  - 复制全部
  - 查找选中内容
  - 清空当前终端
- 主终端额外支持：
  - 粘贴并发送
  - 发送选中内容
  - 基于选中文本新建过滤标签页
- 过滤标签页额外支持：
  - 用选中文本作为过滤条件
  - 将选中文本追加到过滤条件
  - 在主终端中定位
  - 切换区分大小写
  - 切换正则
  - 关闭过滤标签页
- Shell 标签页支持基础会话相关操作，如关闭和重启
- 图表标签页支持暂停/继续、回到实时、清空、导出当前窗口或全部原始数据、打开设置、移动到另一 pane 和关闭标签页

### 高亮与外观

- 可配置终端字体、字号、前景色、背景色
- 可配置终端字体字重
- 可配置时间戳颜色和行号颜色
- 可配置搜索结果、过滤命中和终端选区的前景色与背景色
- 支持多条关键词高亮规则
- 设置窗口的“高亮”页可单独将高亮规则恢复为默认配置，不会重置外观、日志、串口等其它设置
- 每条高亮规则支持：
  - 启用 / 禁用
  - 颜色
  - 大小写控制
  - 正则模式
- 支持系统字体列表选择
- 支持鼠标滚轮滚动行数配置

### 日志与配置

- 支持自动记录串口/终端数据
- 支持自定义日志目录、文件名格式和编码
- 日志在内存中缓冲，达到配置阈值或每 5 秒静默刷盘，并在断开连接、关闭标签页或退出前写入文件
- 支持将所有标签页日志分别保存到独立文件
- 日志文件名格式支持：
  - `%Y %m %d %H %M %S`
  - `%tab`（标签页标题，仅多标签日志场景）
- 主终端、过滤标签页、Shell 标签页都可分别写入独立日志文件
- 可另行启用 RX 原始二进制日志；它逐字节保存串口接收数据，不包含 TX、连接提示或格式化文本，并使用 `.bin` 文件
- 原始日志文件名支持 `%Y %m %d %H %M %S`，同名时自动添加序号；数据按缓冲阈值、断开和退出时追加落盘
- 可选择按本地日期保存到 `YYYY-MM-DD` 子目录，跨过午夜后自动切换目录
- 可配置自动清理周期为关闭、保留 7 天、30 天或 60 天；清理会递归处理日志目录中的 `.txt`、`.log` 和 `.bin`，并跳过当前正在写入的文件
- 左侧工具区可将当前活动的主终端、过滤终端或 Shell 终端缓冲区手动导出为 UTF-8 文本；该目录与自动日志目录独立记忆
- 多标签日志和手动导出文件名会使用标签页的自定义名称
- 使用 `electron-log` 保存应用运行日志，并记录主进程和渲染进程异常、未处理的 Promise 拒绝、加载失败、无响应和渲染进程退出等诊断信息
- Electron Crashpad 在用户数据目录的 `crash-dumps` 中保存本地崩溃转储，不自动上传
- 所有全局配置保存在用户目录下的 `config.json`

### 多语言

当前内置语言：

- English
- 简体中文
- 繁體中文
- Français
- Русский
- Deutsch

主界面、设置窗口、输入区、右键菜单和更新提示均支持多语言文案。

### 匿名标识活跃统计

- 匿名活跃统计默认开启，可随时在设置窗口中关闭
- 首次启用时生成随机安装 ID，每天向服务端成功上报一次；版本变化后会额外上报一次，应用持续运行时也会按天检查
- 上报字段仅包含随机安装 ID、应用版本、操作系统、处理器架构和协议版本
- 不收集串口名称、串口数据、文件、用户名、硬件序列号或崩溃转储；上报失败不会影响串口功能
- 服务端只保存安装 ID 的 HMAC，不保存原始安装 ID，并按 UTC 日期去重统计 DAU、WAU 和 MAU；该数据属于可关联的假名化统计，不用于授权、计费或安全判断
- 设置中关闭匿名统计后会立即停止定时器和正在进行的请求

### 更新与发布

- 集成 `electron-updater`
- 应用启动时自动检查更新
- 支持手动检查更新
- 更新不会静默下载或在退出时自动安装，下载和安装都需要用户明确确认
- 发现新版本时支持：
  - 立即更新
  - 暂不更新
  - 跳过此版本
- 下载完成后支持重启安装或稍后安装
- 自动更新元数据、安装包和差分文件均从腾讯云 COS 下载
- 新版客户端先访问 `https://trigger-cn.top/serialterminal/api/v1/update-source` 获取集中配置的 `latest.yml` 地址；该地址不可用时依次回退服务器 `https://trigger-cn.top/serialterminal/latest.yml`、COS 和 GitHub Release 的 `latest.yml`，重复地址会自动跳过
- 活跃度管理后台的“客户端更新源”可以修改 PostgreSQL 中的更新元数据地址，要求使用 HTTPS 且路径必须以 `latest.yml` 结尾；更新源切换不需要重新发布客户端
- 旧版 `0.3.7` 通过 `https://trigger-cn.top/serialterminal/latest.yml` 兼容入口读取同一份 COS 元数据，升级后改为直接访问 COS
- 更新提示会尝试显示 Gitee Release 正文；获取不到时提示网络异常
- 使用 `electron-builder` 打包 Windows 与 Linux 发布物
- 推送 `v*` Git tag 后，GitHub Actions 会使用同一 lockfile 并行构建 Windows/Linux 发布物；构建前执行测试和 native rebuild，构建后校验 lockfile 未变化
- GitHub Release 正文会自动列出上一个 tag 到当前 tag 之间的提交，每个提交只出现一次，不按提交类型分类
- 发布任务将 Windows 和 Linux 安装包、更新元数据统一上传到 GitHub Releases
- GitHub Actions 仅向 COS 上传 Windows 自动更新必需的 `.exe`、`.exe.blockmap` 和 `latest.yml`；Linux 产物只保留在 GitHub Release
- GitHub Release 和 COS 下载验证成功后，GitHub Actions 将发布提交和不可变 Tag 同步到 Gitee；不会在 GitHub 侧直接修改 Gitee Release
- `.workflow/gitee-release.yml` 由版本 Tag 触发，Windows `.exe` 优先从 COS 下载，每个来源按 `2s/5s/10s` 间隔重试三次；COS 仍失败时改从 GitHub Release 下载，并用 GitHub 附件记录校验文件名和大小，最后复用 GitHub Release 正文创建或更新同 Tag 的 Gitee Release
- Gitee Go 流水线需要配置加密变量 `CI_GITEE_ACCESS_TOKEN`，流水线会将其映射为发布脚本读取的 `GITEE_ACCESS_TOKEN`；令牌需具备该仓库 Release 创建、更新和附件上传权限，企业流水线可复用同一条镜像命令
- 所有发布和公开下载验证成功后，发布任务会永久保留 `releases/latest/`，并按语义版本仅保留最新三个 `releases/v*/` 版本；COS 发布身份需具备列举桶对象和批量删除对象权限

## 项目结构

```text
.
├─ assets/                    图标与截图资源
├─ scripts/                   辅助脚本
├─ test/                      Node 自动化测试与 Python 串口测试脚本
├─ index.html                 主窗口界面
├─ renderer.js                主窗口渲染逻辑（终端、过滤、搜索、输入、Shell、图表）
├─ chart-parser.js             图表自动键值、模板和正则解析
├─ chart-parser-worker.js      图表解析 Worker 入口
├─ chart-parser-ipc-client.js  图表解析 IPC 客户端
├─ chart-data-model.js         图表数据保留、降采样、查询与统计
├─ chart-view.js               实时折线图、时间轴和视口交互
├─ chart-csv.js                图表 CSV 导出
├─ serial-codec.js             Text/Hex 发送请求校验与字节构造
├─ serial-text-stream.js       图表使用的串口文本流解码与分行
├─ config-values.js            设置数值范围与统一归一化
├─ shell-profiles.js           Shell Profile 归一化、迁移与查找
├─ hex-formatter.js            流式 Hex dump 格式化
├─ workspace-manager.js       工作区 pane/tab 布局管理
├─ main.js                    主进程逻辑（窗口、配置、串口、日志、更新、Shell PTY）
├─ preferences.html           设置窗口界面
├─ preferences.js             设置窗口逻辑
├─ i18n.js                    多语言字典与翻译函数
├─ style.css                  全局样式
├─ agent_notes.md             项目接手与维护说明
├─ HEX_FEATURE_TODO.md         Hex 功能实施状态、测试矩阵与未完成项
├─ package.json               依赖、脚本与打包配置
└─ README.md                  项目说明
```

## 技术栈

- Electron
- serialport
- @xterm/xterm
- @xterm/addon-fit
- @xterm/addon-search
- @xterm/addon-unicode11
- uPlot
- iconv-lite
- node-pty
- electron-builder
- electron-updater
- electron-log
- font-list

## 开发环境要求

- Node.js 22.12+
- npm
- 由于项目依赖原生模块，首次安装通常需要本机具备编译环境

### Windows

建议安装 Visual Studio Build Tools（C++ workload）。

### Linux

建议安装 `build-essential` 与 `python3`。

## 安装依赖

```bash
npm install
```

安装后会自动执行 `electron-builder install-app-deps`，用于处理 Electron 原生依赖。

## 本地运行

```bash
npm start
```

## 常用脚本

### 重新编译原生模块

```bash
npm run rebuild
```

### 构建当前平台发行包

```bash
npm run dist
```

### 构建 Windows 包

```bash
npm run dist:win
```

### 构建 Linux 包

```bash
npm run dist:linux
```

正式发版时推送 `v*` tag，GitHub Actions 会自动生成版本说明并创建 GitHub Release。应用更新提示优先读取线上 Release 正文。

## 配置说明

程序运行时会在用户数据目录中生成配置文件：

- 配置文件：`config.json`
- 默认日志目录：用户文档目录下的 `SerialTerminalLogs`
- 应用诊断日志：用户数据目录下的 `logs`
- 本地崩溃转储：用户数据目录下的 `crash-dumps`

当前配置主要包括：

- 外观设置
- 高亮规则
- 高亮规则可在设置窗口单独恢复默认
- 日志设置
- 滚动缓冲区与历史缓冲区大小
- 鼠标滚轮滚动行数
- 自动发送设置
- 快捷发送列表
- 快捷发送分组、折叠状态和窄侧栏顺序
- Hex 显示设置与 RX 原始二进制日志设置
- 最近一次串口连接参数
- 过滤历史
- 过滤标签页状态
- Shell 标签页状态
- 图表标签页解析、系列、显示范围和数据保留配置
- Shell Profiles
- 默认 Shell Profile
- 主输入框设置
- 底部输入框发送历史和保存数量
- 快捷键设置
- 工作区分屏布局
- 日志日期子目录、自动清理周期和手动导出目录
- 匿名活跃统计开关与本地安装标识
- 跳过的更新版本号

## 测试与辅助脚本

仓库中包含用于串口调试/验证的 Python 脚本：

- `test/serial_test.py`
- `test/serial_tester.py`

这些 Python 脚本更适合作为联调辅助工具。项目同时使用 Node.js 内置测试运行器覆盖配置归一化、编码与 Hex 格式化、工作区状态、日志生命周期、关键界面结构和发布工作流，可运行 `npm test` 执行。

## 已知实现特点

- 当前主窗口启用了 `nodeIntegration: true` 且 `contextIsolation: false`
- 项目当前以单串口连接模型为核心，不支持同时连接多个物理串口
- 分屏工作区首版最多支持 2 个 pane
- 过滤、图表与 Shell 标签页恢复的是 UI 和配置状态；Shell 进程会重新创建，图表数据点不会跨重启恢复
- 日志采用内存缓冲和周期刷盘，而不是逐条实时写盘

## 适用场景

- MCU / 开发板串口调试
- AT 指令交互
- 设备日志查看与关键字过滤
- 串口协议开发过程中的快速发送与重复命令测试
- 需要桌面端图形界面的串口联调工具替代方案

## License

MIT