diff --git a/edge-ai-platform/docs/PRD-Integrated.md b/edge-ai-platform/docs/PRD-Integrated.md index dd884c3..7bc247f 100644 --- a/edge-ai-platform/docs/PRD-Integrated.md +++ b/edge-ai-platform/docs/PRD-Integrated.md @@ -8,8 +8,8 @@ |------|------| | 文件名稱 | 邊緣 AI 開發平台 PRD | | 產品名稱 | (暫未定名,以下稱「本平台」) | -| 版本 | v2.7 | -| 日期 | 2026-03-02 | +| 版本 | v3.1 | +| 日期 | 2026-03-09 | | 狀態 | 更新中 | --- @@ -1217,21 +1217,26 @@ Kneron Dongle Arduino 開發板 非 Kneron 晶片 | 項目 | 規格 | |------|------| -| **概述** | 提供非技術人員可使用的桌面 GUI 安裝精靈,雙擊即可完成所有安裝步驟(server binary、Python 環境、系統依賴、硬體驅動),無需開終端機或輸入任何指令 | -| **目標平台** | macOS (.dmg → .app) + Windows (.exe installer) | +| **概述** | 提供非技術人員可使用的桌面 GUI 安裝精靈,雙擊即可完成所有安裝步驟(server binary、Python 環境、系統依賴、硬體驅動、媒體工具),無需開終端機或輸入任何指令 | +| **目標平台** | macOS (.app) + Windows (.exe installer) | | **技術方案** | Go + Wails v2(WebView-based GUI),前端以 HTML/CSS/JS 實作安裝畫面,後端 Go 執行實際安裝邏輯。共用 Go 工具鏈,無需額外 runtime | -| **安裝精靈流程** | 6 步驟:(1) 歡迎頁 + 授權協議 → (2) 安裝路徑選擇 → (3) 元件選擇(必要/可選)→ (4) 自動安裝 + 即時進度 → (5) 硬體偵測結果 → (6) 完成 + 啟動選項 | -| **必要元件(自動安裝)** | edge-ai-server binary(含嵌入式前端)、Python 3 venv + numpy + opencv-python-headless + pyusb、Kneron 韌體檔案(KL520 + KL720)、NEF 預訓練模型、libusb(USB 裝置通訊) | -| **可選元件** | ffmpeg(攝影機/影片串流)、yt-dlp(YouTube 影片下載) | -| **自動依賴解析** | macOS: 自動安裝 Homebrew(若未安裝)→ `brew install libusb python3 ffmpeg`;Windows: 自動下載 Python embedded + libusb DLL,免管理員權限 | -| **即時進度顯示** | 每個安裝步驟獨立顯示進度條 + 狀態文字(下載中 → 解壓中 → 設定中 → 完成),失敗時顯示錯誤訊息 + 重試按鈕 | +| **安裝精靈流程** | 6 步驟:(1) 歡迎頁 + 授權協議 → (2) 安裝路徑選擇 → (3) 元件選擇(必要/可選)→ (4) 自動安裝 + 即時進度(11 子步驟)→ (5) 硬體偵測結果 → (6) 完成 + 啟動選項 | +| **自動安裝步驟** | 11 步驟依序執行:(1) 建立安裝目錄 → (2) 解壓 server binary → (3) 解壓模型與韌體 → (4) 解壓腳本 → (5) 系統設定(symlink/PATH)→ (6) USB 驅動安裝(libusb DLL + WinUSB driver)→ (7) Python 環境設定(venv + requirements + KneronPLUS SDK)→ (8) 媒體工具安裝(ffmpeg + yt-dlp)→ (9) 寫入設定檔 → (10) 驗證安裝 → (11) 設定自動啟動 | +| **必要元件(自動安裝)** | edge-ai-server binary(含嵌入式前端)、Python 3 venv + numpy + opencv-python-headless + pyusb + KneronPLUS SDK(.whl)、Kneron 韌體檔案(KL520 + KL720)、NEF 預訓練模型、libusb(USB 裝置通訊)、WinUSB driver(Windows,pnputil 自動安裝) | +| **媒體工具(自動安裝)** | ffmpeg(攝影機/影片串流)、yt-dlp(YouTube 影片下載);macOS 透過 Homebrew、Windows 透過 winget、Linux 透過 apt-get/pip3 | +| **自動依賴解析** | macOS: `brew install libusb ffmpeg yt-dlp`;Windows: libusb-1.0.dll(payload 內建)+ WinUSB driver(pnputil `/add-driver`)+ Python 3(winget 自動安裝)+ ffmpeg/yt-dlp(winget);Linux: `apt-get install libusb-1.0-0-dev ffmpeg` | +| **WinUSB 驅動安裝** | 自動解壓 kneron_winusb.inf + co-installer DLLs 並透過 `pnputil /add-driver /install` 安裝 WinUSB driver,涵蓋 KL520(VID_3231&PID_0100)、KL720 KDP(PID_0200)、KL720 KDP2(PID_0720)。無需手動安裝 Zadig | +| **即時進度顯示** | 每個安裝步驟獨立顯示進度條 + 狀態文字,失敗的非關鍵步驟顯示 warning 並繼續;關鍵步驟失敗則中止安裝並顯示錯誤訊息 | | **硬體偵測** | 安裝完成後自動掃描 USB Kneron 裝置,顯示偵測到的晶片型號(KL520/KL720)、韌體版本、連線狀態;KL720 KDP legacy 裝置提示一鍵韌體更新 | -| **解除安裝** | 內建解除安裝功能:刪除 server binary + Python venv + 資料檔案 + symlink/PATH,macOS 提供拖曳到垃圾桶 + 深度清理選項,Windows 整合「新增或移除程式」 | +| **Windows Server 控制** | Windows 安裝後以 `--gui` 模式啟動,透過原生 Windows syscall 在系統匣顯示圖示(綠色=運行中、紅色=已停止),右鍵選單提供 Start/Stop Server、Open Dashboard、Quit 功能,無需 CGO | +| **macOS Server 控制** | macOS 安裝後以 `--tray` 模式啟動,透過 fyne.io/systray 顯示系統匣圖示與選單 | +| **自動啟動** | macOS: launchd plist(`~/Library/LaunchAgents/`),Windows: Registry Run key(`HKCU\...\Run`,免管理員權限),Linux: systemd user service | +| **解除安裝** | 內建解除安裝功能:刪除 server binary + Python venv + 資料檔案 + drivers + symlink/PATH + 自動啟動設定 | | **安裝目錄** | macOS: `~/.edge-ai-platform/`(不需 sudo)、Windows: `%LOCALAPPDATA%\EdgeAIPlatform\`(不需管理員) | -| **安裝完成動作** | 可選擇立即啟動 server + 自動開啟瀏覽器(`http://localhost:3721`)、建立桌面捷徑、設定開機自動啟動 | +| **安裝完成動作** | 可選擇立即啟動 server(Windows: 系統匣 GUI、macOS: system tray)+ 自動開啟瀏覽器(`http://localhost:3721`)、設定開機自動啟動 | | **更新支援** | 偵測現有安裝版本,僅更新 binary + 新模型,保留使用者資料(custom-models、設定檔)與 Python venv | -| **打包產出** | macOS: `EdgeAI-Installer.dmg`(含 .app + 背景圖 + Applications 捷徑)、Windows: `EdgeAI-Setup.exe`(NSIS + Wails 包裝) | -| **安裝體積** | 完整安裝約 300-400 MB(binary ~10MB + 模型 ~73MB + Python venv ~250MB + firmware ~2MB) | +| **打包產出** | macOS: `EdgeAI-Installer-macOS.zip`(含 .app)、Windows: `EdgeAI-Installer-Windows.zip`(含 .exe) | +| **安裝體積** | 完整安裝約 300-400 MB(binary ~10MB + 模型 ~73MB + Python venv ~250MB + KneronPLUS SDK ~4MB + firmware ~2MB + drivers ~3MB) | #### F18 — Kneron 硬體通訊整合(KL520 + KL720) @@ -1240,7 +1245,7 @@ Kneron Dongle Arduino 開發板 非 Kneron 晶片 | **概述** | 雙晶片 Kneron USB Dongle 完整通訊管線已驗證,涵蓋 USB 偵測、晶片感知連線、韌體載入/更新、模型載入、即時推論與多模型後處理 | | **支援裝置** | Kneron KL520 (VID 0x3231, PID 0x0100, USB 2.0) + KL720 (PID 0x0720 KDP2 / PID 0x0200 KDP legacy, USB 3.0) | | **晶片感知架構** | Driver 從 `device_type` 或 `product_id` 自動推導晶片類型(KL520/KL720),所有行為依晶片動態調整 | -| **KL520 USB Boot** | 無板載 Flash 韌體,每次連線自動上傳 fw_scpu.bin + fw_ncpu.bin;每 USB session 僅能載入一個模型(Error 40 限制),換模型需 reset + bridge restart | +| **KL520 USB Boot** | 無板載 Flash 韌體,每次連線自動上傳 fw_scpu.bin + fw_ncpu.bin;USB Boot 模式 `is_connectable=False` 為正常狀態,使用 `connect_devices_without_check()` 連線並附帶重試機制(最多 3 次,含 re-scan);每 USB session 僅能載入一個模型(Error 40 限制),換模型需 reset + bridge restart | | **KL720 Flash-based** | KDP2 韌體預燒在 SPI Flash,連線免上傳韌體;無 Error 40 限制,可自由切換模型 | | **KL720 KDP→KDP2 更新** | KL720 出廠可能為舊版 KDP 韌體(PID=0x0200),透過 DFUT magic bypass (`0x1FF55B4F`) 連線後以 `kp_update_kdp_firmware_from_files()` 永久更新為 KDP2;更新後 PID 變為 0x0720 | | **SDK** | Kneron PLUS SDK v3.1.2,從 C 原始碼編譯為 macOS dylib(Apple Silicon 透過 Rosetta 2 執行) | diff --git a/edge-ai-platform/docs/TDD.md b/edge-ai-platform/docs/TDD.md index 67397ca..d6e727a 100644 --- a/edge-ai-platform/docs/TDD.md +++ b/edge-ai-platform/docs/TDD.md @@ -8,8 +8,8 @@ |------|------| | 文件名稱 | 邊緣 AI 開發平台 TDD | | 對應 PRD | PRD-Integrated.md v2.7 | -| 版本 | v1.6 | -| 日期 | 2026-03-02 | +| 版本 | v2.0 | +| 日期 | 2026-03-09 | | 狀態 | 更新中 | --- @@ -2012,39 +2012,59 @@ type StepProgress struct { └─────────────────────────────────────────────────────────┘ ``` -**安裝步驟實作細節:** +**安裝步驟實作細節(已實作):** -| 步驟 | macOS 實作 | Windows 實作 | -|------|-----------|-------------| -| 下載 binary | `net/http` GET → Gitea release tar.gz | `net/http` GET → Gitea release zip | -| 解壓 | `archive/tar` + `compress/gzip` | `archive/zip` | -| symlink | `os.Symlink()` → `/usr/local/bin/edge-ai-server` (需確認權限) | 加入 User PATH (`os.Setenv` + registry) | -| libusb | `exec.Command("brew", "install", "libusb")` 或內嵌 dylib | 內嵌 `libusb-1.0.dll` 到安裝目錄 | -| Python venv | `exec.Command("python3", "-m", "venv", ...)` | `exec.Command("python", "-m", "venv", ...)` 或內嵌 Python embedded | -| pip install | `venv/bin/pip install numpy opencv-python-headless pyusb` | `venv\Scripts\pip install ...` | -| ffmpeg | `brew install ffmpeg` (可選) | `winget install Gyan.FFmpeg` 或內嵌 (可選) | -| 硬體偵測 | `exec.Command(python, "kneron_detect.py")` | 同左 | -| 桌面捷徑 | `~/Desktop/EdgeAI.command` | `shell:desktop\EdgeAI.lnk` (COM API) | -| 開機啟動 | `~/Library/LaunchAgents/com.innovedus.edge-ai.plist` | `HKCU\...\Run` registry | +安裝流程共 11 步驟,依序執行: -**macOS 無 Homebrew 情境處理:** +| # | 步驟 | 進度% | Critical | macOS 實作 | Windows 實作 | +|---|------|-------|----------|-----------|-------------| +| 1 | 建立安裝目錄 | 5 | Yes | `os.MkdirAll` | 同左 | +| 2 | 解壓 server binary | 10 | Yes | 從 `embed.FS` payload 解壓 | 同左 | +| 3 | 解壓模型與韌體 | 30 | Yes | 遞迴解壓 `payload/data/` | 同左 | +| 4 | 解壓腳本 | 48 | Yes | 遞迴解壓 `payload/scripts/` | 同左 | +| 5 | 系統設定 | 55 | No | `os.Symlink` → `/usr/local/bin/` + 移除 quarantine | 加入 User PATH (PowerShell) | +| 6 | USB 驅動安裝 | 62 | No | `brew install libusb` | 解壓 `libusb-1.0.dll` + WinUSB driver (`pnputil /add-driver kneron_winusb.inf /install`) | +| 7 | Python 環境 | 70 | No | `python3 -m venv` + `pip install -r requirements.txt` + KneronPLUS SDK .whl | 同左(Windows 自動以 `winget install Python.Python.3.12` 安裝 Python) | +| 8 | 媒體工具 | 78 | No | `brew install ffmpeg yt-dlp` | `winget install Gyan.FFmpeg` + `winget install yt-dlp.yt-dlp` | +| 9 | 寫入設定檔 | 85 | Yes | `config.json` → `~/.edge-ai-platform/` | `config.json` → `%LOCALAPPDATA%\EdgeAIPlatform\` | +| 10 | 驗證安裝 | 90 | No | 檢查 binary 存在且大小 > 0 | 同左 | +| 11 | 自動啟動 | 95 | No | launchd plist + `launchctl load` | Registry Run key (`HKCU\...\Run`) + 立即啟動 `--gui` | + +**WinUSB Driver 自動安裝(Windows):** ``` -if !commandExists("brew") { - // 方案 A: 提示安裝 Homebrew(推薦) - // 方案 B: 直接下載 libusb dylib 放入安裝目錄 - // 設定 DYLD_LIBRARY_PATH 環境變數 +payload/drivers/ +├── kneron_winusb.inf # WinUSB INF(支援 KL520 + KL720 全系列) +└── amd64/ + ├── WdfCoInstaller01011.dll # WDF co-installer + └── winusbcoinstaller2.dll # WinUSB co-installer +``` + +- INF 涵蓋裝置:VID_3231&PID_0100(KL520)、VID_3231&PID_0200(KL720 KDP)、VID_3231&PID_0720(KL720 KDP2) +- 安裝方式:`pnputil /add-driver kneron_winusb.inf /install` +- 來源:co-installer DLLs 取自 `local_service_win/LocalAPI/win_driver/amd64/` +- 失敗處理:non-fatal,不中斷安裝 + +**Windows Server 控制(`--gui` 模式):** + +Windows notray build 無法使用 `fyne.io/systray`(需 CGO),改用純 Go syscall 實作原生 Windows 系統匣: +- `Shell_NotifyIconW` 顯示 tray icon(綠=運行、紅=停止,嵌入 ICO 檔案) +- `CreatePopupMenu` + `TrackPopupMenu` 右鍵選單 +- `FreeConsole()` 脫離父 console,`CREATE_NO_WINDOW` 隱藏子 process 視窗 +- Build tag: `//go:build notray && windows` + +**Python 環境自動安裝:** + +```go +// Windows: winget 自動安裝 Python 3.12 +func installPython3Windows() { + exec.Command("winget", "install", "Python.Python.3.12", "--silent") + // 自動搜尋 %LOCALAPPDATA%\Programs\Python\Python3XX\ 並加入 PATH } -``` -**Windows 無 Python 情境處理:** - -``` -if !commandExists("python") && !commandExists("python3") { - // 方案 A: 自動下載 Python embeddable package (無需安裝) - // 解壓到 installDir/python/,直接使用 - // 方案 B: 提示使用者安裝 Python (winget install Python.Python.3.12) -} +// venv 建立後安裝 KneronPLUS SDK +matches, _ := filepath.Glob(filepath.Join(scriptsDir, "KneronPLUS*.whl")) +exec.Command(pipPath, "install", matches[0]) ``` **解除安裝流程:**