# Legacy local-tool README（已封存）

> **此檔僅作歷史保留。**
>
> 以下內容是 visionA Agent 於 2026-04-22 從 `local-tool/`（baseline commit `b71ff4cd3c72e879435f773ae15b23bf8b70841e`）fork 時的原始 README 後半段。
>
> 內容描述的是 **local-tool**（單機桌面 Kneron 工具）的產品定位、安裝流程、功能清單與不做的事，**並非 visionA Agent 的當前定位**。
>
> visionA Agent 的真實定位請見 `local-agent/README.md`：
> - visionA Agent **就是** tunnel client（local-tool 明確排除「Tunnel」）
> - visionA Agent 的 UI 只剩 3 頁配置（狀態 / 配對 / 設定），不保留 local-tool 的裝置 / 模型 / 推論 UI
> - visionA Agent 不會單獨上架，靠雲端 visionA-backend 驅動
>
> 保留此檔的目的：
> 1. 未來若需從 local-tool cherry-pick bug fix，可比對原始 README 釐清 baseline 行為
> 2. 部分 build 流程（Makefile target、三平台 installer）仍延用 local-tool 結構，這份原文是歷史對照
>
> 若內容已不再有參考價值，可整檔刪除。

---

> **裝起來像一般 app，離線也能跑，接上 Kneron 就推論。**
> 把 `edge-ai-platform` 的 Kneron AI 邊緣推論能力，打包成單機桌面應用。

![macOS x86_64](https://img.shields.io/badge/macOS_x86__64-beta-brightgreen)
![Windows x86_64](https://img.shields.io/badge/Windows_x86__64-TBD-lightgrey)
![Linux x86_64](https://img.shields.io/badge/Linux_x86__64-TBD-lightgrey)
![License](https://img.shields.io/badge/license-TBD-orange)

<!-- TODO: docs/screenshots/logo.png -->

---

## 這是什麼

local-tool 是 `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）

1. 從內部 Gitea Releases 下載 `visiona-local.dmg`
2. 雙擊開啟 dmg → 把 `visionA Local.app` 拖到 `Applications/`
3. **第一次啟動**：因為未做程式碼簽章，Gatekeeper 會警告「來自未識別開發者」
   - 在 Finder 中**右鍵點 `visionA Local.app` → 選「開啟」**（不是雙擊）
   - 對話框出現「仍要開啟」時點確認
   - 往後直接雙擊即可
4. **首次啟動會花 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 `.exe` installer
- 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

### ❌ 不做的事（明確排除）

> ⚠️ 注意：以下排除清單是 **local-tool** 的設計邊界，**不適用於 visionA Agent**。
> visionA Agent 的核心能力之一就是 Tunnel（與此清單相反）。

為了聚焦「個人工具」，以下功能從 `edge-ai-platform` 全數砍掉：

- ❌ Cluster（多裝置叢集）
- ❌ Relay / Tunnel（遠端連線、反向代理）
- ❌ 韌體燒錄（firmware flash）
- ❌ 系統列 Tray 常駐
- ❌ Auto-update
- ❌ Telemetry / 崩潰回報
- ❌ License 啟用、憑證簽章
- ❌ Mac App Store / Microsoft Store / Snap Store 上架

---

## 開發者區（local-tool 結構，僅供對照）

### 專案結構

```
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
```

> visionA Agent 沿用大部分目錄結構，但 `visiona-local/` → `visiona-agent/`、Bundle ID / 安裝路徑 / lockfile 全部獨立。詳見 `local-agent/docs/BUILD-VERIFICATION.md`。

### 開發流程

```bash
# 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`（local-tool）/ `visiona-agent.dmg`（visionA Agent） |
| `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 需要對應平台）。

---

## 已知限制與 TODO（local-tool 原文）

- 🟡 **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。

---

## 致謝 / 起源

local-tool 衍生自 Innovedus 內部專案 `edge-ai-platform`（原為部署於 EC2 + Docker 的多人共享平台）。本專案將其改造為單機桌面版本，聚焦「一個人帶一台筆電」的使用場景。

感謝 Kneron、python-build-standalone（astral-sh）、shadcn 等開源社群。