jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool
History
jim800121chen ad9beab0ca fix(local-tool): Restart / StopServer+StartServer 後前端 5 階段 UI 不更新 
使用者在 Windows 版 local tool 按「重新啟動伺服器」或 Stop 再 Start 後，
畫面中間的 5 階段面板停留在「等待中」不更新，但實際上 server 已經
成功啟動完成。

根因：
  Restart / StartServer 路徑 → ctrl.Restart() / ctrl.Start() →
  ctrl.startInternal() → startServerV2()

  但 StartupPipeline 已經 markReady (current=7)，所以 startServerV2 內
  所有 CompleteStage(2/3/4) / EmitStageDetail / IsInColdStart 檢查都
  early return 或 no-op，Go 端完全不 emit 任何 startup:progress event。
  前端 resetStartupPanel 後開始等事件，但事件根本沒來 → UI 停留在
  pending「等待中」。

  RestartStartupSequence（Retry 按鈕）有自己完整重建 pipeline 的 5 步
  邏輯，所以 Retry 路徑沒事。但 Restart / Stop+Start 走的是 ctrl.Restart
  / ctrl.Start 不走 RestartStartupSequence。

修法：

1. 抽 helper rebuildStartupPipeline() — 把 RestartStartupSequence 裡
   「重建 pipeline + emit Stage 1 completed + 啟 watcher + 前進 Stage 2」
   那 20 多行邏輯抽出來，讓 startInternal 也能呼叫。

2. startInternal 進場時偵測 pipeline 狀態：
   - cold start 路徑 (current ∈ [1..6]) → 不動
   - 已 ready (current > totalStages) 或 已 failed (current == -1)
     → 清 sentinel file + 呼叫 rebuildStartupPipeline()，記 didRebuild=true

3. startInternal 成功返回前，Stage 5 openBrowser 處理改成三分支：
   - didRebuild=true → 呼叫 runStartupStage5（Restart 路徑）
   - cold start (IsInColdStart && !didRebuild) → skip 由上層呼叫
     runStartupStage5（app.startup 冷啟動路徑或 RestartStartupSequence）
   - fallback (pipeline == nil) → 自己 openBrowser 一次

四條路徑的分流現在完整：

  (A) cold start           : app.startup → Pipeline.Start 自己前進到 2 →
                             startInternal 看 current=2 不 rebuild →
                             didRebuild=false → app.startup 呼叫 stage5
  (B) Restart / Stop+Start : ctrl.Restart/Start → startInternal 看
                             current=7 rebuild → didRebuild=true →
                             startInternal 自己呼叫 stage5
  (C) RestartStartupSequence: 自己 rebuild 前進到 2 → ctrl.Start →
                             startInternal 看 current=2 不 rebuild →
                             didRebuild=false → RestartStartupSequence
                             後續呼叫 stage5
  (D) pipeline == nil       : 走舊 fallback 自己 openBrowser

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- 關鍵 test TestRestartStartupSequence_ColdStartOpenBrowser_OnlyOnce
  仍 pass（驗證 browser 不會被 cold start 開兩次）
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-16 08:19:33 +08:00
..
.autoflow
fix(local-tool): 拆 built-in / user data dir — 修預設模型永遠載入 0 個
2026-04-15 20:23:25 +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
frontend
feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）
2026-04-15 17:57:54 +08:00
installer
fix(local-tool): bootstrap-linux.sh 自動安裝 appimagetool
2026-04-16 08:11:49 +08:00
scripts
fix(local-tool): bootstrap-linux.sh 自動安裝 appimagetool
2026-04-16 08:11:49 +08:00
server
fix(local-tool): 拆 built-in / user data dir — 修預設模型永遠載入 0 個
2026-04-15 20:23:25 +08:00
vendor
feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）
2026-04-15 17:57:54 +08:00
visiona-local
fix(local-tool): Restart / StopServer+StartServer 後前端 5 階段 UI 不更新
2026-04-16 08:19:33 +08:00
.gitignore
feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）
2026-04-15 17:57:54 +08:00
Makefile
fix(local-tool): Linux build 支援 webkit2gtk-4.1（Ubuntu 22.10+ / Debian 12+）
2026-04-16 04:11:53 +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 等開源社群。