serial-debugger — 跨平台串口调试工具 v0.8.0

👋 欢迎使用 serial-debugger！如果它帮到了您，欢迎 Star；遇到问题请提交 Issue，有改进想法欢迎 Pull Request，任何反馈都是对我们的支持。

基于 Go + Wails v2 的跨平台串口调试工具：串口扫描与连接、文本/Hex 双模收发、定时自动发送、端口转发、设备探测、多标签页与历史持久化，一个工具覆盖串口调试全流程。

架构亮点

3 管道 IPC + 共享内存：daemon/resp/sub 命名管道承载控制与事件订阅；共享内存环形缓冲区承载数据（历史 5 MB/进程、发送队列 1 MB/进程），发送走共享内存、IPC 仅触发。
守护进程 + 多客户端：GUI / CLI / MCP 统一接入同一守护进程，ProcessManager 管理 idle/connected 状态与 single/forward 模式；心跳 5 s 一次，连续 3 次失败判定断连。
解码引擎 Go 化：Go 端 per-tab goroutine 逐字节容错解码，产出 []Segment 分段结构；前端纯 DOM 渲染（零 innerHTML），解码与渲染彻底解耦。

快速使用

📦 下载：最新构建产物见 Releases（GitHub Actions 自动构建，解压即用；Windows 需已安装 WebView2 Runtime）。

⚠️ 使用须知

安全：本工具当前无安全相关设计（无认证、加密、访问控制等），仅限在受信任的本地环境使用，请勿用于安全敏感场景——详见安全说明。

翻译：界面多语言由 AI 辅助翻译，可能存在不准确之处，欢迎提交修正——详见国际化。

GUI

启动 serial-gui.exe（自动拉起守护进程）。
点击「扫描」选择目标串口（如 COM3），设置波特率等参数，点击「打开」。
在发送区输入数据，切换文本 / Hex 模式后点击「发送」；接收区实时回显。

CLI

serial-cli start                # 启动守护进程
serial-cli ports                # 列出可用串口
serial-cli open COM3 115200     # 打开串口
serial-cli send "AT\r\n"        # 发送文本
serial-cli status               # 查看守护进程状态
serial-cli shutdown             # 关闭守护进程

不带参数进入交互 REPL，输入 help 查看全部命令；完整命令速查见 CLI 速查表。

MCP

serial-mcp.exe 作为 MCP 服务端通过 stdio 提供 JSON-RPC 2.0 接口，可接入支持 MCP 协议的客户端。

组成

可执行文件	说明
`serial-daemon.exe`	守护进程，单实例（互斥体），ProcessManager 管理 idle/connected 双状态 + single/forward 双模式
`serial-gui.exe`	Wails v2 桌面客户端，多标签页，3 管道持久连接，纯事件驱动
`serial-cli.exe`	命令行工具，交互 REPL + 一次性命令，34 条命令（含 help）
`serial-mcp.exe`	MCP 协议工具，JSON-RPC 2.0 over stdio，28 个工具

架构一览

graph LR
    subgraph 客户端
        GUI[serial-gui 桌面端]
        CLI[serial-cli 命令行]
        MCP[serial-mcp MCP 服务]
    end
    subgraph 守护进程 serial-daemon
        IPC[3 管道 IPC<br/>daemon / resp / sub]
        PM[ProcessManager<br/>进程状态机]
        RB[(共享内存<br/>历史 5MB / 发送队列 1MB)]
    end
    GUI <-->|请求 / 响应 / 事件订阅| IPC
    CLI <-->|3 管道或 CallOnce| IPC
    MCP <-->|3 管道或 CallOnce| IPC
    IPC --> PM
    PM --> RB

数据走共享内存（发送队列），IPC 承载控制与事件。历史上曾规划「客户端直接映射共享内存读取历史」，但该路径从未接通（ringbuf.OpenSharedRing 无调用点，且它只映射只读视图、返回对象上的读操作会写 tail，按原设计调用会崩），历史读取实际全部走 IPC 的 session.history。详见「已知限制」。

功能特性

串口核心

进程生命周期管理：idle ↔ connected 状态机，端口双向映射去重，显式销毁，断连保留
双模显示/发送（文本/Hex），独立缓冲区，单键切换
串口切换：连接中直接切换到其他端口，保留进程和历史
端口转发：绑定双串口双向透传，方向以 P1/P2 独立显示和统计
设备端口探测：TOML 规则配置，3 种匹配模式（substring / regex / modbus_crc），自动跳过已连接端口
流控支持：None / RTS/CTS / XON/XOFF

数据路径

发送走共享内存（1 MB/进程），IPC 仅触发
守护进程内置自动发送引擎：单条模式 + 多条目队列模式，运行中可修改
共享内存环形缓冲区（5 MB/进程），历史读取经 IPC 的 session.history（Snapshot 语义，读不消费；带 limit/beforeTsMs/sameTsSkip 可分页取，界面默认只取最新一页、往上翻时按 5000 条回补）
历史持久化双写：环形缓冲区 + 磁盘文件同步追加
环形缓冲区写满时挤掉最旧的包（保留最新的一段），不会停止记录

事件系统

订阅式推送：rx / tx / 1 / 2 / send-error / ports-changed / process-changed / daemon-shutdown / stats-count / stats-rate / clients-changed / multistr-changed
统计拆分：count（变化推送）+ rate（每秒推送），速率 ≥80% 橙色、≥90% 红色
订阅后立即推送当前状态

主题与外观

颜色主题：文件驱动 + _modes 声明（dark/light 双模式），三段式色值（common/dark/light），CSS 全变量化，外部主题自动发现
图标主题：内置 config/icons/system/（20 个 SVG），外部 themes/icons/<名称>/ 文件夹格式，_fallback 回退
数据高亮自定义：单端口 10 项 + 端口转发 9 项独立颜色设置，深浅色独立/统一，集成调色板（RGBA 滑块 + EyeDropper + 预设色板）
响应式设置页：800 px 断点，宽屏左右分栏，窄屏导航悬浮覆盖层；搜索框内嵌图标
模糊渐变条：config-bar / send-controls / settings-header / 转发按键栏统一透明 + 渐变模糊

前端架构

纯组件化标签页，index.html 仅保留 4 个结构元素，其余 JS 动态构建
TabPage 独立 DOM 子树 + show/hide/destroy 生命周期，per-tab 完整状态
设置页独立标签页，侧边栏导航 + 气泡卡片布局
Go 端 per-tab goroutine 解码，产 []Segment 分段结构；JS renderSegments() 纯 DOM 渲染，零 innerHTML
空格和 CR/LF 可视化为标记（· / ← / ↵），user-select: none 保证剪贴板原样拷贝
CSS 架构分层：o- 布局 / c- 组件 / t- 皮肤 / is- 状态

国际化

9 种语言（zh / en / ja / zh-Hant / ko / ar / ru / fr / es），含阿拉伯语 RTL
外部 i18n 文件覆盖内置翻译，_font 字段绑定语言首选字体

翻译说明：多语言翻译由 AI 辅助生成，可能存在不准确、遗漏或语境偏差，欢迎提交修正（内置文件见 config/i18n/，外部覆盖见上方「配置」表）。

连接管理

双层断连检测：管道断裂即时检测 + 心跳兜底（5 s ping，连续 3 次失败判定断连）
状态栏三色气泡实时显示 GUI/CLI/MCP 连接数
JS 侧 _connecting 互斥防重连风暴，Go 侧锁区合并 + 身份校验

安装与构建

下载

获取对应平台的构建产物压缩包，解压即用。Windows 需系统已安装 WebView2 Runtime。

从源码构建

# 在仓库根目录执行
go build -ldflags="-s -w" -o build/bin/serial-daemon.exe ./daemon/
go build -ldflags="-s -w" -o build/bin/serial-cli.exe    ./cmd/serial-cli/
go build -ldflags="-s -w" -o build/bin/serial-mcp.exe    ./cmd/serial-mcp/
wails build -devtools  # GUI，产物在 build/bin/

💡 仅需命令行工具时（无需 GUI），可直接用 go install 安装：
go install github.com/nienieai/serial-debugger/cmd/serial-cli@latest
go install github.com/nienieai/serial-debugger/cmd/serial-mcp@latest
go install github.com/nienieai/serial-debugger/daemon@latest
GUI（serial-gui）需 Wails 环境（wails build），完整构建矩阵见 BUILD.md。

版本号统一维护在 version/version.go，改一处全部可执行文件同步。仓库已配置 GitHub Actions 自动构建：推送 v* 标签或手动触发即可产出各平台二进制并发布 Release。

CLI 命令（34 条，含 help）

类别	命令
守护进程	`start` `check` `status` `shutdown`
端口	`ports` `refresh` `probe [ports...] [--config]`
进程	`create` `declare` `open` `connect` `disconnect` `close` `switch` `setmode` `forward`
数据	`send [--hex]` `stats` `history`
自动发送	`autosend start/stop/status/interval` `sendqueue`
多字符串	`multistr save/load/reload/status`
历史	`history-files` `history-search` `history-enable` `history-status` `history-attach` `history-new` `history-detach`
诊断	`sessions` `monitor` `threads` `goroutines`
其他	`help`

MCP 工具（28 个）

serial_start_daemon serial_list_ports serial_refresh_ports serial_create serial_open serial_connect serial_disconnect serial_switch serial_forward_create serial_declare serial_set_mode serial_close serial_send serial_sessions serial_history serial_status serial_monitor serial_shutdown serial_stats serial_port_watch serial_autosend_start serial_autosend_stop serial_autosend_status serial_sendqueue serial_multistr_save serial_multistr_load serial_multistr_status serial_probe_ports

配置

位置	说明
`config/probe.toml`	设备探测规则（substring / regex / modbus_crc）
`config/themes/`	颜色主题（`system.json` 内置，`_modes` 声明模式）
`config/icons/system/`	内置图标主题（20 个 SVG + `icons.json`）
`config/i18n/`	内置翻译（9 语言）
`themes/icons/<名称>/`	外部图标主题（文件夹 = 主题，`_fallback` 回退）
外部 i18n 文件	覆盖内置翻译，`_font` 字段绑定语言首选字体

文档

文档	说明
框架文档	架构设计、IPC 协议、进程生命周期、时序图
需求文档	需求列表与实现状态
构建文档	环境要求、构建矩阵、产物说明
待办与已知问题	待实现功能、已知问题、版本完成记录
版本历史	0.1.0 ～ 0.8.0 各版本的变更、根因与验收方法
布局规则	前端布局与 CSS 约束
贡献指南	提交规范、翻译贡献、行为准则
第三方许可	依赖许可证清单（MIT/BSD/Apache/ISC）
CLI 速查表	常用命令速查与示例

版本历史

当前版本 v0.8.0（稳定基线）。最近三版：

版本	要点
0.8.0	把 0.7.5.1 ～ 0.7.5.10 的修复整体收口为稳定基线；不含功能改动（源码与 0.7.5.10 的差别只有版本号）
0.7.5.10	补 `serial-cli sendone [processId] [--raw]`，让「多字符串条目剥头」那条修复可黑盒验收
0.7.5.9	修复「开串口时多建一个进程 / 多出一个标签页」的真因：自动建会话把自己的 `sessionId` 清掉

完整历史（0.1.0 起，含每个版本的根因分析、实测数据与验收方法）见 CHANGELOG.md。

⚠️ 安全说明

本工具当前无安全相关设计：不包含认证、授权、加密、访问控制或审计日志等安全机制；串口收发内容与历史记录以明文形式处理与存储。仅限在受信任的本地环境使用，请勿在不可信网络或安全敏感场景中部署。

贡献与许可

本项目基于 MIT License 开源，欢迎社区贡献——见贡献指南。
AI 辅助声明：本项目在开发与文档维护过程中使用了 AI Agent 工具辅助（代码生成与审计、文档润色、多语言翻译等）；文档与翻译内容由 AI 辅助产出，可能存在错误或不准确之处，欢迎指正与贡献修正。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
build		build
client		client
cmd		cmd
config		config
contract		contract
daemon		daemon
decode		decode
frontend		frontend
pipe		pipe
protocol		protocol
ringbuf		ringbuf
version		version
.gitattributes		.gitattributes
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
BUILD.md		BUILD.md
CHANGELOG.md		CHANGELOG.md
CLI-CHEATSHEET.md		CLI-CHEATSHEET.md
CONTRIBUTING.md		CONTRIBUTING.md
LAYOUT-RULES.md		LAYOUT-RULES.md
LICENSE		LICENSE
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
TODO.md		TODO.md
app.go		app.go
docs-style-guide.md		docs-style-guide.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
platform_other.go		platform_other.go
platform_windows.go		platform_windows.go
settings.go		settings.go
wails.json		wails.json

Navigation Menu

Repository navigation

About

Repository files navigation

serial-debugger — 跨平台串口调试工具 v0.8.0

快速使用

GUI

CLI

MCP

组成

架构一览

功能特性

串口核心

数据路径

事件系统

主题与外观

前端架构

国际化

连接管理

安装与构建

下载

从源码构建

CLI 命令（34 条，含 help）

MCP 工具（28 个）

配置

文档

版本历史

⚠️ 安全说明

贡献与许可

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

serial-debugger — 跨平台串口调试工具 v0.8.0

快速使用

GUI

CLI

MCP

组成

架构一览

功能特性

串口核心

数据路径

事件系统

主题与外观

前端架构

国际化

连接管理

安装与构建

下载

从源码构建

CLI 命令（34 条，含 help）

MCP 工具（28 个）

配置

文档

版本历史

⚠️ 安全说明

贡献与许可

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages