jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
56 Commits 1 Branch 0 Tags
Commit Graph

56 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
jim800121chen
a6a121ae86 fix(local-tool): suppress KneronPLUS DeviceGroup.__del__ access violation 
Windows 上 bridge script 結束時 Python GC 呼叫 DeviceGroup.__del__ →
kp_disconnect_devices 對已釋放的 native handle 操作 → OSError: access
violation reading 0x00...0C。這是 KneronPLUS SDK 的 destructor 沒做
null check 的已知問題，不影響功能但會印嚇人的 stack trace 到 stderr。

修法：
- 新增 _cleanup() 函式：明確 kp.core.disconnect_devices + 把
  _device_group 設 None（讓 __del__ 成 no-op）
- atexit.register(_cleanup) 確保 interpreter 關閉前 cleanup
- main() return 後也同步呼叫一次（belt-and-suspenders）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:40:30 +08:00
jim800121chen
14d5a0ed2f docs(local-tool): Build 指引 → Installer Build 指引 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:04:38 +08:00
jim800121chen
041d872fa0 docs(local-tool): 移除 M8 重構變更紀錄 section 
使用者不需要在功能文件中看到 commit changelog。章節重新編號 6-8。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:02:56 +08:00
jim800121chen
4f9a193782 chore(local-tool): 移除模型 FPS/latency/accuracy 預估值 
使用者要求拿掉 FPS 預估數字（未經實測，不準確）。

- docs/LOCAL-TOOL-SPEC.md: 模型表格移除 FPS 欄位
- server/data/models.json: 7 個模型全部移除 fps / latencyMs / accuracy 欄位

前端 model-detail / model-card 有讀這些欄位的 UI，移除後會顯示 — 或不顯示
該列，不需要額外前端改動（已有 null/undefined fallback）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:01:25 +08:00
jim800121chen
61f9b8bf6b docs(local-tool): 功能規格文件 LOCAL-TOOL-SPEC.md 
涵蓋：
- 概述（三平台 + 完全離線安裝）
- Wails 控制台（5 階段啟動進度、timeout 機制、控制台功能、single-instance）
- Web UI（頁面路由、推論來源、結果顯示、模型管理、裝置管理、離線覆蓋層）
- 預設模型清單（KL520 × 4 + KL720 × 3）
- 內嵌依賴（Python/numpy/opencv/KneronPLUS/ffmpeg LGPL）
- Server API 摘要（系統/模型/裝置/媒體/WebSocket）
- M8 重構變更紀錄（15 個 commit 的完整 changelog）
- 資料目錄結構（三平台路徑 + 檔案說明）
- Build 指引（macOS/Windows/Linux）
- 除錯指引（Windows 啟動問題 + 常見問題）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 14:46:09 +08:00
jim800121chen
9793a2efc1 chore(local-tool): models.json 只保留有實體 .nef 的 7 個預設模型 
使用者要求：前端模型庫只保留有適配裝置的模型（KL520 4 個 + KL720 3 個）。

原本 models.json 有 15 筆：
  - 8 筆 ONNX framework 的 demo 模型（yolov5-face-detection /
    imagenet-classification / person-detection / vehicle-classification /
    hand-gesture-recognition / coco-object-detection / face-mask-detection /
    license-plate-detection）— 都沒有實體 .nef 檔，是 placeholder metadata
  - 7 筆 NEF framework 的實體模型（每個都有 filePath 指向 data/nef/）

現在只保留 7 筆實體模型：
  KL520（4 個）：
    - kl520-yolov5-detection (yolov5 no-upsample 640x640)
    - kl520-fcos-detection (fcos-drk53s 512x512)
    - kl520-ssd-face-detection (ssd_fd_lm 320x240)
    - kl520-tiny-yolov3 (tiny_yolo_v3 416x416)
  KL720（3 個）：
    - kl720-yolov5-detection (yolov5 no-upsample 640x640)
    - kl720-resnet18-classification (resnet18 224x224)
    - kl720-fcos-detection (fcos-drk53s 512x512)

server/data/models.json 是 runtime 讀取，三平台（macOS/Windows/Linux）
共用同一份，改一次三平台全部生效。

驗證：
- python3 json.load 解析正常，7 筆 entries
- 每筆 filePath 指向的 .nef 實體檔都存在於 server/data/nef/{kl520,kl720}/
- 檔案大小：1-13 MB，合計 ~64 MB
- macOS dmg 重 build 163MB OK
- Bundle 內 Contents/Resources/data/models.json 更新為 7 筆

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:44:16 +08:00
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
jim800121chen
485a2e01ff fix(local-tool): bootstrap-linux.sh 自動安裝 appimagetool 
使用者在 Linux build 時遇到「appimagetool 未安裝」錯誤（wails binary
已產出 9.3M，但打包 AppImage 失敗）。原本 bootstrap-linux.sh 只裝 Go /
Node / Wails CLI，沒裝 appimagetool，build-appimage.sh 到打包步驟才
fail。

修法：

1. bootstrap-linux.sh 新增 [5/6] 步驟自動下載 + 安裝 appimagetool
   - 從 AppImage/appimagetool 官方 continuous release 拉
     appimagetool-x86_64.AppImage
   - chmod +x + sudo mv 到 /usr/local/bin/appimagetool
   - 已安裝則跳過

2. build-appimage.sh 的 appimagetool not found 錯誤訊息更新
   - 提供一鍵安裝 curl 指令（不需重跑整個 bootstrap）
   - 提示可重跑 bootstrap-linux.sh 一併補所有依賴
   - 舊訊息裡的 URL 指向已 archived 的 AppImageKit repo，換成
     AppImage/appimagetool（新 repo 位置）

使用者立即可用（不想重跑 bootstrap）:
  curl -fsSL https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage \\
    -o /tmp/appimagetool && chmod +x /tmp/appimagetool && sudo mv /tmp/appimagetool /usr/local/bin/appimagetool
  make appimage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:11:49 +08:00
jim800121chen
fbd585ab73 fix(local-tool): Linux build 支援 webkit2gtk-4.1（Ubuntu 22.10+ / Debian 12+） 
使用者在 Linux build 看到：
  pkg-config --cflags ... webkit2gtk-4.0
  Package 'webkit2gtk-4.0' not found

根因：Wails v2.11 預設 cgo pkg-config 指定 webkit2gtk-4.0，但 Ubuntu
22.10 之後的版本已經把系統 package 從 webkit2gtk-4.0 改名為 4.1
（API 大致相容）。使用者 bootstrap 裝的是 libwebkit2gtk-4.1-dev，
pkg-config 找不到 4.0.pc 就 fail。

修法：

1. Makefile wails-linux target 自動偵測 webkit2gtk 版本
   - 優先 pkg-config --exists webkit2gtk-4.1 → wails build -tags webkit2_41
     （Wails v2.10+ 支援的 build tag，切換到 4.1 的 cgo 宣告）
   - 退回 pkg-config --exists webkit2gtk-4.0 → wails build 預設
   - 兩者都沒有 → 清楚錯誤訊息 + 建議安裝指令

2. scripts/bootstrap-linux.sh 裝 webkit2gtk dev package 時也做版本偵測
   - apt-cache show 優先查 4.1，退回 4.0
   - Ubuntu 22.04 及之前 repo 有 4.0；22.10+ / 24.04 repo 只有 4.1
   - 兩個都試過才 err

驗證：
- make -n wails-linux dry-run 正常 parse
- bash -n scripts/bootstrap-linux.sh 語法 OK
- macOS 端 make dmg 仍 work（未改 darwin target）

使用者待做：Linux 端 git pull 拉新版 → 重跑 bootstrap-linux.sh
（確保 webkit2gtk-4.1-dev 安裝）→ make appimage。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 04:11:53 +08:00
jim800121chen
f5655e38b1 feat(local-tool): hard timeout 5min + Stage 6 隱藏到 header + 全屏 splash 
回應使用者三項需求：

1. 整體 hard timeout 180s → 300s（5 分鐘）
   每個 stage 已有 soft timeout 20s 提示機制，整體 budget 不需緊湊。
   5 分鐘是「使用者點完一杯咖啡都還沒好」的心理上限。pause 機制
   （Stage 1 seed / Stage 2 Python bootstrap / Stage 3 waitHealthy）
   仍維持作為「一次性 bootstrap 完全不算 budget」的快速通道。
   - 同步更新 i18n 紅 banner 文案 180 → 5 分鐘
   - 同步更新 unit tests（HardTimeout 用 -305s，SkipBypass 用 -320s，
     PreventsHardTimeout 註解 effective<300s）

2. Stage 6「等待 Web UI 連線」從 6 階段面板隱藏到 header 連線指示燈
   Go 端 pipeline 仍保持 6 階段（不動），前端 UI 只顯示 5 階段：
   - startup-panel.js: TOTAL_STAGES=5 顯示用，PIPELINE_STAGES=6 內部
     state 用。renderStages / paintProgressBar / 進度數字都用 5。
   - updateStage 仍會收 stage 6 events 更新內部 state（控 collapse 時機）
     但 stage 6 不 paint UI（n > TOTAL_STAGES early return）
   - 新增 onConnectionStatusChange listener 機制：stage 6 status 變化
     時通知外層
   - control-panel.js: setWebUIStatus 把連線狀態 (pending/running/
     completed/failed) 渲染到 header 的 meta-webui 指示燈：圓點顏色
     + 文字 (等待連線/已連線/未連線)
   - index.html: server-meta 新增 <dd id="meta-webui"> 指示燈位置
   - i18n: control.meta.webui / control.webui.{connected,waiting,disconnected}
   - style.css: .webui-status::before 圓點 + pulse 動畫 + 顏色對應
     state (pending=灰 / running=warning+pulse / connected=success / failed=destructive)
   - app.js: 註冊 onConnectionStatusChange listener，初始化呼叫
     setWebUIStatus('pending')

3. 全屏 spinner splash 取代「啟動中...」三個字
   原本 app 啟動最一開始的「啟動中」狀態只有 header 上三個字很不
   明顯，使用者體感像沒反應。改為 DOM ready 時就顯示 fullscreen
   spinner overlay，收到第一個 startup:progress event 才隱藏。
   - index.html: <div id="boot-splash"> 內含 logo + spinner-lg + 文字
   - style.css: .boot-splash position:fixed inset:0 z-index:1000，
     .boot-splash.hidden { display:none } 用 class 控制（避免和
     [hidden]!important 衝突）
   - app.js: hideBootSplash() helper，4 個 hide 觸發點：
     (a) 收到 startup:progress event
     (b) snapshot 補漏發現 pipeline 已啟動
     (c) 收到 startup:error event（即使失敗也要看到錯誤）
     (d) handleServerStatus 收到非 idle 狀態（restart wails app
         server 還活著的情境）

更新 fix marker 為「d946561+ (5min hard timeout + 5-stage UI + fullscreen splash)」

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 01:23:55 +08:00
jim800121chen
d946561362 fix(local-tool): Stage 順序亂跳修復 + 移除秒數顯示 
兩個問題一次修：

1. Stage 順序亂跳 — 「Stage 1 等待中、Stage 2 完成、Stage 3 進行中」
   根因：Wails Webview JS load 需 1-3 秒（Windows 乾淨環境更慢），這段
   期間 Go 的 Pipeline.Start 已經 emit Stage 1 running event 甚至跑完
   Stage 1 / Stage 2，但前端 EventsOn 還沒掛上去，events 全被丟掉。前端
   接到的第一個 event 可能是 Stage 2 completed 或 Stage 3 running，
   stages[1].status 仍是初始 pending 值，UI 顯示亂序。

   修法：
   - 新增 Go binding GetStartupSnapshot() 回傳 pipeline 當前所有 stages
     狀態（含 current / startedAt / status）。
   - 前端 init 流程在 subscribeEvents 後立即拉一次 snapshot，補上漏掉
     的 stage 狀態。
   - updateStage 加 monotonic 模式：snapshot 補漏時不會用較舊狀態覆蓋
     已收到的較新狀態（避免 race condition 倒退）。
   - status 優先級 STAGE_STATUS_RANK = pending<running<{skipped,failed}<completed

2. 進度條已等待秒數顯示錯誤 — 「進度 3 / 6 · 已等待 20 秒」
   根因：pause 機制讓 elapsed 計算失準（pause 期間 wall clock 仍走但
   stages[i].startedAt 沒重設，會顯示明顯比真實還久的數字）。使用者
   覺得不需要顯示秒數。
   修法：
   - paintProgressBar 移除 elapsedText 邏輯，永遠顯示 progressLabel
   - i18n 文案移除 {elapsed} placeholder（zh-TW + en）：
     stage.1.detail.seedSlow / stage.3.detail.waitHealth /
     stage.3.detail.waitHealthSlow 都改為固定文案
   - Go 端 emit 仍會傳 elapsed（waitProgress callback 不變），但前端
     i18n template 不再用該變數，自然就不顯示

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK
- Wails bindings 自動 regen 含 GetStartupSnapshot

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 01:14:21 +08:00
jim800121chen
ff5cab6b0e feat(local-tool): hard timeout 180s + 全 stage 細步 detail emit + Stage1 seed pause 
使用者回報 Windows 仍看到「啟動時間超過 60 秒」紅 banner，且要求每個
階段做什麼都印出來給使用者知道。三件事一次到位：

1. startupHardTimeout 60s → 180s（直接放寬到 3 分鐘）
   即使三段 pause 機制（Stage 1 seed / Stage 2 Python bootstrap / Stage 3
   waitHealthy）都生效，Windows 乾淨環境段落間累積延遲仍可能超過 60 秒。
   180s 給意料之外的延遲足夠 buffer，搭配 pause + 細步進度 emit 涵蓋
   99% 情境。日常啟動只要幾秒，放寬不影響正常情境。
   - 同步更新 i18n 紅 banner 文案 60 → 180
   - 同步更新 unit tests（HardTimeout 用 -185s、SkipBypass 用 -200s、
     PreventsHardTimeout 用 wall=-300/paused=-250 對應 effective=50s）

2. Stage 1 seedUserDataDir 包進 PauseHardTimeout
   Windows 乾淨環境首次跑會被 Defender real-time scan 對 8 個 nef 檔
   逐個掃 5-30 秒。屬一次性 bootstrap，和 Stage 2/3 同理應豁免 hard
   timeout。第二次啟動 fileExists 早 early return，pause 影響 0ms。
   配套：seed 期間每 5 秒 emit slow hint 帶 elapsed 秒數，避免使用者
   看 spinner 不動以為當機。

3. 全 stage 細步 detail emit
   原本只有 Stage 3 有 sub-step 文案（spawn / waitHealth / waitHealthSlow）。
   現在 Stage 1/2/4/5/6 都有：

   Stage 1: migrate / lock / ipc / seed / seedSlow
   Stage 2: detect / bootstrap / venv / pip / driver
   Stage 3: spawn / waitHealth / waitHealthSlow
   Stage 4: probe
   Stage 5: open
   Stage 6: wait

   每個 detail 對應一段使用者能讀懂的中英文文案（i18n.js zh-TW + en）。
   前端 startup-panel 收到 startup:stage-detail event 後在對應 stage 列
   下方顯示文案，比看著「進行中...」靜止文字直觀很多。

   Stage 2 driver install 因為發生在 CompleteStage(2) 之後 current=3，
   emit 到 stage 3 而非 stage 2，避免被前端忽略（detail 只在 stage
   running 時顯示）。

更新 fix marker 為「9c9e005+ (180s hard timeout + all-stage sub-step
detail + Stage1 seed pause)」讓使用者拉新版後能從 wails.log 確認版本。

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 00:45:50 +08:00
jim800121chen
9c9e005d33 feat(local-tool): Stage 3 sub-step 進度 + 啟動完成後面板可收合 
回應使用者三項需求：
1. healthCheckTimeout 60s → 180s（涵蓋 Defender + EDR 串行延遲最壞情境）
2. Stage 3「啟動本機伺服器」期間顯示細步在做什麼，並在 15 秒後改為「首次
   啟動較久屬正常」slow hint，避免使用者看著 spinner 不動以為 app 掛了
3. 啟動完成後 6 階段面板自動收合成一行 summary，使用者點擊可展開檢視歷
   史紀錄；Restart / Retry 會重置並展開新一輪

實作：

Go 端
- healthCheckTimeout 60s → 180s（理由註解寫清楚 Defender + EDR 各自延遲）
- waitHealthy() 加 progress callback，每 5 秒呼叫一次傳入 elapsedSeconds
- StartupPipeline 加 StartupStageDetailEvent + EmitStageDetail() API
- startServerV2 在 spawn 前 emit detail.spawn，等 health check 期間 callback
  emit detail.waitHealth（< 15s）或 detail.waitHealthSlow（>= 15s）

前端
- 新訂 startup:stage-detail event → updateStageDetail() 把 i18n key 解析為
  文案存到 stages[n].detail，paintStageRow 優先顯示 detail（蓋過 slow hint）
- collapseStartupPanel() / expandStartupPanel() / resetStartupPanel() 三個新
  API 取代 hideStartupPanel；startup:ready 觸發 collapse、Retry/Restart 觸
  發 reset+expand
- collapsed CSS：保留 panel 但縮成一行 summary（標題改「啟動完成」+ ✓ +
  「點此展開檢視」hint），整個 panel 可點擊；hover 加亮
- i18n 加 6 個 keys（zh-TW + en）

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 重 build 163MB OK
- 乾淨 dataDir 啟動 wails app：startup 1 秒內完成（macOS 已 cache binary
  + Python venv），server listen 3721，Chrome 自動連上 — 整條 cold start
  正常

Windows 首次安裝預期行為（修復後）：
- Stage 1 → Stage 2（首次 bootstrap pause hard timeout，跑 1-3 分鐘）→ Stage
  3 spawn → 等 health check 30-90 秒（Defender 掃 binary）期間有「已等 N
  秒」即時更新 → ready → 自動 collapse → 瀏覽器自動開啟

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 00:17:37 +08:00
jim800121chen
a6cd1c12b2 fix(local-tool): Wails 控制台一打開就看到 modal — CSS specificity bug 
使用者回報：Windows 乾淨環境安裝後，一打開 app 就看到「Settings modal +
shutdown-modal「正在停止伺服器…」+ 紅 banner「伺服器無法啟動」」三個應該
hidden 的 element 同時可見。

前面幾個 commit 一直往 Go 端找為什麼 ctrl.Stop 會被意外呼叫，全都沒對。
真正的 bug 是 CSS specificity：

  .modal-backdrop { display: flex; ... }  /* L587，specificity (0,1,0) */
  .error-banner   { display: flex; ... }  /* L488，specificity (0,1,0) */

這兩個 class 的 `display: flex` 規則和 user agent stylesheet 內建的
`[hidden] { display: none }` specificity 相同，但因為我們的 CSS 寫在
cascade 後段勝出——結果是即使 DOM 裡元素有 `hidden` 屬性，瀏覽器依然
渲染成 `display: flex` 可見。

三個受害元素：
  <div class="modal-backdrop" id="settings-modal" hidden>
  <div class="modal-backdrop shutdown-modal" id="shutdown-modal" hidden>
  <section class="error-banner" id="error-banner" hidden>

全部從 DOM 載入第一刻就可見，和 Go 端 ctrl.Stop 是否被呼叫無關。M7
splash 時代前端沒 modal 所以沒人踩到，M8 新加的控制台 UI（8cd5751）
引入這個 bug，但 macOS dev 測試時我只看 server 端 log + api 回應，
沒真的看 Wails 視窗長什麼樣，所以也漏抓。

修法：加全域 `[hidden] { display: none !important; }`。這是 W3C 規範
的標準寫法，保證任何帶 hidden 屬性的元素都會被隱藏，不管其他 CSS
規則怎麼寫。!important 在這情境是正確的——hidden 屬性代表「該元素
不應被顯示」是規範強制語意，不該被任何樣式覆蓋。

驗證：
- macOS dmg 重 build 163MB OK
- binary 內 strings 確認 `[hidden] { display: none !important; }` 已 embed
- 清乾淨 user dataDir 後啟動 wails app，wails.log 整條 startup 流程正常：
  Stage 1 complete → Stage 2 → ctrl.Start returned successfully
- Chrome 建立 2 條 ESTABLISHED 連線到 127.0.0.1:3721
- dataDir 有完整檔案（lock / ipc-port / wails-ipc-port / sentinel / models.json / nef/）

前幾個 commit 修的東西（Stage 2 pause、waitHealthy pause、shutdown modal
safety net、Bug A killStaleServerOnPort）仍然有防禦價值，但都不是使用者
截圖症狀的 root cause。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 23:20:33 +08:00
jim800121chen
35db6c8167 fix(local-tool): Windows popup 卡死 safety net + appLog 覆蓋啟動流程 
使用者回報 c649a81 之後仍看到「正在停止伺服器…」popup 一打開就卡住。
無法在不看 log 的情況下推斷根因，先加三層 safety net 確保 popup 不是
blocker，並把關鍵啟動訊息寫到 wails.log 供 Windows 除錯。

Safety net 三層：

1. 前端 watchdog：shutdown-modal 最多顯示 15 秒，超時自動 hide 並 toast
   提示使用者 server 可能還沒停掉。
2. 前端 escape hatch：點 backdrop 空白處 / 按 Esc 可手動關閉 popup。
3. Go 端 hardBailout timer：stopGraceful 最多跑 shutdownGraceV2 + 2 秒
   （目前 = 9 秒），到上限直接 return leak process，避免 Process.Wait
   永遠阻塞（Windows 偶有情境）。graceTimer 分支的 `<-done` 也改成
   非阻塞 `select-with-1s-timeout`。

Windows 除錯 log 強化：

4. startup 頭加版本識別標記到 wails.log：
     ==================================================
     visionA-local startup build=dev buildTime=unknown
     platform=windows arch=amd64 dataDir=...
     fix marker: c649a81+ (Stage3 waitHealthy pause / shutdown modal safety net)
     ==================================================
   使用者拉新版後啟動可從此確認 build 是否是最新版。
5. app.go 把 startup 路徑上的 fmt.Fprintln(os.Stderr, ...) 改 appLog：
   IPC server start / seed failure / Stage 1 complete / ctrl.Start 結果。
   Windows 上 stderr 是 null device，appLog 會同時寫檔到 wails.log。
6. server_control.go stopGraceful 加 appLog 記錄 entry / modal-show /
   grace timer / hard bailout / return，整條 Stop 路徑完全透明。
7. driver auto-install failed 訊息也改 appLog。

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

需要使用者協助：拉新版後在 Windows 乾淨環境試，啟動後貼以下三個檔案
內容給我：
  %APPDATA%\visiona-local\logs\wails.log        — appLog 記錄整個啟動流程
  %APPDATA%\visiona-local\logs\server.stdout.log — server subprocess stdout
  %APPDATA%\visiona-local\logs\server.stderr.log — server subprocess stderr

log 裡有「fix marker: c649a81+」即為本 commit 或更新；若沒有 marker
或 marker 指向別的 commit 則代表 build 不是最新版。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 22:31:15 +08:00
jim800121chen
c649a81d9f fix(local-tool): Windows 首次啟動再修 — waitHealthy pause + shutdown modal hide 
續 a209470 修 Windows 乾淨環境啟動問題。使用者回報：
- 紅 banner「伺服器無法啟動 / 啟動時間超過 60 秒」— 即 pipeline total-timeout
- 但上方狀態列顯示「執行中 :3721 PID 8568 uptime 00:00:44」— server 實際活著
- Settings popup 上疊 shutdown-modal「正在停止伺服器…」永遠卡住

三個獨立問題：

1. Stage 3 waitHealthy 在 Windows 首次啟動時，Defender real-time scan
   會延遲 30-60 秒才讓 visiona-local-server.exe 真正 bind port。原本
   30 秒 timeout 可能 stage-failure，且這段等候時間計入 pipeline 60 秒
   total budget。修法：
   (a) healthCheckTimeout 30 秒 → 60 秒
   (b) startServerV2 的 waitHealthy call 在冷啟動時（IsInColdStart）
       包進 Pause/Resume hard timeout — 和 Stage 2 Python bootstrap 同理，
       首次 bootstrap 的 Windows Defender 掃描不該算進日常啟動預算。
       Restart（pipeline 已 ready）維持嚴格計時，不 pause。

2. stopGraceful 只 emit "shutdown:modal-show" 沒有對稱的 hide event，
   前端 popup 顯示後無法關閉（只能等應用重開）。修法：
   (a) stopGraceful 用 defer emit "shutdown:modal-hide"（若曾 show）
   (b) 前端 app.js 加對應 EventsOn listener 把 hidden attribute 設回

3. 配套：cwd bash working dir 會在 session 內持久（system prompt 明說
   "working directory persists between commands"），但 env vars 不持久
   — 非本次 commit 相關，僅自己的 mental note。

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 重 build 163MB OK

給 Windows 驗證用的 log 位置：
  %APPDATA%\visiona-local\logs\server.stdout.log     — server 端 log
  %APPDATA%\visiona-local\logs\server.stderr.log     — server 端 panic / 崩潰
  %APPDATA%\visiona-local\logs\wails.log             — Wails app (appLog) 訊息

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 21:59:20 +08:00
jim800121chen
a2094708ec fix(local-tool): Windows 乾淨環境啟動失敗 — Stage 2 豁免 hard timeout 
使用者在 Windows 乾淨環境跑 installer 後首次啟動，看到「伺服器無法
啟動」紅 banner + Settings Stop 卡住。根因：

Stage 2 ensurePythonRuntime 在首次 bootstrap 要做 (1) 解壓 ~15MB
Python tarball (2) 建 venv (3) pip install 9 個 wheel（含 numpy 20MB
+ opencv 50MB + KneronPLUS 等 ~150MB 解壓後）。乾淨 Windows 環境上
這三步合計 2-5 分鐘，遠超 R5-E1 的 60 秒 startup hard timeout，導致
pipeline FailStage + emitError(total-timeout) → Error state → 紅 banner。

R5-E1 的 60 秒預算是針對「日常啟動」，不含首次一次性 bootstrap。

修法：StartupPipeline 加 PauseHardTimeout / ResumeHardTimeout API，
app.go 在 ensureBundledPython 偵測到「真正 bootstrap」條件（pythonBin
不存在）時呼叫 Pause，defer Resume。暫停期間 sinceTotal 扣掉 paused
duration，hard timeout 不觸發。Soft timeout（每階段 20 秒「正在重試」
hint）照常，使用者仍能看到進度提示。

配套：修 killStaleServerOnPort 識別 go run 編出來的 server（Bug A）。
原本用 ps -o comm= 比對 "visiona-local-server" 字串，但 go run 產物
comm 只是 "server"（或 "exe"），生產環境不受影響，但開發 / Reviewer
測試流程會踩到（早上 M8-4 Reviewer 留了一組 go run server 孤兒占住
port 3721 到現在）。改用 ps -o args= 取完整 command line，匹配 規則：
  1. 含 "visiona-local-server" — packaged binary
  2. 含 "/go-build" 且含 "visiona-local/server" 或 "/exe/server" — go run

驗證：
- visiona-local 套件 go build / vet / test / test -race 全綠
- server 套件 go build / vet / test 全綠
- 3 個新 unit test 通過：
  - PauseHardTimeout_ExcludesPausedDuration（effective 時鐘正確扣除）
  - PauseHardTimeout_PreventsHardTimeout（wall clock 120s + paused 90s
    = effective 30s，不觸發 60s hard timeout）
  - ResumeHardTimeout_NoopWhenNotPaused（idempotent）
- macOS dmg 重 build 163MB OK

待做（M8-10b）：使用者在 Windows 乾淨環境重新 install + 驗證首次啟動。
如果仍失敗，Windows log 位置：
  %APPDATA%\visiona-local\logs\server.stdout.log
  %APPDATA%\visiona-local\logs\server.stderr.log
  %APPDATA%\visiona-local\logs\wails.log（若有）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 21:30:59 +08:00
jim800121chen
dd35b561cf chore(local-tool): regen wails bindings — 補 M8 漏提的 binding 產物 
M8 重構（8cd5751）加了很多新 Wails binding（ClearLogs / ExportLog /
ForceKillServer / GetBootstrapStatus / GetPreferences / GetRecentLogs /
GetServerStatusV2 / GetSystemInfo / InstallKneronDriver / OpenInBrowser
/ RestartServer / RestartStartupSequence / RevealLogsFolder / SavePreferences
/ 等）+ 新增 struct（Preferences / LogLine / ServerStatusV2 / SystemInfo）。
wails build 時會 regen wailsjs/go/ 下的 bindings，但上次 M8 commit 時沒
把 regen 結果一併提上去，所以磁碟上的 bindings 和 go source 不同步。

這次 M8-10a build 時自動 regen，順手把 diff 提上來。純產物，無邏輯變更。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 20:23:37 +08:00
jim800121chen
d7cddf364b fix(local-tool): 拆 built-in / user data dir — 修預設模型永遠載入 0 個 
M8-10a smoke test 抓到 M1 就潛藏的 P0 latent bug：server 預設 dataDir =
<binary>/data，bundle 內解析成 Contents/Resources/bin/data/（空目錄），
實際 models.json + 8 個 .nef 住在 Contents/Resources/data/（上一層）。
Wails 又傳 --data-dir 成 user home（writable），同樣沒 models.json。
結果任何正式啟動路徑下 /api/models 都回 total: 0，M1-M7 smoke 從沒
跑過這個 endpoint 才漏抓。

修法：把「read-only bundle 內資料」和「writable user 資料」語意拆開。

- 新增 findFirstExisting(candidates, sentinel) helper
- 新增 resolveBuiltInDataDir：①VISIONA_BUNDLE_LIB_DIR/data（AppImage）
  ②<base>/data ③<base>/../data ④<base>/../Resources/data
  ⑤<base>/../lib/visiona-local/data（Linux FHS）。命中條件是
  models.json 存在為 regular file，避開 Wails build artifact 留下的
  空 data/ 目錄
- main() 拆 builtInDataDir（modelRepo + flash.Service 用）與 dataDir
  （custom-models / sentinel / logs 用），職責分明
- flash.NewService 改吃 builtInDataDir — 它要解析 models.json 裡的
  相對路徑 "data/nef/kl520/xxx.nef"，來源是 bundle 不是 user home
- resolveBridgeScript 同步修（同樣的技術債一起清），候選 env var 優先
  + FHS fallback，避免 Linux AppImage 上 kneron_bridge.py 也找不到
- fallback 全 filepath.Abs 化，log.Printf 印嘗試過的路徑清單便於除錯

驗證（build / vet / test + smoke）全綠：
- macOS bundle：/api/models → 15 models ✅
- dev mode（server/ 下 go run）：15 models ✅
- Linux AppImage 模擬 + env var：命中候選 1 ✅
- Linux AppImage 模擬 + 無 env var：命中候選 5（FHS）✅
- 全不命中：log 印完整 tried 清單 + server 不 crash ✅

Reviewer 兩輪通過。第一輪抓到 Linux AppImage 未覆蓋（Major-1）+ 2 Minor
+ 2 Suggestion；第二輪確認全部處理到位、新發現兩項非阻擋風格建議列為
技術債。報告見 .autoflow/05-implementation/reviews/review-m8-10a-*.md。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 20:23:25 +08:00
jim800121chen
8cd5751ce3 feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策） 
依 R5 五輪決策把 visionA-local 從「Wails 內嵌 Next.js」重構為「Wails
本機伺服器控制台 + 瀏覽器 Web UI」模式（類比 Docker Desktop / Ollama）。

程式碼變動
  - M8-1 砍 yt-dlp 全套（後端 resolver / URL handler / 前端 URL tab /
    Makefile vendor / installer / bootstrap / CI workflow，-555 行）
  - M8-2 砍 Mock 模式全套（driver/mock、mock_camera、Settings runtimeMode、
    VISIONA_MOCK 環境變數，-528 行）
  - M8-3 ffmpeg 從 GPL 切換到 LGPL 混合方案：Windows/Linux 用 BtbN 現成
    LGPL binary，macOS 自 build minimal decoder-only 進 git
    （vendor/ffmpeg/macos/ffmpeg 5.7MB + ffprobe 5.6MB，比 GPL 版省 85% 空間）
  - M8-4 Wails Server Controller：state machine、log ring buffer 2000 行、
    preferences.json atomic write、boot-id、Gin SkipPaths、shutdown 7+1 秒、
    notify_*.go 三平台 OS 通知、watchServer 改 Error state 不 os.Exit
  - M8-4b 啟動階段管線 R5-E：6 階段進度 event、20s soft / 60s hard timeout、
    stage 5/6 skip 規則、sentinel file、RestartStartupSequence 5 步驟
  - M8-5 Wails 控制台 vanilla HTML/JS/CSS（9 檔 ~2012 行）取代 M7-B splash：
    state 視覺、log panel、startup progress panel、Stage 6 manual CTA
    pulse、shutdown modal、Settings、Dark Mode、i18n 中英雙語
  - M8-6 上傳影片副檔名擴充（mp4/avi/mov/mpeg/mpg）
  - M8-7 Web UI Server Offline Overlay（role=alertdialog + focus trap +
    wsEverConnected 容錯 + Page Visibility）
  - M8-8 CORS middleware（127.0.0.1/localhost only + suffix attack 防護）+
    ws/origin.go 獨立 WebSocket CheckOrigin 避 package cycle
  - MAJ-4 server:shutdown-imminent WebSocket broadcast 機制
    （/ws/system endpoint + notifyShutdownImminent helper）
  - M8-9 Boot-ID + 瀏覽器 tab 自動重連（sessionStorage loop guard）

品質
  - ~105+ 新 unit test + race detector (-count=2) 全綠
  - 10 個 milestone 全部通過 Reviewer 審查
  - 三方 v2 + v2.1 文件（PRD / Design Spec / TDD）+ 交叉互審紀錄
    收錄在 .autoflow/

交付前待處理（M8-10）
  - 重跑 make payload-macos 把舊 GPL 77MB binary 換成新 LGPL
  - 三平台 end-to-end build 驗證

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 17:57:54 +08:00
jim800121chen
a6b71ea908 fix(local-tool): URL 影片載入提示「正在解析，請耐心等待」 
URL 送出後 yt-dlp 解析 + ffmpeg probe 可能花 10-30 秒，
使用者只看到按鈕 loading 會以為卡住。

加一行黃色 animate-pulse 提示：
「正在解析影片連結，YouTube 影片可能需要 10-30 秒，請耐心等待...」

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-13 00:57:03 +08:00
jim800121chen
c0317225ca feat(local-tool): yt-dlp 錯誤訊息友善化 + 載入逾時提示 
ResolveWithYTDLP 改善：
- 新增 friendlyYTDLPError() 把 yt-dlp 的技術性 stderr 訊息轉成繁中提示
- 涵蓋 9 種常見失敗原因：
  年齡限制 / 私人影片 / 已移除 / 版權 / 直播 / 首播 / DRM / 頻率限制 / 無格式
- 錯誤訊息同時附上原始 stderr（方便 debug）
- yt-dlp 未安裝時改用繁中提示

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-13 00:56:15 +08:00
jim800121chen
f13848cf0b fix(local-tool): workspace 推論面板跑版 — 右側面板固定寬度 
右側 InferencePanel 沒設寬度也沒 shrink-0，被左側 CameraInferenceView
擠壓到只剩幾十 px，文字垂直排列。

修法：
- InferencePanel 外層加 w-80 shrink-0（固定 320px 不縮小）
- CameraInferenceView 外層加 min-w-0（允許 flex item 收縮到 0）
- gap-6 改 gap-4（省一點空間）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 23:36:20 +08:00
jim800121chen
00192d3d1e fix(local-tool): yt-dlp / ffmpeg 找不到 — VISIONA_BUNDLE_BIN_DIR 加到 PATH 
根因：Go 1.19+ Windows 的 exec.LookPath 不再搜尋 current directory，
而 exec.Command("yt-dlp") / exec.Command("ffmpeg") 只走 LookPath。
Wails app 有設 VISIONA_BUNDLE_BIN_DIR 環境變數指向 {app}\bin\，
但 server 的 deps/checker.go 只在 startup 檢查時用它，沒把它加到 PATH。

修法：server main.go 啟動時把 VISIONA_BUNDLE_BIN_DIR prepend 到 PATH。
這一次解決三個問題：
- yt-dlp: cannot run executable found relative to current directory
- ffmpeg 攝影機列舉找不到 ffmpeg binary
- ffmpeg camera capture 也找不到

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 23:32:02 +08:00
jim800121chen
96dee565b3 fix(local-tool): 補上 Kneron KL520/KL720 韌體檔案 
根因：KL520 在 USB Boot 模式下（fw=KDP2 Loader）需要先載入韌體到 RAM
才能接受模型載入。kneron_bridge.py connect 流程會自動呼叫
kp.core.load_firmware_from_file()，但前提是找到韌體檔案：
  scripts/firmware/KL520/fw_scpu.bin + fw_ncpu.bin
  scripts/firmware/KL720/fw_scpu.bin + fw_ncpu.bin

這些檔案在 M1 從 edge-ai-platform 搬程式碼時漏了，補入。
Makefile 的 payload-windows/linux/macos 的 cp -R server/scripts/
會自動帶入 firmware/ 子目錄。

KL520: scpu 51KB + ncpu 39KB
KL720: scpu 128KB + ncpu 2.0MB

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 23:11:47 +08:00
jim800121chen
aa324cef42 fix(local-tool): flash 模型檔案找不到 — 相對路徑未解析 
根因：models.json 的 filePath 是相對路徑（"data/nef/kl520/xxx.nef"），
但 server working directory 是 {app}\bin\（app.go 設 cmd.Dir = binary 目錄），
所以 server 在 {app}\bin\data\nef\ 找 .nef 檔，找不到。

實際位置：{app}\data\nef\（installer 裝的位置），對應 server 的 --data-dir
由 Wails app 傳入的 %APPDATA%\visiona-local（或 fallback 到 <exe>/../data）。

修法：
- flash.NewService 新增 dataDir 參數
- StartFlash 中把相對 filePath 用 dataDir 拼接成絕對路徑：
  "data/nef/..." → 去掉 "data/" 前綴 → dataDir + "/nef/..."
- main.go 傳 dataDir 給 flash.NewService

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 22:03:28 +08:00
jim800121chen
c24a04cdb2 fix(local-tool): Review minor m1/m2/m4 修復 
m1（i18n 混用不一致）：
- flash-dialog.tsx 所有英文字串改繁中（載入模型 / 選擇模型 / 硬體不相容 / 開始載入 / 關閉 / 完成）
- flash-progress.tsx 同理（模型載入失敗 / 重試 / 正在準備載入 / 模型載入完成）

m2（Dialog 關閉防護不完整）：
- 改用 isInProgress 判斷（isFlashing || progress 未到 100%）+ 沒 error
  而非只看 isFlashing，涵蓋「API 回應了但 WS 進度還在跑」的情況

m4（WS 3 秒 timeout 應 reject）：
- connectAndWait timeout 改 reject + Error message
- flash-dialog handleFlash 加 try/catch 捕捉 WS 連線失敗
  → 呼叫 setError 讓 UI 顯示錯誤而非靜默卡住

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 20:21:18 +08:00
jim800121chen
3c6971febd fix(local-tool): Review M1-M4 + m5 修復 — flash 生命週期 + store 隔離 
Review 問題修復：

M1（寫已關閉 channel panic）：
- flash service goroutine 改成先等 driver.Flash() 返回，再寫 error 訊息，最後 close
- driver.Flash 返回後保證不再寫 progressCh，消除 race condition

M2（FlashTask 永不清除 memory leak）：
- service.go 新增 CleanupTask(taskID) 公開方法
- device_handler.go 的 goroutine 在 `for range progressCh` 結束後呼叫 CleanupTask

M3（同裝置重複 flash taskID 衝突）：
- ProgressTracker.Create 改成：舊 task 未完成時返回 nil
- StartFlash 檢查 nil → 回傳 "flash already in progress" 錯誤

M4（前端 flash store 全域不區分 deviceId）：
- flash-store.ts 新增 activeDeviceId 欄位
- updateProgress 改接 (deviceId, progress)，比對 activeDeviceId 防止混裝
- use-flash-progress.ts 的 WebSocket callback 傳入 deviceId

m5（flash_ws.go 雙重 conn.Close）：
- read pump goroutine 移除 defer conn.Close()，由外層 defer 統一關閉

額外修復（S4）：
- modelPath 為空時直接回 error 而非傳無效路徑給 driver

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 20:16:24 +08:00
jim800121chen
44711753ae feat(local-tool): 推論功能完整搬入 — flash 模組 + workspace 推論介面 
## 後端（Phase 1）
新增 flash 模組（從 edge-ai-platform 搬入）：
- server/internal/flash/service.go：StartFlash + 模型相容性檢查 + 晶片 NEF 解析
- server/internal/flash/progress.go：Flash 進度追蹤器
- server/internal/api/ws/flash_ws.go：WebSocket 推送 flash 進度
- device_handler.go：新增 FlashDevice method + flashSvc 欄位
- router.go：新增 POST /api/devices/:id/flash + WS /ws/devices/:id/flash-progress
- main.go：初始化 flash.NewService 並傳入 router

推論/攝影機/MJPEG/inference WebSocket 之前 M1 已搬好，不需改動。
Python bridge (kneron_bridge.py) 與 edge-ai-platform 完全相同，不需改動。

## 前端 store + hooks（Phase 2）
- stores/flash-store.ts（新）：Zustand store — startFlash / updateProgress / retryFlash / reset
- hooks/use-flash-progress.ts（新）：WebSocket hook 接收 flash 進度

inference-store / camera-store / inference types / use-inference-stream / use-websocket
之前 M1 已搬好，不需改動。

## 前端 UI 元件（Phase 3）
- components/devices/flash-dialog.tsx（新）：模型載入對話框 + 硬體相容性檢查
- components/devices/flash-progress.tsx（新）：Flash 進度條 + 錯誤重試

camera-inference-view / camera-feed / camera-overlay / source-selector /
inference-panel / performance-metrics / classification-result / confidence-slider /
video-progress / batch-image-thumbnails 之前 M1 已搬好。

## 前端頁面整合（Phase 4）
- workspace/page.tsx：繁中硬編碼、顯示已載入模型名稱
- workspace/[deviceId]/workspace-client.tsx：加入 FlashDialog 按鈕 + 繁中硬編碼
- devices/[id]/device-detail-client.tsx：加入 FlashDialog + 「進入工作區」按鈕（模型已載入才顯示）
- device-card.tsx：已連線 + 模型已載入時顯示「工作區」快捷按鈕

## 使用者操作流程
裝置列表 → 連線 → 管理 → 載入模型 → 進入工作區 → 選攝影機/圖片/影片 → 開始推論 → 看 bounding box / FPS / latency
或：裝置列表 → 工作區（已有模型）→ 直接推論

## 不搬的東西
- cluster/* 全部不搬（已砍 cluster 功能）
- relay / tunnel 相關不搬

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 20:07:09 +08:00
jim800121chen
819885c85d fix(local-tool): SPA fallback 改用 Next.js dynamic route shell HTML 
根因：點模型卡片 → /models/yolov5-face-detection → server SPA fallback
固定回傳根路徑 /index.html（儀表板） → Next.js CSR router 初始化時
pathname 對不上 → 使用者被跳回儀表板。

修法：spaFallback handler 改成三層 fallback：
1. 精確檔案（/models/index.html 等）
2. Next.js dynamic route shell（把最後一段替換為 _ → /models/_/index.html）
   這是 generateStaticParams 產的 placeholder 頁面，Next.js CSR 會從 URL
   讀真正的 param 值
3. 根目錄 /index.html（最終 fallback）

這修好了：
- 模型詳情頁 /models/:id 不再跳回儀表板
- 裝置詳情頁 /devices/:id 同理
- 工作區裝置頁 /workspace/:deviceId 同理
- Sidebar active 狀態也會正確（因為 pathname 匹配了）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 19:44:25 +08:00
jim800121chen
ebe86663b1 fix(local-tool): i18n type error — 用 devices.status.connecting/disconnecting 
devices.connecting / devices.disconnecting 不在 TranslationDict type 裡，
改用已存在的 devices.status.connecting + 新增 devices.status.disconnecting。
刪掉上一個 commit 多加的頂層 devices.connecting / disconnecting key。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 19:11:36 +08:00
jim800121chen
ae5dfe1739 fix(local-tool): 連線 loading + 資料目錄平台路徑 + 卡片排版 
A. 連線 / 斷線按鈕加 loading state：
- device-store.ts 新增 connectingId / disconnectingId state
- connectDevice / disconnectDevice 用 try/finally 包裹確保 reset
- device-card.tsx 按鈕加 Loader2 spinner + disabled
  當任一裝置正在連線/斷線時所有按鈕都 disabled，防止連按
- i18n 新增 connecting / disconnecting 字串

C. 設定 > 一般 > 資料目錄顯示平台正確路徑：
- 用 navigator.userAgent 偵測平台
  - Windows: %APPDATA%\visiona-local
  - Linux: ~/.local/share/visiona-local
  - macOS: ~/Library/Application Support/visiona-local
- 修正 Python 版本顯示 3.11 → 3.12

D. 裝置卡片排版修正：
- 名稱和狀態 badge 之間加 gap-3
- 名稱區域 min-w-0 + truncate 防止 badge 被擠到換行
- 連線中時 badge 顯示 connecting 狀態

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 18:57:06 +08:00
jim800121chen
9b0d946acd feat(local-tool): splash 顯示實時啟動進度 + 拉長 timeout + 修正執行模式顯示 
Splash 進度：
- app.go 新增 bootstrapStatus field + GetBootstrapStatus() binding
- 各 startup step 呼叫 setBootstrapStatus 更新文字：
  "正在初始化 Python 環境..."
  "正在解壓 Python runtime (~10 秒)..."
  "正在建立 Python 虛擬環境 (~5 秒)..."
  "正在安裝 N 個 Python 套件 (numpy / opencv / KneronPLUS ...) (~30-60 秒)..."
  "正在安裝 Kneron USB 驅動程式 (請在 UAC 視窗點「是」)..."
  "正在準備應用程式資料..."
  "正在啟動伺服器..."
  "等待伺服器就緒..."
  "載入主介面..."
- visiona-local/frontend/app.js 每 400ms 呼叫 GetBootstrapStatus 更新畫面
- wailsjs/go/main/App.js 手動補上新 binding export（避免等 wails generate）

Timeout：
- splash MAX_WAIT_MS 60s → 240s（涵蓋 UAC 被拖延 + 慢速硬碟）
- healthCheckTimeout 15s → 30s（server 首次啟動內部解析 + embed fs 載入）

設定 > 硬體 > 執行模式：
- 顯示預設值從 mock 改為 real（跟 app.go 實際預設對齊 - Q8 決策）
- 下拉選單寬度 240 → 420px 避免文字被截斷
- i18n 說明文字改為「預設為真實硬體模式，強制 Mock 請設 VISIONA_MOCK=1」
- 仍標 disabled — 未來 M8+ 會連 backend GET /api/system/config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 08:42:59 +08:00
jim800121chen
3355a096b8 feat(local-tool): 首次啟動自動安裝 Kneron WinUSB driver 
行為改變：Wails app 首次啟動會在 venv 就緒後、spawn server 前自動呼叫
libwdi 安裝 Kneron WinUSB driver。使用者不再需要手動點「安裝 USB Driver」
按鈕（按鈕保留供失敗後重試用）。

實作：
- startServer() step 1.5 新增 ensureDriverInstalled() 呼叫
- 用 <dataDir>/.driver-installed 記號檔避免每次啟動都彈 UAC
- 失敗不擋 server 啟動，只寫 log，使用者可稍後手動重試
- 新增 app-level log helper appLog() 寫到 <dataDir>/logs/wails.log
  （Wails Windows 以 windowsgui subsystem build，os.Stderr 指向 null device，
   沒有這個檔使用者看不到 startup 期間的 debug 訊息）
- 手動 InstallKneronDriver binding 成功時也寫記號檔

使用者移除 .driver-installed 檔就能強制重裝（例如 Windows 更新把 driver 弄壞時）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 08:03:37 +08:00
jim800121chen
d1ff55005a debug(local-tool): driver install verbose 輸出 + 安裝後自我驗證 
- Python script 對每個 PID install 後 capture traceback，不再 swallow
- 裝完立刻 scan_devices() 驗證 SDK 能不能開 handle，印 is_connectable
- 安裝結果完整寫到 server.stderr.log（而不是只回錯誤摘要）
- 判斷 DONE 標記 + 至少一個 OK 才算成功

這讓我們能清楚看到 libwdi 到底是「沒權限 / DLL 載入失敗 / 綁定成功但
裝置 is_connectable 還是 False（代表 driver 層級 OK 但裝置需要重插）」
哪一種情境，而不是只看到籠統的「error 28」。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 07:38:43 +08:00
jim800121chen
4902cb5531 feat(local-tool): Kneron WinUSB driver 透過 KneronPLUS SDK libwdi 安裝 
根因：
  KP_ERROR_CONNECT_FAILED (error code 28) — Kneron USB 裝置預設沒綁定
  WinUSB driver，SDK 無法開 handle。原 .iss 的 pnputil /add-driver 做法
  需要 .cat 簽章（Windows 10/11 driver signing enforcement），我們沒有。

參考 edge-ai-platform/installer/platform_windows.go 的 installKneronDriverViaSDK：
  KneronPLUS SDK 內建 libwdi wrapper — kp.core.install_driver_for_windows(pid)
  libwdi 會自動用臨時自簽憑證，不需要 .cat 檔，只需要 UAC 提權。

實作：
- server/internal/api/handlers/system_driver_windows.go（新）：
  組 Python script → kp.core.install_driver_for_windows 對 KL520/KL720/KL720_LEGACY →
  PowerShell Start-Process -Verb RunAs 提權執行 → 結果寫 temp 檔讀回
- server/internal/api/handlers/system_driver_other.go（新）：非 Windows stub
- system_handler.go: NewSystemHandler 新增 pythonBin 參數 + InstallDriver handler
  先判斷 runtime.GOOS==windows 才執行
- router.go: 新增 POST /system/install-driver
- main.go: 解析 pythonBin（VISIONA_PYTHON env var → cfg.PythonBin）傳入

前端：
- frontend/src/app/devices/page.tsx：Windows only 多一個「安裝 USB Driver」按鈕
  （用 navigator.userAgent 判斷平台）
- frontend/src/stores/device-store.ts：connect 失敗訊息偵測 winusb / error 28 /
  KP_ERROR_CONNECT_FAILED 特徵字串，回一條明確的繁中提示引導使用者去點按鈕

Wails app 端：
- visiona-local/app.go: 新增 InstallKneronDriver() binding 作為備用入口（目前前端沒用到，
  因為前端跑在 http://127.0.0.1 不是 wails://，但保留給未來 splash 階段觸發用）
- visiona-local/platform_{windows,darwin,linux}.go: installKneronWinUSBDriver 平台實作
  / 跨平台 stub

.iss:
- 移除 pnputil /add-driver 的 [Run] entry（它是 silent-fail 的 dead code，
  因為沒 .cat 簽章）
- 新增註解說明：driver 安裝改由 app 端呼叫 libwdi 完成

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 05:25:32 +08:00
jim800121chen
f8533a6b04 fix(local-tool): sidebar icon + Wails Windows icon.ico + 掃裝置路徑修復 
sidebar E icon：
- frontend/src/components/layout/sidebar.tsx 左上角的 "E" 方塊換成 <img> 指向
  /visiona-logo.png，從 frontend/public/visiona-logo.png serve

Wails 桌面/工作列 icon：
- 把 branding/icon.ico 複製到 visiona-local/build/windows/icon.ico
- Wails v2 Windows build 偵測到這個檔案就會直接用它當 exe embedded icon，
  不再從 appicon.png 自動 resize（解析度更好）

掃裝置根因修復：
1. server main.go：新增 resolveBridgeScript() 智慧找 kneron_bridge.py
   - 優先 <exe>/scripts/kneron_bridge.py
   - fallback <exe>/../scripts/... 對應 Windows installer 的 {app}\bin\ + {app}\scripts\ 佈局
   - fallback <exe>/../Resources/scripts/... 對應 macOS app bundle

2. server kneron/detector.go：ResolvePython 重寫
   - 最高優先：VISIONA_PYTHON 環境變數（由 Wails 殼層注入）
   - 加入 visiona-local 新路徑：%APPDATA%\visiona-local\runtime\venv、
     ~/Library/Application Support/visiona-local/runtime/venv、
     ~/.local/share/visiona-local/runtime/venv
   - 保留 edge-ai-platform 舊路徑作為 legacy fallback

3. visiona-local/app.go：spawn server 時 export VISIONA_PYTHON=<pyBin>
   讓 detector 直接用 Wails 殼層已經 resolve 好的 python interpreter，
   不再自己獨立去找造成不一致。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 04:59:23 +08:00
jim800121chen
50a3f73acd feat(local-tool): 品牌視覺設計 + 內建模型首次啟動 seed 
#8 首次啟動 seed 內建模型：
- app.go 新增 seedUserDataDir() 在 server spawn 之前執行
- 若 user data-dir 缺 models.json，從 locateBundleDataDir() 複製
  models.json + nef/ 預置模型過去
- 新增 locateBundleDataDir() / copyFile() / copyDirRecursive() helper
- user 第一次開 app 會看到 8 個 Kneron 預置 .nef 模型（kl520×5 + kl720×3）

#5 #6 #7 品牌視覺：
- 新增 branding/ 目錄存放設計資產與生成工具
  - logo.svg（向量原始稿）
  - icon-{16,...,1024}.png（10 種尺寸）
  - icon.ico（Windows 多解析度 ICO，PNG-in-ICO 格式）
  - icon.icns（macOS）
  - tools/gen_icon.go + gen_ico.go（純 Go 生成工具，未來調整 logo 用）
  - README.md + 色票表
- 部署：
  - visiona-local/build/appicon.png → Wails build 會嵌入 exe
  - visiona-local/frontend/icon.png → splash 使用
  - frontend/src/app/favicon.ico + icon.png → Next.js App Router favicon
- splash page 升級：加 logo icon + 品牌名 visionA Local + tagline Edge AI Workspace
- Wails window title: "visionA Local — Edge AI Workspace"
- wails.json productName: "visionA Local"
- Next.js metadata title + icons
- i18n: en/zh-TW 把殘留的 "Edge AI 平台" 字串改為 visionA Local 品牌
- .iss: SetupIconFile 指向 branding/icon.ico + UninstallDisplayIcon +
  ArchitecturesAllowed 改 x64compatible 修掉之前的 deprecation warning

品牌色票：
- 主色 #4F7EFF（電子藍）
- 輔色 #6EF3C5（mint 點綴）
- 深色背景漸層 #1A1F36 → #0E1222
- 警示 #FF6B6B

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 04:42:41 +08:00
jim800121chen
8e7b6ae435 feat(local-tool): clean build 為預設 + 藏 server 小黑窗 + 預設真實模式 
Makefile:
- 新增 clean-all target：clean + wails build/ + frontend build/ + server embed
- 新增 clean-build-exe / clean-build-dmg / clean-build-appimage

bootstrap-windows.ps1:
- 預設改為 clean build（每次重做 wails + server binary + frontend embed）
- 保留 vendor/ 快取避免重下 200MB+ 第三方相依
- 需要 fast path（只重跑 iscc）時設 VISIONA_FAST=1

app.go:
- configureSysProcAttr() 注入子行程，Windows 下 CREATE_NO_WINDOW 藏掉 server 小黑窗
- 覆蓋 server spawn / tar 解壓 / venv 建立 / pip install 四個關鍵點
- mockMode 預設改 false（依使用者決策 Q8，預設走真實硬體模式）
  需要強制 mock 時設環境變數 VISIONA_MOCK=1

platform_{windows,darwin,linux}.go:
- 新增 configureSysProcAttr(cmd)：Windows 設 HideWindow + CREATE_NO_WINDOW，
  macOS/Linux 空實作

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 04:25:09 +08:00
jim800121chen
eb52f8c690 fix(local-tool): locateServerBinary 找 {app}\bin\ 子目錄（Windows/Linux installer 佈局） 
根因：Windows installer 把 visiona-local-server.exe 裝到 {app}\bin\
      （.iss 的 DestDir: "{app}\bin"），但 locateServerBinary 只搜
      exeDir\visiona-local-server.exe 和 macOS bundle 專屬路徑，
      Windows/Linux 打包後的 bin/ 子目錄完全沒被搜尋，導致執行時
      "server binary not found" 嚴重錯誤。

修法：
- locateServerBinary 第一優先搜 exeDir\bin\visiona-local-server
  （Inno Setup installer / AppImage 的標準佈局）
- 開發模式 fallback 新增 payload/<goos>/bin/ 候選路徑
- 同時修正 locateBundleBinDir / locateBundledPythonAssets 的開發模式
  fallback 寫死 "payload/darwin"，改用 runtime.GOOS 動態選 payload 子目錄

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 03:45:17 +08:00
jim800121chen
83981e5b1b docs(local-tool): progress.md 記錄 M7 Windows 一鍵 build + splash regression 
- 新增 M7-A：Windows 一鍵 build 工具鏈踩坑紀錄（11 項修好）
- 新增 M7-B：splash regression P0 修復（visiona-local/frontend 殘留 wizard → 改為 splash+redirect）
- 補「M1 驗收流程漏看 Wails 視窗內容」到未解決問題，作為後續 M 任務驗收 checklist
- 補 ffmpeg GPL release blocker 到未解決問題清單

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 03:35:20 +08:00
jim800121chen
570e040a67 fix(local-tool): Wails 主視窗改為 splash + redirect 到 Next.js 主 UI 
根因：visiona-local/frontend/ 是從 edge-ai-platform 複製過來的 installer wizard
HTML/JS/CSS，整組沒清理。main.go 的 //go:embed all:frontend 把這堆 wizard
直接當 Wails 主視窗內容，使用者開啟 app 看到的就是 "Edge AI Platform Installer"
而不是 Next.js 主 UI。macOS dmg 版本也有同樣問題，只是之前驗證時沒開 Wails
視窗而是用瀏覽器直連 localhost:3721 所以沒抓到。

修法：把 visiona-local/frontend/ 重寫為極簡 splash：
- index.html：splash 畫面
- app.js：import GetServerStatus / GetServerURL binding，輪詢直到 server ready，
  window.location.replace(url + '/') 跳到 Next.js 主 UI
- style.css：splash 樣式

Next.js 主 UI 不使用任何 Wails JS binding（純 HTTP API），所以從 wails://
跳到 http://127.0.0.1:<port>/ 後功能完整可用。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 03:32:31 +08:00
jim800121chen
1c5866ed14 debug(local-tool): Windows build 失敗追蹤 
Makefile _run-iscc:
- 開頭印出 ISCC 環境變數和 PATH 前幾項，確認有沒有正確傳進來

bootstrap-windows.ps1:
- 不再用 bash.exe -lc "..." 傳整條字串（含空格路徑會被 PS 雙層 quoting 切斷）
- 改寫成 tmp .sh 檔，用 bash.exe -l file.sh 執行
- 執行前印出 script 內容，執行後刪掉 tmp 檔
- script 開頭加 'set -e' 確保任何一行失敗立即停止並回非 0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 03:17:07 +08:00
jim800121chen
06031206af feat(local-tool): Windows build fast path + 產物驗證 
Makefile:
- 新增 exe-only target：只跑 iscc 打包 installer，不重 build wails/payload
- 拆出 _run-iscc 共用 recipe，exe 和 exe-only 都依賴它

bootstrap-windows.ps1:
- 偵測 visiona-local.exe / server.exe / ffmpeg.exe / python.tar.gz 都在時走 fast path
  只跑 make exe-only，省掉重複 wails build 的數分鐘
- 跑完驗證 dist\visiona-local-*-windows-x64.exe 確實存在，否則明確 Fail 並提示手動 iscc 指令

使用情境：使用者刪掉 dist\ 想重打 installer，再跑一次 bootstrap 就能秒出 .exe

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 03:11:42 +08:00
jim800121chen
4521ee3119 fix(local-tool): Inno Setup 6.3+ 不再內建 ChineseTraditional.isl 
Inno Setup 6.3 起官方只保留 ChineseSimplified，繁體中文語系需額外下載。
改為以 WITH_TRAD_CHINESE 宏條件啟用，預設只用英文 installer UI，
避免在新版 Inno Setup 上直接 compile error。

這只影響「安裝精靈本身」的語系，應用程式 UI 的 i18n 不受影響。
未來若要帶繁體中文 installer，下載 istrans 檔案後用 iscc /DWITH_TRAD_CHINESE=1 編譯。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 02:45:51 +08:00
jim800121chen
80252b12dc chore(local-tool): 為 make exe 加診斷輸出 
印出 iscc 的 cwd、exit code、dist/ 實際內容，
避免靜默失敗讓人找不到產物去向。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 02:41:51 +08:00
jim800121chen
dbad729da3 fix(local-tool): Inno Setup 偵測加入 user-scope 安裝路徑 
winget 7.x 的 Inno Setup 可能裝到 %LOCALAPPDATA%\Programs\Inno Setup 6\
而非傳統的 Program Files (x86)。新增 user-scope 固定路徑 + HKCU 登錄檔 +
%LOCALAPPDATA%\Programs 遞迴掃描三種偵測方式。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 02:35:13 +08:00
jim800121chen
e6f7afe8db fix(local-tool): 強化 Inno Setup 偵測，支援 ISCC 環境變數 override 
Makefile (exe target):
- 新增 ISCC 環境變數 override（絕對路徑優先）
- 偵測順序：\$ISCC → command -v iscc → 已知絕對路徑
- 找不到時列出已嘗試路徑方便 debug

bootstrap-windows.ps1:
- Find-Iscc 函數改用多層策略：固定路徑 → 登錄檔 InstallLocation → Program Files 遞迴掃描
- 偵測不到就自動 winget --force 重裝再試一次
- 同時 export PATH 和 ISCC 雙保險傳給 Makefile

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 02:27:38 +08:00
jim800121chen
634e4011fd fix(local-tool): bootstrap 把 Inno Setup 目錄加進 MSYS2 bash PATH 
winget 裝的 Inno Setup 6 在 'C:\Program Files (x86)\Inno Setup 6\'，
不在 PATH 裡，MSYS2 bash 找不到 iscc.exe 導致 make exe 失敗。
改由 bootstrap 主動偵測安裝路徑並 export 進 bash session PATH。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 02:23:37 +08:00
jim800121chen
13ce654ac2 fix(local-tool): ffmpeg zip 下載改用相對路徑 
Windows 版 python.exe 不懂 MSYS2 的 /tmp 路徑語法，會拿著字面值 '/tmp/...'
去 Windows filesystem 找不到檔案。改下載到 vendor/ffmpeg/windows/ffmpeg-win.zip
相對路徑，bash 跟 python 都看得懂。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 02:17:18 +08:00