# OpenClaw 平台 FPGA Flash 烧写 Skill 改造方案

## 1. 背景与改造难点

目前 `fpga_flash` 这个 skill 是为原版 Claude Code（运行在 Windows 主机上）设计的，脚本中直接调用了 `python` 并使用 Windows 风格的路径（如 `D:/Xilinx/...`、`C:/Users/...`）。

由于 **OpenClaw 是安装在 WSL (Linux) 环境下**的，直接将现有 `SKILL.md` 迁移过去会面临以下跨系统环境问题：
1. **Python 解释器环境错位**：在 WSL 的 Bash 中执行 `python` 会调用 Linux 版的 Python，而不是 Windows 环境下的 Python，这可能导致调用 Windows 版 Vivado 时遇到各种环境变量和子进程调用的兼容性问题。
2. **文件路径格式不兼容**：WSL 中的文件路径是 `/mnt/c/...` 或 `/mnt/e/...` 的形式，而原 Python 脚本（如 `check_flash_csv.py`、`program_flash.py`）预期的是 Windows 路径（`C:/...`、`E:/...`）。直接传入 Linux 路径会导致脚本中的 `os.path.isfile()` 等检查失败。
3. **硬件连接限制**：FPGA 的 JTAG 烧写器通常连接在 Windows 主机的 USB 端口。虽然 WSL 支持 USB 透传，但最稳定可靠的方式是直接在 Windows 端发起 `vivado -mode batch` 调用，以直接使用 Windows 的 Hardware Server。

## 2. 核心改造方案

利用 WSL 优秀的**互操作性（Interop）**，我们不需要对 `scripts/` 目录下的 Python 脚本和 Tcl 脚本做任何修改，只需修改 `SKILL.md` 中的 Prompt，指导 OpenClaw agent 跨环境调用。

**核心机制：**
- **通过 `python.exe` 越界调用**：在 WSL 中可以直接执行 Windows 命令。我们将原 `SKILL.md` 中的 `python` 替换为 `python.exe`。这样执行时会自动启动 Windows Python 解释器，完全在 Windows 上下文中运行脚本。
- **强制要求路径转换**：在 `SKILL.md` 中增加明确的提示词（Prompt），要求 OpenClaw 在提取文件路径（可能由于它在 WSL 中浏览文件，拿到的是 `/mnt/e/...`）后，**必须先将其转换为 Windows 盘符格式**再作为参数传递。

## 3. 具体实施步骤

### 步骤 1：修改 `SKILL.md` 提示词

需要在 `SKILL.md` 中的“执行规范”或相关步骤的命令示例中进行如下调整（在后续实施时可直接修改）：

1. **更改执行命令**：将所有示例中的 `python` 更改为 `python.exe`。
   *原版：* `python "%USERPROFILE%/.claude/skills/fpga_flash/scripts/gen_mcs.py" ...`
   *修改后：* `python.exe "%USERPROFILE%/.claude/skills/fpga_flash/scripts/gen_mcs.py" ...`

2. **增加跨环境路径转换指令**：在 `SKILL.md` 头部或执行规范中增加一条针对 WSL 环境的强调说明：
   > **【WSL 跨环境执行重点约束】**
   > 由于你当前运行在 WSL 环境中，而脚本、Vivado 及硬件都在 Windows 主机上，因此在执行调用前：
   > 1. 必须使用 `python.exe`（而非 `python`）来调用脚本。
   > 2. 所有传递给 `--vivado-dir`、`--bit-file`、`--mcs-file` 和 `--ltx-file` 的参数，**必须转换为 Windows 路径格式**（例如：将 `/mnt/e/Xilinx_design/...` 替换为 `E:/Xilinx_design/...`）。

### 步骤 2：在 OpenClaw 中安装 Skill

OpenClaw 对 `SKILL.md` 的支持与 Claude Code 兼容。可以通过以下方式将其挂载到 OpenClaw 中：

在 WSL 中执行 OpenClaw 的 skill 安装命令，直接指向包含 `SKILL.md` 的目录。例如：
```bash
openclaw skills install /mnt/c/Users/<当前用户>/.claude/skills/fpga_flash
```
*(注：根据 OpenClaw `skills --help` 的提示，`install` 指令支持本地路径安装。)*

### 步骤 3：验证与测试

在 OpenClaw 中对话输入：“请帮我把 E:/Xilinx_design/... 下的 bit 固化到 flash 中”。
观察 OpenClaw 的行动轨迹，确认它是否：
1. 成功识别出此时处于 WSL 环境，并正确生成了 `python.exe` 指令。
2. 成功将 `/mnt/e/...` 等路径翻译成了 `E:/...` 格式。
3. 成功连接到 Windows 侧的 Vivado Hardware Manager 并走通流程。

## 4. 可选的鲁棒性优化（Wrapper Script）

如果发现 OpenClaw 在路径转换上经常犯错（比如忘记转换），可以在 `scripts/` 目录下新增一个 WSL 专用的启动脚本 `run_in_win.sh`，其内容如下：

```bash
#!/bin/bash
# 自动将传入的 WSL 路径通过 wslpath 转换为 Windows 路径，并调用 Windows python
SCRIPT_PATH=$(wslpath -w "$1")
shift
ARGS=()
for arg in "$@"; do
    if [[ "$arg" == /mnt/* ]]; then
        ARGS+=("$(wslpath -w "$arg")")
    else
        ARGS+=("$arg")
    fi
done
python.exe "$SCRIPT_PATH" "${ARGS[@]}"
```
此时 `SKILL.md` 中直接指导 OpenClaw 调用 `./run_in_win.sh scripts/gen_mcs.py --bit-file /mnt/e/...` 即可，把环境切换的负担交给 Bash 脚本处理。这是一种更为稳妥的防呆设计。