jim800121chen fb7da5d180 chore(autoflow): migrate .autoflow/ 共享層文件至 docs/autoflow/

依 autoflow-agent workspace v2 設計把 PRD / 設計 / 架構 / 交付類
共享文件從個人層 .autoflow/（ignored）搬到 docs/autoflow/（進 git），
讓團隊可共享產品與架構文件，個人層只留 progress / review / testing 等
per-branch 筆記。

- 02-prd/        21 個檔（PRD、features、market-analysis 等）
- 03-design/     18 個檔（design-spec、wireframes、flows 等）
- 04-architecture/ 31 個檔（TDD、design-doc、ADR×14、API 規格等）
- 07-delivery/   3 個檔（project-summary、phase-0.6-handover、stage-deployment-setup）

合計 73 檔。原檔已從 .autoflow/ 移除（migration 工具執行 git mv，
但因 .autoflow/ 在 .gitignore 中、git 將此操作視為新增、無 rename history）。

2026-05-04 16:55:55 +08:00

4.9 KiB

Raw Blame History

ADR-007：visionA Agent 採 fork local-tool 獨立演進（非改造 local-tool）

狀態

Accepted — 2026-04-22

背景 (Context)

visionA 雲端版需要在使用者桌機上跑一個「local agent」，使得雲端 Web UI 可以透過 tunnel 操作桌機上的 Kneron 裝置。

這個 local agent 本質上是：

完整的 local-tool server（KneronPLUS / camera / inference / device / model / Python runtime / ffmpeg 等邏輯完全一樣）
加上 tunnel client（反向連 remote-proxy）
加上 3 頁極簡 UI（狀態 / 配對 / 設定）
減去 local-tool 原本的裝置 / 模型 / 推論操作 UI（這些交給雲端 web）

關鍵選擇：

改造 local-tool：讓 local-tool 本身支援「雲端模式」開關，同一份程式碼兩用。
fork local-tool → visionA Agent：複製一份出來，獨立演進。

使用者在 progress.md 明確提出 4 大原則之一：「local-tool 不要動，可以複製出來」。這個 ADR 把這個原則落地並說明技術細節。

決策 (Decision)

採方案 2：fork local-tool 建立新專案 /Users/jimchen/visionA/local-agent/，2026-04-22 fork 一次後獨立演進。

實作細節

整包複製：server/internal/*、server/pkg/*、vendor/、scripts/、Makefile 結構、wails 配置都從 local-tool 整包搬
新增：cmd/visiona-agent/（Wails app shell）、internal/tunnel/、internal/pairing/、internal/tokenstore/、internal/agentconfig/、internal/autostart/、internal/connstate/、internal/logexport/、internal/httpserver/
刪除 / 取代：local-tool frontend（Next.js 多頁 UI）整包刪除，改為極簡 Vite + React + shadcn SPA（3 頁）
改造：wails.json、Bundle ID、App name（visionA Agent、com.innovedus.visiona-agent）、go.mod 改 module visiona-agent

Sync 策略

2026-04-22 fork 一次後不主動 sync local-tool 的改動。若 local-tool 有重大修復，走手動 cherry-pick（人工 diff 檢視 → apply）。這個決策在 progress.md visionA Agent 決策表中明列。

考慮過的替代方案

方案	優點	缺點	排除原因
改造 local-tool 支援雲端模式（build tag / feature flag）	程式碼唯一來源、維護成本低	兩套 UI 分支讓 local-tool 複雜化；使用者測試需覆蓋兩種模式；違反使用者「不動 local-tool」原則	使用者原則 + 複雜度風險
做成 monorepo 兩個 app 共用 server 模組	代碼復用、一次修多處生效	Go module 設定複雜、一處改動可能破兩個 app、測試矩陣加大	雛形階段不值得，收益不確定
純 headless CLI agent（不用 Wails）	最輕量	使用者體驗差（無配對 UI、只能 CLI 貼 token）、無法 Log 檢視 / 設定	UX 差
抽象出獨立的 "agent-core" library	優雅	需要設計 API、進一步增加結構複雜度、現階段只有一個 consumer	過度設計

後果 (Consequences)

正面影響

完全符合使用者「不動 local-tool」原則：local-tool 後續任何改動都不會直接影響 visionA Agent
獨立演進自由：visionA Agent 可以按照雲端整合需求自由改 handler、加欄位、刪 UI，不擔心破壞 local-tool 使用者
共同起跑點清楚：2026-04-22 的 fork 時間戳記是明確的 baseline；未來要追 local-tool 新功能時，知道從哪個 commit 開始 diff
打包獨立：兩個產品各自有 installer，Bundle ID 不衝突，使用者可以同時裝兩個

負面影響（接受的取捨）

維護成本加倍：local-tool 若修了 Kneron driver bug，需要手動 cherry-pick 到 visionA Agent
程式碼重複：整個 server/ 目錄存兩份；未來長出差異的機率高
Installer 體積重複：同樣的 Python / wheels / ffmpeg bundle 各自打包一份（但反正用戶只裝一個）

風險

Cherry-pick 遺漏：修復本 bug 卻忘了同步另一邊 → 建立明確的 review checklist（當 local-tool 修 Kneron 相關或 security 相關 bug 時，必須評估是否 cherry-pick 到 agent）
長出的差異難以回頭合併：隨時間兩邊結構差異加大，未來若想合併可能已不現實 — 接受這個結果，本 ADR 即假設不會合併
使用者同一台電腦裝兩個可能衝突：port / config dir 需要明確隔離（bundle ID、app name、data dir 全部不同已處理）

合規性

使用者核心原則：「local-tool 不要動」— 由 fork 策略保證
與 Design spec 對齊：Bundle ID com.innovedus.visiona-agent 獨立
Cherry-pick SOP 文件：TODO（Phase 1 前補）

4.9 KiB Raw Blame History Unescape Escape