inkstone/arcrun-collector
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
115 Commits 2 Branches 14 Tags
a6ced32d4559bb3d3aaf24d5b14826e672383f19
Commit Graph

115 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
Leo a6ced32d45 collector：積壓分批＋新檔優先／額度用完講人話降速／斷點續傳／同內容多格式去重 
封測事故（Evan）：daemon 逐檔萃取上傳、每個檔在雲端產生一次工作流執行，
690 個檔在自己的免費 CF 帳號上短時間內衝出 1,070 次寫入，撞上免費上限 1,000，
額度爆掉、只有 8 個檔成功。雲端那一半（紀錄改走資料層 API）已修好，
daemon 這一半原本完全沒有節奏——本次補齊四件事：

1. 上傳節奏（direct_pacing.go）：單輪最多處理 MaxEventsPerRun 個事件
   （預設 25）、每次觸發雲端前節流 700ms；一輪掃到的事件依檔案 mtime
   由新到舊排序，今天寫的永遠優先，積壓慢慢消化不擋日常使用。

2. 額度用完講人話（quota.go）：偵測到 Workers AI「10,000 neurons」/
   「4006」等已知上游訊號後，換成三句話（今天已整理幾份／可換模型或
   升級 Cloudflare／不花錢也沒關係、今天或明天早上 8:00 會自動恢復），
   不出現裸露的錯誤碼；同帳號同輪與下一輪都不再繼續撞牆
   （quotaState 全域冷卻，跨資料夾／跨程序重啟持續，直到台灣時間
   早上 8:00 額度重置）。

3. 斷點續傳：每個事件處理完立刻寫回 manifest（不再等整輪跑完才存一次），
   process 被殺掉重開只會接著做真正還沒完成的部分；removed 事件另外
   用 preScanEntries 快照保護，下架失敗時不會被其他事件的存檔動作
   誤標成「已完成」而永遠不再重試。

4. 同內容多格式去重（scan.go）：同一批來源轉出的多種格式（如 leo 給的
   資料集 27,164 檔＝9,045 md＋9,044 json＋9,043 html，md/json 同檔名
   主幹）依檔名主幹分組，只留優先序最高的一份進事件管線，其餘標記在
   DuplicateFormats（不吃三倍額度）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-07 16:58:07 +08:00
Leo 8ad6f25ba3 出貨 v0.18.21：釘子 → c1566cf（Windows 修復鏈＋首發 MSIX 已送達封測者） 2026-08-06 23:18:00 +08:00
Leo c952d66e41 MSIX 帶入真 Store Identity（從頂層 .env 自動讀）＋credentials-map 登錄：別再問 leo 要這三個值 2026-08-06 23:04:53 +08:00
Leo 5c0bddacc4 v0.18.20：失敗清單改摺疊式＋修指紋閘的自我參照 
## UI（leo 實測版面被壓扁）
失敗清單改用原生 `<details>`：只列檔名、旁邊三角形、**預設收合**，
點開才看原因。先前把原因攤在檔名旁邊，中文檔名被擠成一行一個字。

## 🔴 指紋閘三修：帳本自己不能算進指紋（經典自我參照）
`.version-source.json` 就住在 `collector/` 底下 ⇒ 戳版號寫入它、指紋跟著變
⇒ **同一輪連續打 win/mac/msix，第二支就被自己的閘擋下**（實撞）。
查證過才修（沒有亂放寬）：
  · `gen-icons.py` 產的 .ico **位元一致**，不是它
  · `dist/` 早就 gitignore，不在名單裡
  · 真兇只有帳本
⇒ **只排除帳本一個檔**。一度想順手排掉整個 `build/`，那會讓「換 app icon」
  不算原始碼變更＝在閘上挖洞，已收回。
驗：連跑兩次版本號相同（冪等）。

## 三種產物都備齊（在共用資料夾）
`Arcrun-win-v0.18.20.exe`／`送審用/Arcrun-v0.18.20.dmg`／`送審用/Arcrun-v0.18.20.msix`
⚠️ MSIX 的 **Identity 三值仍是佔位**（`PLACEHOLDER.ArcrunRAG`）⇒ **不能送 Store**，
需 leo 從 Partner Center 提供 `IDENTITY_NAME`／`PUBLISHER`／`PUBLISHER_DISPLAY` 再重打。

## 未送達
線上仍 v0.18.8。推遠端需 leo 開 D20 閘。
 2026-08-06 22:39:42 +08:00
Leo 73004b4149 失敗清單改成「檔名 + 三角形，預設收合」（leo 實測版面被壓扁） 
leo：「表格最左邊的標題被壓扁了…**可以顯示沒通過的名稱，旁邊有個三角形，
點擊看到失敗細節，default 摺疊起來，重點是找到問題在哪裏**」

## 真兇
我重用 `.step` 的橫向格線（`display:flex` + 原因擠在右邊）
⇒ 中文檔名被壓成**一行一個字**（實撞截圖）。

## 改法
改用原生 `<details>/<summary>`：三角形、鍵盤可操作、預設收合都不必自己寫。
檔名一行（`word-break: break-word`，長檔名換行但不是一字一行），
原因收在裡面，需要時才展開——**先看到「哪些檔沒過」，細節是第二層**。
CSS 用實際存在的 CIS 變數（`--ink-rgb`／`--amber`；原本誤用不存在的 `--hair`／`--ink-soft`）。

## 驗
`node --check` 過、`check-cis.sh` **全過**、go build 過。
⚠️ **未真機驗**（未打包送到 leo 手上）。
 2026-08-06 22:31:00 +08:00
Leo d0852e9b45 v0.18.19：失敗訊息改成人話（leo：「這個錯誤訊息我真的看不懂」） 
v0.18.18 雖然把失敗檔案列出來了，但寫的是
「上次失敗（第 5 次），5h38m38s 後重試（上面是自動重試的排程，真正的原因是前一次失敗）」
——**那是我寫給自己看的**：只是把 collector 的原文轉貼、再補一句解釋為什麼看起來怪。

使用者要的是三件事：**現在怎樣、為什麼、我要不要做什麼**。

## 改法
- 解析退避訊息取出「試幾次／多久後再試／原因」，重新組成人話
- **有原因**時以原因為主、排程放後面補充（他要判斷的是原因）
- **沒有原因**時（舊版失敗的檔案沒存 LastError）誠實說：
  「已經自動試過 5 次都沒成功，約 5 小時後會再試一次。這個檔是在舊版失敗的，
    當時沒有記下原因；如果一直沒好，把紀錄檔傳給我們。」
- 時間不再精確到秒（`5h38m38s` → 「約 5 小時」）——使用者要的是量級不是秒數

## 實測輸出（三種情境都印出來看過）
  舊：上次失敗（第 5 次），5h38m38s 後重試（上面是自動重試的排程…）
  新：已經自動試過 5 次都沒成功，約 5 小時後會再試一次。這個檔是在舊版失敗的…
  新：今天的免費 AI 額度用完了 ⇒ 明天會自動恢復，這些檔案會自己補上，你不用做什麼。
  新：這份 PDF 看起來是掃描的圖片 ⇒ 需要先做文字辨識（OCR），或換一份有文字的版本。
 2026-08-06 22:02:32 +08:00
Leo 857420dfa7 v0.18.18：失敗原因真的顯示在畫面上（前面幾版只做了一半） 
## 補完「上游錯誤要看得到」這條線
- 退避中的檔案也進 `status.failures`（先前退避期間該欄是空的
  ⇒ 畫面只有「⚠ N 份失敗」沒有原因，等於前面白做）
- `shortError` 從 120 放寬到 240 字：真因在訊息**後半段**，砍 120 會整段切掉

## 實測輸出（不是推測，是印出來的卡片內容）
  有 2 份沒有送進知識庫
   · 2021超新星品牌白皮書-科特勒.pdf
     今天的免費 AI 額度用完了 ⇒ 明天會自動恢復，這些檔案會自己補上，你不用做什麼。
   · 台灣青年創新創業協會謝侑霖.pdf
     這份 PDF 看起來是掃描的圖片 ⇒ 需要先做文字辨識（OCR），或換一份有文字的版本。
⇒ 同樣是「失敗」，處置完全相反（等就好／要動手），使用者現在分得出來。
（測試資料取自 leo Windows collector.log 的原文。）
 2026-08-06 21:41:28 +08:00
Leo c7675a10a0 不再把開發用 template 塞進使用者資料夾；上游錯誤不再被退避訊息吞掉 
## leo 三條裁決，逐條落實
① 「**別人的錯誤一律要顯示給用戶看，不然就會變成我的錯誤，導致客服**」
   → manifest entry 新增 `LastError`（存**原文**），退避訊息改成
     「上次失敗（第 N 次），58m 後重試｜**原因：**<上游原文>」。
     成功後清空，不留舊錯誤嚇人。
     測試 `TestUpstreamErrorSurvivesBackoff` 從上游錯誤字串出發，
     驗它活到給使用者看的那句話；反向驗證拿掉即紅。

② 「**拿來開發一般人用不到的根本別安裝**」
   → daemon 不再代裝 system-dev template（`CLAUDE.md`／`scripts/`／`system-dev/`，37 檔）。
     兩層傷害：把人家資料夾弄亂 ＋ 那些檔被當知識吃進去
     ⇒ 知識庫長出 `kb`／`t195-watch` 這種不是使用者內容的庫（leo 實撞）。
     `template-install` 子命令保留，開發者情境不受影響。

③ 「**它也不能只看隱藏檔內，因為 template 在我所有的 repo 裡不是隱藏的**」
   → 排除規則用**路徑身分**（`TemplateOwns()`，來源是內嵌 templatefs 的實際路徑
     ＋ `system-dev/`・`scripts/` 目錄前綴），**不是**「有沒有以點開頭」。
     測試刻意把 template 檔放成**不隱藏**（就像 leo 的 repo），驗它仍被排除；反向驗證即紅。
     這些檔也不計進「有 N 個檔案沒有被整理」——那欄是給使用者看他自己的檔案的。

## 順帶修 leo 截圖上的重複
「有 2 個檔案沒有被整理」底下 `scripts/sdd-active-check.sh` 出現兩次
——多帳號時同一個資料夾被掃多輪、每輪都 append。已去重。

## 殘項（誠實）
App 端失敗卡還沒接上這條線 ⇒ **畫面尚未真的顯示原因**。未打包、未送達。
 2026-08-06 21:33:37 +08:00
Leo 6e0b65a2bb mistakes：Workers AI 額度用完／掃描版 PDF——兩個「不是 bug 但要說清楚」的已知現象 2026-08-06 20:48:01 +08:00
Leo 9dc7cbc803 v0.18.17：失敗的檔案列出檔名與原因；補上「上一版說有、其實沒做進畫面」的按鈕 
leo Windows 實測 v0.18.16：連線誤報已消失（✅ 那個修正生效），
但出現「⚠ 3 份失敗」→ 加檔後「⚠ 1 份失敗」，兩個新檔沒推上雲端也沒產卡。

## 修：數字不能代替原因（今天第四次同款病）
collector **早就**把「哪個檔失敗、為什麼」寫進 status.json（`Failures[]`），
但 App 一直只讀計數 ⇒ 畫面只會說「⚠ 3 份失敗」
⇒ leo 只能回報「沒推到雲端」，我只能猜。
前三次同款：exit status 2 蓋掉真話／非文件檔不點名／誤判沒連線。
現在列出檔名＋原因（最多 8 份，總數照實講）。

## 🔴 更正：v0.18.12 宣稱的「一鍵打開紀錄檔資料夾」**根本沒進到畫面**
Go 那邊 `OpenLogFolder()`／`EngineTrouble` 都做了，但前端那次 `str.replace()`
**錨點縮排不符、沒命中**，而我沒加斷言 ⇒ 檔案沒變，我卻在回覆與 changelog 裡宣稱做好了。
（同一天已經因為「取代沒驗證」出過一次事，這是第二次。）
本次三處錨點**全部 assert**，並機械複驗五個關鍵字＋`node --check`。
changelog 也已更正 v0.18.12 那段。

## 順帶修 .bat 的收集段（leo：「有按照 1 然後 2，你要檢查 bat」）
收集 log 那段用 `>nul 2>&1` **把錯誤全吞掉** ⇒ 失敗了也沒人知道，
我還以為是 leo 沒按 Enter。改成**逐檔回報 v/X/-**，並把輸出目錄
從中文「記錄檔」改成純英文 `logs`（中文路徑＋UNC＋Big5 主控台三者疊加容易出事）。
 2026-08-06 20:22:24 +08:00
Leo 01fbb21357 v0.18.16：修「明明連上卻說沒連上」——第三次「我這台好好的」 
leo Windows 實測：首頁跳「需要你處理一下 ⇒ 還沒連上知識庫」，
但側邊欄有 geek6688、Portal 的庫目錄管理也看得到它的庫（win_on_mac_test_lib）。

## 真兇：又是「只看根層欄位」
`direct.go` 判連線只看 **根層** `cypher_url`/`api_key`，
而多帳號設定（現在的常態）根層是空的 ⇒ **恆判成沒連線**。
為什麼開發機沒事：leo 的 Mac config 帶著**單帳號時代留下的根層欄位**。
⇒ **今天第三次同一個模式**（另兩次：config 缺 manifest 靠舊檔補齊、
   啟動 log 用根層組出 `/webhooks/named//…`）。
修：抽出 `accountsConnected()`＝「根層有 **或** 任一帳號有」，並補測試
（刻意用「只有 accounts、根層全空」＝全新使用者的形狀）。

## 順帶：那句話還指錯路
訊息叫人「點托盤選單的『＋ 新增帳號…』」——**托盤選單早就只剩「結束 Arcrun」**
（t194 起所有設定都在視窗裡）⇒ 使用者照著做會找不到入口。
改指「左邊『知識庫』下方的新增知識庫帳號」。

## 順帶修我自己的測試腳本（leo 實撞）
`① 測試最新版.bat` 用 `dir /o-d`（修改時間）挑版本 ⇒ 複製到共用資料夾後
時間順序不一定等於版本順序，**leo 那次挑到了 v0.18.13**。
改用 `dir /on`（檔名排序）取最後一個。
另把「固定等 20 秒」改成「等你操作完按 Enter 再收 log」——
清空後第一次跑，引擎本來就不該啟動，等 20 秒收到的是空的。

## 附帶確認（leo 截圖）
- 「有 1 個檔案沒有被整理」**已列出檔名**（`scripts/sdd-active-check.sh`）⇒ 08-06 那個修正生效
- Portal 庫目錄管理三個庫都在（含 Windows 的 `win_on_mac_test_lib`）⇒ 子庫沒出現是假警報
 2026-08-06 19:57:05 +08:00
Leo 458ff3fd88 v0.18.14/15：全新使用者連上知識庫後會自己開始＋log 不再印不存在的網址 
leo 08-06 用共用資料夾實測，兩張圖把最後一個病逼出來：
「第一次直接跑可以，**清空再來一次，就不跑了**」。

## 真兇：restartWatch 第一行就早退
全新使用者的順序是：
  ① 打開程式（**還沒有任何設定**）⇒ startSupervisor 早退，`sup` 是 nil
  ② 連上知識庫、加資料夾 ⇒ restartWatch
  ③ 舊版：`if sup == nil { return }` ⇒ **什麼都沒發生**
  ⇒ 引擎永遠不啟動，畫面叫人「請結束 Arcrun 再重新開啟」
「不算錯」（重開真的會好），但等於要求剛裝好的人自己想到去重開程式。
**每一個第一次用的人都會撞到**；開發機永遠有設定，所以永遠測不到。

修：`sup == nil` 時**現場建立**（設定剛出現，正是該啟動的時機）。
新測試 `TestFirstRunStartsEngineAfterConnect` 從「沒有設定」開始走完整順序；
反向驗證拿掉即紅。

## 順帶把那句沒用的話拿掉
「請結束 Arcrun 再重新開啟」＝把系統的無能推給使用者。
改成「正在啟動同步引擎，請稍候…」；還沒連知識庫時說
「按『新增知識庫帳號』就會開始」。

## log 不再說謊（今天第三次同一個主題）
啟動訊息印 `cfg.triggerURL(...)`＝用**根層**的 cypher_url/namespace 組的，
而多帳號設定根層是空的 ⇒ 印出 `→ /webhooks/named//rag_ingest/trigger`
（沒網域、雙斜線）**看起來像設定壞了，其實功能正常**。
改印每個帳號真正會用到的網址。

## 實測證據（共用資料夾自動收回來的 log，非截圖轉述）
  19:13:54  設定檔缺必填欄位，已自動補上 manifest=C:\Users\leo21\.arcrun-rag\manifest.json
  19:13:55  collector direct daemon 啟動：監看 …\win_on_mac_test_lib  {"phase":"start"}
⇒ v0.18.13 的自我修復在真機生效，config 已補上 manifest，collector 真的跑起來。
 2026-08-06 19:33:36 +08:00
Leo 8dc9a2ee85 v0.18.13：舊設定檔自我修復——我第一次修錯了，只修好全新安裝 
leo 裝了 v0.18.12 **仍然是同一句錯**（實拍：重試 30 次、
「collector direct: config 缺必填欄位：manifest」），並提供了他的 config.json。

## 我錯在哪
v0.18.11 只在 `saveCfg`（存檔）補必填欄位。但使用者打開程式時
**只是「讀 config → 啟動引擎」，saveCfg 根本不會被呼叫**
⇒ 已經存在的壞設定永遠修不好。全新安裝好了，**現有使用者一個都沒被救到**。

leo 的 config 鐵證：頂層只有 `accounts`／`extractor`／`extractor_explicit`／
`gemini_api_key` —— **正好是 saveCfg 寫的那四個鍵**，沒有 manifest。

## 為什麼我的測試沒抓到
`TestFreshInstallCollectorStarts` 是**從 saveCfg 出發**建 config ——
它測的是「我修的那條路」，不是「leo 正在走的那條路」。
**測試照著修正寫，就只會證明修正存在，不會證明問題解決。**

## 這版
- `fillRequired()` 抽出來，**讀取時也補**（升級路徑）＋存檔時也補（新建路徑）
- 讀取時補完**寫回磁碟**——collector 是另一個行程，讀的是磁碟那份不是記憶體
- 補完寫進 app.log 留痕

## 驗
新測試 `TestExistingBrokenConfigSelfHeals` **從磁碟上已存在的壞 config 出發**
（內容逐字取自 leo 那份，只把值改假），驗三件：讀取後磁碟上有 manifest、
JSON 仍合法、**真的把執行檔當 collector 跑起來不再 exit 2**。
反向驗證：拿掉自我修復即紅（訊息就是 leo 撞到的那句）。全套測試綠。

⚠️ 更正 changelog：v0.18.11 原本寫「已經裝過舊版的人不用做任何事，更新後會自動補好」
   —— **那句是假的**，已改成指向本版。
 2026-08-06 18:58:31 +08:00
Leo a22d4e4436 端到端驗證：全新安裝真的跑得起同步引擎（自己驗，不推給 leo） 
自走警察點破：我把「在 Windows 全新裝一次確認」推給 leo，但這件事我自己驗得了。

新增 `TestFreshInstallCollectorStarts`：
全新 HOME → App 的 saveCfg 存 config → **編出真正的執行檔、用 `--collector direct
--once --dry-run` 把它自己跑起來** → 斷言不是 exit 2、輸出沒有「缺必填欄位」。

為什麼要再加這支（已經有 LoadDirectConfig 那支了）：
**「函式回傳 nil」與「行程活得下去」是兩件事**——事故正是死在後者。

反向驗證（拿掉修正）重現 leo 截圖上那句一字不差的訊息：
    collector direct: config 缺必填欄位：manifest
⇒ 這支不是假測試。修正放回後全套綠。

順帶修測試自身的坑：先 `go build` 再改 HOME——先改 HOME 會讓 Go 把**唯讀的**
模組快取寫進暫存目錄，測試結束清不掉（TempDir RemoveAll permission denied）。

剩下真正只有 Windows 能驗的：實機安裝後的行為（托盤/畫面），已列 CP 待辦。
 2026-08-06 18:54:14 +08:00
Leo 9f64615cfd v0.18.12：出問題時一鍵打開紀錄檔資料夾（leo：「不能用一個 debug mode？」） 
leo 08-06：「不能用一個 debug mode，就是它會把 log 寫在一個檔案？」

## 回答：log 一直都在寫，缺的是「找得到」
`~/.arcrun-rag/collector.log`（含 collector 的 stderr，以 `[stderr]` 開頭）
與 `app.log` 從 t14 就在寫。這次 Windows 事故的真正死因
（`config 缺必填欄位：manifest`）**一直躺在 collector.log 裡**，
但使用者只看得到畫面上一句話，沒有任何入口通到那些檔案。

⇒ **不做「debug mode 開關」**（多一個要教使用者的東西，而且出事當下才想到要開就來不及了），
   改成**永遠寫、出事時一鍵打開**：
- `OpenLogFolder()` 綁定（Windows 走 explorer／Mac 走 open／其餘 xdg-open）
- 首頁在 `engineTrouble` 時才長出「需要回報這個問題？」卡，附按鈕與**路徑文字**
  （按鈕失效時仍找得到）。沒事時不顯示——否則會變常駐噪音，真出事反而沒人看。

## 真機證據：v0.18.10 的「說出死因」有效
leo 的 Windows 畫面實拍：
  「同步引擎一直啟動失敗 / 已自動重試 8 次都失敗，所以重新開啟也沒有用。
    原因：collector direct: config 缺必填欄位：manifest（exit status 2）」
⇒ **與 v0.18.11 修的根因一字不差**，診斷鏈完整閉合：
   症狀（閃爍）→ 機制（子行程 exit 2 無限重拉）→ 死因（config 缺 manifest）→ 修正。
 2026-08-06 18:47:17 +08:00
Leo fcf00bb5df v0.18.11：修好 Windows「裝了完全不會動」的真兇——全新 config 缺 manifest 欄位 
leo 08-06 提供決定性線索：**exit status 2，已自動重試 21 次失敗**。

## 真兇
`app.go` 的 `saveCfg` 只寫四個鍵（accounts／extractor／extractor_explicit／
gemini_api_key），**從來不寫 `manifest`**。
而 `manifest` 是 collector 的必填欄位（`direct.go`：
`if c.Manifest == "" { missing = append(missing, "manifest") }`）
⇒ 讀 config 失敗 → `runDirect` 回 2 → supervisor 無限重拉
⇒ ①「看守中／沒有在跑」一直閃、重開無效（死因沒變）
⇒ ②加資料夾沒反應（collector 從沒跑完一輪）

## 為什麼一路活到封測
**開發機的 config 是舊版留下的、早就有這一欄。**
只有「從零長出 config」的機器才會撞到——也就是**每一台封測者的機器**。
「我這台好好的」正是這個 bug 能活下來的原因。
⇒ 新測試 `TestFreshConfigIsUsableByCollector` **從零建 config**，
   並且不只驗欄位在不在，而是**真的餵給 `collector.LoadDirectConfig`**。
   已反向驗證：把修正拿掉，測試會紅（不是假測試）。

## 順帶修好「為什麼只看得到 exit status 2」
supervisor 在行程結束時用 `cmd.Wait()` 的錯誤當訊息，
**蓋掉**了 stderr 剛寫進 `LastError` 的那句真話
（`collector direct: config 缺必填欄位：manifest`）。
⇒ 改成以 stderr 為主、退出碼放括號補充。
（v0.18.10 已讓死因上畫面＋進 app.log，這版讓那句話是**對的**那一句。）

## 三種 exit 2 的實測輸出（重現測試打出來的，非推測）
- config 不是合法 JSON → `config JSON 解析失敗：invalid character …`
- 缺必填欄位 → `config 缺必填欄位：manifest, accounts（或 cypher_url 連線設定）`
- Windows 反斜線路徑 → 正常解析（**排除「反斜線害的」這個猜測**）

## 驗
collector 全測試過、app 測試過、mac+windows 皆編得過；
產物 `Arcrun-win-v0.18.11.exe`（22M）已放 leo 桌面。
⚠️ **尚未真機驗**——要 leo 在 Windows 全新裝一次才算通。
 2026-08-06 18:41:31 +08:00
Leo 6698f9fbda v0.18.10：讓「同步引擎沒在跑」說出死因（leo Windows 實測①②的診斷前置） 
leo 08-06 Windows 回報：「一直在『看守中』和『沒有在跑』中間閃，要我重啟但重啟無效，
我覺得它在跑個迴圈不停重複」＋「加一個資料夾明顯沒產生看守資料夾」。
朋友的一般 PC（非 ARM）也一樣，停在等待中 ⇒ **不是 ARM 模擬的問題，是 Windows 通用**。

## 已定位的機制（不是根因，是「為什麼查不出根因」）
閃爍＝子行程一啟動就死 → supervisor 退避重拉 → 狀態在 Starting（alive=true）與
Error（false）之間彈跳 ⇒ 畫面跟著閃。而**死因一直被記在 Status().LastError 裡，
從來沒有上過畫面、也沒寫進 app.log** ⇒ 使用者只看到閃爍與「請重新開啟」，
重開當然無效（死因沒變）。這是「安靜地略過」的同一種病換地方發作。

## 這版做的
- 死因上畫面：重試 >= 3 次改顯示「同步引擎一直啟動失敗，已自動重試 N 次｜原因：…」，
  且**黏住不閃**（不受重起過程中的 Starting 影響）
- 每次異常結束寫進 app.log（同錯誤 10 次內只記一次，避免洗爆）

## 排除掉的嫌疑（查過，不是）
- PDF 引擎（pdfium/wasm）：**延遲初始化**，第一次讀 PDF 才啟動 ⇒ 不會在啟動時炸
- ARM 模擬：leo 朋友的一般 x64 PC 同樣症狀
- 待查嫌疑：Wails 的 Windows 版是 `-H windowsgui`（GUI subsystem，無主控台），
  而 v0.18.8 的 collector.exe 是 `go build` 的 console subsystem——
  v0.18.9 合併成單一 binary 後，子行程換成 GUI subsystem 的自己。**尚未證實。**

## 順帶修好自己的閘（它擋對了我）
指紋閘擋下「v0.18.10 已對應另一份原始碼」——因為第一次打包失敗、版號卻已被戳。
⇒ 加判準：**磁碟上沒有該版號產物＝從未出貨，允許重戳**（不用去手改 JSON，
那種爛示範遲早被改成「都放行」）。

## 安裝程式（leo ③）尚未兌現，誠實記錄
`wails build -nsis` 需要 makensis；Homebrew 的 3.12 在這台 macOS **連兩行的最小腳本
都在寫檔階段丟 std::bad_alloc**，zlib/bzip2/lzma 三壓縮器全崩，brew extract 舊版
被 homebrew/core 擋。且帶 -nsis 會讓 wails 整個中止、連 exe 都不產
⇒ build-win.sh 改成**先煙霧測試 makensis**，壞的就只出裸 exe 並大聲警告。
 2026-08-06 18:27:08 +08:00
Leo 0b8bc83bd1 版本指紋閘（同一版號只准一份原始碼，實測有效）＋落帳封測兩病與 md 真相 2026-08-06 16:17:40 +08:00
Leo 67effe3b7f 首頁「沒被整理的檔案」修兩病：同一件事講兩次／不說是哪一個檔 
leo 08-06 封測回報（附截圖＋「他放一個 md 檔無法通過」）。

## ① 同一件事講兩次，而且「另外」前面沒有東西
截圖實況：
  「看起來不是文件，所以跳過了。」   ← 底下是空的（非文件檔不逐檔點名）
  「**另外**有 1 個不是文件的檔案（圖片、影片、壓縮檔之類）也沒有處理。」
真兇：app.go buildSkipped 的 else 分支先寫一句通用說明，
接著無條件再寫 Other 那句——後者的「另外」是為「兩種都有」寫的，
在「只有非文件檔」時就變成前面沒有東西可以「另外」。
解：該分支只講一句、自己帶數量，且不留 Other。「另外」只在兩種都有時出現。

## ② 只報總數＝等於沒說（這才是 md 那題卡住的原因）
封測者放 .md 說「無法通過」，但畫面只寫「有 1 個不是文件的檔案」，
**沒說是哪一個** ⇒ 誰也判斷不出發生什麼事。
而 `.md` 明明在 allowedExt 白名單裡（scan.go:26），我在本機實測也一次就過：
    "path":"arcrun-md-test.md","status":"ingested","http_status":200
⇒ 那個「1 個」必然不是他以為的那個檔（副檔名被 Windows 藏起來、存成別的格式…），
  但沒有檔名就永遠查不出來。
解：scan 收集非文件檔的檔名（上限 5 個），一路帶到 status.json 與首頁。
「只報總數」在幾百張圖時是對的，在 1 個時是失職——少量就點名。

## 驗
· 兩支新測試釘住規則：只有非文件檔時不准出現第二句、不准出現「另外」；
  兩種都有時「另外」才成立並帶數量
· 實際文案打出來看過（見下），不是只看測試綠
    有 1 個檔案沒有被整理
    看起來不是文件（圖片、影片、壓縮檔之類），所以跳過了。這是正常的，你不用做什麼。
      · 我的筆記.md.txt
· 312 張圖的情況：列 5 個 +「…還有 307 個」，不洗版
· collector 全測試過、app 測試過、go vet 全綠
 2026-08-06 16:12:01 +08:00
Leo 4d3a6a09a6 v0.18.9：collector 併進同一支執行檔——磁碟上不再攤出第二支 exe 
leo 08-06 裁決：「不要兩支，寫成一支檔案」。

## 為什麼
v0.18.7-8 的「單一 exe」其實是**一支包著另一支**：collector.exe 被 go:embed
進 Arcrun.exe，執行時攤到 ~/.arcrun-rag/bin/ 再跑。
那正是防毒軟體眼中的 dropper 特徵 —— 封測者實撞
`Trojan:Win32/Sabsik.FL.A!ml`，檔案當場被隔離、自動刪除。

⚠️ 誠實界定：`!ml` 結尾＝**機器學習判定**，Sabsik 是最常見的通用誤判家族，
   主因是「未簽章＋下載次數少」，**不是**特別指向 dropper 行為。
   所以本次改動**不保證**解除誤判——真正的解是上架 MS Store（微軟簽章）。
   但「執行時把第二支 PE 寫到磁碟再執行」本來就該拿掉，這是對的方向且順手變小。

## 怎麼做
- `collector/` 39 個檔 `package main` → `package collector`，`main()` → 匯出的 `Run(args) int`
- 新增 `collector/cmd/collector/`（薄殼 CLI，讓單獨跑 collector 這條路仍可用）
- App 直接 import 該套件；`main()` 第一件事就判 `--collector`，是的話走 `collector.Run` 不碰 GUI
- `supervisor` 加 `ArgPrefix`，App 把 `BinPath` 指向 `os.Executable()` 自己
- 刪掉 `bundled_collector_{windows,other}.go`（embed + 攤檔那套）
- 三支打包腳本不再編/複製第二支；版本注入同時打到兩個 package
- build-win.sh 的機械閘改成**直接問它**：`--collector --version` 回得出版本才放行
  （舊閘是比大小，只能證明「有 embed」，證明不了「分派是對的」）

## 驗（真機實跑）
· `.app/Contents/MacOS/` 只有 **一個** 執行檔（原本兩個）
· 跑起來兩個行程是**同一個 exe**：
    …/MacOS/arcrun-app
    …/MacOS/arcrun-app --collector direct --config …
· `~/.arcrun-rag/bin` **不存在**（沒有任何東西被攤出來）
· 端到端：丟檔進看守資料夾 → collector.log `"status":"ingested","http_status":200`
· `lsappinfo` 仍是 `type="UIElement"`、`Version="0.18.9"`
· collector 39 檔測試全過；app 測試過；go vet 全綠；mac + windows 交叉編譯皆過
· 單檔 26MB → 22MB（不再夾帶第二份完整程式）
 2026-08-06 16:00:47 +08:00
Leo f4eb3c9fa1 Mac 四修：Dock 不再重複／結束真的會結束／全螢幕可用／視窗 70% 
leo 08-06 Mac 實測回報。四個都是**只在 Mac 現形**的病。

## ① Dock 與選單列兩邊都顯示（連帶：只有 Arcrun 列在強制結束清單）
真兇：Wails 在 AppDelegate.m:44 applicationWillFinishLaunching 硬設
`setActivationPolicy:Regular`，**runtime 蓋掉 Info.plist 的 LSUIElement**
（後者只決定啟動當下的初始 policy）。而 v2.13 的 mac.ActivationPolicy 是註解掉的。
🔴 **這件事 fyne 版 604704a（07-24）已經解過且真機驗證通過**，換 Wails 時整段掉了；
   wiki mistakes.md:124 也早就記著同一條。**本次是取回原版，不是重新發明**——
   dock_darwin.go／dock_other.go 逐字沿用，只更新註解說明 Wails 死法相同。

## ② 托盤右鍵「結束 Arcrun」點了不會結束
leo：「唯一結束法是強制結束…因為舊版沒結束導致無法覆蓋，
      **如果不知道怎麼強制結束的人就放棄了**」
真兇：Wails 的 runtime.Quit() 與「按 ×」**共用同一個 OnBeforeClose**
（frontend.go:364 `if !OnBeforeClose(ctx) { mainWindow.Quit() }`），
我們無條件回 true ⇒ mainWindow.Quit() 永遠不執行，還順手 WindowHide
⇒ 看起來像關了、其實行程還活著。
（AppDelegate.m:41 的 applicationShouldTerminate 也一律回 NSTerminateCancel，
  決定權整個在這個回呼 ⇒ 回 true 就沒有任何出口。）
解：quitting 旗標區分兩者，並抽出 closeMeansHide()/beginQuit() 讓它**可機械驗證**。

## ③ Mac 全螢幕（綠色）按鈕被停用
真兇同樣在 Wails：window.go:92 `zoomable` 只在 `frontendOptions.Mac != nil` 時賦值，
我們沒設 Mac ⇒ zoomable 維持零值 false ⇒ WailsContext.m:208
`if (!zoomable && resizable) { [zoomButton setEnabled:NO]; }`。Windows 無此段。
解：`Mac: &mac.Options{}`（空的即可，DisableZoom 預設 false）。

## ④ 視窗 50% 太小
leo：「Google Drive 大約螢幕長寬的 70%，改成 50% 後顯得太小」⇒ 常數 screenFraction=0.70。
並加 appLog 留痕（螢幕多大、算出多大），以後不必請人量像素。

## 驗（本機真機實跑，非推測）
· `lsappinfo` → **type="UIElement"**、Version="0.18.8"
  ＝ 604704a 當年用的同一個驗法，通過 ⇒ Dock 無 icon、不列強制結束
· 截圖放大號誌燈 → **綠燈是彩色的（enabled）**，停用時會是灰色
· app.log 自報 → **視窗依螢幕 1470x956 設為 1029x669（70%）**
· 首頁顯示「看守中·資料夾有變動就會自動整理／已整理 1 份」＝判活正常
· go test TestCloseMeansHide 通過（釘住「按×要隱藏、按結束要放行」）
· go vet 全綠；mac build + windows 交叉編譯皆 OK
· **未驗**：托盤右鍵實際點擊（osascript 缺輔助取用權限，點不到選單列）
  ⇒ 邏輯已單元測試＋原始碼追到底，但**實際點擊歸 leo 真機**
 2026-08-06 14:11:49 +08:00
Leo b783b870e6 版本號改由 changelog 決定：從頭到尾沒有人打過數字，且與更新內容天生綁定 
## 為什麼推翻自己幾小時前的做法
上一版用「動過 collector/ 的 commit 數」當 patch。確實不用手打，但
**每個 commit 都變成一版**（一天 5 個 commit 就跳 5 版），
每跳一版還要補一段 changelog ⇒ 把機械化變成新的手工活。leo 要的不是這個。

## 現在的機制（daemon-version.py）
單一真相源＝docs-site/.../help/changelog.md：
  · 要出新版 ⇒ 最上面加一段 `## 下一版（未發佈）`，底下寫白話更新內容
  · 打包時腳本把它**戳成正式版號**（上一版 patch+1）並補今天日期
  · 沒有「未發佈」段 ⇒ 版本＝最上面那一版（重打同一版，冪等不虛增）
⇒ 版本號沒有人打過；且不可能「升了版卻沒人知道改什麼」，
  也不可能「寫了內容卻忘了升版」——兩者出自同一段文字。
換線（0.18→0.19）只改 DAEMON_LINE，下一版自動從 0.19.0 起。
刪掉 daemon-version.sh 與 DAEMON_PATCH_BASE（一版的殘留）。

## 驗（實測輸出）
· `## 下一版（未發佈）` --stamp→ `## v0.18.7（2026-08-06）`（腳本自己改的）
· 沒有未發佈段時重跑 → 仍回 v0.18.7（冪等，不虛增）
· ./build-win.sh 全程通 → dist/Arcrun-win-v0.18.7.exe（27,445,248 bytes）
    strings 抽內嵌版本 = v0.18.7
· ./build-dmg.sh 全程通 → dist/Arcrun-v0.18.7.dmg（10M）
    掛載後 strings 抽 App 內嵌版本 = v0.18.7
    Info.plist CFBundleShortVersionString = 0.18.7（以前永遠是 1.0.0）
⇒ **兩條打包線第一次在同一個版本號上對齊**——這正是 08-06 那個病
  （只重打 Mac DMG、Windows 沒動、manifest 卻宣告新版）的根治。
· 未驗：Windows／Mac 真機行為；未出貨 ⇒ ◐
 2026-08-06 13:16:14 +08:00
Leo be817b3c16 更新內容機械化＋manifest 補上「宣告版本==產物版本」的閘＋前端顯示同步器版本 
回應 leo 08-06 兩問與兩項新需求。

## ①「更新內容還要寫在 docs 裡，機械化要怎麼做」
答：改的是「寫在哪」，不是「誰來寫」。
- 單一真相源＝docs-site/.../help/changelog.md（本來就存在，用戶語言那份）
- 新增 changelog-section.sh：抽出某版段落（供 manifest.notes 投影用）
  ＋ --check 模式當閘
- build-win.sh／build-mac.sh 接上閘：**changelog 找不到這版段落 ⇒ 中止打包**
  ⇒「忘了寫更新內容」變成不可能，而不是靠誰記得
- 已寫 v0.18.8 的用戶語言版本說明（本次五修）

## ② manifest 的閘：這次的病是從兩條規則中間的縫穿過去的
verifyManifest 對 daemon 只驗 ①version 欄在不在 ②file 指的檔存不存在。
08-06 那次**兩條都過**（宣告 v0.18.5、`-v0.18.4.zip` 檔案真的存在）⇒ 全綠放行。
新增第三條：宣告版本必須等於產物真正的版本
  (a) 檔名要帶宣告的版本（光這條就足以擋下 08-06 那次）
  (b) .exe 再驗一層：版本字串要真的在二進位裡（檔名可改，內嵌版本改不了）

實測（用當時的真實 manifest 值重現）：
  · 宣告 v0.18.5 + 檔名 -v0.18.4.zip → ❌ 擋下（mac/win 各一條）
  · 檔名改成 v0.18.8 但內容是 v0.18.7 那顆 → ❌ 擋下（規則 b）

## ③ 前端顯示同步器版本＋下載入口
leo：「連我都沒辦法確認，所以用戶到底是否最新版他自己也不知道」
- /api/latest 新增 daemon 欄（version/notes/downloads），由 daemonOf(env) 讀釘點
  manifest——與 releaseOf 同原則同真相源，不留手抄本。
  下載網址走 raw + 釘點 sha，與 selfupdate.go:158 同源（不自創第二條路）。
- rag.arcrun.dev 步驟 4 補上**真的下載按鈕**（Win/Mac）＋同步器版本＋
  「這一版改了什麼」連結。以前這裡只有文案提到下載、沒有連結也沒有版本。
  取不到就顯示「（查詢中）」並退回安裝說明頁——沿用 bf06ed7 的原則，不留手抄值。

## 驗
· node --check worker.js（installer/landing）皆 OK
· changelog 閘：v0.18.6 通過；不存在的 v0.18.7 → 退出碼 1 並印出可照抄的範本
· manifest 三條規則實測如上
· 未驗：線上畫面（要出貨後才有 daemon 欄位）⇒ ◐，不是 ✅
 2026-08-06 13:12:48 +08:00
Leo a55488040d Windows 交付改單一 exe＋版本號不再手打（leo 08-06 回報②與「整串該機械化」） 
## ② 兩個檔很迷惑 → 一個檔
leo 圖一標註：「下載還是 ZIP ⇒ 應該是 MSIX 或 EXE；解開還是 2 個檔 ⇒ 應該只有 1 個檔案」。
舊做法 zip 裡放 Arcrun.exe＋arcrun-collector.exe 同層，少解一個檔就永遠不會同步，
而畫面不會說是這個原因。
修：collector 用 go:embed 收進 Arcrun.exe，第一次執行攤到 ~/.arcrun-rag/bin/
    （冪等：sha256 相同不重寫；先寫暫存再 rename，避免留半截執行檔）。
    build-win.sh 直接產單一 Arcrun-win-<ver>.exe，不再打 zip。
    加機械閘：產出的 exe 若比 collector 還小 ⇒ 沒 embed 成功 ⇒ 中止（過去只會
    默默得到一顆「裝了也不會同步」的空殼）。
不走 MSIX：未上架的 MSIX 要使用者先開「開發人員模式」，比 zip 更麻煩。

## 版本號機械化（leo：「這一整串都應該是機械化，不應該每次手工做」）
病根實測：本 repo **一個 git tag 都沒有**，而四支 build 腳本寫的是
`git describe --tags` ⇒ 永遠拿不到 v0.18.x ⇒ 只能靠打包時人工敲 VERSION=
⇒ 兩條打包線各敲各的 ⇒ manifest 宣告 0.18.5、產物其實是 0.18.4。

修：新增 daemon-version.sh 當唯一產生器，沿用 release.mjs 已在跑的原則
   （「版本號由內容算出來，不是由人宣告」），不另立新制：
     MINOR ← DAEMON_LINE（人決定，大改版才動）
     PATCH ← 動過 collector/ 的 commit 數 − DAEMON_PATCH_BASE（機器決定）
   ⇒ 沒改 daemon 重跑打包不會虛增；改了才 +1；四支腳本在同一 commit 必得同號。
   ⇒ 不需要 git tag／Actions／輪詢（守 D20 紅線）。
   校準：DAEMON_LINE=0.18、BASE=87 ⇒ 現在的樹算出 v0.18.7（上次出貨過 0.18.6）。
   build-win/mac/dmg/msix 四支全部改用它。

## icon 漂移根治接上打包
build-win.sh 步驟⓪ 每次都跑 gen-icons.py 重產 icon.ico／trayicon.ico。

## 驗（實測輸出，非推測）
· ./build-win.sh 全程跑通，產出 dist/Arcrun-win-v0.18.7.exe（27,445,248 bytes）
· strings 抽內嵌版本 = v0.18.7、buildTime = 20260806-1233（機器算的，沒人敲）
· 位元組比對該 exe：
    CIS trayicon 在裡面        = True
    Wails「W」圖還在           = False
    collector 有 embed 進去    = True（16,104,960 bytes）
· go vet 全綠（darwin + windows）；mac build OK
· 未驗：Windows 真機行為（需封測者實跑）⇒ 狀態 ◐，不是 ✅
· 未做：CHANGELOG 閘、manifest「宣告版本 == 產物版本」驗證閘、前端顯示版本與下載入口
 2026-08-06 12:35:54 +08:00
Leo ee2fc2a803 Windows 三修：不再無限多開／首頁不再謊報「引擎沒在跑」／視窗改螢幕 50% 
leo 08-06 封測回報①④＋圖三標註。三個都是**只在 Windows 現形**的病。

## ④ 托盤一次開好幾個 icon
leo：「點一次開一個新的，測試者原本給我看顯示到 4 個」。
真兇：main.go 的 options.App 沒設 SingleInstanceLock（Wails v2.13 有這選項）。
每個實例還各自拉一份 collector 子行程。
macOS 由 LaunchServices 天然單實例 ⇒ Mac 上驗不出來。
修：加 SingleInstanceLock，第二次啟動叫醒既有視窗後自己退出。

## ① 根本不運行（首頁恆顯示「同步引擎沒有在跑」）
真兇：collectorAlive() 的憑據是 `pgrep -f <bin>`，**Windows 沒有 pgrep**
⇒ 恆回 false ⇒ app.go:356 一定走「同步引擎沒有在跑」，與實際狀態無關。
修：憑據換成 supervisor 自己的狀態機（親手拉起的子行程、runOnce 以 cmd.Wait 收尾）
    ——比掃行程表更有憑據且跨平台，順帶修掉 pgrep 會匹配到別的實例的偽陽性。
⚠️ 不是發明第三種判斷法：db17f28（08-05）已為「同步中」立下同一條路
   「改讀 sup.Status().State ⇒ 接回既有機制，不發明第三種判斷法」，
   當時只改了 collectorSyncing 那半邊，這裡把漏掉的 collectorAlive 補上。
順帶移除 waitCollectorGone/pkill：翻 supervisor 原始碼確認 Stop() 回來時
子行程已被 cmd.Wait 收屍完畢，補刀多餘；且那兩支指令 Windows 根本沒有。

## 視窗高度擠出畫面
leo 圖三：「視窗尺寸應該是 default 50% 螢幕長寬，高度太高快擠到外面了」。
修：OnStartup 依 ScreenGetAll 算 50% 並置中；保底值 1000x700 → 960x600
    （拿不到螢幕資訊時不瞎猜，沿用保底值）。

## 驗（實測輸出）
· go vet 全綠（darwin + GOOS=windows 各一次）
· mac build OK；GOOS=windows CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc 交叉編譯 OK
· 位元組比對交叉編譯出的 .exe：
    新 CIS trayicon.ico 在 exe 裡 = True
    舊 Wails「W」圖在 exe 裡    = False
· 未驗：Windows 真機行為（需重打包後由封測者確認）⇒ 狀態 ◐，不是 ✅
 2026-08-06 12:20:25 +08:00
Leo 051c865085 Windows 版 icon 換回 CIS chevron，並根治「換了 appicon 卻沒換 Windows」 
leo 08-06 封測回報：托盤與視窗 icon 是「W」，不是 CIS 的 chevron。

真兇：build/windows/icon.ico 是 wails init 生成後從沒被動過的 Wails 預設圖。
換 CIS logo 那次只換了 build/appicon.png，Windows 這顆沒人碰；
tray_windows.go 又 embed 同一顆 ⇒ 視窗與托盤兩處都是 W。
macOS 走 trayicon.png（正確）⇒ 這個病在 Mac 上 100% 驗不出來。

改法不是「這次手動換一顆」，是讓它不可能再漂移：
- 新增 gen-icons.py：兩顆 .ico 一律由 appicon.png 現場產生；
  --check 模式比對「committed == 重新產生的」，可當機械閘。
- tray_windows.go 改 embed build/trayicon.ico（小尺寸階梯，系統匣只吃 16/32）。

已驗：重新產生後把 256/32 都渲成 PNG 目視確認為 CIS chevron；--check 通過。
未驗：Windows 真機（需重打包後由封測者確認）⇒ 狀態 ◐，不是 ✅。

同時落帳（wiki status/mistakes）：
- manifest 宣告 v0.18.5 但產物是 v0.18.4 的完整證據鏈
- 五個 Windows 真兇（檔:行）
- leo 兩問的設計定案：trigger=內容指紋（不另立、不用 tag/Actions）、
  changelog 單一真相源=CHANGELOG.md 其餘全投影
- 這次穿過機械閘的那道縫：缺「宣告版本 == 產物內嵌版本」的驗證
 2026-08-06 12:09:53 +08:00
Leo 9cd0adab22 G-6.2：讀不了的檔案不再安靜消失——首頁當場說出來 
服務 J-1 / S6「我丟進去的檔案，查得到」的考題 G-6.2：
「要嘛查得到，要嘛**當場被告知這種檔案還不支援**，不准安靜地略過。」
本次只做後半句（轉檔本體另有人閘，等 leo 裁「那段 Go 住哪裡」）。

## 真實現況比記載更糟
t16 寫的「PDF 被靜默略過」已不成立（t73 的轉檔層把 pdf/docx/xlsx/csv/pptx
都接上了，實測 2 頁中文 PDF 完整抽出）。**真正還在沉默的是別的東西**：
副檔名不在 allowedExt 的檔案在 scan.go 直接 `return nil`——
不進事件、不進 manifest、不進 status、不進畫面。
使用者丟一份 .doc 進去，從頭到尾一個字都沒有。

實測基線（真檔）：丟 .pdf/.md/.doc/.key/.jpg 進資料夾，
`collector scan` 只吐出 pdf 與 md 兩個事件，另外三個檔沒留下任何痕跡。

## 改了什麼
- scan.go：白名單閘不再是死巷。像文件的（.doc/.xls/.ppt/.pages/.key/
  .numbers/.odt/.ods/.odp/.rtf/.epub/.wpd/.msg/.eml）逐檔留名；
  其餘（圖片/影音/程式碼）只計總數——**避免 Obsidian 附件庫炸出幾百行噪音**。
- 兩個新欄位標 `json:"-"`：collector-trigger schema 是
  additionalProperties:false，且 BuildSendablePayload 是淺拷貝
  ⇒ 有 tag 就會漏到雲端被擋。這是給本機使用者看的，不上 wire。
- direct.go → status.json → App 首頁一張卡：講檔名與格式（「舊版報告.doc
  （舊版 Word）」），並告訴他不用重丟、也給替代路（另存成 PDF/.docx）。
- 刻意不進 manifest、不走 CarryForwardActivity：每輪由檔案系統重算，
  不製造 t195 那種「跨輪欄位漏 carry 就靜默歸零」的債。

## 順手修掉一個會讓驗收失效的回歸
同綑的 arcrun-collector 一路自稱 `dev`：退役 fyne 版
（arcrun-tray/build-mac.sh:24，t150／t72）本來就有版本注入，
t194 換 Wails 時沒帶過來，Mac 與 Windows 兩邊都掉。
**幹活的是 collector**——它不報版本，就沒人能判斷修復有沒有到使用者手上。

## 實測
- go test ./... 135 過 0 敗（新增 10 條：scan 5＋首頁文案 5）
- check-cis / check-render / check-tray 三閘全過；淺色深色都抓過畫面
- 從 **DMG 裡那支** collector 實跑：Info.plist 0.18.6、
  collector 回報 v0.18.6 (build 20260806-0101)、
  status.json 吐出 skipped_docs=[簡報.key, 舊版報告.doc]、other=1

⚠️ 未出貨：推 bundles repo 在 GitHub，要 leo 開 D20 閘。
DMG 已備妥 dist/Arcrun-v0.18.6.dmg。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-06 01:04:25 +08:00
Leo f32e82bab5 清掉三個假 Arcrun：退役 fyne 版 .app 不再進版控 
leo 08-05：Launchpad 搜 arc 跑出 4 個 Arcrun，「這很奇怪」。

## 實查：只有一個是真的
  /Applications/Arcrun.app                        v0.18.5  ← 真正安裝的
  collector/cmd/arcrun-app/build/bin/Arcrun.app   v0.18.5  ← 建置產物（未版控）
  collector/cmd/arcrun-tray/Arcrun.app            v0.0.1   ← **退役 fyne 版，被 commit 進 repo**
  collector/cmd/arcrun-tray/Arcrun RAG.app        v0.0.1   ← 同上，更舊的名字

Spotlight 索引磁碟上任何 .app ⇒ repo 裡的產物全冒到 Launchpad。
危險在於**點到 v0.0.1 那兩個就是 t184 的病**（在非 /Applications 執行 ⇒ 更新不了），
等於我們自己的 repo 天天在給用戶擺陷阱。

## 處置
· git rm 兩個 v0.0.1 的 .app（build 產物本來就不該版控；Wails 換代後 arcrun-tray 已退役）
· 刪掉磁碟上三個非安裝版本
· .gitignore 加 collector/cmd/**/*.app
· 兩個 build 目錄放 .metadata_never_index，讓 Spotlight 不再索引產物

驗：mdfind 'Arcrun*.app' 現在只回 /Applications/Arcrun.app 一個。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 18:47:57 +08:00
Leo 6bf0daa786 修首頁狀態說謊＋DMG 補上拖曳版面（leo 08-05 封測回報 ①②） 
## ② 首頁狀態是壞的
leo：「拖新的檔案進資料夾，完成本地萃取、上傳，但自始至終 daemon 的首頁都顯示
『有變動就自動開始』『等待中』，都顯示綠燈沒動，實際上已經做完了。」

兩個獨立的真兇：

**A. 「同步中」判斷用錯依據（回歸）**
t191 早就做好機制：collector 開工印 phase:"start"、跑完印 "done"，
supervisor 據此維護 StateSyncing。**換 Wails 時 App 沒接這條線**，改看 sync-now 訊號檔：
  ① 訊號檔只有手動按「立刻同步」才產生 ⇒ 拖檔進資料夾（自動觸發）整輪不亮燈
  ② 就算手動按，collector 是**先刪檔再跑**（consumeSyncNowSignal）⇒ 真正在跑時檔早沒了
⇒ 改讀 sup.Status().State == StateSyncing。**接回既有機制，不發明第三種判斷法。**

**B. 做完的證據被下一輪抹掉**
ExtractedOK/ExtractFailed 是**本輪**計數、每輪覆寫整份 status.json
⇒ 有產出那輪寫下 N，十幾秒後空轉的一輪把它蓋成 0
⇒ 「上一輪 N 份」永遠空白、四步時間軸的綠燈只靠「跑過任何一輪」判斷＝與實際進度脫鉤。
⇒ 新增 last_activity_{at,ok,failed}：有產出記本輪、空轉沿用上一輪（CarryForwardActivity）。
   首頁改顯示「幾點整理了幾份」，綠燈只在真的整理過東西時才亮。

## ① Mac DMG 少了「看得出要拖」的版面
leo：「要跳出虛擬隨身碟，打開一個 finder 的視窗，**顯示 Arcrun 和 Application 的捷徑**，
用戶把 App 拖進 Application」。
原本 DMG 內容是對的（Arcrun.app＋Applications 捷徑），但**沒設版面**
⇒ 預設清單視圖、位置隨機，看不出「要往右拖」。
⇒ build-dmg.sh 改走 UDRW → Finder AppleScript 設大圖示/視窗大小/左右並排 → 轉 UDZO。
   best-effort：無桌面工作階段時只警告不中止（版面是加分，不該讓打包掛掉）。

⚠️ 真正讓 leo 拿到 zip 的原因不在這裡——是**線上 portal 還沒出貨**（見下）。

## 驗（實測輸出）
· collector 全測綠；新增 TestCarryForwardActivity 四子測（含「空轉不該抹掉上次成果」）
· 掛載 dist/Arcrun-v0.18.5.dmg 實查：
    內容剛好兩項（Arcrun.app + Applications→/Applications 捷徑）
    .DS_Store 6148 bytes（版面已存進去）
    Contents/MacOS/ 有 arcrun-app **和 arcrun-collector**
    CFBundleShortVersionString = 0.18.5（不是 1.0.0）／LSUIElement = true／codesign -v 通過
· 三支機械閘 check-cis／check-render／check-tray 全 PASS

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-05 18:01:17 +08:00
Leo 1a1478260b 打包產物不進版控（dist/ dist-msix/） 
dmg／zip／msix 都是可重現的產物，真身走 bundles repo 出貨
（github.com/youlinhsieh/arcrun-rag-bundles）。
進版控只會讓 repo 膨脹、每次重編都變動、每次都來吵未推警察。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-05 17:25:45 +08:00
Leo 133bfdbc84 修 Info.plist 版本永遠是 1.0.0＋skill 補「用戶視角驗收」 
leo 開 DMG 檢查時抓到：CFBundleShortVersionString = **1.0.0**（Wails 預設），
不是 v0.18.4 ⇒ 使用者在 Finder／「關於」看到的版本永遠不變
⇒ 無從判斷自己是不是新版（同「版本號是唯一驗收介面」的病）。

真因：wails.json 沒有 info.productVersion，而 wails build **沒有 CLI 旗標**可指定。
修：build-mac.sh／build-win.sh 建置前把版本寫進 wails.json 的 info，
建完用 trap 還原（不污染版控）。
驗：重打後 Info.plist = 0.18.4 ✅、wails.json 無殘留 ✅

DMG 用戶視角實測（掛載後看）：
  剛好兩項 Arcrun.app ＋ Applications 捷徑 ✅（拖進去的標準畫面）
  MacOS/ 內含 arcrun-app ＋ arcrun-collector ✅（沒同綑＝裝了不會同步）
  LSUIElement=true ✅（不佔 Dock）｜codesign -v 通過 ✅

skill 補兩段：
· 3.5「把 DMG/zip 真的打開，用使用者第一次看到的樣子檢查」（含五項判準與漏掉的後果）
· 開頭「這支 skill 自己的失效模式」——leo：「你寫完一個 skill 然後每個我要提醒你，
  表示這個 skill 無效」。根因是憑印象列步驟沒走過使用者的路；
  訂三條鐵律（每條要有可貼的實測輸出／使用者看得到的東西一律真的打開/
  被 leo 問出來的缺口當場補進 skill）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-05 16:52:34 +08:00
Leo d80e9e1357 t196：Windows 版重編（Wails）＋MSIX 打包——在 Mac 上交叉編譯，不需 Windows 機器 
leo 08-05：「Windows 版一定要重編，因為我只有 Mac，我需要人家測試，
要做到最完善不要給人家找麻煩，然後當測試者給我截圖安裝成功就要提交 ms store」

## 缺口
Windows 打包腳本全在**舊的 arcrun-tray（fyne 版）**，
新的 arcrun-app（Wails，t193/t194 整批 UI 重做）**完全沒有 Windows 產線**
⇒ Windows 封測者只能拿到 v0.15.7 的舊 fyne 版。

## 新增
· tray_windows.go — Windows 系統匣（energye/systray）
  行為與 macOS 版逐項對齊：左鍵開視窗／右鍵只有「結束 Arcrun」／關窗不結束。
  ⚠️ 為什麼 Windows 能用 systray 而 macOS 不能（wiki 有全文）：
     macOS 上它在 Wails 之下根本不建托盤（setInternalLoop 只在 systray.Run() 呼叫），
     改用 systray.Run() 又搶 macOS 主 loop ⇒ macOS 最後走原生 NSStatusItem。
     **Windows 走 Win32 訊息迴圈，沒有主執行緒限制**，所以這裡用 systray 是對的，
     不是抄 macOS 失敗的做法。
  trayApp 與 ICO 都在本檔自帶（tray_darwin.go 有 //go:build darwin，Windows 看不到）。
· build-win.sh  — 交叉編譯 zip（CGO_ENABLED=1 + mingw-w64，Wails Windows 要 WebView2 綁定）
  **同綑 collector.exe**：daemon 本體是 collector direct，沒同綑＝裝了不會同步
  （t194 在 Mac 版就漏過一次）。supervise.go 的 collectorBinPath() 已處理 .exe 副檔名。
· build-msix.sh — MS Store 用的 msix（沿用 makemsix，Mac 上就打得出來）
  與舊 fyne 版差別：**Wails 是兩個 exe**，兩個都要進 msix root。
  Identity 三值走環境變數（要與 Partner Center 完全一致），預設佔位並印警告。

## 驗
· Windows zip：兩個檔都是正牌 PE（MZ 標頭）／Arcrun.exe 11.4MB＋collector.exe 16.1MB
· 退避修復確實編進 Windows 版（不剝符號重編一份，grep 到 MarkFailed／ShouldRetry／
  retrySkipReason 各 2 處；出貨版用 -s -w 剝符號故查不到，屬預期）
· MSIX：16 檔、含 AppxBlockMap；zip 回讀兩個 exe 的 sha256 與原檔**逐一相符**；
  manifest Executable="Arcrun.exe"、Version=0.18.4.0
· **macOS 版不受影響**：編譯通過、三支機械閘全過

## 兩個踩到的坑（已修）
· zip 用相對路徑在 cd 後失效（zip I/O error，fallback 湊巧成功但不可靠）⇒ 改絕對路徑
· 全形括號緊接變數會被當成變數名（腳本自己的註解就警告過）⇒ 改 ${VAR}

## 殘項
· Identity 仍是 PLACEHOLDER ⇒ **這顆 msix 還不能送 Store**，等 leo 給 Partner Center 三值
· 未在真 Windows 上跑過（誠實界定：只證明編得出來，不證明跑起來對）
 2026-08-05 15:50:57 +08:00
Leo 369eef07d4 修 check-render 誤報：server 沒收乾淨導致連跑會抓到舊頁面 
實撞：同一份 build 連跑三次，一次綠兩次紅，白追一輪
（先誤判「深色模式壞了」→ 實際渲染截圖一看深色是好的）。

真因：trap 用 `kill %1`（job spec），在子 shell／連續執行時抓不到
⇒ 上一次的 http.server 佔住 8799 ⇒ 下一次抓到舊頁面。
修：改記 PID 收；並在啟動前先 lsof 清掉殘留在該 port 的 server。

順帶修 mock.js：t193 三修起 main.js 啟動會依 localStorage 覆寫成預設淺色
⇒ 光改 <html data-theme> 會被 JS 蓋掉，要在 module 之前寫 localStorage
（key=arcrun_app_theme）。

驗：連跑三次全過（原本會紅）；三支閘 check-cis／check-render／check-tray 全過。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-05 15:22:48 +08:00
Leo 47580f4ba5 t195：失敗重試加指數退避＋上限——一個壞檔不再拖住整個資料夾 
leo 2026-08-05：「有封測者在等，一直出錯」「已經等了幾天了」

## 病（leo 實撞，log 實證）
`小果被AFTEE詐貸.pdf` 雲端 401 失敗後，**manifest 完全不記失敗**
⇒ 下輪掃描又當「新檔」⇒ **1387 輪、跨 11 小時**，每輪 3.2~3.8 秒全在撞同一面牆；
且它排在佇列前面 ⇒ **整個資料夾的同步被一個壞檔拖住**。
leo：「原先萃檔案速度也快，現在花了十幾分才萃完」——**萃取沒變慢，慢的是重試**
（log 的 `FOREACH 所有 5 項目均失敗` 證明卡早就萃好了）。

**這是獨立於 401 的架構缺陷**：401 修好了，下次換別的錯照樣卡死。

## 修
· ManifestEntry 加 FailCount / LastFailAt / NextRetry
· MarkFailed()：退避階梯 1m→5m→15m→1h→6h（之後維持 6h）
· ShouldRetry()：退避窗口內跳過；連續失敗 8 次暫停自動重試
  force（使用者按「立刻同步」）忽略退避與上限——**人明確要求不該被機器擋住**
· MarkIngestedBy() 成功時清空失敗狀態（下次再壞從第一階重算）
· direct.go 三個失敗出口都記退避（讀檔失敗／萃取失敗／上傳失敗）
· retrySkipReason()：跳過時說人話，不靜默（同 t195 燈號誠實原則）

## 🔴 真兇其實有兩層——第二層才是關鍵
只加退避欄位**沒有用**：`scan.go` 每輪都**重建** ManifestEntry，
原本只 carry IngestedHash/IngestedAt ⇒ 我寫進去的 fail_count 下一輪就被抹掉
⇒ 退避永遠停在「第 1 次失敗」＝等同沒有退避。
（順帶發現 ExtractedBy(t73「誰萃的」)原本也一直悄悄丟失。）
⇒ scan.go carry 補齊四個欄位，並留註解：**日後新增跨輪欄位必須加在這裡**。

## 驗（真實跑，非只有單元測試）
單元測試 6 項全過（退避窗口／指數遞增 60/300/900/3600/21600/21600／
上限停止／force 忽略／成功清空／壞檔不連累同輪其他檔）
實跑（cypher_url 指向不存在主機製造必失敗）：
  第 1 輪 failed
  第 2 輪 skipped「上次失敗（第 1 次），1m0s 後重試」
  第 3 輪 skipped（同上）
  第 4 輪 skipped（同上）
  模擬退避到期 → 確實重送、fail_count=2、退避升為 300s ✅
go test ./... 全綠；go vet 通過。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-05 14:46:03 +08:00
Leo d787bfc47d t195：燈號不再說謊＋加診斷 log（leo：「燈號是真的還是假的？」→ 是假的） 
## leo 實撞
丟 PDF 進 youlinhsieh-test1 沒反應；按「立刻同步」後畫面顯示
「正在整理知識卡」，但**卡從來沒產出**。

## 燈號為什麼是假的
舊版 describeStatus 只看「sync-now 訊號檔存不存在」就顯示「同步中…」。
那只代表**排隊了**，不代表有人處理：leo 的 collector 在 11:25 跑完最後一輪，
他 11:38 按同步 ⇒ 訊號檔沒人消化 ⇒ 畫面一直說在整理，實際 13 分鐘沒跑過。
**這比沒有燈號更糟——它在說謊。**

修：燈號要有憑有據——
  · collector 沒在跑 → 明說「同步引擎沒有在跑」並告訴他怎麼辦
  · 有排隊 **且** 引擎活著 → 才是「同步中」
  · 其餘 → 看守中

## 順手補上診斷 log（~/.arcrun-rag/app.log）
startSupervisor 以前只 Stat(config) 就靜默 return，出問題完全查不到
（我這次也是繞了很久才確定它有啟動）。現在每個 return 點都留痕。

## 🔴 但真正擋住產卡的是另一個 401（未修，需 leo 裁）
實測鏈路：掃到 PDF ✅ → /portal/daemon/extract ✅ 200 → 寫 kbdb ❌ 401
  curl -X POST https://arcrun-kbdb.youlin-hsieh-dev.workers.dev/entries（無 token）→ 401
真兇：workflows/rag-ingest-card.local.yaml 打 __KBDB_BASE__/entries
**完全沒帶 Authorization**，但 kbdb 要 Bearer KBDB_INTERNAL_TOKEN。
⚠️ 與今天修的 t189 不同：那是 extract 端點入口（現已 200），這是 workflow 內部寫 kbdb。

修法命中 D36 金鑰鐵律（「只能拿 key，送出時自動拉 value」）
⇒ 應寫 {{credential.kbdb_internal_token}} 由 resolve_credentials 回填，
   而非讓安裝器 sed 把 token 值塞進定義。**已停下等 leo 裁**。

## CP 對帳
「丟檔→產卡」＝ ❌ 斷（卡產不出來）。本次只修好「燈號誠實」與「可診斷」，
**未送達用戶**（daemon 新版尚未出貨、401 未修）。
 2026-08-05 11:45:07 +08:00
Leo 5860ef72df t194 四修：托盤改用原生 NSStatusItem——energye/systray 在 Wails 之下根本不建托盤 
leo：右鍵仍然沒用。這次先做**最小重現**才動手，結果推翻了我前兩次的判斷。

## 真兇（實測，非推論）
systray.go:83 的 setInternalLoop(true) **只在 systray.Run() 裡呼叫**；
RunWithExternalLoop 沒有 ⇒ registerSystray() 第一行就
`if (!internalLoop) return;` ⇒ **delegate 從沒建立**
⇒ onReady 不會被呼叫、enable_on_click 不會執行、左右鍵事件根本不存在。

最小重現（scratchpad/traytest）：RunWithExternalLoop + onReady 印 "READY"
⇒ **READY 從未印出**。托盤自始至終沒被建立過。
（左鍵之所以「第一次能開」是 Wails 自己開的窗，與托盤無關。）

## 正解：原生 NSStatusItem（tray_darwin.m + tray_darwin.go）
左鍵＝開視窗；右鍵＝暫時掛選單、performClick、再拿掉（不常駐 setMenu:，
否則按鈕 action 不會被呼叫、左鍵也會變成彈選單——與 systray 那個坑同源）。

## 過程中踩到、也寫進閘的三個坑
① dispatch_async(main_queue) **無效**：Wails 佔住主執行緒後不跑標準 run loop，
   排進去的 block 永遠不執行（log 只印到 "dispatching…"）⇒ 改 performSelectorOnMainThread
② NSStatusBar 需要 NSApp 已初始化：在 wails.Run() 之前呼叫 ⇒ 靜默失敗、icon 不出現
③ 🔴 **我一度對著 `go build` 產的 stub 除錯**——沒帶 Wails build tags 的執行檔
   一跑就印 "Wails applications will not build without the correct build tags" 並退出，
   我卻以為是「托盤沒建起來」，白繞一圈。**驗 Wails App 一定要用 wails build 的產物。**

## 實測證據（AppleScript 從 UI 層查，最貼近使用者看到的）
  menu bar 數=2，status item 數=1   ← 選單列 icon 真的存在
  collector 同步啟動、正常結束無孤兒
三支機械閘全過（閘也改成驗原生實作：不可 dispatch_async／必須
performSelectorOnMainThread／不可常駐 setMenu／不可再依賴 energye/systray）。

⚠️ 仍未驗：左右鍵的**實際點擊行為**要 leo 手動點。
 2026-08-05 02:56:41 +08:00
Leo a02eed539a t194 三修：右鍵選單——正解是「**少寫**一段」，不是再補一段 
leo 實測：右鍵仍然沒有 quit 選單。

## 真兇：我把函式庫本來就會做對的事，換成一個更脆弱的版本
讀 systray_darwin.go 的 systray_on_rclick()：

    func systray_on_rclick() {
        if onRClick != nil { onRClick(st) } else { C.show_menu() }
    }

⇒ **沒註冊 SetOnRClick 時，函式庫自己就會把選單叫出來**；
   而且 C 層的 show_menu 內部已經處理好整套：
   create_menu() → [statusItem.button performClick:nil] → set_menu_nil()

我卻註冊了自己的 handler、還加 `if menu != nil` 防呆
⇒ 等於用一個判斷把「本來會動的預設行為」擋掉。

修：**刪掉 SetOnRClick 註冊**。左鍵仍自訂（要開視窗），右鍵交還函式庫。

## 判準（已寫進 mistakes）
用第三方函式庫時，**先讀它的預設行為再決定要不要覆寫**。
「多註冊一個 handler」看起來是加功能，實際上常是**關掉**原本正確的行為。

## 閘也跟著改
check-tray.sh 原本驗「SetOnRClick 有註冊且順序對」——**那是在守一個錯的寫法**。
改成反向：**出現 systray.SetOnRClick 就擋下**，並說明原因。
實跑 7 項全過；App 活著 pid 14081、crash 0。
 2026-08-05 02:27:23 +08:00
Leo c400292c01 新增 check-tray.sh：托盤行為的機械閘（交付警察攔下後補） 
leo 真機測出的四個 bug **編得過也跑得起來**，只有真的去點才會發現；
我改完只驗「build ok」就想交 ⇒ 把「點不下去的部分」用可機械檢查的前置條件守住：

① template icon：22/44 RGBA、**不透明 <50%**（否則會顯示成方塊）、顏色種類
② 呼叫順序：AddMenuItem → SetMenuNil → SetOnClick/SetOnRClick
   （順序錯＝滑鼠事件全失效，正是 leo 撞到的②③）
③ ShowWindow 必須有 Unminimise/Show/SetAlwaysOnTop 三者（缺一就叫不回被蓋住的窗）
④ 結束路徑：有 signal.Notify＋waitCollectorGone（否則只能強制結束、留孤兒）

實跑 7 項全過。這支＋check-cis＋check-render 三支都要過才准交。
 2026-08-05 01:47:58 +08:00
Leo fcdb1df71d t194 二修：托盤 icon／右鍵選單／重複點擊／正常結束（leo 實測四點） 
leo 真機測出四個問題，每個都查到真兇後才動手：

## ① 托盤 icon 變方塊
真兇：我塞 1024x1024 的**彩色 app icon** 當 template icon。
macOS 選單列規格是 **16-22pt、純黑＋alpha**（由系統依深淺色自動上色）
⇒ 彩色大圖被縮成一坨方塊是必然。
修：用 CIS 的 chevron-double.svg 渲成 44x44 純黑 template icon。

## ②③ 右鍵沒選單／第一次能開之後就不再跳
真兇（energye/systray 原始碼註解白紙黑字寫著）：
「該方法主動調用後 如果托盤菜單已創建則添加進去, **之後鼠標事件失效**」
⇒ 只要用 AddMenuItem 建了選單，SetOnClick／SetOnRClick **全部失效**。
修：SetMenuNil() 移除選單讓滑鼠事件生效，右鍵時自己 ShowMenu()。
另外 ShowWindow 只呼叫 WindowShow 對「已開但被蓋住」無效
⇒ 補 Unminimise ＋ AlwaysOnTop 閃一下搶焦點。

## ④ 只能用強制結束
真兇：Wails 的 loop 不理 SIGTERM，且 collector 是我們自己 Start 的子行程
⇒ 主程式被殺後**子行程變孤兒繼續跑**。
實測（機械驗證，非目視）：
  修前 kill -TERM → App 沒退、collector 孤兒還在
  修後 kill -TERM → App 正常退出 ✅、collector 一起收掉 ✅、殘留 0
修：installSignalHandler 收 TERM/INT → stopSupervisor() →
    waitCollectorGone(3s) 確認子行程真的不見（逾時補一刀）→ 才 os.Exit。
    「關了卻還在同步」比沒關更糟。

實跑驗證：App 活著 pid 88466、自己拉起 collector、crash 0、兩支機械閘全過。
 2026-08-05 01:41:31 +08:00
Leo 643acc0f74 t194 修：托盤必須在主執行緒建立——交付警察攔下，實跑才發現會 crash 
交付警察問「leo 現在去測會不會發現你沒發現的東西」⇒ 我去真的跑一次，
**發現這版根本起不來**。我原本只驗了「打包產物有沒有那些檔案」，沒驗它會不會活著。

## 兩個 crash，都要真機跑才看得到
① `systray.Run()` 自己開 loop ⇒ 與 Wails 搶 macOS 主 loop
   ⇒ SIGTRAP `signal arrived during cgo execution`
② 改用 RunWithExternalLoop 但在 OnStartup／goroutine 裡呼叫 start
   ⇒ SIGABRT `NSWindow should only be instantiated on the main thread!`
   （NSStatusItem 內部會 new NSWindow，AppKit 規定只能在主執行緒）
   ⚠️ 我一度想「加個 sleep 丟 goroutine」——那只是拖延，goroutine 永遠不是主執行緒。

## 正解
main() 一開始（還在主執行緒）就 RunWithExternalLoop 註冊並 trayStart()，
它**不阻塞**，接著把主執行緒交給 wails.Run()；defer trayEnd() 收尾。

## 實測（跑真的 .app，非只看檔案）
  App 活著 pid 59162 ✅
  它拉起自己的 collector ✅（arcrun-app/.../arcrun-collector，與舊 fyne 版並存不衝突）
  crash 訊號 0 ✅／log 僅 1 行 ✅
兩支機械閘仍全過。

⚠️ 未驗：托盤左右鍵的**點擊行為**要人真的去點（我點不了）。
 2026-08-05 00:46:52 +08:00
Leo 549834f343 t194：托盤收成 Google Drive 式（點 icon 開視窗／右鍵只有結束）＋同綑 collector 
leo 2026-08-05：「依照 google drive，托盤裡只剩下按右鍵會結束，
其他設定都在這個頁面，點擊托盤的 icon 就立刻展開界面」

## 托盤
Wails v2 沒有內建托盤 ⇒ 用 energye/systray（Wails 相容分支，支援左鍵事件）。
- 左鍵：直接展開主視窗，**不彈選單**
- 右鍵：只有一項「結束 Arcrun」
- 設定全部留在視窗裡，托盤不再是第二套 UI
  （fyne 版把設定塞下拉選單，leo 早說過「不可能統統塞在下拉選單」）
- 關窗＝隱藏不結束（daemon 常駐；按 × 就停止同步不符預期）
- Dock 不出現 icon：Wails v2.13 的 mac.ActivationPolicy 還沒開放（原始碼是註解掉的）
  ⇒ 改走 Info.plist 的 LSUIElement，與 fyne 版同一個做法

## 🔴 順手抓到自己的大漏：這個 App 根本沒有啟動 collector
daemon 的**本體**是 `collector direct`（監看/萃卡/上傳），Wails 版我一路沒接
⇒ 照這樣出貨會是「裝了也不會同步」的空殼。
修：新增 supervise.go，**複用既有 supervisor 套件**（重起退避／狀態機／
    t191 的 phase:start/done ⇒「同步中…」），不複製一份（複製＝會漂移）。
    go.mod 用 replace 指回 collector 主模組。
    加/刪資料夾、改 AI 設定後都會 restartWatch()，設定立刻生效。

## 打包
新增 build-mac.sh：編 collector → wails build → **同綑進 .app** → ad-hoc 重簽。
沒同綑就等於沒有 daemon。

實測（v0.18.0）：collector 同綑 15M ✅／LSUIElement=true ✅／版本注入 ✅／已簽 ✅
兩支機械閘全過。
⚠️ 未驗：托盤左右鍵的實際行為要真機點（我開不了視窗）。
 2026-08-05 00:31:52 +08:00
Leo 5a48abb784 t193 四修：裁淨版 lockup＋側邊欄選中態照 portal（leo 兩點） 
## ① logo 比例不對＋深色仍有白底＋旁邊大量空白
三個症狀同一個根：**我用的是未裁淨的原始 PNG**。
portal 的註解早就寫著：原始 1840x560 **只有 32% 高度是實際字形**，上下大留白
⇒ 同 height 字看起來很小；留白處露出 paper-on-ink 自帶的 Ink 底板＝白底。
portal 用的是裁淨版（986x176），但**只內嵌在它的 HTML base64 裡**，我抄不到才用了原始圖。

修：
- 從 portal 的 base64 抽出兩張裁淨版，存成 arcrun-cis/trimmed/ 供全站共用
- 兩張**都是透明底**（實測四邊留白 0）⇒ 深色模式**拿掉 Ink 底板**
- 空白是**版面**造成：側欄 232px 扣 padding 剩 184px，logo 高 24px 只有 134px ⇒ 空 50px
  ⇒ 側欄對齊 portal 的 216px，logo 改 width:100% 填滿可用寬度

實測（渲染後量像素）：
  logo 26px 高 × 151px 寬，右側剩餘空白 1px（原本 50px）
  深色：側欄底(18,18,18) vs logo 上下皆(18,18,18) ⇒ 落差 0，無白底

## ② 側邊欄選中態太粗糙
leo：「參考現在 Portal 的格式⋯⋯這個比現在膠囊反紅精緻，重點是跟 portal 的形象符合」
修：逐字照 portal 的 #sidenav .nav.on ——
    **不是實心膠囊**，而是 amber 字色 ＋ 8% amber 底 ＋ 右側 2px amber 邊。
    側欄右緣也照 portal 用 2px amber 35%。
實測：選中列底(237,228,222)=amber 8%、右緣(176,74,47)=Relation、未選(242,241,237)=Canvas。

## 機械閘加三項守衛
- 不准用未裁淨的原始 lockup（字會太小）
- 選中態必須有 border-right-color: var(--amber)
- 不准再出現 border-radius:999px（膠囊，leo 已否決）
兩支閘全過；style.css 仍 0 個 hex。
 2026-08-05 00:02:46 +08:00
Leo 751ee74f19 t193 三修：每庫一頁＋狀態時間軸＋預設淺色（leo 六點回饋） 
## ① logo 尺寸不對導致白邊
真兇：我寫死 height:22px **沒給 width:auto** ⇒ 容器一壓就變形、露出底板邊緣。
修：照 portal 側欄同一條 clamp(22px,5vw,28px) + width:auto + max-width:100%，
    並依 CIS「clear space = one chevron height」在四邊留白。
實測：logo 底板與品牌區落差 **0**（原本是明顯方塊）。

## ② 深色跟網頁不同／「它有淺色佈景？」
是——**portal 預設淺色**，深色由使用者切換並存 localStorage。
我卻硬跟系統走 ⇒ 兩邊當然不同。
修：改成與 portal 同一套（預設淺色＋切換鈕＋localStorage），
    按鈕規格也逐字對齊 portal 的 .btn/.btn3（padding/font-size/radius/border）。
實測淺色：品牌區(253,252,251)=Paper、側欄(242,241,237)=Canvas，與 CIS 一致。

## ③ 「開啟知識庫網頁」開到錯的庫
真兇：它在首頁、寫死取 accounts[0] ⇒ 有兩個庫必然開錯。
修：移到**各庫頁的上方**，開的就是那個庫。

## ④⑤ 30 個資料夾放不下／「加入資料夾」會加到哪個帳號？
修：**每個知識庫一個獨立分頁**（側邊欄動態列出，附資料夾數）。
    「加入資料夾」在庫頁裡，**作用對象就是那個庫**，不會加錯。

## ⑥ 首頁要顯示 status（看守／發現變化／萃取／上傳）
修：首頁改成**狀態時間軸**四步，進行中那步的圓點會呼吸。
    誠實邊界：collector 目前回報「整輪」而非逐檔階段，
    所以同步中時後三步一起標進行中，**不假裝有更細的進度**。

兩支機械閘全過（check-cis.sh 14 項／check-render.sh 深淺色皆驗）。
style.css 仍是 0 個 hex（顏色全走 var）。
 2026-08-04 23:35:49 +08:00
Leo 3d13e5a54e t193 二修：側邊欄版面＋共用 CSS＋App 內更新＋兩支視覺機械閘 
leo 08-04 看過 v0.17.0 後的四點，逐條回應：

## ① 「不會這裡又寫了一個新的 CSS？」——是，我又寫了一份
真兇：portal 的樣式內嵌在 HTML 裡，沒有獨立檔 ⇒ 四個站各抄一份、本來就在漂移。
解：抽出 InkStoneCo/arcrun-cis/css/arcrun-cis.css 當唯一真相源。
    daemon 的 style.css 現在**一個 hex 都沒有**，顏色全走 var(--...)。

## ② 「完全模仿 gdrive，左方側邊欄，在右方替換頁面」
底部 nav bar 拿掉（leo：「幾乎沒看過這種 nav bar 在下方的」）。
改成左側邊欄四頁：首頁／同步資料夾／AI 設定／版本與更新，右側換頁。
設定不再開 popup；只有「確認移除資料夾」才用覆蓋層。

## ③ 「既然是 Web，你做的時候無法檢視？」——可以，我之前沒做
新增 check-render.sh：headless Chrome 真的渲染一次並**量像素**。
它抓到一個肉眼容易誤判的真 bug：
  arcrun-lockup-h-paper-on-ink.png **自帶不透明 Ink 底板**（實測左上像素 RGBA=23,24,26,255），
  設計前提是貼在純 Ink 表面；我們背景有紙張紋理 ⇒ 出現突兀方塊。
  修：深色模式把品牌區做成純 Ink。實測落差 4（原本會是一個明顯方塊）。
過程中也發現自己對著**舊的 dist**除錯，浪費一輪——這支閘同時防這個。

## ④ 「檢查更新連到 docs，不正確，是直接在這裡進行」
新增「版本與更新」頁：顯示**現在版本 vs 最新版本**，
三段式全在 App 內完成——檢查／下載並安裝／重新啟動套用。
selfupdate 邏輯逐字沿用 arcrun-tray（含 t186 走 raw、t184 蓋正在跑的 .app），不重寫。

## 交貨閘（leo：「你做為檢查有嗎？沒有怎麼交貨？」）
check-cis.sh 擴充：版面檔不准出現任何 hex ＋ 共用底層色票逐項比對。
兩支閘實跑全過。
 2026-08-04 23:09:54 +08:00
Leo bd0cead00e t193：daemon UI 換 Wails——CIS 是硬要求，fyne 做不到 
leo 2026-08-04 看過 v0.16.0 畫面後：
「功能都有了，但美感非常糟糕⋯⋯跟 CIS 完全無關，每個功能都開一個小小的 popup 視窗，
 非常缺乏整體感，這要理解的是原始的技術選擇是否出錯？」
「我的要求是符合 CIS，在風格上跟 portal 一樣」
「CIS 已經提供規範，你做的連 Logo 都沒放上去，這跟美不美有關係嗎？
 要求放進 CIS 是硬要求，你做為檢查有嗎？沒有怎麼交貨？」

## 我的兩個錯
1. **動工前沒提醒做不到**——decisions-summary.md:314 的 D-daemon-UI
   是我 07-27 自己寫的調研（結論：fyne 全自繪、CSS 套不進去），寫完就沒再看。
   今天動工前該查它卻直接開寫，浪費 leo 的時間與 token。
2. **沒做 CIS 檢查就交貨**——連 logo 都沒放。

## 換 Wails（WebView 殼）
前端就是 HTML/CSS ⇒ 可以直接用 portal 那份色票與 lockup。
- style.css 的色票/字體/紙張紋理**逐字取自** portal 的 :root
  （matrix/arcrun:console-ui/public/portal/index.html），不自創任何顏色
- CIS lockup 官方 PNG，淺色 ink 版／深色 paper 版，切換規則同 portal
  （避開 08-01 作廢的自產 SVG——字腔缺失）
- 對話框改**內嵌覆蓋層**，不再每個功能開一個小 popup
- 原生資料夾選擇器（macOS powerbox 會自動授予該資料夾存取權，
  fyne 自繪 picker 拿不到；未來上 Mac App Store 是硬需求）
- 同步中的圓點會呼吸 ⇒ 看得出來在動（issue #17）
- 無帳號時是 onboarding 引導，不是空白面板

## 連線邏輯逐字沿用，不重寫
connect.go 的 normalizePortalURL/fetchConfigByLogin 取自 arcrun-tray/main.go，
含 t86 個資外洩事故的防線（不同實例＝新增帳號，絕不覆蓋舊帳號的資料夾）。
今天已犯過一次「重寫別人修好的東西還修得更差」，不再犯第二次。

## 新增 check-cis.sh（交貨前必跑）
機械檢查六類：官方色票逐個到齊／**不准出現非 CIS 色**／logo 真的放進去／
不可用作廢 SVG／深色模式／字體與紙張紋理同 portal／app icon。
實跑 14 項全過。以後「沒跑過就不准交」。

⚠️ 未驗：實際畫面要 leo 開來看（我開不了視窗）。
 2026-08-04 22:19:41 +08:00
Leo cc6534dd39 t191/t192：daemon 主視窗（Google Drive 風格）＋「同步中…」進行中狀態 
解 issue #18＋#17（leo 指定併做）。

## #17 進行中狀態——真兇是「工作時間對用戶隱形」
leo：「按『立刻同步』後很快就回到『看守中』，看起來好像就做完了，
      這時使用者一看沒做完啊，就覺得是 bug」。
真兇：collector **只在一輪跑完後**才印 JSON ⇒ 托盤無從得知「正在跑」。
修：開工前先印 phase:"start"、跑完印 phase:"done"；
    supervisor 新增 StateSyncing；托盤／主視窗顯示「同步中… 正在讀檔並整理成知識卡」。
形狀相容：兩筆都有 at，舊版托盤只會多算一次 round，不會壞。

實測（真的跑一輪 --once）：
  第1筆 phase='start' at=21:31:26
  第2筆 phase='done'  at=21:31:27

## #18 主視窗（新檔 mainwindow.go）
leo：「daemon 設定項越來越多，不可能統統塞在下拉選單」
     「參考 Google Drive 設定畫面：點擊 daemon 就開一個視窗，佔螢幕約 1/2」
     「資料夾清單要可捲動——我每個 gitea 專案都要同步，那就是幾十個，根本塞不下」
- 920x620 視窗，關窗＝隱藏（daemon 續跑）
- 上：大字狀態＋副標（上次同步／已整理幾份／失敗幾份；有錯誤優先顯示）
- 中：widget.List 虛擬捲動的資料夾清單（帳號標題＋其下資料夾攤平成單層）
- 下：白話動作列（加入資料夾／新增知識庫帳號／AI 設定／檢查更新）
- 每秒自動刷新 ⇒ 同步中看得到在動
- 無帳號時引導去連線（onboarding），不是丟錯誤或空面板
- **所有動作複用既有 handler**，不在視窗那邊重寫一份邏輯

托盤選單第一項加「開啟 Arcrun…」——leo 已點破兩次
「能力做出來了，入口沒出現在用戶會看的地方」（docs 沒連結／MCP 零處提及），
這次做完就讓它看得見。

測試：t192_test.go 八則（狀態文案四態／同步中要說明在做什麼／
副標優先顯示錯誤／副標不可空白／清單攤平且 accIdx 正確／60 個資料夾／無帳號空清單）全過。
collector 與 supervisor 全套綠。

⚠️ 未驗：fyne GUI 的實際外觀需真機開窗（無螢幕環境驗不到），
   CIS 視覺套用待 leo 看過畫面再調。
 2026-08-04 21:32:31 +08:00
Leo 8c7b50d9a9 t190：Gemini 金鑰刪不掉——清空輸入框現在真的會刪除 
leo 08-04 實撞：「我切到 Gemini 把內容刪掉，再切回 Workers AI，儲存，
回去發現 Gemini Key 還在」。要求：「如果他不想留 Key 了，要可以刪除」。

真兇：cfg.GeminiAPIKey = key 寫在 if useGemini 裡 ⇒ 選回雲端 AI 時整段跳過，
舊金鑰原封不動（帳號層同病）⇒ 清空輸入框等於沒作用。

改成無條件以輸入框為準（清空＝刪除），符合使用者心智模型：
我把欄位清空並按儲存，它就該不見。頂層與每個帳號層一併清。

測試：新增 t190_test.go 兩則——清空要真的清掉（頂層＋所有帳號層）、
選 Gemini 填值時每層都要寫進去（不可被本次修改弄壞）。兩則皆過，全套綠。
 2026-08-04 20:47:32 +08:00
Leo 6275daa555 t185/t186：三站 nav bar 補齊＋自更新改走 raw（jsDelivr @main ref 解析卡死） 
## t185：用戶原本根本進不去 docs
leo：「從用戶角度看，**你沒有 nav bar 用戶怎麼進去**？」
——docs 建好了但首頁零連結，只有知道網址的人找得到＝同一個病
（能力做出來了，入口沒出現在用戶會看的地方）。

- rag／install 兩站各加同一條 nav（首頁／安裝／說明文件，當前頁 highlight）
- **下載步驟旁**另加 Mac／Windows 分流連結——入口要放在「用戶正在卡住的地方」，
  不能只靠頁首 nav

實測（線上抓 href，非只看 200）：
  rag.arcrun.dev  → /docs/、/docs/start/install-mac/、/docs/start/install-windows/
  install.arcrun.dev → /docs/

## t186：自更新改打 raw.githubusercontent（推翻 t150 二修的判斷）
真兇不是檔案快取，是 **jsDelivr  的 ref 解析（main→commit）被快取**，
 與 purge 都清不掉。08-04 三條路同時比對坐實：
  @main 1.4.9/v0.15.6（卡住，x-cache MISS,MISS 仍吐舊）／@sha 與 raw 皆 1.4.10/v0.15.7
zip 能靠改帶版本號檔名繞開，**manifest.json 檔名寫死在 code 裡繞不了** ⇒ 只能換來源。

D20 合規：t150 那輪否決 raw 的理由「那是實名讀」是**誤判**——
D20 對實名的定義是「URL 帶 token@／clone private 殼」，
daemon 這個請求不帶任何憑證＝**匿名讀**，D20:22 明列「✅ 放行，不計數」。
副效益：portal 下載按鈕本來就走 raw ⇒ 兩條路同源，不再有「下載頁對、檢查更新錯」。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-04 19:29:17 +08:00
Leo 9fcd82b517 v0.15.7：改名 Arcrun.app＋發 DMG（拖進 Applications）＋MSIX 正式身分 
leo 08-04：「如果當初 mac 打包就是 dmg 用拖的，現在 oscar 那裡就解決了，
如果當初 msix 就用了，現在另一個人也是更新就可以」——遠慮該在第一版就有。
原則：**用戶好用、白癡化**。

① 改名 Arcrun RAG.app → Arcrun.app（leo：「不要 rag，要 arcrun.app」）
   五處引用一起改（selfupdate.go／build-mac.sh／build-dmg.sh／t184_test.go／README）

② 新增 build-dmg.sh：DMG 內含 Arcrun.app ＋ Applications 捷徑
   ＝Mac 幾十年的標準做法，開起來就暗示你拖進去 ⇒ **從源頭讓 app 待在對的位置**。
   坑：hdiutil 預設檔案系統會把「Arcrun RAG.app」截成「RAG.app」⇒ 加 -fs HFS+ 解。
   DMG 治源頭、t184 是安全網，兩個都要（已裝在別處的人不會因改發 DMG 就自動變好）。

③ MSIX 用 .env 的正式 Partner Center 身分重打（**不是佔位值**）
   回讀 AppxManifest 逐欄驗證：
     Identity Name        Uncle6.Arcrun
     Publisher            CN=DE038286-31A5-47CF-B83F-FF6B206BF591
     PublisherDisplayName Uncle6
     Version              0.15.7.0
     仍含 PLACEHOLDER      False

實測（t184 端到端，模擬 Oscar 的情境）：
  app 放 /tmp/oscar-test/Downloads/（不在 /Applications）→ 跑更新覆蓋
  → 該處 app 變成 v0.15.7 ✅
  → /Applications 沒有被無中生有一個副本 ✅
  路徑推導三種放置位置皆正確（Downloads／Applications／Desktop）

產物 sha256：
  dmg  0eb3f76b60bf6891   mac zip f264dda7391f3006
  win  32fe44450ca77c62   msix    5bf7c911b8f3a817

⛔ 誠實標記：MSIX 能否實際安裝**這台 Mac 驗不到**（Add-AppxPackage 只有 Windows）。
   已驗的是包結構合法（unpack 過 blockmap 雜湊）＋身分欄位正確。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-04 18:12:53 +08:00
Leo 0021c274e8 t184：自更新蓋回「正在跑的那個 .app」——修 Oscar 更新完又跳回舊版 
leo 08-04 實撞（Oscar 截圖）：托盤顯示「🟢 新版 v0.15.6 已就緒」，
點下去重啟後**版本又是 v0.15.4**。同一套機制在 leo 機器正常。

真兇＝`selfupdate.go` 寫死 `/Applications/Arcrun RAG.app`：
  · leo 有把 app 放進 /Applications ⇒ 剛好蓋對他正在跑的那份 ⇒ 一直正常
  · Oscar 從下載資料夾直接跑 ⇒ 蓋到一個他沒在跑的路徑
  · 而且 **ditto 會自動建出該目錄並回傳成功**（實測 exit 0，非報錯）
    ⇒ 畫面說「更新完成」、版本卻永遠是舊的＝**靜默失敗**
  ⇒ 不是新舊 Mac 的差別，是 **app 放置位置**的差別（leo 機器實查證實）。

修法：改用 os.Executable() 往上推 .app（runningAppBundlePath），
更新**當前真的在跑的那份**——放哪都能更新，也不再無中生有 /Applications 副本。
找不到 .app 結構時誠實回錯，不猜路徑亂蓋（蓋錯比不更新更難查）。

⚠️ 「檢查更新」這條路**保留且必須修好**——leo：「這是我解決每次都要撞
沒簽章問題的解法，不能說它無用」。本次是修它，不是繞過它。

測試：新增 t184_test.go（不得回傳寫死 /Applications／.app 推導對三種放置位置
／ditto 靜默建目錄的認知回歸）；順手把 t182 的 TestAccountEngineLabel 改寫成
新判準（explicit 決定，非 config 殘留字串）。兩模組全綠。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-04 17:57:46 +08:00