# Embedded Debug Workflow

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

- Skill: `docevilock/embedded-debug-workflow` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add docevilock/embedded-debug-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/docevilock/embedded-debug-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: docevilock (https://skillmd.com/u/docevilock)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/docevilock/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`