多会话浏览器串口调试助手

1. 背景与目标

本项目基于 Web Serial API 的纯前端串口调试工具，聚焦"多会话"、"增强发送"、"模板拼包"和"轻量易用"的使用体验。核心诉求是：无需安装、直接在支持浏览器里完成设备串口的连接、收发、校验、模板化造帧及会话管理。index.html 的页头显式提示仅支持支持 Web Serial 的 Chrome/Edge，且需 HTTPS 或 localhost 环境访问，保证浏览器权限模型与安全要求满足运行约束。

2. 系统总体设计

2.1 运行环境与约束

运行环境：桌面端 Chrome/Edge 89+；必须在 HTTPS 或 localhost 打开。该约束在 UI 警示条中已提示。
依赖：仅依赖浏览器自带的 Web Serial 与 Web 平台能力，无第三方库。主脚本 app.js 使用原生 ES 语法与模块化风格（IIFE 封装）。
许可：页脚标注 MIT 许可，作者为 Mark。

2.2 文件结构

index.html：页面结构与模板、上下文菜单（右键）定义。
app.js：业务逻辑与状态管理（Session 类、多会话、串口读写、模板系统、校验算法、右键/拖拽、统计）。
styles.css：暗色风格 UI、栅格布局、分栏、拖拽态、响应式样式。

3. 架构设计

整体采用"三层划分 "：UI 结构（HTML） + 表现（CSS） + 逻辑（JS） 。JS 以 Session 为核心对象，负责单会话的串口生命周期、收发与 UI 绑定；外部有会话列表与标签栏（Tabs）管理，实现多会话激活、复制、关闭与拖拽重排。

3.1 模块划分

串口会话（Session）：封装连接、断开、读取循环、发送（文本/HEX/文件/定时）、信号线（DTR/RTS/CTS/DSR）、统计定时器与 UI 同步。
校验与编码库：SUM8/16、CRC16（XMODEM/IBM/MODBUS）、CRC32（IEEE）与大小端组帧；HEX 文本互转与空格格式化。
模板系统：默认模板 + 用户模板（localStorage 持久化），支持字段类型 const/var/payload/len/crc，len 支持 of=payload/sofar 与 add 偏置，crc 支持指定端序与参与范围。
多会话/标签栏管理：创建、激活、复制、关闭、重命名（F2/右键）、拖拽排序，支持"并列显示 + 列数控制"。
UI/交互：Toolbar 控件、终端视图、滚动与时间戳、本地回显、日志导出、ARIA 标签等。

4. 关键流程设计

4.1 串口连接生命周期

连接：navigator.serial.requestPort() → port.open(options) → 获取 writer、初始化统计、启动 readLoop()。UI 上禁用波特率等参数并显示"已连接"。
读取循环：在 readLoop() 中持续 reader.read()，将 value 累加到 RX 计数与速率窗口，并调用 appendRx() 写入终端视图。
断开/清理：cleanupPort() 负责 reader.cancel()/releaseLock()、writer.releaseLock()、port.close()，并停掉统计/自动发送等定时器。
设备物理断开：监听 navigator.serial.disconnect，若当前会话占用该端口则 UI 提示并按需"自动重连"。

4.2 数据接收与呈现

视图支持 HEX/文本 两种显示；可选 时间戳 、自动滚动。appendRx() 负责格式化与滚动控制。

4.3 数据发送路径

即时发送：回车或按钮触发 sendFromInput()，先通过 buildPayloadFromInput() 构造最终字节流：文本/HEX →（可选）EOL →（可选）校验尾（SUM/CRC，端序可选）→（可选）EOL；同时支持"本地回显"。
自动发送：勾选后以 setInterval() 周期从输入框构帧并写串口。间隔可配置（ms）。
文件发送：选择文件后按 4096B 分片写入串口，防止一次性写入过大阻塞 UI。

4.4 模板拼包（结构化造帧）

默认模板（示例）：例如 AA55 + LEN(payload,2,BE) + CMD + PAYLOAD + CRC16/MODBUS(LE, sofar)；55AA + CMD + PAYLOAD + SUM8(payload)；7E + LEN(sofar,2,LE,add=4) + PAYLOAD + CRC32(sofar)。
字段类型 ：
- const 固定字节（HEX）；
- var（如 cmd）来自 UI 的十六进制输入；
- payload 来自发送输入框（文本或 HEX）；
- len 对 payload 或 sofar 长度取值，支持 1/2/4 字节与端序、偏置；
- crc 对 payload 或 sofar 计算校验并按端序写尾。
使用方式 ：
- "应用模板发送"直接构帧并写串口；
- "仅构建→输入框(HEX)"把结果放入发送输入框便于二次编辑或留存。
持久化：用户模板存放于 localStorage 键 ws_serial_templates_v1，支持新增/删除，默认模板不可删除。

4.5 多会话与布局

多会话：支持创建命名页、复制会话（继承串口参数）、关闭前确认（如已连接）。激活会话后，单页模式仅显示该会话面板。
并列显示：勾选"并列显示"后，sessions 容器切换为 grid，列数可选 1/2/3，适配宽屏多串口并行观测。
拖拽排序：可对标签与会话面板进行拖拽，按落点重新排序并重渲染，支持开启/关闭拖拽模式。

4.6 右键菜单与重命名

标签右键可"重命名/关闭/复制"，也支持 F2 内联重命名输入，失焦或回车提交，Esc 取消。

4.7 统计与日志

每秒刷新 RX/TX 字节计数、即时速率与连接时长；接收窗口可一键清空与导出 .txt。

5. 数据结构与接口

5.1 Session.state

复制代码

{
  port, reader, writer, connectedAt,
  rxBytes, txBytes, rxBytesWindow,
  rxRateTimer, autoSendTimer, readLoopRunning
}

上述字段驱动会话内部的 I/O、统计与定时器控制。

5.2 模板 JSON Schema（轻量）

name: string
fields: Array<Field>
Field.type ∈ {const|var|payload|len|crc}
len: { of: 'payload'|'sofar', size:1|2|4, endian:'be'|'le', add?:number }
crc: { algo:'sum8'|'sum16'|'crc16_xmodem'|'crc16_ibm'|'crc16_modbus'|'crc32', endian:'be'|'le', of:'payload'|'sofar' }
var: 示例 { name:'cmd' }，来源于 UI 的 HEX 输入。

以上定义由 buildByTemplate() 解释执行。

5.3 本地存储

键名：ws_serial_templates_v1；值为用户模板数组 JSON。

6. UI/UX 设计

终端视图：等宽字体、深色主题、滚动承载大量文本与 HEX；按钮分组、表单禁用态与状态文本明确。
辅助能力 ：
- 接收：时间戳、自动滚动、清空、保存；
- 发送：本地回显、EOL（none/\n/\r\n）、HEX 自动插空、校验预览（随输入即时更新）。
可及性：部分控件附带 aria-label 与语义化标签结构。
响应式：宽屏两栏栅格；窄屏下改为单列，以媒体查询控制。

7. 可靠性与错误处理

连接异常：connect() 捕获异常并更新状态栏；tryReconnect() 失败亦提示。
读取异常：readLoop() 捕获 read 错误并安全释放 reader 锁。
HEX 校验：奇数长度立即报错或不计算预览；模板保存 JSON 解析失败以 alert 反馈。
关闭确认：若会话已连接，关闭前弹窗确认断开。

8. 性能与安全

性能：

读循环保守解码，避免 UI 阻塞；
文件发送按 4096B 分片写，兼顾吞吐与流畅度；
统计定时器 1s 刷新，减少频繁 DOM 更新。

安全：

仅在 HTTPS/localhost 运行；
使用浏览器的端口权限选择器与信号 API，不越权访问；
无后端与第三方依赖，避免数据泄漏。

9. 测试建议

连接稳定性：插拔设备、串口占用冲突、参数变更后重连。
接收渲染：大数据流（如 921600bps）下的滚动与速率统计、不丢字符与时戳正确。
发送正确性：文本/HEX、EOL 组合、大小端 CRC/SUM 尾部值与预览一致；自动发送间隔边界（1ms/大于 1s）。
模板造帧：三套默认模板与用户模板（含 len(of=sofar/payload, add)、crc(of=payload/sofar)）覆盖多路径。
会话管理：复制继承参数、重命名/F2、关闭确认、拖拽排序后会话/标签同步。
持久化：刷新页面后用户模板仍可见、默认模板不可删除。
兼容性：在未支持浏览器中显示"功能不可用"提示。

10. 扩展规划

协议解码插件：为常见自定义协议提供解析器（基于模板 + 解码回调），在接收端分层显示字段。可在 Session 内部新增"解析管线"接口。
更灵活的端口发现/自动重连：记录最近端口与过滤 VID/PID，结合 getPorts() 多端口策略。
历史命令与脚本：发送历史记忆、脚本宏（循环、延时、条件）。
更丰富的波特率与参数预设：扩展速率下拉或支持自定义输入。
多格式导出：接收日志导出 CSV/PCAP（自定义链路层）或二进制 Raw。
UI 细节：会话搜索、颜色主题切换、快捷键地图与国际化。

11. 约束与兼容性

浏览器限制：仅桌面端 Chromium 系；Safari/Firefox 目前不适配 Web Serial。工具在不兼容环境下会给出显式提醒。
串口权限：依赖浏览器原生弹窗授权；无法在后台静默获取。

12. 部署与版本

部署：静态站点即可（HTTPS），将三文件放置服务器；index.html 直接引用 app.js 与 styles.css。
版本识别：建议在页脚或状态处追加 version 字样，并对默认模板变更维护 JSON 版本号。

13. 结论

该工具以 Session 面向对象 的轻量架构，覆盖了嵌入式日常调试 90% 以上的高频场景：多会话并行、灵活的发送造帧与校验、便捷的右键与拖拽操作，并在纯前端形态下实现了良好的可移植性与运维成本极简化。后续如叠加"协议解码插件化"与"脚本化自动化"，可进一步提升到车规/量产测试的半自动或自动化能力。

附：代码亮点清单

CRC/SUM 算法全自给，端序可选，预览与尾部写入一致，降低"造帧-验证"心智负担。
模板系统语义清晰（const/var/payload/len/crc），len(of=payload/sofar, add) 很贴合实际协议。
文件分片发送（4096B）+ 自动发送（ms 级）+ 本地回显，覆盖工程常见场景。
多会话复制与拖拽排序，结合并列显示（1/2/3 列），更像"调试工作台"。
无第三方依赖，静态托管即可部署；MIT 许可。