第 5 章

完整 Filter Engine

學會用 Include、Exclude、ANY、ALL 與 Stable 2.0.55 的全部 matcher，先在預覽確認範圍，再讓 Home Assistant 實體進入 Matter Bridge。

先把「哪些實體會被橋接」變成可預測規則

篩選引擎（Filter Engine）決定 Home Assistant 登錄中的實體是否有資格交給 Bridge 建立 Matter endpoint。它不是 Controller 裡的房間篩選，也不會改動 Home Assistant 原本的實體；它只控制這座 Bridge 的候選集合。家庭裡若有照明、診斷感測器、腳本與多個品牌整合，直接包含全部實體容易把不需要或不受支援的項目一起送出。小型辦公室則常需要依樓層、區域或標籤拆成多座 Bridge。

正確做法是先建立「納入條件」，再建立「永遠排除條件」，最後用預覽檢查。Include 空陣列代表不限制候選；Include 非空才依 includeMode 判斷。Exclude 永遠以任一規則命中即排除。最後的結果可寫成：（Include 為空或 Include 判定為真）且 Exclude 沒有任何命中。

注意：篩選成功只表示實體進入候選集合，不保證其 Home Assistant domain、device class 或你覆寫的 Matter device type 能被特定 Controller 顯示。release channel、功能成熟度與 Controller 支援是三件不同的事。

ANY、ALL、空集合與優先序

位置組合方式結果適用情境
Include 空陣列不執行 matcher所有登錄實體先視為 included以 Exclude 為主的黑名單策略
Include + anyOR任一 Include matcher 命中即可納入多個 domain、區域或標籤
Include + allAND每一個 Include matcher 都要命中例如同時要求照明 domain 與指定區域
Exclude固定 ANY／OR任一 Exclude matcher 命中就移除排除診斷、測試或敏感操作實體
Include 與 Exclude 同時命中Exclude 優先最終不納入先廣泛納入，再設安全護欄

includeMode 只套用在 Include；若省略，程式預設 any。Exclude 呼叫 matcher 測試時不指定 mode，因此也是預設 any。ALL 不是把一個 matcher 的多個值視為 AND；每一列仍只有一組 type 與 value，ALL 是要求多列全部成功。

hidden entity 是另一層判定。即使 matcher 命中，Home Assistant 標示 hidden 的實體預設仍會被略過；只有 Bridge 的 includeHiddenEntities feature flag 開啟才納入。映射中 disabled 的實體同樣不應被當成可用 endpoint。不要把 Filter、hidden 與 Entity Mapping disable 混為同一個開關。

Stable 2.0.55 全部 matcher 速查

type比對資料精確行為與注意事項
patternentity_id萬用字元（wildcard）只把 * 展開成任意字串，整個值會被頭尾錨定；其餘正規表示式符號會被跳脫。例：light.demo_*。
regexentity_id直接建立 JavaScript RegExp，只測 entity_id；無效語法回傳不命中，不會改測其他欄位。例：^(light|switch)\.demo_.*。
domainentity_id 點號前段精確且區分大小寫，例如 light；不接受逗號清單或 wildcard。
platformEntity Registry platform精確比對整合／平台字串，例如文件示意 mqtt；以 Filter Reference 顯示的值為準。
label實體本身的 labels已棄用（deprecated），行為等同 entity_label；舊設定可讀，但新規則應遷移。
entity_label實體標籤只納入直接掛上該標籤的實體，不會連帶同一裝置的其他實體。可填顯示名稱或 label_id。
device_label裝置標籤裝置標籤命中時，該裝置旗下每個候選實體都會命中。可填顯示名稱或 label_id。
entity_label_regex每個實體標籤的 slug 與顯示名稱任一已指派標籤符合 RegExp 即命中；無標籤或無效 RegExp 都是不命中。
device_label_regex每個裝置標籤的 slug 與顯示名稱任一裝置標籤符合即讓該裝置實體命中；適合以標籤命名慣例管理整台裝置。
any_field_regex單行 key=value haystack可同時檢查 entity_id、domain、platform、area、entity_category、device_class、實體／裝置標籤 slug 與名稱、device_name、product_name、manufacturer。
areaentity area，否則 device area先採 entity 的 area_id，沒有才退回 device 的 area_id；精確比對 area slug。
entity_categoryEntity Registry category精確比對，例如 config 或 diagnostic；常放在 Exclude。
device_namename_by_user → name → default_name不含 * 時為不分大小寫的子字串；含 * 時是不分大小寫、整段錨定的 wildcard。
product_namemodel → default_model同樣支援不分大小寫子字串或含 * 的錨定 wildcard。
manufacturermanufacturer → default_manufacturer同樣支援不分大小寫子字串或 wildcard，沒有裝置登錄資料時不命中。
device_class目前 state attributes.device_class精確比對，例如 temperature、motion；不是 entity domain，也不是 Matter device type。
名詞：schema 把 pattern 稱為 wildcard pattern，把 regex 定義為 entity ID regex。介面沒有另一個名為 entityIdRegex 的 type；在 v2.0.55 中，需求所稱 entityIdRegex 就是 type: "regex"。

正規表示式、標籤解析與 any-field

標籤精確 matcher 會先以不分大小寫的顯示名稱查表；找到就轉成 label_id。找不到時，程式會正規化輸入：去除組合音標、轉小寫、非英數轉底線並清除頭尾底線。最可靠的方式仍是到側欄 Filter Reference（路由 /labels）複製實際 label_id，避免名稱變更影響規則。

any_field_regex 的 haystack 是同一行、以空格串接的 key=value 欄位。你可以用 alternation 表達 OR，也可用正向 lookahead 表達同一實體同時符合多欄位，例如文件型示意 (?=.*domain=light)(?=.*area=demo_room)。標籤陣列以逗號串接，因此邊界寫法要依實際 slug 測試。引擎以 new RegExp(pattern) 建立規則，沒有另外加入不分大小寫旗標；需要時請在 pattern 明確涵蓋大小寫，最穩定仍是使用 Filter Reference 顯示的原值。

需求建議 matcher原因
一組已知 entity_id 前綴pattern比 regex 容易讀，且整段錨定。
兩個 domain 的 entity_id 結構regex只在 entity_id 上做 alternation，範圍明確。
一個實體標籤entity_label不會意外帶入整台裝置。
整台裝置與其所有實體device_label語意比多條 entity_id 規則穩定。
domain 與 area 同時成立Include ALL 的兩列規則較 any-field lookahead 容易維護。
跨欄位的複雜 OR／ANDany_field_regex只有它能在單一 matcher 看完整 haystack。
注意：無效 regex 靜默變成「不命中」。在 ALL 模式會讓整個 Include 失敗；在 Exclude 則可能失去你以為存在的護欄。每次改 regex 都要看 Preview。

用欄位編輯器建立並預覽篩選

  1. 進入 Bridge 編輯頁

    從 Bridges 選取目標 Bridge，開啟 Edit。先記錄目前 Include、Exclude 與 includeMode，不要同時修改 feature flags。

  2. 選擇 Include Mode

    在 Include or exclude entities 把 Include Mode 設為 any 或 all。ANY 適合「任一類別」，ALL 適合「同時滿足條件」。

  3. 逐列加入 Include

    按 Include 的新增控制，為每列選 Type 並填 Value。標籤、area、platform 等值先從側欄 Filter Reference 複製，不憑顯示文字猜測。

  4. 加入 Exclude 護欄

    在 Exclude 加入不應暴露的類別，例如 category 為 diagnostic 或明確的測試 entity pattern。Exclude 任一命中就勝過 Include。

  5. 檢查 Preview Matching Entities

    等待約 800 ms 自動更新或按 Preview Matching Entities。確認總數、domain chips、名稱與 entity_id；預覽最多列出前 100 筆，total 才是完整命中數。

  6. 儲存並驗證

    只有預覽符合預期且表單有效時才按 Save。再回到 Bridge／Devices 檢查實際 endpoint 與 failed entities；不要以 Controller 是否立即顯示作為唯一判準。

Filter Preview 會使用目前 Home Assistant entity、device、state 與 label registry 執行同一套 matcher 邏輯，並將結果依 entity_id 排序。預覽也會提示大量實體、未支援 domain 或 vacuum 情境；這些提示是規劃資訊，不會自行改寫設定。

可維護的家庭與辦公室規則

房間專用 Bridge：Include Mode 選 ALL，第一列用 area 指定文件用區域 slug，第二列用 domain 限定 light。這與「area 或 light」完全不同。若還要開關，改用單一 entity ID regex 表達 light／switch 並與 area 一起 ALL，或以 entity/device label 重整分類。

語音裝置白名單：在 Home Assistant 把可交給語音 Controller 的實體直接加 entity label，Include 用 entity_label。需要整台裝置全部實體才用 device_label。不要用 deprecated label 建立新設定。

廣納入、精排除：Include 留空，Exclude 加 entity_category=config、entity_category=diagnostic 與測試命名 pattern。這種策略容易隨 Home Assistant 新增實體而擴張；每次新增整合後都應重看 Preview。

品牌或型號分橋：用 manufacturer、product_name 或 device_name。這三者會不分大小寫做子字串，含 wildcard 才改成整段匹配。若 device registry 缺資料，該實體不會命中，應以 Preview 找出缺口，而不是假設 platform 等同 manufacturer。

維護原則：優先使用語意清楚的 domain、area、entity/device label，再用 pattern；只有無法用多列 ANY／ALL 表達時才用 any-field regex。規則越短，之後改名或換整合越容易判讀。

篩選結果不如預期時逐項返回

  1. Include ALL 變成零筆

    逐列暫時只保留一條並看 Preview，確認每條都能獨立命中同一實體。最常見原因是把「area A 或 area B」誤設成 ALL，或 regex 語法無效。

  2. 標籤只帶入一個實體

    確認你使用的是 entity_label。若目標是整台裝置，應在 Home Assistant 對 device 指派標籤並改用 device_label；不要期待 entity label 自動傳播。

  3. Area 規則沒有命中

    到 Filter Reference 複製 area slug。引擎先看 entity area，沒有才看 device area；若 entity 自己被放到另一 area，它會覆蓋 device area。

  4. Preview 有、實際 Bridge 沒有

    檢查 hidden 狀態、includeHiddenEntities、Entity Mapping 的 disabled、domain/type 是否支援，以及 Bridge 的 failed entities。Filter Preview 只證明篩選判定。

  5. Exclude 沒擋住項目

    Exclude 固定 ANY，先檢查 type 是否對到正確欄位。regex 只看 entity_id；若你想查 manufacturer 或 labels，應換專用 matcher 或 any-field regex。

  6. 預覽只看到 100 筆

    這是介面截斷，不是篩選上限。讀取 total，縮小規則或分拆 Bridge 後再預覽，避免因前 100 筆看似正常就漏掉尾端項目。

Filter Engine 常見問題

Include 留空是否代表一個實體都不納入？
不是。v2.0.55 的判定把 Include 空陣列視為全部 included，再套用 Exclude。若想白名單，至少加入一條 Include。
Exclude 也能設成 ALL 嗎？
不能。schema 只有 includeMode，而 backend 對 Exclude 使用預設 ANY。任何一條 Exclude 命中就排除。
pattern 與 regex 哪個不分大小寫？
兩者都沒有自動不分大小寫。pattern 是把 * 轉成 wildcard 並錨定；regex 是 JavaScript RegExp。device_name、product_name、manufacturer 才會先轉小寫比較。
Filter Reference 會改動標籤或 Area 嗎？
不會。它是查閱頁面，列出 labels、areas、domains、platforms、entity categories、device classes、device names 與 product names，並提供複製值的操作。
Controller 沒顯示，是否代表 matcher 錯誤？
不一定。先以 Preview 與 Devices 確認候選與 endpoint，再分開檢查 Matter device type 的 Controller 支援。Controller 能否呈現不是 Filter Engine 的判定欄位。

Stable 2.0.55 固定版本來源

以上均固定到 v2.0.55 commit；本章描述的是 Stable channel。Filter Engine 本身為穩定功能，Controller 支援不參與 matcher 判定。