# AI_README_FIRST: Hardware Lab 环境配置先读我

用途：把这整个压缩包交给 AI 后，让 AI 在 Windows 电脑上尽快配置 Hardware Lab 的编译、扫描、烧录环境。

## 最高优先级规则

1. 先盘点，不要直接下载。第一步必须运行 `check-environment.ps1`，读取生成的 `hardware-lab-env-detection.json`。
2. 已存在的工具不要重复安装。`python`、`node`、`pyocd`、`arm-none-eabi-gcc`、`mingw32-make`、`cmake`、`ninja`、`STM32_Programmer_CLI` 只要检测为可用，就跳过对应下载/安装。
3. 本包内已有的内容优先使用，不要去官网下载同类内容：
   - `files/pyocd-wheelhouse/`：pyOCD 0.43.1 离线 wheelhouse。
   - `files/packs/TexasInstruments.MSPM0G1X0X_G3X0X_DFP.1.3.1.pack`：MSPM0G3507 pyOCD DFP pack。
   - `backend/hardware_lab_backend.js`：Hardware Lab 本机后端。
4. 如果缺 Arm GNU Toolchain 或 MSPM0 SDK，不要先用 `winget` 或官网慢速下载。先搜索本机常见路径、同目录安装包、QQ 文件目录和用户给出的路径；确实没有再提示用户提供本地安装包或使用官网兜底。
5. 不要自动真实烧录硬件。只有用户明确允许，并且已经扫描到当前电脑的 DAPLink/STLink UID 后，才能执行真实 flash。

## 推荐执行顺序

在解压后的目录打开 PowerShell：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\check-environment.ps1
```

然后读取：

```text
hardware-lab-env-detection.json
```

如果 `pyOCD` 缺失，再运行：

```cmd
install-pyocd-offline.cmd
```

如果 `Node.js` 可用，启动后端：

```cmd
start-hardware-lab-backend.cmd
```

验证后端：

```powershell
Invoke-RestMethod http://127.0.0.1:8765/api/health
Invoke-RestMethod http://127.0.0.1:8765/api/scan
```

打开网页：

```text
https://nuedc-components-atlas-public.pages.dev/hardware-lab
```

## 本机优先搜索规则

AI 应先检查这些位置：

- 命令 PATH：`python`、`node`、`pyocd`、`arm-none-eabi-gcc`、`mingw32-make`、`cmake`、`ninja`。
- Arm GNU Toolchain 常见路径：
  - `C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\*\bin\arm-none-eabi-gcc.exe`
  - `C:\Program Files\Arm GNU Toolchain arm-none-eabi\*\bin\arm-none-eabi-gcc.exe`
- MSPM0 SDK 常见路径：
  - `%MSPM0_SDK_INSTALL_DIR%\imports.mak`
  - `C:\ti\mspm0_sdk_*\imports.mak`
  - `D:\ti\mspm0_sdk_*\imports.mak`
  - `D:\ccs\M0_SDK\imports.mak`
- 本地 SDK 压缩包：
  - 当前包目录或父目录下的 `mspm0_sdk_*.zip`
  - 用户明确给出的 QQ/下载目录里的 `mspm0_sdk_*.zip`

## 加速下载入口

如果别人还没有本包，让他先打开：

```text
https://nuedc-components-atlas-public.pages.dev/download-accelerator
```

推荐先点 `下载完整 ZIP`。网络慢时点 `网络慢就下分片`，下载 4 个 part 文件和 `merge-hardware-lab-kit-windows.cmd`，放在同一个文件夹后双击合并。

国内最快的长期方案：把最新 `site_edgeone_ascii.zip` 上传 EdgeOne，再把 EdgeOne 域名发给同学。这样下载页的 `下载完整 ZIP` 会走 EdgeOne 同源下载。

## 缺工具时怎么处理

- 缺 `pyOCD`：只用 `install-pyocd-offline.cmd`，不要 pip 联网。
- 缺 `MSPM0 DFP pack`：本包正常自带；检查 `files/packs/`，不要联网下载 pack。
- 缺 `MSPM0 SDK`：优先找本机和本地 zip。找到多个版本时优先使用能让目标工程编译通过的版本。
- 缺 `Arm GCC`：优先找本机已安装路径。确实没有时，提示用户提供本地安装包或允许下载；不要无限等待慢速官网连接。
- 缺 `Node.js`：后端无法运行。若包内存在 `runtime/node.exe` 就用包内 Node，否则需要用户安装 Node。

## 完成标准

必须同时满足：

- `check-environment.ps1` 生成了 `hardware-lab-env-detection.json`。
- `http://127.0.0.1:8765/api/health` 返回 JSON。
- `http://127.0.0.1:8765/api/scan` 返回 JSON，工具缺失也要是结构化失败。
- Hardware Lab 网页能连接本机后端。
- 没有重复下载已经存在的工具。