jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool
History
jim800121chen a66fd5665b fix(local-tool): 繞過 Windows Store 的 python stub 
- Makefile：vendor-wheels-windows / vendor-ffmpeg-windows 改用迴圈偵測真實 python
  排除 WindowsApps 路徑下的 Store alias stub，優先使用 VISIONA_PYTHON 環境變數
- Makefile：vendor-ffmpeg-windows 解壓完驗證檔案存在，失敗時 exit 1 而非靜默
- bootstrap-windows.ps1：主動找 winget 裝的真實 python.exe（LOCALAPPDATA / Program Files / py launcher），
  轉成 MSYS2 路徑後以 VISIONA_PYTHON 傳給 Makefile

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 02:11:16 +08:00
..
.autoflow
chore(local-tool): rename local_tool → local-tool, add linux/windows bootstrap scripts
2026-04-11 23:23:29 +08:00
.github/workflows
Initial commit: visionA monorepo with local-tool subproject
2026-04-11 22:10:38 +08:00
frontend
Initial commit: visionA monorepo with local-tool subproject
2026-04-11 22:10:38 +08:00
installer
chore(local-tool): rename local_tool → local-tool, add linux/windows bootstrap scripts
2026-04-11 23:23:29 +08:00
scripts
fix(local-tool): 繞過 Windows Store 的 python stub
2026-04-12 02:11:16 +08:00
server
Initial commit: visionA monorepo with local-tool subproject
2026-04-11 22:10:38 +08:00
visiona-local
Initial commit: visionA monorepo with local-tool subproject
2026-04-11 22:10:38 +08:00
.gitignore
Initial commit: visionA monorepo with local-tool subproject
2026-04-11 22:10:38 +08:00
Makefile
fix(local-tool): 繞過 Windows Store 的 python stub
2026-04-12 02:11:16 +08:00
README.md
chore(local-tool): rename local_tool → local-tool, add linux/windows bootstrap scripts
2026-04-11 23:23:29 +08:00

README.md

visionA-local

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

macOS x86_64 Windows x86_64 Linux x86_64 License

這是什麼

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

開發流程

# 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=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 等開源社群。