wp-abilities-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP Abilities Audit

WP Abilities 审计

Produce a standardized audit document for a WordPress plugin's REST surface, proposing a set of Abilities API registrations grouped by semantic intent. The audit doc is a planning artifact for implementers — humans, agents, or both — that captures the controller inventory, capability gates, and proposed ability shapes in a structured form. A reviewer reading the doc can scope the work without re-deriving the survey.

This skill works on any plugin that exposes a REST surface. Plugin classification (for purposes of the optional

plugin_family

annotation) is the user's call; the workflow itself is plugin-agnostic.

为WordPress插件的REST接口生成一份标准化审计文档，按语义意图分组提出一系列Abilities API注册方案。该审计文档是供实现人员（人工、Agent或两者协作）使用的规划工件，以结构化形式记录控制器清单、权限校验规则以及拟议的能力结构。审阅者无需重新调研即可通过文档评估工作范围。

此技能适用于所有暴露REST接口的插件。插件分类（用于可选的

plugin_family

注解）由用户决定；工作流本身与插件无关。

When to use

使用场景

The task is "register Abilities API abilities for a WP plugin" and no audit doc exists yet.
Planning participation in a multi-plugin abilities rollout and need a shareable, standardized audit artifact.
Pre-flight checking a plugin's agent-readiness before implementing abilities.
A PM or non-implementer wants to scope the work before engineering picks it up.

任务为“为WP插件注册Abilities API能力”且尚无审计文档时。
计划参与多插件能力部署，需要一份可共享的标准化审计工件时。
在实现能力前，预先检查插件的Agent适配性时。
产品经理或非技术人员希望在工程师接手前评估工作范围时。

Inputs required

所需输入

Plugin checkout path — working tree of the plugin to audit.
Triage output — run
```
wp-project-triage
```
first if not already done. The audit consumes
```
signals.usesAbilitiesApi
```
,
```
versions.wordpress
```
, and
```
project.kind
```
from the report.
Auditor identity — name and team or context, recorded in the audit's
```
auditor
```
field.
Output path — where the audit doc should land. Default explicit over implicit; ask if not provided rather than writing into the plugin worktree.

插件检出路径 — 待审计插件的工作目录。
分类输出 — 若尚未执行，请先运行
```
wp-project-triage
```
。审计将使用报告中的
```
signals.usesAbilitiesApi
```
、
```
versions.wordpress
```
和
```
project.kind
```
字段。
审计人员身份 — 审计人员的姓名及所属团队或上下文，将记录在审计文档的
```
auditor
```
字段中。
输出路径 — 审计文档的保存位置。优先使用明确指定的路径；若未提供，请询问用户，而非直接写入插件工作目录。

Prerequisites

前置条件

```
wp-project-triage
```
has run successfully and classified the plugin.
The plugin has at least one REST controller. If enumeration finds zero controllers, the audit doesn't apply — see "Failure modes" below.

```
wp-project-triage
```
已成功运行并完成插件分类。
插件至少包含一个REST控制器。若枚举发现零个控制器，则审计不适用——详见下文“失败模式/调试”部分。

Procedure

流程

1. Enumerate REST controllers

1. 枚举REST控制器

Read

references/controller-enumeration.md

now — it covers the two observed enumeration paths (glob for standard layouts, grep as the universal fallback) and when to use each.

Record every controller class + file + REST base + routes in a "Controller Inventory" table. The inventory is exhaustive even though only a subset becomes proposed abilities.

请立即阅读

references/controller-enumeration.md

——其中涵盖了两种已验证的枚举方式（针对标准目录结构的全局匹配、通用兜底的 grep 匹配）及各自的适用场景。

将所有控制器类、文件、REST基础路径及路由记录在“控制器清单”表格中。即使仅部分控制器会成为拟议能力，清单也需做到详尽无遗。

2. For each controller, extract the backing fields

2. 为每个控制器提取基础字段

For every controller found, extract the fields the audit schema requires: class, file, HTTP method, route, route-registration line number, callback name, callback line number, permission callback, whether the callback takes a

WP_REST_Request

argument or is zero-arg, and the return type.

Read

references/audit-schema.md

now for the exact field list and the shape of

proposed_abilities

entries. Line-number fields may be

null

for inherited callbacks — the schema allows this and pairs it with an optional

inherited_from

field.

针对每个找到的控制器，提取审计schema要求的字段：类名、文件、HTTP方法、路由、路由注册行号、回调函数名、回调函数行号、权限回调函数、回调函数是否接收

WP_REST_Request

参数或无参数，以及返回类型。

请立即阅读

references/audit-schema.md

，了解确切的字段列表及

proposed_abilities

条目的结构。对于继承的回调函数，行号字段可为

null

——schema允许此情况，并可搭配可选的

inherited_from

字段。

3. Confirm capability gate(s)

3. 确认权限校验规则

Trace each controller's

permission_callback

to its

current_user_can()

call (or to the post-type capability machinery if the controller extends a post-type-backed base).

Read

references/capability-gate-tracing.md

now — it documents the two common mechanisms (direct

check_permission()

vs post-type-backed

wc_rest_check_post_permissions()

) and how to represent each in the schema. Note explicitly whether read and write gates differ: compound gates are represented as a

{read, write}

object, not a single string.

追踪每个控制器的

permission_callback

至其

current_user_can()

调用（或若控制器继承自基于自定义文章类型的基类，则追踪至自定义文章类型权限机制）。

请立即阅读

references/capability-gate-tracing.md

——其中记录了两种常见机制（直接

check_permission()

与基于自定义文章类型的

wc_rest_check_post_permissions()

）及如何在schema中表示每种机制。需明确注明读取与写入权限校验规则是否不同：复合规则需表示为

{read, write}

对象，而非单一字符串。

4. Propose abilities using semantic-intent grouping

4. 按语义意图分组提出能力方案

Do NOT atomize one ability per HTTP method. Apply the semantic-intent grouping heuristic — it's the only grouping rule this skill uses.

Read

../wp-abilities-api/references/grouping-heuristic.md

now — do NOT re-derive the rules here. Short version: one ability per real-world question or state transition, with filter parameters in

input_schema

collapsing N variants into 1.

Apply the use-case sanity check before populating any candidate. Per

../wp-abilities-api/references/domain-vs-projection.md

's use-case-contract test: would a human or agent intentionally perform this behavior through a supported plugin workflow? If yes, the candidate is a real ability — proceed to fill in fields. If no, the route is internal transport plumbing (cache invalidation, scheduler ticks, bookkeeping endpoints, debug introspection) — keep it in the Controller Inventory section for completeness, but do NOT promote it to

proposed_abilities

. The route may be useful to inventory; the proposed ability must represent a real user/operator question or action.

For each proposed ability that passes the sanity check, fill in every field in the

proposed_abilities

schema:

name

intent

backing

permission

return_type

effort

(S/M/L),

annotations

(readonly/destructive/idempotent),

notes

risks

use_case_fit

side_effects

seed_data_needs

The last three are the implementation-readiness facts the implementer and the verify-mode tooling both need: which human/agent workflow this ability serves (

use_case_fit

), what the backing path emits on every call (

side_effects

— empty array is a fact, not a missing value), and what representative data must exist in the test environment for the ability to execute through the public boundary (

seed_data_needs

请勿为每个HTTP方法单独创建一个能力。应用语义意图分组启发式规则——这是本技能唯一使用的分组规则。

请立即阅读

../wp-abilities-api/references/grouping-heuristic.md

——请勿自行推导规则。简而言之：每个能力对应一个真实场景的问题或状态转换，通过

input_schema

中的过滤参数将N种变体合并为1种。

在填充任何候选能力前，先进行用例合理性检查。 根据

../wp-abilities-api/references/domain-vs-projection.md

中的用例契约测试：人员或Agent是否会通过受支持的插件工作流有意执行此行为？若是，则该候选为真实能力——继续填充字段。若否，则该路由为内部传输管道（缓存失效、调度任务、记账端点、调试自省）——需将其保留在“控制器清单”章节以保证完整性，但请勿将其提升至

proposed_abilities

。路由可能在清单中有用，但拟议能力必须代表真实的用户/操作者问题或操作。

针对每个通过合理性检查的拟议能力，填充

proposed_abilities

schema中的所有字段：

name

、

intent

、

backing

、

permission

、

return_type

、

effort

（小/中/大）、

annotations

（只读/破坏性/幂等）、

notes

、

risks

、

use_case_fit

、

side_effects

、

seed_data_needs

。

最后三个字段是实现人员与验证工具都需要的就绪性事实：该能力服务于哪个人类/Agent工作流（

use_case_fit

）、基础路径在每次调用时会产生什么影响（

side_effects

——空数组表示无影响，而非缺失值），以及测试环境中必须存在哪些代表性数据才能使该能力通过公共边界执行（

seed_data_needs

）。

5. Surface gaps and deferred items

5. 梳理空白项与延迟项

Three buckets:

excluded_from_mvp
— candidates intentionally deferred for risk reasons (real-money writes, irreversible state changes, or prerequisite design work). Each entry gets a one-sentence reason.
surfaced_gaps
— MVP candidates with no backing endpoint (ability with
```
backing: null
```
), plus high-value endpoints discovered during enumeration that aren't in the MVP list but would be easy future wins.
Risks per ability — anything about a backing endpoint that the implementer must handle (no idempotency key, two-phase behavior, state-transition caveats, zero-arg endpoints registered with
```
permission_callback => '__return_true'
```
that must NOT copy that into the ability registration).

分为三类：

excluded_from_mvp
— 因风险原因（涉及真实资金的写入操作、不可逆状态变更或需先完成设计工作）有意延迟的候选能力。每个条目需附带一句原因说明。
surfaced_gaps
— 无基础端点的MVP候选能力（
```
backing: null
```
的能力），以及枚举过程中发现的不在MVP列表中但易于实现的高价值端点。
各能力的风险点 — 基础端点中任何需要实现人员处理的问题（无幂等键、两阶段行为、状态转换注意事项、注册时
```
permission_callback => '__return_true'
```
的无参数端点——此类情况绝不能复制到能力注册中）。

6. Write the audit doc

6. 编写审计文档

Write to the explicit output path collected in "Inputs required". The document structure must match

references/audit-schema.md

exactly:

```
Last updated: YYYY-MM-DD HH:MM
```
header.
YAML block with all required top-level metadata +
```
proposed_abilities
```
,
```
excluded_from_mvp
```
,
```
surfaced_gaps
```
.
"Controller Inventory" table.
"Notes and Surprises" prose section.

A copy-pasteable minimal example showing the full shape lives in

references/audit-schema.md

under "Minimal valid example" — start there when authoring a new audit.

写入“所需输入”中收集的明确输出路径。文档结构必须严格匹配

references/audit-schema.md

：

```
Last updated: YYYY-MM-DD HH:MM
```
头部。
YAML块，包含所有必填顶级元数据 +
```
proposed_abilities
```
、
```
excluded_from_mvp
```
、
```
surfaced_gaps
```
。
“控制器清单”表格。
“注意事项与意外发现”说明章节。

references/audit-schema.md

的“最小有效示例”部分提供了可直接复制粘贴的完整结构示例——编写新审计文档时可从此处开始。

7. (Optional) Designate a reference implementation ability

7.（可选）指定参考实现能力

Set

reference_ability: true

on the first ability an implementer should land — typically the smallest, safest, highest-leverage read. This gives downstream workflows a deterministic starting point.

在第一个实现人员应完成的能力上设置

reference_ability: true

——通常是最小、最安全、价值最高的读取能力。这为下游工作流提供了确定的起点。

Verification

验证

The audit conforms to
```
references/audit-schema.md
```
(all required top-level fields present, at least one entry in
```
proposed_abilities
```
, annotations complete on every ability).
```
capability_gate
```
is a string for single-cap plugins or a
```
{read, write}
```
object for post-type-backed plugins.
Every ability with
```
backing: null
```
also appears in
```
surfaced_gaps
```
.
The doc round-trips through the validator in
```
audit-schema.md
```
"Known limitations" without errors.

审计文档符合
```
references/audit-schema.md
```
要求（所有必填顶级字段齐全，
```
proposed_abilities
```
至少有一个条目，每个能力的注解完整）。
```
capability_gate
```
对于单一权限插件为字符串，对于基于自定义文章类型的插件为
```
{read, write}
```
对象。
所有
```
backing: null
```
的能力均出现在
```
surfaced_gaps
```
中。
文档可通过
```
audit-schema.md
```
“已知限制”部分中的验证器往返验证无错误。

Failure modes / debugging

失败模式/调试

Plugin has no REST controllers — audit doesn't apply. Consider hooks/filters-based abilities (out of scope for this skill's current version) or skip abilities adoption for this plugin.
Plugin inherits controllers from another repo (common for plugins extending core post-type-backed controllers like
```
WP_REST_Posts_Controller
```
, or extension plugins built on a parent's REST classes) — capture with
```
backing.inherited_from: "<parent FQCN>"
```
. Line-number fields may be
```
null
```
per the schema.
Compound capability gate (distinct read/write caps) — use the structured
```
{read, write}
```
form documented in
```
references/capability-gate-tracing.md
```
. Don't smuggle a
```
/
```
-separated string into a field typed as a single cap.
Ambiguous grouping — route to
```
../wp-abilities-api/references/grouping-heuristic.md
```
. Do not invent alternative grouping rules in the audit doc.
Zero-arg endpoints with
permission_callback => '__return_true'
— legal at the REST layer, but the ability's own
```
permission_callback
```
must match the plugin's merchant gate. Never promote
```
'__return_true'
```
into an ability registration. Note this in the ability's
```
risks
```
.
Output path defaults to plugin worktree — always ask the user for an explicit output directory (e.g. their vault
```
plans/
```
). Writing the audit into the plugin's own git history pollutes the worktree and buries the artifact.

插件无REST控制器 — 审计不适用。可考虑基于钩子/过滤器的能力（本技能当前版本不支持）或跳过该插件的能力适配。
插件从其他仓库继承控制器（常见于继承核心自定义文章类型控制器如
```
WP_REST_Posts_Controller
```
的插件，或基于父插件REST类构建的扩展插件）——使用
```
backing.inherited_from: "<parent FQCN>"
```
记录。根据schema，行号字段可为
```
null
```
。
复合权限校验规则（读取/写入权限不同） — 使用
```
references/capability-gate-tracing.md
```
中记录的结构化
```
{read, write}
```
格式。请勿将用
```
/
```
分隔的字符串放入类型为单一权限的字段中。
分组模糊 — 参考
```
../wp-abilities-api/references/grouping-heuristic.md
```
。请勿在审计文档中自创替代分组规则。
权限回调为
__return_true
的无参数端点 — 在REST层是合法的，但能力自身的
```
permission_callback
```
必须匹配插件的商户权限规则。绝不能将
```
'__return_true'
```
推广到能力注册中。请在能力的
```
risks
```
字段中注明此情况。
输出路径默认指向插件工作目录 — 务必询问用户明确的输出目录（例如其Vault的
```
plans/
```
目录）。将审计文档写入插件自身的Git历史会污染工作目录并隐藏工件。

Escalation

升级处理

If the plugin uses an enumeration convention not covered by
```
references/controller-enumeration.md
```
(neither the standard glob nor the grep fallback produces a complete inventory), update that reference with the new convention and open a PR so future audits cover it deterministically.
If capability tracing hits a mechanism not covered by
```
references/capability-gate-tracing.md
```
, extend that file rather than encoding the new case in the audit's "Notes and Surprises" only.

若插件使用的枚举规则未在
```
references/controller-enumeration.md
```
中涵盖（标准全局匹配与grep兜底均无法生成完整清单），请更新该参考文档并提交PR，以便未来审计可确定性地覆盖该规则。
若权限追踪遇到
```
references/capability-gate-tracing.md
```
未涵盖的机制，请扩展该文档，而非仅在审计的“注意事项与意外发现”中记录新情况。",