Sync latest TrueGrowth updates

docs/DESKTOP_PACKAGING.md

@@ -6,7 +6,7 @@
 
 - 客户电脑不需要安装 Node.js、pnpm、Vite 或开发源码。
 - 安装包内置 TrueGrowth Web Renderer、Electron 桌面壳、Local API Gateway 和轻量运行脚本。
-- 本地模型、ComfyUI、FunClip、发布自动化浏览器等重运行时不默认塞进安装包；客户首次使用时从“模型中心”完成检测、下载、安装或登记已有目录。
+- 本地模型、ComfyUI、剪辑高级模型包、发布自动化浏览器等重运行时不默认塞进安装包；客户首次使用时从“模型中心”完成检测、下载、安装或登记已有目录。
 - 打包后的应用目录按只读处理，运行状态、模型、缓存、日志和输出写入当前用户目录：
   - macOS: `~/Library/Application Support/TrueGrowth/runtime`
   - Windows: `%APPDATA%/TrueGrowth/runtime`
@@ -32,7 +32,7 @@ export PATH="/usr/local/opt/node@20/bin:$PATH"
 pnpm desktop:build:dir
 ```
 
-生成 macOS 安装包：
+生成 macOS 内测安装包：
 
 ```bash
 pnpm desktop:build:mac
@@ -44,6 +44,13 @@ pnpm desktop:build:mac
 pnpm desktop:build:mac:dmg
 ```
 
+生成 macOS 商业客户包：
+
+```bash
+pnpm desktop:signing:check
+pnpm desktop:build:mac:signed
+```
+
 生成 Windows 安装包：
 
 ```bash
@@ -64,20 +71,79 @@ dist/desktop/release/
 
 ## macOS 商业分发
 
-macOS 可在 Mac 上构建。未签名包适合内部测试，商业交付建议准备 Apple Developer ID，并完成签名与公证。
+macOS 可在 Mac 上构建。未签名包只适合内部测试，商业交付必须使用 Developer ID Application 证书完成签名，并通过 Apple 公证。
 
-常用环境变量：
+### 证书判断
 
-```bash
-export CSC_LINK="/path/to/developer-id-application.p12"
-export CSC_KEY_PASSWORD="证书密码"
-export APPLE_ID="apple-id@example.com"
-export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
-export APPLE_TEAM_ID="TEAMID"
-pnpm desktop:build:mac
+本机证书目录中的常见文件含义：
+
+- `distribution.cer`: 如果证书类型是 `Apple Distribution`，它不适合作为官网、网盘或私有下载链接直接分发给客户的 macOS 桌面包证书。
+- `*.p12`: 需要证书密码才能确认里面的证书类型。商业客户包必须使用 `Developer ID Application` 类型的私钥证书包。
+- `AuthKey_<KEY_ID>.p8`: App Store Connect API Key，只用于公证上传认证，不用于代码签名。
+- `*.certSigningRequest`: 证书申请文件，不参与打包。
+
+当前本机钥匙串检查结果是 `0 valid identities found`，说明还没有可用的代码签名身份。客户分发前需要在 Apple Developer 后台创建并导出：
+
+```text
+Developer ID Application: <Company Name> (<TEAM_ID>)
 ```
 
-无证书时，Electron Builder 会生成未签名或临时签名产物。客户打开时可能遇到 Gatekeeper 提示，所以只能作为内测包。
+把该证书导出为 `.p12` 后，再配置签名环境。
+
+### 本机签名配置
+
+复制模板：
+
+```bash
+cp .env.desktop-signing.example .env.desktop-signing.local
+```
+
+填写 `.env.desktop-signing.local`：
+
+```bash
+CSC_LINK=/path/to/DeveloperIDApplication.p12
+CSC_KEY_PASSWORD=证书密码
+APPLE_API_KEY=/path/to/AuthKey_KEYID.p8
+APPLE_API_KEY_ID=KEYID
+APPLE_API_ISSUER=App Store Connect Issuer ID
+APPLE_TEAM_ID=TEAMID
+TRUEGROWTH_MAC_TARGETS=zip
+TRUEGROWTH_NOTARIZE=true
+```
+
+`.env.desktop-signing.local` 已被 `.gitignore` 忽略，不要提交。`APPLE_API_ISSUER` 在 App Store Connect 的 Users and Access / Integrations / App Store Connect API 页面查看。
+
+检查配置：
+
+```bash
+pnpm desktop:signing:check
+```
+
+检查通过后生成商业客户包：
+
+```bash
+pnpm desktop:build:mac:signed
+```
+
+这条命令会自动执行 Web 构建、桌面 staging、Electron Builder 签名、公证和更新清单生成。签名检查不通过时会直接失败，避免误把未签名包发给客户。
+
+当前构建机创建 DMG 曾出现 `hdiutil` `设备未配置`，所以默认商业配置建议先用 ZIP。macOS 自动更新也需要 ZIP 和 `.blockmap`。如果换到 DMG 正常的构建机，可把 `.env.desktop-signing.local` 改为：
+
+```bash
+TRUEGROWTH_MAC_TARGETS=zip dmg
+```
+
+### 验证签名和公证
+
+打包后至少执行：
+
+```bash
+codesign --verify --deep --strict dist/desktop/release/mac-arm64/TrueGrowth.app
+spctl --assess --type execute --verbose dist/desktop/release/mac-arm64/TrueGrowth.app
+xcrun stapler validate dist/desktop/release/mac-arm64/TrueGrowth.app
+```
+
+若 Electron Builder 输出路径随版本或架构变化，以实际 `dist/desktop/release/` 下的 `.app` 路径为准。
 
 ## Windows 商业分发
 
@@ -99,7 +165,7 @@ pnpm desktop:build:win
 - ComfyUI 安装或登记已有目录
 - Hugging Face 下载源选择
 - FLUX / Qwen-Image 等模型下载
-- FunClip / ASR / 发布自动化能力检查
+- VideoAgent 剪辑 / ASR / 发布自动化能力检查
 
 客户不需要手动运行仓库命令。需要管理员权限或外部安装器的步骤，会在模型中心以客户可理解的引导呈现。