用途
本技能用于在决定一个 WordPress ability 接受什么、返回什么或做什么时提供指导。它聚焦于 ability 的 schema 与行为设计,适用于设计、更新或审查 WordPress ability 的场景。关于注册、暴露和客户端使用,资料指出应参见 wp-abilities-api。
主要能力
- 从调用者任务出发定义 ability:用调用者的语言描述请求,并将这些概念映射到实现。
- 保持输入精简且精确:只要求调用者需要提供的内容,能查到的就用引用代替;新增字段需有明确调用者需求。
- 严格起步:对字段集合明确的对象设置 additionalProperties: false,包括嵌套对象;使用与 ability 处理能力匹配的类型、允许值和边界。
- 为相关字段赋予独立类型:将描述同一概念的字段归入带自身 schema 的嵌套对象,便于验证、传递和复用。
- 为每个 ability 提供可预测的成功结构:集合查询始终返回集合,避免顶层 oneOf 在单条记录与集合间切换。
- 返回调用者所需内容:提供可直接使用的细节,返回已计算的有用值,报告写入变更及副作用。
- 建模错误与空结果:失败时返回 WP_Error,保持错误码与数据形状稳定;将预期空结果视为成功调用;写入部分失败时描述已变更与未确认内容。
- 保持 CRUD ability 一致:命名采用 {object}-{action},查询与获取分离,共享字段使用相同名称、类型、含义与嵌套。
- 用注解描述副作用:在 meta.annotations 中设置 readonly、destructive、idempotent。
- 执行期强制权限:使用 permission callback 做预检,执行时在读取受保护数据或修改前强制授权。
使用方式
资料给出的流程包括:先收集上下文,识别谁将调用该 ability、他们想做什么、已有什么信息、需要返回什么;对已有 ability,阅读其 schema 与回调,检查相关 ability 的共享对象形状与术语,若已发布则查看文档、测试和已知调用点。然后从调用者任务开始,描述请求并映射到实现。接着保持输入精简精确、为相关字段分组、定义单一成功结构、返回所需内容、建模错误与空结果、保持 CRUD 一致、添加副作用注解、执行期强制权限。最后进行验证:用代表性请求、无效输入和拒绝访问走正常调用路径,检查返回形状是否符合 schema;查询检查零、一、多匹配;部分更新尝试单字段变更并检查存储值与响应;对已发布 ability 的变更,检查依赖其现有契约的代表性调用。
适用场景
适用于需要决定 WordPress ability 接受、返回或执行内容的开发与审查工作,尤其是设计新 ability、修改已有 ability 的 schema 或行为、审查接口契约一致性、以及需要确保调用者可见行为可预测的场景。
限制
资料未提供该技能的具体安装命令、运行环境要求、支持的 WordPress 版本、收费或价格信息、平台限制以及效果保证。关于注册、暴露和客户端使用,资料明确指向 wp-abilities-api,本技能不覆盖这些内容。