embedded-debug-workflow

# 嵌入式调试闭环 ## 工具入口 > **强制**：本 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`