embedded-debug-workflow

name	embedded-debug-workflow
description	当需要按“改代码、编译刷写、串口抓日志、可选 USB 触发、检查日志与回传”这一闭环流程联调整个嵌入式设备行为时使用。

嵌入式调试闭环

工具入口

强制：本 skill 提供编排脚本，配套 skill 各有独立工具。必须加载并调用对应 skill 的工具，禁止自行实现任何替代品。

$SKILL_ROOT = <本 skill 加载输出中 "Base directory for this skill:" 行的路径>

工具	路径	用途
debug_orchestrator.py	$SKILL_ROOT/scripts/debug_orchestrator.py	编排构建、刷写、串口、USB 触发全流程

配套 skill 工具速查

步骤	应加载的 skill	应调用的工具
刷写固件	repo-firmware-flasher	$REPO_FIRMWARE_ROOT/scripts/repo_flash.py
串口日志	serial-log-debug	$SERIAL_LOG_ROOT/serial_tool.py
USB 触发	repo-usb-communicator	$REPO_USB_ROOT/scripts/repo_usb_comm.py
逻辑分析仪	kingstvis-socket	$KINGSTVIS_ROOT/scripts/kingstvis_socket_client.py

每步开始前，先 skill 加载对应配套 skill，从其加载输出的 Base directory 行提取该 skill 的根目录，再调用工具。

---

何时使用

• 需要围绕一次真实设备现象做完整联调，而不是只改代码或只看日志。
• 需要把“代码修改 -> 固件构建 -> 刷写 -> 启动日志抓取 -> 外部触发 -> 结果判定”串成一条稳定流程。
• 需要复用现有仓库型 USB skill、固件刷写 skill 和串口日志 skill，而不是临时手写零散命令。
• 需要把关键证据统一落到 artifacts/，便于复盘。

不适用

• 只做纯静态代码分析，不接设备。
• 只做独立串口收发，不涉及代码修改和固件更新。
• 只做量产、批量刷机或产测工站流程。

核心工作流

1. 先明确本轮调试目标：
   • 要观察的现象
   • 预期日志或预期行为
   • 是否需要外部指令触发
2. 修改代码：
   • 只做最小必要逻辑改动
   • 补充精炼日志，日志只保留关键状态、耗时、分支和错误
   • 性能/耗时测试默认优先走日志埋点
   • 只有用户明确要求且已提供 IO 引脚映射时，才允许通过拉高/拉低 IO 标记点位，再结合 KingstVIS 计算时间间隔
   • 若使用 IO 打点，起点、终点和异常分支附近必须同步补串口日志，至少能对齐“开始、结束、异常/超时”三类事件
3. 编译固件：
   • 优先使用仓库已有构建命令
   • 若构建失败，先修构建问题，不进入后续设备步骤
4. 刷写固件：
   • 使用 repo-firmware-flasher
   • 先确认构建产物、设备识别参数和协议参数来自仓库事实，不硬编码猜测
5. 开启串口日志抓取：
   • 使用 serial-log-debug
   • 先启动抓取，再做上电、重启或后续触发，避免漏首段日志
   • 同时保留原始字节流和可读日志
6. 如需触发动作：
   • 使用 repo-usb-communicator
   • 先根据仓库代码或已有配置确认设备参数、路径线索和报文格式
   • 每次只发一条指令；必须等当前指令完成响应、超时或结果判定后，才能发下一条
   • 默认严禁并行、批量、交错或多通道同时发指令，除非用户明确要求并接受风险
   • 再发送文本或十六进制指令，并按需读取响应
7. 判定结果：
   • 对照预期检查串口日志、USB 回传、状态切换和关键时间点
   • 若本轮使用 IO 打点，必须同时检查逻辑分析仪 CSV、串口日志和触发记录能否相互对齐
   • 若串口有“开始”但 CSV 无起始沿，或串口有“结束/异常”但 CSV 未覆盖到对应沿，本次抓取视为证据不足
   • 若串口显示流程仍在继续，而逻辑分析仪采样已结束，本次抓取视为窗口过短，需要放宽后重抓
   • 只基于真实证据判断“符合预期 / 不符合预期 / 证据不足”
   • 若现象只在已刷写固件上出现，默认不要把 GDB 当主手段；优先用串口日志、USB 回传、IO 打点和板级证据定位
8. 整理证据：
   • 构建命令与结果
   • 刷写命令与结果
   • 串口日志路径
   • 逻辑分析仪原始工程或导出 CSV 路径
   • USB 发送/响应记录
   • 本轮采用的逻辑分析仪抓取窗口、是否发生漏抓、调整后的建议窗口
   • 本轮结论与残余风险

执行顺序要求

• 任何可能触发复位、重启、重新枚举或短时关键日志的动作之前，必须先开串口抓取；刷写和 USB 测试都不例外。
• 需要依赖新代码行为时，必须先完成编译和刷写，不能拿旧固件继续判断。
• 需要 USB 触发时，不要跳过仓库事实检查直接猜设备参数或报文。
• USB 指令必须串行：发送一条，观察一条，记录一条，再进入下一条；默认禁止并行发送，除非用户明确要求并接受风险。
• 性能/耗时测试默认走日志测量；只有用户明确要求且已提供可用 IO 引脚映射时，才切到 IO 打点方案。
• 任何一步失败，都先收敛到失败点，不要并行堆动作掩盖问题。

证据要求

• 所有关键输出优先落到 artifacts/
• 至少保留以下证据：
  • 构建命令与通过/失败结果
  • 实际刷写使用的固件文件
  • 串口原始日志与可读日志
  • 逻辑分析仪抓取配置、原始工程或导出 CSV
  • USB 收发记录
  • 若有 IO 打点，需有一份串口日志与 CSV 的对齐判定结论
  • 最终结论和未覆盖项

逻辑分析仪窗口经验文件

• 当本轮启用 IO 打点 + 逻辑分析仪抓波形方案时，必须维护项目内持久化经验文件 .agents/cache/logic_timing_windows.csv。
• 这份文件用于沉淀同类测试的窗口经验，避免后续重复把抓取窗口设得过短或过长。
• 若文件不存在，先创建再写入；后续同类测试优先读取旧记录，再决定本轮初始窗口。
• 至少记录以下字段：
  • test_method
  • test_file
  • test_case
  • trigger_mode
  • io_mapping
  • expected_window_sec
  • actual_window_sec
  • captured_complete
  • too_short
  • too_long
  • recommended_next_window_sec
  • notes
• 字段含义要求：
  • test_method：测试手段，如 USB 指令、上电、按键、异常注入
  • test_file：本轮对应的测试文件、脚本、固件模块或日志入口文件
  • test_case：具体测试用例名
  • expected_window_sec：抓取前预估窗口
  • actual_window_sec：本轮实际配置窗口
  • recommended_next_window_sec：复盘后建议下次同类测试默认采用的窗口

IO 打点补充要求

• 仅在用户明确要求做 IO 电平打点且已提供可用引脚映射时启用。
• 打点代码必须保持最小化，只覆盖要测的关键区间，不要顺手给无关路径加点位。
• 启用前先查 .agents/cache/logic_timing_windows.csv 是否已有相同 test_method + test_file + test_case 的历史记录；若有，优先用其 recommended_next_window_sec 作为本轮初始窗口。
• 每个关键点位建议同时输出一条短日志，至少包含点位名称或阶段名、成功/失败/超时分支、可用于串口侧排序的上下文标识。
• 抓取完成后，不要只看波形时长，必须做一次“三证合一”核对：串口日志是否完整、CSV 是否覆盖起止沿、触发记录是否与时间顺序一致。
• 收尾时必须回写 .agents/cache/logic_timing_windows.csv，把本轮窗口是否过短、是否过长、以及下次建议窗口沉淀下来。

抓取窗口判定规则

• 满足以下任一情况，判定为“可能漏抓”，不得直接下结论：
  • 串口日志已打印流程开始，但 CSV 中没有起始沿
  • 串口日志已打印流程结束、失败或超时，但 CSV 中没有结束沿
  • 波形中出现孤立起始沿或孤立结束沿，无法和串口日志配对
• 满足以下任一情况，判定为“抓取窗口过短”，应扩大窗口后重抓：
  • 串口日志显示流程仍在继续，而 CSV 已到文件结尾
  • 串口日志进入异常恢复、重试、超时分支，但 CSV 未覆盖这些阶段
  • 本次波形只覆盖主路径，未覆盖本轮实际发生的错误路径
• 建议先以“预期总耗时的 3 倍或 1 秒（二者取大）”作为首次窗口，再根据串口日志和 CSV 对齐结果回收或放宽。

抓取窗口建议表

测试手段	测试用例	触发方式	建议逻辑分析仪窗口	判定依据
仅启动日志联调	上电/复位后观察初始化打点	上电、复位、刷写后自动重启	1s ~ 3s	需覆盖首条启动日志到最后一条初始化完成/失败日志
USB 单条指令功能验证	单条命令触发一次完整业务流程	串口先开抓，再发 1 条 USB 指令	预期流程耗时 3 倍起步，且不少于 1s	CSV 起止沿需与串口中的“命令进入/流程结束”对齐
慢路径/超时路径验证	人为制造超时、重试、异常恢复	发 1 条触发指令或插入异常条件	超时时间 + 1s ~ 3s 余量	必须覆盖超时日志、恢复日志和最终结束沿
人工交互触发	按键、插拔、外设响应等非精确触发	先开串口和逻辑分析仪，再做人工动作	人工动作最长等待时间 + 3s	要覆盖人工动作前后和设备真实响应完成点
连续多轮同用例复测	相同用例重复执行并只比较单轮时长	每轮严格串行触发	单轮完整流程时长 + 30% 余量	每轮都要单独留完整起止沿，禁止把多轮混成一段难以对齐的大窗口

表头说明：

• 测试手段：本轮采用的外部刺激或观测方式
• 测试用例：要验证的具体路径，必须写到主路径/异常路径粒度
• 触发方式：如何让设备进入该路径，要求能复现
• 建议逻辑分析仪窗口：首次建议值，后续可根据真实串口日志和 CSV 微调
• 判定依据：本类窗口是否足够的最低判断标准

配套技能

• repo-firmware-flasher
  • 用于从仓库中提取刷写事实、生成配置并执行探测/检查/刷写
• serial-log-debug
  • 用于本地串口监听、抓取、落盘和初步日志判读
• kingstvis-socket
  • 用于在用户明确要求且已给出 IO 引脚映射时，通过 IO 电平变化标记关键点位并抓取波形计算时间间隔
  • 抓取前应先读取 .agents/cache/logic_timing_windows.csv 中的历史窗口经验，再决定本轮初始抓取窗口
• repo-usb-communicator
  • 用于从仓库中提取 USB 设备识别和通信事实，并执行命令发送或请求响应
  • 默认按单条指令串行发送，不得自行扩展成并发发送流程
• debug-locate-assistant
  • 用于主机可调试二进制、测试程序或 host core dump 的精确定位
  • 不用于已刷写到目标板上的固件默认定位；该场景优先走串口日志/板级证据/逻辑分析仪

编排脚本

• scripts/debug_orchestrator.py
  • 用于把构建、刷写、串口状态会话和可选 USB 触发串成一次执行
  • 不要假设其他 skill 固定放在某个仓库目录；如目录布局不固定，优先显式传入依赖脚本路径
  • 串口阶段使用 open -> status/read-new -> stop 的状态驱动模式
  • 适合 AI 按轮次检查新增日志，再决定是否继续等待、触发动作或结束
  • 默认只编排单次 USB 触发；若要多次发指令，也必须按“单条发送 -> 等待结果 -> 记录证据 -> 再发下一条”的串行方式执行
  • 支持 wait-text、usb-after-text、stop-after-text 这类关键字驱动条件

结果标准

• 成功：
  • 已完成代码修改、编译、刷写、日志抓取以及必要触发
  • 有足够证据说明现象是否符合预期
• need-info：
  • 缺少端口、设备、构建产物、协议参数或预期判定标准
• blocked：
  • 构建失败、刷写失败、串口无法独占打开、设备无响应或关键依赖缺失

工具使用验证（收尾必做）

在声称本轮调试完成前，必须逐一核实以下项：

1. 刷写步骤是否使用了 repo-firmware-flasher 提供的 scripts/repo_flash.py
2. 串口日志抓取是否使用了 serial-log-debug 提供的 serial_tool.py
3. 如需 USB 触发，是否使用了 repo-usb-communicator 提供的 scripts/repo_usb_comm.py
4. 如需 IO 打点/逻辑分析仪，是否使用了 kingstvis-socket 提供的 scripts/kingstvis_socket_client.py
5. 上述任一工具是否被 New-Item/Set-Content/手写脚本替代
6. 若任一工具被自造替代 → 本轮结果无效，需回退重做

参考

• repo-firmware-flasher
• serial-log-debug
• repo-usb-communicator