使用 meta 的 NEEO 驅動程式
meta (jac459/meta) 是一個 Node.js 引擎，它從 active/ 資料夾讀取 JSON 裝置檔案，並將每個檔案轉換為註冊在本機 NEEO Brain 上的 NEEO SDK 驅動程式。您使用 JSON 描述裝置；無需撰寫 JavaScript（除了小型 DYNAMIK 表達式）。
語言：以使用者使用的語言與其溝通。JSON 鍵、引擎關鍵字、按鈕名稱和日誌字串完全按照此處（英文）記錄的方式保留。
範圍：僅關注收購前的 NEEO SDK、本機 Brain 和 meta。忽略 Control4 相關內容和 NEEO 雲端（已關閉）。
基本規則（永不跳過）
- 絕不發明 JSON 鍵或命令類型。 如果參考資料中沒有某項功能，請說明並提供替代方案：配套服務（Node-RED + MQTT，或小型本機 REST 橋接器，請參閱
references/companion-services.md）、cli命令或隱藏按鈕鏈。 - 純 JSON：無註解、無尾部逗號、使用雙引號。使用
python3 -m json.tool file.json和python3 scripts/check_driver.py file.json進行驗證。 - 命令類型區分大小寫：
http-get、http-rest、http-post、http-get-soap、static、cli、repl、webSocket、socketIO、jsontcp、mqtt、wol、mDNS、android。 - 新增可見元件時，請增加
version。Brain 只會新增元件；重新命名或移除元件需要在 NEEO 應用程式中刪除並重新新增裝置（食譜和捷徑必須重新製作）。即使增加版本號，已安裝的裝置有時也不夠：請檢查 Brain（references/debugging.md）。 - 標籤、開關、滑桿、圖片和感測器的名稱（鍵）：僅限字母和數字。 空格或符號會中斷感測器連結（Brain 中的
"sensor": null），並且在遙控器同步時，只要該元件被用作捷徑就會崩潰。顯示的label文字則不受限制。按鈕名稱可以包含空格，但請避免使用+和重音符號（DISNEY PLUS，標籤Disney+）。 - 絕不將
""寫入綁定到標籤的變數：在 meta v1.2.0 上，標籤從文字回到""會導致 meta 停止。請寫入" "（或可讀的回退值）。養成習慣，將標籤變數初始化為" "。 - 在進入標籤之前，淨化所有外部文字：
"->'，\->/，控制字元 -> 空格，$->＄（全形）。在驅動程式和來源端都執行此操作。 - 監聽器透過
ListenerOn防護 + 隱藏的__LISTEN按鈕（連接到每個可見的控制項）在每個會話開始時啟動一次。 永遠不要依賴POWER ON單獨啟動，也永遠不要在mqtt監聽器上呼叫__CLEANUP（請參閱references/listeners-and-state.md）。 - 事件優於輪詢（
webSocket、socketIO、mqtt）。如果需要輪詢，pooltime應 >=3000。 $Result始終是字串，失敗時為"undefined"：對每個JSON.parse進行防護。按鈕接收純量（ok）；目錄動作饋送器接收["ok"]。- 變數名稱：絕不使用會成為另一個變數前綴的名稱；
$Var與字母相連會被視為不同的變數。 - 安全性：
DYNAMIK和cli會在 meta 主機上執行程式碼。設計為共用的驅動程式中切勿硬編碼機密資訊；meta 不得以 root/admin 身份執行。 - 不可逆的變更需要同意：新增可見元件（例如
DIGIT 0-9）無法在不重新安裝裝置的情況下撤銷。請先詢問。 - 區分交付物：meta 驅動程式是一個 JSON 物件（以
{開頭，名稱中不含-flow，放在active/中）；Node-RED 流程是一個 JSON 列表（以[開頭，名稱始終為*-flow.json，匯入到 Node-RED 中）。 - 在
template中，dynamicname和dynamicid是必需的；dynamicid必須是穩定的（MAC 位址或硬體 ID，而非 DHCP IP）。
工作流程
- 收集所需資訊（每次最多提出 3 個有針對性的問題）：確切的裝置型號；其控制協定或 API（HTTP/REST、WebSocket、原始 TCP、MQTT、僅 IR、Android TV...）；是否為固定 IP 以及穩定的 ID（MAC）；必須控制什麼以及必須顯示什麼狀態；meta 版本以及 meta 執行的位置（帶有 pm2 的 Pi、Docker...）；是否有可用的 MQTT 代理和 Node-RED。如果存在，請查閱裝置的官方 API 文件。
- 選擇 NEEO 類型（
references/driver-anatomy.md，類型和已識別的按鈕部分）和探索模式（references/discovery.md）：靜態單一裝置、使用者輸入 IP、mDNS 或中樞。 - 從
assets/中的骨架開始：skeleton-static.json（一個裝置，固定位址）或skeleton-register-ip.json（使用者輸入 IP）。重複使用references/patterns.md中經過驗證的模式。 - 決定邏輯所在位置。 簡單的 HTTP 或 WebSocket 裝置：所有邏輯都在驅動程式中。二進位或有狀態的協定（原始 TCP、持久會話、配對、突發狀態）：在中間放置一個配套服務，使用快速的 HTTP 指令，並將狀態推送為保留的 MQTT 訊息（
references/companion-services.md）。 - 交付前檢查：
python3 -m json.tool driver.json然後執行python3 scripts/check_driver.py driver.json（名稱、空的標籤值、類型、版本、防護、輪詢...）；- 當驅動程式有監聽器時，執行
node scripts/simulate_guard.js driver.json（計算跨會話的__INITIALISE/__CLEANUP次數）； - 使用真實的替換規則在 Node 中評估棘手的
DYNAMIK表達式（references/logic-and-commands.md）； - 重新閱讀
references/pitfalls.md。
- 按以下順序交付：摘要（裝置、協定、NEEO 類型、探索模式、涵蓋/未涵蓋的內容）；包含明確檔案名稱的完整驗證 JSON 檔案；部署步驟（複製到
active/，重新啟動 meta，在 NEEO 應用程式中新增裝置，建立食譜的可見性和捷徑）；測試計劃（要嘗試的按鈕、預期結果、要查找的日誌行）；未在真實裝置上驗證的假設；下一次迭代。對於多檔案專案（驅動程式 + 流程 + 服務）：操作順序、每個交付物中的版本標記，以及如何檢查已安裝的版本。始終說明未在真實裝置上測試的內容。
參考資料對應表（僅閱讀任務所需）
| 文件 | 何時閱讀 |
|---|---|
references/meta-engine.md | 架構、安裝、資料夾、重新啟動、日誌級別、meta 公開的 MQTT 主題、Docker/NAS 託管、已知的 meta v1.2.0 錯誤 |
references/driver-anatomy.md | 頂層鍵、NEEO 裝置類型和已識別的按鈕名稱、變數、$ 替換、DYNAMIK、UI 元件 |
references/logic-and-commands.md | evalwrite、evaldo、evalnext、特殊按鈕、每種命令類型、queryresult / JSONPath |
references/listeners-and-state.md | 監聽器、ListenerOn 防護、MQTT 監聽器行為、突發狀態來源、實例重建 |
references/discovery.md | discover、register、template、initcommandset、mDNS、IP 輸入、中樞、配對 |
references/directories.md | 列表、饋送器、item* 欄位、動作、多層級導航 |
references/patterns.md | 經過驗證的食譜：音量、電源、狀態列、持久性、鏈、迴圈、回退路徑、應用程式啟動器、藝術圖片 |
references/pitfalls.md | 交付前必須重新閱讀 |
references/debugging.md | 讀取 meta、Mosquitto 和 Brain 資料、日誌特徵、隔離連結、沙箱測試 |
references/companion-services.md | Node-RED 和 MQTT 橋接器、本機 REST 橋接器、Apple TV / pyatv 經驗教訓 |
references/community-drivers.md | 可供模仿的參考驅動程式、SDK <-> meta 對應、來源 |
參考資料中使用的證據標籤
[code v1.2.0] 從 meta 原始碼中讀取（分支 Release）；[observed] 在真實驅動程式或真實安裝中觀察到；[to verify] 尚未測試的推論。當某個行為很重要且未標記時，請檢查 meta 的程式碼（git clone --depth 1 --branch Release https://github.com/jac459/meta）而不是猜測，並說明您做了哪種操作。