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

12 KiB

Raw Permalink Blame History

visionA 產品線 Phase 0 + Phase 0.5 交付總結

交付日期：2026-04-22 階段：Phase 0 雛形（visionA 雲端版） + Phase 0.5（visionA Agent）狀態：✅ 全部完成

一、專案全景

visionA 是 Innovedus 的 Edge AI 開發平台，目前由 4 個子專案構成：

子專案	位置	角色	狀態
local-tool	`visionA/local-tool/`	離線版桌面應用（Wails + Next.js + Go）	既有，不動
visionA-frontend	`visionA/visionA-frontend/`	雲端 web 前端（Next.js）	Phase 0 雛形完成
visionA-backend	`visionA/visionA-backend/`	雲端後端（Go；api-server + remote-proxy 雙 binary）	Phase 0 雛形完成
visionA Agent（local-agent）	`visionA/local-agent/`	雲端版 local 端代理（Wails + Next.js + Go）	Phase 0.5 完成

未來還會加：

kneron_model_converter（轉檔網站，獨立專案）
會員系統、Billing、Admin Console（Phase 1+）

二、產品定位

兩種使用模式並存

離線模式：使用者裝 local-tool → 前端連 localhost server → 本機操作 Kneron 裝置
雲端模式：使用者裝 visionA Agent（local 端代理）+ 使用雲端 web UI（瀏覽器開 visionA-frontend）→ 前端連雲端 visionA-backend → 經 remote-proxy tunnel 到 local-agent → 本機 Kneron 裝置

兩個 Wails app 可同機共存：

Bundle ID 獨立（com.innovedus.visiona-local vs com.innovedus.visiona-agent）
Data dir 獨立（visiona-local/ vs visiona-agent/）
Port 不撞（local-tool 用 3721；Agent 內部綁 127.0.0.1:random，不對外）

三、4 大核心原則（使用者定）

local-tool 完全不動，需要時 fork
雲端 vs 本機差異只在前端部署位置（其他一樣）
cloud agent 的 server ≈ local-tool 的 server（差別在沒本機操作 UI + 多 tunnel client + 多配對 UI）
雲端 web UI 先抄 local-tool，Phase 0 不發明新 UI

四、技術堆疊

Frontend（共通）

Next.js 16.x + React 19.x + TypeScript 5
Tailwind CSS 4 + Radix UI + Lucide
Zustand 5（狀態）、自訂 i18n（繁中 + English）
Vitest + React Testing Library

Backend（visionA-backend）

Go 1.26 + Gin + gorilla/websocket + hashicorp/yamux
雙 binary：cmd/api-server（3721）+ cmd/remote-proxy（tunnel 3800 / internal 3801）
in-memory store（Phase 1 換 Postgres/Redis）
S3-compat 抽象層（LocalFS 雛形 / S3 / MinIO 未定）

visionA Agent

Wails v2 桌面外殼 + Next.js（output: 'export'）靜態嵌入
Tunnel client（從 POC 複製，backoff bug 已修）
AES-GCM + scrypt + machineID-衍生 passphrase 的 Token storage
YAML config + 結構化 log + zip 匯出
三平台安裝包：macOS DMG / Windows EXE / Linux AppImage

五、架構圖

                                              ┌─────────────────────────┐
                                              │  visionA-frontend       │
                                              │  (Next.js on CDN)       │
                                              └───────────┬─────────────┘
                                                          │ HTTPS
                                              ┌───────────▼─────────────┐
                                              │  visionA-backend        │
                                   ┌──────────┤  cmd/api-server :3721   │
                                   │          │  (無狀態，可水平擴展)     │
                                   │          └───────────┬─────────────┘
                                   │                      │ internal HTTP :3801
                                   │                      │ (查 session / raw forward)
                       internal ──>│          ┌───────────▼─────────────┐
                       HTTP        │          │  visionA-backend        │
                                   │          │  cmd/remote-proxy       │
                                   │          │  tunnel :3800 / int :3801│
                                   │          │  (有狀態，持 session)    │
                                   │          └───────────┬─────────────┘
                                   │                      │ WebSocket + yamux
                                   │                      │ (tunnel)
                                   │                      │
                                   │          ┌───────────▼─────────────┐
                                   │          │  local-agent            │
                                   │          │  visiona-agent (Wails)  │
                                   │          │  ├─ tunnel client       │
                                   │          │  ├─ local HTTP :random  │
                                   │          │  │  (綁 127.0.0.1)      │
                                   │          │  └─ visiona-agent-server│
                                   │          │     (Kneron/camera/...)  │
                                   │          └───────────┬─────────────┘
                                   │                      │ USB / IP
                                   │          ┌───────────▼─────────────┐
                                   │          │  Kneron 裝置            │
                                   │          │  (KL520/KL720/KL730)    │
                                   │          └─────────────────────────┘

  離線模式：使用者只用 local-tool，前端連 localhost:3721 直接操作

六、交付物總覽

文件（`.autoflow/`）

PRD：02-prd/ — 21 個檔（索引 + 10 章節 + 10 features）
設計規格：03-design/ — 15 個檔（含 visionA Agent spec）
架構 / TDD：04-architecture/ — 14 個檔（含 visionA Agent TDD + 9 個 ADR）
健檢 / Review：00-onboarding/ + 05-implementation/review/ — 10+ 份

程式碼

visionA-frontend：Next.js 應用，13 頁面、30+ 元件、94 tests、static export 就緒
visionA-backend：雙 binary Go 應用，20+ endpoints、100+ tests、Docker compose 就緒、E2E test 5 milestone 全綠
visionA Agent：Wails 桌面應用，tunnel client + 3 個配置頁（狀態/配對/設定）、90 tests、DMG 已 build（160 MB）

安裝包

macOS DMG：✅ 已驗（160 MB，本機 build）
Windows EXE：.github/workflows/build.yml 就緒，由 CI 驗
Linux AppImage：同上

七、關鍵 Milestone & Integration Tests

visionA-backend E2E

cmd/api-server/b5_integration_test.go 等：5 段完整路徑

Browser → api-server → Forwarder → remote-proxy → yamux → fake tunnel client → fake local server

visionA-backend + visionA Agent E2E（AB13）

cmd/api-server/e2e_full_flow_test.go：5 個 milestone

Pairing Exchange（產 pairing → 兌換 session token）
Tunnel Connect（session token 用 yamux 建立 tunnel）
API Forward（透過完整鏈路轉發業務請求）
Token Reuse 防護（同 pairing token 再用 → 401 PAIRING_TOKEN_USED）
Tunnel Drop Failover（agent 斷線 → 502 TUNNEL_DISCONNECTED）

visionA Agent 本機 E2E（AB6）

local-agent/visiona-agent/internal/tunnel/integration_test.go：

fake relay → yamux → agent handleStream → local server
20 並行 stream 無交錯
502 / 500 錯誤處理

八、使用者裁決紀錄（15 個）

Phase 0 雲端版雛形（7 個）

#	議題	決策
Q1	雛形進程模型	C：雙 binary + internal HTTP，不引入 Redis
Q2	POC 程式碼	A：複製到 visionA-backend，POC 保留
Q3	Local Agent	本次雛形用 POC edge-ai-server 暫代，Phase 0.5 做獨立 Agent
Q4	雛形 Auth	C：StaticAuthService 回 demo-user
Q5	Session 覆蓋	A：沿用 POC，後連覆蓋前連
Q6	local-tool-only 元件	A：雛形隱藏 OnboardingDialog / ServerStatusDashboard / ServerLogViewer
Q7	Pairing Token 顯示	API 回純 hex，前端顯示加空格

Phase 0.5 visionA Agent（8 個）

#	議題	決策
A3	Agent 範圍	純橋樑：tunnel + 配對 UI + 設定，無本機操作 UI
—	App Name	visionA Agent（Bundle ID `com.innovedus.visiona-agent`）
—	local-tool 關係	2026-04-22 fork，獨立演進、不主動 sync
—	Tray UI	不做（過去踩過坑）
—	開機自啟	預設關閉
—	Log 介面	基本 log + 匯出 zip
C1	Frontend 框架	Next.js 沿用（不換 Vite）
C2	Tunnel client	從 POC 複製（visionA-backend 的已刪）

九、跨文件矛盾修訂紀錄（Phase 0）

三方審閱後修訂 12 項，關鍵：

M-1 Pairing Token 格式：vAc_ + 32 hex / vAs_ + 64 hex（三方對齊）
M-2 Token TTL：兩階段（Pairing 15 min + Session 90 天）
M-3 Auth 雙層：AuthProvider（handler）+ AuthService（middleware）
M-4 Converter API：REST Resource 風格（POST /v1/jobs）
M-5 心跳：10 秒心跳 + 30 秒判定掉線
M-8 Non-Goal：雛形僅單 instance

十、Phase 1 TODO（彙整）

安全

真實 Auth（Clerk / OIDC / 自建），取代 StaticAuthProvider
Agent token 改用 OS keychain（macOS Keychain / Windows Credential Manager / Linux Secret Service）
remote-proxy 向 api-server 驗證 session token（不只是驗格式）
TLS 終止策略、rate limit、audit log
macOS Notarization / Windows Authenticode code signing

資料持久化

PostgreSQL + migration（golang-migrate）
所有 InMemoryRepository → PostgresRepository
S3 / MinIO 真實接入（取代 LocalFS）

水平擴展

多 remote-proxy 節點 session metadata 共享
api-server → proxy 跨節點路由
評估 Redis / Consul / Gossip

功能

Converter 真實 API 對接（目前 stub，契約已定）
Billing / 訂閱
多組織 Org / Team
API key for programmatic access
裝置 multi-tab 同時觀看（目前 Q5 single session 限制）
WebSocket proxy 真實實作（目前 501 stub）

Agent 專屬

Log rotation
自動更新機制（從 POC update/ 搬）
System Tray（使用者過去踩過坑，非高優先級）
SaveFileDialog（目前 ExportLog 只回 temp path）

Observability

結構化 JSON log
Prometheus metrics + Grafana
OpenTelemetry tracing
SLO dashboards + alert rules

DevOps

CI 真實跑通 Windows / Linux build（workflow 已設定）
Staging 環境、Blue-green / Canary deploy
備份 / DR 演練

十一、下一步建議

A. 端到端跑通（立即）

# 1. 起 visionA-backend
cd visionA-backend
cp .env.example .env
make dev

# 2. 起 visionA-frontend（另一個 terminal）
cd visionA-frontend
cp .env.local.example .env.local
pnpm dev

# 3. 手動測 visionA Agent（另一個 terminal）
cd local-agent
make wails-macos  # 或直接安裝 dist/visiona-agent.dmg

B. CI 驗三平台 build

推 branch 觸發 .github/workflows/build.yml，驗 macOS/Windows/Linux 都能產出 artifact

C. 進 Phase 1

根據 Phase 1 TODO 清單，選要先做的（建議優先序：真實 Auth → DB → S3 → 轉檔整合）

D. 內部測試

乾淨機器安裝 local-tool + visionA Agent 驗共存、真實 Kneron 裝置跑一次配對 + 推論

十二、文件索引

產品：.autoflow/02-prd/PRD.md（雲端版）
設計：.autoflow/03-design/design-spec.md（雲端版）+ visiona-agent-spec.md（Agent）
架構：.autoflow/04-architecture/design-doc.md + TDD.md（雲端版）+ visiona-agent-tdd.md（Agent）
ADR：.autoflow/04-architecture/adr/adr-001 ~ adr-009
健檢：.autoflow/00-onboarding/health-check.md
Review：.autoflow/02-prd/review/ + 03-design/review/ + 04-architecture/review/ + 05-implementation/review/
進度：.autoflow/progress.md
Build 驗證：local-agent/docs/BUILD-VERIFICATION.md

12 KiB Raw Permalink Blame History Unescape Escape