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

1. 背景与改造难点

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

由于 OpenClaw 是安装在 WSL (Linux) 环境下的，直接将现有 SKILL.md 迁移过去会面临以下跨系统环境问题：

Python 解释器环境错位：在 WSL 的 Bash 中执行 python 会调用 Linux 版的 Python，而不是 Windows 环境下的 Python，这可能导致调用 Windows 版 Vivado 时遇到各种环境变量和子进程调用的兼容性问题。
文件路径格式不兼容：WSL 中的文件路径是 /mnt/c/... 或 /mnt/e/... 的形式，而原 Python 脚本（如 check_flash_csv.py、program_flash.py）预期的是 Windows 路径（C:/...、E:/...）。直接传入 Linux 路径会导致脚本中的 os.path.isfile() 等检查失败。
硬件连接限制：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 中的“执行规范”或相关步骤的命令示例中进行如下调整（在后续实施时可直接修改）：

更改执行命令：将所有示例中的 python 更改为 python.exe。 原版： python "C:/Users/bowei/.claude/skills/fpga_flash/scripts/gen_mcs.py" ... 修改后： python.exe "C:/Users/bowei/.claude/skills/fpga_flash/scripts/gen_mcs.py" ...
增加跨环境路径转换指令：在 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 的目录。例如：

openclaw skills install /mnt/c/Users/bowei/.claude/skills/fpga_flash

(注：根据 OpenClaw skills --help 的提示，install 指令支持本地路径安装。)

步骤 3：验证与测试

在 OpenClaw 中对话输入：“请帮我把 E:/Xilinx_design/... 下的 bit 固化到 flash 中”。观察 OpenClaw 的行动轨迹，确认它是否：

成功识别出此时处于 WSL 环境，并正确生成了 python.exe 指令。
成功将 /mnt/e/... 等路径翻译成了 E:/... 格式。
成功连接到 Windows 侧的 Vivado Hardware Manager 并走通流程。

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

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

#!/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 脚本处理。这是一种更为稳妥的防呆设计。

4.7 KiB Raw Blame History Unescape Escape