wp-abilities-api

Name: wp-abilities-api
Author: wordpress

WP Abilities API

使用時機

當任務涉及以下內容時，請使用此 Skill：

在 PHP 中註冊能力（abilities）或能力分類（ability categories）
透過 REST (wp-abilities/v1) 將能力提供給客戶端
在 JS 中呼叫或使用能力（特別是 @wordpress/abilities）
排查「能力未顯示」、「客戶端看不到能力」或「REST 回傳空白」等問題

必要前置資訊

專案根目錄（若尚未執行，請先執行 wp-project-triage）。
目標 WordPress 版本，以及此專案屬於 WP 核心、外掛（plugin）或佈景主題（theme）。
變更應放置的位置（外掛 vs 佈景主題 vs mu-plugin）。

執行流程

在決定要註冊哪些內容之前，請先閱讀 references/domain-vs-projection.md——能力（abilities）位於領域能力層（domain capability layer），而 MCP、命令面板（Command Palette）與 REST 端點開放則屬於投影（projection）。註冊結構與開放結構是不同的決策，若將兩者混為一談，每當使用端的限制改變時，就必須重新註冊。

1) 確認可用性與版本限制

若為 WP 核心開發任務，請檢查 signals.isWpCoreCheckout 與 versions.wordpress.core。
若專案目標版本為 WP < 6.9，可能需要搭配 Abilities API 外掛/套件，而非依賴核心。

2) 搜尋現有的 Abilities 用法

在專案庫中搜尋以下項目：

wp_register_ability(
wp_register_ability_category(
wp_abilities_api_init
wp_abilities_api_categories_init
wp-abilities/v1
@wordpress/abilities

若完全找不到，請決定是要全新引進 Abilities API（包含新註冊與客戶端呼叫），或是僅需呼叫現有能力。

3) 註冊分類（選填）

若需要邏輯分組，請先註冊能力分類（參閱 references/php-registration.md）。

4) 在 PHP 中註冊能力

關於分組決策（要註冊多少個能力，以及何時使用 Filter vs 新建能力名稱），請先閱讀 references/grouping-heuristic.md——這能避免你為每個 REST 操作都發布一個過於微小的能力。

為避免能力定義與現有 UI / REST 程式碼路徑產生偏差，請參閱 references/shared-core-service.md——能力、REST 處理器（REST handlers）、CLI 命令與 UI 控制器都應作為共享服務（shared service）的薄轉接層（thin adapters）。該參考文件也涵蓋了指標陷阱（會發送使用遙測資料的 REST 處理器），以及當底層程式碼路徑變更時保持註冊同步的 AGENTS.md 規則。

當多個 execute 回呼函式委派給現有 REST 控制器時，關於共享 Helper 的模式，請參閱 references/plugin-family-patterns.md（識別 shared-API-client 與 zero-arg-controllers 的架構）以及 references/delegate-helper-pattern.md（可行的 Helper 架構以及何時不該使用）。

關於標準化的 WP_Error 錯誤碼（讓 Agent 能據以判斷重試或升級處理），請參閱 references/error-code-vocabulary.md。

使用 PHP 註冊實現能力，並包含以下設定：

穩定的 id（帶有名稱空間 namespaced）
label/description
category
meta：
- 當能力僅供資訊查詢時，加上 readonly: true
- 對於希望對客戶端公開的能力，設定 show_in_rest: true

請使用文件指定的 init Hook 進行 Abilities API 註冊，以確保它們在正確的時機載入（參閱 references/php-registration.md）。

5) 確認 REST 開放狀態

驗證 REST 端點存在且回傳預期結果（參閱 references/rest-api.md）。
若客戶端仍看不到能力，請確認 meta.show_in_rest 已啟用，且查詢的端點正確無誤。

6) 從 JS 呼叫與使用（若需要）

優先使用 @wordpress/abilities API 進行客戶端存取與檢查。
確保建置工具已包含此相依套件，且專案的打包流程（build pipeline）已將其打包。

驗證方式

變更完成後，wp-project-triage 應顯示 signals.usesAbilitiesApi: true（若適用）。
REST 檢查（在 WP 環境中）：wp-abilities/v1 下的端點在預期情況下會回傳你的能力與分類。
若專案庫包含測試，請在以下位置新增/更新測試涵蓋率：
- PHP：能力註冊與 meta 開放狀態
- JS：能力呼叫與 UI 顯示控制

異常狀況與除錯

能力完全未出現：
- 註冊程式碼未執行（Hook 錯誤 / 檔案未載入）
- 漏設 meta.show_in_rest
- 分類 / ID 不匹配
REST 顯示能力，但 JS 看不到：
- REST base / namespace 設定錯誤
- 未打包 JS 相依套件
- 快取（物件快取/頁面快取）遮蔽了變更
Execute 回呼函式回傳非預期錯誤或靜默忽略輸入：
- 未套用 input_schema 預設值、能力與底層之間的頁碼金鑰（pagination key）偏移，或基於 empty() 的 ID 驗證——參閱 references/input-schema-gotchas.md。