這篇講的是一套判讀紀律，不是某個特定工具。後面幾篇（遠端連線與終端機問題、機器連不到或起不來、程序、服務與狀態怎麼判）是這套紀律在各種具體情境的應用。

表象會騙人：一個判斷被畫面帶偏兩次的實例

一個具體案例最能說明為什麼不能靠肉眼。在一次桌面 shell（畫桌面 UI 的圖形程式，不是 bash/zsh 那種命令列 shell）的除錯裡，畫面中央出現一個「輸入密碼」的覆蓋層，配著時鐘、天氣、通知的整片儀表板。第一眼的判斷很自然：螢幕被鎖住了。

接著幾個看似合理的檢查反而把判斷帶得更偏：loginctl 查不到這個 session 的 LockedHint、pgrep 找不到任何獨立的鎖屏程式、那個 shell 的 CLI 也沒有 lock 指令。三個訊號湊起來，得出一個「更正」的結論：這不是真的鎖，只是一個長得像鎖屏的儀表板面板。

這個「更正」是錯的。真正定案是靠讀那個 shell 自己寫的 log：log 裡明明白白有鎖屏模組被載入、有 idle 計時器在數秒數、時間到就觸發鎖定。它是一個真的螢幕鎖，走的是 Wayland 的 session-lock 協議。

為什麼前面三個檢查會誤導？因為它們讀的是錯的權威來源。loginctl 的 LockedHint 是 logind（systemd 的登入管理）那一層的鎖定狀態，而這個鎖走的是 Wayland 合成器（compositor，負責把視窗合成到螢幕、管輸入輸出的核心程式）那一層的協議，兩者是獨立機制——查 logind 對合成器層的鎖天生查不到，不是「沒鎖」，是查錯地方。pgrep 找不到獨立程式，是因為鎖屏畫面由 shell 主程式在自己的行程內畫，本來就沒有另一個可執行檔可抓。真正記錄「有沒有鎖、為什麼鎖」的權威來源，是那個 shell 的 log；讀到它，一次就定案。

肉眼加上讀錯層的檢查，猜錯了兩次；讀對權威來源，一次就對。教訓不是「那些工具沒用」，是要先確認你讀的是不是這件事的權威狀態。

每種問題都有它的權威狀態來源

除錯的第一步，是為眼前的現象找到記錄它的權威來源。不同類別的問題，權威來源不同：

這張表的用法不是背它，是養成一個反射：看到現象先問「這件事的權威狀態記在哪張表裡」，再去讀那張表，而不是從畫面推測。下面幾個常見的判錯，都是讀了表象而不是權威來源。

讀對權威來源、但查詢條件要對

有時權威來源對了，還是會被誤導——因為查詢的條件寫錯。判程式活著沒，行程表是對的權威、pgrep 是對的工具，但你得比對它實際的行程名：一個程式可能以 symlink 的短名在跑，用你以為的名字 pgrep 就掃不到、誤判成掛了。判服務由誰提供，權威是服務註冊表而非畫面（送一則通知看畫面有沒有跳不可靠——沒跳可能是勿擾吃掉或根本沒送出）。這兩類的具體查法（pgrep -x、busctl 查 D-Bus 擁有者）見 程序、服務與狀態怎麼判。重點是：權威來源對，還要問對地方、用對條件。

卡住是資源問題還是相容問題：先看資源，別先怪相容性

一個耗時的操作中途停住時，很容易直接跳到「是不是這個平台不相容 / 這個東西在這台機器上跑不起來」。但這個結論成本很高（可能讓你放棄一條其實可行的路），而它的權威狀態很好查。一次原始碼編譯跑到一半停住，第一個該看的是資源：df -h 看磁碟是不是滿了、記憶體是不是被吃光——一次實際的案例就是主機磁碟寫滿把編譯中途打斷，清出空間後同一份原始碼接著編就過，跟平台相容性完全無關。先讀資源狀態排除掉最廉價的解釋，再去懷疑相容性這種昂貴的結論。

讀程式自己的 log：從症狀往上游找

當現象是「某個程式行為不對」，它自己的 log 幾乎總是比終端機捲過的畫面更接近真相。很多程式在終端機只印一段摘要，卻同時把詳細執行紀錄寫進一個 log 檔或系統日誌；當畫面上的訊息不足以定位時，那份 log 裡往往就有明確答案。

找 log 的常見去處：程式自己的 log 檔（常在 ~/.local/state/<程式>/ 或 ~/.cache/<程式>/ 底下）、systemd 服務的 journalctl -u <服務名>、或程式啟動時印出的 log 路徑。找到之後，關鍵是用症狀當關鍵字往上游搜——grep -iE 'error|fail|not found|does not exist' <log> 挑出異常行，或在 less 裡用 ?pattern 往回找「第一個」異常（不是停在最後一個下游錯）。一個指令因為前面某個檔案不存在而失敗，終端機可能只報一個看似無關的下游錯誤，但 log 裡會有那句 File does not exist 直指源頭。一個實際案例：某 shell 換了配色卻沒生效，畫面上什麼錯都沒有，是它的 log 裡一句「讀取 scheme 檔失敗：檔案不存在」點出根因——原來那個檔在 shell 啟動當下還沒被建出來。畫面沉默，log 說話。

這一層跟 可除錯的 bootstrap 是一體兩面：那篇談怎麼讓你自己寫的腳本產生一份可診斷的 log，這裡談除錯時怎麼去讀程式自己的 log。兩邊的共同紀律是：不要只盯著終端機捲動，去找那份持久的、詳細的權威紀錄。

遠端除錯反而逼出好紀律

透過 SSH 遠端除錯時，你看不到那台機器的畫面——這個限制反而是好事。看不到畫面，你就沒得靠肉眼猜，只能去讀權威狀態：查 log、查服務註冊、查行程表、查資源。很多在本地會犯的「看畫面就下結論」的錯，在遠端因為根本沒畫面可看而自動被避開。

反過來說，在本地（或看得到畫面的 VM）除錯時，畫面的存在是個誘惑：它讓你以為看到了就懂了。前面那個鎖屏誤判，正是發生在「看得到畫面」的情境——畫面上的密碼框太有說服力，反而蓋過了去讀 log 的動作。把遠端那套「沒有畫面、只信權威狀態」的紀律，也用在本地，就不會被畫面帶偏。

判讀紀律：四步

把上面的東西收成一套每次都能跑的流程：

1. 描述症狀：現象是什麼，先講清楚，不要在這步就急著下結論（「畫面出現密碼框」，不是「螢幕鎖了」）。
2. 定位權威來源：這件事的權威狀態記在哪——log、服務註冊、logind / systemd、行程表、資源用量（用上面那張表對照）。
3. 用對的工具讀它：讀那個權威來源，不是讀畫面、不是讀終端機捲過的殘影。
4. 權威跟表象矛盾時，信權威：如果讀到的權威狀態跟你肉眼的第一印象打架，信權威狀態、回頭修正第一印象——那個矛盾點通常就是你原本會猜錯的地方。

這套流程的價值不在任何單一工具，在於它讓你的判斷有一個可回溯的依據，而不是一串越猜越偏的直覺。

下一步

• 這套心法在遠端連線與終端機情境的應用，見 遠端連線與終端機問題。
• 機器連不到、或根本起不來時怎麼從權威狀態往下查，見 機器連不到或起不來。
• 程序在不在、服務歸誰、狀態怎麼判的具體招式，見 程序、服務與狀態怎麼判。
• 怎麼讓你自己的 bootstrap 腳本產生可讀的 log，見 可除錯的 bootstrap。

內容來自一次完整的 Arch Linux / Hyprland VM 實測與除錯：SSH 連不上、終端機噴亂碼、虛擬機開不起來、鎖屏狀態判錯、服務歸屬搞混——每個卡關點都被記錄下來，蒸餾成可重用的判讀路由，不綁特定發行版。

從哪篇開始

先讀 診斷心法 建立判讀紀律（讀權威狀態、四步流程），再依症狀進對應情境。

文章

依症狀的讀法

• 連不上、開不了機：機器 SSH 連不到、或虛擬機開不起來 → 機器連不到或起不來。
• 終端機行為怪：SSH 斷線後終端機噴亂碼、遠端打字亂碼、要從 SSH 操控圖形桌面 → 遠端連線與終端機問題。
• 某個狀態判不準：程式活著沒、服務歸誰、鎖沒鎖、session 還在不在 → 程序、服務與狀態怎麼判。
• 不想手動盯服務死活：想讓 service 掛掉時主動推播、或擔心整台機器當掉沒人知道 → 服務掛了怎麼自動知道。
• 想建立通用紀律：想要一套適用各種症狀的「不猜錯」判讀方法 → 診斷心法。

跟其他模組的交叉引用

• Linux 安裝與機器初始化——本系列的上游；把機器裝好、連入之後才輪到除錯。其中 可除錯的 bootstrap 談怎麼讓腳本產生可診斷的 log，與診斷心法的「讀程式自己的 log」一體兩面。
• Linux 工具選單——除錯要用的工具（CLI / 圖形桌面 / 遠端）有哪些選擇。
• 模組七：日誌判讀與診斷工具——桌面環境層的日誌判讀，與這裡的通用診斷紀律呼應。

SSH「連不上」本身（Permission denied、Host key verification failed、Connection refused）的判讀與修復，見 外部連入與無 key 的 bootstrap 路徑 的重連段落。這篇處理的是「連上了、但終端機或 session 的狀態不對」的那些情況。

SSH 斷線後本機終端機噴亂碼、狂跳字元

一個嚇人但無害的情況：SSH 連線被中斷後，你本機的終端機開始瘋狂輸出像 <35;80;24M 這樣的序列，尤其在你移動滑鼠時狂跳。這不是遠端機器在打字，是你本機的終端機被卡在滑鼠回報模式。

判讀關鍵在「什麼時候噴」：如果那串亂碼只在你移動滑鼠時出現、而且形如 數字;數字M，那就是滑鼠座標回報。成因是遠端跑的某個全螢幕程式（TUI、編輯器、終端機多工器）啟動時對終端機開了滑鼠追蹤模式，SSH 被硬斷時它來不及送出「關閉滑鼠模式」的序列就死了，於是你本機終端機還停在回報模式，滑鼠一動就把游標座標當輸入送進來。

修復是重置終端機的模式，跟遠端機器無關：

• 最快：開一個新的終端機分頁 / 視窗。模式是「那個終端機 session」的狀態，新視窗是乾淨的。
• 救現有視窗：先把滑鼠移開別動（洪流會停），盲打 reset 再 Enter，送出終端機重置。
• 若 reset 沒清掉，補送關閉滑鼠回報的序列：printf '\033[?1000l\033[?1002l\033[?1003l\033[?1006l'。

同一類的還有「alternate screen 沒還原」——遠端的全螢幕程式異常結束時，本機終端機可能卡在替代畫面緩衝區，看起來像畫面清空或凍結。reset 同樣能救。歸納起來：SSH 被硬斷後本機終端機行為異常，先懷疑「對端程式來不及還原終端機模式」，用 reset 或開新視窗處理本機終端機狀態，不必急著重連遠端。

遠端打字變亂碼、重複、位置錯亂

連上遠端後，如果互動式輸入變得不對——打一個字出現好幾個、游標位置錯亂、畫面重繪殘影——通常是兩層問題之一，判讀方式是分開排除。

第一層是字元編碼（locale）。從某些本機（例如 macOS）SSH 進 Linux 時，本機會把 LC_CTYPE 之類的變數帶過去；如果遠端沒有對應的 locale、就會退回 POSIX/C locale，讓終端機的行編輯（ZLE、readline）對多位元組字元的寬度判斷出錯，表現為輸入重複或錯位。判斷方式是在遠端 locale 看目前值、locale -a 看有沒有裝對應的 UTF-8 locale。修法是在遠端明確設好 LANG / LC_CTYPE 到一個實際存在的 UTF-8 locale，而不是讓它繼承一個遠端不認得的值。

第二層是終端機能力資料庫（terminfo）。你本機終端機的 TERM 值（例如某些新終端機用 xterm-ghostty 之類的自訂值）如果在遠端沒有對應的 terminfo 條目，遠端程式就不知道怎麼正確地清行、移動游標、重繪，畫面就會亂。判斷方式是在遠端 echo $TERM 看值、infocmp $TERM 看遠端認不認得。修法是把本機的 terminfo 條目送過去讓遠端安裝：infocmp -x $TERM | ssh <遠端> 'tic -x -'。

先分清是 locale 還是 terminfo，兩者症狀相似但修法不同：locale 是編碼寬度、terminfo 是繪製指令。查 locale 跟查 $TERM + infocmp 就能分開。

從 SSH 操控遠端的圖形桌面

想從一條純文字的 SSH 連線去操作遠端的 Wayland 圖形桌面（例如啟動應用、截圖、送 IPC 指令）時，會撞到兩類界線，判斷對是哪一類就知道怎麼繞。

第一類是圖形程式需要知道連到哪個顯示。SSH 進來的 shell 預設沒有圖形環境的環境變數，直接跑圖形程式會找不到 display。要對著遠端那個已經在跑的 Wayland session 操作，得補上它的環境變數：XDG_RUNTIME_DIR（通常 /run/user/<uid>）、WAYLAND_DISPLAY（socket 名，如 wayland-1）、必要時還有該 compositor 的 instance 變數與 DBUS_SESSION_BUS_ADDRESS。這些值怎麼撈：socket 名用 ls /run/user/$(id -u)/wayland-* 看；其餘變數直接從那個圖形 session 既有行程的環境複製最準——cat /proc/<compositor-pid>/environ | tr '\0' '\n' | grep -E 'WAYLAND_DISPLAY|XDG_RUNTIME_DIR|DBUS_SESSION|_INSTANCE_'（<compositor-pid> 用 pgrep -x Hyprland 之類找）。撈到後 export 進當前 SSH shell，這條連線就能對遠端的圖形 session 下指令、grim 截圖。

第二類是有些東西必須從實體圖形終端機（VT，即 Ctrl+Alt+F1~F6 切換的那些文字主控台）啟動，SSH 的 pty 起不來。Wayland 的合成器（compositor，畫桌面、把視窗合成到螢幕、管輸入輸出的核心程式，如 Hyprland）需要一個真正的圖形 VT 上的登入 session，拿到 DRM master（對顯示卡的獨佔繪圖控制權）與 logind seat（一組綁在一起的實體螢幕／鍵鼠裝置）才能啟動；從 SSH 的 pty 起它的預設 backend 會直接失敗（例如報 backend 建立失敗），因為預設 backend 要的 DRM master 與 seat 在 SSH 這條連線上不存在。判讀訊號：合成器一啟動就報 seat / DRM / backend 相關的錯，而你是從 SSH 起的——那就是這個界線。（例外：合成器多半有 headless backend，例如設 WLR_BACKENDS=headless 就不要 DRM master、不需 VT，專給 CI、雲端、自動化測試用；nested（跑在另一個 Wayland session 裡）也不需要。所以精確說是「預設 backend 需要圖形 VT」，不是「合成器一定起不來」。）

繞法是回到那台機器的實體圖形終端機去啟動 compositor，但「回到 VT」這件事也可以從 SSH 遠端做：

• sudo chvt <N> 從 SSH 切換那台機器目前顯示的虛擬終端機到第 N 個，比在虛擬機視窗裡跟宿主的 Ctrl+Alt+Fn 快捷鍵搏鬥穩定。
• 切過去卻是空白、沒有登入提示，通常是那個 VT 上沒有 getty 在跑：sudo systemctl start getty@tty<N>（開機時 enabled 但 inactive 是常見狀態，logind 的 autovt 沒觸發）。
• sudo fgconsole 確認目前是哪個 VT 在前景。

還有一個容易混淆的點：一台虛擬機可能同時有「序列主控台」跟「圖形顯示」兩個獨立輸出。在 guest 內 chvt 只切圖形那側，序列主控台看到的畫面不會變。如果你在虛擬機軟體裡看的是序列主控台，圖形桌面得切到顯示輸出那個 view 才看得到。判讀：切了 VT 但畫面沒反應，先確認你正在看的是哪個輸出。

判讀路由

遠端 / 終端機問題的分流：

• 本機終端機噴亂碼、只在動滑鼠時噴 → 滑鼠回報模式沒關（本機終端機狀態），reset 或開新視窗。
• 遠端打字重複 / 錯位 → 分 locale（查 locale）與 terminfo（查 $TERM + infocmp）。
• 圖形程式在 SSH 下找不到 display → 補 WAYLAND_DISPLAY / XDG_RUNTIME_DIR 等環境變數。
• compositor 從 SSH 起不來、報 seat/DRM 錯 → 它需要實體 VT，用 chvt + getty@tty<N> 回到圖形 VT 啟動。
• SSH 連不上（拒絕 / host key / refused）→ 見 外部連入與無 key 的 bootstrap 路徑。

這幾種分流的共同底線是先讀權威狀態（locale、$TERM、runtime 目錄、loginctl、fgconsole）再下判斷；背後的方法論見 診斷心法。

遠端機器突然連不上：先分清是哪一段斷

一台昨天還能 SSH 的機器今天連不上，第一步是確認「網路層通不通」，跟「SSH 服務在不在」分開。連線在 TCP 就 timeout（連 port 22 卡住沒回應），多半是網路層或機器沒在跑；連線有回應但被拒（Connection refused），是網路通、但那台機器上沒有服務在聽 port 22。

對虛擬機或同網段的機器，一個很有用的權威來源是鄰居表（IP 對 MAC 的對應）。要填起來需要對方在鏈路層有回應，所以它直接反映「對方在不在」。用 ip neigh 看目標 IP 的條目——優先用 ip neigh 而不是 arp -a，因為 ip（iproute2）在現代最小系統一定有，arp（net-tools）常常沒裝、跑了會 command not found 反而誤導。如果狀態是 INCOMPLETE（arp -a 顯示的是 incomplete），代表這個 IP 在鏈路層上根本沒有機器回應——不是 SSH 的問題，是那台機器的網路沒起來、或根本沒在跑。一個實際案例：一台虛擬機 SSH timeout，鄰居表顯示整個網段的 guest 位址全是 incomplete、只有閘道（宿主那側的橋接介面）是好的——這就定位到「宿主的橋沒問題，但橋的另一頭沒有 VM 在講話」，方向立刻從「調 SSH」轉到「去看 VM 的網路或開機狀態」。

定位到「機器在跑但網路沒起來」後，去那台機器的主控台（不是 SSH，SSH 正是連不上的東西）確認：ip -brief a 看有沒有拿到 IP、systemctl status <網路服務>（dhcpcd / systemd-networkd）看網路服務起了沒，需要時 sudo systemctl restart <網路服務> 重拉。IP 回來、鄰居表的條目從 incomplete 變成有 MAC，就通了。

還有一個常見誤區是 IP 變了。SSH 的別名、金鑰、known_hosts 都綁在特定機器身分上；換機器 / 重裝 / DHCP 重配後 IP 或 host key 變了，用舊別名會連錯或被 host key 檢查擋。這條的判讀與修法（ssh user@新IP 直連、ssh-keygen -R）見 外部連入與無 key 的 bootstrap 路徑。

網路通、但域名解析不了

有一種故障看起來像「網路壞了」，其實是 DNS 解析斷了：能連 IP、卻連不上任何用域名的東西——ping 8.8.8.8 通、但 ping google.com、pacman -Sy、curl https://... 全失敗。判讀要跟前面「網路沒起來」分開，因為網路層是通的，斷的是「域名 → IP」這一步。權威檢查：ping <IP> 通而 ping <域名> 不通、或 getent hosts <域名>（resolvectl query <域名> 若有 systemd-resolved）解不出位址，就定位到 DNS。常見成因是 /etc/resolv.conf 沒有可用的 nameserver（新裝或網路重設後沒填），或負責 DNS 的服務沒起來。修：確認 /etc/resolv.conf 有一行 nameserver（如 nameserver 1.1.1.1）、systemctl status systemd-resolved（若用它）。這一層在剛裝好的最小系統特別常撞到——ip -brief a 明明有 IP，pacman 或 bootstrap 卻抓不到套件，看起來像「網路好好的卻裝不了東西」，根因是 DNS 沒設。

虛擬機開不起來：分清 guest 內部還是宿主側

虛擬機開機失敗時，關鍵判斷是「錯誤來自 guest 內部（作業系統層）還是宿主側（虛擬化軟體 / QEMU 層）」。宿主側的錯誤訊息通常來自虛擬機軟體本身、在 guest 還沒開始開機前就跳出來，跟 guest 裡裝了什麼無關。

一個實例是 QEMU 報「找不到某個 ROM 檔」（例如 efi-virtio.rom）而拒絕啟動。第一反應可能是「檔案不見了要重裝」，但正確的第一步是去確認那個檔在不在——實際去虛擬機軟體的安裝目錄裡找（find <安裝目錄> -name '<rom名>'），會發現 ROM 檔明明就在。既然檔案在，「找不到」就不是缺檔，是 QEMU 執行時在它預期的路徑下找不到——成因隨宿主 OS 不同。在 macOS + UTM 宿主上，最常見的是 Gatekeeper app translocation：帶隔離屬性的 app 被搬到一個隨機唯讀路徑跑，讓 QEMU 解析資源的相對路徑失效，明明存在的檔案在那個執行路徑下就找不到。在 Linux 宿主上（沒有 translocation 這回事），同樣的「找不到 ROM」通常是缺對應套件（ovmf / ipxe-roms / edk2-ovmf）、libvirt XML 指的 ROM 路徑錯、或檔案權限不對——一樣先確認檔在哪、QEMU 是用哪個路徑去找。

另外兩個常見的「VM 起不來」故障也順手一起排除，它們不會特定產生「找不到 ROM」但常伴隨出現：上一次崩潰殘留的 helper 行程卡著（pgrep -af 'qemu|<虛擬機軟體名>' 找，沒清乾淨會佔住資源），以及宿主磁碟滿（df -h，啟動要寫暫存 / 狀態檔）。多數情況下，完全退出虛擬機軟體（連殘留 helper 一起清）+ 清出宿主磁碟空間 + 重新啟動，就恢復了。

判讀通則：虛擬機開不起來，先讀錯誤訊息判斷是 guest 還是宿主側；宿主側報「找不到某資源」而資源其實存在時，往「QEMU 是用哪個路徑找、那條路徑對不對」查（macOS 是 translocation、Linux 是缺套件 / 路徑 / 權限），再順手排除殘留行程與磁碟滿，而不是急著重裝。

磁碟滿是連鎖故障的共同根因

很多看起來各自獨立的故障，共同根因是磁碟滿。磁碟一滿，寫入就會失敗，而系統裡太多東西依賴寫入：SSH session 可能因為寫不了而被斷、正在跑的編譯 / 安裝會中途失敗、log 寫不進去、虛擬機狀態檔存不下導致連不上或開不起來。所以當你在短時間內撞到「連線斷了 + 某個任務失敗 + 服務怪怪的」這種一串症狀時，df -h 應該是很早就要做的檢查——一個廉價的檢查就可能一次解釋掉全部。

這裡有一個容易搞錯的點：清錯了地方。宿主跟 guest 是兩個獨立的檔案系統；虛擬機的宿主磁碟滿，跟 guest 內部磁碟滿，是兩件事。如果你 SSH 進 guest 裡 df 看到還有空間就以為沒事，但真正滿的是宿主的磁碟，那問題不會解決。判讀時要分清這串故障是「哪一台機器的哪個檔案系統」滿了——在宿主上 df -h 看宿主、在 guest 裡 df -h 看 guest，兩邊都要確認。清空間也要清在對的那一側。

判讀路由

• SSH timeout（TCP 卡住）→ 網路層或機器沒跑，查 ip neigh（INCOMPLETE = 對方沒回應）→ 去主控台看 ip -brief a / 網路服務。
• Connection refused → 網路通、但沒有服務在聽 → 去機器上確認 sshd 起了沒。
• 能 ping IP、不能用域名（pacman / curl 失敗）→ DNS 解析問題，查 /etc/resolv.conf 有沒有 nameserver、systemd-resolved 起了沒，不是網路層斷。
• 連錯 / host key 被擋 → IP 或身分變了，見 外部連入與無 key 的 bootstrap 路徑。
• 虛擬機開不起來、宿主側報「找不到資源」但資源在 → 主因查路徑隔離，再排除殘留行程（pgrep -af 'qemu\|...'）/ 磁碟。
• 一串症狀同時發生 → 早點 df -h，宿主與 guest 兩側都查，磁碟滿常是共同根因。

連不上只是最終症狀，真正的定位靠網路表、服務狀態、資源用量這些權威來源一層層往回推——完整的判讀紀律見 診斷心法。

底層的心法（讀權威狀態、不靠肉眼）見 診斷心法，這篇是它在「程序 / 服務 / 狀態」這一類的具體招式。

程式活著沒：比對正確的行程名

判斷一個程式在不在，行程表是權威來源，pgrep / ps 是對的工具，但成敗在於比對正確的行程名（comm，行程表裡記的執行檔短名，可從 /proc/<pid>/comm 看）。一個實際的坑：某個桌面 shell（畫桌面 UI 的圖形程式，不是 bash/zsh 那種命令列 shell）的可執行檔叫 quickshell，但透過名為 qs 的 symlink 啟動時，它在行程表裡的 comm 是 qs。這時 pgrep quickshell 找不到，很容易誤判成程式掛了、甚至誤觸「重啟」而引發更大的問題，實際上它以 qs 這個名字好好跑著。

可靠的做法：

• 先確認實際的 comm 名：ps -eo pid,comm | grep -i <關鍵字>，或看你啟動它的實際指令。
• 用精確比對：pgrep -x <comm>（-x 要求完全相符），或 pgrep -af <pattern> 連完整命令列一起比對，避免被 symlink 名 / 縮寫名騙。
• 另一個 comm 的坑：kernel 把 comm 截在 15 字元（TASK_COMM_LEN），名字超過 15 字的程式用 pgrep -x <完整長名> 反而 miss——這時改用 pgrep -af <pattern> 比對完整命令列。
• 別用一個「你以為的名字」掃過去就下生死結論——行程表沒騙你，是查詢條件寫錯。

進程活著 ≠ 內部子系統活著

比對到了正確的 comm、pgrep 也有輸出，只證明「這個進程存在」，不證明「它內部在正常運作」。有一類故障是進程好端端活著（pgrep 找得到、STAT 是正常的 S、在 poll 等事件、CPU 不高），但它內部某個子系統已經 wedged——例如一個圖形 shell 的 QML scene 因為上游錯誤（渲染 pipeline 建失敗之類）某個物件沒建起來變 null，於是負責互動的模組全部失效。表現是 bar 還畫得出來、卻點不動，keybind 叫不出東西，但焦點視窗打字正常。這時 pgrep 會騙你說「在跑」。

這種情況權威來源不是行程表，是程式自己的 log，而且這種 log 常常不在 journalctl、也不在你猜的路徑，要用該程式專屬的 log 指令（例如某桌面 shell 的 <shell> -l）。log 裡的 TypeError: Cannot read property 'X' of null 這類訊息，才是「進程活著但子系統死了」的定案證據。另一個更精準的活性探針是程式的 IPC 回不回真實狀態：正常時查詢會回傳資料、子系統死掉時回空——這比「進程在不在」可靠得多。判「進程活著到底有沒有在運作」時，讀它自己的 log 與 IPC，不是看 pgrep 有沒有輸出。桌面 shell 的具體案例與恢復（讀 caelestia shell -l 抓到 null 根因、重啟重建 scene）見 常見故障場景與恢復操作 的「畫得出來但互動死掉」場景。

服務由誰提供：問註冊表

「某個系統服務現在由哪個程式在提供」，權威來源是服務註冊，不是畫面。桌面服務多半註冊在 D-Bus（Linux 桌面的行程間訊息匯流排）上：一個服務用一個名字掛在上面，而同一個名字同一時間只能被一個行程擁有。以桌面通知為例，org.freedesktop.Notifications 這個 D-Bus 名同一時間只有一個擁有者——兩個通知 daemon（例如 mako 跟某個桌面 shell 內建的通知服務）不能共存，誰先註冊誰佔著，後者只能等前者退出。

想知道現在是誰接管，查註冊表而不是送一則通知看畫面：

1# 查 org.freedesktop.Notifications 目前被哪個連線擁有
2owner=$(busctl --user call org.freedesktop.DBus /org/freedesktop/DBus \
3  org.freedesktop.DBus GetNameOwner s org.freedesktop.Notifications | awk '{print $2}' | tr -d '"')
4# 把那個連線換算成 PID，再看行程名
5pid=$(busctl --user call org.freedesktop.DBus /org/freedesktop/DBus \
6  org.freedesktop.DBus GetConnectionUnixProcessID s "$owner" | awk '{print $2}')
7ps -o comm= -p "$pid"

停掉舊 daemon 前擁有者是舊的、停掉後換成新的，就確認接管成功。這比「送通知看畫面有沒有跳」可靠——畫面沒跳可能是勿擾模式吃掉、可能根本沒送出，畫面反應不等於服務歸屬。切換兩個搶同一服務名的 daemon 時，這也解釋了為什麼「新的裝了卻沒作用」：舊的還佔著名字，新的靜默註冊失敗（通常只在它的 log 留一行 warning），得先停掉舊的。

桌面 session 有沒有被鎖：認清是哪一層的鎖

判斷一個圖形 session 有沒有被鎖，最容易被畫面帶偏，因為「畫面上有密碼框」很有說服力、卻不等於 session 真的被鎖（現代桌面 shell 的儀表板常內嵌鎖屏樣式的 widget）。而且鎖有不同層，查錯層會得到誤導的答案。

關鍵是分清兩種鎖：

• logind 層的鎖：systemd 登入管理的 session 鎖，權威狀態是 loginctl show-session <id> -p LockedHint。
• Wayland 合成器層的鎖：走 ext-session-lock 協議、由合成器（compositor，Wayland 下負責把各視窗合成到螢幕、管輸入輸出的核心程式，約當 X11 時代的視窗管理器加顯示伺服器；Hyprland、Sway 等都是）管的鎖，跟 logind 是獨立機制。這種鎖 loginctl 的 LockedHint 查不到——不是沒鎖，是查錯層。（用 GNOME / KDE 的鎖屏走的機制不同，以下的 ext-session-lock 判法與復原針對 wlroots 系的 Wayland 合成器。）

所以「loginctl 沒有 LockedHint、pgrep 找不到獨立鎖屏程式」不足以斷定「沒鎖」：合成器層的鎖不歸 logind、而鎖屏畫面可能由 shell 主程式在自己行程內畫（沒有獨立可執行檔可抓）。這種情況真正的權威來源是那個 shell 自己的 log（有沒有載入鎖屏模組、idle 計時器有沒有觸發鎖定），或直接看 compositor 的 session-lock 狀態。判鎖看合成器 / shell 的 log，不是 loginctl、更不是畫面有沒有密碼框。

鎖屏程式死掉造成的死局與復原

ext-session-lock 有一個安全設計：持鎖的鎖屏程式若在鎖定狀態下崩潰 / 被中止，compositor 會保持鎖定、不會因為鎖屏程式沒了就解鎖（否則殺掉鎖屏程式就成了繞過鎖的漏洞）。表現是畫面卡在「鎖屏程式已死」的安全提示。復原要從另一個 VT 或 SSH 用 hyprctl keyword misc:allow_session_lock_restore 1 允許新鎖屏 client 接管、再 hyprctl dispatch exec hyprlock 起一個接管後輸密碼解鎖。完整機制、兩層鎖的關係、各 compositor 的差異，見 Wayland Session Lock 卡。

診斷紀律：測鎖屏、或 pkill 一個持鎖的鎖屏程式時，要預期它把 session 卡在鎖定——這是協議的安全設計，不是 bug。 自動化 / 無人值守流程尤其要避免在持鎖狀態下殺鎖屏程式。

終端機多工器的 session 還在不在

用 zellij / tmux 這類多工器跑遠端長任務時，判斷「重連後那個 session 還在不在」的權威來源是多工器自己的 session 列表，不是「我 SSH 斷了所以應該還在吧」的假設。zellij ls（或 tmux ls）會列出 session 與狀態：多工器是常駐在遠端的程序，SSH 斷不影響它，所以只要那台機器沒重開，attach 就能接回去；但如果機器重開過、或那個 session 因為資源不足（例如磁碟滿觸發的連鎖）被殺，列表會顯示它已 EXITED / 不存在，這種接不回去。

這裡有個順序上的紀律：當一個 session 可能已經死掉、而它裡面跑的任務有你在意的產出時，先確認產出有沒有被安全保存，再處理 session。 例如任務是在改 git repo，先 git -C <repo> status 跟 git log @{u}..（本地有、遠端沒有的 commit）確認有沒有沒推送的東西、把該推的推掉，再去 zellij delete 清死 session。搞反順序、先清了 session，可能連帶失去唯一還記得那些改動的地方。權威狀態（git 的推送狀態、多工器的 session 列表）先讀清楚，再動手。

判讀路由

• 判程式活著 → pgrep -x <正確 comm> / pgrep -af <pattern>，先確認實際 comm 名，別用猜的名字。
• 判進程活著但「有沒有在運作」→ 讀程式自己的 log（可能要用它專屬的 log 指令、不在 journalctl）+ 它的 IPC 回不回真實狀態，不是看 pgrep 有輸出就當正常。
• 判服務歸誰 → busctl 查 D-Bus name 擁有者 → 換算 PID → comm，不看畫面反應。
• 判 session 鎖沒鎖 → 分清 logind 層（loginctl LockedHint）vs 合成器層（ext-session-lock，看 compositor / shell log），不看畫面有沒有密碼框。
• 鎖屏程式死掉卡住 → allow_session_lock_restore + 重起鎖屏程式接管解鎖。
• 判多工器 session 存活 → zellij ls / tmux ls；可能已死且有在意的產出時，先確認產出已保存 / 已推送再清 session。

判不準時，診斷心法 的四步（描述症狀、定位權威來源、用對工具讀、矛盾時信權威）是通用的回退。

理解這個框架後，監控就不是「裝一套很重的東西」，而是分層選擇：從 systemd 內建的失敗鉤子（不裝任何額外服務），到推播管道，到「整台機器死掉」的體外心跳，到完整的指標儀表板。多數人只需要前一兩層。

你現在手動在做的事（要被取代的基線）

在自動化之前，先認清手動版本——這也是所有告警底層讀的同一個權威來源：

1systemctl --failed          # 現在有哪些 unit 處於 failed（開機後系統怪怪的先掃這個）
2systemctl is-failed <unit>  # 單一 unit 明確判失敗（比 is-active 直接）
3journalctl -u <unit> -f     # 即時跟一個 unit 的 log

systemctl --failed 就是「服務死活」的權威清單。手動版的問題不是不準，是你得記得去看。下面每一層都是把「記得去看」換成「壞了它來找你」。

第一層：systemd 原生 OnFailure 鉤子（不裝額外服務）

systemd 每個 unit 進入 failed 狀態時，可以自動觸發另一個 unit。這是最正統、零額外依賴的做法——告警邏輯就寫成一個普通的 systemd service。它由三塊組成：一個負責送通知的處理器 unit、一個實際送出的腳本、以及在你要監控的 unit 上掛一行 OnFailure=。

通知處理器是一個 template unit（@ 表示可帶參數），參數 %i 會是失敗的那個 unit 名：

1# /etc/systemd/system/alert@.service
2[Unit]
3Description=Alert on failure of %i
4[Service]
5Type=oneshot
6ExecStart=/usr/local/bin/notify-failure %i

送出腳本負責把「哪個 unit、在哪台機、什麼時候」推出去。這裡有個實測踩到的坑：在 systemd service 的執行環境下，hostname 指令可能回傳空字串，要改用 uname -n 或讀 /etc/hostname 才穩：

 1#!/bin/bash
 2# /usr/local/bin/notify-failure   （記得 chmod +x）
 3unit="$1"
 4# 只在「真正放棄」時告警：OnFailure 每次失敗都觸發（含 auto-restart 中途，見下節實測），
 5# auto-restart 中途 ActiveState 是 activating、撞重試上限才進 failed。gate 掉中途避免洗告警。
 6state="$(systemctl show "$unit" -p ActiveState --value)"
 7[ "$state" = failed ] || exit 0
 8host="$(uname -n)"                     # 不要用 hostname，systemd 環境下可能回空
 9ts="$(date -Is)"
10topic="你的私密topic"
11curl -fsS \
12  -H "Title: $host: $unit failed" \
13  -d "$unit 於 $ts 進入 failed" \
14  "https://ntfy.sh/$topic"

在要監控的 unit 掛上鉤子。針對單一 unit，加一行：

1[Unit]
2OnFailure=alert@%n.service    # %n 是本 unit 的全名，會展開成 alert@<本unit>.service

要一次套用到所有 service，用 top-level drop-in（放在 service.d/ 這個型別目錄下的設定會套用到每個 .service）：

1# /etc/systemd/system/service.d/onfailure.conf
2[Unit]
3OnFailure=alert@%n.service

改完 sudo systemctl daemon-reload。一個必須注意的遞迴陷阱：全域 drop-in 也會套到 alert@ 自己，它若失敗會觸發自己。給 alert@.service 一個清空 OnFailure= 的 override（[Unit] 段寫 OnFailure=）擋掉。

這條鏈是實測驗證過的：故意讓一個 ExecStart=/bin/false 的測試 service 失敗，systemd log 出現 Triggering OnFailure= dependencies、alert@ 處理器被觸發跑完、curl 推到 ntfy 回 HTTP 200——通知確實送出，全程沒有肉眼介入。

先自動重啟、放棄了才吵你

多數暫時性失敗（一次連線抖動、一個 race）自己重試就好，不值得半夜叫醒你。把「自動復原」跟「告警」分兩段：讓 systemd 先重啟幾次，撐過重試上限才真的算放棄。

1[Service]
2Restart=on-failure
3RestartSec=5
4[Unit]
5StartLimitBurst=3          # 重試 3 次
6StartLimitIntervalSec=60   # 60 秒內都失敗才進 failed（start-limit-hit）

這裡有個實測踩到、跟直覺相反的坑：OnFailure 不是「放棄才觸發」，而是每一次失敗都觸發——包含 Restart=on-failure 的每次 auto-restart 中途。實測一個反覆 crash 的服務（重試 3 次後放棄）觸發了 4 次 OnFailure（3 次 auto-restart + 1 次最終 start-limit-hit）。所以只靠 Restart= + StartLimit= 這段 config，你會被每次瞬斷洗告警。

真正做到「只在放棄才吵」，靠的是上面送出腳本開頭那道 gate：systemctl show <unit> -p ActiveState 在 auto-restart 中途是 activating、撞上限進 failed 才是 failed，腳本只在 failed 才送。加上 gate 後同一個 crash 測試從 4 次告警降到 1 次（只剩最終放棄那次）。config 負責「重試幾次」，handler 的 gate 負責「只在終局告警」——兩段合起來才是完整的「先重啟、放棄才吵」。

抓「進程活著但沒在做事」：外部健康探針

OnFailure 抓的是「進程狀態變了」——crash、exit、被 kill。但服務可能進程還在、卻沒在做事：hung、deadlock、內部子系統壞掉。這種 systemd 看它還 active、不會觸發任何告警——正是「進程活著 ≠ 在運作」那條，搬到監控場景。

要抓這種，得從外面主動戳它、看它回不回應：一個 timer 定時對服務發一個健康請求（HTTP 服務就 curl 它的 /health）並設逾時；戳不動、逾時失敗，就讓「那個檢查」自己 failed，一樣走 OnFailure 告警。

1# health-check.service（oneshot）+ 一個每 2 分鐘跑的 .timer
2[Service]
3Type=oneshot
4ExecStart=/usr/bin/curl -fsS --max-time 5 http://127.0.0.1:8899/health

實測對照最清楚：讓一個健康服務卡在 sleep（進程還在、單執行緒不再回應），systemctl is-active 仍顯示 active——systemd 沒察覺；但這個外部探針 curl /health 5 秒逾時、check 失敗、告警發出。systemd 抓進程死、外部探針抓進程活著但 hung，兩層互補、缺一漏一種。

canary：先證明告警管線本身是好的

監控最怕的失效模式是「出事時才發現它早就不會叫了」。防這個的辦法是養一隻 canary——一個你可控的假服務，專門用來確認整條管線是活的。它一物兩用：

• 驗證管線：故意弄掛它，看「失敗 → OnFailure → 推送」真的一路通到你手機，不必拿 sshd 這種真服務去冒險。
• 當活性訊號：它自己若無故失敗告警，等於告訴你告警系統本身還在運作。

做法是一個極簡 HTTP 服務（stdlib 就夠、不必框架），留幾個測試入口：/health 正常回、/crash 故意退出（測 OnFailure）、/hang 進程活著但不回應（測外部探針）。這樣任何時候都能一鍵重驗監控沒有默默失效。

第二層：推去哪裡（關鍵是能離開這台機器）

處理器腳本裡那一段 curl 可以換成任何管道：

• ntfy（ntfy.sh 或自架）：一行 curl 推到手機，最省事，上面的例子就是。它怎麼運作、公共站 vs 自架、以及「topic 名稱就是唯一的密碼」這個安全模型，見 ntfy：推送通知服務。
• email：要先設好一個 MTA（如 msmtp），腳本改成 mail / sendmail。
• Telegram bot、Apprise（一個工具打多個目標）等。

判準只有一條：告警要送到機器外。送桌面 notify-send 只有你正盯著螢幕時才有用；送手機或 email，離開座位、人在外面也收得到。一台跑正事的機器，告警管道應該落在它之外。

第三層：整台機器死掉怎麼辦（監控自己的盲點）

OnFailure 有個根本限制：它靠 systemd 觸發，機器整台掛了（當機、斷電、kernel panic），systemd 自己都沒了，發不出任何告警。 這是所有「機器自己監控自己」方案的共同盲點——它報得了服務的死，報不了自己這台的死。

覆蓋這一層要反過來做：讓機器定時對一個體外的服務「報平安」，平安訊號一停，由那個體外服務替你告警。這叫 dead-man’s switch（心跳監控）。

1# /etc/systemd/system/heartbeat.service
2[Service]
3Type=oneshot
4ExecStart=curl -fsS https://hc-ping.com/<你的-uuid>
5# 搭配一個 heartbeat.timer，OnUnitActiveSec=5min 定時打

心跳超過設定時間沒到，healthchecks.io（或自架的 Uptime Kuma）就通知你。體內的監控管不了自己這台的死亡，一定要有體外的一隻眼睛——這跟本系列 機器連不到或起不來 是同一個問題的兩面：那篇是機器已經不回應時從外面怎麼查，心跳是讓「不回應」這件事本身自動觸發告警。

第四層：要指標、趨勢、門檻（不只是 up/down）

當你要的不只是「掛了沒」，而是 CPU、記憶體、磁碟、延遲的趨勢與門檻告警（例如磁碟用量超過 80% 就先警告，接上本系列反覆出現的「磁碟滿連鎖」），就進到完整監控堆疊：

這一層不是每個人都需要。單機、只想知道某個服務死活，第一層就夠；要看趨勢、跨機、設門檻，才值得付這層的設定與維運成本。

先確認有沒有，沒有就從最簡單開始

監控最好在出事之前就建好，不是等第一次沒人發現的當機才想到。有兩個時機該主動確認這台機器有沒有在監控自己：裝好一台新機器時，跟發現自己反覆在除同一個服務的失敗時。確認的方式就是讀權威狀態：

1systemctl --failed                      # 現在有沒有 failed 的
2systemctl show sshd -p OnFailure        # 關鍵服務有沒有掛告警鉤子

沒有任何監控的話，從最簡單那層開始建，別一開始就上重的：第一層的 OnFailure + ntfy 就能讓「服務掛了」主動找上你，零額外 daemon、幾個檔案就設好。遠端機器至少把 sshd 掛上——它掛了你就失聯，是最該先監控的一個。等你真的需要趨勢圖、跨機、或告警內容不能經過第三方時，再往自架 ntfy（帳號 + ACL）跟完整監控堆疊爬。多數單機、個人用的情境，停在第一層就夠。

依情境選

把上面四層對回你實際要監控的東西：

• 某個 service 掛了想被通知 → 第一層 OnFailure drop-in + ntfy。不裝額外 daemon，最貼近 systemd。
• 希望先自動重啟、救不回來才告警 → 第一層再加 Restart=on-failure + StartLimit*。
• 怕整台機器當掉沒人知道 → 第三層心跳 / dead-man switch。這層體內方案覆蓋不到，必須體外。
• 要看資源趨勢、跨多台、設門檻告警 → 第四層，單機用 Netdata、多機用 Prometheus 堆疊。

判準是先分清你要監控的層級：單一 service 的死活、整台機器的死活、還是資源的趨勢——三種對應不同層，別拿其中一種去蓋另一種。最常見的誤區是以為體內的 OnFailure 能報自己這台的當機，那正是它的盲點。

下一步

• 告警把你叫來之後，怎麼判那個服務到底是什麼狀態（failed、restart loop、還是活著但子系統 wedged）→ 程序、服務與狀態怎麼判。
• 機器完全不回應、心跳斷掉之後從外面怎麼查 → 機器連不到或起不來。
• 底層那套「讀權威狀態、不靠肉眼猜」的判讀紀律 → 診斷心法。

元件位置 = 定位基準（anchor）+ 相對基準的偏移。元件「跟著狀態飄」不是元件本身的問題、是它的 anchor 隨狀態在動。 Debug 時把元件位置拆成「找錨點 → 算偏移」兩層、確認哪一層在隨狀態變化。

為什麼狀態化錯位的根因不在元件本身

商業邏輯

CSS 計算元件位置時，元件總是「相對某個 reference」 — block flow 是「上一個 sibling 的下緣」、absolute 是 offset parent、grid item 是 grid container。這個 reference 才是元件位置的決定因素。

當 reference 在不同狀態下尺寸或位置變動，元件被動跟著動 — 看起來是元件「自己飄」，根因卻在 reference。

三層拆解 debug 法

多數狀態化錯位的根因在第 2 或第 3 層、不在第 1 層。

這次任務的實際情境

觀察

新加 scope UI（搜尋範圍 radio group）後出現三個狀態的位置不一致：

判讀

第一輪猜測：scope UI 自己的 CSS 在不同狀態下不同 — 用 playwright 看 computed style，發現三狀態下 scope 的 grid-row 都是 3、CSS 屬性沒變。

第二輪：用 playwright getBoundingClientRect() 量 scope 的位置，發現 y 座標確實在三狀態下不同。

第三輪：往上一層看「scope 的 grid container 是誰、container 的 grid template 在不同狀態下變了嗎」。發現 search-shell 的 grid template-rows 是 auto、自動依子元素內容撐開。

關鍵發現：.pagefind-ui__drawer 不是 .pagefind-ui 的直接子節點 — 它在 <form> 內。

1.pagefind-ui (display: contents)
2└── form.pagefind-ui__form (grid-row: 2)
3    └── div.pagefind-ui__drawer (grid-row: 4 設了沒生效)

於是：

• 初始：form 只含 input、row 2 矮、scope 在 row 3 緊接 row 2 下。
• 輸入後：form 含 input + drawer（187 個結果）、row 2 撐到全頁高。grid-row 4 比 row 2 後 — 但 drawer 被 form 包住、整個 form 在 row 2 — scope（row 3）在 form 之後 = 結果之後。

scope 的 anchor（grid container 的 row 排列）在 form 撐開時改變 — anchor 在動、scope 跟著動。

執行

確認 anchor 問題後改用 absolute 定位：scope 浮在 form 之上、drawer 用 margin-top 讓位。scope 的 anchor 改為 .search-shell 的 position: relative、不再依賴 form 的尺寸。三狀態下位置一致。

拆解 anchor 的四個工具

1. 找元件的 reference

2. 用 getBoundingClientRect 量

1const el = document.querySelector('.search-scope');
2console.log(el.getBoundingClientRect());

在三個狀態下分別量、比對 y 座標。差異對應到「reference 在動」。

3. 往上追 ancestor chain

1let parents = []; let el = target;
2while (el) {
3  parents.push(el.tagName + '.' + el.className);
4  el = el.parentElement;
5}
6console.log(parents);

找出 reference 是誰、reference 的 reference 是誰、一層一層追到「不會動」的元素。

4. Computed style vs DOM tree 一起看

CSS 規則在 computed style 顯示為「我設了什麼」、DOM tree 顯示「實際巢狀關係」。兩者一起看才知道規則為什麼沒生效。

內在屬性比較：三種定位策略對狀態化錯位的抵抗

當一個元件需要在多種狀態下保持固定位置 — 優先 absolute（搭配明確的 offset parent）。

設計取捨：對抗狀態化飄移的定位策略

四種做法、各自機會成本不同。這個專案選 A（absolute + 自定義 offset parent）當預設、其他做法在特定情境合理。

A：Absolute + 穩定 offset parent（這個專案的預設）

• 機制：元件 position: absolute、選定一個尺寸不隨狀態變動的 ancestor 作為 offset parent
• 選 A 的理由：anchor 不變則元件不動、跨所有互動狀態位置一致
• 適合：需要在多狀態下保持固定位置的元件
• 代價：跳出 layout flow、附近元件需要手動讓位（margin spacer）

B：Grid / Flex item

• 機制：把元件當 grid / flex container 的子項、用 grid-row / flex-order 排
• 跟 A 的取捨：B 自然 reflow、A 完全 anchor-driven；B 在 container 內容隨狀態撐開時、grid 排序跟著重算
• B 比 A 好的情境：container 尺寸不隨狀態變動的場景（純 layout、內容靜態）

C：Static / block flow（預設 layout）

• 機制：不設 position、跟 sibling 自然排
• 跟 A/B 的取捨：C 最簡單、A/B 主動處理 anchor；C 完全受前置 sibling 影響、狀態化飄移風險最高
• C 才合理的情境：頁面內容極穩定、無狀態切換 — 否則第 N 個元素位置受前 N-1 個元素影響

D：Fixed（相對 viewport）

• 機制：position: fixed、anchor 是 viewport
• 跟 A 的取捨：D 永遠在 viewport 同位置、A 跟著內容；D 對「導航類元件」合理、對「內容相關元件」不合理
• D 比 A 好的情境：永遠可見的功能元件（toolbar、scroll-to-top button）

判讀徵兆

核心原則：元件「會飄」不是元件的個性、是它依賴的東西在飄。先找飄的源頭，不要追著元件改。

UI 除錯的最小可驗證單位是「一個有明顯邊界的色塊」。 版型用色塊先驗證 grid / flex / absolute 是否如預期排在該在的位置，確定後再串實際內容。一次組裝完整 UI 在版型錯時 debug 困難 — 顏色、字型、邊距、padding 全部一起出問題、根因混雜難辨。

為什麼色塊比實際內容更適合 debug

商業邏輯

UI 由「位置、尺寸、視覺樣式、互動」四層組成。Debug 時要分層處理 — 一次只解一層、解完再下一層。

色塊把後三層都拿掉、只留「位置與尺寸」 — 看到的就是 layout 規則的純粹結果。實際內容把所有層混在一起、看到的位置可能受字型 advance、line-height、margin collapse 等多重因素影響、難以歸因。

漸進式組裝順序

每階段獨立驗證、有問題就停在那階段修。

這次任務的實際應用

觀察

要驗證搜尋頁的版型：「左側 filter sidebar + 右側中央內容（H1、search input、results）」。

第一次嘗試：直接把 Pagefind UI 組起來、調 CSS。結果版型錯時不知道是哪層問題 — 是 grid 排序錯？是 sidebar 寬度錯？是 padding 推到位置不對？

判讀

退回最小可驗證單位：把 filter 整個換成一個寫死寬度的紅色色塊：

1<aside class="search-filter-debug">
2  filter 區（先寫死寬度與底色驗證版型）
3</aside>

1.search-filter-debug {
2  width: 400px;
3  background: red;
4  min-height: 240px;
5  position: absolute;
6  /* ... */
7}

紅色背景一眼看出色塊在哪 — 確認了：

• 色塊在 main 左外側（符合）
• 色塊頂端對齊 H1（符合）
• 寬度 400px、與 main 間距 2rem（符合）

版型驗證後再換上實際 filter UI。

執行的迭代步驟

每步只驗證一件事、有問題就停。

內在屬性比較：兩種除錯起點

漸進的成本是「多寫一個過渡版本」、收益是「debug 範圍縮到最小」。多元件 layout 永遠選漸進。

色塊的設計要點

1. 顏色明顯、易於辨識

紅色、洋紅、亮藍 — 跟頁面其他元素差異大。debug 完拿掉、不影響正式設計。

2. 邊界清楚

寫死 width / height / min-height、不要讓色塊「自適應」 — 自適應時看不出色塊本身有沒有按預期擺放（可能是它縮成 0 還是真的擺對位置）。

3. 內含可辨識的標籤

1<aside>filter 區（先寫死寬度與底色驗證版型）</aside>

文字標明這是什麼、目前是「驗證版型」狀態 — 不會被誤認為正式設計。

4. 拆解成最小可驗證的單位

要驗證「左欄 + 右欄」就用兩個色塊。不要在第一階段就加 filter 內容、search input 等元件 — 那些是後續階段。

設計取捨：UI debug 的起點選擇

四種做法、各自機會成本不同。這個專案選 A（色塊漸進組裝）當預設、其他做法在特定情境合理。

A：色塊 placeholder 漸進組裝（這個專案的預設）

• 機制：先用寫死寬度的彩色色塊代替每個區塊、確認 layout 後再加內容、再加樣式
• 選 A 的理由：每階段只解一個問題、debug 範圍縮到最小
• 適合：複雜 layout、多元件協作、不確定 layout 規則對不對
• 代價：多一個過渡版本、總時間略長（但 debug 時間短得多）

B：一次組裝完整 UI

• 機制：直接把 layout + 內容 + 樣式全部寫好、看結果
• 跟 A 的取捨：B 一次到位（如果一次對）、A 漸進；B 在版型錯時 debug 困難（多層問題交織）
• B 比 A 好的情境：簡單 layout（< 3 元件、無複雜共存）、有 100% 把握一次到位

C：用 wireframe 工具（Figma / Sketch）

• 機制：先在設計工具畫 wireframe、確認設計後再進實作
• 跟 A 的取捨：C 在設計階段確認、A 在實作階段確認；C 適合「設計尚未確定」、A 適合「設計確定但實作有 layout 風險」
• C 比 A 好的情境：設計階段 — 還沒進實作、不確定要做什麼

D：直接用真實內容 debug 版型

• 機制：拿真實 pagefind UI / 文章內容當 debug 對象
• 成本特別高的原因：內容自帶字型 / padding / margin、跟版型問題混在一起、debug 從哪下手都可能錯
• D 是反模式：真實內容適合驗證、不適合 debug — 內容自帶字型 / padding / margin、跟版型問題混在一起、debug 從哪下手都可能錯

判讀徵兆

核心原則：UI 除錯的速度跟「起點的簡單度」成正比。從色塊出發、永遠比從完整 UI 出發快。

跟 #68 驗收的時間軸 的關係：placeholder 漸進是 Checkpoint 2「開發中」的具體做法 — 每階段只引入一個變數、邏輯錯誤跟視覺錯誤能即時 catch。跳階段（直接寫真實內容 + 完整樣式）= 把開發中 checkpoint collapse 成單次驗收、漏掉的失敗會推到 ship 前 / ship 後。

Playwright 不是最後手段、是縮短診斷迴圈的工具。 當靜態 CSS 推理 + 視覺截圖溝通的循環失敗 ≥ 2 次、就應該停止推理、改用 playwright browser_evaluate 直接讀 live DOM 與 computed style。早一點用 = 試錯次數更少、心智負擔更輕。

為什麼推理迴圈有極限

商業邏輯

CSS 行為由「規則 + DOM tree + 樣式繼承 + 框架渲染」四個變數共同決定。靜態推理只能基於假設的 DOM tree — 假設錯了、推理就錯。視覺截圖溝通只能傳達「結果是什麼」、無法傳達「為什麼是這個結果」。

Playwright 的 browser_evaluate 直接執行 JS 在 live page、返回真實的 DOM tree、computed style、bounding rect — 把「四個變數」全部變成已知。

推理 vs 量測的成本曲線

第 1 次推理快、後續成本爆炸；playwright 起步慢、後續穩定。門檻在第 2 次。

這次任務的實際情境

觀察

要把 search scope UI 放在「搜尋輸入框與結果之間」。

第一輪：基於 class name 推測 DOM tree、用 grid + display:contents 設 grid-row 排序。第二輪：發現 scope 跑到頁尾、嘗試調 grid-template-rows。第三輪：嘗試 absolute 定位但時機不對。第四輪：使用者說「思路錯了」、要我換方向。

判讀

四輪推理都基於同一個假設：drawer 是 .pagefind-ui 的直接子節點、跟 form 並列。實際用 playwright 一查：

1const drawer = document.querySelector('.pagefind-ui__drawer');
2let parents = []; let el = drawer;
3while (el && el !== document.body) {
4  parents.push(el.tagName + '.' + el.className);
5  el = el.parentElement;
6}

返回：

1DIV.pagefind-ui__drawer
2FORM.pagefind-ui__form    ← drawer 在 form 內！
3DIV.pagefind-ui

假設錯了 — drawer 是 form 的 child、不是 sibling。grid 規則無論怎麼寫都不會生效，因為 drawer 跟 form 共用同一個 grid cell。

四輪推理 ≈ 30 分鐘。Playwright 一次查清楚 ≈ 2 分鐘。

執行

確認 DOM 結構後：grid 不適合這個場景、改用 absolute + drawer margin-top spacer。一次到位。

Playwright 在開發循環的三個位置

1. 假設驗證

寫 CSS 規則前先量 DOM、確認結構符合假設。

1async () => ({
2  parents: [].slice.call(document.querySelectorAll('.target')).map(el => {
3    let chain = []; let n = el;
4    while (n) { chain.push(n.tagName + '.' + n.className); n = n.parentElement; }
5    return chain;
6  })
7})

2. 行為驗證

Layout 規則寫完後驗證實際結果。

1async () => ({
2  rect: document.querySelector('.target').getBoundingClientRect(),
3  computed: getComputedStyle(document.querySelector('.target')).gridRow,
4})

3. 互動驗證

驗證使用者互動後的狀態。

1async () => {
2  const input = document.querySelector('.search-input');
3  input.value = 'pre';
4  input.dispatchEvent(new Event('input', { bubbles: true }));
5  await new Promise(r => setTimeout(r, 1000));
6  return Array.from(document.querySelectorAll('.result'))
7    .filter(el => getComputedStyle(el).display !== 'none')
8    .map(el => el.textContent.slice(0, 50));
9}

內在屬性比較：四種 debug 方法

選擇順序：簡單 layout 用 DevTools；複雜 / 反覆 debug 用 playwright；推理只在第 1 次試錯前。

引入 playwright 的最低門檻

1# 啟動本地 server（任何方式）
2python3 -m http.server 8000 --directory public
3
4# 或專案有 hugo
5hugo server

Playwright MCP 提供：

• browser_navigate(url) — 開頁
• browser_evaluate(fn) — 執行 JS 拿結果
• browser_take_screenshot() — 截圖
• browser_snapshot() — accessibility tree

寫一個 evaluate fn ≈ 30 行 JS，比反覆推理快得多。

設計取捨：CSS / DOM debug 工具選擇

四種做法、各自機會成本不同。這個專案在推理 ≥ 2 次失敗後選 A（playwright browser_evaluate）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻 抽象原則在「debug 工具切換」這個面向的應用。

A：Playwright browser_evaluate 程式化讀 live DOM（這個專案的預設）

• 機制：起 server、用 browser_evaluate 寫 JS query 讀 DOM tree / computed style / bounding rect
• 選 A 的理由：取得資訊量最大、可重跑、可寫成測試
• 適合：推理失敗 ≥ 2 次、複雜或反覆 debug 的情境
• 代價：起步成本中（需要 server + 寫 evaluate）

B：靜態 CSS 推理 + 視覺截圖溝通

• 機制：純看 CSS 與假設的 DOM 推測、用截圖跟使用者溝通
• 跟 A 的取捨：B 起步成本 0、A 起步成本中；但 B 第 2 次以後成本爆炸（每輪都基於前輪錯誤假設）
• B 比 A 好的情境：第 1 次嘗試、預估假設正確機率高（簡單修改）

C：瀏覽器 DevTools 手動查

• 機制：開 DevTools 切 Elements / Computed / Layout 面板手動探索
• 跟 A 的取捨：C 不需 server / playwright setup、但每次手點切面板慢、不能寫成測試
• C 比 A 好的情境：一次性確認、不需要重複 query 同樣資訊

D：寫成 playwright 測試固化

• 機制：把 debug 過程寫成 playwright 測試、未來自動跑
• 跟 A 的取捨：D 是 A 的延伸 — 第 2 次 debug 同個版型時、值得固化（#15 layout tests）
• D 比 A 好的情境：版型 bug 出現第 2 次以上、值得寫測試防止回歸

判讀徵兆

核心原則：縮短診斷迴圈的工具該早一點用、不該等到推理徹底失敗。第 2 次推理失敗就切換、別等第 5 次。

延伸應用：playwright 也用來查「資料層 vs 視覺層的層錯位」 — 見 #55 Filter 與 Source 的抽象層錯位 用 browser_evaluate 量 source 真實 cardinality 與分批機制。

第 2 次同方向失敗、停下來回報「假設可能錯了、要不要換思路」。 失敗 ≥ 2 次大多是底層假設有問題、不是執行細節有問題。繼續沿同一方向加碼（換更複雜的 selector、加 !important、再寫一層 polyfill）只會放大原本的問題。

為什麼第 2 次是轉折點

商業邏輯

第 1 次失敗常是執行細節（typo、特定 syntax、瀏覽器 cache）— 修正後可能就過。

第 2 次失敗、用同樣的方法但更小心、還是失敗 — 這個訊號的重量遠大於兩次失敗的相加。它說的是「我以為的問題不在這層、根本問題在別處」。

第 3 次以上的失敗、加上「再試一次更小心」的努力、產生的副作用會超過解決的問題：

第 2 次是還能優雅切換方向的最後機會。

這次任務的實際情境

觀察

要把 search scope UI 放在「搜尋框與結果之間」。我嘗試了：

四次失敗都基於同一假設：「drawer 是 .pagefind-ui 的直接子節點」。實際 drawer 在 form 內。

判讀

第 2 次失敗時就應該停下來檢查假設、不該再往同方向加碼。

正確流程：第 1 次失敗修細節；第 2 次失敗用 playwright 量 DOM 確認假設；發現假設錯就立刻換方向、不要為前面的努力買單。

執行：失敗計數與行動

關鍵是第 2 次的「停」 — 把行動從「執行更努力」切換到「驗證假設」。

內在屬性比較：四種失敗應對

選擇規則：第 1 次修細節、第 2 次驗證、第 2 次後驗證假設決定繼續或換方向。不該有第 3 次同方向加碼。

假設驗證的具體方法

1. 用工具讀真實狀態

2. 反問「如果假設錯了會怎樣」

「如果錯了會怎樣」的答案是「跟我看到的失敗一致」 → 假設可能錯。

3. 對外回報

1我嘗試了兩次 [方向 X]、結果都 [現象 Y]。
2我的假設是 [假設 Z]、但驗證 [假設 Z] 似乎不成立。
3要不要換 [方向 W]、或是有什麼資訊我沒看到？

對外回報 = 把問題放到使用者視野、避免繼續單方面加碼。

設計取捨：失敗應對的策略

四種做法、各自機會成本不同。這個專案選 A（第 2 次失敗驗證假設）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻 抽象原則在「同方向失敗」這個面向的應用。

A：第 2 次失敗停下驗證假設（這個專案的預設）

• 機制：第 1 次修細節再試；第 2 次失敗 → 用工具驗證底層假設（DOM tree、computed style、framework 行為）；驗證錯就換方向
• 選 A 的理由：早一點切換、雙方時間都省；2 次失敗的證據量足以判斷「路徑問題」
• 適合：所有除錯情境
• 代價：第 2 次後的「停下」需要心理紀律（克服繼續加碼的衝動）

B：第 4-5 次才停（沉沒成本綁住）

• 機制：繼續加碼直到使用者制止
• 跟 A 的取捨：B 給更多嘗試空間、A 早決；B 在沉沒成本累積後更難切換
• B 是反模式：沉沒成本是認知偏誤、不是合理應對 — 「再試一次更小心」的衝動是訊號、不是解法

C：第 1 次失敗就換方向（過度反應）

• 機制：每次失敗都假設方向錯、立即換
• 跟 A 的取捨：C 太敏感、A 適度；C 在「修細節就能過」的場景過度切換
• C 才合理的情境：嘗試成本極高（每次失敗 = 半天工作）— 即使單次失敗、也值得停下重新評估

D：永不換方向

• 機制：認定方向對、無限加碼
• D 是反模式：方向錯時無法收斂、最後產生脆弱的 patchwork
• 看起來吸引人的原因：心理上不想承認方向錯、繼續加碼比放棄好受
• 實際發生的代價：失敗訊號被忽略、產生脆弱的 patchwork、修復成本指數放大

判讀徵兆

核心原則：第 2 次失敗的最佳行動是「驗證假設」、不是「再試一次」。早一點切換方向、節省的是雙方時間。

「再試一次」是當下便利的選項（不需要重新分析）、「驗證假設換方向」是對齊正確性的選項 — 這個反相關見 #67 寫作便利度跟意圖對齊反相關。

驗證工具的引入時機不該等推理徹底失敗。 靜態 CSS 推理或視覺截圖溝通連續失敗 ≥ 2 次、立刻主動提「我們啟個 server、我用 playwright 看 live DOM」 — 工具的價值是縮短診斷迴圈、不是最後手段。

為什麼要主動提工具

商業邏輯

執行者堅持靠推理 = 把使用者拖進「截圖 - 反饋 - 再試」的長循環。每輪都消耗使用者時間（看截圖、描述問題、回應）— 對使用者是負擔。

主動提工具切換 = 把循環從「視覺溝通」改成「程式量測」。執行者直接讀 live DOM、診斷一輪到位、使用者只需要在最終確認。

主動提的成本是「打一句話建議」、收益是「省 N 輪截圖溝通」。

這次任務的實際情境

觀察

drawer 在 form 內、不是 sibling 這個假設錯誤、靠推理 + 截圖溝通走了多輪：

第 4 輪用 playwright browser_evaluate 讀 ancestor chain — 一個 query、一個答案、兩分鐘解。前三輪 ≈ 30 分鐘。

判讀

第 2 輪失敗時就應該主動提：

「我嘗試了兩次都失敗、根因可能在我對 DOM 結構的假設。要不要啟個 server、我用 playwright 直接讀 live DOM 確認？這樣比繼續用截圖溝通快。」

使用者啟 server、我跑 query、一輪解。

執行：主動提工具的 protocol

驗證工具該在這些時機主動提：

工具引入的成本與價值

內在屬性比較

「起步成本」是一次性、「每輪成本」是重複的。第 2 輪以後、playwright 的 ROI 已經正向。

主動提的具體話術

較差的提法

「要不要試試 playwright」

模糊、使用者不一定知道為什麼要試、可能答「先這樣吧」。

較好的提法

「我嘗試了兩次都失敗、根因可能不在 CSS、在我對 DOM 結構的假設。 要不要啟個 server（python3 -m http.server 8000 在 public/）、 我用 playwright browser_evaluate 直接讀 ancestor chain 確認？ 這樣比繼續用截圖快很多。」

說明：

• 為什麼提：兩次失敗、推理迴圈成本超過工具迴圈
• 要使用者做什麼：啟 server、給一行指令
• 我會做什麼：用 playwright evaluate 讀
• 預期收益：縮短迴圈

使用者明確知道 trade-off、決定簡單。

工具迴圈的標準流程

11. 使用者啟 server（python3 -m http.server / hugo server）
22. 執行者 navigate 到目標頁面
33. 執行者寫 evaluate fn 讀真實狀態
44. 執行者根據結果定位根因
55. 執行者改 CSS / JS
66. 執行者再 evaluate 驗證修復
77. 使用者目視最後確認（可選）

整個流程多數步驟在執行者這邊、使用者只在頭尾參與 — 對使用者負擔輕。

設計取捨：驗證工具引入的時機

四種做法、各自機會成本不同。這個專案選 A（推理 ≥ 2 次失敗主動提）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻 抽象原則在「驗證工具切換」這個面向的應用。

A：推理 ≥ 2 次失敗主動提工具切換（這個專案的預設）

• 機制：靜態推理連續失敗 2 次、立刻提「啟個 server、我用 playwright 看 live DOM」+ 附啟用步驟與預期收益
• 選 A 的理由：對使用者透明（看到 trade-off）、縮短診斷迴圈
• 適合：CSS / DOM 行為跟預期不符的除錯
• 代價：執行者要主動辨識「推理迴圈成本」與「工具迴圈成本」的交叉點

B：等使用者要求才用工具

• 機制：執行者繼續推理、使用者覺得太慢時提
• 跟 A 的取捨：B 對使用者更被動、A 主動；B 在使用者不知道有 playwright 選項時、會一直繼續
• B 才合理的情境：使用者明確表達「想用推理練習」、把工具切換當成放棄

C：全程靜態推理、不用工具

• 機制：堅持推理到底
• C 是反模式：推理迴圈成本累積、最後可能需要 4-5 輪才解決
• 看起來吸引人的原因：覺得用工具是「能力不足」、想撐到自己想出來
• 實際發生的代價：時間成本指數放大（每輪推理基於前輪錯假設）、最後還是要切工具

D：一開始就用 playwright、不嘗試推理

• 機制：跳過推理、直接用工具量
• 跟 A 的取捨：D 跳過推理階段省去 2 次嘗試、但前期 setup 成本投入比例較高（簡單問題不值得）
• D 比 A 好的情境：問題明確需要 live DOM 才能診斷（例如「framework 渲染後的結構」）— 推理本來就無法解

判讀徵兆

核心原則：工具引入時機是「推理迴圈成本超過工具迴圈成本」的點 — 大多在第 2 次推理失敗時。早一點提、雙方都省時間。

跟 #68 驗收的時間軸 的關係：本卡是「debug 工具切換時機」、#68 是「驗收動作分散在四個時點」 — 兩者共用「動作該分配到哪個時點才有 ROI」這個結構。本卡的「第 2 次推理失敗就切工具」≈ #68 的「ship 前要設計 E2E case」 — 都是「把高 ROI 的動作放在對的時點、不要延後」。

本卡抽自 blog CI 的 Playwright install step 反覆 timeout 事件。Playwright 1.59 在 Node.js 24.16.0 上 extract-zip silent hang，表面看是「下載太慢 / timeout 太緊」，實際是 upstream regression。limitation：evidence 來自單一 CI 事件，但 silent hang 模式在 Docker build、cron job、database migration 等場景都出現過。

完整 case study 見 CI step silent hang。

核心原則

非互動 process 的 log 輸出中，最後一行成功訊息（happy log）到被外部 cancel 之間的大段時間無輸出（時間真空），是 silent hang 的判讀訊號。

技術人員習慣在 log 裡搜尋 error keyword 找失敗原因。但 silent hang 沒有 error keyword — process 沒 crash，只是不再做任何事。辨識 silent hang 需要轉換訊號類型：從「訊息內容」轉到「訊息時序」。

情境

CI step 跑了 15 分鐘被 timeout cancel。最後一行 log 是「chromium 下載 100% 完成」— 這是 happy log，直覺判斷是「下載慢、timeout 太緊」。加了 cache + bump timeout 到 25 分鐘，仍然頂到上限被 cancel。

回頭看 detailed log 的 timestamp：

12026-05-27T09:59:44.110Z  | 100% of 170.4 MiB
22026-05-27T10:24:15.201Z  ##[error]The operation was canceled.

24 分 31 秒的時間真空。下載 2 秒完成，之後 process 完全沒有任何 log 輸出直到被 cancel。

理想做法

CI step timeout 時，先抓四個 timestamp 判斷是否 silent hang，再決定修法：

1. Step 開始的 timestamp
2. Step 結束（cancel / fail）的 timestamp
3. 最後一行有意義輸出的 timestamp
4. 計算 #3 到 #2 之間的時間真空

真空相對該 step 正常輸出節奏明顯異常（CI extract 類場景通常秒級輸出、真空超過數分鐘即可疑）且最後一行是 happy log → silent hang 嫌疑高 → 用症狀詞查 upstream issue tracker，不是加 timeout。

三類 timeout 模式的修法不同：

沒這樣做的麻煩

• 反覆加 timeout：每次都「差一點」（頂到上限），每次都以為「timeout 不夠」，實際上 process 永遠不會自己結束
• Cache 是假瓶頸：直覺判斷「下載慢 → 加 cache」，但瓶頸在 extract hang（下載只花 2 秒）
• False positive 越雕越精緻：cache key 調整、timeout 微調、retry 策略 — 每一步單看合理，合起來是把錯誤假設越做越細

判讀徵兆

兩個訊號同時出現時，應該先排除 silent hang 再提其他解法：

1. 非互動 process 跑的時間接近或等於 timeout 上限（「頂到上限」模式）
2. 最後一行 log 是成功訊息（下載完成 / build succeeded / tests passed）

另一個後設訊號：同方向修法（加 timeout / 加 cache / 加 retry）2 次都仍頂到上限 — 這時候問題幾乎確定不是「時間不夠」。對應 #20 同方向反覆失敗的轉折點。

跟其他抽象層原則的關係

• → #20 同方向反覆失敗的轉折點：本案例是 #20 在 CI timeout 場景的 evidence — 第二次 bump timeout 仍 fail 時就該停下來換思路
• → #199 一篇文章只承擔一種功能：本卡的來源文章原本放在 posts/，實際是 debugging case study，搬到 work-log/ 後從中抽出本卡，是 #199 拆分動作的實例

核心議題：CI step 看起來「跑了很久才 timeout」時，要分辨「真的時間不夠」跟「silent hang 占滿時間」 — 兩者修法完全不同。Silent hang 的訊號是「最後一行 happy log 到 cancel 之間有大段時間真空」、不是「最後一行錯誤訊息」。第一次歸因錯誤後、第二次 fail 不該再加 timeout、該停下來重看 detailed log。 案例骨幹：本 blog 的 Playwright CI 一直 timeout、初診「cache 缺失 + timeout 太緊」加了 cache + bump timeout、仍 timeout。重看 detailed log 發現 chromium 下載 2 秒完成、之後 24 分 31 秒完全沒任何 log 才被 cancel — Playwright 1.59 在 Node.js 24.16.0 的 extract-zip regression（microsoft/playwright#41000、上游 nodejs/node#63487）。升 Playwright 1.60.0 後該 step 從 25 分鐘卡死降到 22 秒。

1. Silent hang 是 happy log 的 anti-signal

CI step timeout 時、第一個本能是看「step 跑了多久」。15 分鐘 timeout 然後被砍、直覺判斷是「時間不夠、bump timeout」。這個直覺對應的失敗模式是「step 真的需要 16 分鐘才能跑完」。

但有另一種失敗模式長得很像、修法完全不同：silent hang — step 在某個點之後就不再輸出任何 log、process 仍在執行（沒有 crash）、直到外部 timeout 才被砍。表面看跟「時間不夠」一樣（step 跑很久才被 cancel）、但根因是 process 本身卡死、給多少時間都跑不完。

辨識 silent hang 的關鍵訊號是「最後一行 happy log 到 cancel 訊息之間有大段時間真空」。「Happy log」指的是看起來成功的訊息（例：下載 100% 完成、build succeeded、X tests passed）— 這類訊息特別會誤導判斷、因為它讓人以為任務在進展。Silent hang 開始之前的最後一行通常正是這種 happy log、是正常結束訊號的反面。

三類 timeout 模式的對照

第三種最容易誤判、因為「log 之間沒輸出」沒被當成訊號 — 但訊息真空本身就是訊號。寫 debug log 的人會記得補 error 訊息、但 silent hang 通常發生在工具內部的某個沒輸出 log 的等待點、所以沒有 error 訊息可看。

2. 為什麼「cache 缺失 + bump timeout」的初診是 false positive

第一次看 CI fail log 時、有三件容易抓到的事：

1. workflow YAML 裡的 timeout-minutes: 15
2. step 跑了 15m 6s（幾乎等於 timeout 上限）
3. step 名稱是 Install Playwright browsers（要下載 170 MiB）

直覺合成的結論：「cache 缺失 + timeout 太緊」。這結論看起來「應該對」 — 因為這兩個都是「Install Playwright browsers」眾所周知的優化點。修法：加 actions/cache + bump timeout 25 min。

修完仍 timeout、但這次跑 25m 6s（一樣頂到上限）。

這時的訊號應該是「同樣的 step 在 1.67 倍的 timeout 下仍頂到上限」 — 如果是時間不夠、bump 之後該往中間靠（譬如完成在 18-20 min）；如果一直頂到上限、意思是 step 不會自己結束、是 hang。

但初診時很容易略過這個訊號、轉而繼續想「是不是 cache step 設定有問題？」。這個歸因方向是錯的、因為前置假設「cache 是瓶頸」本身就沒驗證過。

一輪 false positive 的 anatomy

每一步單看都合理、合起來就是把 false positive 越雕越精緻。這個 anatomy 對任何「初診沒驗證就改」的場景都適用、不限 CI。

3. WRAP 的 R 在第二次 fail 時是 stop 訊號

WRAP 決策框架的 R（Reality Test）原則是「需要什麼事證才能證明這個方法可行？」。它不只是決策前的檢查、更是連續失敗後的 stop 訊號。

第二次 fail 時、繼續同方向加 timeout 是自動駕駛模式。WRAP 在這個位置該提醒的事：

• 「兩次同類修法都沒解、是不是前置假設錯了？」
• 「我有沒有資料去判斷真正卡哪？」（資料充足度閘門）
• 「同類問題的 base rate 是什麼？」（基本率思考）

Stop 訊號的觸發條件是「同方向修法連續 fail 2 次」、不是「fail 3 次」。第二次就該回到資料層；第三次已經是浪費 cycle 而且強化錯誤假設。

實際上第二次 fail 後做的對的事是停下來、grep detailed log 的 timestamp 序列、發現「下載完成」跟「cancel」之間有 24 分鐘空白 — 這時才確認是 silent hang。如果第二次沒做這個轉折、第三次大概率是「換更大的 timeout」或「換不同的 cache key」、仍 fail。

4. Detailed log 的關鍵讀法：找「沒輸出的時間段」

CI 平台的 step log 通常很長、人眼掃容易跳過。看 silent hang 嫌疑時、讀法不是順序讀、是抓四個 timestamp：

1. Step 開始的 timestamp（log header 通常有）
2. Step 結束（cancel / fail）的 timestamp
3. 最後一行有意義輸出的 timestamp
4. 計算 #3 到 #2 之間的時間真空

真空夠大（> 1 分鐘）+ #3 是 happy log = silent hang 嫌疑高。

GitHub Actions 用 gh CLI 的具體做法：

1# 取某個 step 的所有 log（filter step 名稱）
2gh run view <run-id> --log --job <job-id> | rg "Install Playwright browsers"
3
4# 抓最後幾行看真空尾巴
5gh run view <run-id> --log --job <job-id> | rg "Install Playwright browsers" | tail -3

本案例的最後 3 行（簡化過）：

12026-05-27T09:59:44.110Z  | 100% of 170.4 MiB
22026-05-27T10:24:15.201Z  ##[error]The operation was canceled.

24 分 31 秒真空、最後一行 happy log 是「下載 100% 完成」 — silent hang 確認。

這個讀法的核心是「時間真空優先於訊息內容」。技術人員習慣讀訊息內容找 error keyword、但 silent hang 沒有 error keyword 可找、只有時間真空。轉個訊號類型才看得到。

5. Upstream issue 搜尋的優先序

Silent hang 確認後、下一步通常不是繼續 reason 根因、是去查 upstream issue tracker。Silent hang 多半是工具 / 依賴的 bug、而非自己 config 錯 — 因為 config 錯通常有 error message、不會 silent。

查詢策略：

1gh api 'search/issues?q=repo:<upstream>/<repo>+<symptom keywords>+is:issue&per_page=10&sort=updated'

關鍵是 keyword 選擇用「症狀詞」而不是「猜測詞」。症狀詞描述讀者實際觀察到的現象（hangs after download、stuck during extract），猜測詞描述讀者推測的根因（slow、timeout、network issue）。猜測詞會找到大量無關 issue；症狀詞通常直接命中。

本案例查詢 playwright install hangs chromium 第二筆結果就是 issue #41000、標題完全匹配「playwright install chromium hangs after download completes on Node.js 24.16.0 (extract-zip)」。Issue 詳情指向上游 nodejs/node#63487、給出兩個 workaround（升 Playwright 1.60.0 或 pin Node 24.15.0）。從查詢到確認根因、全程不到 5 分鐘。

為什麼 issue tracker 該優先於 self-reasoning

技術人員的 instinct 是「自己想出根因」。但 CI silent hang 這類問題、根因通常在工具版本、runtime 版本、OS、container image 的微妙交互、不在自己的 codebase。Reasoning 找不到的東西、社群 issue tracker 經常已經有人回報過。

「先 reason 再查」跟「先查再 reason」的取捨：

Silent hang 預設屬於第二類、應該優先查 issue tracker。

6. 整合：訊號 → 行動 mapping

把本案例的經驗整理成可重用的訊號表：

這張表的順序很重要：每一步的「該做的事」是下一步的「前置條件」。略過任一步、後面的判斷會建立在錯誤假設上。

適用範圍

「Silent log 是 happy log 的 anti-signal」這個原則對所有非互動 process（CI、cron job、background worker、container init）都適用：

• Docker build 卡住（特別是 RUN apt-get / npm install / pip install）— 同類 silent hang 模式
• CI cache restore 卡住 — 大量小檔案的 cache 操作可能 silent hang
• Database migration 卡住 — schema 變更 + 長 transaction 可能 silent hang
• 任何 process 跑時間接近 timeout 上限被 cancel — 先檢查是否 silent hang 才提解法

「WRAP R 在第二次 fail 時是 stop 訊號」這條原則不限 CI、適用所有「同方向修法重複 fail」的場景：debug、設定調校、效能優化。

參考資料

• microsoft/playwright issue #41000 — 本案例的 upstream issue（Playwright 1.57-1.59 在 Node 24.16.0 extract-zip hang）
• nodejs/node issue #63487 — Node 24.16 extract-zip / yauzl regression 上游
• 同 blog 文章：WRAP 決策框架的 R 階段操作 — Reality Test 詳細用法

這類狀態可以稱為 Android emulator 半活（zombie）：emulator host process 還在、ADB 清單仍殘留 device，但 emulator 內的 adbd 或 Android system 已停止回應。Flutter 在掃描階段會對每個 Android device 查 properties，掃描到這個半活 device 就卡在 timeout。

事故場景

事故場景的核心是「Flutter 指令看似卡住，其實卡在下游 device property 查詢」。連續跑 flutter devices 時，輸出長這樣：

1$ flutter devices
2Found 4 connected devices:
3Error -2 retrieving device properties for sdk gphone64 arm64:
4[卡住]
5
6$ flutter devices
7Found 3 connected devices:
8[繼續卡]

這段輸出有兩個值得注意的點：

1. Error -2 retrieving device properties for sdk gphone64 arm64: 訊息出現後仍繼續等待，代表 Flutter 沒有在第一個 device 失敗時 fail-fast
2. 第一次 Found 4、第二次 Found 3，代表 device 數在兩次掃描之間自己少了 1

sdk gphone64 arm64 是 Android Studio AVD 預設模板（Google Phone 64-bit ARM）建出來的 emulator 顯示名稱、macOS 上跑 Android system image 都會看到這個。

為什麼計數變化是關鍵徵兆

device 數從 4 變 3，代表 ADB 對某個 emulator 的狀態判斷在兩次查詢之間變了。ADB server 內部追蹤每個 device 的狀態（device / offline / unauthorized / no permissions）；半活 emulator 在第一次掃描時仍被列在 Found 4，第二次掃描時可能已被標成 offline 或從候選清單移除，所以掉到 Found 3。

判讀訊號是「同一條 list 指令連跑兩次，device 數或 device 狀態自己變」。正常穩定狀態下，清單應該保持一致；清單漂移代表 ADB server 對某個 entry 的看法不穩定，下一步要先找出那個 entry，再決定是否重啟 ADB 或 emulator。

為什麼 flutter devices 會卡住

flutter devices 的責任是把每個候選 device 補成 Flutter 可用的 target，而不只是印出 adb devices 的結果。Flutter 對每個 ADB 看得到的 Android device 還要做幾件事：

1. 跑 adb shell getprop ro.product.cpu.abi 拉 ABI
2. 跑 adb shell getprop ro.build.version.sdk 拉 SDK level
3. 跑 adb shell getprop ro.product.model 拉裝置型號
4. 視情況跑 adb shell 其他指令確認 Flutter 支援度

這些是同步、序列化、有 timeout 的呼叫；timeout 通常設得相對寬鬆，讓慢一點的真機也能跑通。當其中一個 device 是 zombie 狀態：

• adb shell getprop ... 送出後，ADB 把指令轉發給 emulator 內的 adbd
• adbd 收到了但 Android system 沒回應，或 emulator process 整個卡住沒在處理 ADB request
• Flutter 端等 timeout、再 retry、再等更長 timeout，看起來就是「整個指令卡住」

Error -2 retrieving device properties 是其中一次嘗試 timeout 拿到的訊息（-2 是 Dart ProcessException 對應 adb exit code 的內部映射）。Flutter 仍會繼續掃描其他 device，所以使用者看到的是「印出錯誤訊息 + 繼續卡」。

為什麼是半活狀態

Android emulator 在 macOS 上的結構大致是：

1qemu-system-aarch64 (host process)
2  ├─ Android kernel
3  ├─ Android system services
4  └─ adbd (在 emulator 內部，跟 host ADB server 對接)

半活狀態指的是「host process 還在，但 device 內部服務已無法完成 ADB request」。完全正常時 emulator 跑得動、ADB 也通；完全退出時 emulator process 已結束、ADB 清單看不到它。半活介於兩者之間：

• qemu host process 還在（活著）
• emulator 內的某個環節卡住（Android system 沒在 schedule、或 adbd 卡在某個 mutex）
• ADB server 還記得有這個 device，尚未穩定 evict
• 任何 adb shell 指令都打不通

常見成因：

• Quick Boot snapshot 還原失敗或部分還原——AVD 預設關機是 quick boot（存 snapshot），下次開機從 snapshot 還原；snapshot 跟當前 host kernel / hypervisor 狀態不相容時會半開機
• macOS 從 sleep 喚醒後 hypervisor framework 重置——emulator 是用 Hypervisor.framework，喚醒後虛擬 CPU 可能停在奇怪 state
• host 端記憶體壓力導致 emulator 被 swap 嚴重——表面看起來像卡，其實是在等 page fault

這一層的操作目標是恢復工具鏈，而不是追到每個 emulator 內部 race condition。若症狀符合清單漂移與 property 查詢 timeout，先按恢復順序處理；只有反覆發生時，再追 AVD snapshot、system image 或 host 資源壓力。

恢復順序（從輕到重）

恢復順序的核心是先重置最小邊界，再逐層擴大。每一步都要重新跑一次 flutter devices 或 adb devices，確認是否已經恢復，避免直接砍掉 emulator 或清資料。

1# 1. 看 ADB 對每個 device 的狀態
2adb devices
3# 看到 offline / no device / unauthorized 等異常狀態 → 先鎖定該 device

如果有 device 顯示 offline，或正常列出但實際打不通，先重啟 ADB server：

1# 2. 重啟 ADB server（只重置 host 端 ADB session）
2adb kill-server && adb start-server
3adb devices
4# 多數狀況下，ADB 重啟後對該 device 的查詢會 fail-fast，flutter devices 會恢復

如果 ADB 重啟後仍打不通該 emulator，再處理 emulator process：

1# 3. 對特定 emulator 發 emu kill（讓它優雅關閉）
2adb -s emulator-5554 emu kill   # 把 5554 換成實際 port
3
4# 4. 還在的話，終止 qemu process
5pkill -f qemu-system-aarch64

長期修復路由是清掉不穩定的 snapshot。開 Android Studio → AVD Manager → 該 emulator 旁邊的小箭頭 → Cold Boot Now（避免 Quick Boot）。如果冷啟動後仍反覆壞，選 Wipe Data 把 snapshot 與 emulator 內資料整個清掉。

通用診斷思維

工具鏈卡住的診斷核心是先區分「上游 CLI 壞掉」還是「下游 target 沒回應」。flutter / adb 指令卡住時，先用清單穩定性與 device 識別碼定位下游狀態，再決定重啟邊界。

1. 觀察「同一指令連跑兩次結果是否一致」：不一致（device 數變、訊息變）等於某層狀態不穩定
2. 訊息裡有 device 識別碼就釘住它：sdk gphone64 arm64、emulator-5554、序號等都是 ADB 層的識別，可直接拿來 adb -s <id> ... 局部診斷
3. 從外往內排除：ADB server → 個別 device → emulator process → emulator 內 system，逐層重啟
4. 重啟邊界越大、副作用越大：adb kill-server 只影響 ADB session（其他 device 連線會斷一下），pkill qemu 直接砍 emulator，Wipe Data 連 emulator 內的資料都清。能用輕量手段解決就停在那層

操作判準

1. 「device 數兩次掃描之間自己變」是 zombie emulator 的關鍵徵兆：計數變化代表 ADB 內部狀態不穩定
2. Error -2 retrieving device properties 是 property 查詢失敗訊號：Flutter 仍可能繼續處理其他 device，結果是「印出錯誤訊息但繼續卡」
3. adb kill-server && adb start-server 是輕量首選：它只重置 ADB session，不動 emulator 本身，多數狀況下可讓壞 device fail-fast
4. 半活狀態跟 application code 層級不同：先把工具鏈狀態釐清，再回到剛改的程式碼

適用範圍

這個診斷思維不限於 Android emulator：

• iOS Simulator 卡住時 xcrun simctl list 印不出來——同樣的「指令卡 + 訊息看似 fatal 但 process 仍存在」結構
• flutter devices 對任何 device（含 iOS、Web、desktop）的查詢都會走類似的「列出 → 逐個 query property」流程、任一層卡都會表現為類似症狀
• 廣義地說，任何「server 維護一份 client 清單 + 對每個 client 做同步呼叫」的架構（k8s kubectl get pods 對 zombie node、docker docker ps 對掛掉的 container runtime 等）都有同款 failure mode

辨認規則一致：list 指令連跑兩次結果不一致 → 維護清單的 server 對某個 entry 的看法不穩定 → 找出那個 entry 局部處理。這條規則的邊界是：如果清單穩定但操作失敗，問題更可能在該 target 的權限、版本或 runtime 狀態，需要改走對應工具的細部診斷。

事故類型：cross-file 狀態污染、dart test runner 同 process 共用 GetX 症狀：flutter test 約 50% 機率隨機失敗、每次失敗的 test 不固定；單獨跑該 test file 100% 通過 根因：dart test runner 在同 process 內跑多個 test file 共用 GetX 容器；前面 file 的 setUp 留下殘留（測試 mode 旗標、未 dispose 的 controller、stream subscription）污染後面 file 的測試環境

事故場景

表面症狀

跑 flutter test 全 suite，Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail。看到的失敗訊息類似：

100:27 +125: PrintCenter 廚房印表機管理 kitchenPrinter 向後兼容取第一台 - did not complete [E]
200:27 +125: PrintCenter 廚房印表機管理 重複呼叫 initFakeKitchenPrinters 會清除舊的 - did not complete [E]
300:27 +125: Some tests failed.

訊息直接點名 PrintCenter 廚房印表機管理 group 的兩個 test「did not complete」。直覺反應：那兩個 test 有問題、去看那個 file。

第一次診斷與失敗的修法

打開 online_order_print_handler_test.dart，看到 PrintCenter 廚房印表機管理 group 的 setUp 沒做 Get.reset()、純粹依賴 outer setUp 的 Get.reset()。判斷可能是 outer setUp 的 OnlineOrderPrintHandler.onInit 在這個 group 留下副作用（stream subscription 之類），於是給這個 group 加自己的 reset：

 1group('PrintCenter 廚房印表機管理', () {
 2  late PrintCenter printCenter;
 3
 4  setUp(() {
 5    Get.reset();  // ← 加這行隔離 outer setUp 的副作用
 6    printCenter = PrintCenter(FakePrinterAdapter('main'));
 7    Get.put(printCenter);
 8  });
 9
10  tearDown(() {
11    Get.reset();  // ← 加這行確保不殘留
12  });
13});

跑 5 次：Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail——flakiness 比例沒改變。

修錯了。

重新診斷：看 +N -1 計數的真正位置

把 fail 輸出存進檔案、仔細看 progress line 的 +N -1 部分：

100:08 +125 -1: ... auto_service_config_test.dart: ...
200:08 +126 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity searchedOrder 變更：badge 立即更新（list 與 selected 都沒命中時）
300:08 +127 -1: ... auto_service_config_test.dart: ...

-1 在第 126 個 test 才第一次出現——失敗的不是 print handler，是中間夾的 widget test。再看另一次 fail：

100:09 +124 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity orderList[i] 替換：badge 從「已完成」立即變「退貨」

不同 run 失敗的 test 不一樣，但都是 settle_page_order_object_test.dart 的不同 case。print handler 的 did not complete 是被牽連、不是源頭。

確認 root cause：單獨跑全綠

把 widget test 單獨重複跑 8 次：

1for i in 1 2 3 4 5 6 7 8; do
2  flutter test test/widgets/settle_page_order_object_test.dart 2>&1 | tail -1
3done

8/8 全綠。單獨跑沒問題、混進全 suite 跑就 flaky——這是 cross-file pollution 的固定特徵。

為什麼 did not complete 訊息會誤導

dart test runner 的失敗訊息設計上有個盲點：

• +N 是累計通過數
• -N 是累計失敗數
• did not complete 是某個 test 還沒跑完整體就終止了（process 退出 / 超時 / 前面有未捕捉錯誤導致 runner 提前結束）

當前面有 test 失敗、後面的 test 沒機會跑、這些後面的 test 會印 did not complete——但它們本身沒問題。看到 did not complete 直覺會想「這個 test 卡住了」、但真實意思更接近「這個 test 還沒跑、上游已掛」。

正確的診斷流程：

1. 找 -N 第一次出現的位置（-1 表示第一個失敗）
2. 對照那一行的 test 名稱、那才是真正失敗的源頭
3. did not complete 出現的 test 通常只是受牽連

我第一次掉的坑：直接讀 did not complete 的 test 名、跳過了「往前找 -1 第一次出現」這步。

為什麼 cross-file 會污染：dart test runner 與 GetX 的不對齊

dart test runner 的執行模型

flutter test（背後是 dart test）跑全 suite 時不一定 1 file = 1 isolate。預設行為：

• 多個 test file 可能共用同一個 isolate / Dart VM
• 共用 isolate 等於共用所有 process-scoped state（static field、singleton、未 GC 的全域物件）

並發策略受 --concurrency 與 platform 影響、行為不固定，但「共用 process」是日常常見現象。

GetX 的 state 是 process-scoped

GetX 的 Get.put / Get.find 把 instance 放進一個 process-global 容器。Get.reset() 清空容器、但有些東西不會被 reset：

• Get.testMode 是 static field、reset() 不動它
• 如果 instance 在 onInit 內 subscribe 了 stream（例如 BroadcastReceiveService.messages.listen）、Get.reset() 移除 instance reference 但 subscription 不會自動 cancel
• StreamController / Timer / Future.delayed 在 GetX 容器外仍然活著

實際發生的污染鏈

跑全 suite 時，假設執行順序是：

11. test/services/online_order/...      ← 最前面
22. test/widgets/settle_page_order_...   ← 中間
33. test/services/auth_service_config... ← 後面

第 1 個 file 的 setUp 若有 Get.put(SomeService())，service 在 onInit 內訂閱了 stream，就算 tearDown 跑了 Get.reset()、那條 stream subscription 仍 active。第 2 個 file 開始跑時：

• 它的 setUp 也呼叫 Get.put(...)、放進去的物件可能是 完全不同類型 ——但 GetX 容器內可能還有上一輪殘留的物件
• 第 2 個 file 的 widget test 進入 widget tree、Obx 訂閱、各種 reactive 路徑啟動
• 上一輪殘留的 stream / timer 此時 fire、進到不該觸及的 state

整個 race 在「殘留事件何時 fire vs widget test 何時 expect」之間，所以 flakiness 是 ~50% 而不是 100%。

解法：setUp 開頭主動 reset

對任何用 GetX 的 test，setUp 最開頭就該 reset、不要依賴上一個 file 的 tearDown 跑乾淨：

 1setUp(() {
 2  // 同 process 內跑全 suite 時其他 test file 可能在 GetX 容器留殘留
 3  // （Get.testMode、未 dispose 的 controller、未 cancel 的 stream subscription），
 4  // setUp 開頭主動 reset 切斷 cross-file 污染
 5  Get.reset();
 6  Get.testMode = true;
 7  // ... 之後再 Get.put 自己需要的東西
 8});
 9
10tearDown(() {
11  Get.reset();
12});

把這個 pattern 加到所有 widget test 與 controller test 的 setUp 之後，全 suite 連跑 5 次：

1Run 1: All tests passed!
2Run 2: All tests passed!
3Run 3: All tests passed!
4Run 4: All tests passed!
5Run 5: All tests passed!

5/5 全綠，flakiness 消失。

為什麼 tearDown 的 reset 不夠

理論上 tearDown 已經 Get.reset() 了，下個 test 的 setUp 看到的應該是乾淨容器——但這個推理在「同 file 內」成立、跨 file 不成立：

• 跨 file 之間 dart test runner 在 file 邊界做的事是不確定的（可能整個 isolate 重啟、也可能只是切換 group）
• 即使前一個 file 的 tearDown 跑完，跨 file 的某個 microtask / timer callback 仍可能在後一個 file 的 setUp 之前 fire
• 用 setUp 開頭的 reset 等於再保險一次、把這個邊界內的不確定性吃掉

除錯思維：flaky test 的固定診斷流程

 11. 看是不是真的 flaky
 2   - 連跑 5~10 次、計算成功率
 3   - 隨機失敗（不是 100% 也不是 0%）→ 進入 flaky 診斷
 4
 52. 找真正的失敗源頭
 6   - 看 progress line `+N -M`、找 -1 第一次出現位置
 7   - 不要直接讀 "did not complete"、那是受牽連訊息
 8
 93. 判斷是 in-file 還是 cross-file 污染
10   - 失敗的 test 單獨跑：
11     - 100% 通過 → cross-file 污染（其他 file 的殘留進來）
12     - 也會隨機 fail → in-file 污染（同 file 的 test 之間互相污染）
13
144. 補對應的隔離
15   - cross-file → setUp 開頭 Get.reset()
16   - in-file → 看是 setUp/tearDown 沒清乾淨還是 test 之間共享 mutable state

教訓

1. did not complete 不是失敗源、是被牽連訊息——往前找 -1 第一次出現的位置才是真正失敗的 test。
2. 單獨跑通過 + 全 suite fail = cross-file pollution——這是 flaky test 最常見的固定模式之一、有專屬的解法（setUp reset）、不要當成「資料時序的隨機性」隨便重跑。
3. tearDown 清不夠、setUp 也要清——任何用 GetX 的 test 應該在 setUp 開頭主動 Get.reset()、不要依賴上一個 file 的 tearDown。
4. 第一次診斷錯誤是常態、要回到證據——順著 fail 訊息修是直覺反應、但訊息可能誤導；停下來看計數欄位、單獨跑驗證、才是穩定的診斷方式。

適用範圍

這個 pattern 不限於 GetX、適用於任何在 process-scoped global state 註冊東西的框架：

• Provider 的 MultiProvider / 全域 instance
• Riverpod 的 ProviderContainer（雖然 Riverpod 設計上更鼓勵 per-test container）
• 自寫的 service locator / singleton
• 任何 static field 累積的狀態

只要框架的 state 跨 test boundary 而 dart test runner 又在同 process 跑多 file，cross-file pollution 都可能發生。setUp 開頭主動 reset 是通用防身術。

參考資料

• Dart package:test runner concurrency docs
• GetX Get.reset() source
• Flutter flutter_test binding lifecycle

事故類型：潛伏型設計缺陷、第二個訂閱者出現時才暴露 症狀：Bad state: Stream has already been listened to. 根因：在「StreamController() vs StreamController.broadcast()」這個零成本差異的選擇下、選了限制更高的單訂閱版本——當下只有一個訂閱者、限制沒曝光；新增第二個訂閱者就觸發底層型別契約。設計缺陷的本質是「在零成本差異下不必要地縮小了未來空間」、不是「沒預測到後來需求」。

事故場景

業務背景：POS 的多視角狀態同步

POS 系統本質上是「單一交易狀態 + 多個視角同步呈現」。一筆購物車的變化通常要立刻反映到：

• 收銀員操作的主螢幕
• 給顧客看的副螢幕（純顯示，看商品、總價、找零）
• 廚房或後場的出餐顯示
• 列印機（結帳當下觸發）
• 雲端同步、報表、會員紀錄

這些視角各自關心交易狀態的不同切面，但都需要在狀態變動的當下被通知。在系統設計上，這是個典型的「一個資料源、多個訂閱者」場景，本質就是事件廣播。

原始設計：一個事件來源，一個訂閱者

實作初期，「需要訂閱購物車變動」的角色只有一個——副螢幕。副螢幕在 app 啟動時就訂閱、整個 app 生命週期都在聽，純粹做主畫面的鏡像顯示。

於是負責提供「狀態變更通知」的 service 用了 dart:async 預設的 StreamController 對外發事件。事件 payload 設計成兩段資訊：

1. 當前完整商品列表（給副螢幕這類「鏡像當前狀態」的訂閱者用）
2. 這次變動的具體品項（移除或清空時為 null，預留給「需要知道改了哪一筆」的訂閱者）

第二段資訊當下沒人用，但 service 設計者保留了它，理由是「未來如果有訂閱者需要知道每次具體變動是什麼，不必再改介面」——一個合理的擴充性設計。

幾個月過去，這條 stream 只有副螢幕一個訂閱者，運作正常。

新需求：操作體驗優化

新需求出現：收銀員在尖峰時段連續掃商品，畫面更新太快會分不清剛剛動到的是哪一筆。如果是改價、改數量這類修改更明顯——數字突然變了，但視線焦點不在那一行就會錯過。

業務上希望：每次操作後，被改動的那一行在 UI 上有個視覺標記（高亮、邊框或角標都可），讓收銀員一眼確認剛剛動的是對的品項。標記停在最後一次操作的那行，直到下一次操作才轉移。

這個需求對應 service 已經備妥但尚未被消費的資訊——service 對外的事件 payload 從原始設計就分兩段：一段是「當前完整的商品列表」、另一段是「這次變動的具體品項」。第二段是當初為「需要追蹤單筆變動的訂閱者」預留的擴充欄位、過去幾個月一直沒被消費。新需求只要新增一個訂閱者讀這段資訊、再把它對應到 UI 上的視覺標記即可——介面不需要變動、payload 結構不需要調整、實作範圍只限於新增訂閱端。

第二個訂閱者觸發底層限制

第二個訂閱者寫好、進入收銀頁面當下就 throw：

1The following StateError was thrown building Obx(...):
2Bad state: Stream has already been listened to.

第一反應通常是「我哪裡寫錯了 / 是不是哪邊忘了 cancel」。檢查程式碼會發現新訂閱者寫得沒問題，副螢幕的訂閱也沒問題——問題在底層 stream 的型別契約：整個生命週期內只允許被 listen 一次。

這是 StreamController() 預設建構子的契約：建立的是 single-subscription stream、生命週期內最多承載一個 listener。副螢幕第一個訂閱後佔據了唯一的 listener 位置；新加第二個訂閱者直接違反契約、執行期 throw。

更深一層的觀察是設計層面的不一致：業務需求一直具備廣播語義（多個視角同步呈現）、技術選型卻是「單一管線」的工具。需求初期只有一個訂閱者讓限制沒有可見的影響、但限制一直存在於型別契約裡。第二個訂閱者只是觸發條件、不是根因。

兩種 StreamController 的核心差異

三組行為差異的程式碼驗證

1. 重複監聽

 1final c = StreamController<int>();
 2c.stream.listen(print);
 3c.stream.listen(print);
 4// 錯誤：Bad state: Stream has already been listened to.
 5
 6final b = StreamController<int>.broadcast();
 7b.stream.listen((v) => print('A: $v'));
 8b.stream.listen((v) => print('B: $v'));
 9b.add(1);
10// A: 1
11// B: 1

值得注意的不只是「不能同時兩個 listener」——單訂閱 stream 的限制是整個 lifecycle 只能 listen 一次。即使第一個 listener 已經 cancel()、再呼叫 .listen() 仍會違反契約 throw。要重新訂閱必須重建 StreamController。

對 POS 場景的意義：副螢幕服務在 app 啟動時就建立訂閱、且不會 cancel——換句話說、stream 在啟動時就把唯一的 listener 配額分配給副螢幕、之後沒有可釋出的空間。

2. 監聽前的事件處理

 1final single = StreamController<int>();
 2single.add(1);
 3single.add(2);
 4// 此時還沒有 listener
 5single.stream.listen(print);
 6single.add(3);
 7// 輸出：1, 2, 3 ← 之前的事件被 buffer，listener 接上後補送
 8
 9final broadcast = StreamController<int>.broadcast();
10broadcast.add(1);
11broadcast.add(2);
12// 此時還沒有 listener
13broadcast.stream.listen(print);
14broadcast.add(3);
15// 輸出：3 ← 監聽前的事件全部丟掉

這個差異對應用設計的影響：

• 單訂閱保證 listener 不漏接，適合「資料完整性 > 即時性」（檔案讀取、計算結果序列）
• broadcast 不保留歷史，適合「即時性 > 完整性」（UI 事件、狀態變更通知）

如果改成 broadcast 後，希望「新訂閱者進場時能拿到一次當下的狀態」（例如 controller 進場時想知道當前購物車內容），broadcast 本身做不到，要靠 service 自己保留 latest 或在新訂閱時手動 push 一次。RxDart 的 BehaviorSubject 內建這行為，純 dart:async 沒有。

對 POS 案例：sticky 高亮只關心未來變更，不在意歷史事件——broadcast 的丟棄行為跟這個語義一致、不造成資料缺失。但如果是「副螢幕鏡像當前購物車」這種需求，新副螢幕插入時若需要立即顯示當下狀態，就要在訂閱後手動 read 一次 cart.items。

3. Pause 行為（最反直覺）

1final single = StreamController<int>();
2final sub = single.stream.listen(print);
3sub.pause();
4single.add(1);  // 不會立刻送出
5sub.resume();
6// 輸出：1 ← 暫停期間的事件 resume 後補送

1final broadcast = StreamController<int>.broadcast();
2final subA = broadcast.stream.listen((v) => print('A: $v'));
3final subB = broadcast.stream.listen((v) => print('B: $v'));
4subA.pause();
5broadcast.add(1);
6// 輸出：B: 1   ← B 照收，A 暫存
7subA.resume();
8// 輸出：A: 1   ← A resume 後補回

單訂閱的 pause 等於「整條管線暫停」，上游 add 的資料堆在 controller 內部、記憶體會漲。Broadcast 是 per-listener 暫停，互不影響。

POS 的副螢幕場景如果搭配無界事件源（例如背景條碼掃描器）、用單訂閱且某條路徑沒 resume、會在 controller 內部累積未送出的事件、記憶體佔用持續上升——這是 production OOM 的常見來源之一。

設計缺陷為什麼在初期沒有可見影響

訂閱者單一時、限制處於沉默狀態

副螢幕訂閱寫在 service 啟動時、屬於 app lifetime 訂閱、沒有 cancel / 重新訂閱的情境。在這個訂閱模式下：

1. 副螢幕第一個訂閱 → 佔據 single-subscription 的「唯一 listener」配額
2. 沒有第二個訂閱方 → 違反契約的條件不會出現
3. 限制存在於型別契約裡、但沒有可見的影響

當訂閱者擴增到第二個時、這條 stream 的型別契約「整個生命週期只承載 1 個 listener」才開始產生可見的執行期影響。注意這裡描述的是「契約一直存在、只是沒有觸發違反條件」——不是「契約因為新需求才變成限制」。型別契約是當下選擇 StreamController() 時就確定的、訂閱者數量只決定它何時被觸發。

設計缺陷 vs 需求演化的分界

但「為什麼能算設計缺陷」這個問題值得停下來釐清——當下只有一個訂閱者、需求變了才需要多訂閱、這聽起來不像是「設計缺陷」、更像是「需求演化」。兩者怎麼分？

關鍵不是「有沒有預測到後來的需求」、是「當下的選擇是否在零成本差異下不必要地縮小了未來空間」：

本 case 落在第一格——StreamController() vs StreamController.broadcast() 是 11 字元差、零認知負擔、零維護成本差異。即使當下只有副螢幕一個訂閱者、選 broadcast 也沒付任何代價、卻保留了未來的彈性。寫成 single 不是「對當下需求的精確匹配」、是在零成本差異下不必要地縮小了未來空間——這才是「設計缺陷」這個詞要描述的事。

加上 POS 系統的領域先驗強烈指向「多視角同步」（主螢幕 / 副螢幕 / 廚顯 / 雲端 / 列印是教科書級的 pub-sub 場景）、選 single-subscription 等於假設「這個 service 不會有多訂閱需求」——這個假設跟領域常識矛盾、即使在當下也站不住。

「成本對稱性 / 可逆性 / 領域先驗」三軸框架的完整推導見 設計瑕疵還是避免過度設計？YAGNI 的真實適用條件——本 case 三軸都指向 broadcast、屬於 YAGNI 不適用的標準情境。

為什麼 IDE 與測試抓不到

• Dart 編譯器：型別簽章一樣（Stream<T>），編譯不會錯
• 靜態分析：dart analyze 不會警告 single-subscription 用法的潛在風險
• 單元測試：通常 mock 整條 stream，不會驗證真實 controller 是不是支援多訂閱
• Widget test：只跑單一頁面，不會同時掛多個訂閱模組
• 整合測試：理論上能抓，但成本高，多數專案在這層覆蓋稀疏

要在事前抓到，可行的方式：

• Lint rule：自訂規則檢查 StreamController() 預設用法，要求加註解說明「為何刻意不用 broadcast」
• Code review checklist：service 對外暴露 stream 時，預設假設要 broadcast，single 必須有書面理由
• 架構規範：直接禁用 raw StreamController 在 service 層，強制透過框架的廣播原語（Rx, BehaviorSubject, ValueNotifier）

修復決策過程

選項列舉

事故當下的選項：

為什麼選 A

POS 的這條 stream 語義就是「購物車狀態變更廣播」、多訂閱者本來就符合領域模型。選 B 會讓副螢幕服務變成轉發中樞、跟它「純顯示」的職責衝突。選 C 增加重複資料源、未來容易兩條 stream 不同步。選 D 雖然在架構層更一致、但 scope 過大、不是事故當下適合做的決定。

A 是改一行的 minimal fix，且修正了原本的設計缺陷而不是繞過它。

容易漏的細節：mock 也要改

Service 如果有 mock 實作（測試替身）、mock 端也要同步改成 broadcast。否則會出現「測試環境通過、production 仍然 throw」的不對齊狀況——單元測試（注入 mock）跟 production（真實 service）使用不同的 stream 契約、限制沒被測試覆蓋。

這是「測試環境與 production 配置不對齊」的典型陷阱。事故當下要把「修真實實作」「修 mock」當成同一件事的兩個必做動作，分開做就會漏。比較好的長期策略是把這個約束放進 code review checklist，或在 service 介面層加註解註明「實作不論真假都必須是 broadcast 語義」。

還要檢查：所有寫入路徑都有完整 emit

事故修復不只是改 stream 類型，還要回頭審視「事件 payload 的完整性」。

回到事故場景：事件 payload 第二段（這次變動是哪筆）原本沒人用，所以幾個寫入路徑可能根本沒傳。副螢幕只看第一段（完整列表），傳不傳第二段對它沒差。只有第二個訂閱者開始消費這段資訊時，遺漏才會暴露。

這是廣播設計的一個系統性風險：service 提供「為未來訂閱者保留」的擴充欄位時、這些欄位若沒有當下的消費者、缺漏不會在測試中浮現。第一個真正使用該欄位的訂閱者出現後、才會暴露出某些 mutation 路徑沒填寫該欄位。

修復清單：

• 把 single-subscription 改成 broadcast（真實實作 + mock 雙改）
• 審視所有寫入路徑，確保事件 payload 的每個欄位都正確填寫
• 確認第二個訂閱者的 dispose / cancel 邏輯
• 訂閱者進場時若需要「當下狀態」，要補一次直接讀取（broadcast 不保留歷史）

何時該選哪個

選 StreamController() 的情境

• 確定只有一個消費者，且這個契約被寫進文件 / 介面註解
• 需要保證每個事件都被消費（buffer 是 feature）
• 像 Future 但會發多個值：檔案讀取、HTTP response body chunks、long-running task 進度回報

選 StreamController.broadcast() 的情境

• 有多個訂閱者，或不確定未來會不會多
• 事件是「正在發生」的通知，錯過就算了（UI 事件、狀態變更廣播、event bus、application-level domain events）
• 不在意進場前的歷史事件（如果在意，自己保留 latestValue）

一個粗略的決策法

「如果某天有人想加第二個 listener，這在語義上合理嗎？」

• 合理 → 一開始就用 broadcast
• 不合理 → 用單訂閱，並在註解寫清楚為什麼

應用層的 service 通知絕大多數情境都偏向 broadcast；single-subscription 的甜蜜點在底層 I/O 或一次性 task 進度（兩者都有「單一消費者 + 不能漏接」的明確契約）。

對 POS 場景：service 對外暴露的「狀態變更通知」幾乎都落在 broadcast 區——POS 的本質就是多裝置 / 多視圖共享同一份交易狀態（主螢幕、副螢幕、廚顯、雲端、列印機）。

補救與替代方案

已有 single-subscription stream，想對外提供 broadcast

不用改 controller 類型，可以包一層：

1final singleStream = someController.stream;
2final broadcastView = singleStream.asBroadcastStream();
3
4// 對外公開 broadcastView，原本的 singleStream 內部仍是 single-subscription

asBroadcastStream() 把單訂閱當 source，對外提供 broadcast view。一旦呼叫過一次，後續訂閱者都拿這個 view。

注意：這個方法只能呼叫一次、第二次會 throw。實務上要保留回傳值在 service 內部做 cache。

想要「broadcast + 新訂閱拿最後一次值」

標準 dart:async 沒有這功能。要嘛自己實作：

 1class ReplayLastNotifier<T> {
 2  final _controller = StreamController<T>.broadcast();
 3  T? _latest;
 4
 5  Stream<T> get stream async* {
 6    if (_latest != null) yield _latest as T;
 7    yield* _controller.stream;
 8  }
 9
10  void add(T value) {
11    _latest = value;
12    _controller.add(value);
13  }
14}

要嘛用 RxDart 的 BehaviorSubject，內建這行為。POS 副螢幕鏡像場景特別適合 BehaviorSubject：副螢幕進場時就能立即看到當下購物車內容，不必等下一次變更。

Flutter 生態系的替代

純 StreamController 在 Flutter app 層比較少見，更常用的是：

如果你已經在用某個狀態管理框架，優先用框架的廣播原語，而不是 raw StreamController。StreamController 在 Flutter app 通常是底層 I/O service 才用（藍牙、socket、sensor）。

下一節對其中最常被混用的一組——raw StreamController 跟 GetX 的 Rx / .obs——做完整對比，因為這也是事故當下會考慮「是不是該整個換掉」的對象。

深入比較：raw StreamController vs GetX 的 Rx / .obs

先釐清：Rx 跟 .obs 的關係

在 GetX 裡，Rx<T> 是底層 reactive value container，.obs 是把任何值包成對應 Rx 子類的 syntax sugar：

1// 三種寫法本質等價
2final count1 = 0.obs;            // 推導為 RxInt
3final count2 = RxInt(0);         // 顯式建構特化子類
4final count3 = Rx<int>(0);       // 較少用，因為 RxInt 提供更多 operator overload
5
6count1.value++;  // RxInt 可直接用 ++
7count3.value++;  // Rx<int> 也行，但缺了 RxInt 的算術特化

.obs 對不同型別回傳不同特化子類：

特化子類的核心好處：原生語法的 mutation（+=、list add、string concat）都直接觸發 reactive 通知，不需要手動 notifyListeners() 或 add()。

結論：.obs 跟 Rx 不是兩個不同概念，是同一個機制的兩種建構寫法。後者多了型別推導與特化命名。

概念差異

相同任務的程式碼對比

任務：service 對外暴露一個整數狀態，UI 顯示它且當值變化時自動 rebuild。

 1// ===== Raw StreamController 寫法 =====
 2
 3class CounterService {
 4  int _value = 0;
 5  final _controller = StreamController<int>.broadcast();
 6
 7  int get value => _value;
 8  Stream<int> get stream => _controller.stream;
 9
10  void increment() {
11    _value++;
12    _controller.add(_value);
13  }
14
15  void dispose() => _controller.close();
16}
17
18// UI:
19StreamBuilder<int>(
20  stream: service.stream,
21  initialData: service.value,  // 不帶這個首次 build 是 null
22  builder: (context, snap) => Text('${snap.data}'),
23)

 1// ===== Rx / .obs 寫法 =====
 2
 3class CounterService extends GetxController {
 4  final value = 0.obs;
 5
 6  void increment() => value.value++;
 7
 8  // 不需要寫 dispose；Rx 隨 controller 生命週期自動清理
 9}
10
11// UI:
12Obx(() => Text('${service.value.value}'))

差異一目了然：

• 樣板量約 4-5 倍差距
• StreamController 要自己維護 latest value
• StreamController 要記得寫 dispose
• Obx 自動追蹤所有 .value 讀取，不需要手動 listen/cancel
• StreamBuilder 要處理 initialData 與 snap.data 為 null 的情境，Rx 沒這問題（永遠有值）

Rx 內部其實就是 StreamController + ValueNotifier

Rx<T> 底層用 StreamController.broadcast() 加上一個 _value 欄位。Obx widget 在 build 時開一個訂閱範圍，期間任何 .value getter 會被追蹤；build 結束後對應的 stream 訂閱自動建立，值變化時觸發 widget rebuild。

簡化心智模型：

 1class Rx<T> {
 2  T _value;
 3  final _ctrl = StreamController<T>.broadcast();
 4
 5  Rx(this._value);
 6
 7  T get value {
 8    RxInterface.proxy?.addListener(_ctrl.stream);  // Obx 注入的依賴追蹤代理
 9    return _value;
10  }
11
12  set value(T v) {
13    if (_value == v) return;  // ← 等值不觸發
14    _value = v;
15    _ctrl.add(v);
16  }
17}

（真實實作更複雜，但骨架是這樣。）

換句話說 Rx ≈ broadcast StreamController + ValueNotifier + 自動依賴追蹤 + 特化子類。理解這層之後，後面所有「Rx 為什麼這樣」的問題都能從這個本質推回去。

完整對比表格

Rx 的特殊行為與陷阱

1. 等值不觸發更新

1final name = ''.obs;
2name.value = '';     // 不觸發 listener（'' == ''）
3name.value = 'A';    // 觸發
4name.value = 'A';    // 不觸發（'A' == 'A'）

如果需要「每次 set 都觸發」（例如重新打 API 不管值有沒有變），用 .refresh() 或 .trigger()：

1name.refresh();              // 強制通知所有 listener，不變更 value
2name.trigger('A');           // 強制通知，且 set value

2. 物件內部變動不觸發

1final user = User(name: 'A').obs;
2user.value.name = 'B';                         // 不觸發，reference 沒變
3user.refresh();                                // 強制觸發
4user.value = user.value.copyWith(name: 'B');   // 換新 reference 自然觸發

這跟 immutable 風格（Freezed、Equatable）配合最自然，copyWith 一定產出新 reference。

3. Obx 必須讀到至少一個 .value

1Obx(() => Text('hello'))                  // warning: improper use
2Obx(() => Text('${counter.value}'))       // 正確

Obx 靠 build 期間攔截 .value getter 建立訂閱關係，build callback 內完全沒讀任何 Rx 就不知道要 subscribe 誰。

4. RxList / RxMap 的 mutation 規則

1final items = <int>[].obs;
2items.add(1);          // 觸發（RxList 重寫了 add）
3items.value.add(2);    // 不觸發（操作的是底層 List）
4items[0] = 99;         // 觸發（RxList 重寫了 []=）
5items.refresh();       // 補救

特化集合類別重寫了 add/remove/[]=/clear 等 method 讓它們自動 emit；繞過 wrapper 直接操作 .value 就會跳過這層。

5. .obs 推導出的特化型別可能不是你想要的

1final list = [1, 2, 3].obs;        // RxList<int>
2final list2 = <num>[1, 2, 3].obs;  // RxList<num> — 注意泛型推導
3
4// 自定義型別需明確
5final user = User(name: 'A').obs;  // Rx<User>，不是「RxUser」

Rx 的 worker 類型（service 之間的訂閱模式）

Obx 是 widget 自動訂閱；service 內或 controller 之間的訂閱用 worker：

 1// 每次變化都觸發
 2final disposer = ever(counter, (value) => print('changed to $value'));
 3
 4// debounce — 連續變化只取最後一次
 5debounce(
 6  searchText,
 7  (value) => searchAPI(value),
 8  time: Duration(milliseconds: 500),
 9);
10
11// throttle — 固定間隔最多觸發一次
12interval(
13  scrollPosition,
14  (value) => analytics(value),
15  time: Duration(seconds: 1),
16);
17
18// 只觸發一次後自動移除
19once(loginState, (value) => navigateHome());
20
21// 監聽多個 Rx，任一變動就觸發
22everAll([a, b, c], (_) => recompute());
23
24// 手動清理
25disposer.dispose();

這些 worker 在 GetxController.onInit 裡註冊時會被綁定到 controller 生命週期，controller dispose 時自動清；在 controller 外註冊就要自己 .dispose()。

何時選哪個

選 raw StreamController

• 寫底層 service（藍牙、socket、sensor、background isolate 通訊）
• 需要豐富的 stream operators 鏈（map/where/buffer/distinct/merge/combineLatest…）
• 對外提供的 API 不想綁特定狀態管理框架，要保持框架中立
• 需要 backpressure / pause-resume 等進階流量控制
• 跨 isolate 資料傳遞

選 Rx / .obs

• 寫 UI state 或 application state
• 已在用 GetX，沿用一致
• 需要「保留當前值 + 多訂閱者」這個常見組合
• 想要 widget 自動追蹤，不想手動寫 listen/cancel
• service 內部 latest value 與通知的樣板太多次，懶得繼續寫

把事故場景改寫成 Rx 看看

回到事故場景。如果 service 從一開始就用 reactive value container（如 Rx）來表達它的對外契約，整個問題會以另一種方式消失。

對外契約的轉變：service 不再「對外發送事件」，而是「對外暴露兩個可被觀察的狀態屬性」——當前完整的商品列表、最後一次變動的品項。訂閱方不需要 listen() 一條 stream，而是直接讀取屬性的當前值，並且系統保證屬性變化時觀察者會被通知。

在這個契約下回頭看每個訂閱方的需求：

• 副螢幕（鏡像當前商品列表）：只關心「列表屬性」變動，不在乎是哪一筆變動。它建立一個對列表屬性的觀察，每次變動就重畫
• 收銀主畫面（最後變更項標記）：只關心「最後變動屬性」，每次變動就更新高亮哪一行
• 未來的訂閱方（KDS、列印、雲端、analytics）：各自選關心的屬性建立觀察

兩個訂閱者觀察的是不同屬性，互不干擾；同一個屬性也允許多個觀察者（reactive value 天生是廣播語義）。

事故的兩個技術問題在這個契約下自動消失：

1. single vs broadcast 的選擇問題不存在——reactive value 沒有「單訂閱版本」，每個觀察者天生並存
2. 進場拿不到歷史事件的問題不存在——觀察者進場時可以直接讀屬性的「當前值」，不必等下一次變動

更深一層的觀察：raw stream 是「以時間軸上的事件為一等公民」的工具，適合「事件本身就是有意義的（log、命令、訊息）」場景；reactive value 是「以狀態為一等公民」的工具，適合「下游關心的是當前是什麼，不是過去發生了什麼」場景。POS 多視角同步的本質是後者——副螢幕關心的是「現在購物車裡有什麼」，不是「過去 5 分鐘掃進了哪些商品的時序」。

把這個認知一般化：當業務語義是「多個視角共享當前狀態」時，工具應該是 reactive value（Rx / ValueNotifier / BehaviorSubject）；當業務語義是「事件流的時序」時，工具才是 stream。本案的根因是「業務語義（共享狀態）」跟「工具語義（事件流）」錯配；single-subscription 是錯配關係下第一個被觸發的契約限制、但即使換成 broadcast、仍會在「進場拿不到歷史事件」這個層次暴露語義錯配。

是否該全面改寫成 Rx

事故當下不該。理由：

1. scope 控制：事故修復原則是 minimal change，StreamController() → .broadcast() 一字之差就解決
2. 回歸風險：把 service 介面從 Stream<T> 改成 Rx<T>，所有訂閱方（副螢幕、UI、未來的 KDS / 雲端同步）都要改 listen 方式
3. 耦合代價：如果 service 介面原本是 framework-neutral 的（純 dart:async），改 Rx 等於把 GetX 綁進公開 API，未來要換框架成本變高
4. 測試成本：改 Rx 之後，所有針對該 service 的測試都要改 mock 方式

該重構的時機：

• 整個系統已經 implicit 綁 GetX，介面 framework-neutral 的成本沒實質效益
• 新增 service 時直接用 Rx，舊的 stream-based service 等下次大改一起換
• 發現自己重複寫「_latest + StreamController.broadcast + getter + emit + close」的樣板太多次，Rx 是現成解
• 整理技術債的專屬 sprint，可以系統性換掉

事故修復應該專注 minimal fix；架構改造是另一張單。

除錯思維

Bad state: Stream has already been listened to. 的根因落在 stream 定義端的型別契約、不在訂閱端。檢查順序：

1. 這條 stream 是 single-subscription 還是 broadcast？
   • 從定義端確認（StreamController() vs StreamController.broadcast()）、訂閱端只承載限制、看不出契約類型
2. 若是 single、選 single 的理由有書面記錄嗎？
   • 介面註解 / 設計文件有記錄 → 看理由是否仍成立
   • 沒有記錄 → 屬於「用了預設建構子、沒做選擇」、回到當下三軸判斷
3. 多訂閱在語義上合理嗎？
   • 合理 → 改 broadcast、屬於修正型別契約跟業務語義對齊
   • 不合理 → 第二個訂閱者的需求要重新設計（透過第一個 listener 轉送、或拉新 stream）

把「這條 stream 該不該支援多訂閱」做為設計階段的明確決策、判斷成本（跑三軸）落在當下、且不依賴未來需求是否實際出現。

延伸：POS 場景的多訂閱模式

POS 系統本質上就是「中央交易狀態 + 多視圖/多裝置鏡像」，是 broadcast stream 最自然的應用領域。常見訂閱者：

設計階段先假設「會有多個訂閱者」、「未來訂閱者數量會增加」、「每個訂閱者只關心事件的一部分屬性」——這正是 broadcast 的典型語義；之後新功能要訂閱、設計上會自然容納。

對應的設計建議：

1. Service 對外的事件 stream 預設 broadcast——single-subscription 視為例外、要在介面註解書面說明
2. 事件 payload 設計成 record 或 sealed class——包含「是什麼變動 + 變動的詳細資料」、讓不同訂閱者各取所需
3. 不要假設訂閱者之間的觸發順序——broadcast 的 listener 之間沒有保證順序、訂閱者要假設彼此獨立
4. 進場時若需要初始狀態、提供 currentValue getter——broadcast 不保留歷史、用 explicit getter 補這個缺口

參考資料

• Dart StreamController API doc
• Dart StreamController.broadcast constructor
• Dart Stream.asBroadcastStream method
• Dart language tour - Asynchronous programming: streams
• RxDart BehaviorSubject doc

適用：debug 反覆失敗、CSS 規則不生效、JS 改完元素還原、layout 怎麼調都不對。 不適用：第 1 次失敗（修細節即可）；不同方向各自失敗 1 次（不算同方向累積）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋失敗計數、假設驗證、換方向決策、對外回報模板。

何時參閱本文件

為什麼第 2 次是轉折點

第 1 次失敗常是執行細節（typo、cache、syntax）— 修了再試通常會過。

第 2 次失敗、用同樣的方法但更小心、還是失敗 — 訊號的重量遠大於兩次相加。它說的是：「我以為的問題不在這層、根本問題在別處」。

第 3 次以上、沉沒成本綁住、加碼產生的副作用會超過解決的問題：

第 2 次是還能優雅切換方向的最後機會。

失敗計數的協議

關鍵動作是第 2 次的「停」 — 把行動從「執行更努力」切換到「驗證假設」。

假設驗證的具體方法

方法 1：用工具讀真實狀態

方法 2：反問「如果假設錯了會怎樣」

這個反思能在沒有工具的情況下測試假設。

「如果錯了會發生什麼」的答案 = 你正在看的失敗現象 → 假設可能錯。

方法 3：對外回報模板

1我嘗試了 [方向 X]：
2- 第 1 次：[做法 A] → [現象]
3- 第 2 次：[做法 B] → [一樣的現象]
4
5我的底層假設是「[假設 Z]」、但 [方法 1 / 方法 2 的驗證] 顯示 Z 似乎不成立。
6
7要不要換 [方向 W]、或您看到我沒看到的訊息嗎？

對外回報 = 把卡關放到使用者視野、避免繼續單方面加碼。

假設錯了之後：換方向 ≠ 全部重寫

換方向不是「之前的全部丟掉」、是「對抗錯假設的部分丟掉、其他保留」。

範例：search scope UI 放在「form 與 results 之間」。

• 嘗試 1-4：基於假設「drawer 是 form 的 sibling」、用 grid + display:contents + grid-row 排序 → 全失敗
• 第 5 次（用 playwright 驗證）：drawer 是 form 的 child、跟 form 共用 grid cell
• 換方向：不用 grid-row 控制位置（被假設綁住的部分）、改用 absolute + drawer margin-top（不被假設綁住）→ 一次成功

換方向後保留：CSS variable 命名、scope 命名、HTML 結構。丟掉：grid-row 規則。只丟跟錯假設綁定的代碼、不丟所有東西。

Wrong vs Right 對照

範例 1：specificity 戰

錯：

1/* 第 1 次：規則沒生效 */
2.target { color: red; }
3/* 第 2 次：加 specificity */
4.parent .target { color: red; }
5/* 第 3 次：再加 */
6.parent .container .target { color: red; }
7/* 第 4 次：放大絕招 */
8.parent .container .target { color: red !important; }

四次同方向加碼、根本問題（vendor CSS 用了更高 specificity 或更晚 cascade）沒解。

對：

 1/* 第 1 次：規則沒生效 */
 2.target { color: red; }
 3
 4/* 第 2 次失敗 → 停下來驗證假設 */
 5/* DevTools Computed → 看到 vendor 的 .pagefind .target { color: blue } 贏了 */
 6/* 假設「我的規則該贏」錯 → 換方向：CSS layers */
 7
 8@layer vendor { /* @import vendor css here */ }
 9/* 我的規則 unlayered → 自動贏所有 layered 規則 */
10.target { color: red; }

範例 2：JS 改完元素被還原

錯：

1// 第 1 次：改完被還原
2el.textContent = 'custom';
3// 第 2 次：加保護
4setTimeout(() => { el.textContent = 'custom'; }, 100);
5// 第 3 次：再加
6setInterval(() => { el.textContent = 'custom'; }, 50);  // CPU 100%

對：

 1// 第 1 次：改完被還原
 2el.textContent = 'custom';
 3
 4// 第 2 次失敗 → 停、驗證假設
 5// playwright: 看到 framework 每次 state change 重渲染整個子樹
 6// 假設「我的修改會 stick」錯 → 換方向：把客製 UI 放到 framework 邊界外
 7
 8const customEl = document.createElement('div');
 9customEl.textContent = 'custom';
10container.appendChild(customEl);  // 不在 framework 子樹內、不會被 reconcile

自檢清單（dogfooding）

第 2 次失敗時、用這份清單檢查：

• 我有沒有列出「底層假設是什麼」？
• 我有沒有用工具或反問驗證假設？
• 如果假設錯了、有沒有列出替代方向？
• 對外回報訊息有沒有寫「驗證 X、似乎不成立、要不要換 W」這種句式？
• 我有沒有避免「再試一次更小心」這種同方向加碼的衝動？

任一項打勾失敗 → 停下來補上、再決定下一步。

延伸閱讀

對應的事後檢討（在 content/report/）：

• failure-direction-pivot-point — 同方向反覆失敗的轉折點
• two-occurrence-threshold — 2 次門檻的抽象原則（跨工具 / 測試 / 思路 / 溝通四面向）
• verification-method-timing — 驗證方法的選擇時機

Last Updated: 2026-04-26 Version: 0.1.0

適用：UI layout debug、對齊問題、selector / MutationObserver root / JS 操作邊界的設計。 不適用：純內部演算法（沒有視覺、沒有範圍選擇）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋 placeholder 漸進、measurement 完整性、最小必要範圍三個共生原則。

Test-First 補充：當「漸進」的方式是「寫測試固化」時、必須走 RED → GREEN 兩個訊號才算驗證 — 詳見 #69 Test-First：先看到 RED 才相信 GREEN。沒看過 RED 的測試 = 未驗證的訊號、不能信任。

何時參閱本文件

為什麼這三個原則合併在一份 reference

三個原則服務同一個讀者群體（正在開始一個新工作、還沒卡關）、回答同一類問題（該從多大的範圍 / 多少變數起步）。

• Placeholder 漸進 = 視覺面的「一次一個變數」
• Measurement 完整性 = 對齊問題的「方程組必須完整」
• Minimum scope = JS / CSS 範圍的「窄起來再放寬」

共同精神：先窄後寬、有證據再擴張。「先寬後縮」的問題是分不出哪個寬度是刻意的；「先窄後寬」每次擴張都有原因可追。

原則 1：Placeholder 漸進除錯

UI debug 從色塊起步、加東西一次加一個。

起步：純色塊

1<div style="width: 200px; height: 100px; background: red; border: 2px solid black;"></div>

沒文字、沒樣式、沒互動。唯一目的：確認位置、尺寸、grid / flex / absolute 的定位邏輯對。

階段順序

每階段只引入一個變數、發現問題能立刻定位。跳階段 = 失敗時不知道是哪個變數錯。

典型反例

1<!-- 第 1 步直接寫真實內容 + 完整樣式 -->
2<div class="card">
3  <h3>Search results</h3>
4  <p>Showing {{count}} matches for "{{query}}"</p>
5  <ul>...</ul>
6</div>

CSS 寫了 30 條、結果 .card 沒在預期位置。是 grid 錯？font-size 影響？margin-collapse？line-height？無法定位。

原則 2：Measurement 完整性

對齊問題的本質是線性方程組：

1target_y = anchor_y + offset
2total_height = h1_height + form_height + gap + scope_height + ...

每個變數都要有明確來源 — 任一個未知 → 整組無解。

變數來源的三種類型

反例：靠估值補方程式

1/* 假設 form 大概 60px、加 gap 20px、總共 80px */
2.scope { top: 80px; }

實際 form 高度是 72px（隨字型 / line-height 變動）→ scope 跑位 8px。

對例：每個變數有來源

1const formHeight = form.getBoundingClientRect().height;  // measured
2const gap = parseFloat(getComputedStyle(form).marginBottom);  // measured
3scope.style.top = `${formHeight + gap}px`;

或全部用 design token：

1.scope { top: calc(var(--form-height) + var(--gap)); }
2/* var 在某處有單一定義、不是分散估值 */

混搭策略要全選同一邊：對齊基準上要嘛全寫死、要嘛全量測、不要 hardcoded + 估值混用。

原則 3：Minimum Necessary Scope

Selector / MutationObserver / JS 操作的範圍從最小起、擴張要有證據。

Selector 範圍

預設用最小、有證據（多個地方確實要 match）再擴張。

MutationObserver 範圍

三個維度：root、options、頻率。

1// 過寬
2observer.observe(document.body, { childList: true, subtree: true, attributes: true });
3// → 監聽整個 page、每個 attribute 變動都觸發、CPU 100%
4
5// 最小
6observer.observe(searchForm, { childList: true });
7// → 只監聽 form 直接子節點變動

JS 操作邊界

改一個元素的範圍從小到大：

從「改 inline style」起步、不行才升級。

三個原則的共同精神

從最小可驗證單位起步、有證據再擴張：

• Placeholder：色塊 → 文字 → 樣式（一次加一層）
• Measurement：每個變數先確認來源、再寫對齊規則
• Scope：最窄的 selector / observer / JS 邊界、要擴張要有具體 case

「先寬後縮」的反模式：寫一個包山包海的 selector、之後試著加 :not(...) 排除 → 永遠不知道哪些 match 是刻意的。

Wrong vs Right 對照

範例 1：UI debug 起步

任務：把搜尋結果卡片做成兩欄 grid

錯：

 1<!-- 直接寫完整版本 -->
 2<div class="results-grid">
 3  <article class="result-card">
 4    <h3><a href="...">Title</a></h3>
 5    <p class="excerpt">{{excerpt}}</p>
 6    <div class="meta"><span class="tag">tag</span> · <time>date</time></div>
 7  </article>
 8</div>
 9
10<style>
11.results-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 24px; }
12.result-card { padding: 16px; border: 1px solid; }
13.result-card h3 { font-size: 18px; margin-bottom: 8px; }
14/* ... */
15</style>

跑出來、卡片高度不一致、grid-auto-rows 沒設、第二欄擠到第一欄底下。debug 困難 — 是 grid 設定錯？卡片內容差異？margin-collapse？

對：

1<!-- 階段 1：純色塊驗證 grid -->
2<div class="results-grid">
3  <div style="height: 100px; background: red;"></div>
4  <div style="height: 100px; background: blue;"></div>
5  <div style="height: 100px; background: green;"></div>
6  <div style="height: 100px; background: yellow;"></div>
7</div>

確認 grid 兩欄正常後、再進階段 2（加占位文字）。

範例 2：MutationObserver root

任務：當 search results 出現時、注入客製 UI

錯：

1new MutationObserver(...).observe(document.body, { subtree: true, childList: true });
2// 整個 page 任何變動都觸發、callback 跑 1000+ 次/秒

對：

1const container = document.querySelector('.pagefind-ui__results-area');
2new MutationObserver(...).observe(container, { childList: true });
3// 只監聽 results area 的直接子節點變動

如果之後發現 .pagefind-ui__results-area 內部 nested 變動也要監聽 → 那時再加 subtree: true、加之前能說出「為什麼需要」。

自檢清單（dogfooding）

開始一個新工作前：

• UI debug：第 1 階段是不是純色塊（沒文字、沒樣式）？
• 對齊規則寫之前：是不是每個變數都列出來源（hardcoded / hook / measured）？
• Selector：起步是不是最精準的版本？
• MutationObserver：root / options 是不是最窄的？
• JS 改元素：是不是從「改 inline style」起、不行才升級？

任一項打勾失敗 → 退回最小、重新起步。

延伸閱讀

對應的事後檢討（在 content/report/）：

• placeholder-driven-ui-debug — 從色塊 placeholder 開始的漸進式 UI 除錯
• measurement-completeness — 量測值缺一不可
• minimum-necessary-scope-is-sanity-defense — 最小必要範圍是 sanity 防線

Last Updated: 2026-04-26 Version: 0.1.0

requirement-protocol 是一套對話協議 skill，原生位置在 .claude/skills/requirement-protocol/ 供 Claude runtime 呼叫；這份是同內容的文章版本，讓人類讀者也能直接在 blog 閱讀。

把「使用者下指令 → 執行者實作」之間的溝通流程結構化、避免反覆失敗、避免做出使用者沒要的東西、避免在錯誤方向上累積沉沒成本。源頭是 content/report/ 累積的 50+ 篇事後檢討、由本 skill 的五份 reference 萃取對應五個情境的協議步驟。

閱讀順序

場景 1：第一次接觸

場景 2：已熟悉協議、想直接解決當前任務

直接依觸發情境跳對應 reference：

每份 reference 自包含：讀任一份不需要回頭讀其他 reference。

與 blog 專案其他資料的關係

Last Updated

2026-04-26 — 初版：v0.1.0 同步、五份 references 對應「模糊指令 / 失敗轉折 / 成本與 checkpoint / 漸進驗證 / 工具切換」五個情境。

排查 Gradle JVM target inconsistency 時走了七個節點才收斂。這篇復盤每個節點的完整決策流：

節點 A：第一次錯誤出現

當下看到

1Execution failed for task ':flutter_broadcasts_4m:compileDebugKotlin'.
2> ⛔ Inconsistent JVM Target Compatibility Between Java and Kotlin Tasks
3  detected for tasks 'compileDebugJavaWithJavac' (17)
4  and 'compileDebugKotlin' (1.8).

判讀

這類錯誤在系統中代表什麼（商業邏輯）：

Android 專案的每個 module（主 app 或第三方 plugin）會分別編譯 Java 跟 Kotlin 原始碼，各自產出 JVM bytecode。每個 bytecode 檔案有一個「target version」，決定它能在多舊的 JVM runtime 上執行，以及可以使用哪些語言特性。

同一個 module 內的 Java 跟 Kotlin 若產出不同 target 的 bytecode，執行時可能觸發 API 相容性問題（例如 Java 17 的 class 呼叫到 Kotlin 1.8 runtime 不存在的方法）。Kotlin 2.2 把這個原本只是 warning 的情境提升為 strict error，直接中止 build。

所以 Inconsistent JVM Target Compatibility 這類錯誤的本質是：某個 module 裡面 Java 跟 Kotlin 編譯產出的 bytecode 不是同一個版本。

這次訊息具體說了什麼（CASE）：

• 錯誤 task 前綴 :flutter_broadcasts_4m → 出問題的 module 是這個第三方 plugin
• compileDebugJavaWithJavac (17) → 這個 module 的 Java 編譯產出 bytecode target = 17
• compileDebugKotlin (1.8) → 這個 module 的 Kotlin 編譯產出 bytecode target = 1.8
• 17 跟 1.8 不同 → 符合上面「module 內不一致」的 pattern

從 CASE 推論的事：

• 主專案 :app 已設定 JVM 17，這個 plugin 的 Java 繼承到 17；但 Kotlin 被某處明確設成 1.8
• Kotlin plugin 的預設值會跟 Java 對齊，所以 1.8 是「有人明確寫了」，不是預設
• 最有可能的「有人」是 plugin 自己的 build.gradle

需要進一步確認才能完整判讀的：

• Kotlin 1.8 具體寫在哪？cat ~/.pub-cache/hosted/pub.dev/flutter_broadcasts_4m-*/android/build.gradle 可以驗證
• 其他 plugin 有沒有同類寫死？這不影響當前這個錯誤的修復，但影響修復範圍的完整性

判讀後的問題類別：

• 類別：第三方 plugin 內部寫死 JVM target
• 主專案的 override 機制沒能覆蓋到 plugin 的內部設定

這次判讀的完整度：驗證了 plugin 內部寫死（確認過 kotlinOptions { jvmTarget = '1.8' }），但沒有擴大搜尋其他 plugin。這個不完整後來在節點 D 付出代價。

可選策略

A1. 等 plugin 升級

• 優點：零維護；無需理解 Gradle 機制
• 缺點：決策權不在自己；無法保證 plugin 作者會修

A2. 從 root 專案強制覆寫

• 優點：決策權自主；影響範圍可控；不需 fork
• 缺點：需要理解 Gradle 生命週期

A3. Fork plugin 修改

• 優點：覆蓋完整；可修改任何細節
• 缺點：持續維護成本；升級需 merge;增加依賴來源複雜度

A4. 降 :app 回 JVM 1.8

• 優點：不需額外配置
• 缺點：放棄 Java 17 語言特性；跟 AGP 方向相反

選擇與理由

A2。A1 放棄決策權；A3 維護成本跟 plugin 重要性不成比例；A4 機會成本太高。

修正動作

 1subprojects {
 2    plugins.withId("com.android.library") {
 3        android {
 4            compileOptions {
 5                sourceCompatibility = JavaVersion.VERSION_17
 6                targetCompatibility = JavaVersion.VERSION_17
 7            }
 8        }
 9    }
10    tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
11        kotlinOptions { jvmTarget = '17' }
12    }
13}

結果

flutter_broadcasts_4m 過了。

事後檢視

判讀階段明確知道「需要進一步確認其他 plugin 是否有同類問題」，但沒做。當下沒做的理由是「目前錯誤訊息只指向這一個 plugin」，這個理由把判讀完整性降到最低——修復只要能讓當前這次 build 過就好。

若判讀時把「範圍完整性」當成跟「修復正確性」同等的維度：

• 會額外做一次 grep -r "jvmTarget" ~/.pub-cache/hosted/pub.dev/*/android/build.gradle | grep "1.8"
• 會得到一份完整的有同類問題的 plugin 清單
• 修復策略 A2 就會涵蓋整份清單，不只當前一個

這裡不是選錯了策略，是判讀時把範圍當成「訊息指定的」而非「應該主動探索的」。

節點 B：使用者問「要不要換 JVM Toolchain」

當下看到

節點 A 修復成功。使用者提出：「既然官方推薦 JVM Toolchain，A2 的 task 級 configureEach 是不是次佳解？」

判讀

這不是錯誤訊息，是當前方案跟官方推薦方向的差距。

這類判斷的商業邏輯：

Gradle 有兩種層次不同的 JVM 治理機制，判斷「要不要換」之前要先理解它們處理的是不同問題：

• 編譯輸出控制：決定「編譯出來的 bytecode target 是多少」。影響產出的 .class 檔能在哪個 JVM runtime 上跑，但不管 Gradle 自己用什麼 JDK 執行。
• JDK 工具鏈管理：決定「Gradle 執行編譯器時用哪一版 JDK」。不同 JDK 會影響編譯行為、支援的語言特性、以及一些 bytecode 預設目標。

這兩件事可以獨立設定。一個專案可以用 JDK 21 執行 Gradle，但編譯產出 JVM 17 bytecode（為了向下相容）。

所以「要不要換 toolchain」這個問題的本質是：這兩層治理機制現在各自的解決方式是否對當前需求最佳？

這次的具體選擇空間（CASE）：

當前方案：tasks.withType(KotlinCompile).configureEach { jvmTarget = '17' } task 級 configureEach

• 處理的問題：編譯輸出控制（bytecode target = 17）
• 不處理的問題：JDK 工具鏈管理（開發者本機裝什麼 JDK、版本是否一致未控管）

Toolchain 方案：kotlin { jvmToolchain(17) } extension 級

• 處理的問題：JDK 工具鏈管理（Gradle 自動下載 JDK 17 執行）
• 附帶處理：對守規矩的 plugin 也會影響 bytecode target
• 不處理的問題：硬寫死 jvmTarget = '1.8' 的 plugin（extension 會被 plugin 的 task 設定蓋掉）

從 CASE 推論的事：

這兩個方案不是替代關係，是不同層次的治理。task 級覆寫處理「產出」，toolchain 處理「JDK 環境」。兩者可以並存，甚至應該並存。

需要進一步確認：

• Toolchain 的 extension 設定是否真會被硬寫死的 plugin 蓋掉？（答案是：會被蓋掉，但節點 B 當下沒驗證）
• Toolchain 能在哪些時機點設定？（答案：某些屬性在 plugin apply 的 lazy initializer 時 finalize，此時再設會炸——但這也是節點 B 當下沒驗證）

可選策略

B1. 保持現狀（task 級 configureEach）

• 優點：已經 work
• 缺點：偏離官方方向；每位開發者本機 JDK 需自行管理

B2. 完全換成 toolchain

• 優點：符合官方方向；JDK 自動下載
• 缺點：無法覆蓋硬寫死 plugin（extension 會被 plugin 的 task 設定蓋）

B3. 混合（toolchain + task 級覆寫）

• 優點：同時享有 toolchain 的 JDK 管理跟 task 級的強制力
• 缺點：配置面向增加

選擇與理由

B3。B2 單獨不完整，B1 忽略長期適應性，B3 是功能完整的組合。

結果

Build 炸：languageVersion is final。

事後檢視

判讀階段明確列出了「toolchain 能在哪些時機點設定」這個需要確認的問題，但沒確認就進入策略。判讀的未完成部分就是節點 C 的失敗來源。

這次判讀告訴了我們「還缺什麼資訊」，但沒有把「缺的資訊」當成進入下一階段的阻擋條件。若判讀的標準是「所有標示為『需要確認』的事實都要先解答」，節點 C 不會發生。

這一步的本質問題是把判讀中的不確定性帶入執行階段。

節點 C：languageVersion is final 錯誤

當下看到

1* Where:
2Build file '/Users/mac-eric/project/unipos/android/build.gradle' line: 37
3
4* What went wrong:
5> The value for property 'languageVersion' is final and cannot be changed any further.

判讀

這類錯誤在系統中代表什麼（商業邏輯）：

Gradle 的許多 configuration 屬性有「生命週期狀態」的概念。一個屬性從建立時可以自由讀寫，但到了某個時機點後會被 finalize — 意思是「值從此鎖定，任何後續賦值都會被拒絕」。

Finalize 不是錯誤，是 Gradle 保證 build 可預測性的機制：若某個值已經被使用（被其他 task 讀取、被其他設定依賴），再讓它改變會造成「同一次 build 的上下文裡不同地方看到不同值」的不一致。

觸發 finalize 的時機有很多種，最常見的：

• 其他程式碼讀取了這個屬性
• plugin 內部的 lazy initializer 把值固定下來
• project evaluation 進入某個階段

所以 is final and cannot be changed any further 這類錯誤的本質是：你現在嘗試賦值的屬性，已經在更早的時機被鎖定了。問題不在「值本身」，在「賦值的時機」。

這次訊息具體說了什麼（CASE）：

• 錯誤位置：root build.gradle line 37
• line 37 是 kotlin { jvmToolchain(17) } 那行
• 被鎖定的屬性：languageVersion
• 狀態：已 final，拒絕修改

從 CASE 推論的事：

• jvmToolchain(17) 內部試圖設定多個屬性，其中 languageVersion 已 final
• 「已 final」表示有更早的動作完成了它的 finalize。可能來源：
  • (a) 某個 plugin 在 apply 階段透過 lazy initializer 把值固定下來
  • (b) 某個先前的配置（kotlinOptions { } 或類似）把值鎖定
• 這段在 subprojects {} 內，會對每個 subproject 執行；可能不是每個 subproject 都觸發，是某個特定的

錯誤訊息沒說但需要推論的：

• 是哪個 subproject 觸發？訊息沒指名
• 為什麼 :app 先前 kotlin { jvmToolchain(17) } 成功，subprojects 內就失敗？

判讀後的問題類別：

• 類別：時機問題 — 設定 jvmToolchain 的時機晚於某個 plugin 的 languageVersion finalize 時機
• 對照已 work 的 :app：:app 是在自己的 build.gradle 頂層設 toolchain，時機最早
• 差異：subprojects 內的 plugins.withId 或 kotlin {} 區塊是 callback，執行時機比 :app 頂層晚

可選策略

C1. 拿掉 subprojects 的 toolchain，只留 :app

• 優點：:app 的 toolchain 驅動整個 Gradle daemon 的 JDK 環境，子專案繼承；避開 finalize 衝突
• 缺點：依賴「Gradle daemon 用 global JDK」這個前提

C2. 改用 afterEvaluate 延遲 toolchain 設定

• 優點：可能繞過 finalize
• 缺點：afterEvaluate 的時機本身可能更晚，屬性可能更 finalized；且 :app 已 evaluate 的情境會引入另一個問題（未預見）

C3. 回滾 toolchain，完全用 task 級覆寫

• 優點：最保守；已驗證 work
• 缺點：放棄 toolchain 的 JDK 管理；違反節點 B 的初衷

選擇與理由

C1。判讀中指出「:app 頂層時機最早所以 work」，對應的治理是「只在最早時機點設定」。C1 直接反映這個判讀。

結果

flutter_broadcasts_4m 繼續通過，但會遇到下一個 plugin。

事後檢視

C1 選擇正確，但支持 C1 的關鍵事實（Gradle daemon 使用 global JDK）是節點 C 當下才被建立的。若節點 B 判讀階段就補上這個事實，B 階段的「B3 設定方式」會直接選「toolchain 只設在 :app」，節點 C 不會發生。

這一步的決策品質問題不在節點 C，在節點 B 的判讀不完整。

節點 D：第二個 plugin 爆了

當下看到

1Execution failed for task ':external_display:compileDebugKotlin'.
2> detected for tasks 'compileDebugJavaWithJavac' (1.8)
3  and 'compileDebugKotlin' (17).

判讀

這類錯誤在系統中代表什麼（商業邏輯）：

跟節點 A 是同一類錯誤（JVM target 不一致），但要注意不一致的方向：「哪一邊高、哪一邊低」決定治理策略。

在覆寫第三方 plugin 的 JVM target 時，每一個 module 有兩個編譯端（Java、Kotlin），每一端都可能被 plugin 寫死或被主專案覆寫。可能的失敗組合是：

• Java 端被 plugin 拉低，Kotlin 端被主專案拉高 → 要覆寫 Java
• Kotlin 端被 plugin 拉低，Java 端被主專案拉高 → 要覆寫 Kotlin
• 兩端都被 plugin 拉低 → 兩端都要覆寫

訊息裡的「低的那端」就是還沒被主專案成功覆寫的那一端，也就是下一步要處理的目標。

這次訊息具體說了什麼（CASE）：

• 出問題的 module 換了：是 :external_display（不是節點 A 的 :flutter_broadcasts_4m）
• 方向跟節點 A 相反：
  • 節點 A：Java 17 / Kotlin 1.8（Kotlin 低）
  • 現在：Java 1.8 / Kotlin 17（Java 低）

從 CASE 推論的事：

• Kotlin 17 表示節點 A 的 KotlinCompile.configureEach { jvmTarget = '17' } 對 :external_display 也生效了 —— 這條 task 級覆寫不限於單一 plugin
• Java 1.8 表示節點 A 的 plugins.withId("com.android.library") { android { compileOptions = 17 } } 沒對 :external_display 生效
• 這段覆寫對 :flutter_broadcasts_4m 可能生效（否則 Java 也會是 1.8），也可能是 :flutter_broadcasts_4m 的 Java 本來就是 17 沒被寫死
• 需要進一步確認 :external_display 的 build.gradle：是不是它自己硬寫了 compileOptions = 1.8

驗證判讀（實際做了）：

1cat ~/.pub-cache/hosted/pub.dev/external_display-0.4.2+1/android/build.gradle

確認這個 plugin 兩邊都寫死 1.8：

1compileOptions {
2    sourceCompatibility JavaVersion.VERSION_1_8
3    targetCompatibility JavaVersion.VERSION_1_8
4}
5kotlinOptions { jvmTarget = '1.8' }

需要進一步推論的：

• 為什麼節點 A 的 plugins.withId { android { compileOptions } } 沒贏過 plugin 的 android { compileOptions = 1.8 }？
• 猜測：plugins.withId 的 callback 早於 plugin 自己的 android {} 區塊，plugin 後寫所以蓋掉
• 但這只是猜測，還沒驗證 AGP 的同步機制

判讀後的問題類別：

• 類別：跟節點 A 類似（plugin 寫死），但覆寫的方向不同——這次是 Java 端要覆寫
• 節點 A 的 Kotlin 端有 task 級工具（configureEach）可用
• Java 端有沒有對稱的工具？這個判讀沒有完成

可選策略

D1. 在 tasks.withType(JavaCompile).configureEach 設 source/target

• 優點：跟節點 A 的 Kotlin 做法結構一致
• 缺點：假設 AGP 的 JavaCompile 跟 Kotlin plugin 的 KotlinCompile 機制對稱，這個假設沒驗證

D2. 在 plugins.withId { android { compileOptions } } 覆寫

• 優點：用 extension 而非 task
• 缺點：這段已經在檔案內且顯然沒生效（plugin 後來的 android {} 蓋掉）

D3. 用 afterEvaluate 改 android.compileOptions

• 優點：時機晚於 plugin 自己的 android {}，能確實覆蓋
• 缺點：引入 afterEvaluate 的時序複雜度

D4. 先查 AGP 文件，確認 JavaCompile 是否能用 task 級覆寫

• 優點：判讀階段缺失的「Java 端機制」補完，選擇有依據
• 缺點：查證過程有不確定性

選擇與理由

D1。理由：跟節點 A 的 Kotlin 做法對稱。

這個選擇的本質問題在判讀階段。判讀結束時已經留下「Java 端機制未驗證」這個未完成的問題，但策略階段沒把 D4 當成補完判讀的選項，直接用「結構對稱」作為依據跳到 D1。

結果

Build 再爆，完全一樣的錯誤。

事後檢視

D1 的失敗根源是判讀不完整時就進入策略。這跟節點 B → C 的失敗模式相同：判讀列出了需要確認的事，但沒確認就決定策略。

對稱假設之所以危險，是因為它用「結構相似」取代了「機制驗證」。結構相似是判讀層次的現象（訊息結構類似），機制是底層層次的事實（實作者如何設計）。用前者取代後者，判讀就沒有真正進到底層。

當下若把 D4 視為跟 D1 平行的選項，而且讓判讀的未完成問題成為「必須先解」的前提，會直接跳到 D4 → D3 路徑。

節點 E：決定改用 afterEvaluate + extension

當下看到

D1 失敗，確認 AGP 會從 android.compileOptions 同步到 JavaCompile task。要把 Java 端的覆寫改成 extension 級，且要晚於 plugin 自己的 android {}。

判讀

這類選擇在系統中代表什麼（商業邏輯）：

Gradle 的 method(Closure) 形式 API（像 afterEvaluate、configure、doLast）都是兩階段模型：

1. 註冊階段：呼叫 method(Closure) 時，Gradle 把 closure 記起來，決定「什麼時候執行這個 closure」。這個註冊動作本身會立即執行，若註冊條件不滿足（例如目標物件狀態不對），註冊會直接失敗。
2. 執行階段：條件觸發時（例如 project evaluate 完成），Gradle 從註冊列表拿出 closure 執行。

這兩個階段的失敗模式不同：註冊失敗是呼叫 method 本身拋錯，closure 根本不會執行；執行失敗是 closure 內部拋錯。

所以當我們要對 method(Closure) 形式 API 套用過濾條件時，要先問：過濾的對象是誰？

• 若要過濾「延遲執行的內容」 → 條件放 closure 內
• 若要過濾「註冊動作本身是否該發生」 → 條件放 method 呼叫之前

這不是風格偏好，是「過濾發生在不同階段」。

這次的具體選擇空間（CASE）：

寫法 1：afterEvaluate { if (project.name != 'app') { android { compileOptions } } } 寫法 2：if (project.name != 'app') { afterEvaluate { android { compileOptions } } }

表面上兩者「看起來都跳過 :app」。

把商業邏輯套回 CASE 推論：

• 寫法 1：過濾在 closure 內 → afterEvaluate 本身會對所有 subproject 呼叫（包括 :app）。若 :app 狀態不滿足註冊條件，註冊階段就失敗
• 寫法 2：過濾在 afterEvaluate 外 → :app 根本不會觸發註冊呼叫

哪種寫法正確，取決於**「註冊階段對 :app 會不會失敗」**。

判讀需要問的關鍵問題：

• afterEvaluate 的註冊動作會不會失敗？
• 什麼情況下會失敗？
• 「project 已 evaluate」是不是其中一種？
• :app 在當前專案結構下會不會是已 evaluate 狀態？

這些問題當下沒問。判讀停留在「兩種寫法看起來一樣」的表面層次，沒有展開到兩階段模型。

可選策略

E1. 過濾放 closure 內

• 優點：過濾邏輯跟 closure 放一起；讀起來連貫
• 缺點：假設 afterEvaluate 方法呼叫不會失敗

E2. 過濾放 afterEvaluate 外

• 優點：阻止 afterEvaluate 方法呼叫本身對有問題的 project 觸發
• 缺點：兩層 if 需要額外理解

E3. 用 project.state.executed 判斷

• 優點：通用解法，不 hardcode 名字
• 缺點：對這個情境過度設計

選擇與理由

E1。理由：讀起來連貫。

這個選擇的本質問題：判讀沒展開「方法呼叫 vs closure 執行」的兩階段，所以權衡時用「可讀性」這個表面維度決定，沒有觸及「哪個寫法能阻止失敗」這個底層維度。

結果

Build 炸：Cannot run Project.afterEvaluate(Closure) when the project is already evaluated.

事後檢視

E1 vs E2 的真正差異不是「哪個好讀」，是過濾哪一個執行階段：

• E1 過濾延遲執行的 closure 內容
• E2 過濾方法呼叫本身

判讀若展開到這個層次，權衡就會變成：「我要過濾的是哪一個階段？」——而這題有明確答案（:app 的失敗發生在方法呼叫階段），所以 E2 是唯一正確選項。

判讀不到這個層次 → 兩個選項在決策者眼中「等價」→ 用次要維度（可讀性）決定。

節點 F：Cannot run afterEvaluate when already evaluated

當下看到

1Cannot run Project.afterEvaluate(Closure) when the project is already evaluated.

判讀

這類錯誤在系統中代表什麼（商業邏輯）：

Gradle 的 project 有生命週期：建立 → 配置中 → evaluate 完成 → 執行 task。一旦 project 走到「evaluate 完成」狀態，有些動作就再也做不了，因為它們的意義依賴於「evaluate 還沒結束」這個前提。

afterEvaluate 是一種「訂閱 evaluate 完成事件」的 API：註冊一個 closure，Gradle 承諾在該 project evaluate 完成時呼叫它。

但如果 project 已經 evaluate 完成，這個承諾無法兌現 — 「evaluate 完成」這個事件已經發生過了，不會再發生第二次。此時再註冊訂閱沒有意義，Gradle 直接拋錯。

所以 Cannot run Project.afterEvaluate(Closure) when the project is already evaluated 這類錯誤的本質是：想訂閱一個已經發生過的事件。

這次訊息具體說了什麼（CASE）：

• afterEvaluate(Closure) 這個方法呼叫失敗
• 失敗原因：目標 project 已經 evaluate 完
• 位置：root build.gradle line 52（afterEvaluate 那行）

從 CASE 推論的事：

• 「已 evaluate 完的 project」具體是哪個？訊息沒指名，但從上下文推論：
• 回頭看 root build.gradle 上半部有 subprojects { project.evaluationDependsOn(":app") }
• 這行強制 :app 比其他 subproject 先 evaluate
• 當 subprojects {} 的區塊處理到 :app 時，:app 的 evaluate 已完成 → 對它呼叫 afterEvaluate 失敗

完整推論鏈：

1subprojects {} 執行 → 對 :app 呼叫 afterEvaluate(Closure)
2→ :app 已 evaluate（因 evaluationDependsOn）→ 訂閱失敗

判讀後的問題類別：

• 類別：訂閱了一個已發生的事件（註冊時機晚於事件觸發）
• 解決方向：阻止註冊動作對該對象觸發

可選策略

F1. 把 project.name != 'app' 提前到 afterEvaluate 外

• 優點：直接阻止方法呼叫對 :app 觸發
• 缺點：hardcode 名字；若 :app 改名需修

F2. 用 project.state.executed 條件

• 優點：通用，不依賴名字
• 缺點：過度設計；:app 本來就不需要 subprojects 邏輯管

F3. try/catch 吞掉註冊失敗

• 優點：程式碼最少
• 缺點：anti-pattern，隱藏失敗

選擇與理由

F1。F3 是反模式；F2 的通用性在此情境無實際收益。

結果

Build 成功。

事後檢視

F1 選擇正確。但這個節點若在 E 階段判讀「方法呼叫 vs closure 執行」兩階段時就識別出來，F 節點本來不會存在。F 是 E 判讀不完整的延伸結果。

節點 G：最終修復

• :app/build.gradle：kotlin { jvmToolchain(17) }
• android/settings.gradle：Foojay plugin
• android/build.gradle subprojects：
  • Java 端 afterEvaluate 改 android.compileOptions（跳過 :app）
  • Kotlin 端 KotlinCompile.configureEach