jim800121chen
fc7e1e0bc1
根因：Makefile vendor-wheels 用 pip download --dest 只加不清空，跨多次 vendor-sync 累積出同套件多版本（certifi 三版/numpy 二版等共 17 wheel）→ agent bootstrap 的 ensureBundledPython 把目錄所有 .whl 當獨立參數丟 pip install → 版本衝突 ResolutionImpossible → pip 失敗 → venv 建了但空 → 無 Kneron PLUS SDK → bridge scan 走 pyusb fallback 回假序號 0x00000000 → 裝置「尚未回報序號」+ 載入模型 device not connected。 修法（3 個 vendor-wheels target）： - 開頭 rm -f vendor/wheels/<plat>/*.whl 清空，確保每次 sync 單版本 - 結尾 dedup 驗證（sort|uniq -d 偵測多版本 → exit 1 fail-fast） - linux 補「無專屬 KneronPLUS wheel 時退回複製 macos py3-none-any」 - .gitignore 補 local-agent/vendor|payload|dist 對稱規則（保留 ffmpeg binary + .gitkeep 例外），防 vendor-sync 後 git add -A 撈進 build 產物 決定性 evidence（agent 實際 bundled runtime）：清空 runtime → 起剛 build 的 .app → agent 自己 bootstrap 裝 9 個乾淨單版 wheel（修前 17 含重複必失敗） → venv 有 kp → GET /api/devices 回真序號 0xB906162C（非 0x00000000）。 Reviewer 通過（0C/0M/4Mi/3Sug）。win/linux 同邏輯已補、未在對應 runner 驗證（已知限制）。follow-up：ensureBundledPython 列舉 wheel 脆弱設計建議 改 find-links 自解析（backend 另案）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
visionA Agent
Phase 0 雛形 — 正在建置中
此專案於 2026-04-22 從
local-tool/fork，baseline commit：b71ff4cd3c72e879435f773ae15b23bf8b70841efork 後獨立演進，不主動與 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 - UI 規格：
.autoflow/03-design/visiona-agent-spec.md - ADR：
.autoflow/04-architecture/adr/adr-007-*.md（架構）、adr-008-*.md（tunnel 複用）、adr-009-*.md（token 儲存） - 開發進度：
.autoflow/progress.md - Build / 共存驗證：
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，僅作 cherry-pick bug fix 時的歷史對照，不再代表 visionA Agent 的產品定位。
開發指令
# 下載第三方依賴到 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。