Windows Download Tool

VSCode 插件：稳定调用 Cmd_download_tool.exe 下载并运行固件，是「AI 全自动化编程」的关键一环。

• 手动：点开活动栏图标 / 状态栏进入配置界面，首次填入参数（含工具路径，可自由选择）。
• 自动：参数落盘后，AI（Claude Code）通过独立 CLI 免填参直接调用 windows-download-tool download <bin>。

功能

• 下载前枚举 USB 设备：all 命令枚举，按目标 PID（默认 pid_8266）定位 Device ID，并显示设备信息。
• 下载流程（对齐 SDK build_flash.sh）：lf 0 0(解锁) → wf -i(写 Flash，校验 Download OK) → rst -f(复位运行)。
• 命令第一个参数默认用枚举出的 Device ID（标准工具接口），每步前重新枚举（MCU 复位会触发 USB 重枚举、ID 重排）。 若你把 Cmd_download_tool 改成了按 USB PID 解析，把配置项 prefixMode 设为 usbPid，前缀改用 PID 的十六进制值。
• 配置按工程隔离：每个工程目录一份配置，切工程不用重配（见「配置层级」）。
• 命令行测试：配置界面里直接添加 / 排序 / 单条或顺序执行任意工具命令，用于手动验证下载工具（见「手动命令行测试」）。
• 复位目标、列出设备、配置界面（WebView）+ 独立 CLI。

工具与硬件

• 工具：release_v5.9.5/config/Cmd_download_tool.exe（标准命令行格式 <Device ID> <CHIP> <命令> [参数]）。
• 芯片：TL751X 等；目标板 USB PID：pid_8266（不同板子可改）。
• 例外：若工具被改成按 USB PID 解析（非默认），第一个参数改为 PID 的十六进制值（见「手动命令行测试」）。

首次配置

方式一：配置界面（推荐）

1. 左侧活动栏点「Windows Download」图标，或状态栏 $(flame) Windows 下载。
2. 填工具路径（「浏览…」选 Cmd_download_tool.exe）、芯片、目标 PID。 「命令前缀」保持默认 Device ID；只有工具被改成按 USB PID 解析时才选 USB PID。
3. 「固件文件」处「浏览…」选好待下载的 .bin（之后 CLI run 直接用它）。
4. 「查看设备」确认能枚举到板子（应显示 vid_248a&pid_8266），再「保存到本工程」。

方式二：CLI

windows-download-tool config --set "toolPath=C:/.../release_v5.9.5/config/Cmd_download_tool.exe" chip=TL751X devicePid=pid_8266
windows-download-tool list

配置层级（每个工程一份配置）

在多个工程之间来回切换时，不需要反复改配置：配置分两层，工程配置优先、全局配置兜底。

工程配置是局部覆盖：只写它声明过的键，没写过的继续从全局取。 所以工程文件里只有 {"chip":"TL321X"} 时，toolPath / devicePid / timeoutMs 仍跟随全局。

配置界面底部的「保存到本工程」写的是全量快照（表单里所有字段），此后该工程不再跟随全局变化； 旁边的「保存为全局默认」则是给新工程当模板用。面板顶部的「配置来源」横幅随时告诉你正在改哪一份。

工程根怎么定

• 扩展：优先取固件文件所属的工作区文件夹；配置面板取活动编辑器所在文件夹，多根工作区会问你一次。
• CLI：从当前目录向上找最近的含 .vscode\windows-download-tool.json、.git 或 .vscode 的目录， 到用户主目录为止（~/.vscode 是扩展安装目录，不会被误当成工程根）。因此从 build/bin/ 之类的子目录调用也能命中。

猜不准时（例如 SDK 解压在 ~/work/sdk_project/ 而 .git 只在 ~/work）用显式通道：

windows-download-tool config --resolve                       # 看当前生效的是哪份、每个字段来自哪一层
windows-download-tool config --init-local                    # 把当前生效配置快照成本工程配置（锚定）
windows-download-tool config --set chip=TL321X               # 默认写本工程
windows-download-tool config --set chip=TL321X --global      # 强制写全局
windows-download-tool run --project D:/path/to/project       # 显式指定工程根，不做向上查找
windows-download-tool run --local                            # 以当前目录为工程根

环境变量 WINDOWS_DOWNLOAD_TOOL_PROJECT 等价于每次都传 --project。

CLI 每次执行会在开头打一行来源，避免"烧的不是我以为的固件"：

·· 配置: 工程 D:\proj\.vscode\windows-download-tool.json ← 全局 C:\Users\...\config.json
·· 配置: 全局 C:\Users\...\config.json（未检测到工程目录）

config --get / config --path / chips --json 不打这一行（它们的输出会被脚本解析），需要时用 --no-banner 全局关闭。

工程配置文件默认会被 git 看到。要随工程提交（团队共享参数）就保持原样； 只想本机使用就把它加进该工程自己的 .gitignore。文件里存的是绝对路径，跨机器需要重新选一次。

使用

界面

• .bin 文件右键 → Windows Download: 下载此固件到目标
• 命令面板：下载固件到目标 / 列出 USB 设备 / 复位目标
• 输出通道「Windows Download Tool」查看设备信息与完整输出

手动命令行测试

配置界面底部的「命令行测试」可以直接跑任意工具命令，不用开终端：

1. 输入一行命令（不含 exe 路径），例如 all、1 TL751X lf 0 0、 1 TL751X wf {addr} -i "{bin}"，点「添加」。第一个参数默认是 Device ID，不是 USB PID。
2. 命令添加后可直接点文本修改（回车或失焦保存，Esc 取消，清空还原）； 用 ↑ / ↓ 调整顺序，▶ 执行单条，✕ 删除；或点「▶ 顺序执行」从头跑完整套 （第一条失败即停止）。
3. 输出实时显示在下方；工具长时间无输出时会补 ·· 心跳，写 Flash 期间不会像卡死。

命令格式是 <Device ID> <CHIP> <命令> [参数]（全局命令 all / help 除外）。第一个参数是 「查看设备」结果里的编号（如 1），会随 USB 设备数量变化，执行前请先点「查看设备」确认。 占位符取自面板里当前填写的值（还没保存也生效）：{pid}、{chip}、{bin}、{addr}。 含空格的参数用引号包住。命令列表存在配置项 testCommands 里，增删 / 排序会即时写入当前工程配置 （没有工程上下文时写全局）。

USB PID 模式（非默认）：如果你把 Cmd_download_tool 改成了按 USB PID 解析，第一个参数 改为 PID 的十六进制值（如设备板 8266），例如 8266 TL751X lf 0 0；同时把配置项 prefixMode 设为 usbPid（面板「命令前缀」选 USB PID），让自动下载 / 复位也用同样的前缀。 标准工具不需要改这一项。

自动下载 / 复位默认按配置的 PID 现查 Device ID（每步前重查，防止 MCU 复位后编号重排）； prefixMode=usbPid 时直接用 PID。exec / script 不做前缀改写，第一个参数要写当前工具 解析方式对应的值（Device ID 或 PID）。

同样的能力也开放给 CLI（AI 可直接调用）：

windows-download-tool exec 1 {chip} lf 0 0                  # 第一个参数是 Device ID（先 list 确认）
windows-download-tool exec 1 {chip} wf {addr} -i "{bin}"
windows-download-tool exec 8266 {chip} lf 0 0               # 工具改成 USB PID 模式时
windows-download-tool script                                # 顺序执行配置里的命令列表
windows-download-tool script --only 2                       # 只执行第 2 条
windows-download-tool script --keep-going                   # 失败后继续（默认第一条失败即停）

exec 的 argv 原样传给 exe（不经 shell），工具自己的 -i / -f 等参数不会被误当选项； 退出码 0=成功、非 0=失败，与 download / run 一致。

CLI（AI 自动化）

windows-download-tool run                    # 精简：直接下载配置界面里选定的固件
windows-download-tool list
windows-download-tool download ./bttpsll_headset&n22_controller.bin
windows-download-tool download ./x.bin --chip TL751X --pid pid_8266 --no-unlock
windows-download-tool exec 1 {chip} lf 0 0              # 手动执行一条工具命令（1 是 Device ID）
windows-download-tool script                            # 顺序执行配置里的命令列表
windows-download-tool reset
windows-download-tool config --get

run 不填固件路径时用配置文件里的 lastBinPath（配置界面「固件文件」浏览选定的那个，或上次下载成功的那个），可另接 [bin] 与同样的覆盖选项。下载成功后 lastBinPath 记到工程配置（没有工程上下文时才落全局）——它是工程级的，落全局会让 A 工程刚烧的固件被 B 工程的 run 拿去用。

CLI 退出码 0=成功、非 0=失败（错误打到 stderr），方便 AI 直接判断。

烧录期间的进度输出

写 Flash 实测约 95 秒，且期间工具可能完全没有输出 —— 工具自身的进度行在直连终端时是行缓冲、看得见，一旦 stdout 被管道接管（| tail）就退化成全缓冲，中途什么都不吐。这是子进程的 stdio 策略，Node 改不了。

所以工具静默满一个心跳间隔时，CLI 会自己补一行（前缀 ··），证明进程还活着：

[step 2/3] 1 TL751X wf 0 -i xxx.bin
·· 写 Flash 开始，固件 1.5 MB。工具可能长时间无输出，属正常，请勿中断；超时 120s
·· 写 Flash 进行中：已用 10s / 超时 120s（工具暂无输出，属正常，请勿中断）
·· 写 Flash 进行中：已用 20s / 超时 120s（工具暂无输出，属正常，请勿中断）

• 只有工具自己安静时才发：工具在输出时心跳完全不会出现，不刷屏。
• 已用时间达到超时的 80% 时改口提醒：·· 写 Flash 已用 96s / 超时 120s，接近超时——超时将中断该步骤，请勿断电。
• 心跳与 [step] 行同在 stdout，所以现有的 | tail 命令不用改；行尾换行、立即写出，被 tail 时最后一行始终是新鲜的。
• 以 ·· 开头的是本工具的行，其余是工具自己的输出。
• 间隔可用 --heartbeat <秒> 调整（默认 10），--no-heartbeat 关闭。

扩展侧同样有心跳：输出通道会打 ·· 行，进度通知的副标题也会刷新成同一句话。

CLI 稳定路径

扩展安装目录带版本号（~/.vscode/extensions/aaronlu2026.windows-download-tool-<版本>/），每次升级都会变；写死该路径的脚本、文档、AI 记忆升级后必然失效（MODULE_NOT_FOUND）。

因此扩展每次激活时把 CLI 落位（或刷新）到不含版本号的稳定目录 %USERPROFILE%\.windows_download_tool\（与 config.json 同目录）：

脚本与 AI 记忆只引用这里的路径，永不写扩展安装目录。加入 PATH 后即可在任意目录直接调用（一次性，新开终端生效）：

[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path","User") + ";$env:USERPROFILE\.windows_download_tool", "User")

未加 PATH 时直接用完整路径，例如 Git Bash："$USERPROFILE/.windows_download_tool/windows-download-tool" list。

落位发生在扩展激活时（onStartupFinished），所以装好扩展、重启一次 VSCode 后该路径即可用。 源码树内开发时仍可直接 node dist/cli.js <命令>；CLI 的 help 会按当前是否已落位自动显示对应调用前缀。

构建与打包

npm install
npm run build     # tsc -> dist/
npm run package   # vsce package -> .vsix（vscode:prepublish 会自动先 build，避免打包到旧 dist）

说明

• 插件无运行时依赖，仅用 Node 内置模块 + vscode API。
• 命令以 argv 数组直传（不拼 shell），路径含空格/中文/& 均安全。
• 工具的工作目录（表单里的「工作目录」）默认自动推断为 release 根目录（config/*.ini 相对其加载），可覆盖。 它和上面的工程根是两回事：前者是 exe 的运行目录，后者是配置文件的归属。
• 配置分全局与工程两层，见「配置层级」；全局配置目录 %USERPROFILE%\.windows_download_tool\ 同时也是 CLI 稳定落位目录（见上）。