Windows 桌面软件：下载 → 安装 → 开窗验证

目标：交付真实的文件和真的能打开的软件，不是方案文档。

关键前提（先花 10 秒摸清环境）

在这个 agent 环境里，以下"常识做法"全部不能用，别浪费时间：

另一个必踩的坑：agent shell 里带着一堆污染变量，启动 Electron 应用前必须剥离：
ELECTRON_RUN_AS_NODE、AGENT_BROWSER_ARGS、PLAYWRIGHT_MCP_NO_SANDBOX、BROWSER_USE_CHROMIUM_SANDBOX、CODEBUDDY_SAFE_DELETE_SANDBOX、NODE_OPTIONS、http_proxy/https_proxy/HTTP_PROXY/HTTPS_PROXY，以及所有 LSBOX*、SANDBOX_CENTER* 前缀。

步骤 1：确认"最新版"到底是哪个

只看 tag 会翻车。必须先取 assets 清单，确认桌面安装包真的存在。

curl -sL "https://api.github.com/repos/<owner>/<repo>/releases?per_page=12" -o list.json
# 用 Python 打印每个 tag 的 asset 名字，肉眼确认有 .exe / .dmg

实例教训：Obsidian v1.13.8 的 release 只有 .apk（安卓），桌面最新版是 v1.13.7。
拿到目标 asset 后，记下 API 返回的 size，下载完用它校验，这是最强的完整性证据。

步骤 2：下载（国内网络必用镜像）

github.com 直连大概率不通（curl exit 7），但 api.github.com 是通的——所以"能查 API"不等于"能下文件"。

实测可用镜像（2026-09 测速）：
- https://ghproxy.net/ — 快，首选
- https://cdn.gh-proxy.com/ — 次选
- https://gh-proxy.com/ — 备选

实测失败：ghfast.top、hub.gitmirror.com、ghproxy.cc、gh.llkk.cc、ghps.cc、ghproxy.homeboyc.cn

用法就是前缀拼接：https://ghproxy.net/https://github.com/<owner>/<repo>/releases/download/<tag>/<file>

大文件用 scripts/gh_parallel_download.py：20 段分段 + 多镜像轮换 + 失败重试，实测能把 376 KB/s 拉到 6.5 MB/s（315 MB / 4.9 分钟）。下完自动比对字节数。

下载阶段千万别用带中文的路径做临时目录（编码风险）。先用工作区里的纯 ASCII 临时目录，最后再 shutil.move 到中文目标目录。

步骤 3：静默安装

• NSIS 安装包（Electron 桌面应用绝大多数是）：App-Setup.exe /S
• 判断方式：文件头 MZ + PE，且文件里能搜到 Nullsoft 标记
• /S 必须大写；/D= 指定目录时必须放最后一位且不带引号
• 安装会持续几分钟（315 MB 装了约 4 分钟），用后台任务跑，别硬等
• 判断装完：注册表 HKCU/HKLM Uninstall 下出现 DisplayName，并且安装器进程已退出
• 注意：有的应用（如 Obsidian）会装到安装包旁边的 Obsidian\ 子目录，不一定在 %LOCALAPPDATA%。别假设，直接 find 找主 exe。

装完顺手确认：主 exe 存在、Uninstall *.exe 存在、开始菜单/桌面 .lnk 存在。

步骤 4：先验证能启动，再谈其他

4a. 参数矩阵定位崩溃（Electron 必做）

命令结束后子进程会回收，所以"启动 + 检测窗口"必须写在同一条命令里。

典型崩溃：FATAL: GPU process isn't usable. Goodbye.（退出码 2147483651 = 0x80000003）。
这类环境下 Chromium 的独立 GPU 进程起不来，按下面矩阵逐个试：

4b. 端到端验证：模拟双击

explorer.exe <路径> 在非交互上下文里不会真的执行目标，别用它。

正确做法见 scripts/verify_window.py：
1. shell32.ShellExecuteW(None, "open", lnk路径, None, None, 1) → 返回值 >32 即成功（这是资源管理器双击时的同一条 API）
2. EnumWindows 找 IsWindowVisible 且标题含目标关键字的顶层窗口
3. 拿到窗口标题当证据

证据强度排序：窗口标题枚举 > 应用自己落的配置文件/日志 > 进程存在 > 截图（GDI 抓不到 Electron 画面，别交）

步骤 5：需要给启动参数时，改 .lnk（不改 exe）

改 exe 会被自动更新覆盖；改 .lnk 不会。按 MS-SHLLINK 规范重建：

• 头部 76 字节，LinkFlags 在偏移 0x14
• 出现顺序：LinkTargetIDList → LinkInfo → NAME → RELATIVE_PATH → WORKING_DIR → COMMAND_LINE_ARGUMENTS → ICON_LOCATION → ExtraData
• 插入参数要同时把 bit5 (0x20) 置位，否则资源管理器不认
• 必须原样保留 LinkInfo 和 ExtraData（后者含 AppUserModelID，丢了会影响任务栏分组）
• 改完先回读校验：参数在不在、ExtraData 字节数有没有变

直接跑 scripts/lnk_add_args.py（改这两个位置：桌面 + %APPDATA%\Microsoft\Windows\Start Menu\Programs\）。

步骤 6：卸载（NSIS 卸载器在沙箱里会「假成功」）

最坑的一点：在沙箱内跑 Uninstall <App>.exe /S，返回码是 0、看起来成功，其实一个文件都没删。

原理：NSIS 卸载器会先把自己复制到 %TEMP%\~nsu.tmp\Un_A.exe，再启动那个副本干活。沙箱允许「复制」这一步，但不允许副本进程起来 → 卸载永远不开始，而原进程照常退出、返回 0。

识别方法：跑完立刻轮询数安装目录的条目数，等 60 秒没变化 = 失败（TEMP 里会留着 ~nsu.tmp\Un_A.exe）。

解法：加 dangerouslyDisableSandbox: true 重跑，实测 12 秒删干净。

标准流程

1. 先记基线（最重要）：数一遍用户数据目录的文件数。卸载绝不该动用户数据，卸载后要拿这个数字核对。
2. 确认应用没在运行（tasklist | grep -i <app>）。
3. 进安装目录执行：cd "<安装目录>" && "./Uninstall <App>.exe" /S（沙箱外）。
4. 轮询等目录清空，别只看返回码。

卸载后必须核对五处

两个已知行为

• %APPDATA%\<App> 配置目录不会被卸载器删掉（Electron 系通常留几十 MB 缓存）。它是缓存不是数据；留着的好处是重装时配置能复用。要清必须先确认里面没有用户数据。
• 卸载器可能把 UninstallString 注册成带 /currentuser（electron-builder per-user 安装）。手工卸载带上它更保险。

> 重装成本提示：如果当初下载的安装包还留着，重装就是双击一次的事，不用重新下载。所以卸载时先别急着删安装包，问一句用户要不要留。

交付与汇报

• present_files 交下载到的真实安装包路径（用户要看到文件本身）
• 汇报里给全：安装包路径 + 字节数 + SHA256、安装目录、注册表登记、快捷方式位置、验证用的窗口标题
• 改了用户的东西必须说（比如动了 .lnk）：改了什么、原值是什么、怎么还原
• 不要生成"方案/计划"文档；用户要的是文件和事实

遗留清理

• 工作区里的临时脚本/JSON/临时下载目录，任务结束全部删掉
• 如果为改 .lnk 做过备份，别把备份留在桌面上，要么删掉、要么挪进安装目录

💳 付费能力（Pay Skill）

本 Skill 的基础能力永久免费：下载安装启动验证全链路（本地）。

仅「失败案例增强包」为按次付费（0.5 元/次）——付费购买的是服务端下发的方法论资产（常见失败案例库、国内镜像源优选表、静默安装参数库），不是算力。

> 重要：本 Skill 不自建、不部署任何大模型。付费项所需的算力由用户自带（BYOK）或本机提供；用户自带算力同样支付 0.5 元——因为买的是方法论，不是算力。

计费范围

支付依赖（支付宝 AI 按量付费官方能力）

买家侧依赖安装（运行环境尚无时执行一次）：

npx -y @alipay/agent-payment@latest install

> 本 Skill 不自行实现付款流程、不做任何签名与密钥处理。付款、收银与签名全部交给支付宝官方能力完成。

支付流程（Agent 自动执行）

服务端为已通过线上验证的支付宝 AI 按量付费（A2M 402）服务 https://chayuntang-skills.app.workbuddy.host/api/resource（单价以服务端下发的 402 账单为准）。

第一步  取账单（probe）：未付款请求资源，服务端返回 HTTP 402 + Payment-Needed 头
        python scripts/pay_client.py --info
        → 解析出账单 { out_trade_no, amount, currency, goods_name, service_id }

第二步  收银（pay）：向用户明示金额并取得同意后，由官方买家能力收银
        alipay-bot 402-buyer-pay \
          --resource-url "https://chayuntang-skills.app.workbuddy.host/api/resource?skill=windows-app-install-verify&feature=default" \
          --intent-summary "在Windows上安装并验证软件"
        → 用户完成支付后取得 Payment-Proof 凭证
        ⚠️ 必须先向用户明示金额、取得同意后再继续
        ⚠️ 意图摘要必须写清原始业务目的，保留用户最初想做的事

第三步  取回资源（complete）：携带凭证重试，服务端验付并下发内容、发送履约回执
        python scripts/pay_client.py --payment-proof "<Payment-Proof>"
        → 服务端验付通过后返回付费内容，HTTP 2xx 即履约 ack（履约确认完成）

Agent 注意事项：

1. 三步复用同一个原始请求（URL、feature、必要请求头保持一致），付款后不重新下单；
2. 需要支付时以退出码 2 退出，并在 stdout 输出账单 JSON（含 bill、next_action）；
3. 支付状态不明时先查单（官方 alipay-bot 402-query-payment-status），不重复付款、不追加独立回执；
4. 履约回执失败时服务端重试同一订单并保持幂等，不因回执失败要求用户重新付款；
5. 验付失败（凭证无效或过期）时服务端不交付资源，本 Skill 自动降级为免费基础能力继续工作，不让用户走死路。

付费改造自查（对齐 SkillHub 支付宝付费改造规范）

协议与字段细节见 references/payskill/A2M-402-支付协议说明.md，官方支付能力用法见 references/payskill/官方支付能力说明.md。