jim800121chen
30d0ff5695
症狀：Mac 版上傳單張圖推論，畫面完全沒有 bbox 標註。實測追根因後發現
兩層獨立問題疊加（前端 + 後端），擇一修復都無法解決。
## Layer 1: 前端 canvas 尺寸對不上 img 顯示尺寸
- camera-inference-view.tsx renderedSize 初始值硬寫 {w:640, h:480}
- ResizeObserver 理應在 <img> load 後 fire，但實測沒 fire 或時機不對
- 結果 overlay canvas 永遠用 640×480 畫，bbox 嚴重偏位或跑出 canvas
修法（camera-feed.tsx + camera-inference-view.tsx）：
- <img> 加 onLoad handler，decode 完立刻用 getBoundingClientRect 回報
- ResizeObserver effect 進來先檢查 img.complete && naturalWidth > 0，
是就立刻 report（cover HMR / cached image）
- effect 依賴加 streamUrl / batchImageUrl，換圖會重觀察
- renderedSize 初始值改 null，overlay 改為拿到真實尺寸才 render
- setState callback 用 prev 比對，同尺寸不觸發 render
- camera-overlay.tsx 加 [bbox-debug] console.log 保留（debug 成本低，
對未來排查有幫助）
## Layer 2: KL520 推論炸 ApiKPException Error 15
- kp.inference.generic_image_inference_send 回 SEND_DATA_TOO_LARGE
- 試過 image 尺寸（516×640 / 640×794 / 640×640 host pad）、numpy vs
bytes、明確傳 width/height — 全部炸
- Python bridge 直接測試（/tmp/test_bridge.py）做完整
`connect → reset → reconnect → load_model → inference` 序列 → 11 個
detection 正常回傳
- Go driver 走 `connect → load_model → inference` 跳過 reset
根因：commit ddf0eb8（2026-04-16）「KL520 首次 connect 跳過 reset」當時
為解 Windows 60s HTTP timeout 的優化。但副作用：KL520 若 session 間
firmware 殘留（fw=KDP2 Comp/U），直接 load_model + inference 100% 炸
Error 15。必須走完整 reset → 退回 Loader → 重新載 firmware → Comp/U
流程才能得到能 inference 的 session。
修法（kl720_driver.go）：
- 移除「KL520 跳過 reset」特例，讓 KL520 和 KL720 都走 needsReset → restartBridge
- 註解記錄 trade-off：KL520 connect 時間 ~2s → ~15-20s（macOS），
Windows 可能 60s+
## HTTP timeout 配套調整
- device_handler.go ConnectDevice timeout 60s → 120s
- Windows worst-case（~65s：Loader reconnect 16s + firmware load 31s +
reboot 8s + reconnect 5s）留 buffer，避免 504 CONNECT_TIMEOUT
## Bridge 清理
- kneron_bridge.py 清掉中途試驗遺留的 `_host_preproc` 死碼
（還原成原版 _correct_bbox_for_letterbox）
- 加了 debug log（Inference: sending / parse done / EXCEPTION with
traceback）保留，未來排查 inference 路徑很有用
## 驗證（function 層）
/tmp/test_bridge.py 三種尺寸全通過：
- 516×640 直式 → 11 detections (person×8, tie×3) latency 308ms
- 1920×1080 横式 → 0 detections（合成圖，正常）
- 512×512 正方 → 0 detections
## 待使用者驗證
- Mac UI 實測：上傳 ~/Downloads/000000000459.jpg 應見 11 個 bbox 精準框住
- Windows 實測 connect 耗時 + timeout 是否足夠
- Linux 實測
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
visionA-local
裝起來像一般 app，離線也能跑，接上 Kneron 就推論。 把
edge-ai-platform的 Kneron AI 邊緣推論能力，打包成單機桌面應用。
這是什麼
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）
- 從內部 Gitea Releases 下載
visiona-local.dmg - 雙擊開啟 dmg → 把
visionA-local.app拖到Applications/ - 第一次啟動：因為未做程式碼簽章，Gatekeeper 會警告「來自未識別開發者」
- 在 Finder 中右鍵點
visionA-local.app→ 選「開啟」（不是雙擊） - 對話框出現「仍要開啟」時點確認
- 往後直接雙擊即可
- 在 Finder 中右鍵點
- 首次啟動會花 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
.exeinstaller - 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 等開源社群。