1document.querySelector('.target');
2document.querySelectorAll('.target');

從整個頁面找元素、不指定 ancestor scope。

這個做法存在的價值

簡潔。一行就能取到目標、不需要先建立元件根變數。在「我只想快速確認某個元素在不在 / 取它的某個屬性」這類情境下、寫一個 import shell 變數 + null check 是過度工程。

適合的情境

核心特徵：這段程式不會在多元件 / 動態 DOM 環境長期存活。

不適合的情境

安靜失敗是最危險的特徵 — 不報錯、操作了錯元素、bug 表現遠離 root cause。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法、document query 是其中之一：

選擇順序：production 客製預設用「元件根變數」、原型 / 探索 / 一次性才用 document query。

邊界：什麼時候 document query 在 production 也合理

幾個常見的 production 例外：

 1// 例外 1：操作的目標就是「全頁面唯一單例」
 2document.body.classList.add('page-search');
 3document.documentElement.setAttribute('data-theme', 'dark');
 4
 5// 例外 2：跨元件邊界的元素（不在任何元件內）
 6var slot = document.querySelector('.search-filter-slot');
 7// (slot 是 main 的子節點、不在 search-shell 內、不能從 shell 找)
 8
 9// 例外 3：頁面層級的 meta 元素
10document.querySelector('meta[name="description"]');

例外都共享一個特徵：目標元素本質上就在「頁面層級」、不是任何元件的內部。

不是例外的場景、即使「當前頁面只有一個」、也用元件根變數 — 預防未來擴展。

判讀徵兆

核心原則：document query 不是反模式、是有適用範圍的工具。判斷「這段程式預期活多久」 — 短命用 document、長命用元件根。

1var shell = document.querySelector('.search-shell');
2if (!shell) return;
3
4var input  = shell.querySelector('.pagefind-ui__search-input');
5var drawer = shell.querySelector('.pagefind-ui__drawer');
6// ... 之後所有 query 都從 shell 開始

把元件根 query 一次存變數、所有後續 query 都從這個變數開始。

這個做法存在的價值

把 selector 的作用範圍從「全頁面」收斂到「元件內部」。即使未來頁面其他地方出現同名元素、跟我無關。成本只多一行 query + 一個 null check、防護收益大。

適合的情境

核心特徵：寫的時候只有一個元件、但希望程式碼能容忍未來頁面結構變動。

不適合的情境

設計細節

Null check 的時機

1var shell = document.querySelector('.search-shell');
2if (!shell) return;

頁面可能沒有 shell（不是搜尋頁），所有後續 query 都會 null pointer。提早 return 比後續一連串 if (drawer) 乾淨。

等同於宣告：「這段程式只在有 shell 的頁面執行」。

變數的宣告位置

避免全域變數 — window.shell 容易跟其他 script 撞。

等待 shell mount 的處理

如果 script 跑得太早（shell 還沒 mount），shell 會是 null：

 1// 解法 1：等 DOMContentLoaded
 2document.addEventListener('DOMContentLoaded', function () {
 3  var shell = document.querySelector('.search-shell');
 4  if (!shell) return;
 5  // ...
 6});
 7
 8// 解法 2：MutationObserver 等 mount
 9var bootstrap = new MutationObserver(function () {
10  var shell = document.querySelector('.search-shell');
11  if (!shell) return;
12  bootstrap.disconnect();
13  // ...
14});
15bootstrap.observe(document.body, { childList: true, subtree: true });

選擇取決於 shell 是 server-render 還是 client-render：server-render 用 DOMContentLoaded、client-render 用 observer。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法：

預設用本卡片、需要多實例升級到「起點當參數」、需要動態升級到「closest」。

應用範例：完整 setup

 1function init() {
 2  var shell = document.querySelector('.search-shell');
 3  if (!shell) return;
 4
 5  var ui     = shell.querySelector('.pagefind-ui');
 6  var input  = shell.querySelector('.pagefind-ui__search-input');
 7  var drawer = shell.querySelector('.pagefind-ui__drawer');
 8
 9  if (!input || !drawer) return;  // 元件未完整 mount
10
11  syncScopeHeight(shell.querySelector('.search-scope'));
12  setupFilterSlotSwap(shell, drawer);
13  setupScopeFilter(shell, input);
14}
15
16document.addEventListener('DOMContentLoaded', init);

shell 取一次、各 setup 函式從 shell 派生需要的子節點。

判讀徵兆

核心原則：本 pattern 是 production 客製的預設、不是極致最佳化。當當前情境不複雜（一個元件、靜態 mount）、用本 pattern 即可；情境變複雜時再升級到對應做法。

1function setupSearchShell(shell) {
2  var ui     = shell.querySelector('.pagefind-ui');
3  var input  = shell.querySelector('.pagefind-ui__search-input');
4  var drawer = shell.querySelector('.pagefind-ui__drawer');
5  // ... 所有 query 從參數 shell 開始
6}
7
8document.querySelectorAll('.search-shell').forEach(setupSearchShell);

元件根不在函式內 query、由呼叫者傳入。函式支援任意數量的元件實例。

這個做法存在的價值

兩件事：

1. 多實例支援免費：forEach(setup) 自動處理多個 shell
2. 純函式特性：函式行為只依賴參數、不依賴外部狀態 — 可單獨測試、可重用、副作用集中

跟元件根變數的關鍵差異：那個 pattern 假設「shell 唯一」、本 pattern 把這個假設外移到呼叫端、函式本身不假設。

適合的情境

核心特徵：把「shell 從哪來」這個責任明確交給呼叫端、函式自己不關心。

不適合的情境

設計細節

函式簽名的設計

 1// 好：shell 是必填參數
 2function setupSearchShell(shell) { ... }
 3
 4// 較差：依賴外部變數
 5var shell;  // module scope
 6function setupSearchShell() {
 7  // 用了外部 shell
 8}
 9
10// 更差：mega object
11function setupSearchShell(allElements) {
12  var shell = allElements.shell;  // 不知道實際依賴什麼
13  // ...
14}

明確參數 = 明確依賴 = 容易測試、容易讀。

內部子函式也接受 shell

 1function setupSearchShell(shell) {
 2  syncScopeHeight(shell);
 3  setupFilterSlot(shell);
 4  setupScopeFilter(shell);
 5}
 6
 7function syncScopeHeight(shell) {
 8  var scope = shell.querySelector('.search-scope');
 9  // ...
10}

每層都明確接受 shell — 不依賴外層 closure。整套函式族都是純函式。

預先抓子節點 vs 每次重 query

 1// 方式 A：函式入口抓所有子節點
 2function setupSearchShell(shell) {
 3  var els = {
 4    ui:     shell.querySelector('.pagefind-ui'),
 5    input:  shell.querySelector('.pagefind-ui__search-input'),
 6    drawer: shell.querySelector('.pagefind-ui__drawer'),
 7  };
 8  // 後續用 els.ui / els.input / els.drawer
 9}
10
11// 方式 B：各子函式自己 query
12function setupSearchShell(shell) {
13  syncScopeHeight(shell);  // 內部自己 querySelector
14  setupFilterSlot(shell);
15}

A 比較有效率（只 query 一次）、B 比較解耦（子函式自包含）。選 B 為預設、效能瓶頸時才考慮 A。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法：

升級階梯：document → 元件根變數 → 起點當參數 → closest。複雜度遞增、能處理的情境也遞增。

應用範例：多實例 setup

1// 頁面有 N 個 search-shell（例如多語版面切換）
2document.querySelectorAll('.search-shell').forEach(setupSearchShell);
3
4// 跑完之後：每個 shell 各自獨立 setup、互不干擾

當前頁只一個 shell、上面這行也適用 —forEach 對 1 個元素跑一次、跟 hardcode 單例沒差。做了多實例設計、未來不需要重寫。

應用範例：單元測試

純函式可以對 mock DOM 測試：

1test('setupSearchShell 把 filter 移到 sidebar', function () {
2  var shell = createMockShell();  // 建立測試用 DOM
3  setupSearchShell(shell);
4
5  expect(shell.querySelector('.search-filter-slot').children.length).toBe(1);
6});

不需要全頁面 mount、只需要 mock 一個 shell — 測試成本低。

判讀徵兆

核心原則：本 pattern 把「我從哪取得 shell」的答案從函式內搬到呼叫端 — 換到「函式可重用」+「測試容易」+「多實例免費」三個收益、代價是函式簽名多一個參數。當前情境只一個實例也適用、未來擴展不需重寫。

1document.addEventListener('click', function (e) {
2  var shell = e.target.closest('.search-shell');
3  if (!shell) return;
4  // 在這個 shell 內處理
5  handleSearchClick(shell, e);
6});

不在初始化時綁定 listener、而是頁面層級委派事件、事件處理時從 e.target 反向找元件根。

這個做法存在的價值

把「找元件根」從「初始化時綁定」延後到「事件發生時動態判斷」 — 換到三個能力：

1. 元件動態增減免處理：新加的元件不需要重新綁 listener
2. 多實例不需要 forEach setup：所有實例共用一個 listener
3. 記憶體效率：N 個元件只綁 1 個 listener、不是 N 個

代價是事件處理邏輯多一層（每次都要 closest 反向找）。

適合的情境

核心特徵：元件的 mount 時機 / 數量 runtime 才知道、不是初始化時固定。

不適合的情境

設計細節

Closest 失敗的處理

1document.addEventListener('click', function (e) {
2  var shell = e.target.closest('.search-shell');
3  if (!shell) return;  // 點擊不在任何 shell 內
4  // ...
5});

closest 找不到時回 null、提早 return 是必要防護。沒這個 check 會在頁面其他地方點擊時報錯。

從 closest 結果再往下 query

1var shell = e.target.closest('.search-shell');
2var input = shell.querySelector('.pagefind-ui__search-input');

closest 找到 shell 後、可以從 shell 往下 query 同元件內的其他元素 — 這是「事件 + closest + 局部 query」的組合。

事件類型的選擇

注意 focus / blur 不會 bubble — 事件委派要用 focusin / focusout。

委派的根節點選擇

1// 選項 1：document（最寬）
2document.addEventListener('click', handler);
3
4// 選項 2：特定容器（縮範圍）
5var pageContainer = document.querySelector('main');
6pageContainer.addEventListener('click', handler);

縮範圍的好處是「跟其他頁面區域的 listener 不互相干擾」。預設用 document、有干擾風險才縮。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法：

複雜度遞增、能處理的動態程度也遞增。最動態的場景才用本 pattern。

應用範例：跨多 shell 的 scope filter

 1function setupGlobalScopeFilter() {
 2  document.addEventListener('change', function (e) {
 3    var shell = e.target.closest('.search-shell');
 4    if (!shell) return;
 5
 6    var scope = e.target.closest('.search-scope');
 7    if (!scope) return;  // 不是 scope 控制的 change
 8
 9    applyScope(shell, scope);
10  });
11}
12setupGlobalScopeFilter();

一個 listener 處理所有 shell 的 scope 變動 — 不論 shell 是初始 mount 的、還是 runtime 注入的。

應用範例：與 起點當參數 組合

 1// 初始化階段：對已存在的 shell 做 setup
 2document.querySelectorAll('.search-shell').forEach(setupSearchShell);
 3
 4// 事件階段：用 closest 處理可能新加的 shell
 5document.addEventListener('click', function (e) {
 6  var shell = e.target.closest('.search-shell');
 7  if (!shell) return;
 8  // 處理事件、不論 shell 是初始的還是後加的
 9});
10
11// MutationObserver：捕捉新加的 shell 做 setup
12new MutationObserver(function (mutations) {
13  mutations.forEach(function (m) {
14    m.addedNodes.forEach(function (node) {
15      if (node.matches && node.matches('.search-shell')) {
16        setupSearchShell(node);
17      }
18    });
19  });
20}).observe(document.body, { childList: true, subtree: true });

三個 pattern 組合：「靜態 setup」+「事件動態」+「mount 時 setup」 — 各 pattern 補不同時間點的需求。

判讀徵兆

核心原則：closest 反向找根把「定位元件」從綁定時延後到事件發生時 — 換到動態能力、付出的是事件處理多一層判斷。靜態場景用更簡單的做法、動態場景才升級到本 pattern。

1shell.querySelectorAll('.pagefind-ui__result:not([data-scoped])').forEach(function (el) {
2  // ... 處理
3  el.setAttribute('data-scoped', 'true');
4});

apply 函式入口用 :not([data-x]) 過濾掉已處理元素、處理完後設 attribute 標記。下次 apply 被觸發時、已處理的元素不會被命中。

這個做法存在的價值

把「保證只處理一次」的責任從呼叫端（要記得只呼叫一次）轉到元素本身（看自己有沒有被處理過）。

apply 函式可能被多個源觸發：

• 初始化時呼叫
• MutationObserver 偵測到變動觸發
• 使用者事件觸發
• Framework 重繪後重新呼叫

任一個源多呼叫就重複處理 — 無法靠呼叫端紀律避免。Idempotency 標記讓 apply 自己防護。

適合的情境

核心特徵：元素的 attribute 跟著元素 DOM 生命週期、元素移除時標記自動消失。

不適合的情境

設計細節

Attribute 命名規範

1// 好：明確 namespace + 用途
2el.setAttribute('data-search-scoped', 'true');
3el.setAttribute('data-myapp-processed', 'true');
4
5// 較差：通用名、容易跟其他程式撞
6el.setAttribute('data-processed', 'true');
7el.setAttribute('processed', 'true');  // 不是 data-* 開頭、可能不被 HTML spec 接受

預設用 data-{appname}-{purpose} 格式 — 即使引入第三方 library 加 attribute、也不會撞名。

Attribute 值的選擇

 1// 用法 1：固定 'true'（最簡）
 2el.setAttribute('data-scoped', 'true');
 3
 4// 用法 2：紀錄處理時間 / 版本（debug 友善）
 5el.setAttribute('data-scoped', String(Date.now()));
 6el.setAttribute('data-scoped', 'v2');
 7
 8// 用法 3：boolean attribute（無值）
 9el.setAttribute('data-scoped', '');
10// CSS 用 [data-scoped] 即可選中

預設用 'true'、debug 困難時改 timestamp 看處理順序。

跟 framework 重繪共處

Svelte / React / Vue 重繪元素時、自家 attribute 通常會被保留（framework 只管自己的 attribute）— 但有例外：

核心觀察：自家 attribute 跟著元素走 — 元素還在就有、元素被換就沒。這是「正確」行為、不是 bug。

例外：framework 主動清自家 attribute

少數 framework 會 strict 清非預期的 attribute（例如某些 Web Component lib）。檢查方式：

1el.setAttribute('data-scoped', 'true');
2// ... 等 framework patch 一次後
3console.log(el.getAttribute('data-scoped'));  // 還在嗎？

如果消失、改用 WeakMap 紀錄。

跟其他 idempotency 做法的關係

#14 Selector 精準度 的「過濾」維度有三種做法：

預設用本卡片、第三方 library / framework 衝突情境升級到 WeakMap。

應用範例：完整 apply

 1function apply(shell) {
 2  var newResults = shell.querySelectorAll(
 3    '.pagefind-ui__result:not([data-search-scoped])'
 4  );
 5
 6  newResults.forEach(function (el) {
 7    bindClickHandler(el);
 8    addCustomBadge(el);
 9    el.setAttribute('data-search-scoped', 'true');
10  });
11}
12
13// 多源觸發都安全
14init.addEventListener('click', () => apply(shell));
15observer.observe(shell, ...);  // 觀察到變動觸發 apply
16apply(shell);  // 初始化時跑一次

三個觸發點任一個多跑、:not([data-search-scoped]) 都會過濾掉已處理元素。

應用範例：多維度標記

 1// 三個獨立 idempotency 維度、各自 attribute
 2el.setAttribute('data-search-scoped', 'true');     // scope filter 處理過
 3el.setAttribute('data-search-bound', 'true');      // event listener 綁過
 4el.setAttribute('data-search-decorated', 'true');  // 視覺裝飾加過
 5
 6// 各 apply 函式只看自己的 attribute
 7function applyScope(shell) {
 8  shell.querySelectorAll('.x:not([data-search-scoped])').forEach(...)
 9}
10function applyBindings(shell) {
11  shell.querySelectorAll('.x:not([data-search-bound])').forEach(...)
12}

每個 idempotency 維度獨立 — 互相不干擾。

判讀徵兆

核心原則：把 idempotency 責任從呼叫端搬到元素本身、attribute 是「便宜可見的旗標」。Production apply 預設用本 pattern、特殊情境（library / framework 衝突）才升級到 WeakMap。

1var processed = new WeakMap();
2
3shell.querySelectorAll('.pagefind-ui__result').forEach(function (el) {
4  if (processed.has(el)) return;
5  // ... 處理
6  processed.set(el, true);
7});

把「已處理」狀態紀錄在 JS 的 WeakMap 裡、不寫到 DOM 上。WeakMap key 是元素本身、元素被 GC 時自動清理。

這個做法存在的價值

兩件事 DOM attribute 標記 做不到：

1. 不污染 DOM：使用者 DOM 不會被加自家 attribute、適合第三方 library
2. 跟 framework 完全解耦：framework 怎麼操作 DOM 都不影響 WeakMap 紀錄

代價是 debug 不便（看不到狀態）、紀錄跟 JS context 綁定（換頁就消失）。

適合的情境

核心特徵：紀錄獨立於 DOM 之外、跟 JS 物件 lifetime 綁定。

不適合的情境

設計細節

為什麼用 WeakMap 不用 Map / Set

1// WeakMap：key 是元素、元素被 GC 時 entry 自動消失
2var processedW = new WeakMap();
3processedW.set(el, true);
4// el 從 DOM 移除 + 沒其他 reference → GC → WeakMap entry 消失
5
6// Map / Set：強引用、阻止 GC
7var processedS = new Set();
8processedS.add(el);
9// el 從 DOM 移除、但 Set 還抓著 → 永久 leak

DOM 元素可能動態移除（filter、SPA 路由切換、framework 重繪）— Map / Set 會造成 memory leak。處理 DOM 元素 idempotency 預設用 WeakMap。

Value 的設計

 1// 用法 1：純 boolean（最簡）
 2processed.set(el, true);
 3
 4// 用法 2：紀錄處理版本（升級時偵測 stale 紀錄）
 5processed.set(el, { version: 2, time: Date.now() });
 6if (processed.has(el) && processed.get(el).version === currentVersion) return;
 7
 8// 用法 3：紀錄相關 metadata（避免重複查詢）
 9processed.set(el, {
10  bindingsId: registerListener(el),
11  initialClass: el.className,
12});

WeakMap value 可以儲任何資料 — 比 attribute（只能存字串）更彈性。

Debug 替代方案

attribute 標記可以在 devtools inspector 直接看；WeakMap 看不到。debug 時的替代：

1// 開發模式同步寫一份 attribute（production build 時拿掉）
2function markProcessed(el) {
3  processed.set(el, true);
4  if (DEV_MODE) {
5    el.setAttribute('data-debug-processed', 'true');
6  }
7}

或暴露到 console：

1window.__debug_processed = processed;
2// console: __debug_processed.has($0)  // 檢查當前選中元素

這些都是 workaround、不如 attribute 標記直觀。選 WeakMap 的人通常已經接受這個 debug 成本。

Reset 紀錄

1// WeakMap 整批 reset
2processed = new WeakMap();
3
4// 對比 attribute 整批 reset 要遍歷
5shell.querySelectorAll('[data-scoped]').forEach(el => {
6  el.removeAttribute('data-scoped');
7});

需要週期性 reset（例如 user 切換 mode、所有元素該重新處理）— WeakMap 一行解決、attribute 要遍歷。

跟其他 idempotency 做法的關係

#14 Selector 精準度 的「過濾」維度有三種做法：

選擇順序：自家 application → attribute；library / framework 衝突 → WeakMap；反模式不選。

應用範例：library 設計

 1// 第三方 library export 的 init 函式
 2function initSearchEnhancement(shell) {
 3  var processed = new WeakMap();
 4
 5  function apply() {
 6    shell.querySelectorAll('.search-result').forEach(function (el) {
 7      if (processed.has(el)) return;
 8      enhanceResult(el);
 9      processed.set(el, true);
10    });
11  }
12
13  apply();
14  new MutationObserver(apply).observe(shell, { childList: true, subtree: true });
15}
16
17// 使用者：
18initSearchEnhancement(document.querySelector('.my-search'));
19// 不會在使用者 DOM 上加任何 data-* attribute

使用者 DOM 完全乾淨、library 行為內聚。

應用範例：版本化處理

 1var processed = new WeakMap();
 2var CURRENT_VERSION = 3;
 3
 4function apply() {
 5  shell.querySelectorAll('.x').forEach(function (el) {
 6    var record = processed.get(el);
 7    if (record && record.version === CURRENT_VERSION) return;
 8
 9    // 升級到新版本（可能需要清舊綁定）
10    if (record) cleanup(el, record);
11    enhance(el, CURRENT_VERSION);
12    processed.set(el, { version: CURRENT_VERSION, time: Date.now() });
13  });
14}

版本變動時 — 不需要遍歷 DOM 清舊 attribute、直接用 WeakMap value 比對。

判讀徵兆

核心原則：WeakMap idempotency 是 attribute 標記的「不污染 DOM 替代品」 — 在 library / framework 衝突情境必要、在自家 application 通常用 attribute 即可。GC 自動清理是 WeakMap 的特性、預設不用 Map / Set 是因為它們會 memory leak。

 1var mql = window.matchMedia('(min-width: 1400px)');
 2function place() {
 3  if (mql.matches) {
 4    desktopSlot.appendChild(filter);
 5  } else {
 6    drawer.insertBefore(filter, drawer.firstChild);
 7  }
 8}
 9mql.addEventListener('change', place);
10place();  // 初始化

同一個 DOM 節點在兩個 slot 之間搬移、不複製成兩份。

這個做法存在的價值

Stateful UI（內含 checkbox 勾選、表單值、scroll 位置等 state）跨兩個顯示位置切換時、複製兩份會造成 state 分歧 — 使用者在 desktop 勾的 filter、切到 mobile 看不到勾選狀態。

搬同一份節點 = state 永遠跟著節點走 = 切換無感。

適合的情境

核心特徵：UI 內含 state、兩個位置展示的是「同一個邏輯單位」、不是「兩個獨立元件」。

不適合的情境

設計細節

appendChild 是搬遷、不是複製

1parentA.appendChild(node);  // node 從原位置消失、出現在 parentA

DOM API 的 appendChild / insertBefore 是 move、不是 copy — 同一個節點不能同時存在於多個位置。這個特性正是搬遷 pattern 的基礎。

初始放在哪

1<!-- 預設位置（mobile / fallback）-->
2<div class="pagefind-ui">
3  <div class="drawer">
4    <div class="filter-panel">...</div>  <!-- 初始在這 -->
5  </div>
6</div>
7
8<!-- 桌面 slot（空、等待搬入）-->
9<aside class="desktop-filter-slot"></aside>

預設放在 fallback 位置 — 當 JS 失敗時仍可見。

跨 slot 切換的時機

matchMedia event 是 viewport 跨過 breakpoint 的瞬間：

1var mql = window.matchMedia('(min-width: 1400px)');
2mql.addEventListener('change', place);
3place();  // 初始也跑一次

不要用 resize event — 太頻繁、會在 breakpoint 邊界震盪。matchMedia 只在 cross 的瞬間觸發。

搬遷時 framework 的 reactivity

如果搬遷的節點是 framework 管的（如 Pagefind 的 svelte 元件）— 整節點搬通常安全、framework 在下次 patch 時看到節點還在、繼續更新內部。

詳細安全規則由 #13 JS 操作 framework 元件：邊界辨識與安全規則 處理。

Focus 跟著搬

搬遷可能讓鍵盤 focus 暫時失去（視瀏覽器）— 加 save/restore：

1function place() {
2  var activeBefore = document.activeElement;
3  if (mql.matches) desktopSlot.appendChild(filter);
4  else drawer.insertBefore(filter, drawer.firstChild);
5  if (activeBefore && filter.contains(activeBefore)) {
6    activeBefore.focus();
7  }
8}

詳細處理由 #37 動態 DOM 移動時的 focus 管理 處理。

設計取捨：兩個 slot 的 stateful UI 共用

四種做法、各自機會成本不同。預設選 A（搬同節點）、其他做法在特定情境合理。

A：搬同一節點（這個專案的預設）

• 機制：matchMedia + appendChild 在兩 slot 間搬同一份節點
• 選 A 的理由：state 跟著節點、切換無感、不需要 sync 邏輯
• 適合：stateful UI、需要在兩個位置展示同樣內容
• 代價：搬遷 callback 在 viewport 跨 breakpoint 時觸發、需要處理 focus / 動畫
• 詳細：本卡片

B：CSS-only 雙顯示 + display 切換

• 機制：兩個位置都放同一份節點 (寫兩遍 HTML)、用 @media + display: none 切換顯示
• 跟 A 的取捨：B 純 CSS 簡單、A 需要 JS；但 B 對 stateful UI 失敗（兩份 state 各自獨立）
• B 比 A 好的情境：UI 純 stateless（純圖示）、純 CSS 解就夠

C：CSS-only + JS 同步 state

• 機制：兩份節點 + JS 監聽 state 變動同步
• 跟 A 的取捨：C 比 B 解 state 問題、但同步邏輯複雜（雙向更新、避免循環）
• C 比 A 好的情境：兩個位置的 UI 視覺需要差異（不只是位置不同）

D：JS 完全重建 UI

• 機制：viewport 變動時拆掉舊 UI、在新位置重建一份
• 成本特別高的原因：state 在重建時遺失、UI 閃爍、輸入中斷
• D 才合理的情境：UI 是 stateless 的、且重建成本低

跟其他 pattern 的關係

#14 Selector 精準度 的「起點」維度有四種做法、本卡片是「跨 slot 搬遷」這個專門情境的補充：

應用範例：跨 viewport filter 切換

 1function setupResponsiveFilter(shell, breakpoint) {
 2  var filter = shell.querySelector('.pagefind-ui__filter-panel');
 3  var drawer = shell.querySelector('.pagefind-ui__drawer');
 4  var desktopSlot = document.querySelector('.search-filter-slot');
 5
 6  if (!filter || !drawer || !desktopSlot) return;
 7
 8  var mql = window.matchMedia('(min-width: ' + breakpoint + 'px)');
 9
10  function place() {
11    var activeBefore = document.activeElement;
12
13    if (mql.matches) {
14      desktopSlot.appendChild(filter);
15    } else {
16      drawer.insertBefore(filter, drawer.firstChild);
17    }
18
19    if (activeBefore && filter.contains(activeBefore)) {
20      activeBefore.focus();
21    }
22  }
23
24  place();
25  mql.addEventListener('change', place);
26}

完整 pattern：取元件根 + matchMedia + 搬遷 + focus 處理。

判讀徵兆

核心原則：Stateful UI 的兩個展示位置共用同一份節點、state 自然跟著走 — 比「兩份節點 + sync 邏輯」乾淨。複製兩份是「state 來源從一變二」的隱形多源（違反 #44 SSoT）。

抓一批 → filter → 不夠就再抓 → 湊滿 N 個 match 或 source 結束。

對應 #59 Filter × Source 合成策略 的策略 B。

何時用、何時不用

用

• Source 不支援 server-side filter（不能用策略 A）
• 不能控 build pipeline 重 index（不能用策略 C）
• Match 密度可預期、不會稀疏到要拉光整個 dataset
• 使用者期望「filter 後自動湊夠 N 個」、不要手動續抓

不用

• Source 支援 server-side filter（直接用策略 A）
• Match 稀疏、可能拉光整個 dataset 才湊到 N（換 D 誠實 UX）
• Source cardinality 大（10 萬筆）、不能拉太多次

必要元件

元件 1：Quota 跟上限

1const TARGET = 10;       // 期望湊滿的 match 數
2const MAX_BATCHES = 20;  // 最多續抓次數（保護）
3const MAX_TIME_MS = 5000; // 最大時間（保護）

沒有上限 = 稀疏時拉爆。兩個上限缺一不可。

元件 2：Loop with break conditions

 1async function fetchUntilQuota(matches, target = TARGET) {
 2  const collected = [];
 3  const start = Date.now();
 4  let batchCount = 0;
 5
 6  while (
 7    collected.length < target &&
 8    hasMore() &&
 9    batchCount < MAX_BATCHES &&
10    Date.now() - start < MAX_TIME_MS
11  ) {
12    const batch = await fetchNext();
13    collected.push(...batch.filter(matches));
14    batchCount++;
15  }
16
17  return {
18    collected,
19    reachedQuota: collected.length >= target,
20    exhaustedSource: !hasMore(),
21    hitLimit: batchCount >= MAX_BATCHES || Date.now() - start >= MAX_TIME_MS,
22  };
23}

返回值含三個 flag、UI 用來判斷該顯示哪個狀態（湊滿 / 抓完無更多 / 撞到上限）。

元件 3：可中斷

 1async function fetchUntilQuota(matches, target, signal) {
 2  // ...
 3  while (...) {
 4    if (signal?.aborted) throw new DOMException('aborted', 'AbortError');
 5    const batch = await fetchNext({ signal });
 6    // ...
 7  }
 8}
 9
10// 使用
11const ctrl = new AbortController();
12input.addEventListener('input', () => {
13  ctrl.abort();
14  ctrl = new AbortController();
15  fetchUntilQuota(matches, 10, ctrl.signal);
16});

使用者改 query / filter 時能立刻取消舊的續抓。沒有可中斷 = 競態 bug（舊 query 的結果晚到、覆蓋新 query 的）。

UX 配套

載入中顯示進度

1<div class="loading">已掃 <strong>24</strong> 筆 / 已命中 <strong>3 / 10</strong></div>

不顯示進度 = 使用者不知道是在等還是卡住。

結束時顯示原因

不區分原因 = 使用者不知道為什麼停（同 #57 三狀態問題）。

反例

反例 1：沒上限

1while (collected.length < target && hasMore()) {
2  collected.push(...(await fetchNext()).filter(matches));
3}
4// 稀疏 match → 拉光整個 source

反例 2：沒 abort signal

1input.addEventListener('input', async () => {
2  const r = await fetchUntilQuota(matches);
3  render(r);  // 舊 query 的結果可能覆蓋新 query
4});

反例 3：每批序列化等

1for (let i = 0; i < MAX; i++) {
2  const batch = await fetchNext();  // 序列、慢
3  // ...
4}

如果 source 支援平行 fetch（多個 page 同時抓） → 改成平行更快：

1const batches = await Promise.all([fetch(0), fetch(1), fetch(2)]);

但平行有 over-fetch 風險（湊滿後其他批白抓） — 適合 match 密度高的情境。

跟其他 Pattern 的關係

• 跟 #61 Pattern：推進 query（待補）：A 是最優、B 是 source 不支援時的退路
• 跟 #62 Pattern：誠實進度 UX（待補）：B 撞到上限後 fallback 到誠實 UX

判讀徵兆

核心原則：自動續抓的價值在「使用者透明」、但成本是「上限保護必要」。沒上限的 B 比 silent post-filter 更糟（會拉爆）。

把 filter 變成 source 的 query 參數、source 端就回符合的、client 不 post-filter。

對應 #59 Filter × Source 合成策略 的策略 A。

何時用、何時不用

用

• Source 支援該 filter 條件（已索引、能在 query 表達）
• 想避免任何 client-side post-filter
• 想避免層錯位（見 #55）

不用

• Source 不支援（pagefind 對 title-only 沒 native 支援）
• 條件需要 client-side 計算（依 viewport / 隨機抽樣）
• 推進 query 後 cardinality 仍大、還是要 paginate（這時 A + B 並用）

推進的層次

選哪一層 = source 的 capabilities 決定。

評估 Source Capabilities

寫之前讀 source docs / API spec、列出：

不評估就寫 = 寫到一半發現 source 不支援、回頭走策略 B 或 C。

範例：Pagefind

支援的 filter

1// pagefind 已支援 filter（透過 _pagefind/filter.json）
2const r = await pagefind.search('keyword', {
3  filters: {
4    type: 'post',           // 支援
5    tag: { any: ['js', 'css'] }, // 支援多選
6  },
7});

不支援的 filter

1// pagefind 不支援「只搜 title」
2// 因為 pagefind 的 search 對 full-text、不分區
3const r = await pagefind.search('keyword', {
4  scope: 'title-only',  // 不存在（不支援）
5});

要解決：

• 方案 1：build 時用 data-pagefind-body 把 title 標成獨立 region、用 body filter（pagefind v1.1+）
• 方案 2：建兩個獨立 index（一個只 index title、一個只 index content） — 走策略 C
• 方案 3：放棄推進 query、用策略 B 自動續抓 + post-filter

跟原本 query 邏輯的並用

推進 filter 通常不取代原本 query、是「補上條件」：

1// 使用者輸入 query "css"、選 type=post
2const r = await pagefind.search('css', {  // query
3  filters: { type: 'post' },              // filter
4});
5// 兩個都進 source、source 算交集

Filter 跟 query 是不同維度：query 是「找什麼」、filter 是「在哪些範圍找」。

反例

反例 1：推進不完全、留 client-side post-filter 補

1const r = await pagefind.search(q, { filters: { type: 'post' } });
2const filtered = r.results.filter(x => x.title.includes(q));
3// ↑ 這行還是 #55 層錯位

如果 source 不支援 title-filter、不要用「半推進」 — 直接走策略 C 或 B。

反例 2：忽略 cost cap

1input.addEventListener('input', async () => {
2  // 每個鍵盤事件 fire 一個 search query
3  const r = await pagefind.search(input.value, { filters: ... });
4});
5// → query rate 100+/秒、撞 rate limit

加 debounce：

1let timer;
2input.addEventListener('input', () => {
3  clearTimeout(timer);
4  timer = setTimeout(() => pagefind.search(input.value, ...), 200);
5});

反例 3：客製欄位沒進 index、寫了 query 失效

1// 期望 filter 「閱讀時間 > 5 分鐘」
2const r = await pagefind.search(q, { filters: { readingTime: { gt: 5 } } });
3// → 但 build 時沒把 readingTime 進 filter index → filter 被忽略

預期 source 不支援 → 評估「是否值得加進 index」（成本 vs 使用率）。

跟其他 Pattern 的關係

• A 是最優 — 在 source capabilities 範圍內優先選
• A 不可行 → 評估 C（建獨立 index）
• C 也不可行 → 退到 B（自動續抓）
• 都不可行 → D（誠實 UX）

選擇順序：A → C → B → D。

判讀徵兆

核心原則：能推進 query 就推 — 沒層錯位、沒 silent 失敗、跟使用者意圖最近。但前提是 source 支援；不支援就要退到 B / C / D、不要做半推進。

當 filter 必然有層錯位、用「已掃 N / 命中 K / 共 M」三數字 + 「再掃一批」按鈕讓使用者看見掃描範圍、自己決定要不要續抓。

對應 #59 Filter × Source 合成策略 的策略 D。

何時用、何時不用

用

• Source 不支援 server-side filter（A 不可行）
• 不能或不值得重 index（C 不可行）
• Match 稀疏或不可預期、自動續抓（B）會拉爆
• 工程量限制、原型期 / MVP

不用

• Filter 是主要互動模式（使用者預期「自動全找完」）
• 三數字會讓 UI 太複雜
• 使用者完全不在意「掃描範圍」

三數字的語意

最少要顯示「已掃 N / 命中 K」 — 沒有 N 使用者不知道掃描範圍、沒有 K 使用者不知道有沒有命中。

「共 M」可選 — 有的 source（pagefind）會給 total count、有的（streaming）不會。

UI 模板

基本版

1<div class="filter-status">
2  已掃 <strong>24</strong> 筆 / 命中 <strong>3</strong> 筆
3  <button>再掃一批</button>
4</div>

含總數

1<div class="filter-status">
2  已掃 <strong>24</strong> / <strong>~150</strong> 筆 — 命中 <strong>3</strong>
3  <button>再掃一批</button>
4</div>

含結束狀態（呼應 #57 三狀態）

 1<!-- Loading -->
 2<div class="filter-status">掃描中... 已掃 <strong>24</strong> / 命中 <strong>3</strong></div>
 3
 4<!-- Partial（還可續） -->
 5<div class="filter-status">已掃 <strong>24</strong> / 命中 <strong>3</strong>
 6  <button>再掃一批</button>
 7</div>
 8
 9<!-- End（掃完） -->
10<div class="filter-status">已全部掃完、共命中 <strong>12</strong> 筆</div>
11
12<!-- Empty (filter) -->
13<div class="filter-status">已掃 <strong>24</strong>、沒有命中
14  <button>再掃一批</button> 或 <a>清除 filter</a>
15</div>

進度更新時機

即時更新（每筆）

1for (const item of stream) {
2  scanned++;
3  if (matches(item)) {
4    matched++;
5    appendResult(item);
6  }
7  updateUI(scanned, matched);  // 每筆更新
8}

UX 順、但 DOM 操作頻繁、可能 jank。

批次更新（每批）

1const batch = await fetchNext();
2scanned += batch.length;
3const m = batch.filter(matches);
4matched += m.length;
5appendResults(m);
6updateUI(scanned, matched);  // 每批一次

DOM 操作少、但 UX 不夠順（一段時間沒動）。

推薦：每批 + 載入中 spinner

批次後更新數字、批次間顯示 spinner。最平衡。

跟自動續抓（B）的混合

可以做成「初始自動續抓 N 批、之後切誠實 UX」：

1async function searchWithFilter(query) {
2  // 初始自動續抓 3 批（湊一些結果）
3  await fetchUntilQuota(3, autoBatches: 3);
4
5  // 之後使用者手動點「再掃一批」
6  showHonestProgressUI();
7}

混合的好處：使用者一進來就有結果（不是空畫面）、之後續抓由使用者決定。

反例

反例 1：只顯示「命中 K」、不顯示「已掃 N」

1<div>找到 3 筆結果</div>

使用者不知道是從多少筆裡找的、不知道「再掃會不會有」。

反例 2：只顯示「共 M / N」進度條、沒分「已掃」「命中」

1<progress value="24" max="150"></progress>

進度條告訴使用者「load 進度」、但「load 進度 ≠ filter 進度」。沒命中時使用者不知道為什麼進度走了 24% 但畫面沒結果。

反例 3：「再掃一批」沒做

只顯示三數字、沒提供續抓 button — 使用者看到「已掃 24 沒命中」、不知道下一步。

跟 #57 三狀態的關係

誠實進度 UX 是 #57 Loading / Empty / End 三狀態的區分 在「filter + 分批」情境下的具體實作。三數字提供區分三狀態的訊號：

判讀徵兆

核心原則：誠實 UX 不是「lazy 解法」、是「sourcing 限制下的合理透明度」。給使用者三數字 + 行動選項、比假裝完美但 silent 失敗好。

跟 #19 覆寫深度的成本告知 同源：兩者都是「把實作的限制 / 代價攤給使用者、讓使用者參與決策」。差別在 #19 是「實作前告知工程成本」、本卡是「runtime 持續顯示掃描成本」 — 攤出來的位置不同、原則一致：silent 累積負擔是反模式。

Build time 為每種 filter mode 各建一份獨立 source / index、runtime 切換 mode 等於切 source。

對應 #59 Filter × Source 合成策略 的策略 C。

何時用、何時不用

用

• 能控 source 的 build pipeline（自家 build、不是第三方 API）
• Filter mode 數量有限且穩定（< 5 個、不會爆炸組合）
• 兩個（含以上）mode 都重要、流量大、值得獨立 index
• Source 的 query 引擎不支援該 filter（不能用 #61 推進 query）

不用

• Filter 維度多、組合會爆炸（5 維 × 各 5 選項 = 3125 種 index）
• Index 大小敏感（每份 index 都重複占空間）
• Build pipeline 無法控（外部 API、vendor service）
• Mode 不穩定、常常增刪

結構

Build pipeline

1# Pagefind 範例：兩份 index 各自掃不同 region
2pagefind --site public --output-subdir _pagefind-all
3pagefind --site public/title-only --output-subdir _pagefind-title
4
5# 或用 --root-selector 限定 source 範圍
6pagefind --site public --root-selector ".post-title" --output-subdir _pagefind-title

Runtime 切換

1const indexes = {
2  all: await import('/_pagefind-all/pagefind.js'),
3  title: await import('/_pagefind-title/pagefind.js'),
4};
5
6function search(query, mode) {
7  return indexes[mode].search(query);
8}

每個 mode 對應一份完整 index、search 結果直接是該 mode 的全集。沒有 post-filter、沒有層錯位。

多 index 的成本

通常 build / 儲存的成本 < 在 runtime 自動續抓（B）的累積請求成本。

跟 #59 策略並用

C 通常跟其他策略並用：

• C + 推進 query (A)：在每份 index 內、再用 query filter 細分（如 _pagefind-post.search('css', { filters: { tag: 'js' } })）
• C 切 mode + B 自動續抓：mode 切換無感、mode 內續抓也無感

反例

反例 1：Mode 組合爆炸

1# 5 維 × 各 5 選項 = 3125 份 index
2for type in post page tutorial faq doc; do
3  for tag in js css html ts py; do
4    for date in 2020 2021 2022 2023 2024; do
5      pagefind --filter "type=$type tag=$tag date=$date" --output-subdir _pagefind-$type-$tag-$date
6    done
7  done
8done

組合爆炸時不能用 C — 改用 A（推進 query）讓 source 一份就好。

反例 2：Mode 不穩定、常常增減

每加一個 mode、build pipeline 多一份、deploy 多一份。如果 mode 半年內會大改、不適合 C。

反例 3：Index 沒對齊 mode

1pagefind --site public --output-subdir _pagefind-title
2# build 完後沒過濾、其實 index 了 title + content 全部

如果只是改 output 路徑、沒改 index 範圍 → 兩份 index 內容一樣、白做。要用 --root-selector 或 data-pagefind-body 標記正確範圍。

跟其他 Pattern 的關係

選擇順序：A → C → B → D（見 #61）：

• A 不行（source 不支援該 filter） → 評估 C
• C 不行（mode 爆炸 / 不能控 build） → 退到 B
• B 不行（match 稀疏會爆） → 退到 D

C 是 A 的 build-time 模擬 — 用 build 時間換 runtime 體驗、跟使用者意圖完全對齊（每份 index = 該 mode 的全集）。

判讀徵兆

核心原則：C 用 build-time 換 runtime 體驗。前提是 mode 有限、可控、值得 — 否則退到 A 或 B。

當 filter 必然只在已載入子集上運作、用 UI 文字 / API contract / docstring 明確告訴呼叫者「範圍 = 已載入、不承諾全集」 — 不假裝是全集 filter。

對應 #59 Filter × Source 合成策略 的策略 E。

何時用、何時不用

用

• Source 不支援推進 query (A 不可行)
• 不能控 build pipeline (C 不可行)
• Match 稀疏、自動續抓會拉爆 (B 不可行)
• 工程量限制、做不了 #62 誠實 UX 的三數字
• 能接受「filter 範圍 = subset」這個語意縮小、但要使用者知道

不用

• Source 一次給完整 dataset（沒有 subset、不需要縮小）
• 使用者預期 filter 是「全集」、無法接受縮小
• 應用情境影響重大決策（finance、medical 等不能接受 silent 範圍縮小）

跟策略 D（誠實 UX）的差別

D 跟 E 都是「在 subset 上 filter」、差別在「怎麼告訴使用者」：

簡言之：D 是「持續顯示掃描範圍」、E 是「告訴一次、之後不再提」。

「明示」的具體做法

UI 明示

1<input type="search" placeholder="Filter loaded results...">
2<small class="hint">只在已載入的結果裡篩選。要看更多請先載入更多。</small>

「Filter loaded results」、「已載入的結果裡」、「載入更多」 — 三個 cue 讓使用者知道範圍。

API contract 明示

1/**
2 * Filter loaded results by predicate.
3 *
4 * NOTE: Operates on currently loaded subset only.
5 * Does NOT trigger fetch of un-loaded items. To filter the full
6 * dataset, use {@link searchAll} instead.
7 */
8function filterLoaded(predicate: (item: Item) => boolean): Item[];

JSDoc / TSDoc 把語意寫進 API、IDE 提示能看到。

Docstring / README 明示

1## Filter behavior
2
3`filter()` only operates on results currently loaded in client.
4If the source uses pagination, items not yet loaded are NOT included.
5For full-dataset filtering, the source must support server-side filter.

文件級的明示、給開發者讀。

反例

反例 1：Silent 縮小（不告訴）

1<input type="search" placeholder="Filter results...">

「Filter results」沒指明「only loaded」 — 使用者預設是全集 filter、實際是 subset → 撞回 #55 層錯位 的語意縫。

反例 2：明示位置使用者看不到

1/**
2 * Filter results.
3 * Note: subset only.
4 */

使用者只看 UI、不讀 docstring — 「明示」要在使用者會看到的位置（UI hint、tooltip、行為描述）。

反例 3：明示但不清楚

1<small>限定範圍篩選</small>

「限定範圍」太抽象、沒說明是什麼範圍。要寫具體：「已載入的 N 筆內」「不包含尚未載入的」。

何時 E 升級到 D

當以下任一觸發、把 E 升級到 D（誠實 UX 三數字）：

E 是「成本低的退路」、不是長期解。當需求成熟、應該升級到 D / A / C。

跟其他 Pattern 的關係

• E 是策略順序 A → C → B → D 之外的「最後退路」
• E 跟 D 都是「在 subset 上做」、差別在告知方式
• E 跟 #55 silent 反模式的差別：E 是 explicit 縮小、silent 是 implicit 縮小

選擇順序（重申）：A 推進 → C 多 index → B 自動續抓 → D 誠實 UX → E 明示縮小 → silent（反模式）

判讀徵兆

核心原則：能接受語意縮小是可以、但必須明示。Silent 縮小（沒告知就 subset）等於 #55 層錯位、是反模式。E 的價值在「明示」這個動作、不在「subset」這個事實。

把決策交給使用者時、用三層格式：選項列表 + 每選項適配性 + 標出推薦 + 「想改？」開放。不要用「你覺得呢？」「你想怎麼做？」這類開放問。

開放問看似尊重、實際把「整理問題」的成本完全丟給使用者；推薦看似越權、實際讓使用者用「同意 / 反對」這個低成本動作完成決策。

為什麼開放問是反模式

開放問（“你想怎麼做？"）預設使用者已經完成這幾步：

1. 知道有哪些選項
2. 每個選項的成本與風險
3. 哪個選項最適合這個情境
4. 願意在當下重新整理思緒、把答案寫成完整指令

如果使用者已經做完這四步、他不會找你來問 — 他會直接下指令。會走到「需要決策」這個動作、通常是因為手上沒有完整 1-3、需要對方協助整理。

開放問 = 把「整理選項」這件事再丟回去、讓使用者重新做一遍你已經做過的功課。

三層格式的展開

Layer 1：選項列表

把所有合理選項列出（包含「不做」這個選項、如果合理）。每個選項一行、不超過 6 個 — 超過代表還沒篩選完、不該丟給使用者。

Layer 2：適配性 / 取捨

每個選項配一句「為什麼適合 / 不適合」 — 維度可以是成本、風險、相容性、複雜度等、依任務選 1-2 個維度。

Layer 3：標推薦 + 開放修改

明確說「我推薦 X、因為 Y」、然後加一句「想改成其他選項或調整、跟我說」。推薦不是越權、是把判斷攤開供質疑 — 使用者反對時知道反對什麼、同意時知道同意了什麼。

完整模板

1我看到三個方向：
2
3| 選項 | 適配性 | 取捨 |
4|---|---|---|
5| A 用 X 庫 | 既有依賴、易維護 | 功能受限、要小妥協 |
6| B 自己寫 | 完全控制 | 維護成本、邊界 case 要寫測試 |
7| C 不做 | 0 成本 | 使用者繼續手動 |
8
9我會選 **A**、因為這個 feature 不是核心、用既有依賴的維護負擔最低。想改成 B 或補充 C 沒問題、跟我說。

關鍵：使用者只需要回 “好”（同意）或 “改 B、原因是 ⋯⋯"（反對 + 提供新訊息）— 不必重新整理整個問題空間。

反模式對照

何時可以例外（純開放問是合理的）

四類共同點：整理選項這個工作不需要做、或不該由你做。其他情境都該套三層格式。

跟其他卡的關係

判讀徵兆

核心：決策呈現的目標不是「讓使用者參與」、是「讓使用者用最低成本參與」。低成本來自選項已經整理好、推薦已經攤開、只需要說「同意」或「改 X」。

寫到「我們還可以做什麼？」「下一步該往哪走？」「這次反省我們學到 X、Y、Z 哪個重要？」這類反省 / 改進方向問題、預設給複選（checkbox semantics、可選多項）。

執行類決策多半互斥（用 A 工具 vs B 工具）、反省類決策多半不互斥（思考 X + 思考 Y + 思考 Z 都做、互不干擾、合在一起反省深度更高）。把反省題用單選格式呈現 = 強迫使用者排序「思考的優先級」、結果通常 1 被選、2-N 被丟。

為什麼反省題不該單選

反省任務的 output 通常是「對問題的多面向理解 / 多條後續動作」、不是「一個結論」。多選項共存時：

• 思考 A 跟思考 B 互不干擾（同一個事件可從多角度反省）
• 動作 X 跟動作 Y 互補（補卡片 + 寫測試 + 改流程）
• 多角度疊加 → 反省深度更高、不是「一條最佳」就夠

把這種題目強制成單選、暗示「只能挑一個」、使用者就只挑一個。其他 N-1 個本來該做的、被結構性跳過 — 不是因為不重要、是因為呈現格式叫他這樣選。

反省 vs 執行：呈現格式的差異

關鍵：識別這個決策是「執行」還是「反省」、決定用哪種格式。

完整模板（反省題）

1這次經歷我們可以反省幾個方向：
2
31. 補卡片做分析（沉澱知識）
42. 補測試固化（避免回退）
53. 改流程 / 工具觸發（結構性對策）
64. 整理 case study 文章（對外輸出）
75. 重做某個決策（如果發現方向錯）
8
9這些**互不衝突、可以全做**。如果時間有限、我建議優先 1+2（沉澱 + 固化），3+4 下輪。要全做、跳過某幾個、或調整順序、跟我說。

關鍵差異 vs 執行類決策：

• 明示「互不衝突、可以全做」
• 推薦是「優先級」而非「選一個」
• 「全做」是合法選項 + 「跳過某幾個」也是合法選項

反模式

何時反省題該回退到單選

四類共通：互斥性是真實的、不是格式造成的。其他情境預設複選。

跟其他卡的關係

判讀徵兆

核心：執行決定是「選一個 path」、反省決定是「攤開多面向 + 標優先級」。預設互斥的格式（radio）套用到不互斥的場景（反省）= 結構性把多面向 collapse 成單點、丟失反省應有的深度。

把決策呈現成 yes/no 問句（“需要我繼續嗎？"、“要做嗎？"、“確認嗎？"）= 把使用者的回應空間壓縮到 1 bit。1 bit 不夠表達決策：使用者實際上有「改方向 / 延後 / 疊加 / 分批 / 反問」等合法選項、被 yes/no 結構藏起來。

這是 #79 五維度 collapse 的極致形態 — 預設窄格 + 預設立刻 + 預設單選 + 預設一次完成 + 預設單策略 + 再加一層 reduce 到 binary。最容易寫、最隱形、最常見。

為什麼 Yes/No 看起來合理但其實不夠

Yes/No 問句的隱含預設：

1. 使用者已經同意「我提出的方向」是對的 — 只剩執行 / 不執行
2. 沒有「微調」的中間態 — 想改一點點、要重起一輪 yes/no
3. 沒有「再多想想」 — 沒有 yes 也沒有 no 的時候被迫硬選
4. 沒有「順便加 X」 — 想疊加策略要破格自己提
5. 沒有「先做一半」 — 全做 vs 不做、沒有分批選項

實際上多數決策不是 1 bit 寬。當 agent 寫「要繼續嗎？」、使用者經常回答「等等、我想先 X」、「順便也做 Y」、「先做 A 不做 B」 — 這些回應全部都不是 yes 也不是 no、是對話越過 yes/no 結構自我修正。

修正成本由使用者承擔 = 反過來 #74 的問題（把整理成本丟回使用者）。

Yes/No 的常見變種

agent 容易寫的 yes/no 變種：

每個變種都把使用者推進「同意 / 不同意」的二元框、其他合法回應（改 / 延後 / 疊加 / 分批 / 反問澄清）需要使用者自己破格。

修法：把 Yes/No 翻成多維展開

把 binary 拆回多維：

Before（yes/no）

“我打算 ship D（UX hint）、需要我繼續嗎？”

After（五維展開）

接下來的選項：

選項	適配性	取捨
立刻 ship D	解眼前痛	不解根因
延後 D、先補 telemetry	等資料	推遲 1 週
跳過 D、做 B/C	結構 fix	風險高、要驗證
D + 寫測試固化	疊加	多寫 30 分鐘

我推薦 D + 寫測試固化（疊加）— 解眼前痛 + 防回退。改 / 延後 / 跳過都行、跟我說。

對照

明顯多花字、明顯讓使用者更容易做正確決策。

何時 Yes/No 真的合理

不是所有 yes/no 都該展開。合理的少數情境：

五類共通：多選空間已經消耗或不存在。其他情境都該展開。

跟其他卡的關係

判讀徵兆

核心：Yes/No 是 1 bit、決策空間是 N bit。用 yes/no 包裝不是「簡化」、是「藏掉維度」。簡化是少寫某個維度；藏掉維度是把多維壓成 1 bit、讓使用者破格才能表達。前者良性、後者不良。

寫文字（文章 / 註解 / doc / prompt / commit message）的 ROI 來自 N 輪不同 frame 的 re-read、不是單次「寫對」。每輪 catch 上一輪 frame miss 的東西：

每輪用「跟前一輪不同的眼睛」看同一份文字 — 才能 catch 不同層的問題。第 1 輪的 frame 不可能同時 catch 所有層（#82 字面 vs 行為的 ceiling）。

為什麼一輪寫不出全部維度

寫的時候 working memory 有限、必須 collapse 多個維度去專注其中之一：

• 生成 frame 在意 idea 完整 → 顧不上語氣
• 語氣 frame 在意「機會成本 vs 絕對主義」→ 顧不上 grep-ability
• grep frame 在意關鍵字前置 → 顧不上反例

要求一輪同時 catch 所有 = 認知超載。實際結果是「每個維度都做一半」。

多輪設計接受 working memory 限制、用 N 輪解 N 維。每輪只專注一個 frame、效率反而高。

五輪 review 的具體 checklist

輪 1：生成

• idea 從頭寫到尾、不停下來改
• 預期會有 typo、結構亂、語氣不對 — 不在這輪修
• 跑得到結尾比寫得漂亮重要

輪 2：對意圖（#67）

• 開頭一句講清「這段在說什麼」嗎？
• 有沒有 #67 的「便利驅動偏移」— 寫得順但其實偏題了？
• 段落順序是不是「好寫」決定的、不是「易讀」決定的？
• 有沒有「為了補滿格式」寫的廢段？

輪 3：機會成本語氣

• 跑 grep 抓「應該 / 必須 / 不行 / 不可以 / 正確的方式 / 唯一」這些絕對詞
• 每個絕對詞檢查：是物理 / 法律 / 安全事實嗎？不是的話翻成「在 X 情境下 A 較好、Y 情境下 B 較好」
• 反模式表的「為什麼不好」寫到「違反某個原則」、不寫「就是不對」

輪 4：Grep-ability / 命名

• 關鍵字在段首、不在段中
• 表格欄位用 grep 友善的分隔（: | →）
• 檔名 / slug 跟 title 對應、不要用流水號
• 命名能用單次 grep 命中、不需要語意推理

輪 5：反例 / 邊界

• 「何時不適用」段寫了嗎？
• 反模式表給「為什麼不好 + 修法」嗎、還是只給警告？
• 跨卡 cross-link 補了嗎？
• 有沒有 over-claim、把「在多數情境下」說成「總是」？

套用到不同 output 類型

每類有特化的輪次組合：

文章（content/posts、content/report）

完整跑 1-5 輪。額外加：

• 輪 6：跨卡 cross-link 健康度（單向引用 vs 雙向）
• 輪 7：放回 _index.md 的索引條描述對應到內容嗎

程式註解（doc comment / inline）

跑 1-3 輪 + 額外：

• 輪 4’：grep-ability 改成「介面 vs 實作分層」— doc comment 不洩漏 impl、inline comment 講 why 不講 what
• 輪 5’：反例改成「這個註解 5 個月後讀還看得懂嗎」（時間軸 robust）

Naming（變數 / 函式 / 檔名 / slug）

→ 見 #84 Naming 是 iterated artifact、有特化的 4 輪設計。

Prompt（給 LLM 的指令）

跑 1-3 輪 + 額外：

• 輪 4’’：模糊指令（clarifying-ambiguous-instructions）— 「對齊」「靠近」這類詞翻成具體數字 / 條件
• 輪 5’’：「邊界 case 預期行為」明示了嗎

Stakes-conditional 追加輪：Epistemic Rigor

5 輪基本 frame 是 frame 軸（生成 / 意圖 / 語氣 / grep / 反例）；高 stakes 內容（reader 照做後錯誤不可逆 / 系統層 / 不可分批 ship 修正）追加 stakes 軸的 輪 E：epistemic rigor——比照學術 peer review 的 claim / evidence / method / threats / citation 五個 sub-check、確認論述強度足以承擔 reader 直接 implement 的下游風險。

啟動條件（opt-in、不污染預設）

判別啟動的核心問題：「reader 照這段實作會不會在生產系統留 silent gap、且不能靠後續 ship 修補？」——會 → 跑輪 E、不會 → 5 輪即可。動機論證見 #99 資安教學審查標準對應風險不對稱。

輪 E：Epistemic Rigor 的 5 個 sub-check

輪 E 的產出格式

跑完輪 E、每個 weakness 對應到一個 dimension + tier、見 #105 audit recommendation 層級：

• Accept：無 weakness 或在容忍範圍
• Minor revise：補 boundary / contrast / 版本標記類小改、不阻擋 ship
• Major revise：結構性 false sense、需重寫、ship 前必須修
• Withdraw：教錯主動誤導 reader（過時 crypto 沒標 deprecated / 扭曲 citation 反向違反現行標準 / defense theater 當示範），保留 = 增加生產系統 risk、必須移除或全換

withdraw tier 是高 stakes 內容跟一般內容的關鍵差異——一般內容 review 沒有「保留 = 增加 risk」的硬決策、高 stakes 必須有。

跟 5 輪基本 frame 的分工

兩軸正交、不取代——高 stakes 內容兩軸都跑（5 輪 frame + 輪 E stakes）、一般內容只跑 5 輪。輪 E 不在 5 輪裡是因為：把 epistemic rigor 設為預設會讓一般文章 over-audit、稀釋 review 紀律；設為 conditional opt-in 才能讓高 stakes 場景拉到學術級而不污染日常寫作。

→ 詳細維度展開（threat model 對稱 / mitigation 對位 mechanism / context-dependence / citation 時效）跟 audit recommendation tier 判準、見 #99 → #100 → #101-104 → #105 系列。

反模式：跳輪的代價

何時可以跳某些輪

四類共通：ROI 不同、輪次組合不同。Production 文件 / 卡片 / 註解 全跑、即時通訊只跑核心。

跟其他抽象層原則的關係

判讀徵兆

核心：Writing 的 ROI 來自多輪不同 frame、不是單次「寫得仔細」。要寫得仔細的部分太多、超過 working memory、必須分輪。跳輪的代價是某維度永遠做一半、累積成「看起來都對但其實有漏」的低品質文字。

第一次寫的名字幾乎都不對 — 不是因為命名能力不夠、是因為第一版命名只能基於「寫的當下看到的 context」、而正確的名字需要看到「未來所有 call-site / grep 結果 / 重構場景」。

命名的正確設計是 iterated artifact：寫 → re-read → 改 → 再 re-read → 收斂。每輪用不同 frame：

每輪可能 catch 到「上一輪沒看到」的問題、迫使重命名。接受重命名是命名工作的常態、不是失敗。

為什麼第一版幾乎不對

寫第一版時、認知資源都在「概念是什麼」、剩下的給命名只夠：

• 看到當前 function 在做的事 → 命名只反映當前
• 不知道未來會有 N 個 call-site → 沒考慮一致性
• 不知道未來會有 grep / refactor → 沒考慮 unique-ness
• 不知道未來會換 impl → 命名容易洩漏現在的 impl 細節

第一版命名是對「現在的 context」過度擬合。下一輪 review 換 frame 才能看到擬合方向之外。

四輪 review 的具體 checklist

輪 1：第一版

• 名字反映「做什麼 / 是什麼」、不是「怎麼做」
• 動詞 / 名詞符合語言慣例（function 動詞、value 名詞）
• 不超過 4 個單字（長 ≠ 清楚）
• 跑得到 next step、不在這輪糾結

輪 2：Grep-ability

• grep -r "<name>" 能命中目標、不會被別的 entity 蓋過
• 跟 framework / library reserved name 不撞（避免 data、type、value 等過泛）
• 名字不是其他名字的子字串（get 會匹配 getName getUser…）
• 中英混合場景下、英文部分能 grep（不要用 處理器handler 這種 mixed）
• 縮寫慎用（usr cfg mgr 增加 grep 失敗率）

輪 3：Cross-call-site 一致性

• 從 caller 角度看、名字暗示的契約對嗎？
• 跟同 module 其他類似 entity 命名格式一致嗎？（getUser vs fetchUser 不該混用）
• 同一個概念在不同 file 用同名嗎？（不該 userId / user_id / uid 三個並存）
• 動詞時態一致嗎？（fetched vs fetching vs fetch 對應狀態 / 動作 / 命令、不該混用）

輪 4：Impl 洩漏檢查

• 名字含 impl 細節嗎？（fetchUserViaSql ≠ fetchUser、後者較好）
• 換 impl 後名字還對嗎？（cacheGetUser 改成走 DB 後名字錯了）
• 名字洩漏 data structure 細節嗎？（userArray ≠ users、後者不綁 array）
• 介面層名字 vs 實作層名字區分嗎？（介面用「做什麼」、實作用「怎麼做」可加細節）

套用到不同命名場景

變數 / 函式

完整跑 1-4 輪。

額外注意：

• 作用域 — 越窄作用域越可短（loop counter i、close-up var tmp）；越寬作用域越要明確
• 類型暗示 — boolean 用 is / has / should 開頭

檔名 / module

跑 1-4 + 加：

• 層級表達 — 檔名能否反映在 directory 結構中的位置？
• 避免 utils / helpers / common — 這類是「不知該叫什麼」的訊號、強制再過一次輪 1-4

URL slug / route

跑 1-4 + 加：

• SEO — 跟 search query 的 substring match 對齊（#73 search 匹配模式）
• kebab-case 一致
• 不含 stop words（the、a、is、of、with、and）— 跟搜尋引擎 stemming 對齊

API endpoint / DB column

跑 1-4 + 加：

• 跨 service 一致性 — 同一概念在 client / server / DB 用同名（避免 user_id / userId / uid 跨 layer 不一致）
• 不可變更性 — DB column / API endpoint 改名成本極高、輪 1-4 多跑幾次值得

反模式：放棄重命名

何時可以跳輪

兩極：作用域越窄越可省、跨邊界 / public 越要 multi-pass。

跟其他抽象層原則的關係

判讀徵兆

核心：命名是 iterated artifact、不是 single-shot 動作。第一版基於狹窄 context 幾乎必錯。接受 N 輪 review 跟 K 次重命名是常態、命名品質會提升一個量級。試圖一次寫對 = 第一版 ship 出去 = 後續長期付 cognitive 成本。

當底層 engine（search engine、LLM、DB、compiler、framework）沒開放某能力的客製 API、不該硬改 engine 內部、改在 engine 的輸入層 / 外層做 transformation：

核心原則：engine 不開放 = 不要硬改 engine、改改你給 engine 的輸入。

為什麼移到外層是合理 escape

直覺反應遇到 engine 限制是「fork engine」「升級到能調的 engine」「換 engine」 — 但這三條都成本爆炸：

• Fork engine：維護 fork 成本（merge upstream changes、bug fix back-port）
• 升級：可能需要等好幾版、可能 breaking change、可能根本沒得升
• 換 engine：data migration、API 重寫、config 重學

外層 transformation 跳過這三條：

• 不動 engine 內部
• 用 engine 既有的合法 API（input、metadata、wrapper）
• 升級 engine 時 transformation 通常仍兼容
• 換 engine 時也常能直接搬

代價：

• 多一層 indirection
• 需要維護 transformation 邏輯
• 可能有 leak（transformation 不完美、edge case 露出 engine 限制）

通常代價遠小於三條「動 engine」路線。

五個跨領域實例

1. Search：suffix token injection

Pagefind / 多數 build-time search engine 只 prefix match。要支援 substring，build-time emit 額外 hidden tokens：

1<!-- 原文 -->
2<p>backpressure handling</p>
3<!-- transformation 後 -->
4<p>backpressure handling</p>
5<span hidden>pressure handling</span>

grep "pre" → matches pressure prefix → finds page。

2. LLM：prompt-level chain-of-thought

LLM 不會自動 CoT。在 prompt 層加：

1請先列出已知資訊、然後推理步驟、最後給出結論。

Engine 沒變、輸入變了、行為變了。

3. DB：denormalized columns

PostgreSQL JSON column query 慢、但:

1ALTER TABLE events ADD COLUMN user_id_extracted UUID
2  GENERATED ALWAYS AS (data->>'user_id') STORED;
3CREATE INDEX ON events(user_id_extracted);

Engine 沒變、schema 加了 generated column、query 走 index、變快。

4. Compiler：source-level macros

C 語言沒泛型、用 #define macro 模擬：

1#define SWAP(a, b, T) do { T tmp = a; a = b; b = tmp; } while(0)

Compiler 沒變、source 經 preprocessor transformation、行為變了。

5. Framework：wrapper component

React 沒 onAttach lifecycle、用 wrapper:

1function withMount(Component) {
2  return (props) => {
3    useEffect(() => { props.onMount?.(); }, []);
4    return <Component {...props} />;
5  };
6}

React 沒變、加一層 wrapper、行為加上了。

Input 跟 Output transformation 是不同 pattern

外層 transformation 不是單一 pattern、要區分 input transformation（改 engine 看到的）跟 output transformation（改 engine 給出的）：

例對照

Search：

• Input：build-time 加 suffix tokens（engine 索引時看到 hidden “pressure”）
• Output：result 出來後 client-side substring scan（engine 結果照常、額外加 fallback）

LLM：

• Input：prompt 加 “請逐步推理”（engine 看到不同 prompt）
• Output：parse output 後 extract structured data（engine 輸出照常、後處理）

DB：

• Input：generated column（engine 索引時看到 denormalized column）
• Output：query 結果後處理 / aggregation（engine 結果照常、應用層加工）

何時選哪個

多數實作 case 兩者疊加：input 解 80%（更徹底）、output 補剩下 20%（catch input 漏的）。

何時不該用外層 transformation

五類共通：transformation 的成本 / 風險 > 動 engine 的成本。其他情境外層 transformation 是首選。

跟 #45 外部組件合作四層的關係

#45 講「離公共介面越近越穩」、本卡是這條原則的具體展開：

外層 transformation 是邊界層的具體技法 — 在 engine 公共介面外、做 input / output transformation。

反模式

跟其他抽象層原則的關係

判讀徵兆

核心：Engine 限制不等於 capability 限制 — engine 沒開放的能力、通常可在 engine 的輸入 / 輸出層做 transformation 補上。「engine 不支援」是表象、「我沒思考外層解」是根因。

把 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。

跟其他抽象層原則的關係