feat: update preinstalled skills and CLI scripts, enhance packaging process, and add configuration for Windows and macOS

docs/Desktop-Packaging-Workflow.md

@@ -0,0 +1,344 @@
+# 桌面端打包流程
+
+本文用于梳理 `zn-ai` 当前仓库的 Windows / macOS 打包流程，说明应该先执行哪个脚本、每个脚本会自动带哪些前置步骤，以及常见使用场景。
+
+## 1. 先记结论
+
+如果你只是想正常出包，不需要手动先跑 `bundle-openclaw`、`bundle:preinstalled-skills`、`uv:download:*`。
+
+直接按目标平台执行：
+
+- Windows 安装包：`pnpm run package:win`
+- mac 双架构包：`pnpm run package:mac`
+- mac Intel 单架构包：`pnpm run package:mac:x64`
+- mac Apple Silicon 单架构包：`pnpm run package:mac:arm64`
+
+也就是说：
+
+- 要打 Windows 包，优先跑 `package:win`
+- 要打 mac 包，优先跑 `package:mac` 或具体架构脚本
+- `package` 只是“准备打包产物”，不是最终安装包命令
+- `build` 是“当前宿主机默认 electron-builder 打包”，不如平台脚本直观，日常不建议优先用
+
+## 2. 推荐执行顺序
+
+### 2.1 第一次打包或切分支后
+
+1. `pnpm install`
+2. `pnpm typecheck`
+3. 按目标平台执行对应脚本
+
+推荐命令：
+
+```powershell
+pnpm install
+pnpm typecheck
+pnpm run package:win
+```
+
+或：
+
+```powershell
+pnpm install
+pnpm typecheck
+pnpm run package:mac
+```
+
+### 2.2 日常出 Windows 包
+
+```powershell
+pnpm run package:win
+```
+
+### 2.3 日常出 mac 包
+
+如果希望一次出 x64 + arm64：
+
+```powershell
+pnpm run package:mac
+```
+
+如果只想出单一架构：
+
+```powershell
+pnpm run package:mac:x64
+```
+
+或：
+
+```powershell
+pnpm run package:mac:arm64
+```
+
+## 3. 各脚本职责
+
+### 3.1 `pnpm run package`
+
+这是“打包前准备阶段”，会自动执行：
+
+1. `prepackage`
+2. `vite build`
+3. `node scripts/bundle-openclaw.mjs`
+4. `zx scripts/bundle-preinstalled-skills.mjs`
+
+所以它会完成：
+
+- 检查并补齐平台所需的 bundled runtime binaries
+- 生成 `dist` 和 `dist-electron`
+- 生成 `build/openclaw`
+- 生成 `build/preinstalled-skills`
+
+但是它不会直接产出最终安装包。
+
+### 3.2 `pnpm run package:win`
+
+等价于：
+
+```powershell
+pnpm run package
+electron-builder --win --publish never
+```
+
+用途：
+
+- 产出 Windows NSIS 安装包
+- 当前配置只打 `x64`
+
+### 3.3 `pnpm run package:mac`
+
+等价于：
+
+```powershell
+pnpm run package
+electron-builder --mac --publish never
+```
+
+用途：
+
+- 产出 macOS 包
+- 当前配置目标包含 `dmg` 和 `zip`
+- 当前配置默认覆盖 `x64` 和 `arm64`
+
+### 3.4 `pnpm run build`
+
+等价于：
+
+```powershell
+pnpm run package
+electron-builder
+```
+
+特点：
+
+- 使用 `electron-builder.yml` 默认目标
+- 更适合“按宿主机默认配置整体打一遍”
+- 不如 `package:win` / `package:mac` 明确
+
+## 4. 打包时自动发生的事
+
+### 4.1 `prepackage`
+
+`prepackage` 会自动执行：
+
+```powershell
+node scripts/ensure-bundled-runtime-binaries.mjs
+```
+
+这一步会按当前平台检查 `resources/bin` 下的运行时文件是否齐全。
+
+当前规则：
+
+- Windows：检查 `uv.exe` 和 `node.exe`
+- macOS：检查 `uv`
+- Linux：检查 `uv`
+
+如果缺失，会自动调用对应下载脚本：
+
+- Windows：`uv:download:win`、`node:download:win`
+- macOS：`uv:download:mac`
+- Linux：`uv:download:linux`
+
+因此正常情况下，你不需要手动先跑这些下载脚本。
+
+### 4.2 `afterPack`
+
+`electron-builder` 打包后会自动执行：
+
+```powershell
+scripts/after-pack.cjs
+```
+
+它会继续完成这些动作：
+
+- 把 `resources/bin/<platform-arch>/...` 平铺复制到安装包里的 `resources/bin/`
+- 把 `electron/scripts` 处理到包内
+- 补拷 `playwright`、`playwright-core`、`chromium-bidi`、`bytenode`
+- 补拷 `build/openclaw`
+- 清理不必要的开发文件，缩小包体
+
+所以如果你是正常走 `package:win` / `package:mac`，这些都已经自动串好了。
+
+## 5. 什么时候手动跑单独脚本
+
+### 5.1 手动预拉 Windows 运行时
+
+如果你只是想提前把 Windows 运行时二进制准备好，可以执行：
+
+```powershell
+pnpm run prep:win-binaries
+```
+
+它会跑：
+
+```powershell
+pnpm run uv:download:win
+pnpm run node:download:win
+```
+
+适合场景：
+
+- 网络较慢，想在正式打包前先把依赖下载好
+- 排查 `resources/bin/win32-*` 是否齐全
+
+### 5.2 手动更新预装 skills
+
+如果你只想刷新预装 skills，不是正式出包，可以执行：
+
+```powershell
+pnpm run bundle:preinstalled-skills
+```
+
+### 5.3 手动更新 OpenClaw 运行时
+
+如果你只想刷新 `build/openclaw`，可以执行：
+
+```powershell
+pnpm run bundle:openclaw
+```
+
+## 6. 产物位置
+
+最终安装包 / 压缩包输出目录：
+
+```text
+release/
+```
+
+打包中间产物目录：
+
+```text
+dist/
+dist-electron/
+build/openclaw/
+build/preinstalled-skills/
+```
+
+## 7. Windows / mac 实操建议
+
+### 7.1 Windows
+
+推荐最简流程：
+
+```powershell
+pnpm install
+pnpm typecheck
+pnpm run package:win
+```
+
+说明：
+
+- 当前 `electron-builder.yml` 的 Windows 目标是 `nsis`
+- 当前只配置了 `x64`
+
+### 7.2 macOS
+
+推荐最简流程：
+
+```powershell
+pnpm install
+pnpm typecheck
+pnpm run package:mac
+```
+
+如果只打单架构：
+
+```powershell
+pnpm run package:mac:x64
+```
+
+或：
+
+```powershell
+pnpm run package:mac:arm64
+```
+
+如果只是本地快速验包，不追求最大压缩率：
+
+```powershell
+pnpm run package:mac:fast
+```
+
+如果想保留 `afterPack` 清理前的更多内容，便于本地排查：
+
+```powershell
+pnpm run package:mac:local
+```
+
+说明：
+
+- `package:mac:local` 会设置 `SKIP_AFTERPACK_CLEANUP=1`
+- 它不是跳过打包，而是跳过 `afterPack` 里的清理步骤
+
+## 8. 常见误区
+
+### 误区 1：先手动跑 `bundle-openclaw` 才能打包
+
+不是必须。
+
+因为 `package` 已经会自动执行：
+
+- `node scripts/bundle-openclaw.mjs`
+- `zx scripts/bundle-preinstalled-skills.mjs`
+
+### 误区 2：先手动跑 `uv:download:win` 才能打 Windows 包
+
+也不是必须。
+
+因为 `prepackage` 会自动执行 `ensure-bundled-runtime-binaries.mjs`，缺失时会自动下载。
+
+### 误区 3：`package` 就是最终出包命令
+
+不是。
+
+`package` 只做准备，不直接生成最终安装包；真正平台出包应使用：
+
+- `package:win`
+- `package:mac`
+- `package:mac:x64`
+- `package:mac:arm64`
+
+## 9. 建议你平时直接记住的命令
+
+### Windows
+
+```powershell
+pnpm run package:win
+```
+
+### macOS
+
+```powershell
+pnpm run package:mac
+```
+
+### 只做前置产物准备
+
+```powershell
+pnpm run package
+```
+
+### 只想检查类型
+
+```powershell
+pnpm typecheck
+```