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

36 KiB

Raw Blame History

PM 第一輪分析 — visionA-local 方向變更（2026-04-14）

作者：PM Agent 性質：第一輪分析筆記，非正式 PRD 修訂 觸發事件：使用者在 M7 收尾階段提出三項重大方向變更對應使用者訊息：「推論只需包含 camera / image / video upload」「模型只預設 + 只能上傳」「介面希望是網頁不是包在應用程式中」「Wails 負責顯示 server log / 啟停重啟 / 打開 localhost 網頁」

摘要（3 行）

這是一個 L 級變更，不是 S 級：三項變更疊加起來等於把 visionA-local 從「Wails 內嵌式桌面 app」重新定位為「Ollama / LM Studio / Stable Diffusion WebUI 式的 server 管理器 + 獨立 web UI」，PRD 第 1 章（定位）、第 2 章（使用情境）、第 4 章（功能清單）、第 6 章（非功能需求）、第 8 章（風險）全部要改，競品類比也要換。
最大的哲學衝突：原 PRD 的北極星指標是「內部 FAE 在客戶現場 5 分鐘內跑出第一次推論 ≥ 95%」，現在多一步「要使用者先在桌面 app 按 Start Server → 再點 Open Browser → 瀏覽器才看到 UI」，這對「零摩擦 3 分鐘 demo」體驗是退步而非進步，PM 必須先釐清使用者動機，否則會做出一個「技術上更乾淨、但使用體驗更差」的產品。
目前開發階段是最糟的時機點：M1-M6 已經做完，dmg 220MB 可跑，M7 Windows build 在收尾。此時做這種方向轉彎代價很高——前端 Sidebar / 4 主導航 / Workspace / Settings 全部要重新思考「誰住在 Wails 裡、誰住在瀏覽器裡」。但如果使用者的動機夠強（見 C1），延後改比現在改更貴。必須先釐清動機再做決定，不要為了「使用者說了就做」而跳過第一輪分析。

A. 變更解讀

A1. 影片來源變更（砍 URL / yt-dlp）

新要求：推論只包含 camera / image / upload 影片(avi, mpeg, mp4 瀏覽器能吃的格式)。

PM 解讀：

使用者明確砍掉 /api/media/url（YouTube / yt-dlp 相關）。
「瀏覽器能吃的格式」是一個關鍵措辭——暗示使用者的 mental model 從「我用桌面 app 解影片」轉向「我用瀏覽器播影片」。這跟 A3 介面變更是同一件事的兩面。
但這裡有個語意陷阱：瀏覽器能播的 <video> 格式（主要是 MP4 H.264/AAC、WebM VP9/Opus、Ogg）不等於 Kneron 推論管線能吃的格式。推論仍然需要 ffmpeg decode 成 frame 餵給模型。使用者可能沒意識到這一點。這題必須回去澄清（見 C1）。
原本 /api/media/upload/video 已經在保留清單，所以「上傳影片」不是新功能，真正被砍的只是 URL 模式。

影響範圍（具體）：

後端：POST /api/media/url 整個 endpoint 拔掉；server/internal/media/url_handler.go 或類似檔案整包刪。
Bundle：yt-dlp 35MB 可以拔掉，dmg 從 220MB 降到約 185MB，符合 6.2 節 macOS ≤ 220MB 的原目標值（目前是壓著上限走）。這是個體積紅利。
前端：媒體上傳頁面的「URL 貼上」輸入框、「從 YouTube 下載」tab、相關 Loading 狀態（對應 recent commit a6b71ea fix(local-tool): URL 影片載入提示「正在解析，請耐心等待」）全部拔掉。
授權宣告：4.8 第三方授權宣告的 yt-dlp 條目可以移除，LICENSE-yt-dlp.txt 不用打包。
Risk：P2（FAE 不知道有新版）不受影響；但原 R11（發佈通路）如果本來要放 yt-dlp 需要高流量下載則壓力降低。

還沒確認的疑問：

「camera / image / upload 影片」這個措辭漏掉了批次影像 POST /api/media/upload/batch。使用者是忘了、還是也要砍？（見 C2）
砍 URL 模式是否連帶砍 US-8（User Story）？我傾向砍，但要使用者確認。

A2. 模型管理變更（只預設 + 只能上傳）

新要求：模型除了預設的幾種只能用上傳的。

PM 解讀：

現況：預設 8 個 .nef（73MB 內嵌）+ 支援使用者上傳自己的 .nef。
新要求：跟現況幾乎一樣，重點是明確否定「從 URL / Model Zoo 下載」這類未來可能性。
這有兩個可能讀法：
- 讀法 A（保守）：使用者只是確認「不要做 Model Zoo / 遠端下載功能」，目前的預設 + 上傳就是最終狀態。
- 讀法 B（更激進）：使用者可能想重新檢視預設清單——是要維持 8 個？還是想精簡到 3-4 個最有代表性的？
我傾向讀法 A，因為原 PRD 本來就沒規劃 Model Zoo，這句話更像是「再次確認非目標」而非新增要求。但要回去跟使用者確認（見 C3）。

還沒確認的疑問：

使用者上傳 .nef 後，是否需要命名、分類、加說明文字、刪除？原 feature-inventory model-upload-dialog 應該已經涵蓋，要請前端 lead 回看現況。
預設模型的「重置」按鈕是否需要？（使用者不小心刪掉預設模型後能不能還原）

影響範圍：

若讀法 A 正確，這項變更幾乎不影響程式碼，PRD 只需在 4.1 / 4.2 / 4.5 章節明確寫「只預設 + 只上傳，不支援任何形式的遠端模型下載」，並把它列入第 3 章非目標。
若讀法 B 正確，需要重新評估預設模型清單，但這是 Architect / KneronPLUS 範疇的事。

A3. 介面架構巨變（Wails 內嵌 → Wails server 控制台 + 瀏覽器 UI）

這是最大的、最需要深挖的變更。

新要求（逐字擷取）：

我想像中的是 visionA local 安裝完啟動後應用程式介面會有可以顯示 local server log 的地方有可以啟動/停止重啟 local server 的介面有打開 localhost 網頁的介面網頁上會有 scan/connect device 的介面選模型/上傳模型推論的介面

PM 解讀：這實質上是把 visionA-local 從「Wails webview 直接顯示 Next.js UI」退化成**「兩個 app」**：

Wails 桌面 app（server 控制台）：只負責
- 顯示 Go server 的 stdout / log（類似 Docker Desktop 的 Logs 面板）
- 啟動 / 停止 / 重啟 local server 的按鈕
- 「Open in Browser」按鈕（點了開瀏覽器到 http://localhost:{port}）
- 可能還要顯示：server 狀態（running / stopped / error）、port 號、資料目錄路徑、版本號
- 不顯示推論 UI
瀏覽器網頁（真正的 UI）：跟現在的 Next.js 前端幾乎一樣（但要適應沒有 Wails bridge 的情況）
- Scan / Connect Device
- 選模型 / 上傳模型
- 推論（camera / image / video upload）

這是什麼定位？競品類比換人：

原本的類比：Photo Booth、Kneron 官方 demo app——桌面 app，打開就用。
新的類比：Ollama（server 跑在背景 + 獨立 web UI / CLI）、LM Studio（有桌面 app 也有 server 模式）、Stable Diffusion WebUI（點 bat 啟動 + 瀏覽器打開 127.0.0.1:7860）、Docker Desktop（桌面 app 只管 daemon，真正的操作在 CLI / Dashboard）。
這個類比轉換會影響所有對外文案：
- 原本「裝起來就能跑」→ 現在更像「一鍵起 local server，用瀏覽器操作」。
- 原本「像一般桌面 app」→ 現在更像「像 Ollama 一樣輕量伺服器」。

為什麼使用者會這樣想？PM 的猜測（必須回去問，見 C1）：我沒有資料支持，只能猜。列出可能動機讓使用者確認：

#	可能動機	我的評估
a	想要多視窗 / 多分頁，一邊看推論結果一邊看裝置管理	合理。Wails 單視窗架構確實限制了這件事
b	想要瀏覽器的開發者工具（inspect / network / console），除錯方便	合理。Wails webview 也能開 devtools 但比瀏覽器難找
c	想要分享 localhost 連結給同網段其他人（例如客戶的手機開 `http://192.168.1.10:port` 看 demo）	高度懷疑這一點——原 PRD 6.6 明確寫「絕對不 bind 0.0.0.0」。若這是動機，等於安全模型也要改
d	不想被 Wails 視窗鎖住——想讓 server 在背景跑、瀏覽器關掉也沒差，下次要用再開瀏覽器	合理。這是 Docker Desktop / Ollama 的體驗
e	熟悉瀏覽器操作習慣	合理但薄弱。單一動機不足以支撐這種大改
f	想要能用手機 / 平板當第二螢幕看推論（同上 c）	同 c，安全模型風險
g	看不慣 Wails webview 的某些 bug（例如 splash regression，見 progress.md M7）	合理。但這是解 bug 不是改架構
h	想把 web UI 獨立出來，未來可能部署到別處（不綁 Wails）	合理長期考量，但目前內部工具用不到
i	單純覺得「server + web UI」架構比較乾淨	工程師審美考量，PM 角度會挑戰

不同動機導出不同產品方向——a, b, d, g 導向「架構輕度重整，還是桌面 app 為主」；c, f 導向「server 要能被同網段連線，安全模型大改」；h 導向「web UI 要獨立可部署，跟 Wails 解耦」。必須先知道是哪一個，不能一把梭。

PM 的擔憂（一個句子）：

這個變更方向在技術上更乾淨，但在使用者體驗上可能是退步——因為它把原本「雙擊 app → 看到 UI」的 1 步流程變成「雙擊 app → 按 Start → 按 Open Browser → 看到 UI」的 3 步流程，違反 P1 Persona Arthur 的核心願望「不要為了環境浪費客戶時間」。

A3.5 多使用者情境：其他使用者是 FAE 還是外部客戶？

第四輪決策是「內部工具」，所以沒處理「分享給外部」。但 A3 如果動機是 c（分享 localhost 給同網段），會把產品定位從「內部 FAE 個人工具」推向「內部 FAE 向客戶 demo 的 server」，這會改變威脅模型：

內部 FAE 個人工具：威脅模型 = 本機（127.0.0.1 + 無認證即可）
向客戶 demo 的 server：威脅模型 = 區網（可能需要密碼 / token / 限制連線 IP / HTTPS 自簽）

B. 影響範圍

B1. PRD 要改的章節（按影響嚴重度排序）

章節	子檔案	變更性質	嚴重度
1. 產品策略與定位	`strategy.md`	重寫。競品類比從 Photo Booth 換成 Ollama / LM Studio；價值主張要重述（「本機 server + 瀏覽器 UI」而非「桌面 app」）；北極星指標的 5 分鐘門檻是否還合理需要重評	🔴 高
2. 目標使用者與使用情境	`user-research.md`	修訂 + 重寫 US。US-1（第一次安裝）驗收標準 AC-1.3 要加「App 啟動後顯示 server 控制台」；US-2 / US-3 / US-4 / US-5 全部要重寫流程（因為真正操作在瀏覽器而非 Wails 視窗）；US-6 原本已砍；US-7（上傳影片）要保留但砍掉 URL；US-8 砍掉；User Journey Map「第一次成功」階段要重畫	🔴 高
3. 產品願景與非目標	`vision-and-non-goals.md`	補充非目標。明確寫「不支援遠端模型下載 / Model Zoo」「不支援影片 URL 推論 / yt-dlp」「不 bind 0.0.0.0（除非使用者確認 A3 動機 c/f）」	🟡 中
4. 功能清單與 API 對照	`features/feature-inventory.md`	大幅修訂。4.1 API：刪 `/api/media/url`；4.2 前端路由：重新切分「Wails shell 顯示什麼 / 瀏覽器顯示什麼」；4.3 元件：把 cluster UI、relay-token-sync 一樣明確刪，同時新增 server 控制台元件（start/stop 按鈕、log viewer、open browser 按鈕）；4.5 新增功能表：加「server 生命週期控制面板」；4.6 要刪的檔案：加 yt-dlp 相關；4.8 授權宣告：刪 yt-dlp 條目	🔴 高
5. 使用者流程	`features/user-flows.md`	重寫。First-Run / 日常使用 / 離開的流程都要重寫（Wails app 變成 server 管理器，使用者第一次啟動要引導「點 Open Browser」）	🔴 高
6. 非功能需求	`nonfunctional.md`	修訂量化值。6.1 首次推論時間要拆得更細（Wails shell 啟動 / server 啟動 / 瀏覽器開啟 / 第一幀）；6.2 安裝檔大小目標可以降低（yt-dlp 35MB 拔掉）；6.6 安全性需求要根據 A3 動機（c/f）決定是否改 bind IP；6.8 主題跟隨系統這一條在瀏覽器中是「跟隨使用者 OS prefers-color-scheme」而非「Wails webview 繼承 OS」	🔴 高
7. 發佈與交付策略	`release-strategy.md`	輕微影響。dmg 變小、發佈說明要寫「啟動後點 Open Browser」	🟢 低
8. 風險與相依性	`risks.md`	新增風險。見 D 章	🟡 中

B2. 要砍的功能（具體清單）

#	項目	出處	動作
1	`POST /api/media/url` endpoint	`feature-inventory.md` 4.1	刪除
2	yt-dlp 內嵌（35MB）	`feature-inventory.md` 4.8 / `progress.md` M6-2	從 vendor / payload / installer 全部拔掉
3	前端「URL 貼上」UI	`frontend/src/app/media/` 或類似	刪除
4	US-8（YouTube / URL 推論）	`user-research.md` 2.3	刪除
5	授權宣告中的 yt-dlp 條目	`feature-inventory.md` 4.8	刪除
6	「模型從 URL 下載」類功能（若存在）	需確認	確認無後標為非目標
7	（待確認） Wails webview 內嵌 Next.js 前端的架構	`server/main.go` + Wails config	改為只 serve server 控制台介面
8	（待確認） Wails 首頁 iframe / navigate 到 Next.js build	同上	改為 server 控制台 UI

B3. 要重寫的 user story

US	原標題	變更性質
US-1	第一次安裝	大幅重寫。AC-1.3「安裝完成後系統中出現 app icon」不變，但要加 AC-1.7「第一次開啟 app 看到 server 控制台，不是 Dashboard」；AC-1.8「控制台有明確引導『按這裡在瀏覽器打開 UI』」
US-2	Mock 模式試玩	重寫。進入 Mock 模式的入口從「First-Run 選擇 Mock」變成「先在控制台啟動 server（選 Mock 模式） → 開瀏覽器 → 看到 Mock UI」
US-3	連實體 Kneron 裝置	中度重寫。偵測流程不變，但「看到裝置」的 UI 在瀏覽器，不在 Wails 視窗。邊緣情況：若瀏覽器沒開，USB 插入事件要不要 push 到 Wails 控制台 toast？
US-4	切換 / 上傳模型	中度重寫。「拖放 .nef 到視窗任何地方」—— 哪個視窗？Wails 控制台？瀏覽器？兩邊都要？這是體驗面 Design 要回答的關鍵問題（見 E 章）
US-5	跑即時攝影機推論	中度重寫。Workspace 頁在瀏覽器。這裡有個瀏覽器特有的新限制：瀏覽器 `navigator.mediaDevices.getUserMedia()` 取 webcam 需要 HTTPS 或 localhost（目前 localhost 勉強可過但 Chrome 可能提示 permission），跟原 Wails 直接走 Go + AVFoundation / DirectShow 的模型不同。這是關鍵技術風險（見 E 章）
US-7	上傳影片 / 圖片做離線推論	輕微修訂，格式限定「瀏覽器能吃的」
US-8	YouTube / URL 推論	砍掉
US-9	查看 server 日誌	升級。原本是 Settings 進階分頁的次要功能，現在變成 Wails 控制台的一級功能，要獨立一個 AC

B4. 原本架構中「為了 Wails 內嵌」做的設計（請 Architect 補完整清單）

PM 只能從 PRD / progress.md 看到的表層：

server/web/out 內嵌（M1 收尾的 build-embed target）：把 Next.js frontend/out 同步到 server/web/out，再 embed 進 Go binary。這個設計在新架構下仍然有效——但要考慮 Wails 控制台是用什麼技術？是 Wails 自己的 UI（Go template / Wails 原生 webview 顯示一個極簡 HTML）？還是另一份 Next.js build？
Wails /ipc/raise endpoint + wails-ipc-port 檔案（M7 L-3）：原本用來讓 server 崩潰後可以叫回 Wails 視窗。新架構下這個還有意義嗎？server 崩潰時需要通知的是誰——Wails 控制台？還是瀏覽器？兩邊？
Single-instance 保護（PRD 5.5，第四輪決策）：使用者第二次雙擊 app 時 raise 既有視窗。新架構下 single-instance 還是要做，但 raise 什麼——Wails 控制台？還是 focus 既有的瀏覽器 tab？（瀏覽器 tab focus 跨瀏覽器很難做）
⌘Shift+R 重啟服務（第四輪 R4-6）：這個快捷鍵是給 Wails webview 用的。新架構下快捷鍵要住在哪——Wails 控制台用 Wails menu bar，瀏覽器網頁如果要也要的話得自己用 JS 監聽（還會被瀏覽器預設快捷鍵衝突）。
Mock 模式的 sidebar 標記 / 主視窗標題列標記（4.5）：現在「主視窗」有兩個——Wails 控制台、瀏覽器 tab。兩邊都要標嗎？
Wails tray 已砍、改用主視窗 menu bar（第三輪 Q-A）：新架構下 menu bar 屬於 Wails 控制台。那「上傳模型」這種動作，從 Wails menu bar 按下去是要直接處理，還是要切到瀏覽器？
Fatal 原生對話框（L-2）：這個維持有效。
First-Run 歡迎流程在哪：原本是 Wails webview 載入 Next.js 前端的第一個畫面。新架構下——是 Wails 控制台放一個「首次啟動引導」（講解控制台怎麼用），還是瀏覽器打開後才看到 First-Run（跟以前一樣）？還是兩邊都要（Wails 講控制台、瀏覽器講功能）？

請 Architect 補充： 現有 local-tool/server/main.go、Wails wails.json、前端 next.config.js 裡面哪些設定是為了內嵌架構而存在、新架構下哪些要改、哪些可以直接沿用。

C. 待使用者決策的問題

每題都是「必須先問才能繼續」——不是可以延後的。

C1. 🔴【最關鍵】介面架構變更的動機是什麼？

為什麼問：A3 章列出 9 種可能動機（a ~ i），每一種導向不同的產品方向。不問清楚就做會做錯。

選項：

A：多視窗 / 多分頁的便利性（可以一邊看推論、一邊看裝置）→ 方向是「架構輕度重整，Wails 只是 server 生命週期管理器，UI 主體仍在本機瀏覽器，127.0.0.1 不變」
B：想要瀏覽器開發者工具 / 熟悉瀏覽器操作 → 同 A，方向相同
C：要分享 localhost 給同網段的其他裝置（客戶的手機、平板）→ 方向是「架構重整 + 安全模型大改 + 要加認證 / token / IP 限制」這會是另一個 L 級工作
D：想讓 server 在背景跑、瀏覽器關掉也沒差，下次要用再開瀏覽器 → 同 A，方向相同但要加「視窗關閉不終止 server」
E：單純看不慣 Wails webview 的某些 bug（例如 splash 問題）→ 建議不要為此改架構，先解 bug
F：想讓 web UI 可獨立部署（未來不綁 Wails）→ 方向是「把 web UI 做得跟 Wails 完全解耦，未來可以 deploy 到別處」
其他 / 混合：請使用者直接說

PM 建議：

我強烈建議使用者選 A / B / D（或混合），理由是這三種動機都能在不改安全模型的情況下達成，改動範圍可控。

如果選 C 或 F，我會要求暫停 M7 Windows build，重新開一輪三方聯合討論，因為這相當於改變產品的核心定位。

如果選 E，我會直接挑戰使用者：解 bug 比改架構便宜一個數量級，先把 bug 修掉再說。

C2. 🟡「camera / image / 上傳影片」有涵蓋批次影像上傳嗎？

為什麼問：原 /api/media/upload/batch（批次多張圖片上傳）在 feature-inventory 是保留的，新要求措辭漏掉。

選項：

A：保留批次上傳（一次處理多張圖片）
B：砍掉，只保留單張圖片 + 單支影片
C：保留但降級為 Phase 2

PM 建議：

保留（選 A）。批次上傳是既有功能，砍掉無理由，對 FAE 用批次跑回歸測試有價值。

C3. 🟡 模型管理：「只預設 + 只能上傳」的解讀是 A 還是 B？

為什麼問：見 A2 章節。

選項：

A：維持現況的 8 個預設 .nef + 使用者上傳，只是確認「不要做 Model Zoo / 遠端下載」
B：重新評估預設清單，可能精簡到 3-4 個
C：把預設也砍掉，只留上傳

PM 建議：

選 A。原 PRD 本來就沒規劃 Model Zoo，這句話更像是再次確認非目標。選 B 會增加決策成本（「要留哪 3 個？」），選 C 會破壞 Mock / 即時體驗（Persona P3 Solution Architect 的 demo 場景沒模型就完蛋）。

C4. 🔴 Wails 控制台的 scope 究竟有多小？

為什麼問：使用者說「顯示 log」「啟動/停止/重啟」「打開 localhost」，這是最小集合。但還有很多「邊緣功能」不知道要不要也住在 Wails 控制台：

選項（每項都要獨立回答）：

功能	要住在 Wails 控制台嗎？	PM 預設建議
顯示目前 server port	是 ✅	是（使用者需要知道 URL 是 127.0.0.1:XXXX）
顯示資料目錄路徑（macOS `~/Library/Application Support/visiona-local/`）	是 ✅	是（除錯時常用）
顯示版本號 / 建置資訊	是 ✅	是
顯示 server 狀態（running / stopped / error）	是 ✅	是
Mock 模式切換按鈕	待決定 ⚠️	是（Mock 是 server 模式，不是業務模式，住控制台合理）
硬體偵測結果（已接上幾台 Kneron）	待決定 ⚠️	不要（屬於業務資訊，住瀏覽器 UI）
上傳模型	待決定 ⚠️	不要（業務功能）
匯入 / 匯出設定	待決定 ⚠️	是（屬於「工具維護」）
清除 log / 查看歷史 log 檔	待決定 ⚠️	是
第三方授權宣告 About	待決定 ⚠️	是（Wails About 對話框）
Settings > 一般 / 語言	待決定 ⚠️	不要（屬於瀏覽器 UI 的 Settings 頁）
崩潰後的原生對話框通知	是 ✅	是

請使用者逐項確認，或直接接受 PM 建議。

C5. 🔴 Wails 視窗關閉行為

為什麼問：原 PRD Q7 決定「關閉視窗 = 結束程式」（所以砍 tray）。新架構下這個語義要重新定義，因為現在視窗關閉影響兩個東西：server、瀏覽器 UI。

選項：

A：關閉 Wails 控制台 = 停 server = 瀏覽器 UI 失效。最簡單。但使用者若關了控制台忘了 server 還在跑，不會發生這種狀況。
B：關閉 Wails 控制台 ≠ 停 server。關閉後 server 仍在背景跑，下次重開 Wails 控制台 attach 回去。像 Docker Desktop。但在 macOS / Windows / Linux 實作有差異，且 single-instance 保護要重寫。
C：關閉 Wails 控制台時彈確認對話框問使用者「要不要一起停 server」。

PM 建議：

初步偏 A（最簡單），除非使用者在 C1 選了動機 D（想讓 server 在背景跑）。若選 D 則必須是 B。

這題的決定直接影響 B4 第 3 項 single-instance 設計。

C6. 🟡 使用者要不要有機會直接雙擊開瀏覽器（不經過 Wails 控制台）？

為什麼問：既然 UI 在瀏覽器，使用者其實不需要每次都打開 Wails 控制台——他可能想要像 Ollama 那樣「server 背景跑著，直接打開 http://localhost:XXXX」。但這跟 C5 的 B 方案強相關。

選項：

A：必須先開 Wails 控制台，Wails 控制台負責起 server，然後才能用瀏覽器
B：提供 macOS 的 LaunchAgent / Windows 的啟動項 / Linux systemd user unit，讓 server 可以背景常駐（類似 Docker Desktop / Ollama）
C：不背景常駐，但提供 CLI 啟動模式（使用者可以自己 open -a visiona-local 或 visiona-local serve）

PM 建議：

選 A + 未來考慮 C。這是 MVP，先把最小路徑做對。背景常駐會引入 autostart / tray / 開機啟動等一整套複雜度（而 tray 才剛被砍）。

C7. 🟡 瀏覽器選擇：使用者預設瀏覽器 or 指定 Chromium-based？

為什麼問：webcam（US-5）在 Safari / Firefox / Chrome 的權限流程和支援度不同。攝影機 overlay 效能也不同。

選項：

A：用使用者的 OS 預設瀏覽器（Safari on macOS / Edge on Win / Firefox / Chrome 依系統設定）
B：強制 Chrome / Edge 系列，其他瀏覽器警告
C：內嵌 Chromium（如 Electron，但整包會變很大 100MB+）

PM 建議：

選 A 但在 README / First-Run 控制台提示「推薦 Chrome / Edge，Safari 可能有攝影機權限限制」。選 C 違反整個 MVP 的瘦身原則（dmg 會從 220MB 變 400MB+）。

C8. 🔴 Wails 控制台的首次啟動引導如何設計？

為什麼問：原 PRD 的 First-Run 流程（歡迎 → 選擇模式 → 硬體偵測）是長在 Next.js 前端裡的。新架構下這個流程要搬家——是搬去 Wails 控制台、還是維持在瀏覽器但等「使用者第一次開瀏覽器」才看到？

選項：

A：整套 First-Run 仍在瀏覽器端，Wails 控制台的首次啟動只是提示「按 Start Server 然後按 Open Browser」
B：First-Run 拆成兩段：Wails 控制台引導「怎麼用這個控制台」，瀏覽器端引導「怎麼用 visionA-local 的功能」
C：First-Run 整套搬到 Wails 控制台，瀏覽器打開後直接進 Dashboard

PM 建議：

選 A。Wails 控制台是次要視窗，不應該搶 First-Run 戲份。但要確保「按 Open Browser 後」瀏覽器會自動打開到正確的 http://localhost:XXXX/onboarding 路由。

C9. 🟢 這次變更是否要重做 `progress.md` M7 的 Windows build？

為什麼問：M7 正在收尾，若這輪變更砍了 yt-dlp + 改前端架構，Windows build 可能要等改完再跑。

選項：

A：先把 M7 Windows 收完（拿到 Windows 能跑的 baseline），再基於 baseline 套這輪變更
B：M7 停擺，本輪變更優先
C：M7 和本輪變更平行做（高風險）

PM 建議：

選 A。理由：Windows 能跑的 baseline 是品質保險，即使這輪變更改掉 70% 前端，「Windows 能跑 server + 可以打包」這件事本身不會白費。

D. 風險觀察

D1. 【新】「零摩擦安裝」承諾被打破

描述：原 PRD 北極星指標是「5 分鐘內跑第一次推論 ≥ 95%」，P1 Persona Arthur 的一句話是「雙擊 app、插 USB，就能 demo」。新架構多一步「點 Open Browser」，對 Arthur 的心智負擔是 +30%。
可能性：高（結構性變更，不是實作品質問題）
影響：中-高（可能違反北極星承諾）
緩解：(1) Wails 控制台啟動時自動 Start Server（不用手動按），(2) Server 就緒後自動 Open Browser（不用手動按），(3) Wails 控制台第一次啟動後可以「隱藏到背景」但不終止 server。這樣 UX 上仍是「雙擊 → 看到 UI」但底層是新架構。
等級：P0 阻斷項——若沒做到這三點緩解，我會建議使用者回到原架構或放棄變更。

D2. 【新】Safari / Firefox webcam 相容性

描述：瀏覽器 getUserMedia 在 Safari 17+ 雖然支援 localhost HTTP 的 camera permission，但跟使用者的直覺不同；Firefox 也有類似 permission flow 問題。原 Wails 內嵌架構下，直接走 Go + AVFoundation / DirectShow / V4L2，使用者感知不到 permission。
可能性：高（每個 macOS 預設 Safari 使用者都會碰到）
影響：中（US-5 攝影機推論的起步體驗變差）
緩解：(1) README / 首次引導推薦 Chrome / Edge，(2) 在 Wails 控制台的「Open Browser」按鈕旁邊標示「如使用 Safari 需額外允許攝影機權限」，(3) 攝影機啟動失敗時提供具體錯誤訊息。
等級：P1 追蹤項。

D3. 【新】Server 只聽 127.0.0.1 vs 同網段需求的衝突

描述：原 PRD 6.6 明寫「絕對不 bind 0.0.0.0」。若使用者在 C1 選動機 C / F，就得 bind 0.0.0.0 並加認證，這是另一個 L 級工作。
可能性：未知，取決於 C1 答案
影響：大（安全模型改寫）
緩解：C1 先問清楚，動機若非 C / F 則維持 127.0.0.1
等級：待 C1 回答後定級

D4. 【新】Wails 控制台的跨平台 UI 一致性風險

描述：現在的架構下，Wails 只是 webview，UI 本身是 Next.js 跨三平台一致。若控制台改用 Wails 原生 menu + 原生 button，會碰到三平台原生元件差異，重回「跨平台原生 UI」的泥沼。若控制台還是用 webview + HTML，等於又多一份前端 build。
可能性：高
影響：中（開發成本）
緩解：Architect 要在 TDD 裡明確說明「控制台 UI 是用什麼技術」——我建議仍然用 webview + 極簡 HTML 而非 Wails 原生 UI（避免三平台 UI 分岔）。
等級：P1

D5. 【新】使用者關閉瀏覽器後 server 是否仍在跑的心智模型不清

描述：跟 C5 相關。Docker Desktop / Ollama 的體驗是「server 是常駐的」，使用者不會覺得怪；但 visionA-local 若採 C5-A（關 Wails 等於關 server），使用者關了瀏覽器再開瀏覽器發現 UI 404 會困惑。
可能性：中
影響：中
緩解：瀏覽器端檢測 server 不可達時顯示「server 已停止，請回到 visionA-local 控制台重新啟動」的友善錯誤頁
等級：P2

D6. 【新】「單一動機不足，但 sunk cost 足」的心理陷阱

描述：這是 PM 自己的 meta 風險提醒。使用者花了大量時間做 M1-M6，現在提出巨變。若動機薄弱（例如 E：「看 Wails splash 不順眼」），改架構的成本遠大於解 bug 的成本。PM 有責任挑戰這個決定，而不是順從。
緩解：C1 是保護機制。若 C1 答案是「沒特別理由」或 E，PM 應該建議不要改。
等級：管理風險

D7. 【既有】P2「FAE 不知道有新版」依然成立

描述：不受這輪變更影響，但在新架構下「版本號顯示」變得更重要，因為 Wails 控制台是版本資訊的第一個 touchpoint。
緩解：Wails 控制台顯眼處（例如視窗標題列）顯示版本號。
等級：P2

E. 給 Design 和 Architect 的議題

E1. 給 Design 的議題（體驗面）

Wails 控制台的資訊架構（對應 C4）：要放哪些資訊？排版？色調？這是一個全新頁面，不能從既有 Next.js sidebar 直接搬。建議 Design Agent 畫 wireframe。
「Open Browser」按鈕的視覺層級：這是新架構下最重要的單一 CTA。是不是該放在 Wails 控制台的正中央、像 Photo Booth 按拍照鈕那樣顯眼？還是像 Docker Desktop 那樣比較低調？
First-Run 的分段（對應 C8）：若選 A（整套 First-Run 在瀏覽器），Wails 控制台的首次引導要怎麼設計才不會打擾到「使用者只是想趕快開 UI」的急迫感。
拖放 .nef 的目標視窗（US-4）：使用者從 Finder 拖 .nef 檔，應該拖到 Wails 控制台？還是瀏覽器？兩邊都要支援？Design 要決定。
Mock 模式的視覺標記（4.5）：現在「主視窗」有兩個。兩邊都要打 Mock 標？還是只有其中一邊？
Server 啟動中的 loading 體驗：原本 Wails webview 直接載 Next.js，有個 splash 就結束了。新架構下有兩段等待：(a) Wails 啟動後到 server ready、(b) 瀏覽器打開後到頁面渲染完。兩段都要設計。
Wails 控制台的視窗大小：原本 Wails 視窗是 1280x800（主 UI）。新架構下控制台要小得多（可能 600x400 就夠），而且可能不需要 resize。
錯誤狀態的分佈：server 崩潰時要通知誰——Wails 控制台？瀏覽器？兩邊？通知形式（toast / modal / native dialog）如何分？

E2. 給 Architect 的議題（技術面）

Wails 控制台是用什麼實作（對應 D4）：最務實的選擇是 Wails webview + 極簡 HTML（不用 Next.js 那份 build）；另一個選擇是用 Wails 原生 menu / button（三平台原生 UI 不一致）；還有第三個選擇是 Next.js 產出兩份 build（主 UI + 控制台）。Architect 要提方案並分析利弊。
Next.js build 是否要解耦 Wails：原本 build 會 embed 進 Go binary，新架構下如果 UI 主體跑在瀏覽器，還要 embed 嗎？embed 的意義是什麼？可以改成 server 啟動時直接 http.Handler serve static/ 目錄。
Server 啟停的 IPC：Wails 控制台按下 Start 要叫 server 起來；按 Stop 要 graceful shutdown。目前 server 是透過 Wails 生命週期管理（M7 L-1 的 watchServer），新架構下要重新設計 IPC 協定。
Single-instance 保護（對應 C5 + B4-3）：新架構下「second instance」的定義變了。需要重新設計。
Server port 的分配：目前是隨機 port + wails-ipc-port 檔案（L-3）。新架構下要讓使用者在瀏覽器打開「固定 URL」還是「每次不同 port」？固定 port 方便但有衝突風險，隨機 port 要從 Wails 控制台讀取。建議是「固定 port 優先，衝突時降級為隨機並顯示」。
Wails App 的 Dock icon / taskbar 行為：macOS 的 Dock icon 一直亮著、使用者一定會發現有個 app 在跑。跟 Ollama（背景 tray + 沒有 Dock icon）不同。Architect 要決定要不要做 NSApplicationActivationPolicyAccessory（macOS）、hidden from taskbar（Windows）等。
瀏覽器打開方式：open http://...（macOS）/ start（Win）/ xdg-open（Linux）。Architect 要寫跨平台的 OS helper，注意防呆（例如使用者沒設預設瀏覽器時的 fallback）。
攝影機推論的新通路（對應 D2）：原本 Go server 直接用 AVFoundation / DirectShow / V4L2 抓 frame 做推論。新架構下如果 UI 跑在瀏覽器，是維持原路徑（server 抓 frame、MJPEG 推給瀏覽器）還是改走瀏覽器路徑（瀏覽器 getUserMedia → WebRTC / ImageCapture → POST 給 server）？強烈建議維持原路徑（伺服器抓 frame + MJPEG），效能和權限都簡單。但 Architect 要確認。
server 被同網段連線的防護：即使使用者選 C1-A/B/D，也要確認新架構下 server 真的只聽 127.0.0.1 沒意外 bind 0.0.0.0。這點要在 TDD 加驗收。
CORS / CSRF：瀏覽器發 request 到 localhost:XXXX 是同 origin（瀏覽器也在 localhost 開），理論上不需要 CORS。但如果使用者把 URL 複製到別台機器的瀏覽器（跟 C1-C/F 相關），會跨 origin。這題跟 D3 綁在一起。
現有 L-3（Wails /ipc/raise）是否仍需要：原本 server 崩潰後 raise Wails 視窗是為了顯示 UI。新架構下 server 崩潰後要 raise Wails 控制台（顯示錯誤），瀏覽器端只會顯示 offline 頁面。IPC 協定仍有效但意義變了。

結尾：PM 的立場聲明

作為 PM，我對這輪變更有三個明確的立場：

C1（動機釐清）是這次變更能不能做的前提。我不建議在沒有 C1 答案之前啟動任何實作。
D1（零摩擦承諾）是不能妥協的紅線。若新架構無法透過「自動 Start Server + 自動 Open Browser」達成「雙擊就看到 UI」，我會建議使用者回到原架構。
我不建議現在就跳去改前端。正確順序是：(1) 使用者回答 C1-C9；(2) PM 根據答案更新 PRD 相關章節；(3) 三方（PM / Design / Architect）重新聯合審閱；(4) 才進實作。這整個循環我估大約要 1-2 個工作日。

下一步（交給 Orchestrator）：

將本分析文件呈現給使用者
請使用者回答 C1-C9 九個問題（C1、C4、C5、C8 為必答；其他可接受 PM 建議）
答案到位後，請 Design Agent 和 Architect Agent 同步做第一輪分析（對應 E1、E2）
三方第一輪分析完成後再召開聯合討論，決定是否要做、怎麼做、對 M7 的影響

附錄：本分析文件的資料來源

/Users/jimchen/visionA/local-tool/.autoflow/02-prd/PRD.md（索引）
/Users/jimchen/visionA/local-tool/.autoflow/02-prd/features/feature-inventory.md
/Users/jimchen/visionA/local-tool/.autoflow/02-prd/user-research.md
/Users/jimchen/visionA/local-tool/.autoflow/02-prd/nonfunctional.md
/Users/jimchen/visionA/local-tool/.autoflow/02-prd/risks.md
/Users/jimchen/visionA/local-tool/.autoflow/progress.md（M1-M7 進度）
使用者第四輪變更訊息（2026-04-14）

36 KiB Raw Blame History Unescape Escape

PM 第一輪分析 — visionA-local 方向變更（2026-04-14）

摘要（3 行）

A. 變更解讀

A1. 影片來源變更（砍 URL / yt-dlp）

A2. 模型管理變更（只預設 + 只能上傳）

A3. 介面架構巨變（Wails 內嵌 → Wails server 控制台 + 瀏覽器 UI）

A3.5 多使用者情境：其他使用者是 FAE 還是外部客戶？

B. 影響範圍

B1. PRD 要改的章節（按影響嚴重度排序）

B2. 要砍的功能（具體清單）

B3. 要重寫的 user story

B4. 原本架構中「為了 Wails 內嵌」做的設計（請 Architect 補完整清單）

C. 待使用者決策的問題

C1. 🔴【最關鍵】介面架構變更的動機是什麼？

C2. 🟡「camera / image / 上傳影片」有涵蓋批次影像上傳嗎？

C3. 🟡 模型管理：「只預設 + 只能上傳」的解讀是 A 還是 B？

C4. 🔴 Wails 控制台的 scope 究竟有多小？

C5. 🔴 Wails 視窗關閉行為

C6. 🟡 使用者要不要有機會直接雙擊開瀏覽器（不經過 Wails 控制台）？

C7. 🟡 瀏覽器選擇：使用者預設瀏覽器 or 指定 Chromium-based？

C8. 🔴 Wails 控制台的首次啟動引導如何設計？

C9. 🟢 這次變更是否要重做 progress.md M7 的 Windows build？

D. 風險觀察

D1. 【新】「零摩擦安裝」承諾被打破

D2. 【新】Safari / Firefox webcam 相容性

D3. 【新】Server 只聽 127.0.0.1 vs 同網段需求的衝突

D4. 【新】Wails 控制台的跨平台 UI 一致性風險

D5. 【新】使用者關閉瀏覽器後 server 是否仍在跑的心智模型不清

D6. 【新】「單一動機不足，但 sunk cost 足」的心理陷阱

D7. 【既有】P2「FAE 不知道有新版」依然成立

E. 給 Design 和 Architect 的議題

E1. 給 Design 的議題（體驗面）

E2. 給 Architect 的議題（技術面）

結尾：PM 的立場聲明

附錄：本分析文件的資料來源

36 KiB

Raw Blame History

C9. 🟢 這次變更是否要重做 `progress.md` M7 的 Windows build？