visionA/local-agent/docs/BUILD-VERIFICATION.md

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 本機）

# 一次性安裝
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 可同時運作。