三層的職責邊界

Unit Test：驗證程式碼邏輯

Unit test 驗證的對象是「開發者寫的程式碼是否按預期運作」。它的輸入和輸出都在程式碼控制範圍內 — 函式的參數、回傳值、狀態變化、例外拋出。

Unit test 的盲區是所有程式碼以外的東西。外部服務的協議行為、網路傳輸的編碼方式、作業系統的檔案鎖定機制 — 這些不在 unit test 的驗證範圍內，因為 unit test 用 mock 取代了這些外部依賴。Mock 忠實模擬的是程式語言層面的 API 契約（方法簽名、參數型別、回傳值），不是外部服務的協議行為。

app_tunnel 的 192 個 unit test 全部通過，但實機連線後鍵盤輸入無回應。原因是 WebSocket 的 text frame 與 binary frame 差異屬於協議層語意 — FakeWebSocketChannel 的 sink.add(dynamic) 接受任何型別，不區分 frame type（T.C1）。192 個 test 驗證的是「Dart 程式碼邏輯正確」，沒有任何一個 test 的職責是驗證「ttyd 收到的 frame type 是否正確」。

Protocol Integration Test：驗證真實協議互動

Protocol integration test 驗證的對象是「程式碼和真實外部服務之間的協議互動是否正確」。它不用 mock，而是對真實的服務實例發送請求，觀察真實的回應。

這一層的驗證目標包括：連線握手是否完成、認證流程是否正確、資料編碼是否符合對方期望、逾時行為是否合理。這些問題的答案不在程式碼裡，而是在程式碼與外部服務的互動過程中。

app_tunnel 的 auth handshake 缺失就是典型案例。ttyd 要求連線後發送 auth token JSON frame，但 ConnectionManager 沒有實作這個步驟 — FakeWebSocketChannel.ready 立即完成不需認證，所有 test 看到的都是連線成功（T.C2）。對真實 ttyd 執行一個「連線後不發 auth token，斷言 timeout」的 test，就能暴露這個缺失。

Screen State Test：驗證畫面狀態完整性

Screen state test 驗證的對象是「使用者可見的畫面狀態是否覆蓋所有情境」。它的關注點是畫面層級的狀態機 — loading、connected、error、reconnecting 等狀態之間的轉換是否完整，每個狀態下使用者看到什麼、能操作什麼。

Screen state test 和 unit test 的區別在於斷言對象：unit test 斷言「函式回傳值是否正確」，screen state test 斷言「使用者看到的畫面是否正確」。同一段程式碼邏輯可能 unit test 通過（回傳值正確）但 screen state test 失敗（畫面沒顯示對應狀態），因為 UI 層的 binding 有問題。

三層對照

數量與覆蓋率的關係

測試數量和測試覆蓋率是兩個獨立的維度。192 個 unit test 提供的是 unit test 層的覆蓋率 — 程式碼邏輯的分支覆蓋。把 unit test 從 192 個加到 500 個，增加的仍然是同一層的覆蓋率，不會跨越到協議層或畫面層。

層級缺失的問題無法用數量解決。如果整個 test suite 只有 unit test，即使覆蓋率 100%，protocol integration test 層和 screen state test 層的覆蓋率仍然是 0%。app_tunnel 的經驗是：在 unit test 層加更多 test 不會讓 frame type 問題浮現，因為 FakeWebSocketChannel 的行為在每一個 test 中都是一致的 — 一致地遮蔽了協議層差異。

下一步路由

• Mock 如何在 API 層和協議層之間製造盲區 → Mock 遮蔽機制分析
• 如何辨認「名義 integration test」 → 名義 integration test 的識別與修正
• 判斷自己的服務是否需要 protocol integration test → 判斷原則：什麼時候需要 protocol integration test
• 三層測試如何對應畫面狀態矩陣 → ux-design 模組一：畫面狀態機

對應 findings

待寫章節

• 三層定義與職責表（從 _index.md 的表格擴展為完整論述）
• Mock 遮蔽機制分析（API 層 vs 協議層 vs 環境層的斷裂點）
• 「名義 integration test」的識別與修正
• 判斷原則：什麼時候需要 protocol integration test（決策表）
• 反模式：用 mock 數量彌補 mock 盲區

跨分類引用

• → monitoring 模組三 SDK 設計：SDK 的自動攔截機制影響哪些錯誤能被 test 覆蓋
• → ux-design 模組一 畫面狀態機：狀態矩陣直接轉成 screen state test case
• ← ux-design 模組二 Gate Fallback：開發環境遮蔽 gate 問題的機制和 mock 遮蔽結構相同
• ← work-log 案例入口：192 個測試全過、實機全壞

三個判斷維度

維度一：協議複雜度

程式碼和外部服務之間的協議是否存在 API 層無法描述的語意？

HTTP REST API 的協議複雜度相對低：request body 是 JSON、response body 是 JSON、status code 有明確語意。Mock 一個 REST endpoint（回傳固定 JSON）和真實 endpoint 的行為差異主要在效能和邊界案例，核心語意差距小。

WebSocket 協議的複雜度較高：連線握手、frame type（text / binary / ping / pong / close）、分片（fragmentation）、壓縮擴展（permessage-deflate）、子協議協商 — 這些語意在 API 層（sink.add(dynamic)）是不可見的。gRPC 的 streaming、deadline propagation、metadata header 也有類似特徵。

判斷問題：API 簽名是否隱藏了協議層的行為分支？ 如果 API 用 dynamic、Object、Any 等寬泛型別接受輸入，而協議層對不同輸入有不同處理方式，這就是需要 protocol integration test 的訊號。

app_tunnel 的 sink.add(dynamic) 就是這個模式 — API 簽名不區分 String 和 Uint8List，但協議層對兩者產生不同的 frame type（T.C1）。

維度二：Mock 寬鬆度

Mock 的行為是否比真實服務更寬容？

Mock 通常是「最小可用」的實作 — 能讓 test 通過就好。這意味著 mock 的行為往往比真實服務寬鬆：不檢查認證、不限制速率、不要求特定順序、不區分輸入格式。

寬鬆本身不是問題，但寬鬆程度和真實服務的差距決定了 mock 遮蔽的風險大小。判斷問題：Mock 跳過了真實服務的哪些步驟？每個被跳過的步驟在業務上是否關鍵？

app_tunnel 的 FakeWebSocketChannel 跳過了 auth handshake — ready 立即完成不需認證。Auth handshake 在業務上是關鍵步驟（沒有認證，ttyd 不推送資料），mock 跳過這一步讓「功能根本沒實作」變得不可見（T.C2）。

逐項列出 mock 跳過的步驟是一個實用的 audit 方法。寫出「FakeWebSocketChannel 和 IOWebSocketChannel 的行為差異清單」，每一個差異點就是潛在的遮蔽風險。

維度三：失敗靜默度

外部服務收到非預期輸入時，回應是明確的錯誤還是靜默忽略？

如果外部服務對錯誤輸入回傳 HTTP 400 或斷線，問題在實機測試時會快速浮現 — 程式碼進入 error 狀態，開發者看到明確的錯誤訊息。但如果外部服務靜默忽略，問題表現為「連線成功但沒有回應」，debug 方向可能完全錯誤。

ttyd 收到 binary frame 時靜默忽略，不回傳錯誤碼也不斷線。這讓問題的表現從「frame type 錯誤」變成「終端機無回應」，開發者的 debug 方向是「為什麼 terminal 沒反應」而非「為什麼 frame type 不對」。

判斷問題：外部服務是否有靜默忽略的行為？ 如果有，protocol integration test 的價值更高 — 因為即使在實機測試階段，靜默忽略也會增加 debug 成本。

決策流程

以下流程不追求完備覆蓋所有情境，而是提供一個起點，根據上述三個維度的組合判斷 protocol integration test 的必要性。

協議複雜度高（API 層和協議層有語意斷裂）： 需要 protocol integration test。即使 mock 寬鬆度低、失敗回報明確，語意斷裂本身就是 mock 結構性無法覆蓋的盲區。

協議複雜度低，但 mock 寬鬆度高（mock 跳過業務關鍵步驟）： 需要 protocol integration test。Mock 跳過的步驟越多，「功能缺失不可見」的風險越大。

協議複雜度低，mock 寬鬆度低： 依失敗靜默度判斷。如果外部服務靜默忽略錯誤，protocol integration test 有較高價值；如果錯誤回報明確，可以依賴實機測試階段的 error 來發現問題。

成本極低的情境： 當外部服務可以在 test 環境輕鬆啟動時（自用工具 server+client 同機、Docker 一行啟動的 open source service），protocol integration test 的成本門檻大幅降低，三個維度中任何一個有疑慮就值得寫。

下一步路由

• 想實作 protocol integration test → 模組三：協議整合測試
• 理解 mock 遮蔽的結構性原因 → Mock 遮蔽機制分析
• 反模式：試圖用更多 mock test 補救 → 反模式：用 mock 數量彌補 mock 盲區

數量與層級的區別

app_tunnel 的 192 個 unit test 覆蓋了 ConnectionManager、AnsiParser、TerminalBuffer 等元件的邏輯分支。如果在 mock test 全過但實機失敗後，反應是「再寫 50 個 test」，新寫的 test 會使用同一個 FakeWebSocketChannel，測試更多的邏輯分支 — 更多的輸入組合、更多的邊界條件、更多的錯誤處理路徑。

這 50 個新 test 和原來的 192 個 test 在同一個 mock 環境中執行，受到同一個 FakeWebSocketChannel 的行為限制。FakeWebSocketChannel 不區分 text frame 和 binary frame — 這個限制在第 1 個 test 和第 242 個 test 中都一樣。數量增加了，遮蔽範圍沒有改變。

用類比說明：用純水測試淨水器的過濾效果，不管測 1 杯還是 1000 杯，結論都是「水很乾淨」。問題在測試材料 — 需要用含有雜質的水測試才能驗證過濾功能。Mock 是純水，真實服務互動是含雜質的水。

覆蓋率指標的盲點

Line coverage 和 branch coverage 衡量的是「程式碼中有多少行 / 分支被 test 執行過」。這些指標在同一層 test 內有意義 — 100% branch coverage 的 unit test 確保每個 if/else 都被走過。

但覆蓋率指標不區分 test 的依賴環境。一個使用 FakeWebSocketChannel 的 test 和一個使用 IOWebSocketChannel 的 test 走過同一行 sink.add(data) — 在覆蓋率報告中是同一行被覆蓋，但驗證的語意完全不同。

覆蓋率 100% 意味著「在 mock 環境中，所有程式碼分支都被走過」。這不等於「在真實環境中，所有程式碼分支的行為都是正確的」。app_tunnel 的 sendData() 在覆蓋率報告中是「已覆蓋」的，但覆蓋它的 test 用的是不區分 frame type 的 fake。

這個反模式如何在團隊中擴散

「test 不夠多」是一個容易執行、容易衡量的回應。在沒有獨立 QA 驗收流程的團隊中（覆蓋率報告是主要品質指標），寫更多 test 可以提高覆蓋率數字，覆蓋率數字上升給團隊信心。相比之下，「需要一個新的 test 層級」需要建置新的 test 環境、學習不同的 test 技術、接受較慢的執行速度。

這個成本差異讓團隊傾向於在既有的 mock test 層加量，而非引入新的 test 層。每一輪加量後覆蓋率上升，團隊信心增加，但 mock 遮蔽的盲區從未被觸及。問題在下一次實機測試或 production incident 中再次浮現，觸發新一輪的「test 不夠多」反應。

打破這個循環的起點是區分「同層覆蓋率不足」和「層級缺失」。如果問題是同層覆蓋率不足（某個分支沒被 test 走到），加 test 有效。如果問題是層級缺失（mock 結構性地遮蔽了某類行為），加同一層的 test 無效，需要引入新的 test 層級。

判讀訊號

以下訊號指向「層級缺失」而非「數量不足」：

test 全過但實機失敗的 bug 類型集中在外部互動：連線問題、認證問題、資料格式問題、逾時問題 — 這些問題的共同特徵是發生在程式碼與外部服務的邊界上，不是程式碼內部的邏輯錯誤。

修復後原有 test 不需要改動：如果 bug 修復只加了新程式碼（例如新增 auth handshake 步驟）而原有 test 全部不受影響，說明原有 test 從一開始就沒有覆蓋這個行為 — 整個 test 層級不涵蓋這類行為。

bug 修復是型別轉換或編碼調整：if (data is Uint8List) sink.add(String.fromCharCodes(data)) 這類修復改變的是資料在協議層的表現，不是程式邏輯。在 mock 環境中，這個修改前後的行為完全相同 — mock 不區分 frame type。

區分「同層覆蓋率不足」和「層級缺失」之後，回到三層定義與職責表確認每層的邊界。Mock 遮蔽的結構性原因在 Mock 遮蔽機制分析中展開。如果判斷結果是層級缺失，判斷原則：什麼時候需要 protocol integration test 提供引入新層級的決策流程。

本教材採四層結構。第一層是 atomic knowledge card，整理單一商業術語的核心概念、概念位置、可觀察訊號與判讀方式。第二層是分類索引，依商業模式、單位經濟、進入市場、競爭策略、市場動態、資本估值與執行知識把卡片分組。第三層是閱讀框架，幫助讀者判斷一篇商業分析的讀者定位、寫作目的與可信度。第四層是案例拆解，用 WRAP 框架拆解具體市場事件、抽出可遷移的判讀骨架。

分類體系

商業概念分成七個主題分類加一層閱讀框架。每個分類負責一段商業推理責任：商業模式說明公司怎麼賺錢、單位經濟說明每個客戶帶來多少利潤、進入市場說明怎麼把客戶簽進來、競爭護城河說明為什麼客戶不會離開、市場動態說明賽道現在是什麼狀態、資本估值說明財務語言怎麼影響定價、執行知識說明把產品做出來的隱性能力。

閱讀框架 處理「眼前這篇文章是寫給誰看、目的是什麼、該怎麼讀」。看到一篇分析時先用閱讀框架定位文章類型，再用分類卡片解碼術語。案例拆解 則是把整個流程實作出來—每篇文章拿一個具體市場事件（例如 Claude for Legal 推出、CoreWeave 收購 Bufstream），用 WRAP 結構走完一遍判讀。

學習路線

怎麼擴充這個模組

擴充走兩條路、依內容類型決定。

新術語：擴充 knowledge-cards

新術語從社群貼文或書中出現時：

1. 用 建卡判準 判斷該術語是否值得獨立建卡。
2. 用 分類體系 找到該卡片應歸屬的分類。
3. 用 卡片格式 寫卡，遵循「核心概念、概念位置、可觀察訊號、判讀方式」四段結構。
4. 在 knowledge-cards/_index.md 對應分類表格內加入連結。

不適合建卡的術語（過度寬泛、僅是字面翻譯、只能在原文中成立）應在分析文章中直接補清楚，避免建出單薄卡片。

新市場事件：擴充 case-analyses

看到值得拆解的市場事件（M&A、產品推出、IPO、產業整併、政策變動）時：

1. 用 媒介—讀者—目的矩陣 先定位原文類型。
2. 用 案例拆解的 WRAP 結構模板 逐段填寫。
3. 確保每個 Widen Option 都有對應 Reality Test、結尾必須給可遷移的判讀框架表。
4. Tripwire 段必須具體可監控（不能寫「再觀察」這種模糊話）。

如果事件無法產出可遷移框架（只是孤立特例）、放筆記裡即可、不要硬寫成案例。

跟其他模組的關係

商業教材跟 backend 教材是兩個獨立 surface，互不直接依賴。Backend 教材關心的是「服務能力、操作責任、失敗代價」；商業教材關心的是「公司怎麼賺錢、客戶怎麼留下、估值怎麼成立」。技術選型決策（例如「要不要遷移到 Diskless Kafka」）會同時被兩邊影響—backend 看遷移成本與風險，business 看整併週期 與毛利結構—但兩個敘事各自獨立，不互相替代。

多策略選擇（如 #59 五策略、#73 五匹配模式）預設不是單選。能疊加的策略應該疊加、互斥的才需要選。

最常見的疊加：root-cause 結構性修法 + 使用者感知補強（例如 multi-index 解層錯位 + UX hint 解 prefix-match 預期落差）— 解不同層、互不干擾、合在一起的覆蓋面 > 單選任一。

為什麼預設單選是錯誤前提

呈現多選項時容易進「適配性比較表 → 選最高分」的單選思維。這個思維對「互斥工具選擇」（Vue / React、Postgres / MySQL）成立、對「補強型策略」不成立：

• 結構性修法（修正根因、長期穩）— 通常需要時間 + 風險
• UX 補強（解使用者感知、立即可見）— 通常 ROI 立刻、但不解根因

兩者解的問題層不同：根因解了、使用者立刻感受到的混亂仍在；UX 蓋過去了、根因仍在累積技術債。預設單選 = 強迫使用者在「立即解使用者痛苦」與「長期解結構問題」之間二選一、其實兩個都該做。

疊加可行的三條判準

某兩個策略 X + Y 可疊加 ⇔ 滿足以下全部：

1. 解不同層

X 動結構 / 資料 / 演算法、Y 動 UI / 訊息 / 預期管理。同層的兩個策略通常衝突（兩種 cache 策略、兩種 routing 策略），不同層的多半互補。

判讀：把問題分成「根因 / 訊號 / 補償」三層、每層挑 1 個策略 = 疊加組合。

2. 沒副作用衝突

X 加上 Y 不會放大彼此副作用、不會產生新 bug。例：multi-index（佔 build time）+ UX hint（佔畫面空間）— 兩個 cost 維度不同、不互相放大。

反例：fetch-until-quota（多次 round trip）+ aggressive prefetch（更多 round trip）— 同維度副作用會疊加、可能爆炸。

3. 增量成本 ≤ 預算

第二個策略的實作 + 維護成本 ≤ 它解的問題價值。如果 X 已經解掉 80% 問題、Y 解剩下 20% 但成本是 X 的兩倍 → Y 就是過度工程、不該疊加。

典型疊加模式

模式一：Structural fix + UX patch

Structural 解根因、UX 解使用者當下混亂。即使 structural 還沒 ship、UX patch 可以先 ship 解眼前問題。

模式二：Defensive + Optimistic

Defensive 處理失敗、Optimistic 處理成功 — 兩個 happy path 共存、不衝突。

模式三：Now + Later

「先 ship X 解眼前、Y 下輪做」是一種隱式疊加 — 不是放棄 Y、是延後到風險更可承受的 release window。判準見 #76 分批 ship。

模式四：Selector strategy 疊加（#46-#50）

#46 / #47 / #48 / #49 四張 selector 起點 pattern 卡乍看互斥（每個元件只能選一個起點）、實際在同一個 handler 內可疊加：

同一份 component code 可同時用 #46 + #49（外部 portal 用 document、內部用 closest）— 解不同 selector context、不衝突、增量成本低 = 滿足三條判準。

判讀：「這幾個 pattern 是同層次（互斥）還是不同 context（互補）？」不同 context = 疊加。

反模式：強迫單選的代價

何時該堅持單選

四類共通：疊加的代價 > 疊加的收益。其他情境都該先檢查「能不能疊加」。

跟其他卡的關係

判讀徵兆

核心：策略選擇問「能不能疊加」優先於「選哪個」 — 多數工程問題的最佳解是「多層次組合」、不是「找出唯一答案」。

當系統能力不滿足使用者預期（capability gap）時、對策有三層階梯、依序評估：

預設順序：L1 → L2 → L3、依「成本最低先解」。不必每次跳到 L3 — L3 是最完整但也最貴、L1 在很多情境就夠。

為什麼有階梯：cost-coverage trade-off 是真實的

直覺反應遇到 capability gap 都想 L3「從根解決」。但 L3 的成本通常 10-100x 於 L1、覆蓋率提升可能只是 80% → 99%、邊際 ROI 低。

實際分布：

• 50% case：L1 就夠（gap 是「使用者誤解」、講清楚就好）
• 30% case：L2 解掉（gap 是「engine 差一步運算」、補一層 close）
• 20% case：必須 L3（gap 是「engine 模型錯位」、補不夠、要重來）

先試 L1、再試 L2、最後 L3 = 用真實 ROI 排序、不是用「完美主義」排序。

三層的判讀

L1：expectation alignment

適合：

• Gap 是「使用者預期跟 system capability 對不齊」、不是「system 算錯」
• 使用者改變行為就能 close gap（打字方式、order operation、輸入格式）
• Production 真的有 capability、只是 affordance 不明顯

不適合：

• Gap 在 system 算錯、不是預期錯位
• 使用者無法配合（流量大、不可能教育每個 user）
• 訊息會被忽略（A/B test 證明 hint 沒人讀）

例：

L2：augmenting computation

適合：

• Engine 缺一層計算就能 close gap、額外計算不貴
• Client / proxy / wrapper 層可加運算、不動 engine
• 預期 query 量在 augment 計算容量內

不適合：

• 補強計算成本爆炸（dataset 大、O(N) per query）
• Augmenting 跟 engine 結果語意不一致（產生 ghost results）
• 需要兩 engine 同步狀態才正確

例：

L3：structural rebuild

適合：

• L1 / L2 都不夠、capability gap 持續引發痛苦
• Production scale 大、L1 教育成本爆 / L2 計算成本爆
• 系統還沒長太大、重 build 成本可承受
• 將來會反覆遇到同類 gap（一次重 build、長期解多個問題）

不適合：

• L1 / L2 還沒試
• Production scale 不可動 build pipeline / schema
• ROI 不確定（gap 影響範圍小、值得 L3 投入嗎？）

例：

從 L1 升級到 L2 / L3 的訊號

不是「永遠先 L1」、是「依訊號逐層升級」：

逐層升級 vs 一次跳 L3：前者是 #76 分批 ship 的具體展現；後者是「便利驅動偏移」（#67） — 容易寫的選項是 L3「一勞永逸」、跟實際 ROI 不對齊。

從 L3 / L2 降級回 L1 的訊號

階梯不是只能升、也該能降 — L3 ship 後不該當「永久解」、是 ROI 動態的選擇。看到以下訊號、考慮降級：

為什麼降級難

升級有「使用者抱怨」當外部觸發、降級沒有 — 沒人抱怨「我們的 transformation 太多」。所以降級是典型的 #72 高 ROI 無觸發 工作、需要結構性 trigger：

• Periodic review（每季 review「我們還需要這個 L3 嗎」）
• Dependency upgrade event（升級觸發「L3 還相容嗎、還必要嗎」）
• Maintenance cost log（紀錄 L3 修了 N 次、累積到 threshold 觸發 review）

Pruning 是正常 lifecycle

降級不是「我們之前做錯」、是「ROI 變化、調整」。L3 在 ship 當下是最佳解、現在不是了 — 接受 capability gap 對策也會過時、跟其他工程決策同。

階梯 vs 疊加：跟 #75 的差別

#75 主策略 + 補強策略 講的是多策略疊加在不同層（structural + UX 並用）。本卡講的是同一個 gap 上、選哪一層（L1 vs L2 vs L3 通常選一個）。

兩卡互補：

• #75：選了 L3 後、要不要再加 L1 UX hint 當補強？（疊加維度）
• #86（本卡）：先試 L1 還是直接 L3？（階梯維度）

實際 case 通常兩條都用：先 #86 選層級、再 #75 看要不要疊加。

反模式

何時直接跳 L3

四類共通：L1 / L2 已知不夠、或 L3 真的最便宜。其他情境都該先試 L1。

跟其他抽象層原則的關係

判讀徵兆

核心：Capability gap 不是只有 L3 一條路 — L1 / L2 / L3 是 ROI 不同的三層階梯、依「成本最低先解」順序評估。「直接 L3」的便利感跟實際 ROI 反相關（#67）— 寫 L3 在白板上很爽、但通常 L1 / L2 已夠。

把 L1 expectation alignment + L2 augmenting computation 疊加 時、兩個 layer 給使用者的訊號要對齊、不是 redundant 也不是 conflicting：

設計三條原則：

1. L2 自動補時、訊號要明示「這是 fallback、不是 primary path」
2. L1 hint 要承認 L2 的存在（不要假裝 L2 不存在）
3. 使用者一直能 trace「這個結果怎麼來的」

為什麼疊加會打架

L1 跟 L2 各自設計、不協調時、訊號會相互削弱：

Conflicting 例：search

User 打 “pre” → 看到 backpressure 結果 → 困惑：「不是說要打 backpre？」 → 不確定下次該怎麼搜。

Redundant 例：retry with hint

User 看到 hint → 自己 manual retry → 但 system 已經在 retry → 操作冗餘 → 不確定 retry 是 user 觸發還是 system。

Conflicting 例：editor stale data

User 看到 banner、但每次資料其實都是 fresh（refresh 完成）→ banner 變 noise。Banner 撤掉後又會在某次 revalidation 失敗時 leak 出 stale data → 信任崩潰。

Layered Consistency 的三設計原則

原則 1：L2 自動補時、訊號明示「這是 fallback」

L2 不該無聲補強。當 L2 觸發、UI 應該標示：

關鍵：「自動補但隱形」是 silent UX、跟 #82 字面攔截 vs 行為精煉 的「false confidence」同骨。

原則 2：L1 hint 要承認 L2 的存在

L1 hint 不該假裝是「全部能做的事」：

1壞：搜尋為前綴匹配、找 backpressure 請打 backpre
2好：搜尋優先前綴匹配；找不到時會 fallback 到 substring（顯示時會標示）。
3   想精準找 backpressure 直接打完整詞、或打 backpre。

L1 講 capability + L2 講 fallback、合在一起 = 完整的 mental model。

原則 3：可 trace 「結果怎麼來的」

User 能（不必、但能）看到結果的來源層：

• Search result 標 “prefix match” / “substring fallback”
• API response 標 from_cache: true 或 freshness_seconds: 30
• LLM response 標「來自 RAG retrieval / 來自 base model knowledge」

可 trace ≠ 強制顯示、是「想知道時可以知道」。預設可隱藏、debug / 進階 user 可展開。

反模式

何時 conflicting / redundant 是合理的

少數情境：

三類共通：訊號重複的成本 < 訊號漏掉的成本。其他情境追求 layered consistent。

跟其他抽象層原則的關係

套用到當前 search planning case

D + C1 疊加 case：

Bad（conflicting）：

1D hint: "搜尋為前綴匹配、找 backpressure 請打 backpre"
2C1 fallback: 打 "pre" 自動 substring 找到 backpressure、跟其他 prefix result 混排

Good（layered consistent）：

1D hint: "搜尋優先前綴匹配。找不到時自動 fallback 到 substring（會標示）。"
2C1 fallback UI:
3  - Prefix matches（標準）：[後跟前綴匹配 results]
4  - Substring matches（fallback）：[標示後跟 fallback results]

User 看到的：

• 打 “pre” → 立刻看到 prefix matches（如「prefetch」）
• 同頁標 “Substring fallback” 段、列「backpressure」等 substring 命中
• 看 hint 也知道為什麼有兩段

訊號對齊、user mental model 完整。

判讀徵兆

核心：L1 + L2 疊加不是「兩個獨立 layer 各自做事」、是一個 capability gap 上的兩個訊號。訊號要對齊、否則使用者收到的 mental model 是 broken。Silent fallback 看起來簡潔、實際是 false confidence。