jim800121chen
c54f16fca0
local-tool/: visionA-local desktop app
- M1: Wails shell + Go server + Next.js UI + Mock mode (macOS dmg ready)
- M2: i18n (zh-TW/en) + Settings 4-tab refactor
- M3: Embedded Python 3.12 runtime (python-build-standalone) + KneronPLUS wheels
- M4: Windows Inno Setup script (build on Windows runner)
- M5: Linux AppImage script + udev rule (build on Linux runner)
- M6: ffmpeg (GPL, pending legal review) + yt-dlp bundled
- Lifecycle: watchServer health check, fatal native dialog,
Wails IPC raise endpoint, stale process cleanup
.autoflow/: full PRD / Design Spec / Architecture / Testing docs
(4 rounds tri-party discussion + cross review)
.github/workflows/: macOS / Windows / Linux build CI
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
201 lines
7.4 KiB
Markdown
201 lines
7.4 KiB
Markdown
# visionA-local
|
||
|
||
> **裝起來像一般 app，離線也能跑，接上 Kneron 就推論。**
|
||
> 把 `edge-ai-platform` 的 Kneron AI 邊緣推論能力，打包成單機桌面應用。
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<!-- TODO: docs/screenshots/logo.png -->
|
||
|
||
---
|
||
|
||
## 這是什麼
|
||
|
||
visionA-local 是 `edge-ai-platform`（原本要部署到 EC2 + Docker 的 Kneron 邊緣推論平台）的**單機桌面衍生版本**。為「帶著筆電做 Kneron demo 的人」而生 —— 主要服務 Innovedus 內部 FAE 與外部 Kneron 開發者。
|
||
|
||
三個核心承諾：
|
||
|
||
- 🎒 **零依賴**：Python runtime、KneronPLUS SDK、ffmpeg、yt-dlp、預置 `.nef` 模型全部內嵌
|
||
- ✈️ **零網路**：下載一次後完全離線可用（適合客戶現場 IT 鎖得死緊的場景）
|
||
- 🖱️ **零學習成本**：雙擊安裝 → 開啟 → Mock 模式 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）
|
||
- **Mock 模式**：零硬體入口，產品經理、SA 也能拿來說故事
|
||
- **模型管理**：8 個預置 `.nef` 模型（分類 / 偵測 / 臉辨）+ 自上傳切換
|
||
- **核心推論引擎**：image classification、object detection、face recognition
|
||
- **媒體推論**：支援圖片、影片檔、URL（內嵌 yt-dlp）
|
||
- **中英雙語**，跟隨系統 Dark Mode
|
||
|
||
### ❌ 不做的事（明確排除）
|
||
|
||
為了聚焦「個人工具」，以下功能從 `edge-ai-platform` 全數砍掉：
|
||
|
||
- ❌ Cluster（多裝置叢集）
|
||
- ❌ Relay / Tunnel（遠端連線、反向代理）
|
||
- ❌ 韌體燒錄（firmware flash）
|
||
- ❌ 系統列 Tray 常駐
|
||
- ❌ Auto-update
|
||
- ❌ Telemetry / 崩潰回報
|
||
- ❌ License 啟用、憑證簽章
|
||
- ❌ Mac App Store / Microsoft Store / Snap Store 上架
|
||
|
||
---
|
||
|
||
## 開發者區
|
||
|
||
### 專案結構
|
||
|
||
```
|
||
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
|
||
```
|
||
|
||
### 開發流程
|
||
|
||
```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、yt-dlp |
|
||
| `build-server` | 編譯 Go server binary（先 build frontend + embed） |
|
||
| `build-frontend` | pnpm build Next.js 靜態產物 |
|
||
| `payload-macos` | 準備 macOS payload（binary + python + wheels + ffmpeg + yt-dlp + 模型） |
|
||
| `wails-macos` | Wails build + ad-hoc codesign |
|
||
| `dmg` | 產出 `dist/visiona-local.dmg` |
|
||
| `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 需要對應平台）。
|
||
|
||
### 文件位置
|
||
|
||
所有設計與架構文件在 `.autoflow/`：
|
||
|
||
| 類型 | 路徑 |
|
||
|------|------|
|
||
| 產品需求（PRD） | [`.autoflow/02-prd/PRD.md`](./.autoflow/02-prd/PRD.md) |
|
||
| 設計規格 | [`.autoflow/03-design/`](./.autoflow/03-design/) |
|
||
| 架構設計 | [`.autoflow/04-architecture/design-doc.md`](./.autoflow/04-architecture/design-doc.md) |
|
||
| TDD | [`.autoflow/04-architecture/TDD.md`](./.autoflow/04-architecture/TDD.md) |
|
||
| 進度 | [`.autoflow/progress.md`](./.autoflow/progress.md) |
|
||
|
||
---
|
||
|
||
## 已知限制與 TODO
|
||
|
||
- 🔴 **ffmpeg 目前是 GPL build**（含 `--enable-gpl --enable-libx264`），由 `VISIONA_ALLOW_GPL_FFMPEG=1` flag 放行本地驗收，**發佈前等法務 review**
|
||
- 🟡 **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 | **GPL**（目前使用 GPL build） | ⚠️ 法務 review pending |
|
||
| yt-dlp | Unlicense | — |
|
||
| 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。
|
||
|
||
---
|
||
|
||
## 致謝 / 起源
|
||
|
||
visionA-local 衍生自 Innovedus 內部專案 `edge-ai-platform`（原為部署於 EC2 + Docker 的多人共享平台）。本專案將其改造為單機桌面版本，聚焦「一個人帶一台筆電」的使用場景。
|
||
|
||
感謝 Kneron、python-build-standalone（astral-sh）、shadcn 等開源社群。
|