embedded-workflow-cache-init

name	embedded-workflow-cache-init
description	当需要为嵌入式调试、固件刷写或逻辑分析流程初始化项目内 `.agents/cache` 文件时使用，尤其是需要沉淀 `VID/PID`、固件产物、传输协议参数，或在用户已提供逻辑分析仪通道映射和测试方法时初始化 KingstVIS 相关缓存。

初始化嵌入式工作流缓存

工具入口

强制：本 skill 提供以下精确定义的工具，必须直接调用，禁止自行实现替代品。

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

工具	路径	用途
init_embedded_workflow_cache.py	$SKILL_ROOT/scripts/init_embedded_workflow_cache.py	初始化 .agents/cache 下的配置文件
cache-layout.md	$SKILL_ROOT/references/cache-layout.md	缓存文件用途和字段说明

执行缓存初始化时，先提取 $SKILL_ROOT，再用 python "$SKILL_ROOT/scripts/init_embedded_workflow_cache.py" ... 调用。

---

何时使用

• 需要首次为某个项目落盘 .agents/cache/ 下的嵌入式工作流缓存文件。
• 需要为固件刷写流程生成一份可复用的下载配置草稿，再由后续 skill 或人工补齐事实字段。
• 用户已经给出逻辑分析仪通道映射、触发方式或测试方法，需要顺手初始化 KingstVIS 时序经验文件与映射文件。
• 需要把零散的设备识别、固件信息、协议参数先收口为项目内可维护的缓存，而不是散落在对话里。

不适用

• 已经能从仓库中确定完整刷写参数，且目标是直接探测、分包或刷写。此时优先使用 repo-firmware-flasher。
• 已经有完整的逻辑分析仪抓取命令，只差实际抓波形。此时优先使用 kingstvis-socket。
• 只做一次性说明，不需要在仓库内落盘缓存。

核心工作流

1. 先读 references/cache-layout.md，确认要初始化哪些缓存文件。
2. 先到仓库代码里搜索设备识别与枚举事实，至少确认 boot 和应用两套枚举信息：
   • VID/PID、传输类型、设备路径或 FriendlyName 线索
   • bootloader 模式 / 升级模式的枚举信息
   • 应用态 / 正常运行态的枚举信息
   • 若仓库里存在枚举代码、设备路径匹配逻辑或 USB 标识宏，优先以代码事实为准
3. 再结合用户提供的信息拆分两类事实：
   • 固件刷写事实：目标名、VID/PID、传输类型、固件路径、分包和 ACK 规则
   • 逻辑分析事实：测试方法、测试用例、触发方式、通道映射、建议窗口
4. 运行脚本初始化缓存：

python agents\skills\embedded-workflow-cache-init\scripts\init_embedded_workflow_cache.py --project-root . --target <target-name>

5. 如果只有固件刷写信息，就只创建：
   • .agents/cache/<target-name>_download.cfg
6. 如果用户还提供了逻辑分析仪相关映射或测试方法，再额外创建或补充：
   • .agents/cache/logic_timing_windows.csv
   • .agents/cache/kingstvis_channel_maps.json
7. 生成后快速检查文件是否已落盘，并确认 boot / 应用枚举字段和占位字段没有伪造事实。

执行要求

• 初始化下载缓存前，必须先从仓库代码中查出 boot 和应用两套设备枚举信息；不能只写其中一种状态。
• 没有事实支撑时，字段保留为空或占位值，不要猜 VID/PID、ACK、命令字。
• 查到 boot 和应用枚举信息后，应分别写入缓存；至少保证后续 skill 能区分“升级态设备”和“应用态设备”。
• 下载缓存要兼容后续刷写与 USB 工具的真实读取口径：
  • [firmware] 中写 firmware 与 artifact_path
  • [firmware] 中写 header_size、chunk_size、crc_type
  • [usb_comm] 中补齐最小默认字段
  • [serial] 中补齐串口默认参数
• 配置文件要放在项目内 .agents/cache/，不要写到 skill 目录里。
• logic_timing_windows.csv 只在用户提供测试方法、测试用例或建议抓取窗口时初始化。
• kingstvis_channel_maps.json 只在用户提供了逻辑分析仪通道/引脚映射时创建或更新。
• 如果缓存已存在，优先保留现有内容；仅补齐缺失文件或新增缺失条目。

参考

• references/cache-layout.md：缓存文件用途、字段说明和最小示例。
• scripts/init_embedded_workflow_cache.py：初始化 .agents/cache 文件的入口脚本。