wp-ability-development

WordPress 能力开发

适用场景

在决定 WordPress 能力接受什么、返回什么或执行什么操作时，使用此技能。有关注册、公开和客户端用法，请参阅 wp-abilities-api。

需要收集的上下文

明确谁会调用该能力、他们想做什么、已经掌握哪些信息，以及需要获得什么结果。例如，通过固定链接打开便笺的调用方可能知道它的 slug，而加载已保存草稿的编辑器可能已经有它的 ID。每个调用方可用的信息有助于你选择该能力应支持的输入。

对于现有能力，请阅读其架构和回调，了解它接受、返回和更改的内容。查看相关能力，了解共用的对象结构和术语。如果该能力已发布，请查看其文档、测试和已知调用位置，确定调用方目前依赖哪些内容，然后再更改契约。

操作步骤

从调用方的任务入手

用调用方自己的措辞描述请求。在能力名称、字段说明和结果中使用这些术语，然后将这些概念映射到实现。在字段说明中，解释每个字段控制什么，并在必要时说明省略该字段意味着什么。调用方应该能够根据能力的名称、说明和架构选择能力并构造请求。

例如，“查找这位作者发布的文章”意味着使用 where.status 和 where.author。回调可以将这些字段转换为 WordPress 查询参数。

保持输入精简明确

• 只要求调用方提供必要的信息。如果能力可以查找其余信息，就接受一个引用。例如，接受产品 ID 和数量，并根据存储的数据计算价格。
• 只有在确实满足调用方需求时才添加字段。每个额外选项都会增加需要验证和支持的组合。
• 从严格的要求开始。对于字段集已定义的对象（包括嵌套对象），将 additionalProperties: false 设为 false。使用与能力处理范围相符的类型、允许值和边界。例如，拒绝拼写错误的筛选条件，可以让调用方有机会在请求匹配到更广泛的记录集之前更正请求。只有在用例需要时才扩大能力的接受范围，并保留现有请求的含义。

为相关字段指定各自的类型

将描述同一概念的字段组合到具有自身架构的嵌套对象中。命名对象为调用方和开发者提供了可独立验证、传递和复用的值。

例如，同时公开原始内容和已渲染内容的能力，可以将它们分组为 content.raw 和 content.rendered。如果它还返回站点时间和 GMT 下的发布日期与修改日期，这些日期可以共用一种包含 site 和 gmt 字段的类型。

对相关的输入控件使用嵌套对象，以便每组字段可以独立演进。对于一项任务，优先采用一种清晰的输入形式。如果存在不同场景，则在相关对象中对选项进行建模，使常见输入只需定义一次。明确每个分支的必需和可接受内容，以便架构拒绝混合或不完整的请求。

例如，如果查找支持 ID 和 slug，则其 selector 对象可以使用 oneOf，确保只接受这两种形式中的一种。

为每种能力提供一种可预测的成功返回结构

为每次成功调用选择稳定的结果类型和结构。集合查询无论匹配到零条、一条还是多条记录，都应返回集合，这样调用方在任何情况下都能遍历结果。顶层 oneOf 若在单条记录和集合之间交替，会迫使调用方在使用结果前先判断其结构。请确认目标客户端支持你使用的架构特性。

返回调用方所需的信息

• 提供足够的细节，让调用方能直接使用结果。例如，订单摘要可以在调用方需要展示商品名称时，同时返回商品名称及其 ID。
• 返回相关操作已计算出的有用值。例如，结账操作可以包含用于计算总额的折扣和税费。调用方无需重新执行定价规则，就能展示实际明细。
• 说明写入操作更改了什么。返回相关的已保存状态，并说明调用方需要了解的副作用，例如下单是否也创建了客户账户。
• 将定义成功结果的字段设为必填。对于可能不可用的辅助值，使用 null 并说明其含义。另行说明哪些字段可以省略。例如，订单结果可以要求返回订单 ID，并在收据准备期间将收据 URL 设为 null。
• 让响应聚焦于重点。仅包含调用方可能会看到且能够使用的细节。权衡获取、计算和返回额外数据的成本，以及这些数据能为调用方节省的工作量。

错误和空结果的处理方式

• 请求的操作失败时，返回 WP_Error。保持错误代码及其数据结构稳定，以便调用方能以编程方式处理失败。记录调用方可以据此采取行动的错误代码。MCP 客户端只能收到消息，无法获取代码或数据，因此应在每条消息中说明出错原因以及调用方接下来可以做什么。
• 将预期中的空结果视为成功调用。查询没有匹配项时，应返回常规集合结构，只是其中的项目数组为空。选择与声明类型相符的空值，并说明其含义。
• 返回空结果前，先检查数据源是否出错。如果必需的数据库查询、远程请求或其他读取操作失败，应返回 WP_Error。调用方可能会将空集合视为创建记录的理由；如果读取实际失败，这可能导致重复记录。
• 写入操作中途失败时，说明已更改的内容以及无法确认的事项。将这些信息写入错误消息，以便调用方在重试前检查结果。只有在能够确认没有任何更改时，才说明未发生更改。
• 如果主要操作可以在结果不完整的情况下成功，应在输出架构中与结果一同定义 errors 数组。每个条目都应包含稳定的代码和消息；适用时，还应包含指向受影响字段的路径或恢复所需的数据。例如，某个能力可以返回已保存的订单，并在 errors 条目中指向无法获取的库存数量。完全成功时，返回空的 errors 数组。

保持 CRUD 能力的一致性

优先在命名空间内使用 {object}-{action} 格式，让相关能力在排序时排列在一起。集合查询和单条记录查询分别使用 query 和 get 能力。对应的写入操作使用 create、update 和 delete。

• 同一组能力中的共享字段应使用相同的名称、类型、含义和嵌套结构，包括 create 和 update 中可写入的字段。例如，如果 post-query 和 post-get 都提供原始内容，则两者的结果都应使用 content.raw。

• 将列表能力的筛选条件集中放在一个输入对象中，例如 where。说明筛选条件如何组合，让调用方知道必须匹配所有条件、可以匹配任一条件，还是适用其他规则。

• 普通编辑优先使用部分更新。要求提供目标对象，并接受调用方想要更改的字段。例如，编辑标题时，可以发送文章 ID 和新标题。调用方无需发送可能已过时的正文副本，就能完成编辑。

  仅应用已提供的字段，并在支持清除值时说明如何清除。对于嵌套值，应说明已提供的字段是单独编辑各个成员，还是整体替换该值。如果预期操作是替换，则要求提供完整的值。

使用注解描述副作用

为每项能力在 meta.annotations 中设置 readonly、destructive 和 idempotent。根据执行时实际发生的情况确定这些值，包括所调用的钩子和服务产生的影响。

• readonly: true 表示执行不会改变其环境。
• destructive: true 表示执行可能会删除或覆盖现有状态。如果所有写入都只是追加内容，则使用 destructive: false。
• idempotent: true 表示使用相同输入重复调用不会产生额外影响。例如，每次更新标题都会发送通知，那么即使标题已经匹配，仍会产生额外影响。

如需帮助根据实现检查这些声明，请参阅 wp-abilities-verify。

在执行期间强制执行权限

使用权限回调进行预检，以便调用方无需执行能力即可运行检查。在执行期间，先进行授权，再读取受保护的数据或进行更改。如果两条路径会检查相同内容，请共享授权规则。

某些检查取决于能力在运行时发现的内容。例如，查询的预检可以确认调用方是否有权请求某个集合。在执行期间，检查调用方可以查看哪些匹配记录和字段，再返回这些内容。

REST 和 MCP 可能会向调用方公开权限错误消息。不要在消息及任何返回的错误详情中包含受保护的数据。当记录是否存在本身属于敏感信息时，对不存在和无权访问的记录返回相同响应。

验证

• 使用有代表性的请求、无效输入，以及适用时的拒绝访问情形，测试正常调用路径。根据架构检查返回的数据结构。
• 对查询，检查零条、一条和多条匹配结果。对部分更新，尝试更改单个字段，并检查存储的值和响应。验证省略字段和显式清除字段时的行为。
• 对已发布能力的更改，检查依赖其现有契约的代表性调用。在评审中，将每项发现与调用方可见的后果及具体修正措施对应起来。

故障模式 / 调试

• 部分更新更改了额外字段。追踪实现在哪些地方填充默认值或替换嵌套值，并将其行为与预期编辑进行比较。
• 客户端拒绝了 WordPress 接受的架构。通过该客户端重现故障，并检查它对相关架构关键字或结果结构的支持情况。

升级处理

当需要对已发布能力进行不兼容更改时，明确指出哪些调用会失效，并明确做出迁移决策。