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

8.2 KiB
Raw Blame History

Legacy local-tool README（已封存）

此檔僅作歷史保留。

以下內容是 visionA Agent 於 2026-04-22 從 local-tool/（baseline commit b71ff4cd3c72e879435f773ae15b23bf8b70841e）fork 時的原始 README 後半段。

內容描述的是 local-tool（單機桌面 Kneron 工具）的產品定位、安裝流程、功能清單與不做的事，並非 visionA Agent 的當前定位。

visionA Agent 的真實定位請見 local-agent/README.md：

  • visionA Agent 就是 tunnel client（local-tool 明確排除「Tunnel」）
  • visionA Agent 的 UI 只剩 3 頁配置（狀態 / 配對 / 設定），不保留 local-tool 的裝置 / 模型 / 推論 UI
  • visionA Agent 不會單獨上架，靠雲端 visionA-backend 驅動

保留此檔的目的：

  1. 未來若需從 local-tool cherry-pick bug fix，可比對原始 README 釐清 baseline 行為
  2. 部分 build 流程（Makefile target、三平台 installer）仍延用 local-tool 結構，這份原文是歷史對照

若內容已不再有參考價值，可整檔刪除。

裝起來像一般 app，離線也能跑，接上 Kneron 就推論。 把 edge-ai-platform 的 Kneron AI 邊緣推論能力，打包成單機桌面應用。

macOS x86_64 Windows x86_64 Linux x86_64 License

這是什麼

local-tool 是 edge-ai-platform（原本要部署到 EC2 + Docker 的 Kneron 邊緣推論平台）的單機桌面衍生版本。為「帶著筆電做 Kneron demo 的人」而生 —— 主要服務 Innovedus 內部 FAE 與外部 Kneron 開發者。

三個核心承諾：

  • 🎒 零依賴：Python runtime、KneronPLUS SDK、ffmpeg、預置 .nef 模型全部內嵌
  • ✈️ 零網路：下載一次後完全離線可用（適合客戶現場 IT 鎖得死緊的場景）
  • 🖱️ 零學習成本：雙擊安裝 → 開啟 → 插上 Kneron 裝置 30 秒內跑出第一幀推論

對標產品：Docker Desktop、Ollama。

安裝（使用者）

macOS（x86_64，beta）

  1. 從內部 Gitea Releases 下載 visiona-local.dmg
  2. 雙擊開啟 dmg → 把 visionA Local.app 拖到 Applications/
  3. 第一次啟動：因為未做程式碼簽章，Gatekeeper 會警告「來自未識別開發者」
    • 在 Finder 中右鍵點 visionA Local.app → 選「開啟」（不是雙擊）
    • 對話框出現「仍要開啟」時點確認
    • 往後直接雙擊即可
  4. 首次啟動會花 30–60 秒解壓內嵌的 Python runtime 並離線安裝 wheels 這是預期行為，不是卡住。之後啟動只要幾秒

📁 資料目錄：~/Library/Application Support/visiona-local/ 包含 log、lock、ipc-port、自上傳模型

Windows / Linux

Coming soon — build script 已經寫好，等 CI runner 齊備後就會釋出。

  • Windows：Inno Setup .exe installer
  • Linux：.AppImage + udev rules（需 root 裝 99-kneron.rules）

系統需求

平台 最低版本 架構
macOS 14 Sonoma x86_64 ¹
Windows 10 1809 x86_64
Ubuntu 22.04 x86_64

¹ Apple Silicon 理論上可透過 Rosetta 2 執行，但未經測試。

離線可用：安裝後所有核心功能（包含 Python sidecar、推論、模型管理、攝影機、影片解碼）完全不需要網路。

功能總覽

✅ 有的功能

  • 裝置管理：USB 自動偵測 Kneron KL520 / KL720，10 秒內連線
  • 攝影機推論：MJPEG 串流 + 即時 overlay（首次延遲 ≤ 250ms，穩定後 ≤ 150ms）
  • 模型管理：8 個預置 .nef 模型（分類 / 偵測 / 臉辨）+ 自上傳切換
  • 核心推論引擎：image classification、object detection、face recognition
  • 媒體推論：支援圖片與影片檔（本機上傳，R5 決策後不支援 URL 推論）
  • 中英雙語，跟隨系統 Dark Mode

❌ 不做的事（明確排除）

⚠️ 注意：以下排除清單是 local-tool 的設計邊界，不適用於 visionA Agent。 visionA Agent 的核心能力之一就是 Tunnel（與此清單相反）。

為了聚焦「個人工具」，以下功能從 edge-ai-platform 全數砍掉：

  • ❌ Cluster（多裝置叢集）
  • ❌ Relay / Tunnel（遠端連線、反向代理）
  • ❌ 韌體燒錄（firmware flash）
  • ❌ 系統列 Tray 常駐
  • ❌ Auto-update
  • ❌ Telemetry / 崩潰回報
  • ❌ License 啟用、憑證簽章
  • ❌ Mac App Store / Microsoft Store / Snap Store 上架

開發者區（local-tool 結構，僅供對照）

專案結構

local-tool/
├── .autoflow/        PRD / 設計 / 架構 / 進度文件
├── server/           Go 1.26 後端（Gin + go:embed）
├── frontend/         Next.js 16 + React 19 + shadcn
├── visiona-local/    Wails 應用殼（installer）
├── payload/          打包暫存區
├── vendor/           第三方依賴（make vendor-sync 下載，不進 git）
├── dist/             最終安裝檔（.dmg / .exe / .AppImage）
├── installer/        Inno Setup / AppImage script
├── scripts/          build 與維運腳本
└── Makefile

visionA Agent 沿用大部分目錄結構，但 visiona-local/ → visiona-agent/、Bundle ID / 安裝路徑 / lockfile 全部獨立。詳見 local-agent/docs/BUILD-VERIFICATION.md。

開發流程

# 1. 下載全部第三方依賴到 vendor/
make vendor-sync

# 2. 本機 build 並產出 dmg（macOS）
make dmg

# 查看所有可用 targets
make help

主要 make targets：

Target 作用
vendor-sync 下載 python-build-standalone、wheels、ffmpeg
build-server 編譯 Go server binary（先 build frontend + embed）
build-frontend pnpm build Next.js 靜態產物
payload-macos 準備 macOS payload（binary + python + wheels + ffmpeg + 模型）
wails-macos Wails build + ad-hoc codesign
dmg 產出 dist/visiona-local.dmg（local-tool）/ visiona-agent.dmg（visionA Agent）
exe Windows installer（需在 Windows runner 執行）
appimage Linux AppImage（需在 Linux runner 執行）

三方平台 build

平台 指令 執行環境
macOS make dmg 本機（Intel Mac）
Windows make exe Windows runner + Inno Setup 6
Linux make appimage Ubuntu 22.04+ runner + appimagetool

vendor-*-windows / vendor-*-linux 可在 macOS 上跑通（只有 wails-* 和最後一步 installer 需要對應平台）。

已知限制與 TODO（local-tool 原文）

  • 🟡 Kneron 預置模型 re-distribution 授權：開發階段假設可用，正式發佈前需與 Kneron 官方確認
  • 🟡 Windows / Linux 安裝檔：build script 就緒，等 CI runner 齊備
  • 🟡 Apple Silicon 未經測試（理論上 Rosetta 2 可跑）
  • 🟡 Linux Kneron USB vendor ID：installer/linux/99-kneron.rules 需最終確認
  • 🟡 程式碼簽章（Developer ID / EV cert）不做，使用者需手動繞過 Gatekeeper / SmartScreen
  • 🟡 無 auto-update：新版需手動從 Gitea 下載

授權

License: TBD（內部工具 / MIT / proprietary 待定，發佈前確認）

第三方元件授權

元件 授權 備註
ffmpeg LGPL v3（方案 B 混合：macOS 自 build decoder-only / Windows & Linux 用 BtbN n7.1 LGPL） v2 TDD §2.2
KneronPLUS SDK Kneron 商用條款 再次確認 re-distribution 權利
python-build-standalone MPL 2.0 / PSFL —
Python 標準函式庫 PSFL —
shadcn/ui MIT —
Next.js / React MIT —
Wails MIT —
Gin MIT —

完整第三方授權清單於 .autoflow/02-prd/PRD.md §4.8。

致謝 / 起源

local-tool 衍生自 Innovedus 內部專案 edge-ai-platform（原為部署於 EC2 + Docker 的多人共享平台）。本專案將其改造為單機桌面版本，聚焦「一個人帶一台筆電」的使用場景。

感謝 Kneron、python-build-standalone（astral-sh）、shadcn 等開源社群。