WordPress Abilities API 入门指南

本文档基于 WordPress 官方项目 abilities-api 的 getting-started.md，在不改变原意的前提下，进行了完整的简体中文本地化与说明增强，适合中文开发者快速理解和上手。

---

一、什么是 Abilities API？

Abilities API 是一个 尚未合并进 WordPress Core 的实验性 API，用于以“能力（Ability）”为单位，向 WordPress 注册可描述、可校验、可调用的功能接口。

你可以把它理解为：

• 一种比传统 do_action / apply_filters 更结构化的能力注册方式
• 一种为 AI Agent、自动化系统、REST 调用 提供统一能力描述的底层 API
• 一种正在为「AI 原生 WordPress」做准备的基础设施

在它正式进入 Core 之前，需要通过插件或依赖的方式使用。

---

二、安装方式

在 Abilities API 合并进 WordPress Core 之前，必须手动安装。

1️⃣ 作为插件安装（最推荐）

这是最简单、最直观的方式，适合尝鲜和实际项目使用。

方式一：通过 WP-CLI

wp plugin install https://github.com/WordPress/abilities-api/releases/latest/download/abilities-api.zip

方式二：通过 wp-env（本地开发）

在你的 .wp-env.json 中加入：

{
  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
  "plugins": [
    "WordPress/abilities-api"
  ]
}

这样在本地环境启动时会自动加载 Abilities API 插件。

---

2️⃣ 作为依赖使用（插件开发者）

如果你正在开发插件，并希望在 Core 合并前提前使用 Abilities API，可以把它当作依赖。

✅ 推荐方式：声明插件依赖

在插件头部使用 Requires Plugins：

/*
 * Plugin Name: My Plugin
 * Description: 示例插件
 * Requires Plugins: abilities-api
 */

这样可以确保：

• Abilities API 会 先于你的插件加载
• 用户在未安装依赖时会收到明确提示

如果你还需要更严格的版本控制或用户引导，可以结合下面的代码检测方式。

---

方式二：通过 Composer

composer require wordpress/abilities-api

适合 Composer 驱动的项目或框架型插件。

---

三、在代码中检测 Abilities API 是否可用

为了避免依赖缺失导致致命错误，强烈建议在代码中显式检测。

1️⃣ 检测 API 是否存在

if ( ! class_exists( 'WP_Ability' ) ) {
    add_action( 'admin_notices', function () {
        wp_admin_notice(
            __( '本插件依赖 Abilities API，请先安装并启用该插件。', 'my-plugin' ),
            'error'
        );
    } );
    return;
}

---

2️⃣ 检测最低版本要求

if ( ! defined( 'WP_ABILITIES_API_VERSION' ) || version_compare( WP_ABILITIES_API_VERSION, '0.1.0', '<' ) ) {
    add_action( 'admin_notices', function () {
        wp_admin_notice(
            __( '本插件需要 Abilities API 0.1.0 及以上版本，请升级依赖。', 'my-plugin' ),
            'error'
        );
    } );
    return;
}

这在 API 快速演进阶段尤为重要。

---

四、基础使用示例（完整流程）

下面是一个完整、可运行的最小示例，展示 Abilities API 的核心使用方式。

1️⃣ 定义一个能力的执行函数

function my_plugin_get_site_title( array $input = array() ): string {
    return get_bloginfo( 'name' );
}

这个函数是真正执行业务逻辑的地方。

---

2️⃣ 注册 Ability（关键步骤）

add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );

function my_plugin_register_abilities() {
    wp_register_ability( 'my-plugin/get-site-title', array(
        'label'        => __( '获取站点标题', 'my-plugin' ),
        'description'  => __( '返回当前 WordPress 站点的标题。', 'my-plugin' ),
        'category'     => 'site-info',

        'input_schema' => array(
            'type'                 => 'object',
            'properties'           => array(),
            'additionalProperties' => false,
        ),

        'output_schema' => array(
            'type'        => 'string',
            'description' => '站点标题字符串',
        ),

        'execute_callback'    => 'my_plugin_get_site_title',
        'permission_callback' => '__return_true',

        'meta' => array(
            'show_in_rest' => true,
        ),
    ) );
}

📌 重点说明：

• wp_abilities_api_init：确保 API 已完全加载
• input_schema / output_schema：为 AI / 自动化提供结构化描述
• show_in_rest：允许通过 REST API 暴露该能力

---

3️⃣ 获取并执行 Ability

add_action( 'admin_init', 'my_plugin_use_ability' );

function my_plugin_use_ability() {
    $ability = wp_get_ability( 'my-plugin/get-site-title' );

    if ( ! $ability ) {
        return;
    }

    $result = $ability->execute();

    if ( is_wp_error( $result ) ) {
        error_log( $result->get_error_message() );
        return;
    }

    echo 'Site Title: ' . esc_html( $result );
}

此时，你已经完成了：

定义能力 → 注册能力 → 获取能力 → 执行能力

这一完整闭环。

---

五、为什么 Abilities API 很重要？

从设计上看，Abilities API 明显在为以下方向铺路：

• AI Agent 对 WordPress 的安全、可控调用
• 标准化插件/主题对外暴露“能力”的方式
• 比 REST Endpoint 更高层次的语义接口

如果你正在关注：

• MCP / AI Agent / Tool Calling
• Headless WordPress
• 自动化运维与内容生产

那么 Abilities API 非常值得提前研究和实践。

---

六、下一步你可以做什么？

• 尝试为你的插件封装几个“能力”
• 将已有 REST API 重构为 Ability
• 探索与 AI 工具（如 MCP Adapter）的结合方式

Abilities API 仍在快速演进阶段，但它很可能会成为未来 WordPress 的关键基础设施之一。

---