# Home Assistant Matter Hub Stable 2.0.55 教學撰寫規格

本規格適用於 `WOOWTECH/Woow_home_assistant_matter_hub_tutorial_site`。產品事實基準固定為 upstream tag `v2.0.55`、commit `6c8e8403d488fb06d2ac02d9199b92a0b8e8dccf`；Add-on 以 mirror commit `a68dc435da8eb206e9efd51388d5d1ce798aefe0` 為準。

## 讀者與語氣

- 使用台灣繁體中文，稱讀者為「你」，不用「您」。
- 不使用 emoji、翻譯腔或無法驗證的行銷承諾。
- 第一次出現的技術詞以「中文（English）」呈現，後續用一致名稱。
- 先解釋名詞，再給家庭或小型辦公室情境，最後才寫操作步驟。
- 不把 Matter Hub 描述成 Matter Controller；它把 Home Assistant 實體暴露給外部 Controller。

## 版本與來源

來源優先序：

1. v2.0.55 exact-tag 可到達程式碼與 schema
2. 同 tag README、changelog
3. 同 tag docs-site
4. pinned Add-on mirror
5. 實機唯讀觀察

每項功能分開標示 release channel、產品成熟度與 Controller 支援。Stable 中的 Server Mode 多實體、Camera／Security Plugins 與部分 Matter 1.4 類型仍須標示「實驗性」。Alpha、Testing 與 callback architecture 不得寫成 Stable 功能。

## 固定 HTML 骨架

```html
<!doctype html>
<html lang="zh-Hant">
<head>
</head>
<body>
<div class="layout">
  <aside class="sidebar"></aside>
  <main class="content">
    <div class="chapter-header">
      <div class="kicker">第 N 章</div>
      <h1>章節標題</h1>
      <p class="lead">這章解決的問題與讀完後的能力。</p>
    </div>
    <section id="why" data-nav="為什麼要學">
      <h2 data-icon="why">為什麼要學</h2>
      <p>內容。</p>
    </section>
    <div class="pager"></div>
  </main>
</div>
<script src="assets/js/toc.js"></script>
</body>
</html>
```

`head`、`aside.sidebar`、`div.pager` 與 footer 由 `scripts/build_nav.js` 產生，不手動維護。

## 每章硬性規格

- 8–12 個 `<section>`；每節都有唯一 `id` 與 `data-nav`。
- 每個 `<h2>` 都有 `data-icon`，值必須已定義於 `assets/css/style.css`。
- 動手做使用 `<ol class="steps">`，至少四步，寫清楚位置與按鈕。
- 比較與速查使用 `<table class="data-table">`，不使用 inline style。
- 包含 `id="troubleshoot"`，至少四個具體卡關項目。
- 包含 `id="faq"`，至少四個 `<details class="faq">`。
- 包含 `id="sources"`，列出 exact-tag code、官方文件或 pinned Add-on URL。
- 成品以充分可操作為原則，不以字數灌水。

可用 `data-icon`：`why` `concept` `what` `steps` `plan` `now` `done` `assign` `rename` `labels` `persons` `tabs` `tips` `app` `login` `test` `advanced` `faq` `troubleshoot` `url` `enter` `profile` `companion` `modes` `auto` `blueprints` `restore` `location` `remote` `hacs` `addons` `warning` `entity_id_trap` `theme` `integration` `protocol` `todo` `energy` `history` `ai` `docker` `network` `records` `hardware` `security` `compare` `cost`。

## 安全界線

- 不公開 QR payload、manual pairing code、setup PIN、commissioning passcode、discriminator、Lock PIN、Fabric/Node ID、token、cookie、憑證、私有 IP 或測試 hostname。
- 實機只做唯讀導覽；不得為截圖 Save、Create、Delete、Pair、Reset、Install、Uninstall 或 Restore。
- 首次截圖只存 gitignored `artifacts/raw-screenshots/`；人工確認遮蔽後才能放入 `assets/screenshots/`。
- Plugin 安裝、reset、restore、Fabric 移除等高風險操作必須先說明備份、影響與回復方式。
- Basic Auth 不得寫成多帳號、RBAC 或 SSO。

## 常用元件

```html
<div class="callout"><strong>觀念：</strong>中性說明。</div>
<div class="callout tip"><strong>提示：</strong>省時間的方法。</div>
<div class="callout warn"><strong>注意：</strong>常見風險。</div>
<div class="callout danger"><strong>危險：</strong>可能造成中斷或資料遺失。</div>
```

```html
<details class="faq">
  <summary>常見問題</summary>
  <div class="body">可驗證的回答。</div>
</details>
```

## 交付檢查

```bash
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
```

所有命令退出碼為 0 才能提交。章節作者只修改自己的檔案；導覽產物由整合者統一重建。