jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/03-design/design-spec-v2.md
jim800121chen 46514d77d7 docs(local-tool): M9 — Kneron Dongle FW 偵測 + 升降版（A+B、翻案 R5-Q9） 
L 級新功能、PRD/Design/TDD/ADR 三方協作 + 互審 + M9-6 SDK 雙驗證、總計 ~9000 行文件。

範圍：
- A 階段（MVP、5 人天）：KL520 + KL720 自動升級 KDP1 → KDP2
- B 階段（10.5 人天）：手動降版面向一般使用者 + KL630 / KL730 擴展
- 合計 15.5 人天、安裝包 +7MB（保守 bundle 策略）

關鍵決策：
- 翻案 R5-Q9（progress.md 第二輪使用者決策「韌體燒錄 flash → B 砍掉」）
- 跨平台用 KneronPLUS Python C API、不用 DFUT.exe
- 多版本目錄結構選 C metadata（firmware/<chip>/{version}/ + CURRENT_VERSION）
- Kneron firmware redistribution 授權與 R5-B4 預置模型同性質、發佈前評估

文件產出：
- PRD v2.2（PRD-v2.md 495 行 + features/feature-firmware-management.md 599 行）
- Design v2.2（firmware-management.md 948 行 + control-panel.md §6a graceful shutdown）
- TDD v2.2（v2/firmware-management.md 823 行 + ADR-001 218 行）
- 8 份 research（含 M9-6 弱驗證 + 強驗證、~3200 行）
- 3 份三方互審報告（PM/Design/Architect cross-review）

M9-6 強驗證重大發現（影響 B 階段）：
- KL730 product_id 實際是 0x732（不是 0x0730）
- KL630/KL730 firmware 是 embedded Linux rootfs（不是 .bin、不同代設計）
- KneronPLUS Python 沒 update_kdp_firmware_from_files 公開 API、warrenchen 走 ctypes
- 不影響 A 階段、B 階段 M9-8 需 spike

下一步：派 backend M9-1 起跑（bridge.py handle_firmware_upgrade）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 07:40:56 +08:00

12 KiB
Raw Blame History

visionA-local 設計規格 v2（索引）

Design Agent · 第五輪正式規格 · 初版 2026-04-14 目前版本：v2.2（2026-05-24 補丁） — 吸收 R5-Q9 翻案、新增 Kneron Dongle FW 管理規格（升級 + 版本切換、面向一般使用者） 前一版本：v2.1（2026-04-14 補丁）— 吸收 Architect 交叉審閱 Major 1+2 / Minor 1-5 修正 + R5-D1/D2/D3 / R5-E 追加決策 本版依 R5 決策重構：visionA-local 從「Wails 跑 Next.js 的單一桌面 app」轉為「Wails Server Control Panel + 瀏覽器 Web UI」雙 UI 架構。 本文件為 v2 索引檔，各章節詳細內容見 v2/ 子檔。v1（design-spec.md + spec/）仍保留作為基準參考，未來的實作以 v2 為準。

v2 範圍

本次 v2 只重新設計因 R5 決策而改變的部分，其餘 v1 章節（IA、Settings 分頁結構、design tokens、i18n 策略、A11y 等）仍然有效。

R5 決策總表（本 v2 的立論基礎）

# 題目 使用者決定 對設計的影響
R5-1 重構動機 A+B+G（多視窗便利 + devtools + 需求方要求） 確立雙 UI 架構
R5-2 關閉 Wails 視窗行為 關閉 = 結束 server，瀏覽器顯示「Local Server 已離線」覆蓋層 新增 Server Offline Overlay 設計
R5-3 Tray 復議 維持砍 tray（T1） 控制台無 tray 退縮選項
R5-4 首次啟動自動開瀏覽器 A：首次自動開，Settings 可關 新增 Settings toggle + First-Run 流程變動
R5-5 Wails 控制台 scope PM 清單 拿掉 Mock 模式切換 控制台不顯示 Mock UI
R5-5a Mock 模式歸處 完全砍掉 Mock 模式 Settings 刪除硬體分頁的 Mock 相關項 / First-Run 砍模式選擇步驟
R5-6 ffmpeg 授權 LGPL 混合（Win/Linux BtbN、macOS 自 build） 不影響 UI 設計本身
R5-7 M7 Windows 先不管 不影響 v2

文件結構

# 章節 檔案 一句話摘要
v2.1 Wails Server Control Panel v2/control-panel.md 桌面控制台完整規格（wireframe、狀態機、元件、i18n、A11y）
v2.2 Server Offline Overlay v2/server-offline-overlay.md 瀏覽器端偵測到 server 斷線時的全螢幕覆蓋層
v2.3 source-selector 修改 v2/source-selector-update.md 砍 URL mode、重寫 video tab、要刪的 i18n key 清單
v2.4 First-Run 流程重定義 v2/first-run-update.md 砍 Mock 模式選擇步驟、自動開瀏覽器的起手流程圖
v2.5 Settings 頁更新 v2/settings-update.md 新增「啟動時自動開啟瀏覽器」toggle、Linux 預設 OFF、落地 preferences.json、砍 Mock 相關設定
v2.6 啟動進度面板（v2.1 新增） v2/startup-progress.md R5-E 階段化啟動進度面板：6 階段 wireframe、中英雙語文案、20 秒卡頓提示、60 秒 timeout Error 流程
v2.7 韌體管理（v2.2 新增） v2/firmware-management.md Kneron dongle FW 升級 + 版本切換完整規格：Settings 新分頁、Devices 頁 FW badge（紅/黃/綠 + deep-link）、二次確認流程（輸入 DOWNGRADE）、52 個 i18n keys、6 個新 component token、R-FW-11 設計緩解

v2 未動到的章節（仍以 v1 為準）

  • spec/01-information-architecture.md — IA 不變（4 主區塊 + Settings）
  • spec/02-pages-diff.md — 頁面清單變動極小（僅 workspace 推論源砍 URL）
  • spec/03-wireframes.md — Dashboard / Devices / Models / Workspace 主體不變
  • spec/06-cross-platform.md — 跨平台 UX 差異不變
  • spec/07-design-tokens.md — tokens 完全沿用
  • spec/08-states.md — 全域錯誤分級、空狀態文案不變
  • spec/09-accessibility.md — 盡力而為原則不變
  • spec/10-i18n.md — i18n 策略不變

Design Token 一致性（總則）

Wails Server Control Panel 與瀏覽器 Web UI 共用同一套 shadcn oklch design tokens（見 spec/07-design-tokens.md）。 具體做法：控制台前端是 vanilla HTML/JS/CSS（R5 三方共識），但仍引入與 Next.js Web UI 一致的 CSS variable 定義檔（從 frontend/src/app/globals.css 擷取 :root 與 [data-theme='dark'] 的 token block），達到：

  • 控制台與 Web UI 在 Light / Dark 下視覺語言一致
  • 錯誤訊息紅、警告琥珀、成功綠完全相同（不會出現控制台紅和 Web 紅不同的 UX 破綻）
  • 未來若 tokens 更新，只要同步 CSS variable 檔即可

不另外定義控制台專屬 tokens，唯一例外是控制台的 log panel 使用等寬字體 token（font.mono，v1 已存在），以及標題列 window-chrome.height（v1 spec/07-design-tokens.md §7.5 已定義）。

v1 → v2 差異總覽

面向 v1（第四輪） v2（第五輪） 來源決策
主視窗呈現 Wails 單視窗 = Next.js 主 UI Wails 單視窗 = Server Control Panel；Web UI 跑在瀏覽器 R5-1
視窗關閉 結束程式（第四輪 Q7） 結束程式 + 瀏覽器顯示離線 Overlay R5-2
Tray 無 無（維持） R5-3
首次啟動 Wails 開 → First-Run wizard 三步（歡迎 / 模式選擇 / 偵測） Wails 控制台開 → 自動 start server → 自動 open 瀏覽器 → First-Run wizard 兩步（歡迎 / 偵測） R5-4、R5-5a
首次啟動 Settings — 新增「首次啟動時自動開啟瀏覽器」toggle（預設 ON） R5-4
Mock 模式 預設真實硬體，可於 Settings > 硬體切換為 Mock 完全砍除，沒插硬體就空白 R5-5a
Settings 分頁 一般 / 硬體 / 模型 / 進階 一般 / 硬體 / 模型 / 進階（結構不變，內容刪減） v1 保留
Workspace 推論源 camera / image / video（file + url） camera / image / video（僅 file） R5 三方共識
支援影片副檔名 .mp4, .avi, .mov .mp4, .avi, .mov, .mpeg, .mpg R5 三方共識
影片載入文案 「正在解析影片連結，YouTube 影片可能需要 10-30 秒…」 純檔案上傳，無解析文案 R5 三方共識
Wails 控制台 scope 不存在 Header 狀態列 + Primary controls + Log panel + Log actions + Footer R5-5
Server 狀態機 黑盒 五態視覺化：Running / Starting / Stopping / Stopped / Error v2 新增
Server 崩潰通知 Wails shell out native notification 控制台內的 Error state 面板 + 紅字 log + OS notification v2 細化
瀏覽器端 server 斷線 未定義 全螢幕 Server Offline Overlay（不可關閉、提供重試） R5-2

v2.1 → v2.2 差異總覽（2026-05-24 補丁輪）

v2.2 是吸收 R5-Q9 翻案（FW 管理面向一般使用者）後的補丁，新增 Kneron dongle FW 升級 + 版本切換的完整設計規格。不改變 R5 雙 UI 架構立論、只新增功能模組。

面向 v2.1 v2.2（2026-05-24 補丁） 來源
Settings 分頁數 4（一般 / 硬體 / 模型 / 進階） 5（一般 / 硬體 / 韌體 / 模型 / 進階） R5-Q9 + architect 42
Devices 頁 FW 顯示 純文字 FW 2.1.0 pill badge（紅 / 黃 / 綠三色）+ deep-link ⚙ icon R5-Q9 第 5 點
FW 升級 UX 未設計 單步驟確認 + 進度 modal（不可中斷） architect 30 §M9-4
FW 降版 UX 未設計 二次確認（輸入「DOWNGRADE」字串）+ 進度 modal + 全螢幕 hover 攔截 architect 42 §5.3
失敗復原 UX 未設計 8 種失敗類型對應 friendly message + 復原行動 architect 42 §5.5
新增 i18n keys — 52 keys（zh-TW + en） 本檔 v2/firmware-management.md §9
新增 component tokens — 6 個 fw-badge token（current / older / legacy × bg/fg） 本檔 v2/firmware-management.md §11.2
UI 用語策略 — UI 一律稱「韌體管理」/「版本切換」（中性詞）、code/log/技術文件仍稱 downgrade architect 42 §1.1

v2 → v2.1 差異總覽（2026-04-14 補丁輪）

v2.1 是 v2 三方互審後的修正補丁，不改變 R5 雙 UI 架構立論，只處理 Architect 互審發現 + R5-D / R5-E 追加決策。

面向 v2（2026-04-14 初版） v2.1（2026-04-14 補丁） 來源
Settings 落地檔 settings.json + 「走 Wails settings store」 preferences.json @ <dataDir>/ + Go server write-rename atomic Architect Review Major 1
「啟動時自動開瀏覽器」預設值 三平台一致 ON macOS/Windows = ON，Linux = OFF（依 runtime.GOOS） R5-D2
Toggle label 字面 「首次啟動時自動開啟瀏覽器」（待確認） 「啟動時自動開啟瀏覽器」（R5-D3 定案：每次啟動都開） R5-D3
Log panel 上限 1000 行 + rotate 7 天 / 10 MB 2000 行 + 無落地 rotate（in-memory ring buffer，使用者透過 Export log 手動匯出） Architect Review Minor m-1、m-12
Error banner 「Report...」按鈕 正常按鈕 【hold】 待 PM 提供 GitHub Issue repo URL Architect Review Minor m-11
Error state OS 通知 v2 模糊（控制台可見，通知視為次要重複） R5-D1 保留：Error state 發 non-blocking toast notification，與控制台 Error banner 並存 R5-D1
Starting state 視覺 只有 header spinner，5 秒 timeout 階段化啟動進度面板（v2/startup-progress.md），6 階段 + 20 秒卡頓提示 + 60 秒總上限 R5-E
首次啟動流程 「首次」自動開瀏覽器 「每次」 啟動都自動開瀏覽器（Wails 每次新啟動） R5-D3

給 Orchestrator 的問題（懸而未決）

v2 懸而未決已解決：

  • Q2 Server 崩潰 OS 通知 → R5-D1 保留（已吸收至 control-panel.md §6.2 + startup-progress.md §3.7）
  • Q3 Linux 預設值 → R5-D2 Linux 預設 OFF（已吸收至 settings-update.md §2.2）
  • R5-4 label 字面歧義「首次 vs 每次」 → R5-D3 每次（已吸收至 settings-update.md §2.3 + control-panel.md §7.1）

仍懸而未決：

  1. 控制台 header「port 變更 fallback」視覺字樣：v1 第四輪決策「port 佔用則 fallback 到 3722/3723」，建議格式 Port: 3722 (default 3721 in use)，待使用者最終確認字樣。
  2. v2 是否要回頭作廢 v1 的 spec/04-first-run.md：目前 v2 另開 v2/first-run-update.md，但未修改 v1 原檔。建議 v2 穩定後作廢 v1 原檔並改為索引到 v2；在此之前保持雙軌。
  3. R5-E startup-progress.md 新增 3 個小懸念（v2/startup-progress.md §11）：
    • (a) 20 秒卡頓 hint 文案「正在重試...」vs 中性「正在處理中，請稍候...」
    • (b) 階段 6 WebSocket 連線被安全軟體擋的 Error 說明是否要特別提示
    • (c) 使用者按 Retry 的語意：重置整個啟動流程 vs 重試當前階段（Design 建議前者）

v2.2 新增懸而未決（來自 v2/firmware-management.md §14.4）： 4. 降版 modal 字串「DOWNGRADE」未來 i18n 化處理：當前 Design 規格要求所有語系使用者皆輸入字面字串 DOWNGRADE（en）。若未來改 i18n（如中文使用者輸入「降版」），需與 Architect / Frontend 確認後端 confirmToken 是否同步調整（architect 42 §2.3 後端固定接受 confirmToken: "DOWNGRADE"）。Design 建議短期維持英文字串（跨語言一致、避免後端多語對應）。 5. bundled 版本「發布日期」資料源：firmware-management.md §3.3 範例顯示「2024-08 發行」等文案，但 architect 42 §2.1 FirmwareVersion.ReleaseDate 為 optional。需 Backend 在 bundle firmware 時準備 metadata（每個 version 目錄附 META.json 含 releaseDate / notes）。metadata 缺則 UI fallback 為不顯示日期。 6. 降版進行中關閉 Wails 控制台視窗的攔截邏輯：依 R5-2 控制台關閉 = 結束 server。降版進行中關控制台 = 中斷降版 = 可能 brick。Frontend / Backend 是否需要在控制台側偵測「降版進行中」並擋下關閉動作？建議 Architect 補充。

下一步：

  • 三方對 v2.1 最終收斂確認（Architect 回看 Design v2.1 是否全部修正到位）
  • 使用者最終審 v2/startup-progress.md 的 6 階段 wireframe + 文案定版
  • 確認後進入開發階段 M8-1 ~ M8-10
  • 所有 v2 文件的決策引用格式：[R5-X] / [R5-D-X] / [R5-E-X] 以便追溯