jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool
History
jim800121chen c03eb6fd0e feat(local-tool): M9-2 — Go driver UpgradeFirmware + firmware service module 
A 階段第二個 milestone、銜接 M9-1 bridge.py、暴露 service layer 給 M9-3 API/WebSocket。

New module `server/internal/firmware/`:
- types.go: 123 行（FirmwareVersion / FirmwareProgress / ActiveTaskInfo / UpgradeDriver interface / 8 reason const）
- progress.go: 147 行（仿 flash pattern 的 Tracker、Task.cancel 預留 SIGTERM force-cancel godoc）
- service.go: 373 行（核心 service：UpgradeFirmware / HasActiveTask / GetActiveTaskInfo / RequestShutdown / WaitForActiveTasks / ListBundledVersions / GetCurrentVersion）
- service_test.go: 676 行、13 個 test 含 MultiDeviceParallel

Driver layer:
- kl720_driver.go: 697 → 1054 行（+357、新 UpgradeFirmware method + tryRouteFirmwareEvent + sendCommandForUpgrade snapshot pattern）
- kl720_driver_test.go: 360 行、11 個 test（含 InfoNotBlockedDuringUpgrade / CtxCancelReleasesBridge / StderrEventAfterCtxCancel 100 round stress）

關鍵設計：
- flash 與 firmware 模組分離（不 import flash）
- UpgradeDriver interface 隔離 driver 細節、DeviceLookup interface 隔離 device manager
- 中介 channel pattern（service ↔ driver）方便 service 補欄位（DeviceID / Direction / BeforeVersion）
- timeout 雙保險：chip timeout + 30s margin
- 8 reason enum 對齊 bridge.py、stage 採 Design 命名

Concurrency race 修復（M9-2 Reviewer round 1 → round 2）:
- Major 1（mutex deadlock）：新 fwUpgradeMu 獨立鎖 + sendCommandForUpgrade snapshot stdin/stdout pattern、避開 d.mu field-level race + 升級期間 Info/Disconnect 不被卡 + timeout 路徑無死鎖
- Major 2（close-channel race）：tryRouteFirmwareEvent 持 fwMu 整段、配合 defer setFirmwareProgressCh(nil) 提供 happen-before、絕無 send on closed channel panic

Reviewer 兩輪審查：
- Round 1: 0 Critical / 2 Major / 5 Minor / 5 Suggestion
- Round 2: 0 Critical / 0 Major / 2 Minor / 2 Suggestion（11/12 issue 修到位、Suggestion 4 留 follow-up）

M9-1 follow-up 順手清：
- m5（test 死碼 _firmware_upgrade_start_ts 殘留兩行）已清
- s5（test 註解 idempotent shape 說明）已加

測試：
- go test ./... -race -count=1: 全綠（28s、無 regression）
- Python: 36 tests + 22 subtests 全綠（0.31s）
- go vet / build: 0 output

下一步：M9-3 API handler + WebSocket progress（CI 建議 `go test -race -count=3` 提升 race 偵測強度）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 11:27:36 +08:00
..
.autoflow
feat(local-tool): M9-2 — Go driver UpgradeFirmware + firmware service module
2026-05-25 11:27:36 +08:00
.github/workflows
feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）
2026-04-15 17:57:54 +08:00
branding
feat(local-tool): 品牌視覺設計 + 內建模型首次啟動 seed
2026-04-12 04:42:41 +08:00
docs
docs(local-tool): Build 指引 → Installer Build 指引
2026-04-16 15:04:38 +08:00
frontend
fix(local-tool): 推論 bbox 標註不顯示 — 前端 canvas 尺寸 + KL520 reset + 延長 timeout
2026-04-21 01:12:10 +08:00
installer
feat(local-tool): macOS DMG 美化（create-dmg 背景圖 + Applications 捷徑）
2026-04-21 01:11:22 +08:00
scripts
fix(local-tool): bootstrap-linux.sh 自動安裝 appimagetool
2026-04-16 08:11:49 +08:00
server
feat(local-tool): M9-2 — Go driver UpgradeFirmware + firmware service module
2026-05-25 11:27:36 +08:00
vendor
feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）
2026-04-15 17:57:54 +08:00
visiona-local
fix(local-tool): macOS 掃不到 Kneron 裝置 — PythonModeAuto 先 bundled
2026-04-21 01:10:59 +08:00
.gitignore
feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）
2026-04-15 17:57:54 +08:00
Makefile
feat(local-tool): macOS DMG 美化（create-dmg 背景圖 + Applications 捷徑）
2026-04-21 01:11:22 +08:00
README.md
feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）
2026-04-15 17:57:54 +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、預置 .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

❌ 不做的事（明確排除）

為了聚焦「個人工具」，以下功能從 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 等開源社群。