一个基于 Electron 的桌面串口终端工具,面向嵌入式开发、串口调试、设备联调、日志查看与关键字过滤场景。当前版本已支持主串口终端、过滤标签页、实时图表标签页、分屏工作区、Shell 标签页、多标签独立日志、多语言和在线更新。
当前代码使用配置 schema v11。仓库根目录
package.json保留开发占位版本,正式发布时由v*Tag 在 CI 中同步版本号。
Serial Terminal 使用 Electron 构建桌面应用,串口通信基于 serialport,终端显示基于 xterm.js。应用以单串口调试为核心,在同一主界面中集成:
- 主串口终端
- 多个过滤标签页
- 实时串口数据图表标签页
- 最多 2 个 pane 的分屏工作区
- 系统 Shell 标签页
- 左侧侧边栏工具区
- 左侧边栏支持收起为窄工具栏,顶部显示 RX/TX 实时速率,底部保留展开、连接/断开、清空日志、设置、输入栏和 Shell 栏快捷按钮;展开状态下可用相邻小按钮一键清空主终端及全部过滤 Log 标签页,设置中可选择是否同步清空 Shell,默认关闭;折叠状态会自动恢复
- 右侧 Shell 侧边栏
- 独立设置窗口
适合用于 MCU、模组、工业设备、AT 指令、协议联调与日志筛选分析等场景。
- 自动枚举本机串口并支持手动刷新
- 支持标准波特率,并可将自定义正整数波特率永久添加到下拉菜单,重启后直接复用
- 支持数据位、停止位、校验位配置
- 支持接收/发送换行模式切换:
CRLF / LF / CR - RX 显示模式和文本编码位于串口设置区;TX 文本编码也在此设置。底部输入框独立保存
Text / Hex模式和追加 CRLF 状态,快捷指令则各自保存模式和追加选项 - 连接后自动保存最近一次串口参数,便于下次恢复
- 主终端支持像普通终端一样直接键入并逐键发送到串口
- 基于
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 条、可配置为 0-200 条;支持复用、置顶和删除,置顶项不因普通历史超限而被淘汰
- 支持直接在主终端输入并发送串口数据
- 支持底部主输入框发送
- 主输入框支持:
- 发送按钮
- 将当前输入加入快捷发送
- 历史命令记录和下拉菜单
- 上下键切换历史命令
- 按回车发送开关
- 发送后输入框内容不会自动清空
- 底部输入框会保存最近发送历史,默认 20 条;历史菜单可点击条目替换当前输入内容,保存数量可在设置窗口调整,达到上限时自动删除最老条目
- TX 文本编码由串口设置区统一提供;底部输入框保存自身的 Text/Hex 模式和追加 CRLF 选项,快捷指令保存各自的模式和追加选项。主终端与右键粘贴/发送选区始终按 Text 发送,主终端 Enter 只服从换行模式
- Text/Hex 切换时底部输入分别保留当前会话内的草稿
- 保留左侧 Text 自动发送能力,可配置内容和时间间隔;TX 文本编码变化时会重新校验并安全重启
- 支持快捷发送列表
- 每条快捷发送保存稳定 ID、标签、内容、独立的
Text / Hex模式和可选自动触发设置,支持新增、编辑、删除、拖动排序;手动发送和自动触发都使用该指令自身的模式 - 快捷发送支持自定义分组、组内排序、跨组移动、分组折叠、重命名和删除;删除分组会同时删除组内指令及对应的窄侧栏快捷入口
- 每条快捷发送可在编辑窗口单独启用自动触发,匹配文本支持正则、大小写匹配和全字匹配;默认关闭,开启后串口新接收内容按接收编码解码并匹配,命中后自动发送对应快捷指令
- 自动触发命中时,对应快捷发送按钮会以绿色闪烁提示
- 展开和收起侧栏共享快捷发送内容,但分别保存各自的排列顺序;收起侧栏可为快捷按钮配置文字和颜色
- 设置窗口提供“快捷键”页,可查看、修改或恢复默认快捷键
- 默认快捷键包括:
Ctrl+Enter:发送底部输入框Alt+H:打开/关闭发送历史菜单Alt+Up / Alt+Down:切换发送历史Ctrl+F:聚焦搜索Ctrl+L:清空当前活动终端Ctrl+R:刷新串口列表Ctrl+Shift+D:连接/断开串口
- 搜索快捷键会自动展开左侧边栏并切换到搜索页
- 搜索快捷键在 Log 终端获得焦点时仍然有效,并优先搜索当前活动终端中的选中文本
- RX 显示配置与各发送入口的模式互相独立。例如 RX 可查看 Hex dump,同时底部输入或快捷指令仍可按 UTF-8 文本发送。
- Text 发送会按当前 TX 文本编码生成原始字节;对端串口工具必须使用相同编码显示,否则中文等非 ASCII 文本会乱码。排查时可让对端切到 Hex 显示:
中文在 UTF-8 下应为E4 B8 AD E6 96 87,在 GBK 下应为D6 D0 CE C4。 - Hex 发送请使用底部输入框或模式设为 Hex 的快捷指令;自动发送和主终端直接输入均为 Text。主终端粘贴或右键发送选区也按 Text 处理。
- Hex 输入支持连续字节或使用空格、Tab、换行、逗号、冒号、连字符分隔,也支持两位字节的
0x前缀和小写字母。例如AA5501FF、AA 55 01 FF、0xAA,0x55、aa:55-01。 - Hex 校验是严格的:空输入、非法字符、奇数个数字、非两位的
0xtoken 和超限载荷不会发送。底部输入或快捷指令启用追加选项后,Hex 模式追加真实字节0D 0A,Text 模式追加 CRLF。 - RX Hex dump 默认每行 16 字节,显示 8 位偏移与 ASCII 预览;不可打印字节显示为
.。每行字节数、偏移、ASCII、大小写和残余行空闲刷新时间可在设置窗口调整。 - Hex 搜索作用于终端中显示的偏移、字节和 ASCII 文本。过滤标签页创建时固定为当时的 RX 模式;模式不一致时暂停接收,Hex 正则/普通过滤作用于格式化后的单行文本。
- 支持在工作区中新建系统 Shell 标签页
- 每个 Shell 标签页对应独立的
node-pty会话 - 支持在两个 pane 中创建、切换、移动、关闭 Shell 标签页
- 右侧 Shell 侧边栏提供独立快捷指令列表,可新增、编辑、删除并持久化;点击后发送到当前活动 Shell 标签页,可选择是否自动追加 Enter 执行
- 支持自定义 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 和关闭标签页
- 可配置终端字体、字号、前景色、背景色
- 可配置终端字体字重
- 可选择 PNG、JPEG 或 WebP 作为终端壁纸,并设置 0-100% 暗色遮罩;路径无效时回退到纯色背景
- 可配置时间戳颜色和行号颜色
- 可配置搜索结果、过滤命中和终端选区的前景色与背景色
- 支持多条关键词高亮规则
- 设置窗口的“高亮”页可单独将高亮规则恢复为默认配置,不会重置外观、日志、串口等其它设置
- 每条高亮规则支持:
- 启用 / 禁用
- 颜色
- 大小写控制
- 正则模式
- 支持系统字体列表选择
- 支持鼠标滚轮滚动行数配置
- 支持“发送文本内容后自动滚动到底部”开关,默认开启
- 支持自动记录串口/终端数据
- 支持自定义日志目录、文件名格式和编码
- 日志在内存中缓冲,达到配置阈值或每 5 秒静默刷盘,并在断开连接、关闭标签页或退出前写入文件
- 支持将串口 Log 标签页日志分别保存到独立文件;Shell 标签页自动保存由独立开关控制,默认关闭
- 日志文件名格式支持:
%Y %m %d %H %M %S%tab(标签页标题,仅多标签日志场景)
- 主终端和过滤标签页可分别写入独立日志文件;开启 Shell 日志保存后,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 - 应用启动时自动检查更新
- 支持手动检查更新
- 更新不会静默下载或在退出时自动安装,下载和安装都需要用户明确确认
- 发现新版本时支持:
- 立即更新
- 暂不更新
- 跳过此版本
- 下载完成后支持重启安装或稍后安装
- Windows 新版客户端优先请求
https://trigger-cn.top/serialterminal/latest.yml,并附带当前版本和稳定渠道;服务端按管理后台中的启用策略选择实际更新源。Linux 客户端直接使用 GitHub Release 的latest-linux.yml - 动态入口不可用时,Windows 客户端按 Gitee、腾讯云 COS、GitHub Release 的顺序检查外部元数据;元数据请求均限制为 5 秒和 512 KiB,安装包下载失败后仅在版本和 SHA-512 均一致时切换来源
- 稳定渠道拒绝预发布版本;严格 SemVer 预发布 Tag 只发布版本化 COS 元数据,不覆盖稳定的
releases/latest/latest.yml https://trigger-cn.top/serialterminal/api/v1/update-source固定指向动态入口,继续兼容仍使用更新源发现的客户端- 未附带版本和渠道的旧客户端只使用后台标记为“旧客户端”的策略;部署期间必须保留一条启用的旧客户端策略
- 更新提示会尝试显示 Gitee Release 正文;获取不到时提示网络异常
- 使用
electron-builder打包 Windows 与 Linux 发布物 - 推送
v*Git tag 后,GitHub Actions 会使用同一 lockfile 并行构建 Windows/Linux 发布物;构建前执行测试和 native rebuild,构建后校验 lockfile 未变化 - 发布 Tag 必须是无 build metadata 的严格 SemVer(例如
v0.4.0或v0.4.0-preview.1),并遵守 npm SemVer 的长度和安全整数限制 - GitHub Release 正文会自动列出上一个 tag 到当前 tag 之间的提交,每个提交只出现一次,不按提交类型分类
- 发布任务先将 Windows/Linux 安装包和原始更新元数据上传到 GitHub draft Release;COS 发布脚本基于原始元数据在内存中生成 COS URL,仅上传
releases/<tag>/版本化对象且不得修改dist/latest.yml。COS 版本化对象通过版本、大小和 SHA-512 校验后,再次逐项校验 GitHub 资产并发布 draft。稳定版此时成为 GitHub latest,预发布版不会抢占 latest - 同一 Tag 的 GitHub、COS 和 Gitee 资产视为不可变内容:重试只复用名称、大小和 SHA-512 完全一致的远端资产,发现多余、重复或内容变化的资产会在覆盖或更新 Release 正文前终止
- GitHub Actions 仅向 COS 上传 Windows 自动更新必需的
.exe、.exe.blockmap和latest.yml;Linux 产物只保留在 GitHub Release - GitHub Release 和 COS 版本化对象验证成功后,GitHub Actions 将发布提交和不可变 Tag 同步到 Gitee,并等待 Gitee Tag 流水线创建 Release;主工作流最多轮询 15 分钟,重新公开下载并校验 Gitee 的
.exe、.exe.blockmap和latest.yml .workflow/gitee-release.yml由严格 SemVer 版本 Tag 触发,完整镜像 Windows.exe、.exe.blockmap和latest.yml;三类资产均优先从 COS 版本化对象下载并在失败时回退 GitHub,避免 Gitee 运行器无法访问 github.com 资产时连元数据都取不到;元数据因各镜像 URL 形式不同不按字节大小校验,镜像前后均按latest.yml校验安装包版本、大小和 SHA-512- Gitee 已存在附件的校验下载最多跟随三次重定向,且只允许
gitee.com及其子域名;下载请求不携带 Release API 令牌 - Gitee Go 流水线需要配置加密变量
CI_GITEE_ACCESS_TOKEN,流水线会将其映射为发布脚本读取的GITEE_ACCESS_TOKEN;令牌需具备该仓库 Release 创建、更新和附件上传权限,企业流水线可复用同一条镜像命令 - 仅当 GitHub、COS 版本化对象和 Gitee 公开下载全部验证成功后,稳定版才通过独立
--promote-latest操作更新releases/latest/latest.yml,随后再次回读验证;预发布版本永不切换稳定 latest。最后按语义版本分别保留最新三个稳定版本和最新三个预发布版本,并保护当前稳定 latest 引用的版本。COS 发布身份需具备列举桶对象和批量删除对象权限
.
├─ 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 导出
├─ search-history.js 搜索历史归一化、置顶、淘汰和删除
├─ 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 功能实施状态、测试矩阵与未完成项
├─ CHART_TAB_IMPLEMENTATION_PLAN.md 图表设计基线、实施状态与验收标准
├─ package.json 依赖、脚本与打包配置
└─ README.md 项目说明
README.md:面向用户和贡献者的当前功能、运行与发布说明。agent_notes.md:维护者接手入口,记录当前架构、不变量和高风险区域。ToDo.md:全仓库仍需执行的工程待办与验证基线。HEX_FEATURE_TODO.md:Hex 功能的历史实施记录和剩余实机测试矩阵。CHART_TAB_IMPLEMENTATION_PLAN.md:图表页设计基线、当前落地映射和剩余性能/交互验证。telemetry-server/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
- 由于项目依赖原生模块,首次安装通常需要本机具备编译环境
建议安装 Visual Studio Build Tools(C++ workload)。
建议安装 build-essential 与 python3。
npm install安装后会自动执行 electron-builder install-app-deps,用于处理 Electron 原生依赖。
npm startnpm run rebuildnpm run distnpm run dist:winnpm run dist:linux正式发版时推送 v* tag,GitHub Actions 会自动生成版本说明并创建 GitHub Release。应用更新提示优先读取线上 Release 正文。
程序运行时会在用户数据目录中生成配置文件:
- 配置文件:
config.json - 默认日志目录:用户文档目录下的
SerialTerminalLogs - 应用诊断日志:用户数据目录下的
logs - 本地崩溃转储:用户数据目录下的
crash-dumps
当前配置主要包括:
- 外观设置
- 终端壁纸路径和暗色遮罩
- 高亮规则
- 高亮规则可在设置窗口单独恢复默认
- 日志设置
- 滚动缓冲区与历史缓冲区大小
- 鼠标滚轮滚动行数
- 发送文本后自动滚动到底部开关(默认开启)
- 自动发送设置
- 快捷发送列表
- 快捷发送分组、折叠状态和窄侧栏顺序
- Shell 快捷指令列表及 Enter 追加选项
- Hex 显示设置与 RX 原始二进制日志设置
- 最近一次串口连接参数
- 过滤历史
- 搜索历史及保存数量
- 过滤标签页状态
- Shell 标签页状态
- 图表标签页解析、系列、显示范围和数据保留配置
- Shell Profiles
- 默认 Shell Profile
- 主输入框设置
- 底部输入框发送历史和保存数量
- 快捷键设置
- 工作区分屏布局
- 日志日期子目录、自动清理周期和手动导出目录
- 匿名活跃统计开关与本地安装标识
- 跳过的更新版本号
仓库中包含用于串口调试/验证的 Python 脚本:
test/serial_test.pytest/serial_tester.py
这些 Python 脚本更适合作为联调辅助工具。项目同时使用 Node.js 内置测试运行器覆盖配置归一化、编码与 Hex 格式化、工作区状态、日志生命周期、关键界面结构和发布工作流,可运行 npm test 执行。
npm test 会通过 scripts/run-tests.js 运行根项目 Node 测试及 telemetry-server 测试。真实串口字节一致性、长时间高吞吐、Linux 打包和完整桌面交互仍属于发布前人工验证范围。
- 当前主窗口启用了
nodeIntegration: true且contextIsolation: false - 项目当前以单串口连接模型为核心,不支持同时连接多个物理串口
- 分屏工作区首版最多支持 2 个 pane
- 过滤、图表与 Shell 标签页恢复的是 UI 和配置状态;Shell 进程会重新创建,图表数据点不会跨重启恢复
- 日志采用内存缓冲和周期刷盘,而不是逐条实时写盘
- MCU / 开发板串口调试
- AT 指令交互
- 设备日志查看与关键字过滤
- 串口协议开发过程中的快速发送与重复命令测试
- 需要桌面端图形界面的串口联调工具替代方案
MIT
