# visionA Agent — Build Pipeline 驗證報告

> AB12 產出。驗證三平台 build pipeline 設定是否正確，以及 macOS 實際 build 結果。
> 最後驗證日期：2026-04-22（jimchen 的 macOS 13 開發機）

## 三平台預期輸出

| 平台 | 產出路徑 | 格式 | 參考大小 | 備註 |
|------|---------|------|---------|------|
| macOS | `dist/visiona-agent.dmg` | zlib-compressed UDZO DMG | ~160 MB | x86_64 Intel，LSMinimumSystemVersion 10.13 |
| Windows | `dist/visiona-agent-<ver>-windows-x64.exe` | Inno Setup self-extracting EXE | ~180 MB（估） | MinVersion 10.0.17763（Win10 1809+） |
| Linux | `dist/visiona-agent-<ver>-linux-x64.AppImage` | AppImage（FUSE 可執行） | ~180 MB（估） | glibc 2.35+（Ubuntu 22.04 build） |

## 環境需求

### 共通
- Go 1.26+
- Node 22.x + pnpm 9（或 10）
- Wails CLI v2.12+（`go install github.com/wailsapp/wails/v2/cmd/wails@latest`）
- curl

### macOS 專屬
- Xcode Command Line Tools（clang、codesign）
- `brew install create-dmg`（美化 DMG；未裝則 fallback 到 plain `hdiutil` DMG）
- （只有升級 ffmpeg 時）`brew install pkg-config nasm`

### Windows 專屬（只在 Windows runner 上跑）
- Inno Setup 6+（`choco install innosetup`）
- Git Bash / MSYS（用 bash 跑 Makefile）
- 真實 Python（非 WindowsApps stub）— 給 `pip download` 公開 wheels 用

### Linux 專屬（只在 Linux runner 上跑）
- `libgtk-3-dev libwebkit2gtk-4.1-dev libusb-1.0-0-dev`
- `fuse libfuse2`（AppImage 執行需要）
- `desktop-file-utils`
- `appimagetool`（從 AppImage releases 下載）

## 已驗證項目

| 項目 | 狀態 | 驗證方式 |
|------|------|---------|
| macOS DMG 本機 build | ✅ 通過 | 本地 `make dmg` 跑過（160 MB zlib UDZO，hdiutil attach OK） |
| macOS Info.plist Bundle ID | ✅ 通過 | `com.innovedus.visiona-agent`（與 local-tool 不衝突） |
| macOS App 內嵌 payload 完整 | ✅ 通過 | Contents/Resources/ 下 bin / data / scripts / python / wheels 齊備 |
| macOS App ad-hoc codesign | ✅ 通過 | `codesign --verify` 通過 |
| Windows .iss 語法 + 路徑 | ✅ 審閱通過 | 檔案存在，`visiona-local` 字串已清除，AppId GUID 固定 |
| Linux build-appimage.sh | ✅ 審閱通過 | 腳本存在，`visiona-local` 字串已清除 |
| CI workflow `build.yml` | ✅ 審閱通過 | 三 job（macos-13 / windows-2022 / ubuntu-22.04）設定齊備 |
| CI workflow cache key | ✅ 通過 | 使用 `visiona-agent` 路徑與 artifact 名稱 |
| Windows 實 build | ⏳ 待 CI | macOS 無法交叉 build WebView2 + iscc；依賴 `.github/workflows/build.yml` Windows runner |
| Linux 實 build | ⏳ 待 CI | macOS 無法 build webkit2gtk + appimagetool；依賴 `.github/workflows/build.yml` Linux runner |
| 三平台安裝到乾淨環境 | ⏳ 待人工 | 需要乾淨 macOS / Windows / Linux VM 或實機 |

## 與 local-tool 共存對照表

兩個工具可同時安裝在同一台機器上，互不干擾。

| 項目 | local-tool | visionA Agent | 結論 |
|------|-----------|---------------|------|
| App Bundle Identifier（macOS） | `com.innovedus.visiona-local` | `com.innovedus.visiona-agent` | ✅ 不衝突 |
| App Bundle Name（macOS） | `visionA-local` | `visionA Agent` | ✅ 不衝突 |
| App 安裝位置（macOS） | `/Applications/visiona-local.app` | `/Applications/visiona-agent.app` | ✅ 不衝突 |
| App 安裝位置（Windows） | `Program Files\visiona-local` | `Program Files\visiona-agent`（`DefaultDirName={autopf}\visiona-agent`） | ✅ 不衝突 |
| Inno Setup AppId GUID（Windows） | local-tool 自己的 | `{8671343F-815C-4AA5-891F-1C453CE14E82}` | ✅ 不同 GUID |
| Data dir（macOS） | `~/Library/Application Support/visiona-local` | `~/Library/Application Support/visiona-agent`（`platform_darwin.go` + `appName="visiona-agent"`） | ✅ 不衝突 |
| Data dir（Linux） | `~/.local/share/visiona-local` | `~/.local/share/visiona-agent` | ✅ 不衝突 |
| Single-instance lock 檔名 | `visiona-local.lock` | `visiona-agent.lock`（`app.go:1580`） | ✅ 不衝突 |
| IPC port sentinel 檔名 | `visiona-local.ipc-port` | `visiona-agent.ipc-port`（`app.go:1539`） | ✅ 不衝突 |
| 對外網路 port | 3721（HTTP UI） | 無（server 只 bind 127.0.0.1:random） | ✅ 無衝突 |
| Tray icon 狀態列圖示 | 獨立 | 獨立 | ✅ 可同時常駐 |

**macOS 雙安裝測試**：本機已有 `/Applications/visiona-local.app`（Bundle ID `com.innovedus.visiona-local`），本次 build 的 DMG 掛載後顯示 `visiona-agent.app`（Bundle ID `com.innovedus.visiona-agent`），LaunchServices 視為不同應用，可並存。

## 遇到的問題與處理

### 1. Wails build 因 `visiona-agent/frontend` 缺 package.json 而失敗

**症狀**：首次跑 `make wails-macos`，Wails 偵測 `assetdir: ./frontend` 後自動執行 `frontend:install`，在 `visiona-agent/frontend/` 跑 `pnpm install`，但該目錄只放 `//go:embed` 用的靜態產物，沒有 `package.json`，報錯：

```
ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND  No package.json... was found in "visiona-agent/frontend".
```

**修復**：`Makefile` 的 `wails-macos` / `wails-windows` / `wails-linux` 三個 target 的 `wails build` 命令都加 `-s`（Skip Frontend）。理由：前端產物已由 `wails-sync-frontend` target 從 `frontend/out/` 同步過來，Wails 不需要自己再跑 pnpm。

### 2. 殘留 `visiona-local` / `visionA-local` 字串

**找到 3 處**，已全部修正：

| 檔案 | 行數 | 原字串 | 修正後 |
|------|------|--------|--------|
| `installer/linux/99-kneron.rules` | 1 | `# Kneron USB devices — visionA-local` | `# Kneron USB devices — visionA Agent` |
| `installer/macos/make-dmg-background.py` | 49 | `title = "Drag visionA-local to Applications"` | `title = "Drag visionA Agent to Applications"` |
| `.github/workflows/release.yml` | 55 | `name: visionA-local ${{ github.ref_name }}` | `name: visionA Agent ${{ github.ref_name }}` |

`installer/windows/visiona-agent.iss:117` 的 `edge-ai-platform` 字串是註解（「未來若要偵測舊版 edge-ai-platform...」），保留。

### 3. go.mod Wails 版本警告（非致命）

Wails CLI 提示：

```
Warning: go.mod is using Wails '2.11.0' but the CLI is 'v2.12.0'.
```

Build 本身不受影響。可未來升級（`wails build -u` 或手動改 `go.mod`），AB12 不處理。

## Makefile 變更摘要（AB12）

| Target | 變更 |
|--------|------|
| `wails-macos` | `wails build` 加 `-s`，並加註解說明為何（frontend 靜態產物由 wails-sync-frontend 處理） |
| `wails-windows` | 同上 |
| `wails-linux` | 同上（兩個分支都加） |

## 完整 build 流程（macOS 本機）

```bash
# 一次性安裝
brew install create-dmg
go install github.com/wailsapp/wails/v2/cmd/wails@latest
export PATH="$HOME/go/bin:$PATH"

# vendor（第一次約 5-10 分鐘，之後吃 cache）
make vendor-sync

# build pipeline
make build-frontend          # → frontend/out/ (~1 MB)
make build-server            # → dist/visiona-agent-server (~31 MB)
make payload-macos           # → payload/darwin/ (~203 MB)
make wails-macos             # → visiona-agent/build/bin/visiona-agent.app (~216 MB)
make dmg                     # → dist/visiona-agent.dmg (~160 MB)

# 或一步到位
make clean-build-dmg
```

## 下一步建議

1. **推到 GitHub 觸發 CI**：`.github/workflows/build.yml` 會在 Windows 與 Linux runner 上完整 build，驗證 pipeline 在另兩個平台也能跑通。
2. **乾淨環境安裝測試**：
   - macOS：下載 `dist/visiona-agent.dmg`，在沒裝過 visionA Agent 的 Mac 上 drag-to-Applications，首次啟動確認 tray icon 出現、Pair 流程可用。
   - Windows：CI 產出的 `.exe` 在 Win10/11 乾淨 VM 上跑，確認 Inno Setup 安裝流程、WinUSB driver 首次啟動提權。
   - Linux：CI 產出的 `.AppImage` 在 Ubuntu 22.04 上 `chmod +x && ./visiona-agent-*.AppImage`，確認 udev rule 提示可用。
3. **Code signing / notarization**（Phase 2，暫不做）：
   - macOS：Developer ID + notarize（否則使用者首次打開要在設定 > 安全性手動允許）
   - Windows：EV Code Signing 憑證（避免 SmartScreen 警告）
4. **安裝與 local-tool 同機共存**驗證：在已安裝 local-tool 的機器上安裝 Agent，確認兩個 tray icon 同時出現、兩套 data dir 獨立、兩個 server 可同時運作。