jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-agent/README.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

5.3 KiB
Raw Blame History

visionA Agent

Phase 0 雛形 — 正在建置中

此專案於 2026-04-22 從 local-tool/ fork，baseline commit：b71ff4cd3c72e879435f773ae15b23bf8b70841e

fork 後獨立演進，不主動與 local-tool 同步。 需要時手動 cherry-pick bug fix。

產品定位

visionA Agent 是 visionA 雲端版的 local 端代理程式：

它是什麼

  • 一個完整的 local server（沿用 local-tool 的 KneronPLUS / camera / inference / device / model / Python runtime / ffmpeg 邏輯）
  • 加上 tunnel client，把自己 reverse-tunnel 到雲端 visionA-backend，讓雲端 web UI 可以透過 tunnel 操作使用者桌機上的 Kneron 裝置
  • 加上 3 頁極簡配置 UI（狀態 / 配對 / 設定），給使用者看「Agent 是否在線」和「配對雲端帳號」用

它不是什麼

  • 不是 local-tool 的修改版（local-tool 不動；visionA Agent fork 後獨立演進）
  • 不保留 local-tool 原本的裝置 / 模型 / 推論 UI（這些由雲端 web UI 負責；本機 UI 只管配對/設定）

目前進度（Phase 0 雛形）

任務 狀態 說明
AB1 ✅ fork + 改名（visiona-local → visiona-agent / bundle ID / Makefile 變數 78 處替換）
AB2+AB3 ✅ 裁剪 Wails 業務 UI binding、刪除舊資料目錄遷移；新增 pairing / connection / settings 的 stub binding（回 ErrNotImplemented），為 AB4-AB10 預留擴點
AB4 ⏳ 複製 tunnel client（從 POC）到 internal/tunnel/
AB5 ⏳ Agent config (YAML) 讀寫
AB6 ⏳ Internal HTTP server（wrapper 綁 127.0.0.1:0）
AB7 ⏳ Pairing Exchanger（呼叫雲端 /api/pairing/exchange）
AB8 ⏳ connstate broadcaster + Wails event 推送
AB9 ⏳ autostart 三平台實作
AB10 ⏳ logexport（壓縮最近 7 天 log）
AB11-12 ⏳ Wails 整合 + 整合測試

架構圖（簡版）

[ Browser ] ── HTTPS ──► [ visionA-backend ]
                                │ （內部 HTTP forward）
                                ▼
                         [ remote-proxy ]
                                │ （WSS + yamux 出站長連線）
                                ▼
┌───────────────────────────────────────────────────────┐
│  visionA Agent（使用者桌機，Wails app）                │
│                                                       │
│   [Tunnel client]            [3 頁配置 UI]             │
│         │                         │ Wails bindings    │
│         ▼                         ▼                   │
│   [Internal HTTP server 127.0.0.1:<random port>]      │
│   （沿用 local-tool 的 Gin handler：裝置/模型/推論/...） │
│                         │                             │
│                         ▼                             │
│   [Python runtime + KneronPLUS SDK + ffmpeg]          │
└───────────────────────────────────────────────────────┘
                                │
                                ▼
                       Kneron USB 裝置

文件

fork baseline

本專案於 2026-04-22 從 local-tool/（commit b71ff4cd3c72e879435f773ae15b23bf8b70841e）一次性 fork 後獨立演進，不主動 sync（ADR-007）。

local-tool 原始 README 已封存於 docs/legacy-local-tool-readme.md，僅作 cherry-pick bug fix 時的歷史對照，不再代表 visionA Agent 的產品定位。

開發指令

# 下載第三方依賴到 vendor/
make vendor-sync

# 本機 build + 產出 macOS DMG
make dmg

# 列出所有 targets
make help

主要 targets（沿用 local-tool 結構，但所有產物名稱已替換為 visiona-agent）：

Target 作用
vendor-sync 下載 python-build-standalone / wheels / ffmpeg
build-frontend pnpm build Next.js 靜態產物 → frontend/out/
wails-sync-frontend 同步 frontend/out/ → visiona-agent/frontend/（Wails embed）
wails-macos / wails-windows / wails-linux Wails build + ad-hoc codesign（macOS）
dmg 產出 dist/visiona-agent.dmg（缺 create-dmg 時 fallback hdiutil）
exe Inno Setup → dist/visiona-agent-*-windows-x64.exe（需 Windows runner）
appimage dist/visiona-agent-*-x86_64.AppImage（需 Linux runner）
dev-agent Wails dev mode
test-tunnel tunnel client 整合測試

三平台 build 細節與 local-tool 共存對照表：docs/BUILD-VERIFICATION.md。