docs: update PRD v3.1 and TDD v2.0 with recent installer features

PRD F17: WinUSB auto-install, ffmpeg/yt-dlp auto-install, Windows native tray (--gui mode), Registry Run auto-start, KneronPLUS SDK. PRD F18: KL520 USB Boot connect retry mechanism. TDD 8.5.14: Complete 11-step install flow, WinUSB driver details, Windows syscall tray implementation, Python auto-install. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-09 22:01:28 +08:00 · 2026-03-09 22:01:28 +08:00 · eca1363298
commit eca1363298
parent f744e8ca26
2 changed files with 68 additions and 43 deletions
--- 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 執行） |
--- 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])
 ```

 **解除安裝流程：**