usbtracePlus 采集分析
面向嵌入式调试的 usbtracePlus 采集分析工具：从目标板抓取 VCD 波形与 LOG 日志两大类数据，
解码成标准 VCD，做确定性的事实提取与断言检查。
同一套引擎，两种用法：本扩展的图形面板，以及内置的命令行 usbtraceplus
（全命令支持 --json，适合脚本与 AI 自动化）。两者读写同一份配置文件，
面板里设好参数后，命令行未显式指定的选项会自动取配置文件里的值
（子命令本身仍要给出，例如 usbtraceplus capture vcd）。
术语
- usbtracePlus —— 本工具链的统称，涵盖下面两大类。
- VCD —— 波形类。来自 USB trace 字流，解码为标准 VCD 文件。
- LOG —— 日志类。来自接口 0 的 HCI/debug 日志。
文中出现「usbtracePlus」时指整体，「VCD」「LOG」分别指其中一类。
快速开始
装好 Python 3.8+，并确保 python 在 PATH 中
（或用设置 usbtraceplus.pythonPath 指定解释器路径）。
按 Ctrl+Shift+P 运行 usbtracePlus: 自测（不接硬件），输出窗口出现 ALL PASS 即环境正常。
运行 usbtracePlus: 打开工具面板，在面板左侧：
| 要选什么 |
选什么 |
| 文件命名参照 |
一个 bin 文件（只用于命名产物，不要求文件存在） |
| 信号参考文件 |
你的 def.h（决定能解析出哪些信号） |
| 分析规则文件 |
断言规则 spec.json |
再确认**系统时钟频率（MHZ）**与固件一致。
在停止设置 → VCD 把「时长（秒）」设为 3，点 VCD采集。
点 打开 VCD 看波形，点 分析 生成分析报告。
装好插件后会自动弹出分步引导（也可以用命令面板运行 Welcome: Open Walkthrough 找到
「usbtracePlus 快速上手」）。更详细的说明见下方文档。
功能
采集
- VCD 采集 —— 边采边解码为标准 VCD，GTKWave 可直接打开。
默认 4 路并发重叠读可跑满链路（~185 字/ms）；也可用
--decode-after 把解码
完全挪到采集之后（--readers 1 退回旧单读路径）。
- LOG 采集 —— 从 interface 0 读取 HCI/debug 日志，实时解析滚动显示并写文件。
- 两路独立可并行，也可用「联动停止」让一侧停止时带动另一侧。
- 停止方式：VCD = 时间 / task 信号触发；LOG = 时间 / 字符串触发。
两者都支持按钮强制停止，按钮永远最高优先级。
- 时长为 0 表示不限，一直采到点停止。
- 支持未上电等待与断线自动重连；时长从设备首次就绪开始算，
所以「先启动采集、再给设备上电」能采到完整时长（抓启动过程就靠这个）。
分析
- 波形分析 —— 信号/事件统计、周期与抖动、脉冲宽度、多 bit 单调性、
关联 LOG 的标签趋势。确定性事实提取，不做启发式结论，结论留给人或 AI。
- 日志对时刻 —— LOG 记录自带设备 tick，采集收尾时挂到 VCD 时间轴上
（行尾
@t=），可直接和波形的 #<us> 对照，不必再靠主机钟粗对。
对不上的（采集前积压在 USB FIFO 里的那批，其主机时刻是「倒出时刻」而非产生时刻）
留空不猜，并报出可对齐区间。
- 断言检查 —— 按 spec 校验事件是否存在、周期是否达标、时序先后、事件时刻的信号取值。
- LOG 规则检测 —— 8 类可配置规则（关键字、序号跳变、标签缺失、计数上下限、
数值范围、趋势、静默间隔、解析失败）。
自动化
- 内置命令行
usbtraceplus，全命令 --json（stdout 只输出一个 JSON 对象）、退出码统一。
usbtraceplus run 一键跑完 采集 → 分析 → 断言。usbtraceplus schema --json 自描述命令目录。
常见问题
| 症状 |
先查什么 |
| 一直「等待设备上电...」 |
板子是否上电、USB 是否接好、VID/PID 是否对（用 usbtracePlus: 设备信息 确认） |
| 采集到 0 字节 |
设备没被识别到 / 固件没在跑 —— 用 usbtracePlus: 设备信息 确认设备在线，核对 VID/PID |
| 所有时间成比例偏大/偏小 |
系统时钟频率是否与固件配置一致 |
| task 信号下拉框是空的 |
信号参考文件是否还指向内置示例 —— 点「浏览...」选中你自己的 def.h |
| 「打开 VCD」提示文件不存在 |
还没采集过 |
| 改动参数后命令行没生效 |
是否取消了「自动保存」—— 勾回，或点「保存配置」 |
| 提示找不到 Python |
安装 Python 3.8+，或在设置里填 usbtraceplus.pythonPath |
采集与设备枚举仅支持 Windows（通过 usbprint.sys 访问目标板）。
解码、分析、断言、自测跨平台可用。
命令行
装了扩展后，CLI 会被落位到不含版本号的稳定路径，扩展升级后依然有效：
~/.usbtraceplus/usbtraceplus（Windows 为 %USERPROFILE%\.usbtraceplus\usbtraceplus.cmd）。
~/.usbtraceplus/usbtraceplus doctor --json
没配过的话 doctor 会返回 ready: false 并列出 blockers（缺什么、怎么修），
而不是「全部通过」。只做分析不做采集时用 doctor --for analyze。
不确定路径在哪时，运行命令 usbtracePlus: CLI 路径。
从源码仓库开发时也可直接用仓库根的 ./usbtraceplus。
常用命令：
usbtraceplus doctor --json # 自检：ready=true 才表示「可以采集」
usbtraceplus run --seconds 3 --json # 一键：并行采集 → 分析 → 断言
usbtraceplus capture log --stop-string ASSERT --json
usbtraceplus analyze vcd --with-check --json
退出码统一：0 成功 / 1 断言失败 / 4 仅日志规则命中（多为关键词误报）/
2 用法错误 / 3 运行时错误。run 的 summary.verdict 会直接给出结论。
完整命令、参数、输出字段与自动化配方 →
python/CLI.md
文档
装好插件后，点采集面板顶部的 「帮助文档」 按钮即可打开下面两份文档，
也可以从命令面板运行：
| 命令 |
内容 |
usbtracePlus: 使用指南 |
界面详解、操作步骤、产物读法、断言与规则写法、故障排查、设置速查 |
usbtracePlus: 命令行参考 |
全部命令/参数/输出字段、退出码、自动化配方 |
在线版本：
设置
| 设置项 |
说明 |
usbtraceplus.pythonPath |
Python 解释器路径（留空则自动探测 python / python3 / py -3） |
其余参数（时钟频率、VID/PID/设备编号、文件路径、停止方式、联动停止、自动化模式等）
保存在工作区 .vscode/usbtraceplus.json，与命令行共用同一份。
面板上的「自动保存」（默认勾选）会在参数变更时立即写盘；取消勾选时，点「保存配置」
或任意采集/分析操作同样会保存。
目录结构
usbtraceplus / usbtraceplus.cmd 命令行入口（转发到 python/usbtraceplus_cli.py）
python/ Python 引擎（命令行与扩展共用）
usbtraceplus_cli.py 唯一 CLI 入口
cliutil.py 输出信封、退出码、错误模型
usbcapture.py usbtracePlus 采集传输层（VCD + LOG）/ 设备枚举（Windows）
tracevcd.py 字流 → VCD 解码器
logparse.py LOG 包解析
loganalysis.py LOG 事实提取 + 规则引擎
analyze_vcd.py 波形事实提取
vcdcheck/vcdcheck.py 断言引擎
config.py 配置读写、路径解析
src/ VS Code 扩展（TypeScript）
extension.ts commands.ts captureManager.ts configFile.ts cli.ts python.ts
webview/ 面板 UI 与 webview 资源
walkthrough/ 首次安装引导的 markdown
scripts/ 构建脚本
构建（开发）
npm install
npm run compile # tsc 编译 + 复制 Python 脚本/静态资源/文档到 resources/
npm run package # 产出 usbtraceplus-x.x.x.vsix
scripts/copy-assets.js 决定哪些 Python 模块与文档进 .vsix；
新增模块或文档必须同步加进去，否则打包出的扩展会缺文件。resources/ 与 out/ 是构建产物（已 gitignore），每次构建会重建。
