jim800121chen 8cd5751ce3 feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策）

依 R5 五輪決策把 visionA-local 從「Wails 內嵌 Next.js」重構為「Wails
本機伺服器控制台 + 瀏覽器 Web UI」模式（類比 Docker Desktop / Ollama）。

程式碼變動
  - M8-1 砍 yt-dlp 全套（後端 resolver / URL handler / 前端 URL tab /
    Makefile vendor / installer / bootstrap / CI workflow，-555 行）
  - M8-2 砍 Mock 模式全套（driver/mock、mock_camera、Settings runtimeMode、
    VISIONA_MOCK 環境變數，-528 行）
  - M8-3 ffmpeg 從 GPL 切換到 LGPL 混合方案：Windows/Linux 用 BtbN 現成
    LGPL binary，macOS 自 build minimal decoder-only 進 git
    （vendor/ffmpeg/macos/ffmpeg 5.7MB + ffprobe 5.6MB，比 GPL 版省 85% 空間）
  - M8-4 Wails Server Controller：state machine、log ring buffer 2000 行、
    preferences.json atomic write、boot-id、Gin SkipPaths、shutdown 7+1 秒、
    notify_*.go 三平台 OS 通知、watchServer 改 Error state 不 os.Exit
  - M8-4b 啟動階段管線 R5-E：6 階段進度 event、20s soft / 60s hard timeout、
    stage 5/6 skip 規則、sentinel file、RestartStartupSequence 5 步驟
  - M8-5 Wails 控制台 vanilla HTML/JS/CSS（9 檔 ~2012 行）取代 M7-B splash：
    state 視覺、log panel、startup progress panel、Stage 6 manual CTA
    pulse、shutdown modal、Settings、Dark Mode、i18n 中英雙語
  - M8-6 上傳影片副檔名擴充（mp4/avi/mov/mpeg/mpg）
  - M8-7 Web UI Server Offline Overlay（role=alertdialog + focus trap +
    wsEverConnected 容錯 + Page Visibility）
  - M8-8 CORS middleware（127.0.0.1/localhost only + suffix attack 防護）+
    ws/origin.go 獨立 WebSocket CheckOrigin 避 package cycle
  - MAJ-4 server:shutdown-imminent WebSocket broadcast 機制
    （/ws/system endpoint + notifyShutdownImminent helper）
  - M8-9 Boot-ID + 瀏覽器 tab 自動重連（sessionStorage loop guard）

品質
  - ~105+ 新 unit test + race detector (-count=2) 全綠
  - 10 個 milestone 全部通過 Reviewer 審查
  - 三方 v2 + v2.1 文件（PRD / Design Spec / TDD）+ 交叉互審紀錄
    收錄在 .autoflow/

交付前待處理（M8-10）
  - 重跑 make payload-macos 把舊 GPL 77MB binary 換成新 LGPL
  - 三平台 end-to-end build 驗證

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-15 17:57:54 +08:00

43 KiB

Raw Permalink Blame History

visionA-local — 產品需求文件（PRD v2）

版本：v2.1（2026-04-14） 作者：PM Agent 任務等級：L 級（重構方向變更）狀態：v2.1 補丁：吸收 R5-D1/D2/D3 + R5-E + Design 交叉審閱 4 Major / 4 Minor 前版：PRD-v2.md v2.0（2026-04-14）/ PRD.md v1.2（2026-04-11）

0. v2 變更摘要（和 v1.2 的差異）

本版本因應 2026-04-14 使用者提出的三項重大方向變更（介面架構、影片來源、模型管理），基於 R5 第五輪決策重新定位產品。本文件採「只更新受影響章節」策略，未影響的章節以「同 v1.2」標註並指向原子檔。

最關鍵 5 點差異：

產品定位轉向：從「Wails 桌面 app 內嵌 Next.js UI」改為「本機服務（Wails 控制台）+ 網頁控制台（瀏覽器 Web UI）」，競品類比從 Photo Booth 換成 Ollama / LM Studio / Docker Desktop / Stable Diffusion WebUI（R5-1）。
砍 Mock 模式：完全刪除，沒插硬體就讓 UI 空白（R5-5a）。Persona P3 Solution Architect 的使用情境被迫降級，US-2 整條砍掉。
砍 yt-dlp 全套 + URL 影片推論：媒體上傳只剩 camera / image / upload 影片（.mp4 / .avi / .mov / .mpeg / .mpg）。砍 35MB vendor binary。
ffmpeg 授權從 GPL blocker 升級為 LGPL 方案 B 混合：Windows/Linux 用 BtbN LGPL binary，macOS 自 build decoder-only（~20MB）commit 到 repo（R5-6 / R5-6a / R5-6b / R5-6c）。
啟動時自動開瀏覽器（每次啟動）：Wails 控制台 server 就緒後每次啟動都自動開系統預設瀏覽器，Settings 可關（R5-4 / R5-D3）。平台預設：macOS / Windows ON；Linux OFF（xdg-open 在極簡 WM 行為不穩，R5-D2）。用於抵消「多一步摩擦」對北極星指標的傷害。

v2.1 補丁摘要（相對 v2.0）

v2.1 為 Design 交叉審閱發回的小版本修正（Major 1–3 + 4 個 Minor）+ R5-D / R5-E 決策落地，未改動產品定位與核心決策，只補齊語意與驗收標準。

變更	內容	依據
M1	「首次啟動自動開」→「每次啟動自動開」（全文 replace）	R5-D3
M2	auto-open 平台預設差異（macOS / Windows ON；Linux OFF）	R5-D2
M3	US-7 Server 崩潰時除控制台 banner 外仍發 OS 原生通知	R5-D1
M4	auto-open toggle 住 Wails 控制台（Design 仲裁採 PRD 原案）	Design review §G Major 4
R5-E 大改	AC-1.3 從「10 秒硬指標」翻轉為「60 秒 + 階段化進度 + perceived performance」	R5-E1～E6
Minor 1	US-2 明確：日常啟動（非首次）同樣 auto-open	Design review Minor 1
Minor 2	Offline Overlay 硬阻斷（`role="alertdialog"` + focus trap + 不可關閉 + 純色卡片）	Design Spec v2 `server-offline-overlay.md`
Minor 3	Wails 控制台 Footer 持久警示取代單次 confirm / Error state 三動作按鈕（Restart / View log / Report）	Design Spec v2 `control-panel.md`
Minor 4	First-Run wizard 從 3 步縮為 2 步（砍模式選擇），無硬體可按「稍後再設定」	Design Spec v2 `first-run-update.md` / R5-5a

行數目標：v2.1 新增約 40 行、精簡約 20 行，總量仍 ≤ 500 行。

保留 vs 重寫對照表：

章節	子檔	v2 處理
1. 產品策略與定位	`strategy.md`	🔴 重寫（見本檔 §1）
2. 目標使用者與情境	`user-research.md`	🔴 重寫 US（見本檔 §2 / §5）
3. 產品願景與非目標	`vision-and-non-goals.md`	🟡 修訂（見本檔 §3）
4. 功能清單與 API 對照	`features/feature-inventory.md`	🔴 大幅修訂（見本檔 §4）
5. 使用者流程	`features/user-flows.md`	🔴 重寫（見本檔 §5）
6. 非功能需求與驗收	`nonfunctional.md`	🟡 修訂（見本檔 §6）
7. 發佈與交付策略	`release-strategy.md`	🟢 同 v1.2（安裝檔數字需更新見 §6）
8. 風險與相依性	`risks.md`	🔴 大幅修訂（見本檔 §8）
4.8 第三方授權	`feature-inventory.md §4.8`	🔴 改寫（見本檔 §7）

1. 產品策略與定位（重寫）

1.1 新定位

visionA-local 是一個本機服務 + 網頁控制台架構的 Kneron AI 邊緣推論工具：

Wails 桌面 app = 本機 server 控制台（類比：Docker Desktop 的 Dashboard、Ollama 的 tray app），只負責 server 生命週期、log、版本資訊。
瀏覽器 Web UI = 真正的工作區（類比：Stable Diffusion WebUI、LM Studio 的 web mode），所有「選裝置、選模型、推論」在瀏覽器完成。
兩者只在本機、只綁 127.0.0.1、不做 LAN、不做背景 daemon（R5-1 / R5-2）。

1.2 一句話價值主張

「雙擊 app → 自動開瀏覽器 → 插 USB → 5 分鐘內跑第一次推論。熟悉的瀏覽器操作、熟悉的 devtools，離線可用、零依賴。」

1.3 競品類比更新

v1.2 類比	v2.0 類比
Photo Booth、Kneron 官方 demo app	Ollama（server + web UI / CLI）、Docker Desktop（桌面 app 管 daemon、Dashboard 管操作）、LM Studio（桌面 app + server 模式）、Stable Diffusion WebUI（點 bat → 瀏覽器打開 127.0.0.1）

1.4 北極星指標（更新）

v1.2 原指標：內部 FAE 在客戶現場首次安裝後 5 分鐘內順利跑出第一次推論的比例 ≥ 95%。

v2.0 新指標（處理「多一步開瀏覽器」紅線）：

內部 FAE 在客戶現場首次安裝後 5 分鐘內，瀏覽器 Web UI 跑出第一次推論的比例 ≥ 95%。 起點雙擊安裝檔，終點瀏覽器顯示第一幀推論結果。自動開瀏覽器（R5-4 / R5-D3）是必要條件 — 使用者不需手動點「Open in Browser」，除非關過 Settings。比 v1.2 更嚴格（把瀏覽器冷啟動也納入 5 分鐘）。

1.5 策略取捨紀錄

砍 Mock 模式的代價（R5-5a）：P3 Persona Sam 的「零摩擦 demo」情境無法再被支援，使用者明確接受此取捨，P3 實質降級為非目標（§2）。
雙視窗的代價：Wails 控制台 + 瀏覽器比 v1.2 單視窗多一層「誰是主角」的心智負擔。緩解：控制台 UI 極簡（4 按鈕 + 1 log panel），所有業務操作（裝置、模型、Settings > 語言）強制住瀏覽器。

2. 目標使用者（修訂）

2.1 Persona 變動

P1 — Arthur（內部 FAE）：同 v1.2。核心使用情境「帶筆電到客戶現場跑 demo」在 v2.0 下多一步自動開瀏覽器，但 R5-4 / R5-D3 決定每次啟動都自動開，對 Arthur 幾乎無感。
P2 — Dora（外部開發者）：同 v1.2。她會欣賞「瀏覽器 devtools」（R5-1 動機 B），這是 v2.0 相對於 v1.2 的潛在加分項。
P3 — Sam（Solution Architect / PM）：實質降級為非目標使用者。R5-5a 砍 Mock 模式後，Sam「沒硬體也能 demo」的訴求無法被滿足。保留 Persona 定義只是為了文件完整性，不再為他優化任何 MVP 功能。若未來要重新支援 Sam，應提 L 級功能重新討論。

2.2 Persona 對新架構的反應（PM 預測）

Persona	對「Wails 控制台 + 瀏覽器」的反應	對「砍 Mock」的反應
P1 Arthur	🟡 中性偏好（第一次會愣一下，但每次啟動自動開瀏覽器大幅緩解）	✅ 無感（他本來就帶硬體）
P2 Dora	✅ 正面（瀏覽器 devtools 正中下懷）	✅ 無感（她本來就在評估自家硬體）
P3 Sam	🟡 中性（多一步開瀏覽器）	🔴 負面（他本來就沒硬體）

3. 非目標補充（修訂）

相對於 v1.2 vision-and-non-goals.md，v2.0 明確新增以下非目標：

❌ Mock 模式 / 假資料 / 假裝置（R5-5a）。沒插硬體就讓 UI 空白。
❌ 影片 URL 推論 / yt-dlp / YouTube / Vimeo / Dailymotion 整合（R5 共識 2）。
❌ Model Zoo / 遠端模型下載（R5 共識 9，同 v1.2 但再次確認）。
❌ LAN / 區網分享 localhost（R5-1，使用者明確放棄動機 C/F）。
❌ 背景 daemon / tray 常駐（R5-3 維持砍 tray，R5-2 維持視窗關閉=結束 server）。
❌ 雙 Next.js build（共識 5，Wails 控制台用 vanilla HTML/JS/CSS，不搞兩份前端）。

保留的非目標（同 v1.2）：cluster、relay、tunnel、auto-update、程式碼簽章、telemetry、韌體燒錄、多架構、商店上架、license 啟用機制、WCAG 2.2 AA 正式合規。

4. 功能清單與 API 對照（大幅修訂）

本節列出相對於 v1.2 的變動。v2.0 完整的功能清單後續由 PM Agent 同步更新到 features/feature-inventory.md 子檔。

4.1 保留（沿用 v1.2）

Device scan / connect（GET /api/devices、POST /api/devices/scan、POST /api/devices/:id/connect|disconnect、POST /api/devices/:id/inference/start|stop）
模型管理：8 個預設 .nef + 使用者上傳（GET /api/models、POST /api/models/upload、DELETE /api/models/:id、GET /api/models/:id/download）
批次影像上傳（POST /api/media/upload/batch，R5 共識 10）
推論引擎：camera / image / 上傳影片
MJPEG 串流（GET /api/camera/:id/stream）
WebSocket 推論結果 stream（/ws/devices/*、/ws/server-logs）
系統 API：GET /api/system/health|info|deps|metrics、POST /api/system/restart
i18n 中英雙語（住瀏覽器 Web UI）
Dark Mode 跟隨系統（住瀏覽器 Web UI，靠 prefers-color-scheme）
Log 檔案持久化（macOS：~/Library/Application Support/visiona-local/logs/）

4.2 砍除（v2.0 明確刪除）

#	項目	理由	R5 依據
1	`POST /api/media/url` endpoint	砍 URL 推論	R5 共識 2
2	`server/internal/media/url_handler.go`（或類似檔案）	同上	R5 共識 2
3	yt-dlp 內嵌（35MB binary + `vendor/ytdlp/` + `installer/payload-*` 相關 stage）	砍 URL 推論	R5 共識 2
4	前端「URL 貼上」tab、source-selector 中的 URL 選項	砍 URL 推論	R5 共識 2 / R5 共識 4
5	Mock 模式全部：Mock 裝置資料、Mock 推論結果 mock、Mock mode 切換按鈕、Mock 視覺標記、`server/internal/mock/`（若存在）、前端 Mock 入口	使用者明確砍	R5-5a
6	Wails webview 載入 Next.js 前端的路由（原 `server/web/out` 不再被 Wails 直接 serve 作為主要 UI）	轉為 server 控制台	R5-1
7	Wails tray 相關（維持 v1.2 Q-A 決策）	沒意義	R5-3
8	First-Run 流程中的「模式選擇（真實 / Mock）」畫面	Mock 砍了	R5-5a
9	v1.2 US-2（Mock 模式試玩）整條 user story	Mock 砍了	R5-5a

4.3 新增（v2.0 明確增加）

#	項目	描述	R5 依據
N1	Wails 控制台 UI	vanilla HTML/JS/CSS 的獨立桌面視窗。包含：Start / Stop / Restart Server 按鈕、Open in Browser 按鈕、Server 狀態指示（running / stopped / error）、Server port 號、資料目錄路徑、版本號、Clear log 按鈕、Log panel（自動捲動 + 手動捲動解鎖）、Settings menu（含 auto-open toggle，見 N2）。Footer 持久警示：右下角固定顯示 `⚠ 關閉此視窗會停止 Local Server`（12 px muted，隨時可見，取代單次 confirm dialog 作為主要提醒）。Error state 面板（對應 N6）：log panel 上方浮動 banner 含三個動作按鈕 `Restart Server` / `View log` / `Report issue`（見 Design Spec v2 `v2/control-panel.md §5`）。不含裝置管理、推論、模型、Settings > 語言等任何業務操作。	R5-1 / R5-5 / Design review Minor 3
N2	啟動時自動開瀏覽器（每次啟動）	Wails 控制台啟動、server 就緒後，每次啟動都自動開系統預設瀏覽器到 `http://127.0.0.1:{port}`（不是只在首次，R5-D3）。auto-open toggle 住 Wails 控制台的 Settings menu（讀取時機在 Wails `main.go` 啟動階段，Web UI 尚未 load；已與 Design 取得共識採此位置）。平台預設：macOS / Windows `autoOpenBrowser = true`；Linux `autoOpenBrowser = false`（因 `xdg-open` 在極簡 WM 行為不穩定，R5-D2）。使用者可隨時切換。	R5-4 / R5-D2 / R5-D3
N3	Web UI Server Offline Overlay	瀏覽器 Web UI 偵測 server 斷線（heartbeat / WebSocket 斷）時，顯示全螢幕半透明 backdrop（`rgba(0,0,0,0.4-0.5)`）+ 置中純色卡片（卡片本體不是半透明，以確保 WCAG 4.5:1 對比）。卡片內訊息：「Local Server 已離線」+「請回到 visionA-local 桌面視窗重新啟動 Server」+「重試連線」Primary 按鈕 +「了解更多 ↓」Ghost 按鈕。A11y 硬阻斷特性：`role="alertdialog"` + `aria-modal="true"` + focus trap + 不可由使用者手動關閉（無 ✕ 按鈕，只能 retry 成功或使用者自行 ⌘W / Ctrl+W 關 tab / 重開 app 後自動恢復）。覆蓋層下方 UI 凍結不可操作。	R5-2 / Design review Minor 2
N4	server boot-id 機制	Go server 啟動時產生 UUID boot-id，放進 `/api/system/info` 回應。瀏覽器 Web UI 連上後記下第一個 boot-id；後續 poll 發現 boot-id 變了就代表 server 重啟，前端自動 reload state。Restart Server 按鈕（住 Wails 控制台）依賴此機制讓瀏覽器 tab 不用手動重載。	R5 共識 14
N5	CORS 中介層	Go server 加 CORS middleware，`Access-Control-Allow-Origin` 只允許 `http://127.0.0.1:` / `http://localhost:`，其他 origin 一律拒絕。	R5 共識 6
N6	watchServer() 改為 Error state	v1.2 watchServer 連續 3 次健檢失敗會 `os.Exit(1)`，v2.0 改為把 Wails 控制台的 Server 狀態切為「Error」並在 log panel 顯示錯誤，不強制退出 app。Error state 面板同時顯示三個動作按鈕（見 N1）。	R5 共識 8
N7	Server 崩潰 OS 原生通知	當 `watchServer()` 偵測連續 3 次健檢失敗進入 Error state 時，除了控制台 Error banner 外，同步發一次 OS 原生通知（macOS Notification Center / Windows Toast / Linux `libnotify`）。使用者可能正在使用瀏覽器 tab，靠 OS 通知把他拉回控制台。去重策略（避免 Error 狀態期間重複發通知）由 Architect 在 TDD v2 決定。	R5-D1
N8	啟動階段化進度顯示（6 階段）	Wails 控制台在啟動過程全程顯示階段化進度：`1. 初始化控制台 → 2. 檢查 Python → 3. 啟動 server → 4. 偵測裝置 → 5. 開瀏覽器 → 6. 瀏覽器就緒`。每階段有編號 + 使用者可理解的動作描述 + 視覺回饋（spinner / 進度條）+ 中英雙語文案。第 6 階段「ready」的偵測訊號 = Web UI 透過 WebSocket hub 建立第一個 client 連線（不做新 endpoint，R5-E6）。階段文案由 Design Agent 最終決定（R5-E5）。啟動總預算見 §6.1 AC-1.3 系列。	R5-E1～E6

4.4 功能對 Persona 對照表（更新）

功能	對應 Persona	住哪裡
Wails 控制台（Start/Stop/Restart/Log）	P1, P2	Wails 桌面視窗
Device scan / connect	P1, P2	瀏覽器 Web UI
模型管理	P1, P2	瀏覽器 Web UI
Workspace（推論）	P1, P2	瀏覽器 Web UI
Settings > 語言 / 深色模式	P1, P2	瀏覽器 Web UI
Settings > 自動開瀏覽器	P1, P2	Wails 控制台（因為它控制的是 Wails 啟動行為）
Server Offline Overlay	全體	瀏覽器 Web UI
~~Mock 模式~~	P3	砍

5. User Stories（重寫受影響的）

US-1：第一次安裝 → 首次看到推論 UI（重寫，取代 v1.2 US-1 + 部分 US-5）

身份：任意目標 Persona（主力 P1 Arthur）情境：剛拿到 .dmg / .exe / .AppImage，全新機器、客戶現場敘述：

身為 FAE，我希望雙擊安裝檔、按幾下「下一步」、等進度條跑完，視窗自動打開（Wails 控制台）、瀏覽器自動打開（Web UI），插上 Kneron USB 後瀏覽器立刻顯示裝置，我按一下「Start」就看到第一幀推論結果。整個流程不超過 5 分鐘。

驗收標準：

AC-1.1：下載安裝檔，無 terminal 操作可完成安裝（同 v1.2）
AC-1.2：整個安裝過程 ≤ 3 分鐘（目標）/ ≤ 5 分鐘（上限）（同 v1.2，R4-4）
AC-1.3（R5-E 改寫）：安裝完成後首次啟動，從 Wails 控制台視窗出現到瀏覽器 Web UI 顯示第一幀，全程 ≤ 60 秒（R5-E1，原 10 秒硬指標取消）。啟動過程全程可見、不可出現白畫面或無回饋狀態 — 採 Nielsen Norman perceived performance 原則，使用者感覺進度在推進比硬時間指標重要
AC-1.3a（新）：啟動全程顯示階段化進度（6 階段，見 §4 N8），每階段有編號 + 使用者可理解的動作描述 + 視覺回饋（spinner 或進度條）+ 中英雙語文案。階段文案由 Design Agent 決定（R5-E2 / R5-E5）
AC-1.3b（新）：任一啟動階段卡超過 20 秒，UI 必須顯示「正在重試」或「這步比預期久」類提示，不可停留在白畫面或無變化狀態（R5-E3）
AC-1.3c（新）：總啟動時間超過 60 秒仍未進入「就緒」狀態，Wails 控制台進入 Error state，顯示「Restart Server」「View log」「Report issue」三個動作按鈕（對應 §4 N1 / N6，與 watchServer 3 次失敗後行為一致，R5-E4）
AC-1.3d（新）：「瀏覽器就緒」的定義 = Web UI 建立 WebSocket 連線到 server（hub 收到第一個 client），不是瀏覽器視窗出現時。不做新 endpoint、不做固定延遲（R5-E6）
AC-1.4：瀏覽器 Web UI 首次顯示時，若沒插硬體，Dashboard 顯示空白狀態 + 「請插入 Kneron 裝置」提示文字（R5-5a，不是 Mock 資料）。First-Run wizard 從 v1.2 的 3 步縮為 2 步（砍模式選擇，R5-5a）：Step 1 歡迎 → Step 2 硬體偵測。Step 2 在無硬體情況下可按 稍後再設定 略過，直接進 Dashboard 空白狀態（Design review Minor 4）
AC-1.5：Mac 第一次開啟若出現 Gatekeeper 警告，Wails 控制台和安裝說明頁提供「右鍵 → 開啟」引導（同 v1.2）
AC-1.6：auto-open 可在 Wails 控制台的 Settings menu 切換（不在 Web UI Settings，見 §4 N2）。平台預設：macOS / Windows ON；Linux OFF（R5-D2）。關閉後下次啟動只開 Wails 控制台、不開瀏覽器，使用者可手動按「Open in Browser」

US-2：日常啟動（新增，取代 v1.2 US-2 Mock）

身份：P1, P2 情境：第二次以後的日常啟動（非首次安裝，但「啟動時自動開」對首次 / 日常同樣生效，R5-D3）敘述：

身為日常使用者，我希望雙擊 app icon 後，Wails 控制台和瀏覽器都自動開啟（除非我關過 auto-open），server 狀態顯示 running，瀏覽器顯示上次的 Dashboard 狀態。

驗收標準：

AC-2.1：日常啟動時，若 Wails 控制台 Settings autoOpenBrowser === true，仍會自動開瀏覽器（和首次啟動行為一致，R5-D3 / Design review Minor 1）。AC-1.3 系列的 60 秒預算與階段化進度在日常啟動同樣生效（通常遠低於 60 秒）
AC-2.2：瀏覽器 Web UI 保留上次的 i18n 語言偏好、深色模式偏好
AC-2.3：若使用者關過 auto-open（或 Linux 平台預設 OFF 且使用者未手動開），啟動時只開 Wails 控制台，使用者可點「Open in Browser」手動開

US-3：連實體 Kneron 裝置（微調）

身份：P1, P2 敘述：同 v1.2，但 UI 住瀏覽器 驗收標準：

AC-3.1 ~ AC-3.6：同 v1.2（插 USB → 3 秒內瀏覽器 Devices 頁顯示裝置）
AC-3.7（新）：若使用者關閉瀏覽器但 Wails 控制台還在（server 仍跑），插入 USB 的事件不會通知使用者（不做 toast），下次使用者打開瀏覽器會看到裝置。不發原生 OS 通知（維持 v1.2 R4-8 OS 通知策略）。

US-4：切換 / 上傳模型（微調）

身份：P1, P2 敘述：同 v1.2，但 UI 住瀏覽器 驗收標準：

AC-4.1 ~ AC-4.4：同 v1.2
AC-4.5（新）：拖放 .nef 只在瀏覽器視窗內有效，拖到 Wails 控制台視窗無反應（不處理跨視窗拖放，避免混淆）
AC-4.6（新）：預設模型清單維持 8 個 .nef，使用者可上傳自己的 .nef，但沒有任何 Model Zoo / URL download 入口（R5 共識 9）

US-5：跑即時攝影機推論（重寫，瀏覽器情境）

身份：P1 敘述：

身為 FAE，我希望在瀏覽器 Workspace 頁選一顆 webcam、選一個模型、按 Start，看到 MJPEG 即時串流和推論 overlay。

驗收標準：

AC-5.1：Workspace 頁能列出所有可用 webcam（透過後端 /api/camera，而非瀏覽器 navigator.mediaDevices；這點對 Chrome / Edge / Safari 行為一致）
AC-5.2：選 webcam + 模型後按 Start，≤ 3 秒看到第一幀
AC-5.3：推論 overlay（方框 / 標籤 / 信心度）正確顯示
AC-5.4：即時 FPS / 延遲 / CPU / RAM 顯示
AC-5.5：按 Stop 即時停止
AC-5.6（新）：不使用瀏覽器 getUserMedia() API（避開 Chrome/Edge/Safari 權限差異 + HTTPS 限制）。所有攝影機存取走後端 AVFoundation / DirectShow / V4L2 pipeline（和 v1.2 架構相同）

US-6：上傳影片推論（修訂，取代 v1.2 US-7 / US-8）

身份：P1, P2 敘述：

身為使用者，我希望能把一段 .mp4 / .avi / .mov / .mpeg / .mpg 影片拖進瀏覽器 Workspace，跑離線推論、看到逐幀結果。

驗收標準：

AC-6.1：瀏覽器 Workspace 頁支援拖放或 file picker 上傳影片
AC-6.2：支援副檔名：.mp4 / .avi / .mov / .mpeg / .mpg（R5 共識 11）
AC-6.3：上傳後後端走 ffmpeg decode → Kneron 推論 → 前端顯示結果
AC-6.4：不支援 URL 推論 / YouTube / Vimeo / Dailymotion（R5 共識 2）

US-7：Server 崩潰 / 意外中斷（新增）

身份：P1, P2 情境：Go server 子程序因某種原因崩潰（OOM、panic、依賴錯誤），或使用者關閉 Wails 視窗敘述：

身為使用者，我希望當 server 斷線時，我在瀏覽器看到清楚的「Local Server 已離線」訊息，而不是無聲的網頁卡住。我也希望 Wails 控制台能告訴我發生什麼、我能按 Restart 重啟。

驗收標準：

AC-7.1：瀏覽器 Web UI 偵測 server 斷線（health check 失敗 or WebSocket 斷 + retry 失敗）→ 顯示全螢幕 Server Offline Overlay（R5-2 / N3）。Overlay 無 ✕ 按鈕、不可手動關閉（role="alertdialog" + focus trap，Design review Minor 2）
AC-7.2：Overlay 卡片內訊息：「Local Server 已離線，請回到 visionA-local 桌面視窗重新啟動 Server」+「重試連線」Primary 按鈕 +「了解更多 ↓」Ghost 按鈕。卡片背景純色（非 backdrop 半透明），確保 WCAG 4.5:1 對比
AC-7.3：Wails 控制台 Server 狀態顯示變為「Error」（紅色），log panel 上方浮現 Error banner 面板，含 三個動作按鈕：Restart Server / View log / Report issue（對應 §4 N1 / N6，Design Spec v2 v2/control-panel.md §5，Design review Minor 3）
AC-7.4：使用者在 Wails 控制台按 Restart Server 後，server 重啟、取得新 boot-id，瀏覽器 Web UI 透過 Retry 重連、偵測到新 boot-id、自動 reload state（R5 共識 14 / N4）
AC-7.5：使用者直接關閉 Wails 視窗 → server 結束（R5-2 維持 v1.2 Q7）→ 瀏覽器 Web UI 顯示相同的 Offline Overlay + 提示「請重新啟動 visionA-local」
AC-7.6：為避免使用者誤解「關閉視窗 = 程式還在背景跑」，雙保險警示：(a) Wails 控制台 Footer 右下角持久警示文字 ⚠ 關閉此視窗會停止 Local Server（12 px muted，始終可見，§4 N1）；(b) 標題列 / menu bar 的「Close」按鈕 tooltip / confirm dialog 同樣寫明。(a) 是主要手段（避免使用者盲目點 confirm），(b) 為輔
AC-7.7（R5-D1 新）：Server 崩潰事件（watchServer 連續 3 次失敗進入 Error state 的瞬間），除控制台 Error banner 外，同步發一次 OS 原生通知（macOS Notification Center / Windows Toast / Linux libnotify）。使用者可能正在使用瀏覽器 tab 而未看控制台，OS 通知負責把他拉回來。去重策略（Error 狀態期間避免重複發）由 Architect 在 TDD v2 決定

砍掉的 User Stories

US	v1.2 標題	v2.0 處理
v1.2 US-2	Mock 模式試玩	砍（R5-5a）
v1.2 US-6	從 Tray 快速控制	維持 v1.2 已砍（第三輪 Q-A）
v1.2 US-8	YouTube / URL 推論	砍（R5 共識 2）
v1.2 US-9	查看 server 日誌	升級：住 Wails 控制台成為一級功能（N1）

6. 非功能需求（更新）

6.1 效能指標

指標	v1.2	v2.0	變化說明
安裝時間	≤ 3 分 / 上限 5 分	同 v1.2	R4-4 沿用
首次推論時間（首次啟動）	≤ 20s / 上限 30s（至 Mock 第一幀）	≤ 20s / 上限 30s（至瀏覽器第一幀）	終點改為瀏覽器 Web UI 顯示第一幀真實推論結果（因 Mock 砍）。R5-4 的自動開瀏覽器是達成此指標的必要條件。Architect TDD v2 需驗證預算
首次推論時間（回訪）	≤ 10s / 上限 15s	同 v1.2（但終點改為瀏覽器）	同上
實機接入時間	≤ 5s / 上限 10s	同 v1.2	—
攝影機串流延遲（首次）	≤ 200ms / 上限 250ms	同 v1.2（R4-2）	—
攝影機串流延遲（穩定後）	≤ 120ms / 上限 150ms	同 v1.2（R4-2）	—
idle CPU（無硬體狀態）	≤ 3% / 上限 5%（Mock 模式）	≤ 3% / 上限 5%（無硬體狀態）	Mock 改為「無硬體空白狀態」。CPU 估計值不變，因為 v1.2 Mock 本來就不 spawn Python
idle RAM（無硬體狀態）	≤ 500 MB / 上限 600 MB	≤ 450 MB / 上限 550 MB	因無 Mock state、無 Python sidecar、無 yt-dlp 子程序，可略降。此指標不含瀏覽器 tab 記憶體（由 OS 系統瀏覽器負責，不是 Wails app 的責任範圍）。Architect 實測：Wails + Go server + Python 樂觀估 275–405 MB，達標
真實推論 RAM	≤ 1 GB / 上限 1.5 GB	同 v1.2	—

6.2 安裝檔大小（更新）

平台	v1.2 上限	v2.0 目標	組成變化
macOS `.dmg`	≤ 220 MB	≤ 185 MB（目標）/ 上限 ≤ 220 MB	-35MB yt-dlp、ffmpeg 從 77MB GPL build 換成 ~20MB LGPL decoder-only = 淨 -92MB
Windows `.exe`	≤ 200 MB	≤ 165 MB（目標）/ 上限 ≤ 220 MB	-35MB yt-dlp、ffmpeg 換 BtbN LGPL ~40MB（差異較小，但仍略降）
Ubuntu `.AppImage`	≤ 200 MB	≤ 165 MB（目標）/ 上限 ≤ 220 MB	同 Windows

根據：R5-6 / R5-6a / R5-6b / R5-6c ffmpeg LGPL 混合方案，砍 yt-dlp 全套。實際數字需 Architect 在 TDD v2 實測確認。

6.3 瀏覽器相容性（新）

預設：開啟使用者 OS 預設瀏覽器（macOS：Safari/Chrome/Edge 依 OS 設定；Windows：Edge；Linux：依 xdg-settings）
auto-open 平台預設（見 §4 N2）：macOS / Windows autoOpenBrowser = true；Linux autoOpenBrowser = false（xdg-open 在極簡 WM 下行為不穩定，R5-D2）
推薦：Chrome 或 Edge（MJPEG decode 穩定性最好、devtools 最完整、WebSocket 穩定）
可用但不保證：Safari（MJPEG decode 可能較慢；因為 US-5 AC-5.6 決定不走 getUserMedia，Safari 的攝影機權限流程差異不構成問題）
不支援：IE、舊版 Firefox ESR（< 115）、行動版瀏覽器（不是使用情境）
WebSocket 就緒偵測（R5-E6 / AC-1.3d）：依賴瀏覽器支援 WebSocket — 所有現代瀏覽器原生支援，風險低

注意：v1.2 靠 Wails webview（WebView2 / WKWebView）是 Chromium/Safari 核心的一個已知固定版本，v2.0 改用使用者系統瀏覽器後多了一維瀏覽器版本差異。這是 Architect TDD v2 和 Testing Agent 要接受的新測試矩陣。

6.4 安全性需求（修訂）

✅ Server 只監聽 127.0.0.1，絕對不 bind 0.0.0.0（同 v1.2，R5 共識 7 再次確認）
✅ CORS 中介層：Access-Control-Allow-Origin 只允許 http://127.0.0.1:* / http://localhost:*（v2.0 新增，R5 共識 6）
✅ 使用者資料存在 OS 慣例目錄（同 v1.2）
❌ 無 TLS（localhost 不需要）（同 v1.2）
❌ 無認證（單人工具）（同 v1.2）
⚠️ 瀏覽器 DevTools 暴露：v2.0 使用者可以用 F12 看到所有 API 呼叫、WebSocket 流量。這不是安全問題（因為是單人本機），但要在 FAE 訓練文件提醒「不要把瀏覽器分頁截圖給外部，可能含硬體序號」

6.5 其他非功能需求

其餘章節（相容性、可維護性、可打包、可用性、日誌）同 v1.2，詳見 nonfunctional.md。

7. 第三方授權宣告（大改，取代 v1.2 §4.8）

7.1 依賴對照表（v2.0）

依賴	用途	授權	宣告要求	v1.2 → v2.0 變動
ffmpeg LGPL build（BtbN）	Windows / Linux 的攝影機 / 影片 decode	LGPL v2.1+	必須宣告（LGPL 條文、動態連結、About 對話框列 `Powered by FFmpeg (LGPL)` + 連結）	v1.2 是 GPL build 標 `under legal review` 🔴，v2.0 改 LGPL 方案 B 解除 blocker（R5-6）
ffmpeg LGPL build（macOS 自 build）	macOS 的攝影機 / 影片 decode	LGPL v2.1+	同上；額外說明「本 binary 由 Innovedus 在 macOS 上自 ffmpeg 官方 source 以 `./configure --enable-shared --disable-gpl` 等 flag build 出，源碼可取得」	v2.0 新增。Decoder-only ~20MB，只含 mp4/avi/mov/mpeg/mpg 五種 decoder（R5-6a），commit 到 `vendor/ffmpeg/macos/`（R5-6b）。ffprobe 一起包（R5-6c）
KneronPLUS SDK（wheel）	裝置 / 推論	Kneron 專有	同 v1.2（發佈前 gate，R5 風險維持）	同 v1.2
Python runtime（python-build-standalone）	執行 KneronPLUS	PSF 2.0	同 v1.2	同 v1.2
Python wheels（numpy / opencv / pyusb 等）	推論依賴	BSD / MIT / Apache 2.0 為主	同 v1.2	同 v1.2
Wails v2	Wails 控制台殼	MIT	同 v1.2	角色改變（v1.2 是前端 shell，v2.0 是控制台 shell）
Next.js / React / shadcn / Radix / Tailwind / Zustand	瀏覽器 Web UI	MIT 為主	同 v1.2	同 v1.2
~~yt-dlp~~	~~URL 影片下載~~	~~Unlicense~~	v2.0 刪除	整個 vendor 拔掉

7.2 macOS ffmpeg 自 build 的長期責任

Architect TDD v2 必須產出 scripts/build-ffmpeg-macos.sh（記錄 configure flags / source tarball URL / checksum 驗證）。LGPL ffmpeg 幾乎不需更新（R5-6b）；~20MB binary commit 到 repo 可接受；2-3 年後 build 系統變化時需 ~0.5 人天重 build。

7.3 授權檔案落點

同 v1.2 <APPDATA>/licenses/，但：❌ 刪 LICENSE-yt-dlp.txt；✅ LICENSE-ffmpeg.txt 從 GPL 換成 LGPL v2.1 + v3；✅ 新增 ffmpeg-macos-build-notes.md 說明 macOS binary 來源。

8. 風險與相依性（大幅修訂）

8.1 技術風險變動

風險 ID	v1.2 狀態	v2.0 處理
R1（KneronPLUS Linux wheel glibc）	高可能 / 高影響	同 v1.2（不變）
R2（Windows WinUSB UAC）	中 / 高	同 v1.2
R3（KneronPLUS macOS x86_64）	中 / 高，已被 Q4 降級	同 v1.2
R4（Linux venv）	中 / 中	同 v1.2
R5（Kneron .nef re-distribution）	發佈前 gate	同 v1.2
R6（ffmpeg GPL blocker）	🔴 release blocker	✅ 解除（R5-6 走 LGPL 方案 B）
R11（發佈通路）	P2 追蹤	同 v1.2
R12（CI runner）	P2 追蹤	同 v1.2

8.2 新增風險（v2.0）

N-R1 — 瀏覽器相容性差異（新）

項目	內容
描述	v2.0 改用使用者系統瀏覽器後，MJPEG decode 效能、WebSocket 穩定性、深色模式判斷都會因瀏覽器而異。Safari 的 MJPEG 延遲可能超過 150ms 上限
可能性	中
影響	中（Safari 使用者體驗可能變差，但 P1 FAE 多用 Chrome）
等級	P2 追蹤項
緩解	1) 預設推薦 Chrome / Edge；2) Safari 列為「可用但不保證」；3) Testing Agent 測試矩陣加 Safari；4) 發佈說明寫「若遇延遲過高，請改用 Chrome / Edge」
PM 行動	Testing 階段實測 Safari，若嚴重超標則在 Wails 控制台自動開瀏覽器時優先選 Chrome / Edge

N-R2 — macOS 自 build ffmpeg 的長期維護成本（新）

項目	內容
描述	macOS 上沒有現成的 LGPL decoder-only ffmpeg binary，需要 Innovedus 自 build（R5-6a / R5-6b）。2-3 年後若 ffmpeg build 系統變化 / configure flag 調整 / source tarball 結構變化，可能需要重新 build
可能性	中（長期）
影響	低—中
等級	P3 追蹤項（不緊急）
緩解	1) TDD v2 產出 `scripts/build-ffmpeg-macos.sh`，記錄完整 build 步驟；2) commit 時把 source tarball checksum、configure flags、build 環境一起寫進 commit message；3) 每 2 年做一次 build 演練確保 script 還能跑
PM 行動	交付時在 delivery docs 加「ffmpeg rebuild SOP」

N-R3 — 使用者誤解「關閉視窗 ≠ 結束 server」（新）

項目	內容
描述	R5-2 決定維持「關閉 Wails 視窗 = 結束 server」，但因為 v2.0 多了瀏覽器視窗這個「真正的操作介面」，使用者可能誤以為「我關掉 Wails 視窗沒關係、瀏覽器 tab 還在、應該還能用」。這種誤解會導致他在瀏覽器看到 Offline Overlay 時很困惑
可能性	高
影響	中（體驗面混亂，不危險）
等級	P2 追蹤項
緩解	1) Wails 控制台 Close 按鈕的 tooltip / confirm dialog 明確寫「關閉此視窗會結束 Local Server」（AC-7.6）；2) Web UI 的 Offline Overlay 文案引導「請回到 visionA-local 桌面視窗重新啟動」；3) First-Run 歡迎頁加一句說明
PM 行動	Design Agent 在 Design Spec v2 確認這三處文案都到位

N-R4 — 砍 Mock 後 CI / E2E 測試困難（新）

項目	內容
描述	v1.2 有 Mock 模式，CI runner 沒插硬體也能跑 E2E 測試（跑 Mock pipeline）。v2.0 砍 Mock 後，CI runner 要跑裝置管理 / 模型切換 / 推論 E2E 時，若沒硬體就測不了
可能性	高
影響	中（測試覆蓋率下降）
等級	P2 追蹤項
緩解	1) E2E 測試分層：「不需硬體的 UI 測試」（載入、i18n、Settings、Offline Overlay、Wails 控制台 start/stop button）可在無硬體 CI 跑；「需要硬體的測試」（裝置偵測、推論）只能在有硬體的 runner 跑；2) 用 HTTP fixture mock 後端 API（前端 unit 測試層級），但不碰 Go server 的推論 pipeline；3) Testing Agent 在測試計畫明確區分兩層
PM 行動	與 Testing Agent / DevOps 討論是否要建「有硬體 CI runner」（M5+ 規劃）

8.3 PM 需要進一步確認的事項（寫入 progress.md 未解決問題）

沿用 v1.2 三項（R5 授權 / R11 發佈通路 / R12 CI runner）；新增 N-R1 瀏覽器相容性（Testing 驗證 Safari/Chrome/Edge/Firefox MJPEG + WebSocket）、N-R4 CI/E2E 測試分層（Testing + DevOps 於 TDD v2 提出分層方案）。

9. 策略性路線圖（更新）

Now（本 sprint，重構實作）：PRD v2.1 / Design Spec v2 / TDD v2 三方互審 → Architect 產 ffmpeg LGPL vendor script + Wails 控制台實作 + CORS middleware + 刪檔清單 → Design 產控制台 wireframe + Offline Overlay + source-selector 拔 URL → 拆 milestone 進開發
Next（重構完成後）：M7 Windows build 重驗（R5-7）；v1.0.0 release gate：Kneron re-distribution 授權（R5 發佈前 gate）；三平台 smoke test
Later（v1.0.0 發佈後）：視回饋決定是否放回 v1.2 功能（Mock / URL 推論 / tray）；視需求升級 LAN 模式（重走 R5-1 動機 C）

10. 變更追蹤（和 v1.2 的完整差異清單）

區域	v1.2	v2.0	R5 依據
產品定位	Wails 桌面 app 內嵌 Next.js UI	本機服務 + 網頁控制台	R5-1
競品類比	Photo Booth	Ollama / Docker Desktop / LM Studio / SD WebUI	R5-1
一句話價值主張	「裝起來就能跑、離線可用、零依賴」	「雙擊 → 自動開瀏覽器 → 插 USB → 5 分鐘跑第一次推論」	R5-1 / R5-4
北極星指標終點	Mock 第一幀	瀏覽器第一幀（真實硬體）	R5-5a
Mock 模式	MVP 必達	砍	R5-5a
URL 影片推論	US-8 / `/api/media/url` / yt-dlp 內嵌	砍	R5 共識 2
yt-dlp vendor（35MB）	打包	砍	R5 共識 2
ffmpeg	GPL build（blocker 🔴）	LGPL 方案 B 混合（Win/Linux BtbN、macOS 自 build decoder-only ~20MB commit）	R5-6 / R5-6a / R5-6b / R5-6c
安裝檔大小（macOS 目標）	≤ 220 MB	≤ 185 MB	R5-6
idle RAM（無硬體）	≤ 500 MB / 上限 600 MB	≤ 450 MB / 上限 550 MB	砍 Mock / yt-dlp
Wails 視窗關閉	結束程式	同 v1.2（R5-2 復議後維持）	R5-2
Tray	砍（v1.2 Q-A）	同 v1.2（R5-3 復議後維持）	R5-3
啟動時自動開瀏覽器	無	新增，每次啟動都開（R5-D3），macOS/Win 預設 ON、Linux 預設 OFF（R5-D2），toggle 住 Wails 控制台 Settings（已與 Design 取得共識）	R5-4 / R5-D2 / R5-D3
AC-1.3 啟動預算	—	≤ 60 秒（原 v2.0 草案 10 秒硬指標被 R5-E1 取代）+ 階段化進度（6 階段，R5-E2）+ 20 秒卡住提示（R5-E3）+ 60 秒超時進 Error state（R5-E4）+ WebSocket 就緒偵測（R5-E6）	R5-E1～E6
Server 崩潰 OS 通知	無	新增（控制台 Error banner 並存，R5-D1）	R5-D1
First-Run wizard 步數	3 步（歡迎 / 模式選擇 / 硬體偵測）	2 步（歡迎 / 硬體偵測，砍模式選擇；無硬體可按「稍後再設定」略過）	R5-5a / Design review Minor 4
Offline Overlay 硬阻斷	—	新增驗收特性（`role="alertdialog"` + focus trap + 無 ✕ 按鈕 + 純色卡片）	Design review Minor 2
Wails 控制台 Footer 持久警示	無	新增「⚠ 關閉此視窗會停止 Local Server」取代單次 confirm 作為主要提醒	Design review Minor 3
Error state 三動作按鈕	無	新增 `Restart Server` / `View log` / `Report issue`（Wails 控制台 Error banner 內）	Design review Minor 3
Wails 控制台	無（webview 載 Next.js）	新增 vanilla HTML/JS/CSS：Start/Stop/Restart/Open Browser/log panel/status/port/dir/version	R5-5 / R5 共識 5
Server Offline Overlay	無	新增（Web UI 全螢幕覆蓋層）	R5-2
CORS middleware	無	新增（127.0.0.1 / localhost only）	R5 共識 6
watchServer 連 3 次失敗	`os.Exit(1)`	改為 Error state，不退出	R5 共識 8
Server boot-id	無	新增（支援 Restart Server 按鈕的 tab 自動重連）	R5 共識 14
US-1	3 分鐘看到 Dashboard	5 分鐘瀏覽器跑第一次推論	R5-1 / R5-4
US-2	Mock 試玩	日常啟動（取代）	R5-5a
US-5	Wails webview 攝影機	瀏覽器 Workspace + 後端攝影機 pipeline（不走 `getUserMedia`）	R5-1
US-7 / US-8	影片 / URL 上傳	合併為 US-6，砍 URL	R5 共識 2
US-9	Settings 進階分頁次要功能	升級為 Wails 控制台一級功能	R5-1 / R5-5
新 US-7（server 崩潰 / 離線）	無	新增	R5-2
上傳影片副檔名	mp4 / avi / mov / webm（瀏覽器能吃）	mp4 / avi / mov / mpeg / mpg	R5 共識 11
Persona P3 Sam	三順位目標	實質降級為非目標	R5-5a
新風險	—	N-R1 瀏覽器相容 / N-R2 macOS ffmpeg 維護 / N-R3 關窗誤解 / N-R4 CI 測試分層	—
解除風險	R6 ffmpeg GPL blocker	解除	R5-6

11. 給 Orchestrator / 下輪審閱的問題

#	問題	v2.1 狀態
11-1	auto-open Settings 資料落在哪？Web UI 和 Wails 控制台共用同一個 config 嗎？	✅ 已解決（Architect 答：`preferences.json @ <dataDir>/`，write-rename 原子寫，fallback DefaultPreferences；auto-open toggle 由 Wails 進程讀取，Web UI 不碰此欄位）
11-2	US-1 AC-1.3 10 秒預算是否可達？	✅ 已解決（由 R5-E 取代） — 整個問題被重新定義為「60 秒總預算 + 階段化進度 + perceived performance」，不再是硬時間指標
11-3	idle RAM ≤ 450 MB 是否可達？	✅ 已解決（Architect 實測：Wails + Go server + Python 275–405 MB 達標；悲觀估含瀏覽器 tab ~500 MB 超 50 MB，但瀏覽器 tab 不在本指標範圍內，已於 §6.1 clarify）
11-4	N-R4 砍 Mock 後 CI / E2E 測試分層	⏳ 懸置，交 Testing Agent 在測試計畫提出「不需硬體的 UI 測試」vs「需硬體測試」分層方案
11-5	Web UI 要不要加常駐「本機服務」徽章？	✅ 已解決：不加（Design Agent 決定，改由 First-Run Step 1 歡迎頁一次性告知；見 Design review §D）
11-6	Settings auto-open toggle 住哪裡？	✅ 已解決（Design 仲裁採 PRD 原案：住 Wails 控制台 Settings menu；Design Spec v2 `v2/settings-update.md` 將同步修正）
11-7	R5-E 階段化進度 6 階段文案（中英雙語）定稿	⏳ 懸置（R5-E5 使用者授權 Design Agent 決定；最終在 Design Spec v2 wireframe 定版時由使用者審閱 override）

變更紀錄

版本	日期	作者	變更
v2.0	2026-04-14	PM Agent	依 R5 五輪決策重寫：砍 Mock / URL 推論 / yt-dlp；新增 Wails 控制台 + Server Offline Overlay + 首次自動開瀏覽器 + CORS；ffmpeg 從 GPL blocker 解除為 LGPL 方案 B 混合；Persona P3 降級；US-1/US-2/US-5/US-6/US-7 重寫；解除 R6，新增 N-R1 ~ N-R4 風險。完整差異見 §10
v2.1	2026-04-14	PM Agent	吸收 Design 交叉審閱（4 Major + 4 Minor）+ R5-D1/D2/D3 + R5-E1～E6：(1) 「首次啟動自動開」→「每次啟動自動開」全文修正（R5-D3）；(2) auto-open 平台預設 Linux OFF（R5-D2）；(3) US-7 新增 AC-7.7 Server 崩潰時發 OS 原生通知（R5-D1）；(4) §4 新增 N7 OS 通知、N8 啟動階段化進度（6 階段）；(5) AC-1.3 從 10 秒硬指標改寫為 60 秒 + perceived performance + AC-1.3a/b/c/d 四條新驗收（R5-E1～E6）；(6) US-2 明確日常啟動同樣 auto-open（Minor 1）；(7) Offline Overlay 補齊 `role="alertdialog"` + focus trap + 不可關閉 + 純色卡片（Minor 2）；(8) US-7 AC-7.3 / AC-7.6 補 Wails 控制台 Footer 持久警示 + Error state 三動作按鈕（Minor 3）；(9) US-1 AC-1.4 補 First-Run 從 3 步縮為 2 步 + 「稍後再設定」略過（Minor 4）；(10) §6.1 idle RAM 加不含瀏覽器 tab 註記 + Architect 實測佐證；(11) §11 懸念 5 題結案 + 新增 11-6 / 11-7，保留 11-4 CI 測試分層懸置

43 KiB Raw Permalink Blame History Unescape Escape

visionA-local — 產品需求文件（PRD v2）

0. v2 變更摘要（和 v1.2 的差異）

v2.1 補丁摘要（相對 v2.0）

1. 產品策略與定位（重寫）

1.1 新定位

1.2 一句話價值主張

1.3 競品類比更新

1.4 北極星指標（更新）

1.5 策略取捨紀錄

2. 目標使用者（修訂）

2.1 Persona 變動

2.2 Persona 對新架構的反應（PM 預測）

3. 非目標補充（修訂）

4. 功能清單與 API 對照（大幅修訂）

4.1 保留（沿用 v1.2）

4.2 砍除（v2.0 明確刪除）

4.3 新增（v2.0 明確增加）

4.4 功能對 Persona 對照表（更新）

5. User Stories（重寫受影響的）

US-1：第一次安裝 → 首次看到推論 UI（重寫，取代 v1.2 US-1 + 部分 US-5）

US-2：日常啟動（新增，取代 v1.2 US-2 Mock）

US-3：連實體 Kneron 裝置（微調）

US-4：切換 / 上傳模型（微調）

US-5：跑即時攝影機推論（重寫，瀏覽器情境）

US-6：上傳影片推論（修訂，取代 v1.2 US-7 / US-8）

US-7：Server 崩潰 / 意外中斷（新增）

砍掉的 User Stories

6. 非功能需求（更新）

6.1 效能指標

6.2 安裝檔大小（更新）

6.3 瀏覽器相容性（新）

6.4 安全性需求（修訂）

6.5 其他非功能需求

7. 第三方授權宣告（大改，取代 v1.2 §4.8）

7.1 依賴對照表（v2.0）

7.2 macOS ffmpeg 自 build 的長期責任

7.3 授權檔案落點

8. 風險與相依性（大幅修訂）

8.1 技術風險變動

8.2 新增風險（v2.0）

N-R1 — 瀏覽器相容性差異（新）

N-R2 — macOS 自 build ffmpeg 的長期維護成本（新）

N-R3 — 使用者誤解「關閉視窗 ≠ 結束 server」（新）

N-R4 — 砍 Mock 後 CI / E2E 測試困難（新）

8.3 PM 需要進一步確認的事項（寫入 progress.md 未解決問題）

9. 策略性路線圖（更新）

10. 變更追蹤（和 v1.2 的完整差異清單）

11. 給 Orchestrator / 下輪審閱的問題

變更紀錄

43 KiB

Raw Permalink Blame History