wp-interactivity-api

wp-interactivity-api 技能總覽

這個技能能做什麼

wp-interactivity-api 技能可幫你在不靠猜測 directive、store 結構或 server/client 串接方式的情況下，建立或除錯 WordPress Interactivity API 功能。當你正在處理 data-wp-* 標記、@wordpress/interactivity、viewScriptModule 或 wp_interactivity_*() 函式，並且需要一條從壞掉的互動行為走到可運作版本的實際路徑時，它特別有用。

這個技能適合誰

如果你在 WordPress 的 block、theme 或 plugin 中做 Frontend Development，並且需要能順利通過首次渲染的互動式 UI，就很適合使用 wp-interactivity-api skill。當你已經有一個 repo，並且需要追查 hydration 為什麼失敗、為什麼 directive 沒有觸發，或如何正確組織新的互動區域時，它尤其合適。

為什麼值得安裝

它的核心價值是幫你更快做判斷：應該查什麼、哪些輸入最重要，以及如何把 block 導向、theme 層級和 plugin 增強這幾種做法分開看。這讓 wp-interactivity-api 指南比一般泛用提示更有用，因為它反映的是 WordPress 6.9+ 的真實限制，以及這個 API 的實際串接方式。

如何使用 wp-interactivity-api 技能

正確安裝與限定作用範圍

先依照目錄入口的 wp-interactivity-api install 模式安裝，接著在具備 bash 與 Node、且能存取檔案系統的 agent session 中使用這個技能。倉庫說明提到相容 WordPress 6.9+，而且部分工作流程也會用到 WP-CLI；如果你的環境無法檢查專案檔案或執行 WordPress 指令，結果通常會比較弱。

提供正確的起始輸入

wp-interactivity-api usage 在你提供以下資訊時表現最好：

• repo root
• 來自 wp-project-triage 的分流結果
• 受影響的範圍：frontend、editor，或兩者
• WordPress 版本與任何 module/build 限制

較弱的提示是：Fix the Interactivity API.
較好的提示是：Debug why data-wp-on--click does not fire in this block on the frontend, WordPress 6.9, module scripts enabled, triage attached, and the issue only appears after navigation.

先讀這些檔案

先從 SKILL.md 開始，再打開：

• references/directives-quickref.md：看 directive 名稱與搜尋錨點
• references/debugging.md：看失敗檢查清單
• references/server-side-rendering.md：看 PHP 端設定與 hydration 規則

如果你正在判斷這個技能是否適合目前任務，這三個檔案會比只看 repo tree 更快讓你看懂實際工作流程。

依照實務流程處理

這個技能是圍繞著一個簡單順序來組織的：

1. 透過搜尋 data-wp-interactive、@wordpress/interactivity 與 viewScriptModule 找出既有用法
2. 辨識 store namespace，以及 markup 是否期待相同名稱
3. 驗證 server-rendered context 與初始 state
4. 檢查 rendered HTML 裡是否同時存在 root element、view script module 與 event directives
5. 縮小範圍，直到壞掉的 directive 或 state path 被單獨定位出來

如果是新的互動式 block，優先使用官方 scaffold template，不要從零硬造結構。

wp-interactivity-api 技能 FAQ

這個技能只適合除錯嗎？

不是。wp-interactivity-api skill 同時涵蓋建立與除錯工作。當你需要決定要透過 block viewScriptModule 加入互動功能、在 plugin 中增強既有標記，或以能正確 hydration 的方式串接 theme 層級行為時，它都很有幫助。

它和一般提示有什麼不同？

一般提示常會跳過真正決定成敗的 WordPress 細節：directive 命名、store namespace 是否一致、server-side context，以及 WordPress 6.9 的行為變更。這個技能把這些檢查內建進去，能減少白走的路，也能幫 agent 先讀對檔案。

對新手友善嗎？

可以，只要你能說清楚目標，並把 agent 指到正確的 repo 區域。它不是從零學完整 API 的教學，但能幫新手避開最常見的導入錯誤：互動 root 遺漏、namespace 不一致，以及用了錯誤的 render 路徑。

什麼情況不適合使用？

如果是 WordPress Interactivity API 之外的 JavaScript UI 工作，或者你的功能完全是靜態、不需要 server-rendered directives，就不適合用它。當你無法檢查實際 repo 檔案時，它也不是好選擇，因為這個技能仰賴 repo 專屬的標記與 PHP/JS 整合細節。

如何改進 wp-interactivity-api 技能

提供更精準的來源上下文

最好的結果來自同時提供目前的 block、theme 或 plugin 介面，以及你想檢查的確切 directive 或 function。把 data-wp-interactive、data-wp-context 與對應的 store namespace 周邊片段一起貼上，讓 agent 能直接比對意圖與實作，而不是自行推測。

說明失敗模式，不要只講症狀

對 wp-interactivity-api skill 來說，button does nothing 太模糊了。更好的輸入會直接寫出可觀察到的失敗與預期行為，例如：click handler is bound but state does not update after server render，或 hydration works on first load but fails after client-side navigation。這能幫你區分 directive 問題、state 初始化問題，或 module 載入問題。

先要求 repository-reading 輸出，再逐步迭代

一個好的 wp-interactivity-api guide 工作流程，是先要求：

• 可能的根因
• 下一步應該檢查的精確檔案
• 最小修改範圍的程式碼變更
• 任何 WordPress 6.9 相容性風險

接著帶著第一輪結果繼續迭代。如果問題是 server rendering，請附上相關 PHP 與 rendered HTML；如果是事件處理，請附上 directive 標記與 store actions 檔案。這樣就能把技能從搜尋輔助，變成可直接執行的實作檢查清單。