sync: collector/ 同步自 inkstone/arcrun-rag@45b74a4（桌面小幫手 0.18.36）

cmd/arcrun-app/README.md

@@ -1,19 +1,84 @@
-# README
+# Arcrun 桌面小幫手（Wails）— 地端 build 說明
 
-## About
+> 這份取代了原本 `wails init` 留下的英文樣板 README（那份只寫「用 `wails build`」，
+> 而這裡真正的打包線是旁邊那四支腳本，不是裸的 `wails build`）。
+>
+> 🔴 **為什麼會有這份**（leo 2026-08-24，`inkstone/arcrun-rag#137`）：
+> 「daemon 部分要傳給地端做，**或是你做好給它 build**」——採後者。
+> 雲端只交**編得起來的 code**，安裝檔（DMG／exe／msix）由地端打，
+> 因為那需要 macOS／Windows 環境與簽章，雲端沒有。
 
-This is the official Wails Vanilla template.
+---
 
-You can configure the project by editing `wails.json`. More information about the project settings can be found
-here: https://wails.io/docs/reference/project-config
+## 一、一次性前置（每台機器裝一次）
 
-## Live Development
+| 需要 | 怎麼裝 | 用來做什麼 |
+|---|---|---|
+| Go **1.25+** | `brew install go`（`go.mod` 寫 `go 1.25.0`；較舊的 Go 會自己抓 toolchain） | 編 App 與 collector |
+| Node 18+ | `brew install node` | 編前端（Vite） |
+| Wails CLI v2 | `go install github.com/wailsapp/wails/v2/cmd/wails@v2.13.0` | 打包 |
+| mingw-w64 | `brew install mingw-w64` | **只有要打 Windows 版才需要**（WebView2 要 CGo 交叉編譯） |
+| cmake、icu4c | `brew install cmake icu4c` ＋ `bash build-msix.sh --setup` | **只有要送 Microsoft Store 才需要** |
 
-To run in live development mode, run `wails dev` in the project directory. This will run a Vite development
-server that will provide very fast hot reload of your frontend changes. If you want to develop in a browser
-and have access to your Go methods, there is also a dev server that runs on http://localhost:34115. Connect
-to this in your browser, and you can call your Go code from devtools.
+> `wails` 裝完記得 `export PATH="$PATH:$(go env GOPATH)/bin"`（四支 build 腳本自己也會補這行）。
 
-## Building
+## 二、打包：跑既有的腳本，不要自己下 `wails build`
 
-To build a redistributable, production mode package, use `wails build`.
+```sh
+cd collector/cmd/arcrun-app
+
+./build-mac.sh      # → build/bin/Arcrun.app
+./build-dmg.sh      # → dist/Arcrun-<版本>.dmg      （自己會先跑 build-mac.sh）
+./build-win.sh      # → dist/Arcrun-<版本>.exe      （在 Mac 上交叉編譯，需 mingw-w64）
+./build-msix.sh     # → dist/Arcrun-<版本>.msix     （送 Store 用；不必自購憑證）
+```
+
+🔴 **版本號不要手打。** `daemon-version.py --stamp` 會從 `collector/CHANGELOG.md`
+最上面那個「下一版（未發佈）」段落戳出版號並補上日期——四支腳本都已經呼叫它。
+本次（`#137`）的 changelog 段落已經寫好，所以**這一版打出來會是 `0.18.35`**
+（`./daemon-version.py` 唯讀查詢可以先確認）。
+
+🔴 打包前若改過任何 `collector/` 底下的檔，指紋會變 ⇒ 同一個版號不准對應兩份原始碼，
+腳本會擋下來並告訴你怎麼辦。那是刻意的閘，不要繞過它。
+
+## 三、交貨前自己先驗（這三支都在本目錄，跑得很快）
+
+```sh
+go test ./...                       # 後端（含本次新增的 App 啟動器 12 條）
+bash check-cis.sh                   # CIS 合規（色票／lockup／選中態）
+npm --prefix frontend run build && node check-launcher.mjs   # 畫面與互動（需 playwright）
+```
+
+`check-launcher.mjs` 會真的把 `frontend/dist` 渲染出來、真的點下去，
+截圖丟在 `/tmp/arcrun-launcher-shots/`。沒裝 playwright 它會自己跳過
+（`npm i -D playwright && npx playwright install chromium`）。
+
+macOS 上另外還有 `check-render.sh`（量 lockup 像素與深色模式），需要本機的 Chrome。
+
+## 四、只有在真機上才驗得到的（雲端做不到，地端請補）
+
+雲端這台沒有 GUI、也沒有 WebView，所以下面這些**沒有被驗過**，
+打包完請在真機上走一次：
+
+1. `wails dev`（或直接開打好的 `Arcrun.app`）能不能起來、視窗尺寸對不對。
+2. 系統匣：Mac 是原生 `NSStatusItem`（`tray_darwin.m`）、Windows 是 `energye/systray`；
+   點 icon 開窗、右鍵只有「結束 Arcrun」。
+3. **App 啟動器**（本次新增）：打開就落在「App 界面」，九宮格列出的是你連的那個
+   知識庫實際裝了的 App；點一個進去、按一下它的動作，看結果回不回得來。
+4. Windows：WebView2 有沒有裝、SmartScreen 會不會攔、Defender 會不會誤判。
+
+## 五、平台檔案對照（改東西前先看這張）
+
+| 檔 | build tag | 說明 |
+|---|---|---|
+| `tray_darwin.go` / `tray_darwin.m` | `darwin` | macOS 原生 NSStatusItem |
+| `tray_windows.go` | `windows` | Windows systray |
+| `tray_other.go` | `!darwin && !windows` | **no-op**。讓 `go build`／`go test` 在 Linux／CI 上跑得起來，對出貨零影響（Linux 不是出貨平台） |
+| `dock_darwin.go` / `dock_other.go` | 同上 | Dock icon 隱藏 |
+
+## 六、開發時的即時預覽
+
+```sh
+wails dev
+```
+Vite 熱重載；`http://localhost:34115` 可以用瀏覽器連進去，Go 方法一樣叫得到。