jim800121chen
44711753ae
## 後端（Phase 1） 新增 flash 模組（從 edge-ai-platform 搬入）： - server/internal/flash/service.go：StartFlash + 模型相容性檢查 + 晶片 NEF 解析 - server/internal/flash/progress.go：Flash 進度追蹤器 - server/internal/api/ws/flash_ws.go：WebSocket 推送 flash 進度 - device_handler.go：新增 FlashDevice method + flashSvc 欄位 - router.go：新增 POST /api/devices/:id/flash + WS /ws/devices/:id/flash-progress - main.go：初始化 flash.NewService 並傳入 router 推論/攝影機/MJPEG/inference WebSocket 之前 M1 已搬好，不需改動。 Python bridge (kneron_bridge.py) 與 edge-ai-platform 完全相同，不需改動。 ## 前端 store + hooks（Phase 2） - stores/flash-store.ts（新）：Zustand store — startFlash / updateProgress / retryFlash / reset - hooks/use-flash-progress.ts（新）：WebSocket hook 接收 flash 進度 inference-store / camera-store / inference types / use-inference-stream / use-websocket 之前 M1 已搬好，不需改動。 ## 前端 UI 元件（Phase 3） - components/devices/flash-dialog.tsx（新）：模型載入對話框 + 硬體相容性檢查 - components/devices/flash-progress.tsx（新）：Flash 進度條 + 錯誤重試 camera-inference-view / camera-feed / camera-overlay / source-selector / inference-panel / performance-metrics / classification-result / confidence-slider / video-progress / batch-image-thumbnails 之前 M1 已搬好。 ## 前端頁面整合（Phase 4） - workspace/page.tsx：繁中硬編碼、顯示已載入模型名稱 - workspace/[deviceId]/workspace-client.tsx：加入 FlashDialog 按鈕 + 繁中硬編碼 - devices/[id]/device-detail-client.tsx：加入 FlashDialog + 「進入工作區」按鈕（模型已載入才顯示） - device-card.tsx：已連線 + 模型已載入時顯示「工作區」快捷按鈕 ## 使用者操作流程 裝置列表 → 連線 → 管理 → 載入模型 → 進入工作區 → 選攝影機/圖片/影片 → 開始推論 → 看 bounding box / FPS / latency 或：裝置列表 → 工作區（已有模型）→ 直接推論 ## 不搬的東西 - cluster/* 全部不搬（已砍 cluster 功能） - relay / tunnel 相關不搬 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
visionA-local
裝起來像一般 app，離線也能跑，接上 Kneron 就推論。 把
edge-ai-platform的 Kneron AI 邊緣推論能力，打包成單機桌面應用。
這是什麼
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）
- 從內部 Gitea Releases 下載
visiona-local.dmg - 雙擊開啟 dmg → 把
visionA-local.app拖到Applications/ - 第一次啟動：因為未做程式碼簽章，Gatekeeper 會警告「來自未識別開發者」
- 在 Finder 中右鍵點
visionA-local.app→ 選「開啟」（不是雙擊） - 對話框出現「仍要開啟」時點確認
- 往後直接雙擊即可
- 在 Finder 中右鍵點
- 首次啟動會花 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
.exeinstaller - 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
開發流程
# 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/03-design/ |
| 架構設計 | .autoflow/04-architecture/design-doc.md |
| TDD | .autoflow/04-architecture/TDD.md |
| 進度 | .autoflow/progress.md |
已知限制與 TODO
- 🔴 ffmpeg 目前是 GPL build（含
--enable-gpl --enable-libx264），由VISIONA_ALLOW_GPL_FFMPEG=1flag 放行本地驗收，發佈前等法務 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 等開源社群。