EMQX 指南

獨立 Agent Handbook · EMQX 5.8.9

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

這份手冊可直接交給研究或寫作 agent。工作事實邊界固定為 EMQX 5.8.9、官方文件 docs.emqx.com/en/emqx/v5.8，add-on 以 WOOWTECH/Woow_ha_emqx 的 emqx/ 為準。

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

你的任務

  • 只寫可由官方 v5.8 文件、Woow_ha_emqx 原始碼，或實機唯讀觀察支持的主張。
  • 使用台灣繁體中文，稱讀者為「你」，先解釋名詞，再給家庭情境，最後才寫步驟。
  • 把系統描述為「MQTT broker」，不是「無所不能的平台」；叢集只做概念與監控。
  • 明確標示每個功能的選單路徑、預設值與成熟度。

禁止事項

  • 不得把 EMQX 4.x 的「Modules」「Data Bridge」寫成 5.x 建議寫法。
  • 不得把 add-on 5.9.0 當成 EMQX 版本（5.9.0 只加 ngrok TCP 通道）。
  • 不得為截圖執行 Create、Delete、Save、Kick、Disconnect 等變更操作。
  • 不得公開 MQTT 密碼、client ID、API key、ngrok authtoken、TLS 私鑰、連線字串。

來源優先序與衝突處理

  1. Woow_ha_emqx 原始碼／README：最高優先，用於 add-on 安裝、env_vars、host_network 與連接埠事實。
  2. EMQX v5.8 官方文件：Dashboard 模組、預設值、Authentication／ACL／Listener／Rule／Connector 等使用者操作事實。
  3. 實機唯讀觀察：只證明「這個環境看見什麼」，不能單獨證明普遍支援，也不得在線上建立／刪除任何設定。
  4. 同版本釋出說明：用於版本行為與限制；與文件不一致時以可到達的官方來源為準並註記。
衝突規則：不要自行調和。建立「主張、來源 A、來源 B、採用結論、仍待驗證」紀錄；無法解決時把文字降級成限制或待驗證。

Feature Manifest 工作法

研究前先建功能清單再寫章節。每列至少包含：feature_id、名稱、章節、成熟度、來源、驗證狀態、限制與安全註記。

feature_id: [穩定識別]
version: 5.8.9
channel: [正式 | 實驗性 | 僅概念]
dashboard_module: [是 | 否]
security: [需在 UI 設定 | 屬概念]
evidence:
  - [官方文件 URL]
limitations: [限制]
redact: [需要遮蔽的欄位]

唯讀截圖與遮蔽

  1. 規劃：先寫截圖目的、頁面、需要證明的 UI 狀態與可能敏感欄位。
  2. 唯讀導覽：只開啟無副作用分頁、搜尋、展開區塊；禁止任何改變狀態的按鈕。
  3. 原始檔隔離：首次截圖只存 gitignored artifacts/raw-screenshots/。
  4. 遮蔽：遮蔽 MQTT 密碼、client ID、username、API key、ngrok authtoken、TLS 私鑰、連線字串與私有 IP。
  5. 雙人檢查：第二人以 100% 放大檢查畫面、檔名、EXIF 與周邊文字，確認後才放進公開資產。
紅線：不要為了「更漂亮的畫面」按 Create／Delete／Save／Kick。缺畫面就用文字與可驗證示意結構，不仿造產品 UI 或 logo。

22 章作者分工與骨架

篇章章節核心交付
基礎01–04認識、安裝、Dashboard、MQTT 心智模型。
存取控制05–08連線、Authentication、Authorization、Listener／TLS。
規則與整合09–13Rule Engine、動作、Connector／Sink／Source、HA 整合。
維運14–22客戶端、監控、訊息、設定、Log／API、ngrok、備份、安全、排錯。

每章硬性骨架

事實、安全、編輯與可及性審查

Factual review

  • 逐段標出可驗證主張與來源；版本、預設值、UI 路徑逐項核對。
  • 搜尋「一定、完整、所有、保證、一律」並要求證據或改寫。
  • 確認 add-on 版本 5.9.0 與 EMQX 5.8.9 用語一致。

Security review

  • 執行敏感資料掃描並人工查密碼、token、IP、hostname。
  • 高風險動作前必須有備份、影響、批准與回復。
  • 認證不得誤寫成任意防護；公開 1883 前說明風險。

Editorial review

  • 台灣繁體中文、稱「你」、無 emoji、無翻譯腔。
  • 首次技術詞採中文（English），之後一致。
  • 表格與程式碼在手機可橫向捲動。

Accessibility review

  • 標題階層、landmark、連結文字與表頭語意正確。
  • 鍵盤焦點可見，互動目標至少 44px。
  • 320／360px 不產生整頁水平捲動。

驗證命令與失敗處理

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

部署與交付

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

固定來源