Abilities API 仅适用于 WordPress 6.9 及以上版本。
WordPress Abilities API 提供了一种标准化的方式，用于注册和发现 WordPress 站点内的独立功能单元。这些被称为"Abilities"的单元代表组件可以执行的具体操作或能力，具有明确定义的输入、输出和权限。
它作为一个中央注册表，使得 WordPress 的不同部分、第三方插件、主题以及外部系统（如 AI 代理）更容易理解和与特定站点上可用的能力进行交互。
核心概念
- Ability：一个具有独立名称的功能单元，遵循
namespace/ability-name模式。每个 Ability 都有人类可读的名称和描述、输入/输出定义（使用 JSON Schema）、类别分配、可选权限以及用于执行的关联回调函数。每个注册的 Ability 都是WP_Ability类的实例。 - Category：一种组织相关能力的方式。每个能力必须属于且仅属于一个类别。类别具有 slug、标签和描述。每个注册的类别都是
WP_Ability_Category类的实例。 - Registry：一个中央单例对象（
WP_Abilities_Registry），保存所有已注册的能力。它提供用于注册、注销、查找和查询能力的方法。同样，WP_Abilities_Category_Registry管理所有已注册的类别。 - Callback：当通过
WP_Ability::execute()调用能力时执行的 PHP 函数或方法。 - Schema：能力预期输入（
input_schema）和返回输出（output_schema）的 JSON Schema 定义。这允许进行验证并帮助代理了解如何使用该能力。 - Permission Callback：一个可选函数，用于确定当前用户是否可以执行特定能力。
- Namespace：能力名称的第一部分（斜杠之前），通常与注册该能力的插件或组件名称相匹配。
目标与优势
- 标准化：提供一种单一、一致的方式来暴露站点能力。
- 可发现性：使 AI 系统和自动化工具能够轻松发现功能。
- 验证：内置的基于 JSON Schema 的输入/输出验证确保数据完整性。
- 安全性：权限回调提供细粒度的访问控制。
- 可扩展性：简单的注册模式允许任何插件或主题暴露其能力。
- AI 友好：机器可读格式支持智能自动化和 AI 代理交互。
使用场景
- AI 集成：允许 AI 代理发现和与站点能力进行交互。
- 插件互操作性：启用插件发现和利用彼此的功能。
- 自动化工具：提供对站点功能的编程式访问。
- API 文档：具备 Schema 验证的自文档化能力。
- 开发者工具：暴露插件功能的标准方式。
注册示例
// First, register a category, or use one of the existing categories.
add_action( 'wp_abilities_api_categories_init', 'wporg_register_category' );
/**
* Register a custom ability category.
*
* @return void
*/
function wporg_register_category() {
wp_register_ability_category(
'site-information',
array(
'label' => __( 'Site Information', 'textdomain' ),
'description' => __( 'Abilities that provide information about the WordPress site.', 'textdomain' ),
)
);
}
// Then, register an ability in that category.
add_action( 'wp_abilities_api_init', 'wporg_register_ability' );
/**
* Register a custom ability to get site information.
*
* @return void
*/
function wporg_register_ability() {
wp_register_ability(
'my-plugin/site-info',
array(
'label' => __( 'Site Info', 'textdomain' ),
'description' => __( 'Returns information about this WordPress site', 'textdomain' ),
'category' => 'site-information',
'input_schema' => array(),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'site_name' => array(
'type' => 'string',
'description' => __( 'The name of the WordPress site', 'textdomain' ),
),
'site_url' => array(
'type' => 'string',
'description' => __( 'The URL of the WordPress site', 'textdomain' ),
),
'active_theme' => array(
'type' => 'string',
'description' => __( 'The active theme of the WordPress site', 'textdomain' ),
),
'active_plugins' => array(
'type' => 'array',
'items' => array(
'type' => 'string',
),
'description' => __( 'List of active plugins on the WordPress site', 'textdomain' ),
),
'php_version' => array(
'type' => 'string',
'description' => __( 'The PHP version of the WordPress site', 'textdomain' ),
),
'wordpress_version' => array(
'type' => 'string',
'description' => __( 'The WordPress version of the site', 'textdomain' ),
),
),
),
'execute_callback' => 'wporg_get_siteinfo',
'permission_callback' => function () {
return current_user_can( 'manage_options' );
},
'meta' => array(
'show_in_rest' => true,
),
)
);
}
/**
* Execute callback to get site information.
*
* @return array
*/
function wporg_get_siteinfo() {
$active_plugins = array();
foreach ( get_option( 'active_plugins', array() ) as $plugin_path ) {
$plugin_data = get_plugin_data( WP_PLUGIN_DIR . '/' . $plugin_path );
$active_plugins[] = $plugin_data['Name'];
}
return array(
'site_name' => get_bloginfo( 'name' ),
'site_url' => get_bloginfo( 'url' ),
'active_theme' => wp_get_theme()->get( 'Name' ),
'active_plugins' => $active_plugins,
'php_version' => PHP_VERSION,
'wordpress_version' => get_bloginfo( 'version' ),
);
}这将创建一个机器可读的能力，AI 系统和自动化工具可以在 WordPress 权限和验证规则范围内安全地发现、理解和执行它。