用途:当任务涉及 WordPress Abilities API 时使用,包括在 PHP 中注册能力(wp_register_ability)或能力分类(wp_register_ability_category)、通过 wp-abilities/v1 REST 命名空间暴露能力、在 JS 中借助 @wordpress/abilities 消费能力,以及诊断“能力不出现”“客户端看不到能力”“REST 返回空”等故障。
必要输入:仓库根目录(未运行过可先执行 wp-project-triage)、目标 WordPress 版本及项目属于 WP 核心还是插件/主题、变更应放置的位置(插件、主题或 mu-plugin)。
主要流程:先阅读 references/domain-vs-projection.md,明确能力属于领域能力层,而 MCP、命令面板、REST 暴露只是投影,注册形态与暴露形态是不同决策;再确认可用性与版本约束(WP 核心工作需检查 signals.isWpCoreCheckout 与 versions.wordpress.core,目标低于 WP 6.9 时可能需用 Abilities API 插件/包);随后在仓库中搜索 wp_register_ability(、wp_register_ability_category(、wp_abilities_api_init、wp_abilities_api_categories_init、wp-abilities/v1、@wordpress/abilities 以判断现有用法;必要时先注册分类,再在文档规定的初始化钩子上注册能力,包含带命名空间的稳定 id、label/description、category,以及 meta(信息型能力设 readonly: true,需对客户端可见则设 show_in_rest: true)。注册前可参考 references/grouping-heuristic.md 决定能力粒度,参考 references/shared-core-service.md 避免能力与既有 UI/REST 代码路径产生偏差,参考 references/plugin-family-patterns.md 与 references/delegate-helper-pattern.md 处理共享辅助模式,参考 references/error-code-vocabulary.md 使用标准化 WP_Error 代码。之后验证 REST 端点是否按预期返回能力与分类;如需客户端消费,优先使用 @wordpress/abilities API,并确保构建工具包含并打包该依赖。
验证与排错:变更后 wp-project-triage 的 signals.usesAbilitiesApi 应为 true;在 WP 环境中检查 wp-abilities/v1 下的端点。若能力始终不出现,检查注册代码是否运行(钩子错误或文件未加载)、是否缺少 meta.show_in_rest、分类/ID 是否不匹配;若 REST 有返回但 JS 看不到,检查 REST base/命名空间、JS 依赖是否打包、对象缓存/页面缓存是否掩盖变更;若执行回调报错或静默忽略输入,检查 input_schema 默认值、分页键漂移、基于 empty() 的 ID 校验等,详见 references/input-schema-gotchas.md。版本支持不确定时,需先确认目标 WP 核心版本及 Abilities API 来自核心还是插件。