jim800121chen
fb7da5d180
依 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）。
81 lines
4.9 KiB
Markdown
81 lines
4.9 KiB
Markdown
# 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）
|
||
|
||
關鍵選擇：
|
||
|
||
1. **改造 local-tool**：讓 local-tool 本身支援「雲端模式」開關，同一份程式碼兩用。
|
||
2. **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 全部不同已處理）
|
||
|
||
## 合規性
|
||
|
||
- [x] 使用者核心原則：「local-tool 不要動」— 由 fork 策略保證
|
||
- [x] 與 Design spec 對齊：Bundle ID `com.innovedus.visiona-agent` 獨立
|
||
- [ ] Cherry-pick SOP 文件：TODO（Phase 1 前補）
|
||
|
||
## 相關文件
|
||
|
||
- `progress.md` visionA 產品線 4 大核心原則
|
||
- `.autoflow/04-architecture/visiona-agent-tdd.md` §2-§3
|
||
- ADR-008（tunnel client 複用策略）
|
||
- ADR-009（token 儲存策略）
|