jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
78 Commits 1 Branch 0 Tags
Commit Graph

78 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
jim800121chen
700b7b08ba chore(stage): 新增 v2 deploy 流程（remote build via DOCKER_HOST） 
v1 (deploy-stage.sh) 走 docker save | gzip | docker load 模式，需要把 81MB
tarball 一次性 POST 到 stage docker daemon /images/load API。5/4 / 5/9 兩次
驗證 VPN 下 docker daemon 對單一大 POST hang（卡 30+ 分鐘 / i/o timeout），
公司網段直連才可靠。

v2 仿 edge-ai-platform/scripts/deploy-docker.sh 改用 DOCKER_HOST=stage
docker build — multi-stage build 完全在 stage daemon 上執行：
- 跨網路只傳 build context（~44 MB streaming，VPN 友善）
- alpine base / nodejs / go mod / pnpm install 都由 stage daemon 自己 pull
- layer cache 留在 stage daemon，後續 incremental build 更快
- 5/9 VPN 下實測 work：first build ~3min、redeploy(layer cache) ~10s

連帶修：
- pnpm-workspace.yaml: 加 onlyBuiltDependencies (sharp / unrs-resolver /
  @tailwindcss/oxide / esbuild) — pnpm 10 預設拒跑依賴 build script、
  乾淨環境第一次 install 撞 ERR_PNPM_IGNORED_BUILDS
- package.json: 加 packageManager: pnpm@10.30.1 — 鎖 pnpm 版本，corepack
  在 stage daemon 第一次跑時不會拉到最新 pnpm 11（行為差異）
- Dockerfile.stage: COPY pnpm-workspace.yaml 進 builder context、否則
  容器內 install 看不到 trust list

v1 (deploy-stage.sh) 保留作為公司網段直連備援；v2 是 VPN / 預設模式。
 2026-05-11 10:35:21 +08:00
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
jim800121chen
7575d4f8ee chore(stage): 補 Phase 0.8 conversion 環境變數設定範例 
- VISIONA_CONVERTER_BASE_URL / VISIONA_FAA_BASE_URL（轉檔服務端點）
- VISIONA_SERVICE_CLIENT_ID / VISIONA_SERVICE_CLIENT_SECRET（service token）
- 對齊 .autoflow/04-architecture/conversion.md §5.3 啟用判定邏輯
 2026-05-04 16:55:17 +08:00
jim800121chen
e02059eff2 feat(visionA-frontend): Phase 0.8 conversion UI — sidebar tab + 6 view + 5 e2e flow tests 
Phase 0.8 對應後端轉檔功能的 frontend UI。完整 state machine（idle / uploading /
queued / running / succeeded / failed / expired）+ XHR upload progress + polling +
half-auto result handling（加到模型庫 / 下載）。

新增 src/app/conversion/（11 元件 + 12 test files，~5,000 行 prod+test，310/310 tests 全綠）：

- page.tsx：state router（mount → bootstrap → 依 store.uiState 切換 view）+ toast on
  store.error（aborted / active_job_exists 不 toast，避免雙重提示）
- IdleForm.tsx + FileDropzone.tsx + ChipSelector.tsx：上傳表單（拖放 + .onnx/.tflite
  format 驗證 + 500MB 大小限制 + KL520/630/720/730 chip 選擇 + ref images ≤100×10MB）
- UploadingView.tsx：XHR upload progress 0-100% + EWMA ETA（alpha=0.3 平滑，<5s 顯示
  「即將完成」避抖動）+ beforeunload warning + AlertDialog 取消
- ProcessingView.tsx：StageIndicator 三段式（解析模型 → 量化編譯 → 編譯 NEF）+
  Progress bar 三模式（queued / determinate / indeterminate）+ tab title `(轉檔中)` 防疊加 +
  409 active_job_exists banner（switchedFromActiveJob flag）
- SuccessView.tsx + PromoteDialog.tsx：兩按鈕（加到模型庫 / 下載）視覺平衡不暗示預設答案 +
  7 天 expires_at 倒數（mount 時 setTimeout 鎖過期那刻 + 60s tick）+ PromoteDialog 單欄位
  name 驗證（≤100 字元 / 無 /\\）+ spinner-during-close 阻擋 + 409 already_imported 特殊
  訊息 + toast.success router.push 跳模型清單
- FailedView.tsx：5 個 known error code 翻譯（UNSUPPORTED_FORMAT / INVALID_CHECKSUM /
  QUANTIZATION_FAILED / MODEL_TOO_LARGE / QUOTA_EXCEEDED）+ unknown fallback +
  3 個建議解決方法 + Job ID 前 8 字元（供回報）+ 「重新開始」
- ExpiredView.tsx：橘色 hero（過期不 alarming）+ source/chip 摘要 + 「重新轉檔」→
  store.reset()

新增 src/stores/conversion-store.ts（Zustand store + 29 tests）：
- 7 個 UI state machine（不允許跳階段）
- recursive setTimeout polling（running 5s / queued 10s / 5xx 指數退避 cap 30s）+
  visibilitychange 暫停/恢復
- 不持久化 jobId（純靠 backend getActiveConversion() lazy rebuild ownership）
- AbortController 防 stale request + 取消上傳
- switchedFromActiveJob flag（409 自動切到既存 job + UI 顯示 banner）
- formDraft（chip / taskName 提到 store，failed→idle 後保留設定，file picker 重選；
  File 物件不能序列化只留 local）

新增 src/lib/api/conversion.ts + types/conversion.ts（5 client 函式 + 22 tests）：
- initConversion：XHR multipart + onUploadProgress + AbortSignal
- getActiveConversion / getConversion / promoteConversionToModels：標準 fetch
- getConversionDownloadURL：純函式，回 `/api/conversion/{job_id}/download` 給 anchor
  download 觸發（server-side 302 → FAA，token 不過 frontend JS）
- ConversionAPIError(status, code, message, requestId?)，code 統一全小寫對齊
  conversion.error.<code> i18n key 命名

新增 src/lib/utils/eta.ts（EWMA 演算法純函式 + 19 tests）：抽出 smoothSpeed /
estimateRemainingSeconds / instantSpeedBytesPerSec / computeEtaUpdate（test 友善）。

新增 src/app/conversion/e2e-conversion-flow.test.tsx（5 e2e flow tests）：
- happy path .onnx + KL720 + 0 ref images（idle → upload → polling → succeeded → 加到模型庫）
- variant 5 ref images
- upload fail → retry（form 設定保留）
- polling 5xx 指數退避 → 恢復繼續
- expired job → ExpiredView → 重新轉檔

修改 sidebar.tsx：左側 nav 新增「轉檔」tab（Wand2 icon，模型庫之後）。
修改 i18n 字典：新增 ~150 個 conversion.* keys（中英雙語對齊）。

PRD §9 14 條功能驗收條件全達成（4 條整合驗收等 stage 部署）。

驗證：pnpm lint / test (310/310) / build 全綠。

對齊文件：
- .autoflow/02-prd/features/feature-converter-integration.md
- .autoflow/03-design/wireframes/wireframe-conversion.md
- .autoflow/03-design/flows/flow-conversion.md
- .autoflow/04-architecture/api/api-conversion.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-04 13:56:54 +08:00
jim800121chen
1231bf0ed2 feat(visionA-backend): Phase 0.8 conversion package — 5 endpoint + 8 個內部模組 
Phase 0.8 把 kneron_model_converter 的轉檔功能整合進 visionA Cloud。
visionA backend 當 streaming proxy（upload）+ delegated download token broker（download）+
ownership trust boundary，converter / FAA / MC 三方零修改。

新增 internal/conversion/ 套件（8 個檔，~10,000 行 prod+test，117+ test cases，race -count=3 全綠）：

- conversion.go：Service interface 5 method、Job/PromoteResult/InitJobInput types
- errors.go：13+ sentinel errors + ErrorCode/HTTPStatus mapping，對齊 conversion.md §6
- mc_token_client.go：service-to-service token (client_credentials grant) + DCL cache
  （exp - 15s 重取，per-scope cache），IssueDelegatedDownload(MC delegated download token)
  錯誤分 idp_misconfigured (4xx) / idp_unavailable (5xx) / download_token_failed / mc_token_unavailable
- converter_client.go：對 converter scheduler 4 method（InitJob multipart streaming /
  GetJob / Promote / ListInProgressJobs），InitJob 不 retry 5xx（streaming body 無法 replay）
- faa_client.go：對 FAA GET /files/{key} server-to-server pull，Phase A retry（GET 無 body
  可 replay）對齊 §9.1 retry 矩陣，streaming io.ReadCloser 透傳避 OOM
- ownership.go：in-memory job_id → user_id map + per-user mutex 防 thundering herd lazy rebuild
  （不同 user 平行 fetch，同 user 100 caller 收斂成 1 次），visionA 重啟靠 converter
  ListInProgressJobs(user) 重建
- flow.go：Service interface 整合層（5 method 串接 converter/FAA/MC/ownership）
  - InitJob 用 io.Pipe + multipart.Reader/Writer 重組 streaming proxy（黑名單 client user_id
    + 灌入 OIDC sub）
  - DownloadRedirectURL 自動觸發 promote（spec §1 Stage 3b），用 ensurePromoted helper
  - PromoteToModels 冪等（modelStore.FindBySourceJobID 為 source-of-truth）
  - OwnershipMismatch → ErrJobNotFound 不 forbidden（§7.2 防枚舉）
  - storage / modelStore 失敗包 ErrStorageUnavailable / ErrModelStoreUnavailable
    （視為 visionA 自身 500 而非 502 gateway，SRE alarm 才打對 team）

新增 internal/api/conversion.go（5 endpoint handler + main.go wire）：
- POST /api/conversion/init（multipart streaming proxy，不呼叫 c.MultipartForm()）
- GET  /api/conversion/active（lazy rebuild ownership）
- GET  /api/conversion/{job_id}（poll status）
- POST /api/conversion/{job_id}/promote-to-models（FAA pull → models 三段式）
- GET  /api/conversion/{job_id}/download（server-side HTTP 302 → FAA，token 不過 frontend
  JS，仿 FAA TestSite DownloadFileDirect pattern；Cache-Control: no-store）

5 個 endpoint 全部走 OIDC AuthMiddleware；user_id 從 cookie session 灌（trust boundary），
從不接受 client multipart form / JSON / query 的 user_id。
TestAllAPIEndpointsRequire401WithoutCookie 自動覆蓋新 5 endpoint regression 防呆。

新增 cmd/api-server/conversion_e2e_test.go（4 個 e2e 場景）：
- TestConversionE2E_StreamingProxy（10MB body + trust boundary regression）
- TestConversionE2E_LazyRebuildAfterRestart（visionA 重啟仍能 /active）
- TestConversionE2E_Download302Redirect（驗 302 + Location header + token 不在 body）
- TestConversionE2E_ActiveJobConflict（409 + active_job 詳情）

修改 internal/config/{config,load}.go：新增 ConversionConfig 5 欄位
（ConverterBaseURL / FAABaseURL / TenantID / ServiceClientID / ServiceClientSecret）+
Enabled() helper（雙非空判定）。
修改 cmd/api-server/main.go：條件 wire（cfg.Conversion.Enabled() 為 true 才建 client + Service；
否則 Deps.Conversion=nil，handler 自動回 501）。
修改 .env.example：新增 Phase 0.8 區塊註解。
新增 cmd/api-server/conversion_adapters.go：narrow interface adapter（接既有
internal/model.Repository / internal/storage.Store → conversion.ModelStore / Storage，避免 import cycle）。

驗證：go test -race -count=3 ./... 17 packages 全綠 / go vet 0 warning / go build 成功。

對齊文件：
- .autoflow/04-architecture/adr/adr-014-conversion-integration.md
- .autoflow/04-architecture/conversion.md (TDD)
- .autoflow/04-architecture/api/api-conversion.md
- .autoflow/02-prd/features/feature-converter-integration.md
- .autoflow/03-design/wireframes/wireframe-conversion.md
- .autoflow/03-design/flows/flow-conversion.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-04 13:56:07 +08:00
jim800121chen
72672972c8 chore(local-agent): 從 git 移除誤 commit 的 wails build binary（10MB Mach-O） 
3f0175f commit local-agent/ 時連帶把 wails build 出的執行檔
local-agent/visiona-agent/visiona-agent（10MB Mach-O 64-bit x86_64）
一起進 git，違反「build artifact 不進 git」原則：

- 可重新產生：source 已在 git，clone 後 wails build 即可
- 平台特定：x86_64 macOS 執行檔對其他平台無用
- repo 變胖：git history 永遠保留這 10MB

修法：
- git rm --cached（保留磁碟上檔案，下次 wails build 還會用）
- local-agent/.gitignore 補 /visiona-agent/visiona-agent 防再犯

注意：3f0175f 的 history 仍含此 binary，徹底清除需 git filter-repo
（local-only repo、未 push、暫不處理）。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 18:29:22 +08:00
jim800121chen
d9d8f03fba chore: visionA Cloud monorepo 根目錄設定（Makefile + README + .gitignore） 
- Makefile：top-level convenience targets（呼叫各子專案的 Makefile）
- README.md：擴充為 monorepo 索引（local-tool / visionA-backend /
  visionA-frontend / local-agent 各組件說明 + dev-with-mc / stage 部署 quickstart）
- .gitignore：
  - .env.dev / .env.dev.generated / .env.stage 排除（dev 與 stage 環境檔不進 git）
  - .autoflow/ 整包 ignore（個人/per-branch 工作目錄；progress.md 與 review 報告
    皆 ignored；共享產品文件已搬到 docs/ 進 git）
  - graphify-out/ 排除

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:22:57 +08:00
jim800121chen
eb66a7287a feat(deploy): visionA Cloud dev / stage docker compose + Caddy/nginx + 部署腳本 
新增雲端版部署設定（Phase 0.6 dev + Phase 0.7 stage 分兩套）：

dev 環境（docker-compose.dev.yml）：
- 5 service all-in-one（postgres + member-center + visionA-backend + frontend + Caddy）
- Caddy 自動 HTTPS for localhost
- .env.dev.example 範本（使用者拷出 .env.dev 後 docker compose up -d）
- Makefile dev-with-mc 9 個 target

stage 環境（docker-compose.stage.yml + docker/Dockerfile.stage）：
- multi-stage build（node22 frontend + go1.26 backend × 2 + nginx-alpine runtime）
  最終 image 319 MB，含 nginx + nodejs + tini + bash
- entrypoint.stage.sh 4 process 共命運（nginx + api-server + remote-proxy +
  next.js standalone）用 wait -n + SIGTERM trap
- nginx.stage.conf：白名單 server_name stage-9527.innovedus.com + 444 default_server
  + /healthz 例外（127.0.0.0/8 only）+ /api/ 與 /storage/ 強制 no-store
  + /tunnel/connect WS upgrade + 100M body / 3600s timeout
- 對外 mapping 0.0.0.0:9527:80（公司 host nginx 在外層處理 HTTPS termination
  — Let's Encrypt stage-9527.innovedus.com 自動續簽）
- named volume visiona-data（不用 bind mount，因 stage docker daemon 在 host root
  無 mkdir 權限）

部署腳本（scripts/deploy-stage.sh）：
- 仿 edge-ai-platform/scripts/deploy-docker.sh 早期 save/load 模式
- 為什麼不用 internal registry：公司 192.168.0.130:5000 開了 auth、無帳密
- 流程：buildx --load → docker save | gzip → DOCKER_HOST docker load → compose up
- 含 --rollback &lt;tag&gt; / --skip-build / --no-push / --skip-deploy 選項
- timestamp + git SHA tag 留 rollback 餘地

文件（docs/）：
- DEV-SETUP.md：dev 環境一鍵起步驟
- SMOKE-TEST.md：手動煙測 checklist（OIDC flow / pairing / tunnel）
- STAGE-DEPLOY.md：stage 完整手冊（架構圖 / 環境前置 / 部署 step / rollback /
  7 種故障排除 / 緊急救回 POC）

.env.stage.example 對齊 backend A1 改造：
- VISIONA_OIDC_CLIENT_SECRET 留空（PKCE-only public client）
- VISIONA_OIDC_SERVICE_CLIENT_ID/_SECRET 留空（Phase 1 預留鉤子）
- 所有 secret 用 placeholder（CHANGE_ME_OPENSSL_RAND_HEX_32）

.dockerignore：避免 node_modules / .next / .git 等進 build context

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:22:44 +08:00
jim800121chen
3f0175f1a9 feat(local-agent): Phase 0.5 visionA Agent — Wails 桌面 + tunnel client + 配對 UI 
從 local-tool 複製出獨立的「visionA Agent」桌面應用（A3 純橋樑：
tunnel client + 配對 UI + 設定，不開 HTTP port、不做本機裝置/推論 UI）。
Bundle ID 與 local-tool 不同（com.innovedus.visiona-agent vs visiona-local），
雙 app 可共存。fork 後不主動 sync，需要時手動 cherry-pick。

Backend / Wails Go（AB1-AB13）：
- internal/tunnel：6 狀態機（Idle/Connecting/Connected/Reconnecting/Failed/Stopped）
  + Pair/Unpair/Reconnect/Disconnect binding + ClientHooks event
- internal/auth：encrypted file token store（AES-GCM + scrypt + machineID
  fallback salt + 13 tests）
- internal/config：YAML validation + atomic write + 11 tests
- internal/log：ring buffer + ExportLog 升級 zip
- visionA-backend /api/pairing/exchange：SessionTokenStore + 17 new tests
- 三平台 build 驗證（macOS DMG 160 MB / Windows EXE / Linux AppImage）
- end-to-end 5 milestone 全綠（pairing → tunnel → forward → reuse 防護
  → tunnel drop failover）

Frontend / Next.js（AF1-AF7，沿用 visionA-frontend 基礎）：
- AppShell + Header + TabNav（StatusView / PairView / SettingsView 三 tab）
- ConnectionStatusBadge 5 種狀態
- TokenInput regex 驗證 + 7 種錯誤 + 0.5s auto-switch 到狀態頁
- 設定頁 4 區塊（含重新配對 AlertDialog）
- agent-api.ts 封裝 Wails bindings（mock/real 雙實作）+ 90 tests

Phase 0.7 review-driven fix（Round 2）：
- A1 Session fixation 防護（RotateSessionID）
- A3 mock pairing 預設改 false（必須明確 opt-in）+ startup log
- A4 Pair 失敗後 state 清理矩陣（exchange/Save/Start fail 各自終態）
- A5 Pair/Unpair/Reconnect lifecycleMu + 50 goroutine race test
- F1 重新配對次按鈕 / F2 PairView Esc cancel / F3 Wails BrowserOpenURL
  / F4 Settings draft 持久 + 未儲存 badge

驗證：agent backend go test -race -count=3 ./... 4 packages 全綠 /
agent frontend pnpm test 119 tests 全綠

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:22:01 +08:00
jim800121chen
99dea42239 feat(visionA-frontend): Phase 0 → 0.7 雲端前端（Next.js + OIDC redirect 流程） 
visionA 雲端版前端 — 沿用 local-tool 既有 UI（原則 4：先抄 local-tool）+
新增雲端特有的登入 / 配對 / 設定流程，含以下整合階段：

- Phase 0：13 頁 + 30+ 元件 + 雛形 banner
  - dashboard / devices / models / workspace / clusters / settings 等頁
  - AppShell + Sidebar + Header + tokens + i18n（中英雙語 96 keys）
  - API client + 5 stores + 3 hooks
- Phase 0.6：OIDC redirect 改造
  - login 頁改為 OIDC redirect（`window.location.href = /api/auth/login`）
  - register 改說明頁、account 改唯讀（user 資料來源是 MC）
  - api client 改 cookie session（credentials: include）+ 完全清掉 localStorage
- Phase 0.7：stage 部署 + nil guard
  - getApiBaseUrl() 修：browser 環境視為 same-origin（與 login 頁一致）
  - login 頁加「已登入 → router.replace('/')」effect
  - User type email/name 改 optional（MC id_token 不一定回 email/name claim）
  - header.tsx UserMenu displayName 4 層 fallback：name → email → id → i18n
  - 雛形 banner 文案更新（已接 Innovedus 帳號中心）+ 版號 Phase 0.7

驗證：pnpm lint / test (125/125) / build 全綠

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:21:36 +08:00
jim800121chen
22f0837ba8 feat(visionA-backend): Phase 0 → 0.7 雲端後端（雙 binary + OIDC BFF + stage 部署） 
從 edge-ai-platform POC 轉為正式產品的雲端後端，含以下整合階段：

- Phase 0：雛形骨架 — `cmd/api-server` (REST :3721) + `cmd/remote-proxy`
  (tunnel :3800 / internal :3801) 雙 binary 共用 internal/，沿用 POC 的
  WebSocket+yamux tunnel 協定但解耦 relay 與 API
- Phase 0.6：OIDC BFF 接 Innovedus Member Center
  - internal/oidc package（coreos/go-oidc + PKCE S256 + state + nonce）
  - internal/usersession package（HMAC-SHA256 cookie + RotateSessionID
    防 session fixation, OWASP ASVS V3.2.1）
  - 4 個 OIDC handler（/api/auth/login｜callback｜me｜logout）+ AuthMiddleware
  - 完全拔除 StaticAuthProvider，OIDC 是唯一認證路徑
  - 9 個 ADR（含 ADR-010 BFF / ADR-011 取代 static auth /
    ADR-012 pending session shared cookie / ADR-013 PKCE-only public client）
- Phase 0.7：A1 改造 + security audit 修復
  - OIDC ClientSecret 變選填，支援 stage MC 的 public PKCE-only client
    （AuthStyleInParams 強制 token endpoint 不送 client_secret）
  - 預留 ServiceClient* 欄位給未來 client_credentials grant
  - 移除 13+ 處 resolveUserID(uc, StaticUserID) fallback 改 strict mode
    （Audit C1：multi-tenant 隔離破口）
  - Pairing exchange MarkUsed 失敗 abort + revoke session token（Audit M3）
  - 新增 all_endpoints_require_auth_test 整合測試（51 endpoint × 401）

驗證：go test -race -count=3 ./... 17 packages 全綠 / go vet 0 warning

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:21:20 +08:00
jim800121chen
b71ff4cd3c perf(local-tool): Windows KL520 cold-boot connect 106s → ~40s（跳過多餘 reset） 
背景：
Windows 實測 KL520 首次 connect 耗時 106 秒，原因是 reset 流程內部重複
firmware load：
  1. 進來 Loader → load firmware (35s) → Comp/U
  2. reset 退回 Loader → bridge 重啟
  3. reconnect 進來又是 Loader → load firmware (30s) → Comp/U
  4. Loader reconnect 第一次常 fail（15s timeout）
總共 ~65s 花在「砍掉剛載好的 firmware、再載一次」的白工上。

根因：先前修的 needsReset 邏輯不管 firmware 新舊一律 reset。但 Error 15
只發生在「Comp/U 是上次 session 殘留」的情境；「本次 connect 內部剛載的
Comp/U」session 是乾淨的，不需要 reset。

修法（條件性 reset）：
- server/scripts/kneron_bridge.py：connect handler 新增追蹤本次有無走
  firmware load flow，return 多帶 `fresh_firmware_loaded` bool
- server/internal/driver/kneron/kl720_driver.go：Connect 讀 flag，若為
  true 就 skipReset（firmware 剛載的，session 已乾淨）

驗證（2026-04-21）：
- `/tmp/test_bridge.py` 拔插 USB 後跑 `connect (fw=Loader) →
  fresh_firmware_loaded=True → skip reset → load_model → inference`
  → 11 detections（person×8, tie×3, latency 332ms）
- Mac UI Comp/U 殘留路徑：reset → 11 bbox ✓
- Mac UI Loader cold-boot 路徑（拔插後）：skip reset → 11 bbox ✓

預期效益：
- Windows cold-boot（常見）：106s → ~40s（省 65s）
- Mac 跨 session（常見）：~15-20s 不變
- 極少數（Windows device 未斷電但跨 server session）：走完整 reset

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 11:09:25 +08:00
jim800121chen
30d0ff5695 fix(local-tool): 推論 bbox 標註不顯示 — 前端 canvas 尺寸 + KL520 reset + 延長 timeout 
症狀：Mac 版上傳單張圖推論，畫面完全沒有 bbox 標註。實測追根因後發現
兩層獨立問題疊加（前端 + 後端），擇一修復都無法解決。

## Layer 1: 前端 canvas 尺寸對不上 img 顯示尺寸
- camera-inference-view.tsx renderedSize 初始值硬寫 {w:640, h:480}
- ResizeObserver 理應在 <img> load 後 fire，但實測沒 fire 或時機不對
- 結果 overlay canvas 永遠用 640×480 畫，bbox 嚴重偏位或跑出 canvas

修法（camera-feed.tsx + camera-inference-view.tsx）：
- <img> 加 onLoad handler，decode 完立刻用 getBoundingClientRect 回報
- ResizeObserver effect 進來先檢查 img.complete && naturalWidth > 0，
  是就立刻 report（cover HMR / cached image）
- effect 依賴加 streamUrl / batchImageUrl，換圖會重觀察
- renderedSize 初始值改 null，overlay 改為拿到真實尺寸才 render
- setState callback 用 prev 比對，同尺寸不觸發 render
- camera-overlay.tsx 加 [bbox-debug] console.log 保留（debug 成本低，
  對未來排查有幫助）

## Layer 2: KL520 推論炸 ApiKPException Error 15
- kp.inference.generic_image_inference_send 回 SEND_DATA_TOO_LARGE
- 試過 image 尺寸（516×640 / 640×794 / 640×640 host pad）、numpy vs
  bytes、明確傳 width/height — 全部炸
- Python bridge 直接測試（/tmp/test_bridge.py）做完整
  `connect → reset → reconnect → load_model → inference` 序列 → 11 個
  detection 正常回傳
- Go driver 走 `connect → load_model → inference` 跳過 reset

根因：commit ddf0eb8（2026-04-16）「KL520 首次 connect 跳過 reset」當時
為解 Windows 60s HTTP timeout 的優化。但副作用：KL520 若 session 間
firmware 殘留（fw=KDP2 Comp/U），直接 load_model + inference 100% 炸
Error 15。必須走完整 reset → 退回 Loader → 重新載 firmware → Comp/U
流程才能得到能 inference 的 session。

修法（kl720_driver.go）：
- 移除「KL520 跳過 reset」特例，讓 KL520 和 KL720 都走 needsReset → restartBridge
- 註解記錄 trade-off：KL520 connect 時間 ~2s → ~15-20s（macOS），
  Windows 可能 60s+

## HTTP timeout 配套調整
- device_handler.go ConnectDevice timeout 60s → 120s
- Windows worst-case（~65s：Loader reconnect 16s + firmware load 31s +
  reboot 8s + reconnect 5s）留 buffer，避免 504 CONNECT_TIMEOUT

## Bridge 清理
- kneron_bridge.py 清掉中途試驗遺留的 `_host_preproc` 死碼
  （還原成原版 _correct_bbox_for_letterbox）
- 加了 debug log（Inference: sending / parse done / EXCEPTION with
  traceback）保留，未來排查 inference 路徑很有用

## 驗證（function 層）
/tmp/test_bridge.py 三種尺寸全通過：
- 516×640 直式 → 11 detections (person×8, tie×3) latency 308ms
- 1920×1080 横式 → 0 detections（合成圖，正常）
- 512×512 正方 → 0 detections

## 待使用者驗證
- Mac UI 實測：上傳 ~/Downloads/000000000459.jpg 應見 11 個 bbox 精準框住
- Windows 實測 connect 耗時 + timeout 是否足夠
- Linux 實測

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 01:12:10 +08:00
jim800121chen
c1d2e2ddaa feat(local-tool): macOS DMG 美化（create-dmg 背景圖 + Applications 捷徑） 
需求：Mac 端 installer 體驗類比 Windows .exe — 進 DMG 就看到漂亮的視窗
背景 + 拖到 Applications 的視覺引導。

實作：
- installer/macos/ 新資料夾
  - make-dmg-background.py：動態生成 640×400 深色背景，配色對齊 Wails
    控制台 splash（#111827→#0B0F19 漸層 + #38BDF8 accent）
  - background.png + background@2x.png（1x + 2x Retina）
- Makefile dmg 拆三 target：
  - dmg：auto-detect，有 create-dmg 走 fancy，沒有 fallback plain（CI 無痛）
  - dmg-fancy：強制美化版（需 `brew install create-dmg`）
  - dmg-plain：原 hdiutil UDZO（保留為 fallback）
- Windows / Linux 流程零改動

驗證：
- `make dmg-fancy` 產出 157MB DMG，mount 後內容：app + Applications 捷徑
  + .background/background.png + .DS_Store（視窗樣式）
- `hdiutil verify` 通過

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 01:11:22 +08:00
jim800121chen
d0b33f8c71 fix(local-tool): macOS 掃不到 Kneron 裝置 — PythonModeAuto 先 bundled 
症狀：Mac 版 app 啟動後，前端顯示沒有裝置（實際 KL520 透過 USB 連上）。

根因：
PythonModeAuto 原本「先 system 後 bundled」，但系統 python3 通常沒裝
KneronPLUS wheel → `import kp` 失敗 → HAS_KP=False → bridge 降級 pyusb →
pyusb 找不到 libusb → scan 空陣列。表面看起來啟動成功但 detector 是空的。

修法：
- visiona-local/app.go PythonModeAuto 語意翻轉 → 先 bundled（已預裝 kp wheel），
  失敗才 fallback system。Local-tool 架構就是整包內嵌 Python + wheels，
  系統 python 不會裝 kp，不該優先。
- server/scripts/kneron_bridge.py 在 `import kp` 前新增
  `_preload_kneron_dylibs_macos()` — 用 ctypes.CDLL 絕對路徑預載 wheel 內
  `kp/lib/libusb-1.0.0.dylib` + `libkplus.dylib`，避開 macOS hardened
  runtime 剝掉 DYLD_LIBRARY_PATH 的風險。Windows/Linux 守門不執行。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 01:10:59 +08:00
jim800121chen
b76acbe227 fix(local-tool): build-appimage.sh wheel 檢查改用 grep -i 不分大小寫 
上一輪誤把關鍵字寫成 'kp'，但 wheel 檔名是 'KneronPLUS-2.0.0-*.whl'，
shell glob *kp*.whl 匹配不到，導致即使 wheel 實際存在仍 exit 1。

改用 ls | grep -i 不分大小寫比對「KneronPLUS」，同時更正錯誤訊息
從「kp wheel」改為「KneronPLUS wheel」。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-18 23:40:17 +08:00
jim800121chen
6c21beb7b6 fix(local-tool): Linux AppImage bundled Python + udev 單次密碼 
Linux AppImage 掃不到 Kneron 裝置的根因是 Wails app 端三個 locator
完全沒讀 AppRun 已 export 的 VISIONA_BUNDLE_LIB_DIR，導致：

- locateBundleDataDir 找不到 models.json → seed user data dir 失敗
- locateBundledPythonAssets 找不到 python tarball + wheels
  → ensurePythonRuntime(Auto) fallback 到 system Python
  → system Python 缺 numpy / kp / pyusb → bridge scan silent fail
  → "No Kneron devices detected"

修復：

1. 三個 locator 優先讀 VISIONA_BUNDLE_LIB_DIR / VISIONA_BUNDLE_BIN_DIR
   （AppRun 已 export），AppImage 佈局 usr/lib/visiona-local/{data,python,wheels}
   一次到位

2. AppRun 加 VISIONA_PYTHON_MODE=bundled — Linux AppImage 強制走內嵌
   Python，避免 system Python 環境差異（符合 R4「完全離線內嵌」決策）

3. InstallUdevRule 合併 pkexec：cp + reload-rules + trigger 用
   pkexec sh -c 一次提權，使用者只需輸入 1 次密碼（原本 3 次）

4. build-appimage.sh 加硬檢查：
   - python tarball 缺失 → 自動 make vendor-python-linux，仍缺就 exit 1
   - wheels 數量 < 4 → 自動 make vendor-wheels-linux，仍不足就 exit 1
   - 驗證關鍵 wheel（numpy / opencv / pyusb / kp）存在，少任一 exit 1

5. Makefile payload-linux 同步加硬檢查（python tarball 必存在，
   wheels ≥ 4 個）

6. 參照 edge-ai-platform POC 補齊 visiona-local/wheels/linux/ 的
   KneronPLUS-2.0.0-py3-none-any.whl（POC 已驗過可用）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-18 23:15:52 +08:00
jim800121chen
4e3dc3e504 fix(local-tool): Linux udev rule 自動偵測安裝 + pkexec FUSE 修復 
兩個修復：

1. pkexec cp 失敗：AppImage 的 FUSE mount（/tmp/.mount_vision*）有特殊
   權限，pkexec 提權後的 root process 無法讀取 user mount 的 FUSE 檔案。
   修法：先用 os.ReadFile 把 rule 讀到 /tmp/visiona-local-99-kneron.rules
   （普通使用者權限可寫 /tmp），再 pkexec cp 從 /tmp 到 /etc/udev/rules.d/。
   同時修 server API endpoint 和 Wails 啟動流程兩處。

2. 啟動流程自動偵測 udev：Stage 4 probeDeviceListAndComplete 解析
   /api/devices response 的 udevHint 欄位。Linux + 0 裝置 + udevHint=true
   → 自動找 bundle 裡的 99-kneron.rules → 複製到 /tmp → pkexec cp 安裝
   到 /etc/udev/rules.d/ → reload udev。會彈 Linux 圖形化密碼框，使用者
   輸入密碼即完成。取消密碼不阻擋啟動流程（log 記錄跳過）。

   Wails 控制台 Stage 4 會顯示細步文案：「偵測到 USB 權限未設定，正在
   安裝（請在密碼視窗輸入密碼）...」

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-17 00:02:37 +08:00
jim800121chen
372259b4b1 fix(local-tool): 載入模型 dialog 點灰色區域不再關閉 
使用者回報點 dialog 周圍灰色 overlay 會誤關 popup。

修法：flash-dialog 的 DialogContent 加：
- onInteractOutside: 永遠 preventDefault（灰色區域點擊不關）
- onEscapeKeyDown: 載入中 preventDefault（載入完成後可 Esc 關）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 23:43:34 +08:00
jim800121chen
db272cac5a feat(local-tool): Linux udev rule 未安裝偵測 + 一鍵安裝 UX 
使用者在 Ubuntu 上 scan 不到 Kneron 裝置。根因：Linux 預設 USB 裝置
權限是 root only，非 root 使用者的 kp.core.scan_devices 因 permission
denied 而 silently 回傳 0 裝置。需要安裝 udev rule。

修法三層：
1. Server：GET/POST /api/devices 在 Linux + 0 裝置 + udev rule 不存在
   時帶 udevHint: true
2. 新增 POST /api/system/install-udev：用 pkexec 提權安裝 99-kneron.rules
   + reload udev（彈 Linux 圖形化密碼對話框）
3. 前端 devices page：udevHint=true 時顯示 amber 色 banner 提示 +
   一鍵安裝按鈕，成功後自動 rescan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 23:20:28 +08:00
jim800121chen
ddf0eb8147 fix(local-tool): KL520 首次 connect 跳過不必要的 device reset 
使用者 Windows 上 connect KL520 耗時 60+ 秒且前端收到 504 timeout。

根因分析（從 log 逐行推斷）：
  1. server 啟動後首次 connect → needsReset=true → restartBridge()
  2. reset 送出 → KL520 reboot → 退回 KDP2 Loader 模式（USB Boot 裝置，
     reset = firmware 從 RAM 清掉）
  3. USB 重新枚舉 8 秒 → 新 bridge process → 嘗試 reconnect
  4. Loader 模式的 connect_devices_without_check 不穩定 → attempt 1 fail
     (16 秒 timeout) → attempt 2 成功 (4 秒)
  5. 載 firmware fw_scpu.bin → 31 秒
  6. firmware loaded → 再次 reboot → 5 秒後 reconnect
  7. 總時：8 + 16 + 4 + 31 + 5 = 64 秒 > 前端 60 秒 HTTP timeout → 504

但 KL520 是 USB Boot 裝置，每次斷電 firmware + model 就會清掉，connect
時本來就是 clean state。server 啟動後主動 reset 是多餘的——它把完整
firmware 砍掉再重載一次，浪費 60 秒且 Loader 模式 connect 不穩定。

這個 reset 邏輯最初是為 KL720 設計的：KL720 是 flash-based 裝置，
firmware 和 model 保留在 flash，reset 清 stale model 才有意義。

修法：needsReset 條件加上 chipType == "KL720"。KL520 跳過 reset，
直接使用已有的 firmware。如果 KL520 真的有殘留 model 要清（理論上
不會因為它是 RAM-based），下次 load_model 前的 restartBridge 會處理。

修復後 KL520 connect 預期時間：2-5 秒（一次 connect + set_timeout）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 22:49:01 +08:00
jim800121chen
abbe9d4c0b fix(local-tool): DeviceGroup.__del__ access violation 全面修復 
上一個 commit (a6a121a) 只修了 script 結束時的 cleanup，但使用者仍在
connect 重試路徑看到 access violation：

  connect attempt 1 failed → 新 connect attempt 2 → GC 回收 attempt 1
  的舊 DeviceGroup → __del__ → kp_disconnect_devices 對已失效的 native
  handle → OSError: access violation

根因：`_device_group = None` 只是清掉 Python reference，舊物件的 __del__
會延遲到下一次 GC cycle（可能發生在新 connect call 的 allocation 時），
此時 native handle 已 invalid。

修法：
- 新增 `_clear_device_group()` helper：先 kp.core.disconnect_devices 把
  native handle 正常釋放（errors silenced），再設 None
- 全檔搜 `_device_group = None` 共 12 處，除了初始宣告（L40）和兩個 helper
  自身（_clear_device_group / _cleanup）以外全部替換為 _clear_device_group()
- 涵蓋所有 code path：connect retry / firmware load reconnect / disconnect
  handler / reset handler / error fallback

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 17:20:12 +08:00
jim800121chen
a6a121ae86 fix(local-tool): suppress KneronPLUS DeviceGroup.__del__ access violation 
Windows 上 bridge script 結束時 Python GC 呼叫 DeviceGroup.__del__ →
kp_disconnect_devices 對已釋放的 native handle 操作 → OSError: access
violation reading 0x00...0C。這是 KneronPLUS SDK 的 destructor 沒做
null check 的已知問題，不影響功能但會印嚇人的 stack trace 到 stderr。

修法：
- 新增 _cleanup() 函式：明確 kp.core.disconnect_devices + 把
  _device_group 設 None（讓 __del__ 成 no-op）
- atexit.register(_cleanup) 確保 interpreter 關閉前 cleanup
- main() return 後也同步呼叫一次（belt-and-suspenders）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:40:30 +08:00
jim800121chen
14d5a0ed2f docs(local-tool): Build 指引 → Installer Build 指引 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:04:38 +08:00
jim800121chen
041d872fa0 docs(local-tool): 移除 M8 重構變更紀錄 section 
使用者不需要在功能文件中看到 commit changelog。章節重新編號 6-8。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:02:56 +08:00
jim800121chen
4f9a193782 chore(local-tool): 移除模型 FPS/latency/accuracy 預估值 
使用者要求拿掉 FPS 預估數字（未經實測，不準確）。

- docs/LOCAL-TOOL-SPEC.md: 模型表格移除 FPS 欄位
- server/data/models.json: 7 個模型全部移除 fps / latencyMs / accuracy 欄位

前端 model-detail / model-card 有讀這些欄位的 UI，移除後會顯示 — 或不顯示
該列，不需要額外前端改動（已有 null/undefined fallback）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:01:25 +08:00
jim800121chen
61f9b8bf6b docs(local-tool): 功能規格文件 LOCAL-TOOL-SPEC.md 
涵蓋：
- 概述（三平台 + 完全離線安裝）
- Wails 控制台（5 階段啟動進度、timeout 機制、控制台功能、single-instance）
- Web UI（頁面路由、推論來源、結果顯示、模型管理、裝置管理、離線覆蓋層）
- 預設模型清單（KL520 × 4 + KL720 × 3）
- 內嵌依賴（Python/numpy/opencv/KneronPLUS/ffmpeg LGPL）
- Server API 摘要（系統/模型/裝置/媒體/WebSocket）
- M8 重構變更紀錄（15 個 commit 的完整 changelog）
- 資料目錄結構（三平台路徑 + 檔案說明）
- Build 指引（macOS/Windows/Linux）
- 除錯指引（Windows 啟動問題 + 常見問題）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 14:46:09 +08:00
jim800121chen
9793a2efc1 chore(local-tool): models.json 只保留有實體 .nef 的 7 個預設模型 
使用者要求：前端模型庫只保留有適配裝置的模型（KL520 4 個 + KL720 3 個）。

原本 models.json 有 15 筆：
  - 8 筆 ONNX framework 的 demo 模型（yolov5-face-detection /
    imagenet-classification / person-detection / vehicle-classification /
    hand-gesture-recognition / coco-object-detection / face-mask-detection /
    license-plate-detection）— 都沒有實體 .nef 檔，是 placeholder metadata
  - 7 筆 NEF framework 的實體模型（每個都有 filePath 指向 data/nef/）

現在只保留 7 筆實體模型：
  KL520（4 個）：
    - kl520-yolov5-detection (yolov5 no-upsample 640x640)
    - kl520-fcos-detection (fcos-drk53s 512x512)
    - kl520-ssd-face-detection (ssd_fd_lm 320x240)
    - kl520-tiny-yolov3 (tiny_yolo_v3 416x416)
  KL720（3 個）：
    - kl720-yolov5-detection (yolov5 no-upsample 640x640)
    - kl720-resnet18-classification (resnet18 224x224)
    - kl720-fcos-detection (fcos-drk53s 512x512)

server/data/models.json 是 runtime 讀取，三平台（macOS/Windows/Linux）
共用同一份，改一次三平台全部生效。

驗證：
- python3 json.load 解析正常，7 筆 entries
- 每筆 filePath 指向的 .nef 實體檔都存在於 server/data/nef/{kl520,kl720}/
- 檔案大小：1-13 MB，合計 ~64 MB
- macOS dmg 重 build 163MB OK
- Bundle 內 Contents/Resources/data/models.json 更新為 7 筆

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:44:16 +08:00
jim800121chen
ad9beab0ca fix(local-tool): Restart / StopServer+StartServer 後前端 5 階段 UI 不更新 
使用者在 Windows 版 local tool 按「重新啟動伺服器」或 Stop 再 Start 後，
畫面中間的 5 階段面板停留在「等待中」不更新，但實際上 server 已經
成功啟動完成。

根因：
  Restart / StartServer 路徑 → ctrl.Restart() / ctrl.Start() →
  ctrl.startInternal() → startServerV2()

  但 StartupPipeline 已經 markReady (current=7)，所以 startServerV2 內
  所有 CompleteStage(2/3/4) / EmitStageDetail / IsInColdStart 檢查都
  early return 或 no-op，Go 端完全不 emit 任何 startup:progress event。
  前端 resetStartupPanel 後開始等事件，但事件根本沒來 → UI 停留在
  pending「等待中」。

  RestartStartupSequence（Retry 按鈕）有自己完整重建 pipeline 的 5 步
  邏輯，所以 Retry 路徑沒事。但 Restart / Stop+Start 走的是 ctrl.Restart
  / ctrl.Start 不走 RestartStartupSequence。

修法：

1. 抽 helper rebuildStartupPipeline() — 把 RestartStartupSequence 裡
   「重建 pipeline + emit Stage 1 completed + 啟 watcher + 前進 Stage 2」
   那 20 多行邏輯抽出來，讓 startInternal 也能呼叫。

2. startInternal 進場時偵測 pipeline 狀態：
   - cold start 路徑 (current ∈ [1..6]) → 不動
   - 已 ready (current > totalStages) 或 已 failed (current == -1)
     → 清 sentinel file + 呼叫 rebuildStartupPipeline()，記 didRebuild=true

3. startInternal 成功返回前，Stage 5 openBrowser 處理改成三分支：
   - didRebuild=true → 呼叫 runStartupStage5（Restart 路徑）
   - cold start (IsInColdStart && !didRebuild) → skip 由上層呼叫
     runStartupStage5（app.startup 冷啟動路徑或 RestartStartupSequence）
   - fallback (pipeline == nil) → 自己 openBrowser 一次

四條路徑的分流現在完整：

  (A) cold start           : app.startup → Pipeline.Start 自己前進到 2 →
                             startInternal 看 current=2 不 rebuild →
                             didRebuild=false → app.startup 呼叫 stage5
  (B) Restart / Stop+Start : ctrl.Restart/Start → startInternal 看
                             current=7 rebuild → didRebuild=true →
                             startInternal 自己呼叫 stage5
  (C) RestartStartupSequence: 自己 rebuild 前進到 2 → ctrl.Start →
                             startInternal 看 current=2 不 rebuild →
                             didRebuild=false → RestartStartupSequence
                             後續呼叫 stage5
  (D) pipeline == nil       : 走舊 fallback 自己 openBrowser

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- 關鍵 test TestRestartStartupSequence_ColdStartOpenBrowser_OnlyOnce
  仍 pass（驗證 browser 不會被 cold start 開兩次）
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:19:33 +08:00
jim800121chen
485a2e01ff fix(local-tool): bootstrap-linux.sh 自動安裝 appimagetool 
使用者在 Linux build 時遇到「appimagetool 未安裝」錯誤（wails binary
已產出 9.3M，但打包 AppImage 失敗）。原本 bootstrap-linux.sh 只裝 Go /
Node / Wails CLI，沒裝 appimagetool，build-appimage.sh 到打包步驟才
fail。

修法：

1. bootstrap-linux.sh 新增 [5/6] 步驟自動下載 + 安裝 appimagetool
   - 從 AppImage/appimagetool 官方 continuous release 拉
     appimagetool-x86_64.AppImage
   - chmod +x + sudo mv 到 /usr/local/bin/appimagetool
   - 已安裝則跳過

2. build-appimage.sh 的 appimagetool not found 錯誤訊息更新
   - 提供一鍵安裝 curl 指令（不需重跑整個 bootstrap）
   - 提示可重跑 bootstrap-linux.sh 一併補所有依賴
   - 舊訊息裡的 URL 指向已 archived 的 AppImageKit repo，換成
     AppImage/appimagetool（新 repo 位置）

使用者立即可用（不想重跑 bootstrap）:
  curl -fsSL https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage \\
    -o /tmp/appimagetool && chmod +x /tmp/appimagetool && sudo mv /tmp/appimagetool /usr/local/bin/appimagetool
  make appimage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:11:49 +08:00
jim800121chen
fbd585ab73 fix(local-tool): Linux build 支援 webkit2gtk-4.1（Ubuntu 22.10+ / Debian 12+） 
使用者在 Linux build 看到：
  pkg-config --cflags ... webkit2gtk-4.0
  Package 'webkit2gtk-4.0' not found

根因：Wails v2.11 預設 cgo pkg-config 指定 webkit2gtk-4.0，但 Ubuntu
22.10 之後的版本已經把系統 package 從 webkit2gtk-4.0 改名為 4.1
（API 大致相容）。使用者 bootstrap 裝的是 libwebkit2gtk-4.1-dev，
pkg-config 找不到 4.0.pc 就 fail。

修法：

1. Makefile wails-linux target 自動偵測 webkit2gtk 版本
   - 優先 pkg-config --exists webkit2gtk-4.1 → wails build -tags webkit2_41
     （Wails v2.10+ 支援的 build tag，切換到 4.1 的 cgo 宣告）
   - 退回 pkg-config --exists webkit2gtk-4.0 → wails build 預設
   - 兩者都沒有 → 清楚錯誤訊息 + 建議安裝指令

2. scripts/bootstrap-linux.sh 裝 webkit2gtk dev package 時也做版本偵測
   - apt-cache show 優先查 4.1，退回 4.0
   - Ubuntu 22.04 及之前 repo 有 4.0；22.10+ / 24.04 repo 只有 4.1
   - 兩個都試過才 err

驗證：
- make -n wails-linux dry-run 正常 parse
- bash -n scripts/bootstrap-linux.sh 語法 OK
- macOS 端 make dmg 仍 work（未改 darwin target）

使用者待做：Linux 端 git pull 拉新版 → 重跑 bootstrap-linux.sh
（確保 webkit2gtk-4.1-dev 安裝）→ make appimage。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 04:11:53 +08:00
jim800121chen
f5655e38b1 feat(local-tool): hard timeout 5min + Stage 6 隱藏到 header + 全屏 splash 
回應使用者三項需求：

1. 整體 hard timeout 180s → 300s（5 分鐘）
   每個 stage 已有 soft timeout 20s 提示機制，整體 budget 不需緊湊。
   5 分鐘是「使用者點完一杯咖啡都還沒好」的心理上限。pause 機制
   （Stage 1 seed / Stage 2 Python bootstrap / Stage 3 waitHealthy）
   仍維持作為「一次性 bootstrap 完全不算 budget」的快速通道。
   - 同步更新 i18n 紅 banner 文案 180 → 5 分鐘
   - 同步更新 unit tests（HardTimeout 用 -305s，SkipBypass 用 -320s，
     PreventsHardTimeout 註解 effective<300s）

2. Stage 6「等待 Web UI 連線」從 6 階段面板隱藏到 header 連線指示燈
   Go 端 pipeline 仍保持 6 階段（不動），前端 UI 只顯示 5 階段：
   - startup-panel.js: TOTAL_STAGES=5 顯示用，PIPELINE_STAGES=6 內部
     state 用。renderStages / paintProgressBar / 進度數字都用 5。
   - updateStage 仍會收 stage 6 events 更新內部 state（控 collapse 時機）
     但 stage 6 不 paint UI（n > TOTAL_STAGES early return）
   - 新增 onConnectionStatusChange listener 機制：stage 6 status 變化
     時通知外層
   - control-panel.js: setWebUIStatus 把連線狀態 (pending/running/
     completed/failed) 渲染到 header 的 meta-webui 指示燈：圓點顏色
     + 文字 (等待連線/已連線/未連線)
   - index.html: server-meta 新增 <dd id="meta-webui"> 指示燈位置
   - i18n: control.meta.webui / control.webui.{connected,waiting,disconnected}
   - style.css: .webui-status::before 圓點 + pulse 動畫 + 顏色對應
     state (pending=灰 / running=warning+pulse / connected=success / failed=destructive)
   - app.js: 註冊 onConnectionStatusChange listener，初始化呼叫
     setWebUIStatus('pending')

3. 全屏 spinner splash 取代「啟動中...」三個字
   原本 app 啟動最一開始的「啟動中」狀態只有 header 上三個字很不
   明顯，使用者體感像沒反應。改為 DOM ready 時就顯示 fullscreen
   spinner overlay，收到第一個 startup:progress event 才隱藏。
   - index.html: <div id="boot-splash"> 內含 logo + spinner-lg + 文字
   - style.css: .boot-splash position:fixed inset:0 z-index:1000，
     .boot-splash.hidden { display:none } 用 class 控制（避免和
     [hidden]!important 衝突）
   - app.js: hideBootSplash() helper，4 個 hide 觸發點：
     (a) 收到 startup:progress event
     (b) snapshot 補漏發現 pipeline 已啟動
     (c) 收到 startup:error event（即使失敗也要看到錯誤）
     (d) handleServerStatus 收到非 idle 狀態（restart wails app
         server 還活著的情境）

更新 fix marker 為「d946561+ (5min hard timeout + 5-stage UI + fullscreen splash)」

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 01:23:55 +08:00
jim800121chen
d946561362 fix(local-tool): Stage 順序亂跳修復 + 移除秒數顯示 
兩個問題一次修：

1. Stage 順序亂跳 — 「Stage 1 等待中、Stage 2 完成、Stage 3 進行中」
   根因：Wails Webview JS load 需 1-3 秒（Windows 乾淨環境更慢），這段
   期間 Go 的 Pipeline.Start 已經 emit Stage 1 running event 甚至跑完
   Stage 1 / Stage 2，但前端 EventsOn 還沒掛上去，events 全被丟掉。前端
   接到的第一個 event 可能是 Stage 2 completed 或 Stage 3 running，
   stages[1].status 仍是初始 pending 值，UI 顯示亂序。

   修法：
   - 新增 Go binding GetStartupSnapshot() 回傳 pipeline 當前所有 stages
     狀態（含 current / startedAt / status）。
   - 前端 init 流程在 subscribeEvents 後立即拉一次 snapshot，補上漏掉
     的 stage 狀態。
   - updateStage 加 monotonic 模式：snapshot 補漏時不會用較舊狀態覆蓋
     已收到的較新狀態（避免 race condition 倒退）。
   - status 優先級 STAGE_STATUS_RANK = pending<running<{skipped,failed}<completed

2. 進度條已等待秒數顯示錯誤 — 「進度 3 / 6 · 已等待 20 秒」
   根因：pause 機制讓 elapsed 計算失準（pause 期間 wall clock 仍走但
   stages[i].startedAt 沒重設，會顯示明顯比真實還久的數字）。使用者
   覺得不需要顯示秒數。
   修法：
   - paintProgressBar 移除 elapsedText 邏輯，永遠顯示 progressLabel
   - i18n 文案移除 {elapsed} placeholder（zh-TW + en）：
     stage.1.detail.seedSlow / stage.3.detail.waitHealth /
     stage.3.detail.waitHealthSlow 都改為固定文案
   - Go 端 emit 仍會傳 elapsed（waitProgress callback 不變），但前端
     i18n template 不再用該變數，自然就不顯示

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK
- Wails bindings 自動 regen 含 GetStartupSnapshot

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 01:14:21 +08:00
jim800121chen
ff5cab6b0e feat(local-tool): hard timeout 180s + 全 stage 細步 detail emit + Stage1 seed pause 
使用者回報 Windows 仍看到「啟動時間超過 60 秒」紅 banner，且要求每個
階段做什麼都印出來給使用者知道。三件事一次到位：

1. startupHardTimeout 60s → 180s（直接放寬到 3 分鐘）
   即使三段 pause 機制（Stage 1 seed / Stage 2 Python bootstrap / Stage 3
   waitHealthy）都生效，Windows 乾淨環境段落間累積延遲仍可能超過 60 秒。
   180s 給意料之外的延遲足夠 buffer，搭配 pause + 細步進度 emit 涵蓋
   99% 情境。日常啟動只要幾秒，放寬不影響正常情境。
   - 同步更新 i18n 紅 banner 文案 60 → 180
   - 同步更新 unit tests（HardTimeout 用 -185s、SkipBypass 用 -200s、
     PreventsHardTimeout 用 wall=-300/paused=-250 對應 effective=50s）

2. Stage 1 seedUserDataDir 包進 PauseHardTimeout
   Windows 乾淨環境首次跑會被 Defender real-time scan 對 8 個 nef 檔
   逐個掃 5-30 秒。屬一次性 bootstrap，和 Stage 2/3 同理應豁免 hard
   timeout。第二次啟動 fileExists 早 early return，pause 影響 0ms。
   配套：seed 期間每 5 秒 emit slow hint 帶 elapsed 秒數，避免使用者
   看 spinner 不動以為當機。

3. 全 stage 細步 detail emit
   原本只有 Stage 3 有 sub-step 文案（spawn / waitHealth / waitHealthSlow）。
   現在 Stage 1/2/4/5/6 都有：

   Stage 1: migrate / lock / ipc / seed / seedSlow
   Stage 2: detect / bootstrap / venv / pip / driver
   Stage 3: spawn / waitHealth / waitHealthSlow
   Stage 4: probe
   Stage 5: open
   Stage 6: wait

   每個 detail 對應一段使用者能讀懂的中英文文案（i18n.js zh-TW + en）。
   前端 startup-panel 收到 startup:stage-detail event 後在對應 stage 列
   下方顯示文案，比看著「進行中...」靜止文字直觀很多。

   Stage 2 driver install 因為發生在 CompleteStage(2) 之後 current=3，
   emit 到 stage 3 而非 stage 2，避免被前端忽略（detail 只在 stage
   running 時顯示）。

更新 fix marker 為「9c9e005+ (180s hard timeout + all-stage sub-step
detail + Stage1 seed pause)」讓使用者拉新版後能從 wails.log 確認版本。

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 00:45:50 +08:00
jim800121chen
9c9e005d33 feat(local-tool): Stage 3 sub-step 進度 + 啟動完成後面板可收合 
回應使用者三項需求：
1. healthCheckTimeout 60s → 180s（涵蓋 Defender + EDR 串行延遲最壞情境）
2. Stage 3「啟動本機伺服器」期間顯示細步在做什麼，並在 15 秒後改為「首次
   啟動較久屬正常」slow hint，避免使用者看著 spinner 不動以為 app 掛了
3. 啟動完成後 6 階段面板自動收合成一行 summary，使用者點擊可展開檢視歷
   史紀錄；Restart / Retry 會重置並展開新一輪

實作：

Go 端
- healthCheckTimeout 60s → 180s（理由註解寫清楚 Defender + EDR 各自延遲）
- waitHealthy() 加 progress callback，每 5 秒呼叫一次傳入 elapsedSeconds
- StartupPipeline 加 StartupStageDetailEvent + EmitStageDetail() API
- startServerV2 在 spawn 前 emit detail.spawn，等 health check 期間 callback
  emit detail.waitHealth（< 15s）或 detail.waitHealthSlow（>= 15s）

前端
- 新訂 startup:stage-detail event → updateStageDetail() 把 i18n key 解析為
  文案存到 stages[n].detail，paintStageRow 優先顯示 detail（蓋過 slow hint）
- collapseStartupPanel() / expandStartupPanel() / resetStartupPanel() 三個新
  API 取代 hideStartupPanel；startup:ready 觸發 collapse、Retry/Restart 觸
  發 reset+expand
- collapsed CSS：保留 panel 但縮成一行 summary（標題改「啟動完成」+ ✓ +
  「點此展開檢視」hint），整個 panel 可點擊；hover 加亮
- i18n 加 6 個 keys（zh-TW + en）

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 重 build 163MB OK
- 乾淨 dataDir 啟動 wails app：startup 1 秒內完成（macOS 已 cache binary
  + Python venv），server listen 3721，Chrome 自動連上 — 整條 cold start
  正常

Windows 首次安裝預期行為（修復後）：
- Stage 1 → Stage 2（首次 bootstrap pause hard timeout，跑 1-3 分鐘）→ Stage
  3 spawn → 等 health check 30-90 秒（Defender 掃 binary）期間有「已等 N
  秒」即時更新 → ready → 自動 collapse → 瀏覽器自動開啟

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 00:17:37 +08:00
jim800121chen
a6cd1c12b2 fix(local-tool): Wails 控制台一打開就看到 modal — CSS specificity bug 
使用者回報：Windows 乾淨環境安裝後，一打開 app 就看到「Settings modal +
shutdown-modal「正在停止伺服器…」+ 紅 banner「伺服器無法啟動」」三個應該
hidden 的 element 同時可見。

前面幾個 commit 一直往 Go 端找為什麼 ctrl.Stop 會被意外呼叫，全都沒對。
真正的 bug 是 CSS specificity：

  .modal-backdrop { display: flex; ... }  /* L587，specificity (0,1,0) */
  .error-banner   { display: flex; ... }  /* L488，specificity (0,1,0) */

這兩個 class 的 `display: flex` 規則和 user agent stylesheet 內建的
`[hidden] { display: none }` specificity 相同，但因為我們的 CSS 寫在
cascade 後段勝出——結果是即使 DOM 裡元素有 `hidden` 屬性，瀏覽器依然
渲染成 `display: flex` 可見。

三個受害元素：
  <div class="modal-backdrop" id="settings-modal" hidden>
  <div class="modal-backdrop shutdown-modal" id="shutdown-modal" hidden>
  <section class="error-banner" id="error-banner" hidden>

全部從 DOM 載入第一刻就可見，和 Go 端 ctrl.Stop 是否被呼叫無關。M7
splash 時代前端沒 modal 所以沒人踩到，M8 新加的控制台 UI（8cd5751）
引入這個 bug，但 macOS dev 測試時我只看 server 端 log + api 回應，
沒真的看 Wails 視窗長什麼樣，所以也漏抓。

修法：加全域 `[hidden] { display: none !important; }`。這是 W3C 規範
的標準寫法，保證任何帶 hidden 屬性的元素都會被隱藏，不管其他 CSS
規則怎麼寫。!important 在這情境是正確的——hidden 屬性代表「該元素
不應被顯示」是規範強制語意，不該被任何樣式覆蓋。

驗證：
- macOS dmg 重 build 163MB OK
- binary 內 strings 確認 `[hidden] { display: none !important; }` 已 embed
- 清乾淨 user dataDir 後啟動 wails app，wails.log 整條 startup 流程正常：
  Stage 1 complete → Stage 2 → ctrl.Start returned successfully
- Chrome 建立 2 條 ESTABLISHED 連線到 127.0.0.1:3721
- dataDir 有完整檔案（lock / ipc-port / wails-ipc-port / sentinel / models.json / nef/）

前幾個 commit 修的東西（Stage 2 pause、waitHealthy pause、shutdown modal
safety net、Bug A killStaleServerOnPort）仍然有防禦價值，但都不是使用者
截圖症狀的 root cause。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 23:20:33 +08:00
jim800121chen
35db6c8167 fix(local-tool): Windows popup 卡死 safety net + appLog 覆蓋啟動流程 
使用者回報 c649a81 之後仍看到「正在停止伺服器…」popup 一打開就卡住。
無法在不看 log 的情況下推斷根因，先加三層 safety net 確保 popup 不是
blocker，並把關鍵啟動訊息寫到 wails.log 供 Windows 除錯。

Safety net 三層：

1. 前端 watchdog：shutdown-modal 最多顯示 15 秒，超時自動 hide 並 toast
   提示使用者 server 可能還沒停掉。
2. 前端 escape hatch：點 backdrop 空白處 / 按 Esc 可手動關閉 popup。
3. Go 端 hardBailout timer：stopGraceful 最多跑 shutdownGraceV2 + 2 秒
   （目前 = 9 秒），到上限直接 return leak process，避免 Process.Wait
   永遠阻塞（Windows 偶有情境）。graceTimer 分支的 `<-done` 也改成
   非阻塞 `select-with-1s-timeout`。

Windows 除錯 log 強化：

4. startup 頭加版本識別標記到 wails.log：
     ==================================================
     visionA-local startup build=dev buildTime=unknown
     platform=windows arch=amd64 dataDir=...
     fix marker: c649a81+ (Stage3 waitHealthy pause / shutdown modal safety net)
     ==================================================
   使用者拉新版後啟動可從此確認 build 是否是最新版。
5. app.go 把 startup 路徑上的 fmt.Fprintln(os.Stderr, ...) 改 appLog：
   IPC server start / seed failure / Stage 1 complete / ctrl.Start 結果。
   Windows 上 stderr 是 null device，appLog 會同時寫檔到 wails.log。
6. server_control.go stopGraceful 加 appLog 記錄 entry / modal-show /
   grace timer / hard bailout / return，整條 Stop 路徑完全透明。
7. driver auto-install failed 訊息也改 appLog。

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

需要使用者協助：拉新版後在 Windows 乾淨環境試，啟動後貼以下三個檔案
內容給我：
  %APPDATA%\visiona-local\logs\wails.log        — appLog 記錄整個啟動流程
  %APPDATA%\visiona-local\logs\server.stdout.log — server subprocess stdout
  %APPDATA%\visiona-local\logs\server.stderr.log — server subprocess stderr

log 裡有「fix marker: c649a81+」即為本 commit 或更新；若沒有 marker
或 marker 指向別的 commit 則代表 build 不是最新版。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 22:31:15 +08:00
jim800121chen
c649a81d9f fix(local-tool): Windows 首次啟動再修 — waitHealthy pause + shutdown modal hide 
續 a209470 修 Windows 乾淨環境啟動問題。使用者回報：
- 紅 banner「伺服器無法啟動 / 啟動時間超過 60 秒」— 即 pipeline total-timeout
- 但上方狀態列顯示「執行中 :3721 PID 8568 uptime 00:00:44」— server 實際活著
- Settings popup 上疊 shutdown-modal「正在停止伺服器…」永遠卡住

三個獨立問題：

1. Stage 3 waitHealthy 在 Windows 首次啟動時，Defender real-time scan
   會延遲 30-60 秒才讓 visiona-local-server.exe 真正 bind port。原本
   30 秒 timeout 可能 stage-failure，且這段等候時間計入 pipeline 60 秒
   total budget。修法：
   (a) healthCheckTimeout 30 秒 → 60 秒
   (b) startServerV2 的 waitHealthy call 在冷啟動時（IsInColdStart）
       包進 Pause/Resume hard timeout — 和 Stage 2 Python bootstrap 同理，
       首次 bootstrap 的 Windows Defender 掃描不該算進日常啟動預算。
       Restart（pipeline 已 ready）維持嚴格計時，不 pause。

2. stopGraceful 只 emit "shutdown:modal-show" 沒有對稱的 hide event，
   前端 popup 顯示後無法關閉（只能等應用重開）。修法：
   (a) stopGraceful 用 defer emit "shutdown:modal-hide"（若曾 show）
   (b) 前端 app.js 加對應 EventsOn listener 把 hidden attribute 設回

3. 配套：cwd bash working dir 會在 session 內持久（system prompt 明說
   "working directory persists between commands"），但 env vars 不持久
   — 非本次 commit 相關，僅自己的 mental note。

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 重 build 163MB OK

給 Windows 驗證用的 log 位置：
  %APPDATA%\visiona-local\logs\server.stdout.log     — server 端 log
  %APPDATA%\visiona-local\logs\server.stderr.log     — server 端 panic / 崩潰
  %APPDATA%\visiona-local\logs\wails.log             — Wails app (appLog) 訊息

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 21:59:20 +08:00
jim800121chen
a2094708ec fix(local-tool): Windows 乾淨環境啟動失敗 — Stage 2 豁免 hard timeout 
使用者在 Windows 乾淨環境跑 installer 後首次啟動，看到「伺服器無法
啟動」紅 banner + Settings Stop 卡住。根因：

Stage 2 ensurePythonRuntime 在首次 bootstrap 要做 (1) 解壓 ~15MB
Python tarball (2) 建 venv (3) pip install 9 個 wheel（含 numpy 20MB
+ opencv 50MB + KneronPLUS 等 ~150MB 解壓後）。乾淨 Windows 環境上
這三步合計 2-5 分鐘，遠超 R5-E1 的 60 秒 startup hard timeout，導致
pipeline FailStage + emitError(total-timeout) → Error state → 紅 banner。

R5-E1 的 60 秒預算是針對「日常啟動」，不含首次一次性 bootstrap。

修法：StartupPipeline 加 PauseHardTimeout / ResumeHardTimeout API，
app.go 在 ensureBundledPython 偵測到「真正 bootstrap」條件（pythonBin
不存在）時呼叫 Pause，defer Resume。暫停期間 sinceTotal 扣掉 paused
duration，hard timeout 不觸發。Soft timeout（每階段 20 秒「正在重試」
hint）照常，使用者仍能看到進度提示。

配套：修 killStaleServerOnPort 識別 go run 編出來的 server（Bug A）。
原本用 ps -o comm= 比對 "visiona-local-server" 字串，但 go run 產物
comm 只是 "server"（或 "exe"），生產環境不受影響，但開發 / Reviewer
測試流程會踩到（早上 M8-4 Reviewer 留了一組 go run server 孤兒占住
port 3721 到現在）。改用 ps -o args= 取完整 command line，匹配 規則：
  1. 含 "visiona-local-server" — packaged binary
  2. 含 "/go-build" 且含 "visiona-local/server" 或 "/exe/server" — go run

驗證：
- visiona-local 套件 go build / vet / test / test -race 全綠
- server 套件 go build / vet / test 全綠
- 3 個新 unit test 通過：
  - PauseHardTimeout_ExcludesPausedDuration（effective 時鐘正確扣除）
  - PauseHardTimeout_PreventsHardTimeout（wall clock 120s + paused 90s
    = effective 30s，不觸發 60s hard timeout）
  - ResumeHardTimeout_NoopWhenNotPaused（idempotent）
- macOS dmg 重 build 163MB OK

待做（M8-10b）：使用者在 Windows 乾淨環境重新 install + 驗證首次啟動。
如果仍失敗，Windows log 位置：
  %APPDATA%\visiona-local\logs\server.stdout.log
  %APPDATA%\visiona-local\logs\server.stderr.log
  %APPDATA%\visiona-local\logs\wails.log（若有）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 21:30:59 +08:00
jim800121chen
dd35b561cf chore(local-tool): regen wails bindings — 補 M8 漏提的 binding 產物 
M8 重構（8cd5751）加了很多新 Wails binding（ClearLogs / ExportLog /
ForceKillServer / GetBootstrapStatus / GetPreferences / GetRecentLogs /
GetServerStatusV2 / GetSystemInfo / InstallKneronDriver / OpenInBrowser
/ RestartServer / RestartStartupSequence / RevealLogsFolder / SavePreferences
/ 等）+ 新增 struct（Preferences / LogLine / ServerStatusV2 / SystemInfo）。
wails build 時會 regen wailsjs/go/ 下的 bindings，但上次 M8 commit 時沒
把 regen 結果一併提上去，所以磁碟上的 bindings 和 go source 不同步。

這次 M8-10a build 時自動 regen，順手把 diff 提上來。純產物，無邏輯變更。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 20:23:37 +08:00
jim800121chen
d7cddf364b fix(local-tool): 拆 built-in / user data dir — 修預設模型永遠載入 0 個 
M8-10a smoke test 抓到 M1 就潛藏的 P0 latent bug：server 預設 dataDir =
<binary>/data，bundle 內解析成 Contents/Resources/bin/data/（空目錄），
實際 models.json + 8 個 .nef 住在 Contents/Resources/data/（上一層）。
Wails 又傳 --data-dir 成 user home（writable），同樣沒 models.json。
結果任何正式啟動路徑下 /api/models 都回 total: 0，M1-M7 smoke 從沒
跑過這個 endpoint 才漏抓。

修法：把「read-only bundle 內資料」和「writable user 資料」語意拆開。

- 新增 findFirstExisting(candidates, sentinel) helper
- 新增 resolveBuiltInDataDir：①VISIONA_BUNDLE_LIB_DIR/data（AppImage）
  ②<base>/data ③<base>/../data ④<base>/../Resources/data
  ⑤<base>/../lib/visiona-local/data（Linux FHS）。命中條件是
  models.json 存在為 regular file，避開 Wails build artifact 留下的
  空 data/ 目錄
- main() 拆 builtInDataDir（modelRepo + flash.Service 用）與 dataDir
  （custom-models / sentinel / logs 用），職責分明
- flash.NewService 改吃 builtInDataDir — 它要解析 models.json 裡的
  相對路徑 "data/nef/kl520/xxx.nef"，來源是 bundle 不是 user home
- resolveBridgeScript 同步修（同樣的技術債一起清），候選 env var 優先
  + FHS fallback，避免 Linux AppImage 上 kneron_bridge.py 也找不到
- fallback 全 filepath.Abs 化，log.Printf 印嘗試過的路徑清單便於除錯

驗證（build / vet / test + smoke）全綠：
- macOS bundle：/api/models → 15 models ✅
- dev mode（server/ 下 go run）：15 models ✅
- Linux AppImage 模擬 + env var：命中候選 1 ✅
- Linux AppImage 模擬 + 無 env var：命中候選 5（FHS）✅
- 全不命中：log 印完整 tried 清單 + server 不 crash ✅

Reviewer 兩輪通過。第一輪抓到 Linux AppImage 未覆蓋（Major-1）+ 2 Minor
+ 2 Suggestion；第二輪確認全部處理到位、新發現兩項非阻擋風格建議列為
技術債。報告見 .autoflow/05-implementation/reviews/review-m8-10a-*.md。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 20:23:25 +08:00
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
jim800121chen
a6b71ea908 fix(local-tool): URL 影片載入提示「正在解析，請耐心等待」 
URL 送出後 yt-dlp 解析 + ffmpeg probe 可能花 10-30 秒，
使用者只看到按鈕 loading 會以為卡住。

加一行黃色 animate-pulse 提示：
「正在解析影片連結，YouTube 影片可能需要 10-30 秒，請耐心等待...」

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-13 00:57:03 +08:00
jim800121chen
c0317225ca feat(local-tool): yt-dlp 錯誤訊息友善化 + 載入逾時提示 
ResolveWithYTDLP 改善：
- 新增 friendlyYTDLPError() 把 yt-dlp 的技術性 stderr 訊息轉成繁中提示
- 涵蓋 9 種常見失敗原因：
  年齡限制 / 私人影片 / 已移除 / 版權 / 直播 / 首播 / DRM / 頻率限制 / 無格式
- 錯誤訊息同時附上原始 stderr（方便 debug）
- yt-dlp 未安裝時改用繁中提示

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-13 00:56:15 +08:00
jim800121chen
f13848cf0b fix(local-tool): workspace 推論面板跑版 — 右側面板固定寬度 
右側 InferencePanel 沒設寬度也沒 shrink-0，被左側 CameraInferenceView
擠壓到只剩幾十 px，文字垂直排列。

修法：
- InferencePanel 外層加 w-80 shrink-0（固定 320px 不縮小）
- CameraInferenceView 外層加 min-w-0（允許 flex item 收縮到 0）
- gap-6 改 gap-4（省一點空間）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 23:36:20 +08:00
jim800121chen
00192d3d1e fix(local-tool): yt-dlp / ffmpeg 找不到 — VISIONA_BUNDLE_BIN_DIR 加到 PATH 
根因：Go 1.19+ Windows 的 exec.LookPath 不再搜尋 current directory，
而 exec.Command("yt-dlp") / exec.Command("ffmpeg") 只走 LookPath。
Wails app 有設 VISIONA_BUNDLE_BIN_DIR 環境變數指向 {app}\bin\，
但 server 的 deps/checker.go 只在 startup 檢查時用它，沒把它加到 PATH。

修法：server main.go 啟動時把 VISIONA_BUNDLE_BIN_DIR prepend 到 PATH。
這一次解決三個問題：
- yt-dlp: cannot run executable found relative to current directory
- ffmpeg 攝影機列舉找不到 ffmpeg binary
- ffmpeg camera capture 也找不到

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 23:32:02 +08:00
jim800121chen
96dee565b3 fix(local-tool): 補上 Kneron KL520/KL720 韌體檔案 
根因：KL520 在 USB Boot 模式下（fw=KDP2 Loader）需要先載入韌體到 RAM
才能接受模型載入。kneron_bridge.py connect 流程會自動呼叫
kp.core.load_firmware_from_file()，但前提是找到韌體檔案：
  scripts/firmware/KL520/fw_scpu.bin + fw_ncpu.bin
  scripts/firmware/KL720/fw_scpu.bin + fw_ncpu.bin

這些檔案在 M1 從 edge-ai-platform 搬程式碼時漏了，補入。
Makefile 的 payload-windows/linux/macos 的 cp -R server/scripts/
會自動帶入 firmware/ 子目錄。

KL520: scpu 51KB + ncpu 39KB
KL720: scpu 128KB + ncpu 2.0MB

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 23:11:47 +08:00
jim800121chen
aa324cef42 fix(local-tool): flash 模型檔案找不到 — 相對路徑未解析 
根因：models.json 的 filePath 是相對路徑（"data/nef/kl520/xxx.nef"），
但 server working directory 是 {app}\bin\（app.go 設 cmd.Dir = binary 目錄），
所以 server 在 {app}\bin\data\nef\ 找 .nef 檔，找不到。

實際位置：{app}\data\nef\（installer 裝的位置），對應 server 的 --data-dir
由 Wails app 傳入的 %APPDATA%\visiona-local（或 fallback 到 <exe>/../data）。

修法：
- flash.NewService 新增 dataDir 參數
- StartFlash 中把相對 filePath 用 dataDir 拼接成絕對路徑：
  "data/nef/..." → 去掉 "data/" 前綴 → dataDir + "/nef/..."
- main.go 傳 dataDir 給 flash.NewService

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 22:03:28 +08:00
jim800121chen
c24a04cdb2 fix(local-tool): Review minor m1/m2/m4 修復 
m1（i18n 混用不一致）：
- flash-dialog.tsx 所有英文字串改繁中（載入模型 / 選擇模型 / 硬體不相容 / 開始載入 / 關閉 / 完成）
- flash-progress.tsx 同理（模型載入失敗 / 重試 / 正在準備載入 / 模型載入完成）

m2（Dialog 關閉防護不完整）：
- 改用 isInProgress 判斷（isFlashing || progress 未到 100%）+ 沒 error
  而非只看 isFlashing，涵蓋「API 回應了但 WS 進度還在跑」的情況

m4（WS 3 秒 timeout 應 reject）：
- connectAndWait timeout 改 reject + Error message
- flash-dialog handleFlash 加 try/catch 捕捉 WS 連線失敗
  → 呼叫 setError 讓 UI 顯示錯誤而非靜默卡住

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 20:21:18 +08:00
jim800121chen
3c6971febd fix(local-tool): Review M1-M4 + m5 修復 — flash 生命週期 + store 隔離 
Review 問題修復：

M1（寫已關閉 channel panic）：
- flash service goroutine 改成先等 driver.Flash() 返回，再寫 error 訊息，最後 close
- driver.Flash 返回後保證不再寫 progressCh，消除 race condition

M2（FlashTask 永不清除 memory leak）：
- service.go 新增 CleanupTask(taskID) 公開方法
- device_handler.go 的 goroutine 在 `for range progressCh` 結束後呼叫 CleanupTask

M3（同裝置重複 flash taskID 衝突）：
- ProgressTracker.Create 改成：舊 task 未完成時返回 nil
- StartFlash 檢查 nil → 回傳 "flash already in progress" 錯誤

M4（前端 flash store 全域不區分 deviceId）：
- flash-store.ts 新增 activeDeviceId 欄位
- updateProgress 改接 (deviceId, progress)，比對 activeDeviceId 防止混裝
- use-flash-progress.ts 的 WebSocket callback 傳入 deviceId

m5（flash_ws.go 雙重 conn.Close）：
- read pump goroutine 移除 defer conn.Close()，由外層 defer 統一關閉

額外修復（S4）：
- modelPath 為空時直接回 error 而非傳無效路徑給 driver

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 20:16:24 +08:00