WordPress Abilities API 项目概述

项目简介

WordPress Abilities API 是 WordPress AI 建设模块计划 的一部分，旨在为 WordPress 核心、插件和主题提供一种标准化的方式来描述它们的功能（”能力”），以机器可读、人类友好的形式呈现，从而支持 AI 代理和自动化工具的发现与执行。

主要用途

Abilities API 作为中央注册表和执行框架，用于向外部系统暴露 WordPress 功能。其主要目的是为 WordPress 组件提供一种通用方式来描述它们能做什么，采用机器可读且人类友好的形式，专注于发现、权限控制和执行元数据，而实际业务逻辑保留在注册组件内部。 

该系统使 WordPress 的不同部分、第三方插件、主题以及外部系统（如 AI 代理）更容易理解并与特定站点上可用功能进行交互。

设计目标

项目遵循四个核心设计原则：

1. 可发现性 – 每个能力都可以被列出、查询和检查
2. 互操作性 – 统一的架构让不相关的组件能够组合工作流
3. 安全优先 – 明确的权限决定谁/什么可以调用能力
4. 渐进式采用 – 首先作为 Composer 包发布，然后平滑迁移到核心

核心特性

1. 注册系统

API 提供全局 PHP 函数用于声明功能：

• wp_register_ability() – 注册单个能力
• wp_register_ability_category() – 组织能力到分类中

2. 发现机制

多种接口支持能力发现：

• REST API 端点（/wp-abilities/v1/abilities）用于列出能力
• PHP 函数如 wp_get_ability() 和 wp_get_abilities() 用于程序化访问
• JavaScript 客户端库与 @wordpress/data 存储集成

3. 执行框架

能力具有标准化执行和全面验证：

• 使用 JSON Schema 进行输入/输出验证
• 通过可配置回调进行权限检查
• 执行前后触发 WordPress 动作钩子
• 自动 HTTP 方法确定（只读用 GET，常规用 POST，破坏性用 DELETE）

4. 安全优先设计

每个能力执行前都需要通过可配置回调函数进行显式权限检查。权限回调提供细粒度访问控制，确保只有授权用户才能执行特定能力。 

5. 模式驱动验证

所有能力都为输入和输出定义 JSON Schema 规范，实现自动验证和自文档化。这确保了数据完整性，并帮助代理理解如何使用每个能力。 

6. REST API 暴露控制

能力默认不会通过 REST API 暴露。开发者可以使用 show_in_rest 元标志控制暴露，允许选择性暴露，同时保持内部能力私有。

核心组件

组件架构

系统由六个主要子系统组成：

组件	类/文件	用途
WP_Ability 类	class-wp-ability.php	封装单个能力及其属性、验证模式、执行回调和权限检查
WP_Abilities_Registry	class-wp-abilities-registry.php	存储和检索所有已注册能力的单例注册表
能力分类	class-wp-ability-category.php, class-wp-ability-categories-registry.php	为组织相关能力提供结构
注册函数	includes/abilities-api.php	提供能力管理的公共 API 的全局 PHP 函数
核心能力	includes/abilities/wp-core-abilities.php	演示系统功能并提供有用 WordPress 功能的内置能力
引导和初始化	abilities-api.php, includes/bootstrap.php	插件初始化、类加载和 WordPress 钩子集成

1. WP_Ability 类

WP_Ability 类表示具有关键属性的单个能力：

• $name – namespace/ability-name 格式的唯一标识符
• $label – 人类可读名称
• $description – 详细描述
• $category – 用于组织的分类别名
• $execute_callback – 实现功能的 PHP 函数
• $permission_callback – 确定执行访问权限的函数
• $input_schema – 输入验证的 JSON Schema
• $output_schema – 输出验证的 JSON Schema
• $meta – 包括注释在内的附加元数据 

2. 注册表模式（双单例）

系统实现两个单例注册表：

• WP_Abilities_Registry：管理所有已注册的能力，按名称索引
• WP_Ability_Categories_Registry：管理所有已注册的分类，按别名索引

两个注册表都通过魔术方法防止序列化和反序列化以增强安全性。

3. 引导和初始化

引导过程确保正确的加载顺序：

1. WordPress 加载主插件文件
2. 引导条件加载核心类
3. 分类注册表在能力注册表之前初始化
4. 全局函数变为可用
5. 核心能力通过动作钩子注册
6. REST API 集成在 rest_api_init 上初始化

4. REST API 层

REST API 在 /wp-abilities/v1 命名空间下提供 HTTP 端点：

• GET /wp-abilities/v1/abilities – 列出所有能力
• GET /wp-abilities/v1/categories – 列出所有分类
• GET /wp-abilities/v1/{namespace}/{ability} – 检索特定能力
• GET|POST|DELETE /wp-abilities/v1/{namespace}/{ability}/run – 执行能力

5. JavaScript 客户端

JavaScript 客户端库提供基于浏览器的访问：

• 发现函数（getAbilities, getAbility, getAbilityCategories）
• 执行函数（executeAbility）具有自动 HTTP 方法确定
• 与 @wordpress/data 存储集成用于 React 组件
• 支持客户端能力注册

6. 核心能力

系统包括演示功能的内置能力：

• core/get-site-info – 返回 WordPress 站点信息
• core/get-user-info – 返回用户信息

这些在核心分类中注册：site 和 user。

系统架构模式

验证管道

WP_Ability::execute() 方法实现多阶段验证管道：

1. 输入标准化 – 应用模式中的默认值
2. 输入验证 – 根据 JSON Schema 验证
3. 权限检查 – 调用权限回调
4. 执行前钩子 – 触发 wp_before_execute_ability 动作
5. 执行 – 调用执行回调
6. 输出验证 – 根据输出模式验证结果
7. 执行后钩子 – 触发 wp_after_execute_ability 动作

每个阶段都可以快速失败并返回 WP_Error，防止使用无效数据或权限不足执行。

外观模式

全局函数提供简化的公共 API，隐藏单例初始化和注册表方法调用的复杂性，允许开发者使用简单的函数如 wp_register_ability() 而无需理解底层的单例模式。

与 WordPress AI 计划的集成

Abilities API 是 WordPress AI 建设模块计划 的基础组件，旨在使 WordPress 更适合 AI 并支持智能自动化。 

目标用例

系统支持多个 AI 相关场景：

• AI 集成 – 允许 AI 代理发现并与站点功能交互
• 插件互操作性 – 使插件能够发现和使用彼此的功能
• 自动化工具 – 提供站点功能的程序化访问
• API 文档 – 具有模式验证的自文档化功能
• 开发者工具 – 暴露插件功能的标准方式

灵感和现代协议

项目从现代 AI 助手协议和命令系统汲取灵感：

• wp-feature-api – 在 PHP 层声明功能的共享愿景
• Gutenberg 中的命令面板实验
• 现代 AI 助手协议（MCP, A2A） 

当前状态和分发

项目目前正在为 WordPress 6.9 开发中，并通过多个分发渠道提供：

• Composer 包：wordpress/abilities-api 在 Packagist 上可用
• 功能插件：可从 GitHub 发布版下载
• 未来核心集成：计划迁移到 WordPress 核心

系统需要 PHP 7.4 或更高版本，并与现有 WordPress 安装无缝集成。

注意事项

Abilities API 代表了 WordPress 的重要架构进步，为 AI 代理和自动化工具安全发现和执行 WordPress 功能提供了基础架构。通过实施 established 设计模式（注册表、外观、验证管道）并利用 WordPress 现有的 REST API 和钩子系统，它创建了标准化接口，桥接传统 WordPress 开发与现代 AI 驱动交互。

安全优先方法确保所有能力执行都经过适当身份验证和授权，而模式驱动验证既提供安全性又提供自文档化。通过 Composer 打包的渐进采用策略允许生态系统在潜在核心集成之前进行实验和提供反馈。

---

备注

• 该项目目前处于活跃开发状态，API 可能会发生变化
• 项目采用 GPL-2.0-or-later 许可证
• 社区讨论在 WordPress Slack 的 #core-ai 频道进行
• 有关更多详细信息，请参阅项目的 开发者文档 和 贡献指南