需要 Chromium 内核浏览器（Chrome / Edge 89+），并通过 https:// 或 http://localhost 访问；没有硬件也可以打开左侧「测试」页签，一键开跑合成数据案例。

1 这是什么：把串口助手搬进浏览器

调电机、看编码器、抓 IMU 数据，几乎每个做机器人的人都会长期挂着一个串口调试助手。传统工具是桌面软件：装一次、换台电脑重装一次，画的曲线只能截图，解析规则只能靠记事本抄。这个工具换了个思路——用 Web Serial API 把串口助手做成一个网页，打开即用，解析规则、通道配色、图表布局全部记在配置里，可以导出一份 JSON 带走。

它对齐 Vofa+ 与市面上常见串口助手的基础能力：设备连接与参数配置、手动信号线控制、文本与 HEX 双模式收发、实时数据监视、波形的时域与频域展示、定时轮询与触发应答、预设快捷发送。在此之上补了三件更贴近「做实验」的事：一是时间线录制——把流过的帧录下来，事后回放、导出、复盘；二是面向 AI 的调试回路——一键导出一份自包含的调试包（配置 + 帧结构说明 + 通道统计 + 原始样本 + 失败样本），AI 读完就能给判断，而改完规则的验证靠「用缓存字节重放」完成，不必重烧固件；三是声明式显示——图表的种类、绑定哪几路数据、用什么公式换算、颜色与量程，都由一份 JSON 描述符决定，想加一个新视图不需要改代码。而界面布局本身也是围绕「调试时眼睛在看什么」设计的：串口监视器是绝对主视觉（占主区约 62% 的上半部分），波形带在下方的独立滚动区，中间一条分割线调比例——见下一节的界面分区说明。

整个应用是纯静态文件：没有后端、没有第三方运行时依赖、没有构建步骤，与本站其他页面共用一套离线缓存。它的解析内核、绘图内核、插件系统都是本站自研，源码可读、可改，也自带一份给 AI 读的开发说明（见第 7 节）。

2 能力清单

界面怎么分区的：为什么监视器占主位、波形在下面

打开应用会看到四块区域，划分依据是「调试时眼睛真正盯着什么」——

「主区工具条」上另外放了六个全局动作：全屏主区 / 收起主区 / 重置分割，以及「新图表」下拉 + 添加 / 清空面板 / 清空缓存。每个面板标题栏的六枚小按钮各司其职：主位上是 ⛶ 全屏与 ▭ 收起，工作区里是 ⇱ 移到主位、⇔ 加宽、▾ 收起、✕ 移除。

与常见串口助手的功能对照

3 三步上手

第一步，把设备接上。点「连接设备」，浏览器会弹出一个端口列表（这一步必须由你亲手点，浏览器不允许网页自动打开串口）。选好设备后按你固件的设置调整波特率——默认 115200。如果你用的是 Arduino 或 ESP 系列，打开串口的瞬间 DTR 拉低会让板子复位，工具会显示「复位等待」，等它结束再发指令。手边没有硬件也不要紧：点「进入演示模式」，工具会用合成数据（位置/速度/电流/温度/母线电压五路正弦与噪声信号）走完全部流程，包括发送后的回显，用来验证解析规则刚刚好。

第二步，告诉它数据长什么样。串口来的数据无非两种形态。文本形态最常见，一行里写着键值对，比如 temp=25.3, cur:1.02——这种情况下什么都不用配，工具会自动把出现过的键建成通道，等宽曲线立刻就有。如果是 二进制帧，切到「十六进制」模式：先定义帧结构（帧头 AA55？有没有长度字段？帧尾是什么？有没有校验和？），再逐个字段声明它从第几个字节开始、是什么类型、要不要乘缩放系数。逗号分隔的演示帧结构可以点「套用示例」一键填入，对着改最快；如果你的设备已经在用开源生态的协议，直接点「解析」页签顶上的预设按钮（FireWater / Teleplot / JustFloat / 匿名 V1.0），工具会套好后立刻拿缓存数据重放一遍给你看效果。

第三步，挑一个顺眼的视图。切到「图表」页签（或直接用主区工具条上的「新图表」下拉），从七种渲染器里选一个加到工作区：看趋势用时域折线，查振荡找频域谱，盯一路即时值用仪表盘，看电机电流与位置的相位关系用二维轨迹。加进来的面板是固定高度的，右下角拖一下就能调高；点标题栏的「编辑」绑定它要显示哪几路通道、窗口显示最近多少点、纵轴要不要固定量程、每一路用什么颜色。想换算成更直观的量，就在「映射公式」里写一行算式：(cur*24) 把电流换算成功率，sqrt(ix*ix+iy*iy) 求合成矢量幅值。公式只支持四则运算与白名单数学函数，用通道名当变量，不支持任何脚本执行。

这套配置会自动存在本机浏览器里，下次打开还在原地。要换台电脑、或者分享给同学，去「数据」标签页复制配置，或者干脆导出「面板包」——里面装着图表框布局与通道配色。

4 数据格式说明：把「数据长什么样」一次配对

这一节回答两个最常被问到的问题：默认格式到底是什么？我自己的协议怎么配上去？先说结论——文本数据几乎不用配，二进制帧需要你把帧结构告诉它。配好之后，任何被解析出来的数值字段都会自动成为一路通道，可以直接进时域折线、频域谱、柱状图、仪表盘或表格。

文本格式：键值对，等号冒号都认

每行写一个或多个键值对，分隔符 = 与 : 都识别，数值对之间用逗号或空格分开，后缀数字（temp1 / temp2）会各自成为独立通道，数值支持整数、小数与科学计数法。若设备发的是没有换行的裸流，工具会在 60ms 静默后按一帧处理，不会一直卡着不动。

temp=25.3, cur:1.02
pos:90 vel=12.5
acc1=0.2, acc2=0.3

默认（演示）HEX 帧：共 11 字节

点「套用示例」或进入演示模式时用的就是这一帧。它不是任何标准协议，只是一个「结构完整、便于对照」的示例，你可以照它的形状改成自己的协议：

演示波形由三条互不相同的信号合成：pos = 90·sin(2π·0.5t)、cur = 3.2·sin(2π·0.5t+0.6)、temp = 42 + 3·sin(2π·0.02t)。所以时域上能看到慢变与快变叠加，频域谱上在 0.5Hz 附近有明确峰值——这也正好用来验证频域面板工作是否正常。

自定义 HEX 格式：在「解析」页签逐项配置

1. 打开「解析」页签，模式选「十六进制」。
2. 帧结构：填帧头（如 AA55）、帧尾（如 0D0A）；留空表示不按该方式定界。
3. 长度字段：偏移（相对整帧起始，含帧头）、字节数（0 = 不用，1~4）、含义（载荷长度 / 整帧长度）。
4. 校验：选类型（无 / 累加和8 / 异或8 / 累加和16 / CRC16-Modbus），再填校验起始与结束字节（-1 表示到载荷末尾）。
5. 字段表：点「＋新增字段」，逐个填键名、类型（int8~uint32、float32）、偏移、长度、缩放系数、是否大端。
6. 回「设备」页签点「进入演示模式」——演示数据会按你刚配好的帧结构合成，手边没有硬件也能确认「帧收得齐、字段解得对、通道画得出」。

开源协议预设：四套社区事实标准，一键套用

如果你的设备已经在用某个开源生态的协议，不必从零拼帧结构——「解析」页签顶上有四枚预设按钮，点一下即套用，并且会立刻用缓存里的原始字节按新规则重放一遍，当场看效果（不必让硬件重跑）。套用后仍可手动微调任何一项。

5 发送与录制：把调试过程变成可复盘的材料

定时轮询适合周期性问一个寄存器：填好内容和间隔（最小 20ms），勾上启用即可，工具会用与配置对账的方式管理计时器，改内容或改间隔下一次发送就生效，不用重启。触发应答适合「设备上报某状态，我立刻回一条控制字」的闭环：接收内容里出现你写的匹配词就自动发送应答。这里有一层保护——单条规则 250ms 冷却，自动发送每秒最多 30 次；如果匹配词与应答内容互相包含，工具会限流并提示，避免把串口打满。预设发送是给常用指令准备的：绑一个单字符快捷键（焦点不在输入框时生效），顺手敲一下就把指令发出去；还能填「期望回包」与超时时间，收到就提示往返耗时，超时也会明确告诉你——这比盯着屏幕数秒数靠谱。

调完一轮，最珍贵的往往是中间那段异常数据。录制标签页点「开始录制」，工具会把这期间流过的每一帧（含时间戳、方向、原始 HEX、文本与解析值）存进内存；停止后可以回放——按原始时间关系重新喂给图表，让当时的抖动重演一遍——也可以导出成 JSON 存档、或者粘回另一台机器继续分析。需要长时间留档时，用「数据」标签页导出解析结果 CSV 或原始记录 CSV：CSV 带 UTF-8 BOM，Excel 双击打开中文不乱码。

6 支持与限制：先把这几条看完

另外三条工程限制，用之前知道比踩到再查省事：改口串口参数必须关端口重开——波特率、数据位、停止位、校验、流控都不能热改，工具会自动完成「关闭→重开」，大约四分之一秒内不可发送。开启硬流控后不再手动控制 RTS——两者会打架，工具会自动让出控制权。页面关闭前会主动释放端口——否则下次打开会提示端口被占用，如果你强行关掉标签页导致占用，拔插一次设备即可。

7 面向 AI：它同时是一份可复用的开发基座

这个应用不是一次性页面，而是按「可被复用的基座」写的。它把串口调试这类应用拆成了十四个职责单一的模块，全部挂在同一个命名空间 window.SerialLab 下，模块之间不互相持有引用、只通过事件总线通信：

同时，应用目录里自带三份给 AI 直接读取的文档：llms.txt（速览与关键约定）、AGENTS.md（工程硬约束与协作规则）、skills/html-webserial-app/SKILL.md（从零开发同类应用的完整流程与踩坑清单）。如果你想让 AI 帮你做一件类似的事——做一个网页端 CAN 调试器、一个串口协议分析器，或者在这个应用上加新图表、新发送方式——把这三份文档连同对应模块贴给它，比口头描述快得多。应用内「AI 开发提示词」按钮还提供了一份浓缩版，可一键复制或下载为 txt。

更直接的一条路：让 AI 来读你的现场数据。调试硬件时最费时间的往往不是点按钮，而是「把现在的现象讲清楚」——截图讲不全，复制日志又丢掉了解析上下文。所以这个应用把「给 AI 的输入」做成了一个按钮：「显示」页签里的 「导出 AI 调试包」会生成一份自包含 JSON，里面装着

• 当前配置：串口参数、时间戳口径与全部显示设置、图表框清单——AI 据此知道你是怎么配的，给出的建议不会答非所问；
• 帧结构人话说明：文本模式说明分隔符与数值正则；二进制模式逐项列出帧头、长度字段的位置与含义、每个数据字段的偏移/类型/端序/缩放、校验类型与区间、帧尾；
• 可用预设清单：四套开源协议的名字与结构摘要，让 AI 知道还能换成什么；
• 各通道统计：键名、标签、单位、颜色、精度、计数、末值、极值、均值、极差，以及是否数值恒定（恒定通道常常意味着占位字段或偏移错位）；
• 最近 N 条原始记录：每条都带原始 HEX 与解出的数值，AI 可以据此离线复算；
• 全部失败样本与原因分布：校验和不符、长度越界、未识别出键值对各占多少，附具体帧；
• 一段给 AI 的排查提示：例如「当前未设帧头，长噪声下容易串帧」「文本模式下大量未识别，多半是分隔符或数值正则不符」。

同时会产出一段纯文本摘要并自动复制到剪贴板——不想传文件时直接粘进对话框即可。拿到 AI 给出的规则修改后，回到应用「按当前规则重放缓存」，用缓存里的原始字节重新解一遍就能验证，形成「AI 读数据 → 发现规律 → 改规则 → 当场重放验证」的闭环，不必让硬件重跑。这也是「实时暂停继续」在架构上要配合的一环：运行绿圆标暂停的只是屏幕刷新，数据仍在后台缓冲，所以暂停期间的数据同样能进调试包、同样能被重放。

AI 自动化调试接入：让 AI 直接读串口、跑判据（MCP）

上面两条路（调试包 / 复制提示词）仍需要人做一次「搬运」。V2.2.2 起补上了完全自动的一条：仓库里的 _本地工具/serial-bridge 是一个本地串口桥（Node.js + serialport），它直接 require 本应用的 9 个真源模块复用同一份解析内核——桥解析出的通道值与网页端逐字节一致，不存在两套实现各算各的。桥已封装为 MCP server（Model Context Protocol），接入后任何支持 MCP 的 AI 会话都能直接调用五个工具：

三步接入（详细命令与参数见 _本地工具/serial-bridge/README.md）：

• ① 安装：进 _本地工具/serial-bridge 执行 npm install（Node 18+，仅本地工具目录有依赖，站点本体仍是零依赖）；
• ② 在 AI 工具的 MCP 配置里加一个 server：{"command": "node", "args": ["<仓库根>/_本地工具/serial-bridge/bridge.mjs", "mcp"]}，路径换成你自己的仓库位置；
• ③ 在对话里直接说「读一下串口」「用 FireWater 预设采 3 秒」「断言 x>0.5」即可。

除了 MCP，还有两条不依赖任何协议的通路：浏览器持续落盘（应用内勾选「持续写入本地文件」，NDJSON 逐行追加，AI 拿文件路径就能读）与 HTTP 收件箱（勾选「HTTP 上报」+ 运行 python _本地工具/serial-inbox.py，数据实时落到 latest.brief.txt 等文件）。AI 拿到导出的数据文件后，可以像操作普通文件一样下载、diff 两轮数据、甚至帮你 git 提交上传 GitHub——这些都不需要额外权限，走的就是普通文件系统。隐私边界：串口数据只在你的本机流转，桥与收件箱没有任何上传代码；AI 能读到什么，取决于你让它读哪个文件。

8 常见问题速查