Plugin System、API 與 WebSocket
在標準 Bridge 上安全管理 Plugin 生命週期，明確標示內建 Camera／Security 的實驗性，評估 npm、tgz 與 symlink 供應鏈風險，並把 REST、WebSocket、logs、metrics 與 health 視為 v2.0.55 可驗證介面，而非永久公開合約。
Plugin 是同程序程式碼，不只是 UI 擴充
Plugin 可以註冊 Matter device、更新 cluster state、接收 Controller attribute write、呼叫外部服務並使用持久化 storage。v2.0.55 的 Plugin 直接在 HAMH backend 程序內執行，沒有 OS-level sandbox；錯誤 wrapper、timeout 與 circuit breaker 能降低故障擴散，不能把惡意套件變安全。安裝第三方 Plugin 等同授權它在 HAMH 程序權限內執行程式碼。
Plugin 只支援標準 Bridge。啟用 Server Mode 的 Bridge 不建立 Plugin manager，連內建 Plugin 都不承載；若所有 Bridge 都是 Server Mode，Plugins 頁會顯示相對應空狀態。這項規則與 release channel 無關：Server Mode 本身仍是實驗性（experimental-in-Stable）。
| 來源 | 更新／載入 | 主要風險 | 適用 |
|---|---|---|---|
| Built-in | 隨 HAMH 版本 | 仍可能實驗性；需看 Controller 支援 | Camera／Security 特定能力 |
| npm package | 安裝後重啟 Bridge 載入 | 名稱混淆、依賴與 install script 供應鏈 | 經審查、鎖定版本的正式測試 |
| uploaded tgz | 上傳安裝後重啟 | 來源、完整性與內容不透明 | 可驗證建置產物 |
| local symlink | 來源變更於 Bridge 重啟後生效 | 路徑替換、權限、非可攜與持久性 | 隔離開發，不適合生產 |
生命週期、裝置註冊與 circuit breaker
Plugin 的必要 hook 是 onStart(context)，Bridge 啟動時探索／註冊 device 與建立連線；可選 onConfigure() 在裝置註冊後恢復狀態，onShutdown(reason) 清理 timer／socket，getConfigSchema() 提供 UI schema，onConfigChanged(config) 套用更新。Context 提供 register／unregister device、update state、domain mapping、plugin-scoped storage、logger、bridge ID 與可選 HA connection。
Enable／Disable 是每座 Bridge、每個 Plugin 的狀態。Disable 會卸載其 mounted devices 並持久化選擇；Enable 重新啟動 Plugin。設定在 Plugin disabled 時可先保存，之後 enable 才生效。Install／Uninstall 則是套件層級，通常需要重啟 Bridge 才套用；不要混淆「套件已安裝」與「某座 Bridge 上 Plugin 已啟用」。
SafePluginRunner 對一般 lifecycle call 採預設 timeout，連續失敗達門檻會開啟 circuit breaker 並停用 Plugin；成功操作會重置 failure count。Reset 按鈕只清 breaker 讓它可再嘗試，不會修正根因。Shutdown cleanup 即使 breaker 已開仍會嘗試執行，避免資源洩漏。
Stable 中的實驗性 Plugin 與 Controller 邊界
| 能力 | Release channel | 產品成熟度 | Controller 支援 |
|---|---|---|---|
| Plugins 頁與 Plugin manager | Stable 2.0.55 | Plugin system 可用；第三方品質各自負責 | 取決於註冊 device type |
| 內建 Camera Plugin | Stable 內建 | 實驗性（experimental-in-Stable）；media path 尚未完成真機端到端驗證 | 官方同版文件指出 Apple Home 不呈現；當時以 SmartThings 為主要目標，不可外推 |
| 內建 Security Plugin | Stable 內建 | 實驗性（experimental-in-Stable），自有 state machine | mode switch／contact sensor 的呈現依 Controller |
| Server Mode Bridge 上 Plugin | Stable 內有 Server Mode | 不支援；Server Mode 本身實驗性 | 無 Plugin endpoint |
| REST／WebSocket | v2.0.55 程式碼可驗證 | 供 Web UI 與整合使用 | 與 Matter Controller 支援無直接關係 |
API 合約聲明：v2.0.55 程式碼與 pinned docs 列出 REST route、WebSocket message 與 response shape，但 repo 沒有在這些來源中承諾永久相容的公開 API 版本策略。除非另有來源保證，不要把它描述為 guaranteed stable public contract。自動化應 pin 版本、驗證 status／schema、設定 timeout，升級前跑 smoke test。
Plugin manifest 可宣告 hamhPluginApiVersion；目前 manager 常數為版本一，不匹配時記錄 warning。Warning 不是相容保證，也不會替第三方套件升級。Live matter.js EndpointType 還必須來自同一 matter.js instance，外部套件通常更適合使用可序列化的 deviceType 與 cluster data。
Plugin 上線的最小風險流程
確認標準 Bridge 與隔離範圍
在 Bridges 選一座未啟用 Server Mode 的標準 Bridge，先確認 running、Fabric 與 Health 正常。為實驗性 Camera／Security 或第三方 Plugin 使用專用 Bridge，可縮小 Controller 相容與故障範圍。
備份並審查來源
建立完整身份備份與 Plugin 狀態紀錄。npm 要鎖定明確版本並核對 package owner、來源 repo、manifest、依賴與發行完整性；tgz 要由可信 CI 產生並校驗；symlink 僅在隔離開發環境使用。
安裝或選擇 built-in
Built-in 不要在 npm 欄輸入名稱，直接於 Plugins 頁啟用／設定；程式會拒絕保留的 built-in 名稱。第三方 package 使用相應 npm／Upload／Local tab，成功後依提示重啟目標 Bridge，再 Refresh 列表。
以 schema 設定最小資料
先填 required 欄位，number 必須可解析，未知 schema key 應保留既有設定。標示 secret 的欄位由 backend redaction，不回傳已存值；留用遮蔽 placeholder 代表保持原值。任何 token／password 都只能從 secret 管理流程輸入，不進文件或 log。
驗證 endpoint 與 Controller
確認 Plugin metadata、enabled、devices 與 breaker state，再到 Bridge endpoint tree 檢查 device type／clusters。以一個低風險 device 做狀態與 Controller write 測試；Camera 另需評估 operational port TCP firewall，Security 不用安全關鍵實體做首次測試。
建立失敗返回點
若錯誤增加，先 Disable Plugin 讓 mounted device 移除，保留 log 與設定。修正外部服務／schema 後才 Reset breaker 再 Enable；若要 Uninstall，先確認沒有 Bridge 正在使用並保留備份，完成後重啟與驗證其他 Plugin。
Built-ins、schema、REST 與即時介面
Camera Plugin
Camera 把指定 Home Assistant camera entity 以 Matter Camera device 暴露，使用 WebRTC transport flow。未設定 camera entity 前不註冊裝置；設定後可動態 mount。可選自訂 HA URL 與秘密，但最小設定應重用 Bridge 既有 HA connection。專用 Bridge 可隔離 Matter over TCP capability 對其他 Controller 的影響。
它在 Stable 2.0.55 仍是實驗性；不能宣稱 Apple Home 支援，也不能宣稱任何 Controller 上已完整驗證 live view。Camera stream 牽涉隱私、網路與防火牆，Plugin 頁可用不等於符合你的監控法規或存取政策。
Security Plugin
Security 建立 Home／Away／Night／Vacation mode switch 與 Alarm contact sensor，以 exit／entry delay、trigger list、alert list、setters 與持久化 armed state 運作。它不是既有 Alarmo／alarm integration 的同步前端；若兩者使用同一批 sensor，會形成彼此不知道的兩套 state machine。
此實驗性 Plugin 沒有獨立驗證碼流程；能操作 mode switch 的 Controller 也可能 disarm。因此只暴露給可信 Controller，不把它當符合認證的入侵警報。HA 中斷期間的 trigger event 可能遺失，這也是不能把它當 safety system 的原因。
Schema secret 與 breaker
v2.0.55 backend schema property 有明確 secret flag：已存 secret 在 listing 中替換為 sentinel，save 時若仍是 sentinel 就保留原值。前端也以欄位名稱 fallback 遮蔽舊 schema，但真正的保護應依 backend secret flag。第三方 Plugin 若沒有正確標示 secret，平台不能自動知道某字串敏感。
REST surface
/api/plugins 提供各標準 Bridge plugin metadata、redacted config、breaker 與 devices；另有 installed list、npm install、binary tgz upload、local install、uninstall、enable／disable／reset、config schema 與 config update。整個 /api 還掛載 matter、health、bridges export、images、mappings、settings、backup、HA、logs、system、diagnostic、metrics 與 network。這是管理平面，必須套用第 20 章的存取控制；但 WebSocket 有同版 auth bypass 邊界，不能把 REST 保護外推到 upgrade。
WebSocket、logs、metrics、live／ready
WebSocket 路徑隨 base path 掛在 /api/ws，連線時送初始 Bridge state，之後可 broadcast bridge update；client 可 ping／pong、subscribe／unsubscribe diagnostics，訂閱時收到 snapshot 與後續 diagnostic event。關鍵安全邊界：v2.0.55 upgrade 直接掛在 raw HTTP server，繞過 HAMH Express Basic Auth 與 application IP allowlist。可信 proxy／網路邊界必須自行驗證、限制 upgrade 並阻止直接 backend reachability；client 也要能處理未知 message type 與重連。
Logs API 支援 level、search、category、facility、limit／offset，另有 level count、clear 與 Server-Sent Events stream；低記憶體系統使用較小 buffer。Metrics 有 JSON 與 Prometheus。Health live 回答程序存活，ready 只看 HA connected。這些端點的範圍不同，不能用單一 200 回應宣稱整個 Matter topology 健康。
| 介面 | 用途 | 安全注意 |
|---|---|---|
| Plugin REST | 安裝、生命週期、設定 | 具變更能力，限制到管理者 |
| WebSocket | Bridge update 與 diagnostics | 沿用 base path，但不繼承 HAMH Basic Auth／allowlist；proxy 必須驗證並限制 upgrade |
| Logs／stream | 查詢與即時 log | 可能含環境資訊；clear 是破壞性診斷動作 |
| Metrics | 資源、Bridge、HA 趨勢 | label／版本屬營運資訊 |
| live／ready | 程序與 HA readiness probe | 程式碼略過 Basic Auth；靠網路限制 |
安全採用與自動化情境
內建 Camera 試驗：建立專用標準 Bridge，只放一個非敏感測試 camera，限制到測試 Controller 與 VLAN，確認 TCP policy、Health 與 Disable 回復。結果只代表該 Controller／版本／網路，不外推到 Apple、Google、Alexa 或其他產品。
第三方雲端 Plugin：在隔離環境以最小 scope credential 測試，schema secret 正確標示，log 不得輸出 request header 或 token。先觀察一段 failure／memory／network 趨勢，才考慮生產；套件升級仍按新程式碼重新審查。
外部監控：monitor 透過受控網路讀 ready、metrics 與必要 logs，不使用能安裝／刪除 Plugin 的管理帳號。升級前 pin v2.0.55 response fixture；升級後驗證 content type、required field 與 WebSocket message，再調整 parser。
常見卡關與安全修復
Plugins 頁空白或看不到 built-in
檢查：是否沒有 Bridge、全部為 Server Mode、或標準 Bridge 未 running。安全修復：建立／啟動專用標準 Bridge；不要去 npm 安裝同名 built-in。
安裝成功但 Plugin 沒載入
檢查：installed list、manifest main／API version、Bridge 是否已 restart、log import error。安全修復：確認 package 完整性與相容後單座 restart；不可信 package 直接移除並輪替可能接觸的秘密。
Circuit breaker tripped
檢查：last error、連續 failure、外部服務與 schema。安全修復：先 Disable，修根因，再 Reset 與 Enable；單純 Reset 會再次失敗。
設定頁沒有遮蔽秘密
檢查：Plugin schema 是否把欄位標成 secret。安全修復：停止使用並向維護者修 schema；已暴露值立即輪替，前端欄名猜測不是充分保證。
Web UI 狀態不更新但 REST 正常
檢查：proxy WebSocket upgrade、base path 與瀏覽器 socket。安全修復：修 proxy 後重連，不重設 Bridge Fabric。
Uninstall 後 Controller 留下裝置
檢查：Bridge 是否重啟、Plugin endpoint 是否仍在、Controller cache。安全修復：先讓 Bridge 正常重建且 endpoint 消失，再依 Controller 安全移除；不要為單一 Plugin 直接災難 reset。
常見問題
Plugin 可以跑在 Server Mode Bridge 嗎？
Stable 內建 Camera 就是正式成熟功能嗎？
Circuit breaker 是安全沙箱嗎？
REST API 是保證永遠相容的公開合約嗎？
Local symlink 適合生產嗎？
readiness 成功代表 Plugin 都健康嗎？
固定版本來源
- v2.0.55 Plugin lifecycle、built-ins、限制與官方文件
- v2.0.55 Plugin REST、secret redaction 與安裝限制原始碼
- v2.0.55 timeout、circuit breaker 與 in-process 限制
- v2.0.55 schema secret、context 與 lifecycle types
- v2.0.55 WebSocket 路徑與 message handling
- v2.0.55 logs query、buffer 與 stream 原始碼
- v2.0.55 JSON／Prometheus metrics 原始碼
- v2.0.55 liveness 與 readiness 定義