WoowTech · AI Agent Handbook

研究、撰寫與交付 Node-RED 教材的完整 Skill

本規格約束 agent 的來源、產品邊界、Flow、安全、品牌、品質閘門與交付權限。關鍵字 MUST 是無條件要求；STOP 表示停止產出推測或停止任何變更，交由具權限的人決定。

來源優先序與衝突

MUST 1：exact-tag 原始碼。依序使用 Community App：22.0.1（repository tag v22.0.1）、Node-RED 5.0.2、HA WS v0.80.3、FlowFuse Dashboard v1.30.2 的固定 commit。
MUST 2：同版官方文件與 release note。只能補充固定來源可支持的使用者說明，不用 rolling latest 覆蓋 exact tag。
MUST 3：實機唯讀觀察。只能描述該環境看見的 UI，不外推成普遍能力。
STOP：來源衝突時建立主張／來源／差異／待驗證紀錄；無法解決就降級為限制，不自行猜測。

產品邊界

層	固定版本	可主張範圍
Community App	22.0.1	容器、Add-on schema、啟動、Ingress、綑綁依賴
Node-RED	5.0.2	editor、runtime、core node、msg、Context、Deploy、Projects
HA WebSocket	0.80.3	HA config 與事件、狀態、action 等註冊節點
FlowFuse Dashboard 2	1.30.2	僅選裝 package；MUST 標示 optional nonbundled

STOP：不得把四個版本互換，不得把選裝功能說成 Add-on 內建，不得引用舊 dashboard 當建議方案。

Feature manifest 契約

以下是完整欄位形狀的代表項目，不是 source of truth；實際內容一律以 data/node-red-22.0.1-feature-manifest.json 與 scripts/check_feature_manifest.js 為準。

{
  "id": "addon-option-log-level",
  "layer": "add-on",
  "feature": "log_level：Supervisor log level schema（trace 至 fatal，可省略）",
  "version": "22.0.1",
  "source": "https://github.com/hassio-addons/app-node-red/blob/bcfd5b83d3d322dc12a7bd2a310ca705c130b419/node-red/config.yaml",
  "sourceId": "app-node-red-22.0.1",
  "sourcePath": "node-red/config.yaml",
  "chapters": [2, 22],
  "status": "covered",
  "securityNotes": "較詳細的 log 可能暴露訊息內容；排障後降回必要等級。"
}

layer 只接受 add-on、node-red、ha-websocket、optional；status 只接受 planned 或 covered。

MUST 先由 source lock 建 manifest，再寫正文；目前 gate 要求精確 116 項。
每個具體能力、預設值、node type 與版本主張必須可反查 evidence。
新增或移除主張時同步更新 manifest、章節與檢查，不得只改文案。

22 章作者規格

MUST 依 chapters.json 的精確 22 筆順序、標題、part 與檔名；head、sidebar、pager、footer 由 build_nav.js 擁有。
每章 8–12 個具 id／data-nav 的 section，固定含 troubleshoot、至少四則 FAQ 與 pinned sources。
先說心智模型與安全邊界，再給步驟、測試、失敗路徑及回復；台灣繁體中文，稱讀者為「你」。
資料表使用 data-table；標題層級、skip link、main landmark、焦點、44px target、320／360px 都要驗收。

安全 Flow JSON

MUST

輸出可匯入的 JSON array、唯一 id、合法 tab 與無 dangling wire。
server、entity、device、area、URL、broker、topic 一律用明確 PLACEHOLDER。
HTTP、MQTT、HA action 等副作用 node 預設 disabled，附人工啟用前提。
README 記錄來源章節、預期輸入／輸出、風險、匯入、測試與清理。

STOP

發現 token、password、credential、私有 IP、hostname 或真實 HA identifier。
Flow 自動啟動、無界重試、無 timeout，或可能重複控制設備。
未知第三方 node type、無來源版本、缺 config reference 或安全回復。
不得為了通過 gate 放寬 checker 或藏值於編碼、註解、名稱。

事實、安全與編輯審查

Factual MUST

逐段列主張與 exact evidence；搜尋「一定、全部、保證、預設、最快」，沒有同版證據就改為條件式或 STOP。

Security MUST

執行敏感掃描、Flow gate，再人工查秘密、識別值、外部 endpoint、副作用、回復與批准。

Editorial MUST

不用 emoji；術語一致；不以暫存骨架或未來式描述已交付內容；連結具非色彩提示，程式碼與表格可捲動。

Accessibility MUST

語意 landmark、可見焦點、鍵盤操作、live status、明確 link text、320／360px 無整頁橫向溢位。

唯讀截圖

規劃：列出要證明的 UI、允許的唯讀動作與敏感欄位。
擷取：只能導航、搜尋、展開；不得 Create、Save、Deploy、Delete、Kick、觸發 Inject 或呼叫 action。
隔離：原始圖放 gitignored raw/probe 目錄，不得直接成為 public asset。
遮蔽：處理 token、URL、IP、entity/device/area、client ID、topic、使用者與 EXIF。
雙人 gate：第二人 100% 檢查畫面、檔名、周邊文字與 metadata 後才可發布。

WoowTech 品牌與下載

MUST 使用 #6183FC spot color、20px card、Poppins／Outfit／Noto Sans TC 字型策略與既有共用 CSS。
MUST 維持完整 SEO／OG 1200×630、相同 topnav、aria-current、skip link、main 與商標聲明。
三份單頁下載 MUST 由 build_downloads.js 產生，內嵌 CSS、系統字型、無外部 CSS／font／script；提示詞 inline JS 必須保留。
22 章是多頁，下載 MUST 指向 GitHub main archive ZIP，不宣稱單頁離線。

品質閘門與 STOP 規則

node scripts/build_downloads.js --check
node scripts/build_nav.js --check
node scripts/check_links.js
node scripts/check_content.js
node scripts/check_flow_examples.js
node scripts/check_feature_manifest.js
node scripts/check_sensitive.js
node scripts/check_downloads.js
node scripts/check_resource_hub.js
node scripts/check_dockerfile.js
node scripts/test_checks.js
node scripts/validate_responsive.js

MUST 全部 exit 0，再檢查 diff、未追蹤檔、頁面內容、桌面與手機。
任何 gate 失敗、版本未知、秘密命中、來源衝突、Flow 副作用未核准時立即 STOP。
不得刪測試、改 allowlist、略過命令或用人工說「看起來正常」取代可重現證據。

部署權限與輸出契約

STOP：本 Skill 不授權 remote push、GitHub Pages、Cloudflare、custom domain、Home Assistant 或任何正式環境部署。Agent 只能在核准 repository 與分支產出、檢查及提交；發布由明確具權限的人另外批准。

每次輸出 MUST 包含

變更檔案與目的；固定版本與來源摘要；新增／更新的內容計數。
所有命令、退出碼、關鍵輸出；未執行項目及原因。
Flow／下載／Docker／responsive／敏感資料 gate 結果。
commit SHA、工作樹與 staging 狀態、殘餘瀏覽器／runtime／部署風險。

研究、撰寫與交付 Node-RED 教材的完整 Skill

來源優先序與衝突

產品邊界

Feature manifest 契約

22 章作者規格

安全 Flow JSON

MUST

STOP

事實、安全與編輯審查

Factual MUST

Security MUST

Editorial MUST

Accessibility MUST

唯讀截圖

WoowTech 品牌與下載

品質閘門與 STOP 規則

部署權限與輸出契約

每次輸出 MUST 包含

交付前檢查表

內容

安全與發布