本机二进制工具安装
先看这一节：本机网络实测事实（2026-09-21 实测）
不要凭直觉选下载源。 这台机器上有几条硬约束：
| 源 | 实测结果 |
|---|---|
github.com |
❌ 完全不可达（超时）。任何指向 GitHub release 的直连都别试 |
winget install |
❌ 失败 0x80072f7d（到 winget CDN 的 TLS 握不上手）。winget search 能出结果（读缓存），但装不了 |
gyan.dev |
⚠️ 可达但仅 16 KB/s，104MB 要跑 1.8 小时，只做最后备选 |
| GitHub 加速代理 | gh-proxy.com 116 KB/s（最快）> gh.xxooo.cf 24 > ghproxy.net 21；hub.gitmirror.com/moeyy/ghproxy.cc 均不可达 |
registry.npmmirror.com/-/binary/ |
✅ 首选，实测 7.7 MB/s |
第一选择永远是 https://registry.npmmirror.com/-/binary/。 它是 npmmirror 的二进制镜像，索引在 /-/binary/（返回 JSON 数组，含 name / type / size），已知包含：
ffmpeg-builds/— BtbN FFmpeg 全量构建（按版本号分目录，如v8.1.3/），带配套<version>.sha256.txtffmpeg-static/- 以及 node、electron、chromium 等常见运行时
两个必踩的坑（会让人误判成"网络不通"）
坑 1：curl -o <文件> 在沙箱里写入失败
表现为 curl: (23) client returned ERROR on write of N bytes，即使 HTTP 状态是 200 文件也是空的。
-o /dev/null 同样失效 —— 用它测速会得到 下载=0B 速度=0 KB/s 的假数据，进而误判成"源不可达"。
✅ 正确写法：用 shell 重定向
curl -sSL --max-time 300 "https://.../file.tar.xz" > file.tar.xz
测速也必须写真实文件再量大小，不能靠 -o /dev/null：
rm -f t.bin; t0=$(date +%s.%N)
curl -sSL -r 0-10485759 --max-time 30 "$URL" > t.bin 2>/dev/null
t1=$(date +%s.%N); sz=$(wc -c < t.bin)
awk -v s="$sz" -v a="$t0" -v b="$t1" 'BEGIN{d=b-a; printf "%.0f KB/s\n",(s/d)/1024}'
坑 2：Python 在 Windows 下不认 /c/... 这种 Unix 路径
把 Git Bash 风格的路径传给 Python 脚本参数（如 --ffmpeg /c/Users/.../ffmpeg.exe），Python 会报 [WinError 2] 系统找不到指定的文件，看起来像"工具没装"。
✅ 传参一律用 C:\Users\...\ffmpeg.exe。Bash 内部命令可以用 /c/...，跨界传参要转。
标准流程
- 先探测，别猜：确认目标是否已存在（
find常见安装位置 + 包管理器--version），避免重复下载。
bash for c in winget choco scoop; do printf "%-8s " "$c"; command -v $c >/dev/null 2>&1 && $c --version 2>&1|head -1 || echo "未安装"; done - 测速选源：候选源各拉 5–10MB 真实落盘测速，选最快的，别一头扎进最慢的。
- 下载 + 校验：务必同时下载官方哈希文件并比对。
bash sha256sum file.tar.xz # 与官方 .sha256 比对，不一致就停 - 解压：优先 ZIP（
unzip可用）；.tar.xz用 Python 内置tarfile（tarfile.open(p,'r:xz')），本机没有 7z 解压器，避免选只提供.7z的构建。 - 安装位置：用户级、免管理员 ——
C:\Users\admin\AppData\Local\Programs\<工具名>\。 - 写入用户 PATH（用 PowerShell，不要用
setx，setx会在 1024 字符截断）：
powershell $bin = "C:\Users\admin\AppData\Local\Programs\<工具>\bin" $cur = [Environment]::GetEnvironmentVariable("Path","User") if (-not ($cur -split ';' -contains $bin)) { [Environment]::SetEnvironmentVariable("Path", $cur.TrimEnd(';') + ";" + $bin, "User") }
注意：当前已开的 bash 会话看不到新 PATH，属正常，新开终端生效。验证时要读回注册表值确认。 - 验收（关键）：不要只看"文件存在"，要验"能力可用"（详见下节）。
验收套路：验能力，不验存在
# 1) 版本能跑起来
<tool>.exe -version
# 2) 关键能力真的编译进去了（以 ffmpeg 为例）
FF=.../ffmpeg.exe
for f in subtitles drawtext overlay loudnorm; do
printf "%-12s " "$f"
"$FF" -hide_banner -filters 2>/dev/null | awk -v n="$f" '$2==n{print "✅";f=1}END{if(!f)print "❌"}'
done
# 3) 真实场景冒烟测试（比看版本号可信得多）
# 以中文字幕为例：真的渲染一张带中文的图
"$FF" -f lavfi -i "color=c=black:s=640x200:d=1" \
-vf "drawtext=fontfile='C\:/Windows/Fonts/msyh.ttc':text='测试中文':fontcolor=white:fontsize=36:x=20:y=80" \
-frames:v 1 zh.png
# 4) 读图确认字形（无缺字方框），而不是只看"退出码 0"
如果目标工具自带 doctor / 自检子命令，优先跑它，退出码就是依赖就绪度。
FFmpeg 专项（本机已装，重装时用）
- 当前版本：8.1.3（BtbN
win32-x64-gpl，含--enable-libass/--enable-libfreetype/--enable-fontconfig） - 位置：
C:\Users\admin\AppData\Local\Programs\ffmpeg\bin\（已入用户 PATH） - 重装地址：
https://registry.npmmirror.com/-/binary/ffmpeg-builds/v8.1.3/，取ffmpeg-8.1.3-win32-x64-gpl.tar.xz（140MB）+ffmpeg-8.1.3.sha256.txt - 该版本 SHA256：
dad18b024a104cac9c0820031eba3d03d403bfd7374aac4338b2a06bd9bb4512 - 不要选
lgpl变体，也不要用 gyan.dev 的essentials（能含 libass 但下载要 1.8 小时）；-shared变体需要额外 DLL，别用 - 中文字体：
C:\Windows\Fonts\msyh.ttc（微软雅黑，ASS 字体名Microsoft YaHei）
HyperFrames（HTML→MP4）在本机的三个坑（2026-10-05 实测）
hyperframes 的 CLI 与依赖可以正常装（npm i hyperframes --ignore-scripts --registry=https://registry.npmmirror.com，
必须加 --ignore-scripts：否则 esbuild 的 postinstall 会 spawnSync node.exe 报 EBUSY，
整个 install 回滚，node_modules 被清空）。装完后 validate / inspect / snapshot 都能跑通，
但 render 会被下面三个坑逐个拦住。
坑 3：chrome.exe --version 在本机恒失败 → render 永远过不了体检
render 启动时调 chromeLaunchOutcome()，用 spawn(executablePath, ["--version"]) 做 5s 体检。
本机实测（系统 Chrome 142 与 Chrome for Testing 154 都一样）：
| 命令 | 结果 |
|---|---|
chrome.exe --version |
❌ 退出码 3，无任何输出 |
chrome.exe --product-version |
❌ 退出码 3 |
chrome.exe --version --user-data-dir=... |
❌ 退出码 3 |
chrome.exe --no-sandbox --version |
❌ 挂起（超时） |
chrome.exe --headless=new --no-sandbox --dump-dom about:blank |
✅ rc=0，正常输出 HTML |
即 Chrome 本身能正常无头启动（validate/snapshot 都成功拉起过 Chrome 并拿到硬件 WebGL），
坏的只有 --version 这一条探测路径。而 HYPERFRAMES_BROWSER_PATH 指向任何真 Chrome 都救不了。
✅ 有效解法：把体检改成软通过（改完后 render 正常产出 MP4）。
文件：node_modules/hyperframes/dist/chunk-YSCN66NT.js
- 把探测参数换成一个真能成功的命令：
executablePath, ["--version"], {→executablePath, ["--dump-dom", "about:blank"], { - 把 catch 分支里的失败返回（
name:"Chrome", ok:false, title:"Chrome cannot start"那个对象）
整块替换成return { ...found };，让探测失败不再是致命错误。
注意：dist/** 里只有这一个文件含该逻辑；改完要确认 -- 后的错误文案里仍写着 --version（模板是写死的），
别被文案误导以为补丁没生效。
坑 4：~/.hyperframes/running/<pid> 的陈旧锁文件会触发沙箱批量删除拦截
每个 CLI 命令会在 C:\Users\admin\.hyperframes\running\ 留一个 <pid> 空文件，退出时删除。
沙箱拒绝覆盖式/批量删除，于是这些文件越积越多；下次启动时 CLI 想一次性清扫，
就报 [safe-delete][SAFE_DELETE_BULK_REJECTED] {"count":98,"threshold":50,"scope":"turn"}，
整个命令被拦下（per-turn 阈值 50，同一轮里删多了就全拒）。
- ❌ 别试图
rm -rf那个目录（沙箱会弹确认，用户拒了就彻底别重试） - ✅ 临时绕法：给单条命令换个 home，让 CLI 在新目录里从零开始
bash export MSYS_NO_PATHCONV=1 export USERPROFILE='C:\Users\admin\.workbuddy\binaries\node\workspace\.hfhome' export HOME="$USERPROFILE"
⚠️ 代价：换 home 后会探测不到 Chrome（Browser not available），因为浏览器路径记在旧 home 的
install-state.json里。所以换 home 和 render 不能同时用——render 要么在原 home 下跑，
要么靠坑 3 的补丁 +HYPERFRAMES_BROWSER_PATH显式指定。
坑 5：node_modules 里缺失完整包会让 CLI 直接崩
EACCES/EBUSY 引起的 install 回滚会留下半个 node_modules（例如 @esbuild/win32-x64 在、
但 esbuild 主包不在），此时任何 hyperframes 命令报
Cannot find package 'esbuild' imported from .../hyperframes/dist/chunk-*.js。
✅ npm i esbuild --ignore-scripts --registry=https://registry.npmmirror.com 补齐即可。
附：Chrome for Testing 镜像
https://registry.npmmirror.com/-/binary/chrome-for-testing/<version>/win64/chrome-win64.zip
（实测 205MB，9s 下完，约 23 MB/s）。目录索引 /-/binary/chrome-for-testing/ 返回 JSON 数组。
注意：低版本目录（如 142.x）没有 win64/ 子目录，只有 154+ 才是 win32/+win64/ 的布局。
解压用 Python zipfile（1.9s），解压后 --version/--dump-dom 行为与系统 Chrome 一致。
边界
- 不擅自安装系统服务、不改系统级 PATH、不执行远程脚本。改动只限用户目录 + 用户级 PATH。
- 大体积下载（>100MB）先告知体积与预计耗时再动手。
- 哈希对不上就停止，不要"先装了再说"。
- 不要在聊天里粘贴任何凭据；需要密钥的工具让用户自己在界面里配。
