jim800121chen
3f0175f1a9
從 local-tool 複製出獨立的「visionA Agent」桌面應用（A3 純橋樑： tunnel client + 配對 UI + 設定，不開 HTTP port、不做本機裝置/推論 UI）。 Bundle ID 與 local-tool 不同（com.innovedus.visiona-agent vs visiona-local）， 雙 app 可共存。fork 後不主動 sync，需要時手動 cherry-pick。 Backend / Wails Go（AB1-AB13）： - internal/tunnel：6 狀態機（Idle/Connecting/Connected/Reconnecting/Failed/Stopped） + Pair/Unpair/Reconnect/Disconnect binding + ClientHooks event - internal/auth：encrypted file token store（AES-GCM + scrypt + machineID fallback salt + 13 tests） - internal/config：YAML validation + atomic write + 11 tests - internal/log：ring buffer + ExportLog 升級 zip - visionA-backend /api/pairing/exchange：SessionTokenStore + 17 new tests - 三平台 build 驗證（macOS DMG 160 MB / Windows EXE / Linux AppImage） - end-to-end 5 milestone 全綠（pairing → tunnel → forward → reuse 防護 → tunnel drop failover） Frontend / Next.js（AF1-AF7，沿用 visionA-frontend 基礎）： - AppShell + Header + TabNav（StatusView / PairView / SettingsView 三 tab） - ConnectionStatusBadge 5 種狀態 - TokenInput regex 驗證 + 7 種錯誤 + 0.5s auto-switch 到狀態頁 - 設定頁 4 區塊（含重新配對 AlertDialog） - agent-api.ts 封裝 Wails bindings（mock/real 雙實作）+ 90 tests Phase 0.7 review-driven fix（Round 2）： - A1 Session fixation 防護（RotateSessionID） - A3 mock pairing 預設改 false（必須明確 opt-in）+ startup log - A4 Pair 失敗後 state 清理矩陣（exchange/Save/Start fail 各自終態） - A5 Pair/Unpair/Reconnect lifecycleMu + 50 goroutine race test - F1 重新配對次按鈕 / F2 PairView Esc cancel / F3 Wails BrowserOpenURL / F4 Settings draft 持久 + 未儲存 badge 驗證：agent backend go test -race -count=3 ./... 4 packages 全綠 / agent frontend pnpm test 119 tests 全綠 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
105 lines
5.3 KiB
Markdown
105 lines
5.3 KiB
Markdown
# visionA Agent
|
||
|
||
> **Phase 0 雛形 — 正在建置中**
|
||
>
|
||
> 此專案於 2026-04-22 從 `local-tool/` fork，baseline commit：`b71ff4cd3c72e879435f773ae15b23bf8b70841e`
|
||
>
|
||
> **fork 後獨立演進，不主動與 local-tool 同步。** 需要時手動 cherry-pick bug fix。
|
||
|
||
## 產品定位
|
||
|
||
visionA Agent 是 visionA 雲端版的 local 端代理程式：
|
||
|
||
**它是什麼**
|
||
- 一個完整的 local server（沿用 local-tool 的 KneronPLUS / camera / inference / device / model / Python runtime / ffmpeg 邏輯）
|
||
- 加上 **tunnel client**，把自己 reverse-tunnel 到雲端 `visionA-backend`，讓雲端 web UI 可以透過 tunnel 操作使用者桌機上的 Kneron 裝置
|
||
- 加上 **3 頁極簡配置 UI**（狀態 / 配對 / 設定），給使用者看「Agent 是否在線」和「配對雲端帳號」用
|
||
|
||
**它不是什麼**
|
||
- 不是 local-tool 的修改版（local-tool 不動；visionA Agent fork 後獨立演進）
|
||
- 不保留 local-tool 原本的裝置 / 模型 / 推論 UI（這些由雲端 web UI 負責；本機 UI 只管配對/設定）
|
||
|
||
## 目前進度（Phase 0 雛形）
|
||
|
||
| 任務 | 狀態 | 說明 |
|
||
|------|------|------|
|
||
| AB1 | ✅ | fork + 改名（visiona-local → visiona-agent / bundle ID / Makefile 變數 78 處替換） |
|
||
| AB2+AB3 | ✅ | 裁剪 Wails 業務 UI binding、刪除舊資料目錄遷移；新增 pairing / connection / settings 的 stub binding（回 ErrNotImplemented），為 AB4-AB10 預留擴點 |
|
||
| AB4 | ⏳ | 複製 tunnel client（從 POC）到 `internal/tunnel/` |
|
||
| AB5 | ⏳ | Agent config (YAML) 讀寫 |
|
||
| AB6 | ⏳ | Internal HTTP server（wrapper 綁 127.0.0.1:0） |
|
||
| AB7 | ⏳ | Pairing Exchanger（呼叫雲端 `/api/pairing/exchange`） |
|
||
| AB8 | ⏳ | connstate broadcaster + Wails event 推送 |
|
||
| AB9 | ⏳ | autostart 三平台實作 |
|
||
| AB10 | ⏳ | logexport（壓縮最近 7 天 log） |
|
||
| AB11-12 | ⏳ | Wails 整合 + 整合測試 |
|
||
|
||
## 架構圖（簡版）
|
||
|
||
```
|
||
[ Browser ] ── HTTPS ──► [ visionA-backend ]
|
||
│ （內部 HTTP forward）
|
||
▼
|
||
[ remote-proxy ]
|
||
│ （WSS + yamux 出站長連線）
|
||
▼
|
||
┌───────────────────────────────────────────────────────┐
|
||
│ visionA Agent（使用者桌機，Wails app） │
|
||
│ │
|
||
│ [Tunnel client] [3 頁配置 UI] │
|
||
│ │ │ Wails bindings │
|
||
│ ▼ ▼ │
|
||
│ [Internal HTTP server 127.0.0.1:<random port>] │
|
||
│ （沿用 local-tool 的 Gin handler：裝置/模型/推論/...） │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ [Python runtime + KneronPLUS SDK + ffmpeg] │
|
||
└───────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
Kneron USB 裝置
|
||
```
|
||
|
||
## 文件
|
||
|
||
- 架構 TDD：[`.autoflow/04-architecture/visiona-agent-tdd.md`](./.autoflow/04-architecture/visiona-agent-tdd.md)
|
||
- UI 規格：[`.autoflow/03-design/visiona-agent-spec.md`](./.autoflow/03-design/visiona-agent-spec.md)
|
||
- ADR：[`.autoflow/04-architecture/adr/adr-007-*.md`](./.autoflow/04-architecture/adr/)（架構）、`adr-008-*.md`（tunnel 複用）、`adr-009-*.md`（token 儲存）
|
||
- 開發進度：[`.autoflow/progress.md`](./.autoflow/progress.md)
|
||
- Build / 共存驗證：[`docs/BUILD-VERIFICATION.md`](./docs/BUILD-VERIFICATION.md)
|
||
|
||
## fork baseline
|
||
|
||
本專案於 2026-04-22 從 `local-tool/`（commit `b71ff4cd3c72e879435f773ae15b23bf8b70841e`）一次性 fork 後獨立演進，**不主動 sync**（ADR-007）。
|
||
|
||
local-tool 原始 README 已封存於 [`docs/legacy-local-tool-readme.md`](./docs/legacy-local-tool-readme.md)，僅作 cherry-pick bug fix 時的歷史對照，不再代表 visionA Agent 的產品定位。
|
||
|
||
## 開發指令
|
||
|
||
```bash
|
||
# 下載第三方依賴到 vendor/
|
||
make vendor-sync
|
||
|
||
# 本機 build + 產出 macOS DMG
|
||
make dmg
|
||
|
||
# 列出所有 targets
|
||
make help
|
||
```
|
||
|
||
主要 targets（沿用 local-tool 結構，但所有產物名稱已替換為 `visiona-agent`）：
|
||
|
||
| Target | 作用 |
|
||
|--------|------|
|
||
| `vendor-sync` | 下載 python-build-standalone / wheels / ffmpeg |
|
||
| `build-frontend` | pnpm build Next.js 靜態產物 → `frontend/out/` |
|
||
| `wails-sync-frontend` | 同步 `frontend/out/` → `visiona-agent/frontend/`（Wails embed） |
|
||
| `wails-macos` / `wails-windows` / `wails-linux` | Wails build + ad-hoc codesign（macOS） |
|
||
| `dmg` | 產出 `dist/visiona-agent.dmg`（缺 create-dmg 時 fallback hdiutil） |
|
||
| `exe` | Inno Setup → `dist/visiona-agent-*-windows-x64.exe`（需 Windows runner） |
|
||
| `appimage` | `dist/visiona-agent-*-x86_64.AppImage`（需 Linux runner） |
|
||
| `dev-agent` | Wails dev mode |
|
||
| `test-tunnel` | tunnel client 整合測試 |
|
||
|
||
三平台 build 細節與 local-tool 共存對照表：[`docs/BUILD-VERIFICATION.md`](./docs/BUILD-VERIFICATION.md)。
|