Initial TrueGrowth source import

docs/DESKTOP_PACKAGING.md

@@ -0,0 +1,125 @@
+# TrueGrowth 桌面端商业打包流程
+
+本文档用于把 TrueGrowth 桌面端打包给 macOS 和 Windows 客户使用。
+
+## 交付原则
+
+- 客户电脑不需要安装 Node.js、pnpm、Vite 或开发源码。
+- 安装包内置 TrueGrowth Web Renderer、Electron 桌面壳、Local API Gateway 和轻量运行脚本。
+- 本地模型、ComfyUI、FunClip、发布自动化浏览器等重运行时不默认塞进安装包；客户首次使用时从“模型中心”完成检测、下载、安装或登记已有目录。
+- 打包后的应用目录按只读处理，运行状态、模型、缓存、日志和输出写入当前用户目录：
+  - macOS: `~/Library/Application Support/TrueGrowth/runtime`
+  - Windows: `%APPDATA%/TrueGrowth/runtime`
+
+## 本机准备
+
+```bash
+corepack enable pnpm
+pnpm install
+```
+
+建议使用 Node.js 20.19+。如果本机默认 Node 太旧，可临时使用：
+
+```bash
+export PATH="/usr/local/opt/node@20/bin:$PATH"
+```
+
+## 常用打包命令
+
+生成当前平台可运行目录，适合快速检查：
+
+```bash
+pnpm desktop:build:dir
+```
+
+生成 macOS 安装包：
+
+```bash
+pnpm desktop:build:mac
+```
+
+默认生成 macOS ZIP。若构建机的 `hdiutil` 可用并且需要 DMG，可执行：
+
+```bash
+pnpm desktop:build:mac:dmg
+```
+
+生成 Windows 安装包：
+
+```bash
+pnpm desktop:build:win
+```
+
+一条命令会依次执行：
+
+1. `pnpm build:web` 构建生产 Web Renderer。
+2. `pnpm desktop:prepare` 生成图标并把运行所需文件 staged 到 `dist/desktop/app`。
+3. `electron-builder --config electron-builder.yml` 生成桌面端产物。
+
+产物输出目录：
+
+```text
+dist/desktop/release/
+```
+
+## macOS 商业分发
+
+macOS 可在 Mac 上构建。未签名包适合内部测试，商业交付建议准备 Apple Developer ID，并完成签名与公证。
+
+常用环境变量：
+
+```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
+```
+
+无证书时，Electron Builder 会生成未签名或临时签名产物。客户打开时可能遇到 Gatekeeper 提示，所以只能作为内测包。
+
+## Windows 商业分发
+
+Windows 正式安装包建议在 Windows 电脑或 Windows CI runner 上构建：
+
+```bash
+corepack enable pnpm
+pnpm install
+pnpm desktop:build:win
+```
+
+商业分发建议准备 Authenticode 代码签名证书。macOS 上可以尝试交叉构建 Windows 包，但不建议把 macOS 交叉构建结果作为最终商业交付包，尤其是签名、杀软信誉和安装体验都应在 Windows 环境验证。
+
+## 客户首次运行
+
+客户安装并打开 TrueGrowth 后，基础工作台、素材、任务、画布和 Local API 会随应用启动。需要本地模型或重运行时的功能，从“模型中心”完成：
+
+- 系统环境检测
+- ComfyUI 安装或登记已有目录
+- Hugging Face 下载源选择
+- FLUX / Qwen-Image 等模型下载
+- FunClip / ASR / 发布自动化能力检查
+
+客户不需要手动运行仓库命令。需要管理员权限或外部安装器的步骤，会在模型中心以客户可理解的引导呈现。
+
+## 验证清单
+
+每次发客户包前至少检查：
+
+- `pnpm build:web` 成功。
+- `pnpm desktop:prepare` 成功，并生成 `dist/desktop/app`。
+- `pnpm desktop:build:dir` 或目标平台打包命令成功。
+- 启动打包后的应用，确认不是加载 `127.0.0.1:7200` 开发服务。
+- 打开模型中心，确认运行目录显示为用户目录，不是应用安装目录。
+- 打开 `/local-api/health` 或模型中心状态，确认 Local API 已启动。
+- macOS 商业包完成签名/公证；Windows 商业包完成签名并在真实 Windows 电脑安装测试。
+
+## 空间建议
+
+构建机至少预留：
+
+- Web + Electron 打包临时空间：10GB+
+- 如果要本机测试下载模型：额外 80GB+
+
+仓库中的 `vendor/ComfyUI/models`、Python `.venv`、缓存和运行输出不会被默认复制进安装包。它们应由客户首次运行后在模型中心按需准备。