Matter Hub 指南

獨立 Agent Handbook · Stable 2.0.55

研究、撰寫與交付 22 章指南的作業規格

這份手冊可直接交給研究或寫作 agent。工作邊界固定為 upstream tag v2.0.55、commit 6c8e8403d488fb06d2ac02d9199b92a0b8e8dccf，Add-on 以 pinned mirror commit a68dc435da8eb206e9efd51388d5d1ce798aefe0 為準。

角色、讀者與不可跨越的界線

你的任務

  • 只寫可由 exact-tag、同版本文件、pinned Add-on 或唯讀實機觀察支持的內容。
  • 使用台灣繁體中文，稱讀者為「你」，先解釋名詞，再給家庭／小型辦公室情境，最後才寫步驟。
  • 把 Matter Hub 描述為將 Home Assistant 實體暴露給外部 Controller 的橋接工具，不描述成 Matter Controller。
  • 每項功能分開記錄 release channel、產品成熟度與 Controller 支援。

禁止事項

  • 不得把 Alpha、Testing 或 callback architecture 寫成 Stable 功能。
  • 不得用其他版本文件填補 v2.0.55 的未知事實。
  • 不得承諾所有 Controller、裝置或網路環境相容。
  • 不得為截圖執行 Save、Create、Delete、Pair、Reset、Install、Uninstall 或 Restore。
  • 不得公開任何配對秘密、token、cookie、憑證、私有 IP 或 hostname。

來源優先序與衝突處理

  1. v2.0.55 exact-tag 程式碼與 schema：最高優先。使用固定 commit URL，記錄檔案路徑與符號。
  2. 同 tag README 與 changelog：用於安裝、公開功能與變更說明；若與 code 不同，以可到達程式碼為準並註記差異。
  3. 同 tag docs-site：補足使用情境與操作說明，不用 latest 文件取代。
  4. Pinned Add-on mirror：只支援 Add-on 安裝、Ingress、容器設定等鏡像事實。
  5. 實機唯讀觀察：只證明該環境「看見什麼」，不能單獨證明普遍支援。
衝突規則：不要自行調和。建立「主張、來源 A、來源 B、採用結論、仍待驗證」紀錄；無法解決時，把文字降級成限制或待驗證項目。

Channel、成熟度與 Controller 支援

欄位允許值寫作規則
Release channelStable／Testing／Alpha只有能在 Stable 2.0.55 到達的功能可寫入主流程；其他只能列排除邊界。
成熟度正式／實驗性／未知Server Mode 多實體、Camera／Security Plugins、部分 Matter 1.4 類型在 Stable 仍標「實驗性」。
Controller已驗證／文件宣稱／待驗證／不適用Apple、Google、Alexa、Aqara、SmartThings 分開記錄，不做橫向推論。
證據code／schema／同 tag docs／實機每個高風險或相容性主張至少附一個固定版本來源。

Feature Manifest 工作法

研究前先建功能清單，再開始寫章節。每列至少包含：feature_id、名稱、章節、release channel、成熟度、Controller、code path、schema path、文件 URL、驗證狀態、限制與安全註記。

feature_id: [穩定識別]
version: 2.0.55
channel: [stable | testing | alpha]
maturity: [正式 | 實驗性 | 未知]
controllers:
  apple: [已驗證 | 文件宣稱 | 待驗證 | 不適用]
  google: [已驗證 | 文件宣稱 | 待驗證 | 不適用]
  alexa: [已驗證 | 文件宣稱 | 待驗證 | 不適用]
  aqara: [已驗證 | 文件宣稱 | 待驗證 | 不適用]
  smartthings: [已驗證 | 文件宣稱 | 待驗證 | 不適用]
evidence:
  - [exact-commit URL]
limitations: [限制]
security: [安全註記]

22 章作者分工

篇章章節核心交付
基礎01–04角色、安裝、Dashboard、第一座 Bridge 與網路預檢。
篩選與映射05–12Filter、設定、映射、組合實體、裝置類型、Standalone／Server Mode。
Controller13–17Commissioning、multi-fabric、Apple、Google、Alexa、Aqara、SmartThings。
維運18–22Bridge 維運、Health／拓撲、網路安全、Plugins／API、備份與排錯。

每章硬性骨架

安全唯讀截圖與遮蔽

  1. 規劃：先寫截圖目的、頁面、需要證明的 UI 狀態與可能敏感欄位。
  2. 唯讀導覽：只開頁面、切換不會寫入的分頁、搜尋與展開資訊；禁止任何會改狀態的按鈕。
  3. 原始檔隔離：首次截圖只存 gitignored artifacts/raw-screenshots/，不直接放公開資產。
  4. 人工遮蔽：遮蔽 QR、配對碼、setup PIN、discriminator、Fabric／Node ID、token、cookie、憑證、IP、hostname 及可識別家庭資料。
  5. 雙人檢查：第二人以 100% 放大檢查畫面、檔名、EXIF 與周邊文字，通過後才放入 assets/screenshots/。
紅線：不要為了「取得更漂亮的畫面」按 Save、Create、Delete、Pair、Reset、Install、Uninstall 或 Restore。缺畫面就使用文字與可驗證的示意結構，不仿造產品 UI 或 logo。

事實、安全與編輯審查

Factual review

  • 逐段標出可驗證主張與來源。
  • 版本、預設值、上限、支援矩陣與 UI 路徑逐項核對。
  • 搜尋「一定、完整支援、所有、保證」並要求證據或改寫。
  • 檢查 Matter Hub／Controller、Bridge／Fabric／Endpoint 用詞是否一致。

Security review

  • 執行敏感資料掃描並人工查 QR、PIN、token、IP、hostname。
  • 高風險動作前必須有備份、影響、批准與回復。
  • Basic Auth 不得誤寫為 RBAC／SSO。
  • 預設採最小暴露、最小權限與先預覽後變更。

Editorial review

  • 台灣繁體中文、稱「你」、無 emoji、無翻譯腔。
  • 首次技術詞採中文（English），之後一致。
  • 步驟寫明位置與按鈕，限制緊接操作。
  • 表格與程式碼在手機可橫向捲動。

Accessibility review

  • 標題階層、landmark、連結文字與表格表頭語意正確。
  • 鍵盤焦點可見，互動目標至少 44px。
  • 320／360px 不產生整頁水平捲動。
  • 圖示只用版本鎖定 MDI，裝飾圖示隱藏於輔助科技。

驗證命令與失敗處理

node scripts/build_nav.js --check
node scripts/check_links.js
node scripts/check_content.js
node scripts/check_sensitive.js
node scripts/check_feature_manifest.js

部署與交付

  1. 凍結事實基準：確認 exact commit、Add-on mirror 與 manifest 一致。
  2. 完整建置檢查：執行導覽 check、連結、內容、敏感資料與 manifest 驗證。
  3. 預覽環境：以 GitHub Pages 相同 base path 測根目錄與專案子路徑，檢查 404 返回連結。
  4. 人工驗收：桌面、320px、360px、鍵盤、螢幕閱讀語意與敏感內容二次檢查。
  5. 原子提交：只提交核准範圍，記錄 SHA、變更摘要、驗證輸出、殘餘風險與回退方式。
  6. 發布後冒煙測試：檢查首頁四卡、22 章目錄、三本手冊、OG 圖、404 與外部來源。

固定來源