Electron Mac Packaging

Electron 桌面打包规范（macOS + Windows）

面向 AI Media Agent 的 Electron 桌面版（electron/）。打包前必读，避免 logo 占位图、Python/Node 安装失败、Windows 端口 8000 冲突或 Backend 误报 Error。

何时使用

• 用户说：打 DMG、打 Windows 包、打包、发版、build mac / build win
• 修改 electron/main.js 安装/venv/pip/Node/Python/端口/服务生命周期/backend 同步/内嵌控制台/splash
• 修改 electron/renderer/（status/setup/splash）或 preload.js 的 IPC
• 修改 backend/ 新增 API 路由（如 /agent/chat/stream）后需重新打包并验证 APP_DATA 同步
• Sidebar/登录页 logo 空白；安装向导无进度；Node 安装失败；Backend :8000 Error
• 桌面包 Pexels/Pixabay 无素材、PEXELS_API_KEY not configured、一键短视频拿不到 stock footage

包类型选择（必读 — 勿用错脚本）

用户说「打 Windows 包 / 打包 / env 打进包 / 开箱即用」→ 一律走 electron/build_win.sh，禁止默认跑 build_windows.sh。

发版后必跑（build_win.sh Step 8 已自动执行）：

bash electron/scripts/verify_win_zip.sh "$(pwd)" "electron/dist/AI Media Agent-<ver>-win.zip"

另遵守 windows-package-compat skill：staging 用 storage/temp/、zip 用 zip -r -X、排除 node_modules/.git/.DS_Store、检查超长路径。

开箱即用（OOB）功能矩阵 — Windows zip

构建机 backend/.env 在 Step 4 复制为 resources/backend/.env.bundled；首次启动 mergeBundledEnvDefaults() 合并到 %APPDATA%/ai-media-agent/backend/.env。用户无需手配 env。

桌宠 Step 5b 失败 = 构建失败（≥1.8.0，不再告警跳过）。前置：brew install mingw-w64 + rustup target add x86_64-pc-windows-gnu。

安装向导日志（≥1.8.1）：首次安装过程写入 %APPDATA%/ai-media-agent/logs/install.log（向导内可滚动查看 +「打开日志文件」）；每行含时间戳、步骤名、进度与详情。

macOS 快速命令

# 无 Developer ID（分发给其他 Mac，需 Install.app 或 dmg-install.sh）
cd electron && ./build_mac.sh arm64 unsigned

# 有 Developer ID + 公证（mac-build.env 已配置）
cd electron && ./build_mac.sh arm64

# 仅生成 logo/icon（推荐用 venv Python，确保有 Pillow）
./venv/bin/python3 electron/scripts/create_icons.py

# 仅校验 logo/icon/Python  tarball（不打包）
bash electron/scripts/validate_packaging_assets.sh "$(pwd)" resources

产物：electron/dist/AI Media Agent-<version>-arm64.dmg（dist/ 在 .gitignore，不入库）

含内置 Python 后 DMG 约 270MB（含 Next standalone + 运行时）。

macOS 运行时体验（≥1.0.37）

Mac 与 Windows 统一为内嵌控制台，不再 shell.openExternal 跳 Safari/Chrome：

Dashboard 窗口选项（Mac + Windows 共用）：

• frame: true — 标准标题栏，避免 titleBarOverlay 盖住页面右上角按钮（如「对话设置」）
• dashboardWindowNeedsReload(url) — 仅在窗口不存在或 URL 变化时 loadURL，禁止每次 health poll 重载（否则聊天输入被清空）
• dashboardAutoOpened — 仅自动打开一次

启动时序（已安装、非向导）：

app.ready → startAllServices()
  → showSplashWindow + sendStartupProgress
  → syncAppResources + post-sync pip
  → ensurePlaywrightBrowsersReady（Mac 后台；Win 另 schedulePlaywrightInstall）
  → launchAllServices (backend → frontend)
  → pollHealth(frontend) → maybeAutoOpenDashboard
  → closeSplashWindow + openDashboardWindow

Renderer 文件（须打进 asarUnpack）：

electron/renderer/
  splash.html / splash.css / splash.js   # 启动进度
  status.html  / status.css  / status.js # 服务状态
  setup.html   / setup.css   / setup.js  # 安装向导
electron/preload.js                      # onStartupProgress IPC

electron/package.json：

"files": ["main.js", "preload.js", "renderer/**/*", "!resources/**"],
"asarUnpack": ["renderer/**/*"]

Windows 专项：file:// 加载 setup/status 时，内联 <style> + CSP 会被当作文本显示；必须外置 *.css（见故障排查）。Mac 同样使用外置 CSS，但现象主要在 Windows 暴露。

覆盖升级（同版本号换包时必读）

electron/package.json 的 version（如 1.0.37）与 bundle revision（如 1.0.37-3e8a583，写入 resources/backend/.bundle_revision）是两套标识：

仅换 DMG、版本号不变 时，用户可能跳过安装向导，旧 backend 仍留在 APP_DATA → 新前端调新 API 会 404。

发版后告知用户（覆盖安装）：

# 1. 完全退出应用（托盘 → 退出）
# 2. 安装新 DMG 到「应用程序」
# 3. 清除 backend 同步戳，强制下次启动重拷
rm -f ~/Library/Application\ Support/ai-media-agent/.resource_bundle_version
# 4. 重新打开应用（会自动 sync backend + 刷新 pip）

≥1.0.37 的 main.js 已在 每次 startAllServices() 调用 syncAppResources()，并检查哨兵文件 routers/agent_chat_router.py；缺文件时强制同步。

Windows 快速命令

前置（Mac 上交叉编译桌宠）：brew install mingw-w64 + rustup target add x86_64-pc-windows-gnu。缺失则 Step 5b 失败，整包构建中断。

# 推荐：zip + portable（Mac 上无 Wine 时默认，已自动跳过 rcedit）
cd electron && ./build_win.sh

# 仅 zip + portable
cd electron && ./build_win.sh portable

# NSIS 安装包（需 Wine：brew install --cask wine-stable）
cd electron && ./build_win.sh nsis

# 仅重编桌宠 exe（含陪伴室 signal / 语音修复后单独重打）
bash electron/scripts/bundle_desktop_pet_win.sh

# 校验 Windows 资源（不打包）
bash electron/scripts/validate_packaging_assets.sh "$(pwd)" win-resources
bash electron/scripts/validate_packaging_assets.sh "$(pwd)" win-unpacked electron/dist/win-unpacked

# 发版后 zip 开箱即用验证（build_win.sh Step 8 自动跑；也可手动）
bash electron/scripts/verify_win_zip.sh "$(pwd)" "electron/dist/AI Media Agent-<ver>-win.zip"

Windows rcedit / Wine 失败（必读）

Mac/Linux 上 electron-builder 用 rcedit（经 Wine）给 .exe 写版本号 + 图标元数据。Wine 失效时报：

wineserver: Can't check in server_mach_port
wine: for some mysterious reason, the wine server failed to run.
⨯ cannot execute  cause=exit status 1   (rcedit-x64.exe …)

• 注意：此时 win-unpacked/ 通常已打包完成（含全部 resources），仅最后写元数据失败 → 整体 exit 1。
• ≥1.7.0 的 build_win.sh 已自动处理：无 Wine 时 build_portable_zip() 追加 --config.win.signAndEditExecutable=false，跳过 rcedit。
• 手动绕过（脚本中断 / 旧版脚本）：

cd electron
npx electron-builder --win --x64 --config.win.target=portable --config.win.signAndEditExecutable=false
npx electron-builder --win --x64 --config.win.target=zip --config.win.signAndEditExecutable=false

• 影响：仅 exe 文件属性里的版本号/产品名/图标元数据缺失，不影响运行。要完整元数据需在 Windows 机器构建或装可用 Wine。

Windows 产物（electron/dist/）

用户数据：%APPDATA%/ai-media-agent/

Windows 7 步构建（build_win.sh）

桌宠 (Boni) Windows Sidecar 打包

桌宠是独立 Tauri 2 进程（desktop-pet/），随数字员工安装包附带（非单独 zip）。

改了 desktop-pet/ 的 Rust/Svelte 后：必须 bash electron/scripts/bundle_desktop_pet_win.sh 重编 exe，再重打 Electron 包（或直接 ./build_win.sh，Step 5b 会自动重编）。

陪伴室跨进程唤起（≥1.7.0）：桌宠点「打开陪伴室」不再跳系统浏览器，而是经 signal 文件让 Electron 主窗口打开：

桌宠 Svelte openConsole()
  → Tauri 命令 open_app_console (lib.rs)
  → backend_client::request_open_console("/companion")
  → 写 APP_DATA/desktop-pet/open-console.signal  {"path":"/companion"}
Electron startDesktopPetConsoleWatcher() 轮询该文件
  → openDashboardWindow({ path: '/companion' }) 打开/聚焦内嵌控制台
  → 删除 signal 文件

• 桌宠未由 Electron 托管（独立 tauri:dev）时，request_open_console 返回 false → Svelte 回退 open() 系统浏览器。
• 关键文件：desktop-pet/src-tauri/src/{lib.rs,backend_client.rs}、desktop-pet/src/App.svelte、electron/main.js（startDesktopPetConsoleWatcher / openDashboardWindow / dashboardOnPath）。

桌宠启动「超时/WebView2」误报（已修，≥1.7.0）：detached GUI 进程会让 spawn 提前返回，旧逻辑误判为失败。main.js 已用 isPidAlive() + 20s 超时 + isDesktopPetProcessRunning() 容错，并由 startDesktopPetMonitor() 持续同步状态。

语音识别 (STT) — qwen3-asr-flash

桌宠语音输入链路：Svelte MediaRecorder(webm/opus) → /companion/pet/transcribe → DashScope Qwen ASR（webm 直传）；失败时 ffmpeg 转 wav → 智谱/Whisper 兜底。

改了 audio_tools.py / companion_pet_router.py 后属 backend 变更：重打包即自动进 resources/backend/（Step 4 全量刷新），并依赖 syncAppResources 同步到 APP_DATA。

Windows 内置 Node（必读）

安装期 禁止依赖系统 Node 或错误地下载 macOS 版 Node：

main.js 关键函数：

• installNodeFromBundledRuntime() — 优先 copy 内置 runtime
• extractNodeZipPowerShell() — zip 解压兜底（tar 不可用时）
• ensureNodeRuntime() — 打包版强制 portable Node

安装向导应显示 「复制内置 Node.js 运行时…」。

Windows 端口 8000（WinError 10013）

main.js 已实现：

• collectPidsOnPort() — 完整 netstat -ano -p tcp（支持中文「侦听」）
• resolveBackendPort() — 候选端口 8000,8010,8020,8030,8080,8888,18000
• retryBackendOnNextPort() — 绑定失败自动换端口
• Frontend BACKEND_URL 跟随 SERVICES.backend.port

排查占用：

netstat -ano -p tcp | findstr :8000
taskkill /F /PID <pid> /T

Windows Backend 误报 Error（已修复）

旧进程 close 事件覆盖新进程状态，Scheduler INFO 被当成错误：

• spawnService 用 svc.proc !== proc 忽略过期进程事件
• isBenignServiceLog() 过滤 Scheduler stopped / Uvicorn startup
• stopAllServices 用 taskkill /F /T

Windows 安装向导

• setup-ui-ready IPC：UI 就绪后再 runSetup，避免无进度
• pip 依赖按 requirements.txt 哈希跳过重复安装
• Playwright 在 Windows 后台安装，缩短首次向导时间
• syncAppResources() 按版本增量复制 backend

Windows package.json 要点

"win": {
  "target": [{ "target": "zip" }, { "target": "nsis" }],
  "requestedExecutionLevel": "asInvoker"
}

• asInvoker：无需管理员即可运行（旧版 requireAdministrator 易引发权限/端口问题）
• create_icons.py 生成 icon.ico（electron-builder 要求 256×256 为首帧）

Windows 构建缓存（勿提交 git）

electron/resources/python/*.tar.gz
electron/resources/node/

构建时 Step 0b/0c 自动下载；.gitignore 已忽略。

打包前检查清单

复制 checklist.md 逐项确认；核心项：

- [ ] electron/package.json version 已递增
- [ ] electron/assets/logo.png 存在且已 git track
- [ ] ./venv/bin/python3 electron/scripts/create_icons.py 成功（勿只用无 Pillow 的系统 python3）
- [ ] web/public/brand-logo.png 与 logo.png MD5 一致（或体积均 >50KB，非 ~4KB 占位图）
- [ ] electron/resources/python/cpython-3.12.13+20260510-*-apple-darwin-install_only.tar.gz 存在
- [ ] backend 变更已能通过 build 脚本进入 resources/backend（含 routers/、agents/）
- [ ] Next build 输出含 `ƒ /api/agent/chat/stream`（LangGraph 代理路由）
- [ ] `electron/renderer/splash.*`、`status.*`、`setup.*` 外置 CSS 齐全；`asarUnpack` 含 `renderer/**/*`
- [ ] Mac/Win 控制台为内嵌 `openDashboardWindow`（非 openExternal）
- [ ] validate_packaging_assets.sh resources + app-bundle 均通过
- [ ] `electron/main.js` 含 `mergeBundledEnvDefaults()`（每次 `startAllServices` + `runSetup`）
- [ ] 构建机 `backend/.env` 含发版所需 Key；构建日志有 `.env.bundled`
- [ ] 未将 developer 证书/私钥、`.env.bundled` 构建产物提交到 git

macOS 发版流程（推荐顺序）

1. Bump electron/package.json version（对外发版；同版本热修复可只依赖 git hash 更新 .bundle_revision）
2. 确认 backend/ 新模块在 build_mac.sh Step 4 copy 列表内
3. 构建 cd electron && ./build_mac.sh arm64（或 unsigned）
4. 验包 Step 8 validate 通过；检查 resources/backend/.bundle_revision
5. 挂载 DMG 或解包 抽查 .app 内 resources/backend/routers/agent_chat_router.py
6. 安装冒烟（见文末命令）：health + /agent/chat/stream 200 + 内嵌控制台 + Playwright + stock_keys
7. 分发说明：覆盖安装用户需删 .resource_bundle_version 或依赖新版 main.js 自动 sync；新 API Key 依赖 .env.bundled 合并
8. 勿提交 dist/、证书、python tarball、electron/resources/web-standalone/public/public/（Next 误产物）

品牌 Logo（禁止变成紫色火箭）

根因（必读）

来源与引用

生成

# 必须：build_mac.sh 使用 venv Python；手动时也同理
./venv/bin/python3 electron/scripts/create_icons.py

脚本行为：

1. 优先 Pillow；缺失时尝试 pip install pillow 或 macOS sips fallback
2. brand-logo.png = shutil.copy2(logo.png)，不是火箭占位图
3. icon.icns 从 logo 等比 fit 到 square canvas
4. 若 web-standalone/public 已存在则同步 brand-logo

构建顺序（强制）

build_mac.sh 约定：

1. Step 0 — 检查 electron/assets/logo.png 存在 → create_icons.py（venv Python）
2. Step 0b — 下载/缓存 Python tarball 到 electron/resources/python/（见下节）
3. Step 0 末 — validate_packaging_assets.sh resources（含 logo 体积校验 + bundled Python）
4. Step 3 — Next standalone 复制 public/，并 cp brand-logo.png 双保险
5. Step 6 — 再次 cp brand-logo 到 standalone
6. Step 8 — validate … app-bundle 校验 .app 内 logo + Python

.gitignore 例外

根目录 *.png / *.html 忽略，必须保留：

!web/public/brand-logo.png
!electron/assets/logo.png
!electron/resources/web-standalone/public/brand-logo.png
!mobile/**/*.html

Python tarball 不入库（构建时下载）：

electron/resources/python/*.tar.gz
electron/resources/node/
electron/resources/backend/.env.bundled

切勿提交：

• developer_id_private.key、developerID_application.cer
• electron/dist/、backend/published_content.json
• electron/resources/web-standalone/public/public/（重复 public 目录，构建偶发产物）
• electron/resources/backend/.env.bundled（构建时从 backend/.env 生成，含密钥）

内置 Python 运行时（安装时不依赖 GitHub）

构建期

Step 0b 将 python-build-standalone 下载到：

electron/resources/python/cpython-3.12.13+20260510-{aarch64|x86_64}-apple-darwin-install_only.tar.gz

经 extraResources 打进 .app/Contents/Resources/resources/python/。

安装期（main.js）

用户数据目录：~/Library/Application Support/ai-media-agent/

• python-dist/ — 解压后的 Python 3.12
• venv/ — pip 依赖与 Playwright
• node/ — portable Node.js（Frontend 用）
• .browsers/ — Playwright Chromium（由 Electron 注入 PLAYWRIGHT_BROWSERS_PATH）
• .playwright_browser_stamp — 已安装 Chromium 对应的 playwright 包版本
• .setup_done / .app_version — 安装状态

Playwright 浏览器（macOS / Windows 共用）

桌面包的平台登录、浏览器 RPA 依赖 Chromium；路径必须与 backend 一致。

Electron 侧（main.js）

Backend 侧（须同步进 bundle）

打包后 backend 从 APP_DATA 启动，须尊重环境变量，勿硬编码项目根 .browsers：

修改上述文件后 必须重打 DMG，并确认 syncAppResources 已把新 backend 拷到 APP_DATA。

内置 Node.js 运行时（Frontend :3000）

打包版 macOS 禁止依赖 Homebrew node：

安装向导若跳过 Node 下载会导致 Frontend 报 「Node.js 未安装，请重新运行安装向导」。

8 步构建流程

环境变量与 .env.bundled（API Key 进包必读）

桌面包 不会直接把 backend/.env 打进 DMG 的 backend 源码目录（避免 syncAppResources 覆盖用户 LLM Key）。
构建机上的 backend/.env 以 只读 defaults 形式进入安装包，启动时再合并到用户目录。

三份 .env 各是什么

macOS：~/Library/Application Support/ai-media-agent/backend/.env
Windows：%APPDATA%/ai-media-agent/backend/.env

构建期（build_mac.sh / build_win.sh Step 4）

for f in main.py requirements.txt .env.example; do …
# 若构建机存在 backend/.env → 复制为 resources/backend/.env.bundled
if [ -f "$ROOT_DIR/backend/.env" ]; then
  cp "$ROOT_DIR/backend/.env" "$BACKEND_RES/.env.bundled"
fi

• 复制的是 整份 构建机 backend/.env（含 PEXELS_API_KEY、ZHIPUAI_API_KEY 等）
• .env.bundled 经 extraResources 进 .app，不参与 copyDir 覆盖 APP_DATA/backend/ 源码树
• .gitignore：electron/resources/backend/.env.bundled（构建产物，勿提交）

运行期（main.js）

调用时机：

• runSetup() 在 syncAppResources() 之后
• 每次 startAllServices() 在 syncAppResources() 之后（覆盖升级也能补新 Key）

合并规则（重要）：

• bundled 有、用户 .env 无或空 → 写入
• 用户 .env 已有非空值 → 不覆盖（保护用户自配 LLM Key）
• 新增功能 Key（如 PEXELS_API_KEY）发版后：用户重启 App 即可自动合并，无需重装向导

Backend 侧：main.py 的 load_dotenv() + Electron buildEnv() 双路径；桌面包以 buildEnv() 注入为准。

常见 Key 与功能

发版前检查

1. 构建机 backend/.env 含所需 Key（或 CI 构建前写入）
2. 构建日志出现 Bundled env defaults → …/.env.bundled
3. 挂载 DMG 抽查：.app/Contents/Resources/resources/backend/.env.bundled 存在且含 PEXELS_API_KEY=
4. 安装后：grep PEXELS ~/Library/Application\ Support/ai-media-agent/backend/.env

故障：打包后 Pexels 仍无数据

临时手动修复（不重打包）：

# macOS
grep -q '^PEXELS_API_KEY=' ~/Library/Application\ Support/ai-media-agent/backend/.env \
  || echo 'PEXELS_API_KEY=你的key' >> ~/Library/Application\ Support/ai-media-agent/backend/.env

验证 API：

curl -s http://127.0.0.1:8000/tools/video/auto/config/voices | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print('pexels:', d.get('stock_keys',{}).get('pexels'))"
# 期望 pexels: True

Backend 双副本与同步（macOS / Windows 共用逻辑）

运行时 不直接读 .app 内 resources/backend/，而是复制到用户目录后启动：

.app/Contents/Resources/resources/backend/   ← 构建期 bundle（只读来源）
        ↓ syncAppResources()
~/Library/Application Support/ai-media-agent/backend/   ← uvicorn cwd（macOS）
%APPDATA%/ai-media-agent/backend/                      ← uvicorn cwd（Windows）

syncAppResources() 触发条件（main.js）

同步 当且仅当 以下任一成立：

1. .resource_bundle_version ≠ .bundle_revision
2. APP_DATA/backend/main.py 不存在
3. APP_DATA/backend/routers/agent_chat_router.py 不存在（哨兵）

同步后：

• copyDir(RES_BACKEND → BACKEND_DATA) 覆盖 backend 源码
• 写入 .resource_bundle_version
• startAllServices() 若刚同步且 venv 就绪 → 调用 installPythonDependencies() 刷新 pip（新依赖如 aiosqlite）

历史坑：旧版仅在安装向导 / Python repair 时 sync，正常启动不同步 → 新前端 + 旧 backend → /agent/chat/stream 404。

build_mac.sh Step 4 复制范围

for d in agents core tools utils routers services admin; do
  cp -r backend/$d → resources/backend/
done
for f in main.py requirements.txt .env.example; do …
# 若存在 backend/.env → resources/backend/.env.bundled
echo "${PKG_VERSION}-${GIT_REV}" > resources/backend/.bundle_revision

新增 backend 模块时：若目录不在上述列表，必须改 build_mac.sh / build_win.sh 的 copy 循环，否则不会进包。

LangGraph 统一聊天 API（≥1.0.37）

Next 代理在 backend 404 时会 fallback 到 /multi-agent/stream（兼容未同步的旧 APP_DATA）。

打包后必验（backend 就绪后）：

# 应返回 200（SSE），不是 404
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8000/agent/chat/stream \
  -H "Content-Type: application/json" -d '{"input":"你好","mode":"direct"}'

# OpenAPI 应含新路由
curl -s http://127.0.0.1:8000/openapi.json | python3 -c \
  "import sys,json; print([p for p in json.load(sys.stdin)['paths'] if 'agent/chat' in p])"
# 期望: ['/agent/chat/invoke', '/agent/chat/stream']

APP_DATA 内人工检查：

ls ~/Library/Application\ Support/ai-media-agent/backend/routers/agent_chat_router.py
cat ~/Library/Application\ Support/ai-media-agent/backend/.resource_bundle_version
# 应与 .app 内 bundle_revision 一致

版本与 pip

• 版本号：改 electron/package.json 的 version；build_mac.sh 同时写入 resources/backend/.bundle_revision
• 同版本热修复：只改 backend/前端逻辑、不 bump version 时，仍会因 git hash 变化更新 .bundle_revision；依赖 syncAppResources 或用户手动删 .resource_bundle_version
• pip：macOS 用 python -m pip；backend sync 后自动 installPythonDependencies；检测 ~ip 损坏包并重建 venv
• Playwright：安装向导内可跳过；≥1.0.37 每次 startAllServices() 会 ensurePlaywrightBrowsersReady（Mac 后台装，Win 另起线程）；stamp 文件 .playwright_browser_stamp 与 playwright 包版本对齐
• LangGraph checkpoint 依赖：requirements.txt 含 langgraph-checkpoint-sqlite、aiosqlite；backend sync 后 pip 会增量安装

详见 electron/main.js：runSetup、autoCleanupBeforeInstall、installPythonDependencies、ensureNodeRuntime、ensurePlaywrightBrowsersReady、openDashboardWindow。

签名与分发

• ad-hoc 签名：electron/scripts/afterPack.js + disable-library-validation entitlement
• 不要恢复 DMG 内已删除的 .command 方式一（Gatekeeper 易报「已损坏」）

发版 commit 建议

git add electron/package.json electron/main.js electron/build_mac.sh electron/build_win.sh \
  electron/preload.js electron/renderer/ \
  backend/.env.example \
  electron/scripts/ electron/assets/logo.png web/public/brand-logo.png \
  .agent/skills/electron-mac-packaging/ .gitignore
git commit -m "fix(electron): … — bump vX.Y.Z"
git push origin HEAD

勿提交：

• developer_id_private.key、developerID_application.cer
• electron/dist/、electron/resources/python/*.tar.gz、electron/resources/node/
• backend/published_content.json 等运行时数据
• electron/resources/web-standalone/public/public/（构建误产物）

故障排查

Windows 故障排查

macOS 安装冒烟命令

# 覆盖升级：强制 backend 重同步（可选）
rm -f ~/Library/Application\ Support/ai-media-agent/.resource_bundle_version

# 可选：干净重装（会清 venv）
# rm -f ~/Library/Application\ Support/ai-media-agent/.setup_done

# 安装后验证 — 基础服务
curl -sI http://127.0.0.1:3000/brand-logo.png | head -1   # HTTP/1.1 200
curl -sI http://127.0.0.1:8000/health | head -1             # HTTP/1.1 200
ls ~/Library/Application\ Support/ai-media-agent/node/bin/node
ls ~/Library/Application\ Support/ai-media-agent/python-dist/bin/python3

# LangGraph 统一入口（≥1.0.37）
curl -s -o /dev/null -w "agent-chat:%{http_code}\n" -X POST http://127.0.0.1:8000/agent/chat/stream \
  -H "Content-Type: application/json" -d '{"input":"ping","mode":"direct"}'
# 期望 agent-chat:200

# 内嵌控制台（手动：托盘 → Open Dashboard；自动：Frontend Running 后应弹出窗口，非 Safari）
# 若仍跳浏览器 → DMG 内 main.js 过旧

# Playwright Chromium（交互式登录 / 浏览器 RPA）
CHROME="$HOME/Library/Application Support/ai-media-agent/.browsers/chromium-"*/chrome-mac-arm64/Google\ Chrome\ for\ Testing.app/Contents/MacOS/Google\ Chrome\ for\ Testing
test -x "$CHROME" && echo "playwright:ok" || echo "playwright:missing"
# 若 missing，手动安装：
# PLAYWRIGHT_BROWSERS_PATH="$HOME/Library/Application Support/ai-media-agent/.browsers" \
#   "$HOME/Library/Application Support/ai-media-agent/venv/bin/python" -m playwright install chromium

# APP_DATA backend 与 bundle 一致
cat ~/Library/Application\ Support/ai-media-agent/backend/.resource_bundle_version
# 应与 DMG 内 resources/backend/.bundle_revision 相同（若可挂载 DMG 查看）
test -f ~/Library/Application\ Support/ai-media-agent/backend/routers/agent_chat_router.py && echo "langgraph router ok"

# 一键短视频 / Pexels（需 backend/.env 在构建时打进 .env.bundled）
curl -s http://127.0.0.1:8000/tools/video/auto/config/voices | python3 -c \
  "import sys,json; sk=json.load(sys.stdin).get('stock_keys',{}); print('pexels:', sk.get('pexels'), 'pixabay:', sk.get('pixabay'))"
grep -E '^PEXELS_API_KEY=' ~/Library/Application\ Support/ai-media-agent/backend/.env || echo "PEXELS missing in APP_DATA .env"

Windows 安装冒烟

# 安装向导完成后
curl -sI http://127.0.0.1:8000/health
curl -sI http://127.0.0.1:3000/
dir "$env:APPDATA\ai-media-agent\node\node.exe"
type "$env:APPDATA\ai-media-agent\.backend_port"   # 若非 8000 说明发生过端口切换

附加资源

• 详细检查表：checklist.md
• macOS 安装说明：electron/resources/安装说明.txt
• 项目文档：docs/WINDOWS_DEPLOYMENT.md
• iOS 全屏客户端（连接局域网/云端 :3000，非本地 Python）：mobile/README.md + mobile/build_ios.sh
• 桌宠 Sidecar（Tauri 2）（连接本机 FastAPI :8000，依赖 Electron/start_local.sh 已启动 backend）：
  • 工程：desktop-pet/
  • 文档：docs/DESKTOP_PET.md
  • 开发：cd desktop-pet && npm install && npm run tauri:dev
  • 构建：cd desktop-pet && npm run tauri:build → src-tauri/target/release/bundle/macos/*.app
  • DMG 可选附带：将 desktop-pet.app 复制到 electron/dist/mac-arm64/AI Media Agent.app/Contents/Resources/desktop-pet.app，或在 DMG 根目录增加「桌宠」快捷方式；Electron 菜单可 shell.openPath 启动
  • 不打包 .env / API Key；桌宠只连 :8000，密钥由 backend APP_DATA .env + .env.bundled 提供
  • 本地闲聊可选 Ollama（OLLAMA_BASE_URL / OLLAMA_MODEL 见 backend/.env.example）

mac-build.env（签名 + 公证，可选）

有 Developer ID Application 证书时，在 electron/mac-build.env（gitignore）配置：

APPLE_ID=your@email.com
APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx
# 可选：APPLE_TEAM_ID=XXXXXXXXXX

然后执行 cd electron && ./build_mac.sh arm64（无 unsigned）。build_mac.sh 会：

1. 用 Keychain 中第一个 Developer ID Application: 身份签名 Install.app
2. electron-builder 签名 .app + DMG
3. 若 APPLE_ID 有效 → scripts/notarize.js 公证

无效占位凭据会被自动 unset，避免 electron-builder 公证步骤失败。