WordPress能力API技能Skill wp-abilities-api

---

name: wp-abilities-api description: “在涉及WordPress能力API（wp_register_ability、wp_register_ability_category、/wp-json/wp-abilities/v1/*、@wordpress/abilities）时使用，包括定义能力、分类、元数据、REST接口暴露以及客户端权限检查。” compatibility: “目标环境WordPress 6.9+（PHP 7.2.24+）。基于文件系统的代理，使用bash + node。部分工作流需要WP-CLI。”

WordPress能力API

使用时机

当任务涉及以下内容时使用此技能：

• 在PHP中注册能力或能力分类
• 通过REST接口（wp-abilities/v1）向客户端暴露能力
• 在JS中消费能力（特别是@wordpress/abilities）
• 诊断“能力不显示”/“客户端无法看到能力”/“REST返回空”等问题

所需输入

• 代码库根目录（如果尚未运行，请先执行wp-project-triage）
• 目标WordPress版本，以及这是WP核心还是插件/主题
• 变更应存放的位置（插件 vs 主题 vs mu-plugin）

操作流程

1) 确认可用性和版本限制

• 如果是WP核心工作，检查signals.isWpCoreCheckout和versions.wordpress.core
• 如果项目目标WP版本<6.9，可能需要使用能力API插件/包，而非依赖核心功能

2) 查找现有能力API使用情况

在代码库中搜索以下内容：

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

如果不存在，决定是全新引入能力API（新注册+客户端消费）还是仅消费现有能力

3) 注册分类（可选）

如果需要逻辑分组，尽早注册能力分类（参见references/php-registration.md）

4) 注册能力（PHP）

在PHP注册中实现能力，包含：

• 稳定的id（带命名空间）
• label/description
• category
• meta：
  • 当能力为信息性时添加readonly: true
  • 设置show_in_rest: true以使能力对客户端可见

使用文档化的初始化钩子进行能力API注册，确保在正确时机加载（参见references/php-registration.md）

5) 确认REST接口暴露

• 验证REST端点存在并返回预期结果（参见references/rest-api.md）
• 如果客户端仍无法看到能力，确认meta.show_in_rest已启用且查询了正确的端点

6) 从JS消费（如需要）

• 优先使用@wordpress/abilities API进行客户端访问和检查
• 确保构建工具包含该依赖项，且项目的构建流程已打包

验证

• wp-project-triage在变更后显示signals.usesAbilitiesApi: true（如适用）
• REST检查（在WP环境中）：wp-abilities/v1下的端点按预期返回你的能力和分类
• 如果代码库有测试，在以下位置附近添加/更新覆盖：
  • PHP：能力注册和元数据暴露
  • JS：能力消费和UI门控

故障模式/调试

• 能力从不出现：
  • 注册代码未运行（错误的钩子/文件未加载）
  • 缺少meta.show_in_rest
  • 分类/ID不匹配
• REST显示能力但JS不显示：
  • 错误的REST基础/命名空间
  • JS依赖未打包
  • 缓存（对象/页面缓存）掩盖了变更

升级处理

• 如果不确定版本支持，确认目标WP核心版本以及能力API是来自核心还是插件
• 获取规范细节，请参考：
  • references/rest-api.md
  • references/php-registration.md