jim800121chen
f62141a925
使用者截圖標籤顯示「撣�」而非「布」。實證：布 的 UTF-8 位元組 e5 b8 83 用 cp950 解碼正好得到「撣�」。 根因是 bridge 的 stdio 綁在系統 ANSI code page（繁中 Windows = cp950）， 而非 UTF-8。兩個方向的表現不同： - Go → Python（stdin）：Go 的 json.Marshal 不 escape 非 ASCII，送出的是 原始 UTF-8，Python 卻用 cp950 解碼 → 標籤壞掉。這是實際的損壞路徑。 - Python → Go（stdout）：json.dumps 預設 ensure_ascii=True 會轉成 \uXXXX， 所以碰巧沒事 —— 但那是巧合不是設計。 同一根因也造成 log 的「(source: declared) �X SDK did not report」，那個 �X 是程式碼裡的 em dash 編碼失敗。 修正兩層，各自不可省： 1. kneron_bridge.py 在 module import 時強制 stdio 為 UTF-8（早於任何 I/O， import 期間的 traceback 也涵蓋），並在 os.fdopen 明確指定 encoding —— 那是 JSON-RPC 回應通道，reconfigure() 碰不到它，目前只靠 ensure_ascii 巧合存活。errors="replace" 是刻意的：bridge 崩潰會讓裝置 離線，比一個壞字元嚴重得多。 2. kl720_driver.go 加 PYTHONUTF8=1。實測 PYTHONIOENCODING 只影響 sys.stdin、 PYTHONUTF8 才管得到 os.fdopen 與 locale.getencoding()，單一層都不夠。 Go 端 stdout scanner 不需改（bufio.Scanner 是 byte-oriented，不做轉碼）。 Co-Authored-By: Claude Opus 4.8 (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 等開源社群。