Fpai-user-env-check

单模型部署前的开发环境检查与校准 skill：基础开发环境 / icraft 版本对齐 / icraft python 运行时导入 / AI Python 环境 / 交叉编译环境 / 全链路确认 / 编译与仿真

作为 Fpai-user-one-model 的前置门禁：进入导出/编译/上板前先跑本 skill，输出「环境就绪 / 缺项清单」与版本清单。
版本清单（CLI 版本、python 包版本、SDK/镜像就绪情况）供 one-model 选择 icraft_v<major>.<minor> 分支。
自动挂载两个只读根目录：fpai_kb 知识库、fpai_env 离线包；首次使用必须由用户提供真实路径。
不擅自安装、卸载或改动用户现有环境；所有环境操作先给方案并经用户确认。

快速使用

输入请求：

请使用这个 skill 检查单模型部署前的开发环境：
fpai_kb 知识库根目录：<绝对路径>
fpai_env 离线包根目录：<绝对路径>
本次部署 icraft 版本：3.36 / 3.38 / 3.39.0
目标后端：100Tai / 30Tai / 400Tai
交叉编译方式：Docker / WSL / 虚拟机

或直接运行自动化脚本：

powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\check_env.ps1 -IcraftVersion 3.39 -Backend 400Tai -FpaiEnvRoot <fpai_env_root>

检查流程

基础开发环境：git / Python3 / CMake / Visual Studio（含 C++ 桌面负载 CRT）/ Docker Desktop 或 Ubuntu24.04（交叉编译），逐项标注使用环节与必要性。
icraft 版本对齐：CLI（如 C:\Icraft\CLI\bin\icraft.exe）与 python 包同版本且可 import，icraft --version 识别；Windows / 交叉编译 / 板卡三处一致。
icraft python 运行时导入：import icraft.xir, icraft.xrt, icraft.host_backend, icraft.buyibackend, icraft.zg330backend，缺一不可。
AI Python 环境：pytorch / onnx / onnxruntime / uv。
交叉编译环境（按后端 + icraft 版本，见下）。
100Tai(BY) / 30Tai(ZG) / 400Tai(WL) 全链路工具链、icraft 版本、AI Python 环境、离线资源可用。
编译 + 仿真冒烟：Model -> 源码 + 1_scripts + 2_compile + 3_deploy，确保编译成功且仿真成功。

交叉编译环境

交叉编译环境按 icraft 版本确定：

3.38：本地已有 icraft_3.38_24.04_images.tar 时，该镜像支持 BY / ZG / WL 三个后端的交叉编译，直接 docker load 导入使用；无镜像时按 Ubuntu24.04 构建。
3.39.0：在 3.38 镜像上把 icraft 换版本为 3.39（dpkg -r Icraft/CustomOp → dpkg -i Icraft_3.39.0_onchip.deb，按后端选 onchip 包）；无 3.38 镜像时按 Ubuntu24.04 构建。
3.36：默认只跑 BY / ZG（不支持 WL），且暂不提供交叉编译环境；确有需要时按 Ubuntu20.04 构建交叉编译环境。

关键约束

fpai_kb / fpai_env 只读，首次使用必须先确认两个真实根目录，不假定默认路径。
离线包检索：共用包在 <fpai_env_root>\public，版本相关包在 <fpai_env_root>\icraft_vx.x；找不到时明确提示“需用户自行安装”，不编造下载地址。
icraft python 运行时五个子模块缺一不可；CLI 与 python 包必须同版本。
交叉编译环境按 icraft 版本：3.38 有镜像则支持 BY/ZG/WL 三后端；3.39.0 在 3.38 镜像上换版本；3.36 默认只跑 BY/ZG、暂不提供交叉编译环境（有需要按 Ubuntu20.04 构建）。
Python 与 icraft python 包核对覆盖 conda / uv / venv 等环境，不能只查系统默认 PATH。
报告每项标注使用环节与必要性，对“根据情况/建议安装”类非必须项允许按任务跳过。
最终必须输出「环境就绪 / 缺项清单」，供 one-model 进入导出前把关。

输出报告

环境就绪状态报告：每项 PASS / 缺项（缺失项 + 修复指引）。
版本清单：icraft CLI 版本、python 包版本、SDK/镜像就绪情况，给出目标 icraft_v 分支。
icraft python 运行时导入：五模块是否全部可导入。
AI Python 环境：pytorch/onnx/onnxruntime/uv 版本。
交叉编译环境：按 icraft 版本（3.38 镜像支持 BY/ZG/WL；3.39.0 在 3.38 镜像上换版本；3.36 默认只跑 BY/ZG、暂不提供）。
全链路确认：BY / ZG / WL 各自工具链、版本、AI Python、离线资源。
编译 + 仿真冒烟：1_scripts / icraft compile / 仿真结果。

文件

SKILL.md — skill 指令（检查流程、报告模板、硬性约束）。
README.md — 本文件。
scripts/check_env.ps1 — 自动化执行步骤 1-5 的环境探测与报告。
references/icraft-install-guide.md — iCraft Windows / Ubuntu24.04-aarch64 / Ubuntu24.04-x86_64 安装、Docker 交叉编译环境、3.38 镜像（支持 BY/ZG/WL）、3.39.0 在镜像内换版本、3.36 按 Ubuntu20.04 构建、modelzoo_utils / thirdparty / uv 准备。

脚本

脚本	用途
`check_env.ps1`	探测基础环境 / icraft CLI 与 python 包 / icraft 运行时导入 / AI Python 环境 / 交叉编译环境，输出 PASS-缺项报告与版本清单

参数：

参数	说明
`-IcraftRoot`	icraft 安装根目录，默认 `C:\Icraft`
`-IcraftVersion`	目标版本（如 `3.36` / `3.38` / `3.39.0`），留空从 CLI 自动识别
`-FpaiEnvRoot`	fpai_env 离线包根目录（检索镜像 tar / 安装包）
`-Python`	用于 icraft python 包与 AI 环境检查的解释器，默认 `python`
`-Backend`	`100Tai`/`30Tai`/`400Tai` 或 `BY`/`ZG`/`WL`；用于 3.36 后端校验（仅 BY/ZG）与镜像 tag 提示
`-BaseImageTar`	`icraft_3.38_24.04_images.tar` 路径（3.38 直接使用；3.39.0 在镜像内换版本时使用）
`-Json` / `-OutFile`	输出 JSON 报告 / 写入指定文件

参考文档（references/）

icraft-install-guide.md：安装与交叉编译环境搭建（Windows / Ubuntu24.04-aarch64 / Ubuntu24.04-x86_64 / Docker，含 §4.5 3.38 镜像与 3.39.0 换版本、§4.6 3.36 按 Ubuntu20.04 构建）。

限制

仅做环境检查与冒烟把关；模型适配、TOML 生成、算子审计、精度分析由 Fpai-user-one-model 及其后续 skill 负责。
3.39.0 在 3.38 镜像内的 arm icraft 换版本需用户确认后执行；替换用的 onchip deb 需能从 fpai_env 或本地获取，否则需用户提供。3.36 暂不提供交叉编译环境，有需要时按 Ubuntu20.04 构建。
check_env.ps1 为 Windows 侧探测脚本；板卡端与容器内检查以文档步骤为准。
上板上传 / SSH / 板端执行由 Fpai-user-connector 负责。