jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/04-architecture/design-doc.md
jim800121chen 5a8d2797c2 chore(local-tool): rename local_tool → local-tool, add linux/windows bootstrap scripts 
- 統一目錄名為 local-tool（連字號），修正所有文件中殘留的底線版本
- 新增 scripts/bootstrap-linux.sh 與 scripts/bootstrap-windows.ps1
  一鍵安裝依賴（Go/Node/pnpm/Wails/MSYS2）並執行 payload + installer build

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-11 23:23:29 +08:00

11 KiB
Raw Blame History

visionA-local — Design Doc（索引）

本檔案為設計文件總索引，各章節摘要 + 子檔連結。 專案：visionA-local（edge-ai-platform 的本地桌面版） Bundle ID：com.innovedus.visiona-local 作者：Architect Agent ｜ 版本：1.0 ｜ 日期：2026-04-11

0. 文件地圖

面向 檔案
架構總覽與程序模型 architecture-overview.md
依賴內嵌策略（Python / Kneron / ffmpeg / yt-dlp / 模型） dependency-bundling.md
打包流程（mac dmg / win Inno Setup / linux AppImage） packaging.md
Build pipeline / Makefile / CI 骨架 build-pipeline.md
生命週期（port 衝突、single-instance；tray 已砍） tray-and-lifecycle.md
多語系（中英雙語） i18n.md
風險與緩解（R1–R12） risks-and-mitigations.md
Plan B（R9 contingency，線上下載預置模型） plan-b-online-download.md
技術設計文件（索引） TDD.md

TDD 底下還拆分：

1. 產品定位（一段話）

visionA-local 是 edge-ai-platform 的單機桌面版，把原本需要 EC2 + Docker + nginx 的 web 工具改造為「雙擊即用」的 GUI 應用，目標體驗對標 Docker Desktop / Ollama。所有依賴（Python runtime、KneronPLUS SDK、ffmpeg、yt-dlp、預置 .nef 模型）全部內嵌在安裝檔中，使用者機器完全不需要預先安裝任何東西，且完全離線即可運作。支援 macOS 14/15、Windows 10/11、Ubuntu 22.04/24.04，僅 x86_64（Apple Silicon 用 Rosetta）。

2. 高層架構（一句話 + 圖）

Wails 殼（Go + WebView）→ spawn → Go server 子行程（Gin + 內嵌 Next.js）→ spawn → Python sidecar（KneronPLUS bridge）

┌──────────────────────────────────────────────────┐
│  visionA-local  (Wails app — 使用者看到的殼)       │
│  ├─ 首次執行：安裝精靈（解壓 payload → 建 venv）   │
│  ├─ 一般模式：Dashboard（關閉視窗 = 結束程式）     │
│  └─ 內嵌 WebView → http://127.0.0.1:3721/        │
│                          │                        │
│                 spawn    ▼                        │
│  ┌────────────────────────────────────────┐       │
│  │ visiona-local-server (Go binary)        │       │
│  │  - Gin HTTP + WebSocket                 │       │
│  │  - go:embed Next.js 靜態檔              │       │
│  │  - REST: /api/devices, /api/models, ... │       │
│  │  - WS:   /ws/devices, /ws/server-logs   │       │
│  │           │                              │       │
│  │  spawn    ▼                              │       │
│  │  ┌─────────────────────────────────┐    │       │
│  │  │ python3 kneron_bridge.py         │    │       │
│  │  │  - KneronPLUS SDK                │    │       │
│  │  │  - 推論 / 裝置列舉 / 模型載入    │    │       │
│  │  └─────────────────────────────────┘    │       │
│  │  spawn (on demand)                       │       │
│  │  ┌─────────────────────────────────┐    │       │
│  │  │ ffmpeg / yt-dlp                  │    │       │
│  │  └─────────────────────────────────┘    │       │
│  └────────────────────────────────────────┘       │
└──────────────────────────────────────────────────┘

詳見 architecture-overview.md。

3. 最重要的 5 個架構決策（摘要）

# 決策 為什麼
D1 三層程序模型（Wails 殼 + Go server 子行程 + Python sidecar），不合併成 single binary Go server 要長時間跑、UI 殼可獨立崩潰重啟；KneronPLUS 必須用真的 Python interpreter；installer/app.go 已驗證此模型可行（894 行成熟程式碼）
D2 Python runtime 雙策略：主策略 A = 內嵌 python-build-standalone（完全離線）；備策略 B = 偵測系統 python3 作為 fallback / 開發模式 使用者決策：要完全離線，但要保留 fallback。A 確保第一次執行就能跑（符合「一鍵安裝」），B 用在 --dev 模式與 standalone runtime 壞掉時的救援
D3 完全放棄程式碼簽章：macOS 用 ad-hoc sign、Windows 無 Authenticode、Linux AppImage 無簽章 使用者決定不買憑證，接受 Gatekeeper / SmartScreen 警告。但必須寫清楚首次啟動 workaround 文件（見 packaging.md §6）
D4 x86_64 only，三平台都不做 ARM / Universal Binary 使用者是 Intel Mac；目標受眾也是內部 FAE + 客戶 demo 機，多為 x86_64。Apple Silicon 走 Rosetta 2。這大幅簡化 build pipeline（不用 lipo、不用雙架構 wheel）
D5 預置模型全部打包（~73MB），不做 auto-update、不收 telemetry 符合「完全離線、零踩坑」原則。auto-update 對內部工具不值得投入（見 R6），且每次升級都會放 SmartScreen 警告重新觸發

4. 程式碼來源策略（摘要）

新專案 local-tool/ 從零建立，但可以自由從 edge-ai-platform/ 取用程式碼：

  • 直接複製（~60% 程式碼）：installer/、server/internal/{api,camera,config,deps,device,driver,inference,model}、server/scripts/kneron_bridge.py、server/data/、server/pkg/logger
  • 改寫（~20%）：server/main.go（移除 cluster / tunnel / relay）、server/internal/api/router.go（刪 cluster routes）、server/internal/config/config.go（刪 relay / gitea flags）、installer/app.go（改名 + 加入 Python runtime 雙策略）、frontend/（刪 cluster / relay UI）
  • 新寫（~20%）：Python runtime 偵測與 fallback 邏輯、i18n 系統、新版 Makefile / build 腳本、Inno Setup 腳本、AppImage 腳本
  • 刪除：server/internal/{cluster,tunnel,update}、server/cmd/relay-server、server/pkg/hwid、docker/、scripts/deploy-*.sh、server/scripts/firmware/ + update_kl720_firmware.py（flash 砍掉）

詳見 code-reuse-plan.md 與 removed-code.md。

5. 第一個 Milestone 範圍建議（M1：End-to-End Skeleton）

目標：從零起一個可以在 macOS 跑通的最小可行版本。其他平台與功能後續 milestone 處理。

# 任務 說明 預估大小
M1-1 建立 repo 骨架 local-tool/ 目錄結構 + go.mod + Makefile 骨架 S
M1-2 複製 server core 從 edge-ai-platform 複製 server/internal/{api,camera,config,deps,device,model,inference} + pkg/logger S
M1-3 清理 main.go 改寫 server/main.go：移除 cluster / tunnel / relay / hwid / GiteaURL M
M1-4 清理 config.go 砍 relay / tunnel / gitea / GUIMode 相關 flags S
M1-5 清理 router.go 刪除 /api/clusters/*、/ws/clusters/*、/auth/token S
M1-6 複製 frontend 複製 frontend/ 進 local-tool S
M1-7 清理前端 UI（Q-C=C2） M1 必做：刪除 src/app/clusters/、src/app/workspace/cluster/、src/components/cluster/、relay-token-sync.tsx、lib/api/{clusters,tunnel,update}.ts；修改 sidebar（移除 Clusters 導航項）、Dashboard（移除 cluster 卡片）、Settings（移除 relay / cluster 區塊）；最終 pnpm build 通過且 UI 乾淨、沒有殘留的 cluster / relay / tunnel 入口 M
M1-8 Go server 本地 build make build 產出 visiona-local-server（含 embedded Next.js），可直接 ./visiona-local-server 跑起來 S
M1-9 複製 installer shell 從 installer/ 複製 app.go + main.go + embed.go + platform_*.go，改名為 visiona-local M
M1-10 改寫 installer 移除 relay/dashboard 欄位、加入 Python runtime 雙策略的空殼（先走 B — 系統 Python） M
M1-11 payload 打包 make payload-macos：把 dist/visiona-local-server + data/ + scripts/ 塞進 visiona-local/payload/ S
M1-12 macOS installer build wails build → .app → ad-hoc sign → 手動打包 dmg（dmgbuild） M
M1-13 End-to-end 驗證 全新 mac 上雙擊 .dmg → 裝起來 → Mock 模式看到 3 台假裝置跑推論，且 UI 完全沒有 cluster / relay / tunnel 入口 M

M1 不做： Python runtime 內嵌（策略 A）、Windows、Linux、打包最佳化、i18n、新 Logo、yt-dlp 內嵌。 M1 必做（與前一版差異）： 前端清理已從 M2 提前到 M1（使用者決策 Q-C=C2），tray 整條從計畫中移除（使用者決策 Q-A=A3）。

M1 產出物： macOS x86_64 .dmg，可在全新機器上（只要系統有 python3）跑通 Mock 模式，且前端 UI 已清乾淨。

後續 milestone 建議（M2~M6 概覽）

  • M2：i18n 中英切換 + Settings 分頁調整（前端 cluster / relay UI 清理已於 M1 完成；tray 已砍）
  • M3：Python runtime 策略 A（內嵌 python-build-standalone）+ KneronPLUS wheel 離線安裝
  • M4：Windows Inno Setup + WinUSB driver 安裝
  • M5：Ubuntu AppImage + udev rules
  • M6：ffmpeg / yt-dlp 內嵌 + 完整依賴離線化 + 打包最佳化

6. 與 PRD / 設計規格的對應

  • PRD US-1（第一次安裝 < 3 分鐘）→ 見 packaging.md §3（首次啟動解壓流程）
  • PRD US-2（Mock 模式零門檻試玩）→ 已內建於 deviceMgr 的 mockMode flag，沿用
  • PRD US-3（插 USB 裝置自動偵測）→ 見 dependency-bundling.md §2（KneronPLUS wheel + driver）
  • Design 生命週期（關閉視窗 = 結束、single-instance）→ 見 tray-and-lifecycle.md（lifecycle 章節）
  • Design 中英雙語 → 見 i18n.md

7. 審閱紀錄

日期 審閱者 結論
2026-04-11 PM Agent 待審
2026-04-11 Design Agent 待審
2026-04-11 使用者 待確認