85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# Arcrun 桌面小幫手（Wails）— 地端 build 說明
|
||
|
||
> 這份取代了原本 `wails init` 留下的英文樣板 README（那份只寫「用 `wails build`」，
|
||
> 而這裡真正的打包線是旁邊那四支腳本，不是裸的 `wails build`）。
|
||
>
|
||
> 🔴 **為什麼會有這份**（leo 2026-08-24，`inkstone/arcrun-rag#137`）：
|
||
> 「daemon 部分要傳給地端做，**或是你做好給它 build**」——採後者。
|
||
> 雲端只交**編得起來的 code**，安裝檔（DMG／exe／msix）由地端打，
|
||
> 因為那需要 macOS／Windows 環境與簽章，雲端沒有。
|
||
|
||
---
|
||
|
||
## 一、一次性前置（每台機器裝一次）
|
||
|
||
| 需要 | 怎麼裝 | 用來做什麼 |
|
||
|---|---|---|
|
||
| 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 才需要** |
|
||
|
||
> `wails` 裝完記得 `export PATH="$PATH:$(go env GOPATH)/bin"`（四支 build 腳本自己也會補這行）。
|
||
|
||
## 二、打包：跑既有的腳本，不要自己下 `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 方法一樣叫得到。
|