wp-abilities-api

WP Abilities API

适用场景

在以下任务中使用此技能：

• 在 PHP 中注册能力或能力类别，
• 通过 REST（wp-abilities/v1）向客户端公开能力，
• 在 JS 中使用能力（尤其是 @wordpress/abilities），
• 诊断“能力未显示”／“客户端看不到能力”／“REST 返回空结果”。

所需输入

• 仓库根目录（如果尚未运行，请先运行 wp-project-triage）。
• 目标 WordPress 版本，以及这是 WP 核心还是插件／主题。
• 应将更改放在哪里（插件、主题还是 mu-plugin）。

流程

在决定注册什么之前，请阅读 references/domain-vs-projection.md——能力存在于领域能力层；MCP／命令面板／REST 暴露则是一种投影。注册形式和暴露形式是两个不同的决策；将它们混为一谈，会导致每当使用方的约束发生变化时都必须重新注册。

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）

在决定如何分组（注册多少个能力，以及将筛选器放在哪里，或何时新增能力名称）时，请先阅读 references/grouping-heuristic.md——它可以避免你为每个 REST 操作都发布一个原子能力。

为避免能力与现有 UI／REST 代码路径出现偏差，请参阅 references/shared-core-service.md——能力、REST 处理器、CLI 命令和 UI 控制器都应是共享服务之上的轻量适配器。该参考还涵盖了指标陷阱（发出使用情况遥测的 REST 处理器），以及用于在底层代码路径发生变化时保持注册同步的 AGENTS.md 规则。

如果多个执行回调都委托给现有 REST 控制器，并且你需要共享辅助函数模式，请参阅 references/plugin-family-patterns.md（识别共享 API 客户端与零参数控制器这两种形式）和 references/delegate-helper-pattern.md（一种可行的辅助函数形式，以及不应使用它的情况）。

有关标准化的 WP_Error 代码（可帮助 Agent 判断应该重试还是升级处理），请参阅 references/error-code-vocabulary.md。

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

• 稳定的 id（带命名空间），
• label／description，
• category，
• meta：
  • 对于提供信息的能力，添加 readonly: true，
  • 对于希望客户端可见的能力，设置 show_in_rest: true。

使用 Abilities 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 依赖未打包，
  • 缓存（对象缓存 / 页面缓存）掩盖了更改。
• 执行回调返回意外错误或静默忽略输入：
  • input_schema 默认值未应用，能力与底层实现之间的分页键不一致，或使用基于 empty() 的 ID 验证——请参阅 references/input-schema-gotchas.md。

升级处理

• 如果不确定版本支持情况，请确认目标 WP 核心版本，以及 Abilities API 应由核心提供还是作为插件提供。
• 有关规范详情，请参阅：
  • references/rest-api.md
  • references/php-registration.md