feat(daemon/p04): fyne 托盤殼 + collector 看守器（CP-1 第6關產品化，leo 定 fyne）
leo 2026-07-21 回「fyne」。交付「可交付的殼」： - collector/supervisor（純 stdlib，無 fyne）：看守 collector direct 子行程、串 stdout JSON 出 狀態（看守中/上次同步/出錯自動重試/已暫停）、崩潰重起、Stop 同步等 loop 收掉（修 Stop→Start 換資料夾時舊 loop 覆寫新狀態的 race）。**sandbox `go test -race ./... 全綠（6 測，含 race）**， 既有 collector 測試零回歸。 - collector/cmd/arcrun-tray（獨立 module，隔開 fyne CGo 依賴）：選單列/系統匣 icon＋狀態＋ 選資料夾(原生對話框)/暫停·繼續/打開資料夾；關窗縮背景；watch_folder 預設 ~/ArcrunRAG 避開 ~/Documents 的 TCC 禁區；wires supervisor。 誠實界定（mindset §7）： - **in-process vs 子行程**：leo 偏好 in-process，但 collector 是 package main，真 in-process 需抽核心成 library（動已驗引擎有回歸風險）→ 本版走子行程看守（collector 零改、崩潰隔離），行為對用戶相同； in-process 抽取列可選後續，待 leo 裁。 - **fyne GUI 沙箱編不了**（CGo+GL）→ build/簽章/TCC 授權＝leo/地端真機做（紅線②③）； fyne API 細節以首次真機 build 為準。README 附建置/簽章/TCC 交接。
This commit is contained in:
cloud-worker
@@ -0,0 +1,62 @@
|
||||
# Arcrun RAG 托盤殼（arcrun-tray）— 建置／簽章／TCC 交接
|
||||
|
||||
> CP-1 第 6 關 daemon 產品化。leo 2026-07-21 定框架＝**fyne**（窮舉七案後推薦，見頂層
|
||||
> `journeys/daemon-tray-shell-options.md`）。**建置/簽章/公證/TCC 授權＝leo/地端在真機做**（紅線②③）。
|
||||
|
||||
## 這顆殼做什麼
|
||||
|
||||
一個**選單列（Mac）/系統匣（Windows）icon**，讓不開 terminal 的人也能用：
|
||||
- 狀態一眼看（看守中 · 上次同步 HH:MM／啟動中／出錯自動重試／已暫停）
|
||||
- 選單：**選擇知識資料夾**（系統原生對話框）／打開資料夾／暫停·繼續看守
|
||||
- 關掉視窗＝縮回背景續看守（不是結束）
|
||||
|
||||
它**看守** `arcrun-collector direct`（同綑執行檔），把它當背景常駐；崩了自動重起。
|
||||
|
||||
## 哪些已驗、哪些待真機驗（誠實界定，mindset §7）
|
||||
|
||||
| 部分 | 狀態 | 驗法 |
|
||||
|------|------|------|
|
||||
| **看守核心** `collector/supervisor`（子行程管理／狀態解析／崩潰重起／停止） | ✅ **sandbox `go test` 驗過**（純 stdlib，5 測全綠，含重起/停止/狀態解析） | `cd collector && go test ./supervisor/` |
|
||||
| collector 引擎（未動） | ✅ 既有測試無回歸 | `cd collector && go test ./...` |
|
||||
| **fyne GUI 本體**（本 main.go：tray icon／選單／原生選資料夾） | ⏳ **待真機 build**——fyne 需 CGo＋GL/webview，無螢幕 sandbox 編不了 | 真機 `go mod tidy && fyne package` |
|
||||
| macOS **TCC 同意流** | ⏳ 待真 Mac 驗（沙箱測不到真 TCC 語意＝假綠，故不盲寫） | 見下「TCC」 |
|
||||
|
||||
> ⚠️ **fyne API 細節（fyne.Do／SetSystemTrayMenu 刷新／Lifecycle）以首次真機 build 為準**——
|
||||
> 本檔按 fyne v2.5 API 寫，但未經編譯器。第一次 `go mod tidy && go build` 若有 API 出入，就地修。
|
||||
|
||||
## 建置（leo/地端，真機）
|
||||
|
||||
```bash
|
||||
cd collector/cmd/arcrun-tray
|
||||
go mod tidy # 拉 fyne 依賴（首次需網路）
|
||||
# 把 collector 執行檔一起放進 bundle（托盤靠同層 arcrun-collector）
|
||||
（cd ../.. && GOOS=darwin GOARCH=arm64 go build -o cmd/arcrun-tray/arcrun-collector .）
|
||||
# 打包 .app（Mac）／.exe（Win）
|
||||
go run fyne.io/fyne/v2/cmd/fyne@latest package -os darwin -icon icon.png -name "Arcrun RAG"
|
||||
# Windows：-os windows
|
||||
```
|
||||
> icon.png 待放（leo logo 進行中）；Mac 選單列建議 **template 單色 icon**（自動深淺色）。
|
||||
|
||||
## 簽章／公證（Mac，leo/地端）
|
||||
|
||||
未簽章的 .app 會被 Gatekeeper 擋（右鍵開可繞，但非產品體驗）。正式版：
|
||||
```bash
|
||||
codesign --deep --force --options runtime --sign "Developer ID Application: <你>" "Arcrun RAG.app"
|
||||
xcrun notarytool submit "Arcrun RAG.zip" --apple-id … --team-id … --wait
|
||||
xcrun stapler staple "Arcrun RAG.app"
|
||||
```
|
||||
|
||||
## TCC（macOS，只有真 Mac 驗得到）
|
||||
|
||||
**預設 watch_folder ＝ `~/ArcrunRAG`（本殼已這樣設）——刻意避開 `~/Documents`**：launchd/背景程序碰
|
||||
`~/Documents` 會被 TCC 擋（2026-07-19 實撞）。預設在非 TCC 禁區＝**零授權即可用**。
|
||||
|
||||
用戶若堅持把資料夾設在 `~/Documents`/`~/Desktop`/`~/Downloads`：
|
||||
1. 首次讀取被拒 → 本殼應偵測並引導：**系統設定 → 隱私權與安全性 → 檔案與資料夾**（或完整磁碟取用權）勾選 Arcrun RAG。
|
||||
2. 這一步**必須在真 Mac 上驗**（跳不跳授權框、launchd 背景 vs GUI 前景差異）。sandbox 只能測到 `os.Open` 成不成，測不到真 TCC＝假綠，故本輪不寫死。
|
||||
|
||||
## 安裝（用戶視角，最終形態）
|
||||
|
||||
下載 → 拖進「應用程式」→ 開啟 → 選一個資料夾 → 完成。cypher_url/namespace/api_key 由**安裝器**寫進
|
||||
`~/.arcrun-rag/config.json`（用戶不碰）。**現行 `docs/manual/product-install-guide.md` 是廢棄的
|
||||
Docker 六步，產品化時要重寫成這段。**
|
||||
@@ -0,0 +1,14 @@
|
||||
// 獨立 module：把 fyne（CGo/GL）依賴與純 stdlib 的 collector module 隔開，
|
||||
// 讓 collector 模組維持 `go test ./...` 可在無 GUI 環境驗證。
|
||||
// 本 module 在 Mac/Windows 真機 build（leo/地端）：`go mod tidy && fyne package`。
|
||||
module arcrun-rag/collector/cmd/arcrun-tray
|
||||
|
||||
go 1.22
|
||||
|
||||
require (
|
||||
arcrun-rag/collector v0.0.0
|
||||
fyne.io/fyne/v2 v2.5.3
|
||||
)
|
||||
|
||||
// 複用同 repo 的 supervisor 套件（純 stdlib）。
|
||||
replace arcrun-rag/collector => ../../
|
||||
@@ -0,0 +1,221 @@
|
||||
// arcrun-tray — Arcrun RAG 桌面托盤殼（CP-1 第 6 關 daemon 產品化，leo 2026-07-21 定 fyne）。
|
||||
//
|
||||
// 目的：讓「不開 terminal 的人」也能裝、開關、選資料夾——一個選單列/系統匣 icon 就是全部。
|
||||
// 它看守 `collector direct`（子行程，見 supervisor 套件的誠實界定）並顯示狀態。
|
||||
//
|
||||
// ⚠️ 本檔是 fyne GUI（CGo＋系統 webview/GL），**無法在無螢幕 sandbox build/驗**——
|
||||
//
|
||||
// build/簽章/公證/TCC 授權＝leo/地端在真機做（紅線②③）。純邏輯（看守/config）已抽到
|
||||
// supervisor 套件並在 sandbox `go test` 驗過。
|
||||
//
|
||||
// 真機 build：
|
||||
//
|
||||
// cd collector/cmd/arcrun-tray && go mod tidy
|
||||
// go run fyne.io/fyne/v2/cmd/fyne@latest package -os darwin -icon icon.png -name "Arcrun RAG"
|
||||
// （Windows：-os windows；簽章/公證另見同目錄 README）
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
|
||||
"arcrun-rag/collector/supervisor"
|
||||
|
||||
"fyne.io/fyne/v2"
|
||||
"fyne.io/fyne/v2/app"
|
||||
"fyne.io/fyne/v2/container"
|
||||
"fyne.io/fyne/v2/dialog"
|
||||
"fyne.io/fyne/v2/driver/desktop"
|
||||
"fyne.io/fyne/v2/storage"
|
||||
"fyne.io/fyne/v2/theme"
|
||||
"fyne.io/fyne/v2/widget"
|
||||
)
|
||||
|
||||
// directConfig 是 collector direct 的設定（與 collector/direct.go 的 DirectConfig 同結構；
|
||||
// 這裡只需讀寫 watch_folder，其餘由安裝器帶入）。
|
||||
type directConfig struct {
|
||||
WatchFolder string `json:"watch_folder"`
|
||||
Manifest string `json:"manifest"`
|
||||
CypherURL string `json:"cypher_url"`
|
||||
Namespace string `json:"namespace"`
|
||||
APIKey string `json:"api_key,omitempty"`
|
||||
Library string `json:"library,omitempty"`
|
||||
IngestWF string `json:"ingest_workflow,omitempty"`
|
||||
RemovedWF string `json:"removed_workflow,omitempty"`
|
||||
PollSec int `json:"poll_interval_sec,omitempty"`
|
||||
MaxRemoved float64 `json:"max_removed_ratio,omitempty"`
|
||||
}
|
||||
|
||||
// appDir 是設定與 manifest 落地處：~/.arcrun-rag/
|
||||
func appDir() string {
|
||||
home, _ := os.UserHomeDir()
|
||||
return filepath.Join(home, ".arcrun-rag")
|
||||
}
|
||||
|
||||
func configPath() string { return filepath.Join(appDir(), "config.json") }
|
||||
|
||||
// defaultWatchFolder 預設 ~/ArcrunRAG——**刻意避開 ~/Documents**：macOS launchd 背景程序碰
|
||||
// ~/Documents 會被 TCC 擋（07-19 實撞）。預設在非 TCC 禁區＝零授權即可用；用戶要改到 Documents
|
||||
// 才需走 TCC 同意流（見 README）。
|
||||
func defaultWatchFolder() string {
|
||||
home, _ := os.UserHomeDir()
|
||||
return filepath.Join(home, "ArcrunRAG")
|
||||
}
|
||||
|
||||
func loadConfig() *directConfig {
|
||||
c := &directConfig{}
|
||||
if data, err := os.ReadFile(configPath()); err == nil {
|
||||
_ = json.Unmarshal(data, c)
|
||||
}
|
||||
if c.WatchFolder == "" {
|
||||
c.WatchFolder = defaultWatchFolder()
|
||||
}
|
||||
if c.Manifest == "" {
|
||||
c.Manifest = filepath.Join(appDir(), "manifest.json")
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
func saveConfig(c *directConfig) error {
|
||||
if err := os.MkdirAll(appDir(), 0o755); err != nil {
|
||||
return err
|
||||
}
|
||||
data, _ := json.MarshalIndent(c, "", " ")
|
||||
return os.WriteFile(configPath(), data, 0o600)
|
||||
}
|
||||
|
||||
// collectorBinPath 找同綑的 collector 執行檔（app bundle 內與托盤同層）。
|
||||
func collectorBinPath() string {
|
||||
exe, err := os.Executable()
|
||||
if err != nil {
|
||||
return "arcrun-collector"
|
||||
}
|
||||
name := "arcrun-collector"
|
||||
if isWindows() {
|
||||
name += ".exe"
|
||||
}
|
||||
return filepath.Join(filepath.Dir(exe), name)
|
||||
}
|
||||
|
||||
func isWindows() bool { return os.PathSeparator == '\\' }
|
||||
|
||||
func main() {
|
||||
a := app.NewWithID("dev.arcrun.rag.tray")
|
||||
cfg := loadConfig()
|
||||
|
||||
// 設定視窗（平時隱藏；選資料夾/看說明時開）
|
||||
win := a.NewWindow("Arcrun RAG")
|
||||
win.SetCloseIntercept(func() { win.Hide() }) // 關窗只隱藏，不結束 app（托盤續跑）
|
||||
win.Resize(fyne.NewSize(420, 220))
|
||||
|
||||
sup := supervisor.New(collectorBinPath(), configPath())
|
||||
|
||||
// 狀態列（tray 選單第一項，只讀）
|
||||
statusItem := fyne.NewMenuItem("狀態：尚未開始", nil)
|
||||
statusItem.Disabled = true
|
||||
|
||||
folderItem := fyne.NewMenuItem("選擇知識資料夾…", func() {
|
||||
win.Show()
|
||||
win.RequestFocus()
|
||||
dialog.ShowFolderOpen(func(uri fyne.ListableURI, err error) {
|
||||
if err != nil || uri == nil {
|
||||
return
|
||||
}
|
||||
cfg.WatchFolder = uri.Path()
|
||||
if err := saveConfig(cfg); err != nil {
|
||||
dialog.ShowError(err, win)
|
||||
return
|
||||
}
|
||||
// 換資料夾＝重起看守
|
||||
sup.Stop()
|
||||
sup.Start()
|
||||
win.Hide()
|
||||
}, win)
|
||||
})
|
||||
|
||||
openFolderItem := fyne.NewMenuItem("打開資料夾", func() {
|
||||
if u, err := storage.ParseURI("file://" + cfg.WatchFolder); err == nil {
|
||||
_ = a.OpenURL(u)
|
||||
}
|
||||
})
|
||||
|
||||
var pauseItem *fyne.MenuItem
|
||||
pauseItem = fyne.NewMenuItem("暫停看守", func() {
|
||||
st := sup.Status()
|
||||
if st.State == supervisor.StateStopped {
|
||||
sup.Start()
|
||||
pauseItem.Label = "暫停看守"
|
||||
} else {
|
||||
sup.Stop()
|
||||
pauseItem.Label = "繼續看守"
|
||||
}
|
||||
})
|
||||
|
||||
tray := fyne.NewMenu("Arcrun RAG",
|
||||
statusItem,
|
||||
fyne.NewMenuItemSeparator(),
|
||||
folderItem,
|
||||
openFolderItem,
|
||||
pauseItem,
|
||||
)
|
||||
|
||||
desk, hasTray := a.(desktop.App)
|
||||
if hasTray {
|
||||
desk.SetSystemTrayMenu(tray)
|
||||
desk.SetSystemTrayIcon(theme.StorageIcon()) // TODO 換品牌 icon（leo logo 進行中）；Mac 建議 template 單色
|
||||
}
|
||||
// 重設選單＝刷新（比 (*Menu).Refresh() 跨版本更穩）
|
||||
refreshTray := func() {
|
||||
if hasTray {
|
||||
desk.SetSystemTrayMenu(tray)
|
||||
}
|
||||
}
|
||||
|
||||
// 狀態變更 → 刷新 tray 文案（回呼在 supervisor goroutine，切回 UI thread）
|
||||
sup.SetOnChange(func(s supervisor.Status) {
|
||||
fyne.Do(func() {
|
||||
statusItem.Label = "狀態：" + humanStatus(s)
|
||||
refreshTray()
|
||||
})
|
||||
})
|
||||
|
||||
// 設定視窗內容：說明現況 + 選資料夾按鈕（給會開窗的人；不會開的人靠 tray 選單）
|
||||
win.SetContent(container.NewVBox(
|
||||
widget.NewLabelWithStyle("Arcrun RAG 知識同步", fyne.TextAlignCenter, fyne.TextStyle{Bold: true}),
|
||||
widget.NewLabel("把檔案丟進你選的資料夾，就會自動進你的知識庫。\n這個程式會待在選單列/系統匣，關掉視窗它仍在背景看守。"),
|
||||
widget.NewButton("選擇知識資料夾…", func() { folderItem.Action() }),
|
||||
))
|
||||
|
||||
// 開機即看守（若設定完整）
|
||||
if cfg.CypherURL != "" && cfg.Namespace != "" {
|
||||
sup.Start()
|
||||
} else {
|
||||
// 缺安裝器帶入的 cypher_url/namespace：提示用戶先完成安裝
|
||||
statusItem.Label = "狀態：尚未連結（請先完成安裝）"
|
||||
win.Show()
|
||||
}
|
||||
|
||||
a.Lifecycle().SetOnStopped(func() { sup.Stop() })
|
||||
a.Run()
|
||||
}
|
||||
|
||||
// humanStatus 把狀態機轉成白話（給不懂內部的人）。
|
||||
func humanStatus(s supervisor.Status) string {
|
||||
switch s.State {
|
||||
case supervisor.StateWatching:
|
||||
if !s.LastRoundAt.IsZero() {
|
||||
return fmt.Sprintf("看守中 · 上次同步 %s", s.LastRoundAt.Local().Format("15:04"))
|
||||
}
|
||||
return "看守中"
|
||||
case supervisor.StateStarting:
|
||||
return "啟動中…"
|
||||
case supervisor.StateError:
|
||||
return "暫時出錯，正在自動重試"
|
||||
case supervisor.StateStopped:
|
||||
return "已暫停"
|
||||
default:
|
||||
return "尚未開始"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user