jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-agent/docs/BUILD-VERIFICATION.md
jim800121chen 3f0175f1a9 feat(local-agent): Phase 0.5 visionA Agent — Wails 桌面 + tunnel client + 配對 UI 
從 local-tool 複製出獨立的「visionA Agent」桌面應用（A3 純橋樑：
tunnel client + 配對 UI + 設定，不開 HTTP port、不做本機裝置/推論 UI）。
Bundle ID 與 local-tool 不同（com.innovedus.visiona-agent vs visiona-local），
雙 app 可共存。fork 後不主動 sync，需要時手動 cherry-pick。

Backend / Wails Go（AB1-AB13）：
- internal/tunnel：6 狀態機（Idle/Connecting/Connected/Reconnecting/Failed/Stopped）
  + Pair/Unpair/Reconnect/Disconnect binding + ClientHooks event
- internal/auth：encrypted file token store（AES-GCM + scrypt + machineID
  fallback salt + 13 tests）
- internal/config：YAML validation + atomic write + 11 tests
- internal/log：ring buffer + ExportLog 升級 zip
- visionA-backend /api/pairing/exchange：SessionTokenStore + 17 new tests
- 三平台 build 驗證（macOS DMG 160 MB / Windows EXE / Linux AppImage）
- end-to-end 5 milestone 全綠（pairing → tunnel → forward → reuse 防護
  → tunnel drop failover）

Frontend / Next.js（AF1-AF7，沿用 visionA-frontend 基礎）：
- AppShell + Header + TabNav（StatusView / PairView / SettingsView 三 tab）
- ConnectionStatusBadge 5 種狀態
- TokenInput regex 驗證 + 7 種錯誤 + 0.5s auto-switch 到狀態頁
- 設定頁 4 區塊（含重新配對 AlertDialog）
- agent-api.ts 封裝 Wails bindings（mock/real 雙實作）+ 90 tests

Phase 0.7 review-driven fix（Round 2）：
- A1 Session fixation 防護（RotateSessionID）
- A3 mock pairing 預設改 false（必須明確 opt-in）+ startup log
- A4 Pair 失敗後 state 清理矩陣（exchange/Save/Start fail 各自終態）
- A5 Pair/Unpair/Reconnect lifecycleMu + 50 goroutine race test
- F1 重新配對次按鈕 / F2 PairView Esc cancel / F3 Wails BrowserOpenURL
  / F4 Settings draft 持久 + 未儲存 badge

驗證：agent backend go test -race -count=3 ./... 4 packages 全綠 /
agent frontend pnpm test 119 tests 全綠

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-01 11:22:01 +08:00

149 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 可同時運作。
Reference in New Issue View Git Blame Copy Permalink