wp-abilities-api

WP Abilities API

适用场景

当任务包含以下内容时使用本 Skill：

• 在 PHP 中注册 Ability（能力）或 Ability 分类；
• 通过 REST API (wp-abilities/v1) 向客户端暴露 Ability；
• 在 JS 中调用 Ability（尤其是使用 @wordpress/abilities）；
• 排查“Ability 未显示” / “客户端看不到 Ability” / “REST 返回为空”等问题。

前置输入需求

• 项目根目录路径（若尚未运行，请先执行 wp-project-triage）。
• 目标 WordPress 版本，以及当前项目是 WP Core 还是插件/主题。
• 改动生效位置（插件 vs 主题 vs mu-plugin）。

执行流程

在决定要注册什么之前，请先阅读 references/domain-vs-projection.md —— Ability 存在于领域能力层（domain capability layer），而 MCP / 命令面板（Command Palette）/ REST API 暴露则属于投影（projection）。注册结构与暴露结构属于不同的设计决策，将二者混为一谈会导致每次前端消费端约束变更时都不得不重新注册。

1) 确认可用性与版本约束

• 如果是在 WP Core 中工作，请检查 signals.isWpCoreCheckout 和 versions.wordpress.core。
• 如果项目目标版本为 WP < 6.9，可能需要安装 Abilities API 插件/包，而不是依赖 Core 内置实现。

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) 注册分类（可选）

如果需要逻辑分组，请提前注册 Ability 分类（参见 references/php-registration.md）。

4) 在 PHP 中注册 Ability

关于分组决策（注册多少个 Ability，以及在何处使用 Filter 扩展与新建 Ability 名称），请先阅读 references/grouping-heuristic.md —— 这能避免为你每一个 REST 操作都盲目发布一个原子化的 Ability。

为避免 Ability 与现有 UI / REST 代码路径发生漂移，请参阅 references/shared-core-service.md —— Ability、REST 句柄、CLI 命令和 UI 控制器都应当作为共享服务（shared service）之上的薄适配层。该参考文档还指出了指标陷阱（例如触发使用情况遥测的 REST 句柄），以及在底层代码路径变更时保持注册同步的 AGENTS.md 规范。

当多个执行回调函数委派给现有的 REST 控制器时，如需了解共享 Helper 模式，请参阅 references/plugin-family-patterns.md（识别 shared-API-client 与 zero-arg-controllers 两种形态）和 references/delegate-helper-pattern.md（一种行之有效的 Helper 形态及其不适用场景）。

关于帮助 Agent 判断重试还是向上抛出异常的标准 WP_Error 错误码，请参阅 references/error-code-vocabulary.md。

在 PHP 注册中实现 Ability 时需包含：

• 稳定的 id（带有命名空间）；
• label/description（标签/描述）；
• category（分类）；
• meta：
  • 当 Ability 仅用于提供信息时，添加 readonly: true；
  • 对于希望向客户端展示的 Ability，设置 show_in_rest: true。

请使用文档指定的 init Hook 进行 Abilities API 注册，以确保它们在正确的时间加载（参见 references/php-registration.md）。

5) 确认 REST 接口暴露状态

• 验证 REST Endpoint 是否正常存在并返回预期结果（参见 references/rest-api.md）。
• 如果客户端依然看不到 Ability，请检查 meta.show_in_rest 是否已启用，并确认请求的 Endpoint 路径是否正确。

6) 在 JS 端调用（如需要）

• 客户端访问与权限检查优先使用 @wordpress/abilities 提供的 API。
• 确保构建工具已包含该依赖，并且项目的构建流水线已将其正确打包。

验证方式

• 执行变更后，wp-project-triage 的结果显示 signals.usesAbilitiesApi: true（如适用）。
• REST 检查（在 WP 环境下）：wp-abilities/v1 下的 Endpoint 能按预期返回对应的 Ability 和 Category。
• 如果代码库包含测试用例，请在以下位置添加/更新测试覆盖：
  • PHP：Ability 注册及 Meta 暴露；
  • JS：Ability 调用与 UI 权限拦截。

常见失败场景与排查

• Ability 完全未显示：
  • 注册代码未运行（使用了错误的 Hook / 文件未载入）；
  • 遗漏了 meta.show_in_rest；
  • 分类（Category）或 ID 匹配错误。
• REST 能查到 Ability 但 JS 中查不到：
  • REST base / namespace 填写错误；
  • JS 依赖未打包进产物；
  • 缓存（对象缓存/页面缓存）导致变更未即时生效。
• 执行回调（Execute callback）返回异常错误或静默忽略输入：
  • input_schema 默认值未生效、Ability 与底层实现之间的分页键（pagination key）漂移，或使用了基于 empty() 的 ID 校验机制 —— 详见 references/input-schema-gotchas.md。

升级与寻求支持

• 如果对版本支持不确定，请确认目标 WP Core 版本，以及 Abilities API 是预期由 Core 内置提供还是通过插件引入。
• 权威细节请查阅：
  • references/rest-api.md
  • references/php-registration.md