作者：Warren Huang，来源：FPGA FAE技术分享选集
场景：目标机没有外网（或只有内网），需要在 Windows + WSL2 上部署一套本地 AMD 文档检索服务
前提：另一台有网机器负责下载；目标机全程离线
说明：<包位置> = 离线包在本地的目录，下文统一用它代替真实盘符
需要你自己动手的只有三件：用 AMD 账号取一次 A 组离线包、允许一次重启、为 UNIX 用户设一次密码；下载器需PowerShell 5.1+
一、这套脚本解决什么问题
如何保证断网部署？脚本做了两件事：
1. 把"要联网的动作"全部挪到有网机器上（下载清单 + 文件大小核对）；
2.把"断网后的动作"全部变成纯本地操作（MSI 装机、dpkg -i 装 deb、docker load 装镜像）。
一共 14 个脚本：7 个部署 + 7 个日常。
二、目录的位置约束
脚本按相对路径找材料，不写死盘符。放错了离线包错了直接报"离线包缺失"。以下命令均以“部署脚本\”、“日常脚本\”内的脚本为准：
三条硬约束：
① 必须本地盘（UNC 网络路径会主动报错）；
② 路径不能含单引号 '（拷贝阶段会失败）；
③ docker-debs 名字不能改。
磁盘要先看：安装包\ 约 5.3 GiB（16 个文件 809 MiB + A 组 4.44 GiB），拷进 ext4 再占 4.44 GiB，镜像与模型解包后还要几 GB；ext4.vhdx 默认落在<包位置>\wsl\<Distro>，和离线包同一块盘。建议该盘留 ≥ 30 GB。
三、联网侧：一条命令下完 16 个文件
3.1 00_下载依赖包.ps1 —— 下载器 + 校验器
它做了什么（这也是它比"手动点链接"靠得住的原因）：
三个常用参数：
3.2 16 个文件都是什么
为什么要单独下后 9 个？ docker-ce 的 Depends 里含 iptables, nftables，而 Ubuntu 24.04 的 WSL base rootfs 这两者连同依赖库一个都没有，不补就 unmet dependencies——断网时 apt-get -f install 也救不了，它得联网。
3.3 A组只能自取
AMD那个包没有公开URL，需要用AMD账号登录官方Downloads 页面下载 20260918.qwen3-embedding-0.6b，整个目录放进安装包。
安装包路径为：
https://www.amd.com/en/support/downloads/ross-agentic-ai.html
四、断网侧：4 步部署
4.1 第 1 步 04_离线安装WSL3.ps1
作用：不碰 Store、不碰 GitHub，只用两个本地文件把 WSL 和 Ubuntu 装好。内部 6 步：
参数（一般不用给）：
·文件名按特征匹配（wsl.*.x64.msi、ubuntu-*-wsl-amd64.wsl），所以下载 3.0.4、24.04.6 也能跑，不用改脚本。
· 可能要跑两次：若第 3 步提示重启，重启后再跑一次，它会跳过已完成步骤继续装 Ubuntu。
· 镜像有 SHA256 校验：与官方清单一致才导入，校验不过直接停，不会装出一个半成品。
成功标志：systemd PID1: systemd（不是 init）+ Ubuntu 24.04.5 LTS。
4.2 第 2 步一键部署_路线B.ps1
作用：一个总控，把"配 WSL + 拷文件 + 装Docker"三件事串起来。内部 7 个子步（编号 0/6–6/6）：
装完 Docker 必须关掉重开 Ubuntu 终端（exit 后重新wsl -d Ubuntu-24.04）让 docker 组生效；否则下一步 12_ 的第一项检查就 permission denied。
默认就是离线，不用加开关；只有在你有外网、想走 Docker 官方源时才加：
.wslconfig 是算出来的，不是写死的：
4.3 10_WSL内安装DockerEngine.sh —— 被第 2 步调用
这个脚本有两个模式。离线模式只走 dpkg，不跑 apt-get update / apt-get install（第 1 步清冲突包用的 apt remove 除外）：
4.4 第 3 步 12_Ubuntu内_部署DocSearch.sh
作用：把"部署器自检 → 生成配置 → 起容器 → 看状态"串起来，5 步：
configure里三个选择，断网时选错就是必挂：
图中doctor 三行全绿，下面就是对三个选项的明文提醒
4.5 第 4 步：填端点
两个注意点：
①键名不同客户端不同（VS Code用servers，Claude/WorkBuddy风格用 mcpServers）；
② "type" 不能漏（本地 http，云端 streamable-http）；
图中绿点+ 1 tool 就说明通了，工具名 vivado_doc_search
五、7 个日常脚本
六、验收清单
报错 → 回哪一节：
七、跑一遍性能基准（可选）
验收清单只看"通不通"，不看"快不快"。延迟可以直接量出来：让编辑器里的 Agent 调vivado_doc_search，按 UG/PG/Wiki 三类文档随机抽题，跑10 轮，最后由 UI 汇总成一份 HTML 报告。
用一句话让 Agent 自己跑 10 轮随机检索，并把结果汇总成 HTML
报告总览：70 次请求全部成功，平均 122.7 ms、P50 118.4 ms、P95 157 ms、最慢 358.1 ms
同一份报告的可视化：各轮均值、按文档类别的均值、延迟分布
附录 · 一页命令卡
联网侧只做一件事（把 16 个文件按文件大小核对完），断网侧只做一件事（把每一步都换成纯本地操作）。
AMD-Ross官网：
https://www.amd.com/en/products/software/ross-agentic-ai.html
AMD官方新闻稿：
https://newsroom.amd.com/news/amd-ross-agentic-ai-embedded-design-development/
GitHub 仓库：
https://github.com/xilinx/ross-ai-assistant
下载页面：
https://www.amd.com/en/support/downloads/ross-agentic-ai.html
如果您在Vivado MCP、AI开发FPGA方面有问题，欢迎联系：
simonyang@comtech.cn
charlesxu@comtech.cn
