基于 C++17、Qt 6 Widgets 和 FluentQtWidgets 的跨平台串口调试工具。
English · 简体中文 · 官网 · 下载 · 变更记录 · 贡献指南 · Code signing policy
Fluent 串口助手提供现代 Fluent 风格的串口终端,覆盖连接、收发、显示、协议解析、绘图、自动化和导出等常用调试流程,支持 Windows、macOS 和 Linux。

![]() 终端工作台:多标签会话、日志着色和流量统计 |
![]() 曲线窗口:按协议提取字段并实时绘图 |
![]() 帧协议编辑器:字节结构、字段和校验一目了然 |
![]() 数据表格:按帧查看 HEX、文本和校验结果 |
![]() 协议解析:按地址查看三个设备的实时字段,并在同一张图上比较曲线 |
|
在 Releases 下载对应平台的安装包,每个安装包都附带 .sha256 校验文件。
| 平台 | 安装包 | 说明 |
|---|---|---|
| Windows x64 | FluentSerialAssistant-X.Y.Z-windows-x64-setup.exe |
安装程序,需要管理员权限,默认安装到 Program Files |
| macOS(Apple 芯片和 Intel) | FluentSerialAssistant-X.Y.Z-macos-universal.dmg |
打开后把应用拖到“应用程序”文件夹 |
| Linux x64 / arm64 | FluentSerialAssistant-X.Y.Z-linux-{x64,arm64}.deb |
sudo apt install ./FluentSerialAssistant-X.Y.Z-linux-x64.deb |
macOS 版本未经 Apple 公证,首次打开被系统阻止时,请在“系统设置 → 隐私与安全性”中点击“仍要打开”。安装后的更新可在应用内完成,见应用内更新。
- 扫描串口并显示端口名、描述、厂商、VID/PID 和序列号;支持常用及扩展波特率、数据位、校验位、停止位、流控、RTS 和 DTR。
- 文本或 HEX 发送,可选 None、CR、LF、CRLF 行结束符;接收和发送可分别选择 UTF-8、GBK、ASCII、Latin1 编码。
- 毫秒级循环发送、最近 20 条发送历史,以及按块大小和间隔分块发送文件。
- 多标签会话:每个标签独立连接一个串口,新标签复制当前配置。
- 内置虚拟串口对:开启后两个会话可分别连接
VIRTUAL-A和VIRTUAL-B互相收发,无需安装驱动。
- 终端支持文本、HEX、混合显示,时间戳、自动滚动和暂停显示,发送记录可自定义颜色,并实时统计收发总量、速率和连接时长。
- 自动断帧:按接收间隔、帧头、帧尾或固定长度分割记录。
- 终端搜索:关键字或正则、区分大小写、高亮跳转,并可只看接收或发送记录。
- 内容着色:内置 ESP-IDF、日志等级、成功与失败、AT 指令响应等预设,也可按关键词或正则自定义颜色。
- 曲线窗口:同时打开多个独立窗口,支持全部数字、分隔值、键值对、JSON 和二进制字段,可预览样例、筛选字段;通道列表显示最新值,可独立设置倍率、偏移和显隐,并暂停、清空或导出 CSV。
- 数据表格:按帧查看时间、方向、来源、长度、HEX、文本和校验结果,支持排序、过滤、复制,并可定位回终端记录。
- 帧协议模板:在可视化编辑器中定义帧头、长度、命令、载荷、校验和帧尾,校验可从指定偏移开始计算,用样例或最新接收帧检查解析结果;启用后接收记录会标注命令和校验状态。
- 协议解析窗口:在模板中定义载荷字段和设备地址,直接查看实时数值,勾选字段即可在同一张图上比较不同设备、不同模板的曲线。
- 校验工具:CRC16-Modbus、CRC16-CCITT、CRC32、LRC、XOR、SUM8,可手动计算或在发送时自动追加;可跳过开头和末尾的字节(如帧头、帧尾),校验码插在末尾跳过的字节和换行符之前。
- Modbus RTU:生成常用读写请求、自动追加 CRC,并解析响应摘要。
- 常用包:分组、备注、启用/停用、批量发送、排序和 JSON 导入导出。
- 宏命令:多步骤发送、步骤延时、等待文本或 HEX 响应、循环运行、失败中止,并导出 CSV 结果。
- 自动应答:按文本、HEX 或正则匹配,立即或延时发送应答,并在记录中标记来源。
- 脚本插件:内置 JavaScript 运行器,通过受控的
serialAPI 收发数据、读取记录和写日志。 - AI 控制:通过本地 IPC、CLI 和 MCP 服务复用 GUI 当前会话,见 AI、CLI 与 MCP 控制。
- 会话记录导出为 TXT、CSV 或 BIN。
- 自动日志按 TXT、CSV、BIN 记录收发数据,文件名包含时间、串口名和波特率,可按单文件大小滚动。
- 将接收的原始数据保存到文件。
- 浅色、深色、跟随系统主题和自定义主题色;界面字体、终端等宽字体、字号和自定义字体导入。
- Windows 11 上可开启云母效果。
- 简体中文和 English 无需重启即可切换。
- 恢复上次的串口参数、发送内容、常用包、宏命令、自动应答规则和文件发送参数,可选启动后自动连接;侧栏卡片记住折叠状态。
- 配置保存在系统标准的用户配置目录,不写入 Windows 注册表;升级时自动迁移旧版安装目录中的配置。
- 选择串口并设置波特率、数据位、校验位、停止位和流控,点击“连接”。
- 在终端查看收发记录;需要时开启时间戳、自动断帧或切换 HEX 显示。
- 在发送区输入文本或 HEX,选择行结束符和编码后发送;可勾选校验自动追加或循环发送。
- 点击终端工具栏的曲线图标,确认解析设置即可新建曲线窗口;当前协议模板已定义数据字段时,会直接带入模板和字段。
- 在左侧“协议模板”中点击“编辑协议”定义帧格式和载荷字段,保存后勾选“启用”,直接打开数据与曲线解析窗口。
- 用常用包、宏命令、自动应答或脚本插件把重复操作自动化。
- 点击终端工具栏最左侧的扫把按钮,同时清空终端和收发计数;用 TXT、CSV、BIN 导出记录。
- 点击“编辑协议”,在“字段解析”区域按 1 / 2 / 4 / 8 B 或 Float32 / Float64 添加数据字段;字段按整帧字节顺序排列,同一行显示类型、整帧位置、原始 HEX、解析值和状态。选中一行后,在固定的右侧属性区设置名称、载荷内起点、数值类型、字节序、倍率和加值;右侧“模板设置”常驻显示,集中提供新建、切换、保存和删除操作;下方通过字段选择框配置帧头、长度、设备地址、命令、校验和帧尾。 可上下拖动数据字段调整顺序,载荷偏移随之更新。字段值按“原始值 × 倍率 + 加值”换算,保存后生效。字节图始终显示,字段列表的色块和 HEX 底色与字节图对应;点击字节图或列表中的字段可联动查看属性;新建或切换到没有保存样例的模板、修改协议配置时,会自动生成匹配样例,并重算长度和校验;也可直接粘贴 HEX 或使用“最新接收”分析实际数据;这类样例在修改名称、倍率等配置时保留原始字节,清空样例后继续编辑可恢复自动生成。样例缺少数据时明确显示缺失字节数。
- 同一总线上有多个设备时,设置地址字节数和地址在整帧中的偏移,解析窗口会按地址的 HEX 字节分组;不区分地址时选择“不区分设备地址”。同一个模板最多定义 32 个载荷字段,未定义时按载荷字节显示 CH1、CH2 等。
- 勾选左侧协议模板的“启用”即可打开解析窗口;关闭窗口后可点击“解析数据与曲线”再次打开,沿用当前协议和曲线勾选。需要解析多种帧格式时,在窗口中勾选多个模板。
- 列表显示各设备字段的当前值和更新时间,勾选“曲线”即可绘制,共用以秒为单位的时间轴。点击窗口顶部“配置”可收起或展开左侧模板与字段列表,收起后继续采集和绘图,并显示图例以区分设备曲线。窗口最多显示 256 个数据字段,同时绘制 32 条曲线;曲线保留最近 12,000 个点。关闭后再次打开或重启应用会保留曲线勾选。
- 暂停、隐藏、最小化或关闭窗口时停止采集;清空后保留字段和勾选,更改参与解析的模板或保存模板修改后清空历史。校验失败的帧不更新数值,缺少的字段显示“—”。原始串口流按模板长度字段或固定载荷长度重组分批接收的数据;没有长度信息时,请在接收设置中先配置断帧。已断帧的数据块会跳过长度越界的残缺候选,继续解析后续帧;原始流仍等待声明长度,避免误切载荷中的帧头。
- 每次确认都会新建一个独立窗口,可同时打开多个窗口分别绘制不同字段;窗口左上角的按钮显示当前协议,点击可修改解析设置。
- 用文本或 HEX 样例预览解析结果;二进制字段可配置类型、字节偏移、大小端、比例和偏移,并从完整帧或协议模板载荷中取数。
- 协议编辑器中的“创建曲线”直接带入当前模板、字段和样例;终端工具栏也会优先使用当前已配置数据字段的模板。模板模式共用字段定义、收帧与校验逻辑,按设备地址分别绘图,可通过“编辑协议”返回编辑器。保存同名模板后,关联曲线同步字段并清空旧数据,开始重新采样。
- 点击工具栏的“通道数据”可展开或隐藏右侧面板,隐藏后曲线占满空间,数据接收和通道设置继续保留。列表显示各通道的颜色和最新值,勾选通道控制曲线显隐;拖动中间分隔条可调整列表宽度。
- “通道设置”默认收起,点击可单独展开或隐藏。选中通道后设置倍率和偏移,按“显示值 = 解析值 × 倍率 + 偏移”同步更新已有曲线、新数据和 CSV 导出;解析值保留,可用“重置当前通道”恢复。二进制字段先应用解析设置中的比例和加值,再应用这里的倍率和偏移。
- 每个窗口的通道设置独立,清空数据后按通道名称保留;更换解析配置或载荷模板后重置,关闭窗口后不保留。
- 窗口只绘制打开期间收到的数据,隐藏、最小化或关闭期间的数据不会补绘;最多显示 32 个通道。
- 打开“设置”,开启“内置虚拟串口对”。
- 在两个会话中分别选择
VIRTUAL-A和VIRTUAL-B并连接;端口列表未更新时点击刷新。 - 在任一端发送数据,另一端即可收到;也可配合自动应答规则测试请求与响应。
虚拟串口对只在同一应用实例内可用,不影响物理串口。它原样转发字节,不模拟波特率和流控;另一端未连接时发送的数据会被丢弃。
- 启动后自动检查更新;没有新版本或无法联网时不弹窗。也可在“设置 → 应用更新”手动检查。
- 发现新版本后先显示版本号和界面语言的更新说明,点击“下载并安装”才开始下载。
- 下载使用 4 路并行连接,显示进度并可随时取消;服务器不支持分段下载时自动改用单连接。
- 文件大小和 SHA-256 校验通过后交给系统安装,必要时会请求权限,应用保存配置后退出。
应用运行时,可通过 fluentserial-cli 或 fluentserial-mcp 控制 GUI 当前会话。GUI 始终是串口唯一的使用者,CLI 和 MCP 通过当前用户私有的本地 IPC 复用它的连接、协议解析、记录和曲线窗口,不会与 GUI 抢占串口。
fluentserial-cli ports
fluentserial-cli status
fluentserial-cli send-hex --hex "01 03 00 00 00 02 C4 0B"
fluentserial-cli records --direction rx --limit 20
fluentserial-cli plot --plot-protocol keyValue --plot-field "free sram" --clearCLI、MCP 需与应用使用同一版本。架构、MCP 客户端配置、全部工具和 IPC 约定见 AI 控制、CLI 与 MCP 文档。
项目以 Git 子模块引入 FluentQtWidgets:
git clone --recursive https://github.com/txp666/FluentSerialAssistant.git
cd FluentSerialAssistant已克隆但没有拉取子模块时:
git submodule update --init --recursive- CMake 3.21+ 和 Ninja
- Qt 6.12,包含 Widgets、SerialPort、Svg、Network、Qml 和 Core5Compat 模块(Qt 安装器中勾选 Qt Serial Port 和 Qt 5 Compatibility Module);与发布工作流
.github/workflows/release.yml中的QT_VERSION一致 - Linux 另需
libgl1-mesa-dev、libxcb-cursor0和libxkbcommon-x11-0
CMakePresets.json 默认使用 C:/Qt/6.12.0/mingw_64 和 C:/Qt/Tools/mingw1310_64,路径不同时请修改预设。
cmake --preset mingw-release
cmake --build --preset mingw-release --parallel
.\build\mingw-release\FluentSerialAssistant.exeDebug 构建使用 mingw-debug 预设。链接时提示 cannot open output file FluentSerialAssistant.exe: Permission denied,通常是旧程序仍在运行。
可以用 aqtinstall 安装 Qt,以 macOS 为例:
pip install aqtinstall
aqt install-qt mac desktop 6.12.0 clang_64 -O ~/Qt -m qtserialport qt5compat
cmake -S . -B build/release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build/release --parallelLinux 把 mac desktop 6.12.0 clang_64 换成 linux desktop 6.12.0 linux_gcc_64。Qt 装在 Qt 安装器或 aqtinstall 的默认位置(~/Qt、C:\Qt)时,CMake 会自动使用其中最新的 Qt 6.12 及以上版本;装在其他位置时,用 -DCMAKE_PREFIX_PATH=<Qt 目录> 指定。
ctest --test-dir build/release --output-on-failure测试默认随项目构建,使用 Qt 的 offscreen 平台运行,不需要显示器或真实串口。
仓库内置 .vscode/tasks.json:Ctrl+Shift+B / Cmd+Shift+B 执行 Debug 构建,F5 构建并启动调试。Windows 下复用 MinGW 预设,macOS 和 Linux 下使用 build/vscode-debug 或 build/vscode-release 目录。
GitHub Actions 只在 GitHub Release 发布时运行。
- 更新
CMakeLists.txt中的版本号、CHANGELOG.md和docs/release-notes/vX.Y.Z.md,并推送到 main。 发布说明直接从正文开始,不写一级标题(Release 页和应用内更新对话框已显示版本号);先写中文,英文放在## English一行之后,应用只显示界面语言对应的部分。 - 在 GitHub 上以
vX.Y.Z为标签和标题发布 Release。 - 工作流先把该 Release 标为预发布,在三个平台上运行测试并构建安装包,并在 Intel Mac 上启动一次 macOS 安装包里的应用;全部校验通过并上传后,再转为正式版并标记为最新。构建失败时它保持预发布,应用内更新不会看到它。
产物包括 Windows x64 安装程序、macOS 通用 DMG(同时含 Apple 芯片和 Intel 版本)、Linux x64/arm64 DEB 及各自的 .sha256 文件。同一个 DMG 还以 macos-arm64.dmg 的名字再发布一份,0.1.24 及更早版本的应用内更新只认这个名字。Windows 发布支持 SignPath Foundation 的免费开源 Authenticode 签名:配置后先签名 FluentSerialAssistant.exe,再构建并签名安装程序,见 SignPath 设置说明。
本地打包可使用 scripts/package_release.ps1(Windows 便携包),三平台安装包的底层脚本为 scripts/package_windows.ps1、scripts/package_unix.sh 和 scripts/create_deb_package.sh。
.
├── .github/workflows/ # Release 测试与打包工作流
├── docs/
│ ├── ai-control.md # AI、CLI 与 MCP 控制说明
│ ├── images/ # README 截图
│ ├── release-notes/ # 各版本发布说明
│ └── signing/ # 代码签名配置说明
├── packaging/
│ ├── linux/ # Linux 桌面入口
│ └── windows/ # Inno Setup 安装程序定义和翻译
├── scripts/ # 打包脚本
├── signing/signpath/ # SignPath 签名产物配置
├── src/
│ ├── app/control/ # 会话控制接口和本地 IPC
│ ├── app/core/ # 协议、校验、绘图解析、编码、更新等通用逻辑
│ ├── app/resources/ # Qt 资源、图标和翻译
│ ├── app/serial/ # 串口封装和内置虚拟串口对
│ ├── app/view/ # 主窗口、设置页、曲线、协议编辑器等界面
│ │ └── workbench/ # 终端工作台,按功能拆分为连接、终端、发送、宏、脚本等文件
│ ├── cli/ # 命令行工具
│ └── mcp/ # MCP stdio 服务
├── tests/ # Qt Test 自动化测试
└── third_party/FluentQtWidgets/
本项目采用 GNU General Public License v3.0 or later,详见 LICENSE。项目依赖的 FluentQtWidgets 同样采用 GPL-3.0-or-later,分发本项目或其派生版本时需遵守 GPL 的源代码开放和再分发要求。
Free code signing is provided by SignPath.io, with a certificate from SignPath Foundation, after the project's open-source application is approved. Team roles, release controls, signed artifact scope, and the privacy statement are documented in the code signing policy and privacy policy.




