Bridge 進階設定與 Feature Flags
逐欄理解 Stable 2.0.55 BridgeConfig、表單與 JSON 驗證，並把身份、session、同步、cover、fan、vacuum 與 Alexa workaround 放到正確的 Controller 情境。
Feature Flag 是精準 workaround，不是全部開啟的加速器
Bridge 設定同時承擔三類責任：決定候選實體的 filter、固定 Matter node 的執行參數，以及針對特定 Controller 行為啟用 workaround。這些欄位可能改變 endpoint 身份、cluster 組合、同步頻率或控制命令語意。你應先有可用的基準 Bridge，再一次只改一個相關選項。
本章以 Stable 2.0.55 的 schema 與 bridge-data.ts 為準。功能「存在 Stable release」不等於成熟度都是正式；serverMode 雖在 Stable channel，超過一個裝置的節點仍明確是實驗性。Controller 支援又是第三項事實：例如 Alexa 專用亮度 workaround 會破壞 Apple Home 的特定 Siri 操作，因此不能在 Multi-Fabric Bridge 上因為「看起來有幫助」而開啟。
serialNumberSuffix、uniqueIdSuffix 與部分每實體識別覆寫會讓 Controller 視為新裝置或混淆已配對快取。先備份持久化資料、記錄原值與 Controller 影響，再規劃重啟及重新探索；不要把改 suffix 當一般排錯第一步。BridgeConfig 每個頂層欄位
| 欄位 | schema／範圍 | 用途與修改界線 |
|---|---|---|
name | 必填字串，1–32 字元 | Bridge 在介面中的名稱；Server Mode 第一個實體另會驅動 node 身份與類型，不要混淆。 |
port | 必填 number，最小 1 | Bridge 監聽埠。編輯器另做「不能與其他 Bridge 重複」驗證；建立流程可由 backend 找下一個可用埠，但既有 BridgeConfig 要有值。 |
filter | 必填 object | 包含必填 include、exclude 陣列與可選 includeMode。完整 matcher 見第 5 章。 |
featureFlags | 可選 object | 本章後續逐項列出。多數布林預設 false；有例外與「未寫入」語意。 |
countryCode | 可選字串，2–3 字元 | schema 說明為 ISO 3166-1 alpha-2 國別碼，只在 commissioning 因缺國別碼失敗時需要。使用文件占位符 <COUNTRY_CODE>，不要抄實機資料。 |
icon | 可選 enum | 介面顯示用，可選 light、switch、climate、cover、fan、lock、sensor、media_player、vacuum、remote、humidifier、speaker、garage、door、window、motion、battery、power、camera、default；不改 Matter device type。 |
priority | 1–999，預設 100 | 啟動優先序，數字越小越早。它是排序，不是 Controller 優先權。 |
serialNumberSuffix | 可選，最長 16 字元 | 附加到這座 Bridge 每個實體的 serial number，可用來讓 Controller 繞過舊快取；可能被辨識成新裝置。 |
uniqueIdSuffix | 可選，最長 16 字元 | 混入標準 Bridge Mode 的每個 bridged device uniqueId，重啟後生效；Server Mode 不屬於其註解指定範圍。 |
sessionMaxAgeHours | 0–168 小時 | 讓過齡 Matter session 重新建立並重新訂閱；0 關閉。Server Mode 預設每 4 小時輪替，標準 Bridge 只有設定此欄位才啟用。 |
schema 對頂層與 filter 設為 additionalProperties: false，所以拼錯欄位不是可忽略註解，而是驗證錯誤。feature flag schema 沒明寫 additionalProperties false，但仍不應加入來源未定義的鍵。表單把 icon 交由獨立的 Bridge Icon 元件管理，切換表單／JSON 時會保留 icon。
可見性、組合、自動同步與名稱 Flags
| flag | 預設／成熟度 | 精確行為 |
|---|---|---|
includeHiddenEntities | false；穩定 | 允許 Filter 命中的 Home Assistant hidden entity 進入 Bridge。它不會解除 Entity Mapping 的 disabled。 |
serverMode | false；Stable 中實驗性 | 把實體作為 standalone Matter device，而非 bridged device。每個 node 最多帶 10 個裝置，第一個是 primary 並決定 node 名稱與類型；超過一個裝置仍為實驗性。 |
autoBatteryMapping | false；穩定 | 把同一 HA device 的 battery sensor 附到主實體，避免在 Controller 成為獨立裝置。 |
autoHumidityMapping | true；穩定 | 同一 HA device 的 humidity 與 temperature 自動組合。程式以「不是明確 false」判定，因此省略也啟用。 |
autoPressureMapping | true；穩定 | 同一 HA device 的 pressure 與 temperature 自動組合；省略也視為啟用。 |
autoComposedDevices | false；穩定 | 組合裝置 master toggle，同時啟用 battery、humidity、pressure、power、energy 自動映射。更多 cluster 也會增加同步資料量。 |
autoForceSync | false；穩定 workaround | 每 90 秒比較並推送全部裝置狀態，針對 Google Home／Alexa 可能遺失 subscription 的情境。健康檢查不依賴此 flag。 |
productNameFromNodeLabel | false；穩定 | 以解析後 nodeLabel 回報 productName，供會把 productName 當裝置名稱的 Controller 使用；每實體 customProductName 優先。 |
preferEntityRegistryName | false；穩定 workaround | nodeLabel 順序改為 customName → registry name → registry original_name → friendly_name → entity_id，處理 HA 2026.4 friendly_name 前綴變化。Matter 沒有 alias，只能回報一個名稱。 |
useHaRegistrySerial | false；穩定 | 沒有每實體 custom serial 時，使用 HA device registry serial_number；再沒有才用 entity-ID-based hash。commissioning 後改 serial 可能讓 Controller 混淆。 |
batteryEntity、humidityEntity 等是你明確指定的連結。兩者不能只看 Controller 畫面猜測，應在 Devices card 的 mapping 資訊核對。Cover、Fan、Vacuum 與 Alexa 行為
| flag | 作用 | Controller 界線 |
|---|---|---|
coverDoNotInvertPercentage | 不做 Matter 標準方向的百分比反轉，讓數字貼近 HA；schema 明確說這不符合 Matter。 | 只有確認數值語意需求時使用；不要與命令反向混為一談。 |
coverUseHomeAssistantPercentage | 顯示 HA 百分比，Open／Close 命令仍正確；HA 高百分比表示更開，而 Alexa 往往解讀為更關。 | schema 標為 Alexa-friendly，但語意差異仍存在。 |
coverSwapOpenClose | 交換開／關命令並反轉位置回報。 | 只在語音「關」反而打開時使用；每實體同名覆寫可優先處理單一 cover。 |
coverSliderDebounceMs | 0 保留內建兩階段 400／150 ms；大於 0 改成單一等待窗，範圍 0–5000 ms。 | 處理 Apple Home 持續送 slider 更新；單一 cover 的 per-entity 值優先。 |
fanSliderDebounceMs | 等待最後一次風速寫入後才送 HA，範圍 0–10000 ms；0 每筆立即送。 | 適合會因 IR／UART 每幀發聲的設備；每實體值優先，Entity Mapping UI 會限制到 5000 ms。 |
vacuumOnOff | 為 RVC 加 OnOff cluster，且沒有 schema default。 | v2.0.55 實際 registry 在 Bridge／Server Mode 都只有明確 true 才加入；省略與 false 都不加入。bridge-data.ts 註解與 schema 仍描述 Server Mode 未設定時自動加入，和執行碼矛盾，操作應以執行碼為準。Alexa 需要時設 true；非標準 cluster 可能影響 Apple／Google。 |
alexaPreserveBrightnessOnTurnOn | 忽略同一燈開啟後 200 ms 內送到最大亮度的命令，避免 Alexa subscription renewal 後回到 100%。 | 只用 Alexa-only Bridge；會破壞 Apple Home 房間層級「設為 100%」Siri 命令。 |
vacuumIncludeUnnamedRooms | 在 bridge-data.ts 的型別宣告中存在。 | v2.0.55 schema 沒有此欄位，且 exact commit 的 packages 內沒有執行期讀取；因此不能宣稱 UI 可設定或具有可驗證效果，請勿依賴。 |
Controller profiles 是建立時的建議組合，不是即時相容性保證：Apple profile 開 composed/battery/humidity/pressure；Google 再開 autoForceSync；Alexa profile 開 autoForceSync、battery/humidity/pressure 與 HA cover percentage；Multi-Controller 使用標準 cover 行為。profile 套用後仍是一般 BridgeConfig，你要按實際 Controller 與裝置類型驗證。
Stable Identity、Session Recovery 與 Watchdog
| 設定 | 觸發條件 | 能處理／不能處理 |
|---|---|---|
stableIdentity | 啟用後以 HA entity registry unique_id 錨定 endpoint id、uniqueId、serialNumber。 | HA entity_id 改名時 Controller 可保留群組、名稱與自動化。identity records 從一開始就 seed，所以之後開啟不應重加既有裝置；不是資料備份替代品。 |
fastSessionRecovery | Controller 丟失全部 subscriptions。 | 5 秒後清理 dead session 並重新 announce，而不是 60 秒；縮短 Google offline 視窗，不能阻止 Controller 拒絕 subscription。 |
wedgeWatchdog | subscription 仍活著，但約 45 分鐘沒有 Controller inbound Interaction Model request。 | 提早輪替疑似 wedged 的單一 session，針對 Apple Home Updating；誤判成本是透明重新建立 CASE，不代表網路故障都能修復。 |
sessionMaxAgeHours | session 超過設定年齡。 | 盲式年齡輪替並促使重新訂閱；0 關閉。它是頂層欄位，不是 feature flag。 |
autoForceSync | 每 90 秒週期。 | 推狀態，不等於 session 清理。與 composed devices 同開會增加流量。 |
這些機制處理不同層級：identity 解決 HA rename 的裝置連續性；session rotation／fast recovery／watchdog 處理 Matter 連線與 subscription；autoForceSync 處理狀態推送。不要同時全開後再試圖判斷是哪個機制有效。家庭多 Controller Bridge 尤其應先採通用設定，Controller 專用 workaround 則分拆 Bridge。
安全切換 Raw JSON 與欄位編輯器
備份目前設定
先從既有 Bridge 匯出或以安全方式記錄非秘密設定，並確認持久化資料有可回復備份。不要在文件或工單貼出實際環境識別資料。
開啟 Edit 並切換 JSON
在 Bridge 編輯頁按右上角編輯器切換按鈕，從 Fields Editor 進入 JSON Editor。保留必填
name、port、filter.include與filter.exclude。只加入 schema 定義鍵
使用文件占位符檢查結構，例如
"countryCode": "<COUNTRY_CODE>"；布林寫 true／false，debounce 與 session 年齡寫 number，不把數字放在引號內。看即時驗證結果
修正 JSON 語法、required、enum、最小／最大值與 additional properties 錯誤。若 port 已被另一座 Bridge 使用，custom validation 也會阻止儲存。
切回表單交叉檢查
確認欄位仍顯示預期值；特別檢查
vacuumOnOff是否只在 Alexa 專用需求下明確為 true，以及 icon 是否被獨立控制保留。一次只儲存一組變更
按 Save 後依該 flag 的層級驗證：身份相關看 rename 連續性，session 看 Health，cover/fan/vacuum 看單一測試裝置。需要重啟才套用的身份 suffix 要先安排中斷窗口。
從症狀選最小設定
| 已確認症狀 | 優先評估 | 避免同時做 |
|---|---|---|
| HA 改 entity_id 後 Controller 重建裝置 | stableIdentity | 同時改 serial／unique suffix，否則無法判斷身份變動來源。 |
| Google 取消 subscription 後離線 | fastSessionRecovery，必要時再評估 autoForceSync | 把網路不可達誤當 subscription 問題。 |
| Apple tile 長時間 Updating、仍有 subscription | wedgeWatchdog 或規劃 session age rotation | 直接 reset／重新配對；先看 Health 與已遮蔽 log。 |
| Alexa 開燈後亮度跳滿 | Alexa-only Bridge 的 alexaPreserveBrightnessOnTurnOn | 在同座 Apple Home Bridge 開啟。 |
| Cover 語音開關反向 | coverSwapOpenClose，單一裝置優先 per-entity | 先改百分比 flags；命令方向與百分比顯示不同。 |
| 拖曳風扇／窗簾造成多次實體命令 | 相應 debounce，先從單一 entity 覆寫測試 | 把 update throttle 當 inbound command debounce。 |
若一座 Bridge 同時服務 Apple、Google、Alexa，先採 Multi-Controller 的通用語意；需要互斥 workaround 時分拆 Bridge，因為同一 endpoint 不可能同時用標準 cover 語意與 Controller 專用反轉，也不能同時忽略 Alexa 的最大亮度序列又保留 Apple 相同序列。
進階設定排錯與安全返回點
Save 按鈕不能按
先切回表單看驗證：name 長度、port 重複、required filter arrays、enum、debounce／session 範圍與未知頂層鍵都可能使設定無效。不要繞過 schema 直接改 storage。
Vacuum 在 Alexa 配對後不顯示
檢查
vacuumOnOff是否明確為 true；v2.0.55 執行碼在 Bridge／Server Mode 都不會因欄位省略而自動加入。若同 Bridge 還有 Apple／Google，先評估分拆，不要犧牲其他 Controller。Apple 房間亮度語音失效
檢查是否在含 Apple 的 Bridge 開了
alexaPreserveBrightnessOnTurnOn。關閉並回到 Controller 中性設定；不要同時改燈的 type 或 identity。修改 suffix 後出現重複裝置
這正是 mint fresh identity 可能造成的結果。還原原 suffix、由備份確認原設定，再按 Controller 的安全維運流程處理；不要反覆變更 suffix 產生更多身份。
Auto Force Sync 仍顯示離線
它只定期推狀態。查看 Health 的 session／subscription 與網路狀態；若是取消 subscription，評估 fast recovery；若是疑似 wedge，再按 Controller 類型評估 watchdog。
單一 cover 或 fan 不適合全域值
清除 Bridge 層級 workaround 或維持通用值，改到 Entity Mapping 設 per-entity
coverSwapOpenClose、cover/fan debounce；每實體設定優先且影響較小。