jim800121chen
3f0175f1a9
從 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>
210 lines
8.2 KiB
Markdown
210 lines
8.2 KiB
Markdown
# 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 邊緣推論能力，打包成單機桌面應用。
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<!-- TODO: docs/screenshots/logo.png -->
|
||
|
||
---
|
||
|
||
## 這是什麼
|
||
|
||
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`。
|
||
|
||
### 開發流程
|
||
|
||
```bash
|
||
# 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 等開源社群。
|