jim800121chen
d7cddf364b
M8-10a smoke test 抓到 M1 就潛藏的 P0 latent bug：server 預設 dataDir = <binary>/data，bundle 內解析成 Contents/Resources/bin/data/（空目錄）， 實際 models.json + 8 個 .nef 住在 Contents/Resources/data/（上一層）。 Wails 又傳 --data-dir 成 user home（writable），同樣沒 models.json。 結果任何正式啟動路徑下 /api/models 都回 total: 0，M1-M7 smoke 從沒 跑過這個 endpoint 才漏抓。 修法：把「read-only bundle 內資料」和「writable user 資料」語意拆開。 - 新增 findFirstExisting(candidates, sentinel) helper - 新增 resolveBuiltInDataDir：①VISIONA_BUNDLE_LIB_DIR/data（AppImage） ②<base>/data ③<base>/../data ④<base>/../Resources/data ⑤<base>/../lib/visiona-local/data（Linux FHS）。命中條件是 models.json 存在為 regular file，避開 Wails build artifact 留下的 空 data/ 目錄 - main() 拆 builtInDataDir（modelRepo + flash.Service 用）與 dataDir （custom-models / sentinel / logs 用），職責分明 - flash.NewService 改吃 builtInDataDir — 它要解析 models.json 裡的 相對路徑 "data/nef/kl520/xxx.nef"，來源是 bundle 不是 user home - resolveBridgeScript 同步修（同樣的技術債一起清），候選 env var 優先 + FHS fallback，避免 Linux AppImage 上 kneron_bridge.py 也找不到 - fallback 全 filepath.Abs 化，log.Printf 印嘗試過的路徑清單便於除錯 驗證（build / vet / test + smoke）全綠： - macOS bundle：/api/models → 15 models ✅ - dev mode（server/ 下 go run）：15 models ✅ - Linux AppImage 模擬 + env var：命中候選 1 ✅ - Linux AppImage 模擬 + 無 env var：命中候選 5（FHS）✅ - 全不命中：log 印完整 tried 清單 + server 不 crash ✅ Reviewer 兩輪通過。第一輪抓到 Linux AppImage 未覆蓋（Major-1）+ 2 Minor + 2 Suggestion；第二輪確認全部處理到位、新發現兩項非阻擋風格建議列為 技術債。報告見 .autoflow/05-implementation/reviews/review-m8-10a-*.md。 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、預置
.nef模型全部內嵌 - ✈️ 零網路：下載一次後完全離線可用（適合客戶現場 IT 鎖得死緊的場景）
- 🖱️ 零學習成本：雙擊安裝 → 開啟 → 插上 Kneron 裝置 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）
- 模型管理：8 個預置
.nef模型（分類 / 偵測 / 臉辨）+ 自上傳切換 - 核心推論引擎：image classification、object detection、face recognition
- 媒體推論：支援圖片與影片檔（本機上傳，R5 決策後不支援 URL 推論）
- 中英雙語，跟隨系統 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 |
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 |
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
- 🟡 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。
致謝 / 起源
visionA-local 衍生自 Innovedus 內部專案 edge-ai-platform（原為部署於 EC2 + Docker 的多人共享平台）。本專案將其改造為單機桌面版本，聚焦「一個人帶一台筆電」的使用場景。
感謝 Kneron、python-build-standalone（astral-sh）、shadcn 等開源社群。