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）。
5.8 KiB
5.8 KiB
Feature：推論操作（P0：Camera；P1：Image / Video / Batch）
父文件：PRD.md | 對應 User Stories：US-10、US-11、US-15
概述
使用者選裝置 + 模型 + 來源後，能啟動推論並即時看到結果（bounding box / 分類結果）。
這是visionA Cloud 最核心的價值體驗。推論結果要即時、低延遲、UI 和 local-tool 一致。
使用者行為
Workspace 進入點（/workspace 或 /workspace/[deviceId]）
三段式選擇：
- 選裝置：從已配對的裝置列表挑一個
- 選模型：從模型庫挑一個（需和裝置型號相容）
- 選來源：
- Camera（Phase 0）：使用者 agent 端的 USB / IP camera
- Image（Phase 1）：從瀏覽器上傳單張圖片
- Video（Phase 1）：從瀏覽器上傳影片（MP4/AVI/MOV 等）
- Batch Images（Phase 1）：批次上傳多張圖片
選完後進推論工作區。
推論工作區
UI 沿用 local-tool 的設計：
- 左上：即時 MJPEG 畫面 + overlay（bounding box + label + confidence）
- 右側：控制面板
- 信心度門檻 slider
- 推論 FPS / 延遲顯示
- 開始 / 停止按鈕
- 底下：分類結果 / 偵測框列表
- 右上 header：Tunnel 延遲顯示（visionA Cloud 獨有）
Camera 推論流程（Phase 0 重點）
┌────────────────────────────────────────────────────────────┐
│ Camera 推論資料流 │
│ │
│ 1. Browser 呼叫 api-server：POST /workspace/start │
│ { deviceId, modelId, source: "camera", cameraId } │
│ ▼ │
│ 2. api-server 找到對應的 tunnel session │
│ 透過 remote-proxy 轉發到 local agent │
│ ▼ │
│ 3. local agent 啟動 KneronPLUS inference pipeline │
│ Camera → 幀捕捉 → Kneron → 推論結果 │
│ ▼ │
│ 4. local agent 把 MJPEG stream 推給 tunnel │
│ tunnel ─yamux stream─> remote-proxy ─> api-server │
│ ▼ │
│ 5. Browser 透過 /api/camera/stream 拿到 MJPEG │
│ （遠端 stream 經過 api-server proxy 到瀏覽器） │
│ ▼ │
│ 6. Browser 透過 WebSocket /ws/inference 拿到推論結果 │
│ Canvas overlay bounding box │
└────────────────────────────────────────────────────────────┘
關鍵技術挑戰（給 Architect 參考）
- MJPEG binary stream 要能過 tunnel：yamux 支援，但需要測試吞吐量
- WebSocket（推論結果）也要過 tunnel：雲端前端的 WebSocket 連到 api-server，api-server 的對應連線再過 tunnel 到 local agent
- 多 client 存取同一個 stream：local-tool 支援多 client multipart MJPEG。visionA Cloud 可能一個使用者開多個 tab，要處理並發
- Tunnel 斷線處理：推論中 tunnel 斷線，UI 要明確提示並自動重連
延遲預算
| 路徑段 | 延遲 |
|---|---|
| Camera → local agent 幀捕捉 | ~10ms |
| local agent → Kneron 推論 | ~30ms（model 而異） |
| local agent → remote-proxy（tunnel，經 WAN） | ~50-200ms RTT |
| remote-proxy → api-server | ~5ms（同機房） |
| api-server → Browser | ~10-50ms |
| 端到端總延遲（P95 目標） | < 500ms |
（local-tool 端到端 ~150-250ms，多的部分主要是 tunnel 的 WAN RTT）
驗收條件（Phase 0，Camera only）
- 能從 Workspace 頁選裝置 + 模型 + Camera 來源
- 點「開始」後，MJPEG 畫面在 2 秒內出現
- Bounding box / 分類結果 overlay 正確即時更新
- 信心度門檻調整立即反映在畫面
- 推論 FPS 顯示正確（大約 10-30 fps）
- 端到端延遲 P95 < 500ms（內網測試）
- Tunnel 延遲顯示正確（header）
- Tunnel 斷線時立即提示使用者並自動嘗試重連
- 重連成功後推論自動恢復
- 停止推論後，畫面停在最後一幀 + 有明確「已停止」狀態
- 同一使用者開兩個 tab 看同一裝置推論 → 都能看（多 client multipart）
- 不同使用者之間互相隔離（不會看到別人的推論畫面）
Phase 1 擴充（Image / Video / Batch）
Image / Video / Batch 推論不需要即時 stream，使用者上傳檔案到 api-server，透過 tunnel 把檔案送到 local agent，agent 做完回傳結果。
技術挑戰：
- 大檔案傳輸的 tunnel 效率
- 檔案臨時儲存策略（api-server 記憶體 or 暫存磁碟）
- 影片 seek 操作的 tunnel 往返
Phase 0 的 TODO
- TODO 1：Image / Video / Batch 推論（Phase 1）
- TODO 2：推論結果的 history / 回放（Phase 1，需 DB）
- TODO 3：多 client 同時看同一推論的效能優化（Phase 1）
- TODO 4：推論結果下載 / export（Phase 1）
- TODO 5：Camera 來源的使用者選擇 UI — local agent 可能有多個 camera，要讓使用者選
- TODO 6：推論 logging / analytics（Phase 2，用於叢集指標追蹤）
連結
- 回：PRD 索引
- 相關：叢集推論、工作區、非功能性需求 — 效能