PHP API

概述

PHP API 是 Abilities API 的核心，用于在 WordPress 后端注册、管理和执行能力（Ability）。
能力可以理解为一种结构化、可被 AI / 前端 / 外部系统调用的“功能单元”。

在使用 Abilities 之前，你必须先注册「能力分类（Category）」，再注册「能力（Ability）」本身。

---

一、注册能力分类（Registering Categories）

能力分类用于对能力进行组织和分组，便于发现、筛选和管理。

函数签名

wp_register_ability_category( string $slug, array $args ): ?WP_Ability_Category

参数说明

• $slug（string）
  分类的唯一标识符
  • 只能包含：小写字母、数字、短横线
  • 不允许：大写字母、下划线、特殊符号
• $args（array）
  分类配置参数：
  • label（必填）：分类显示名称（建议使用可翻译字符串）
  • description（必填）：分类说明
  • meta（可选）：任意附加元数据

返回值

• 成功：WP_Ability_Category 实例
• 失败：null（参数非法或 slug 重复）

⚠️ 注意：必须在 wp_abilities_api_categories_init 钩子中注册分类

示例

add_action( 'wp_abilities_api_categories_init', function () {
    wp_register_ability_category( 'data-retrieval', [
        'label' => __( '数据获取', 'my-plugin' ),
        'description' => __( '用于读取站点数据的能力', 'my-plugin' ),
    ] );
});

---

二、注册能力（Registering Abilities）

能力是 Abilities API 的核心单元，对应一个可执行的功能。

函数签名

wp_register_ability( string $name, array $args ): ?WP_Ability

能力命名规范

• 格式：namespace/ability-name
• 推荐：使用插件 slug 作为 namespace
• 示例：
  • my-plugin/get-site-info
  • woocommerce/get-product

---

三、能力参数详解（Parameters Explained）

参数	是否必填	说明
label	是	能力名称（用于展示）
description	是	能力详细说明（对 AI 非常重要）
category	是	所属分类 slug
input_schema	否	输入参数的 JSON Schema
output_schema	是	返回结果的 JSON Schema
execute_callback	是	实际执行的 PHP 回调
permission_callback	是	权限校验回调
meta	否	元数据（REST、注解等）

---

四、meta.annotations 语义说明（非常重要）

这些字段会直接影响 REST API 调用方式、HTTP Method、AI 行为判断：

注解	含义
readonly	是否只读（不修改数据）
destructive	是否可能产生破坏性修改
idempotent	是否幂等（多次调用无副作用）
instructions	给 AI 的额外使用提示

---

五、执行能力

$ability = wp_get_ability( 'my-plugin/get-site-info' );
$result = $ability->execute();

• 返回 WP_Error 表示失败
• 成功返回符合 output_schema 的数据