wp-abilities-verify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP Abilities Verify

Verify a WordPress plugin's Abilities API registrations. The centerpiece is the adversarial annotation correctness check: a

readonly: true

ability that actually writes (via

$wpdb->update

update_option

, a non-GET delegate, etc.) is a security and UX disaster because agents plan actions on the basis of the annotations they introspect. This skill catches those lies by reading the callback body and comparing what it does against what the annotation claims.

The skill also validates audit docs produced by

wp-abilities-audit

, checks permission gates and schema hygiene, and optionally executes each ability against a live environment.

验证WordPress插件的Abilities API注册情况。核心功能是对抗性注解正确性检查：标注为

readonly: true

但实际执行写入操作（如通过

$wpdb->update

、

update_option

、非GET委托等）的能力会引发安全和用户体验问题，因为智能体（Agent）会基于其自省到的注解来规划操作。本工具通过读取回调函数体，将实际行为与注解声明进行对比，从而识别此类不符情况。

本工具还可验证

wp-abilities-audit

生成的审计文档、检查权限网关与架构规范性，并可选择性地在真实环境中执行每个能力。

When to use

使用场景

After abilities have been registered in a plugin but before a PR lands.
As a health-check on an already-shipped plugin (catch regressions where a refactor turned a readonly ability into a writing one).
To validate an audit document before handing it to an implementer.

插件中注册能力后、PR合并前。
作为已发布插件的健康检查工具（捕捉重构导致只读能力变为写入能力的回归问题）。
向开发者交付前验证审计文档。

Two modes

两种模式

Static mode — runs from the plugin checkout. No env. Enumerates via source inspection, runs the adversarial correctness check, runs schema and permission lints, and validates audit docs.
Runtime mode — requires a running env. Does everything static does PLUS:
```
wp_get_abilities()
```
for authoritative enumeration, executes each ability with curated inputs, confirms permission roundtrip against real users, and runs a twin-invocation heuristic on
```
idempotent: true
```
abilities to flag candidates for review (return-value equality is a signal, not a verdict — core defines idempotent as "no additional effect on the environment").

Both modes produce the same structured report format.

A static-mode PASS means "no obvious-shape violations," not "verified write-free." For high-stakes plugins, run runtime mode before landing — it catches bootstrap-order, permission-roundtrip, and idempotency issues that static can't. See

references/annotation-correctness.md

for the static blind spots.

静态模式 — 基于插件代码仓库运行，无需环境。通过源码检查枚举能力、执行对抗性正确性检查、运行架构与权限校验、验证审计文档。
运行时模式 — 需要运行中的环境。包含静态模式的所有功能，额外增加：通过
```
wp_get_abilities()
```
获取权威的能力枚举结果、使用预设输入执行每个能力、针对真实用户验证权限往返逻辑、对标注
```
idempotent: true
```
的能力执行双调用启发式检查以标记需复核的候选（返回值相等是参考信号而非最终结论——核心定义中幂等指“对环境无额外影响”）。

两种模式都会生成相同结构的报告格式。

静态模式通过仅代表“无明显格式违规”，而非“已验证无写入操作”。对于高风险插件，合并前应运行运行时模式——它能捕捉静态模式无法检测的启动顺序、权限往返和幂等性问题。详见

references/annotation-correctness.md

中的静态模式盲区说明。

Inputs required

所需输入

Plugin checkout path — working tree to verify.
Mode —
```
static
```
or
```
runtime
```
. Default to static if unspecified.
(Runtime only) Env-up command — read the plugin's
```
AGENTS.md
```
. Common patterns:
```
npm run wp-env start
```
,
```
npx wp-env start
```
, or a composer-based bring-up. Plugin families with their own dev tooling will document their own command. Do NOT assume
```
npm run wp-env
```
works.
(Optional) Audit doc path — enables cross-checks between the audit and the registered abilities, and validates the audit itself.
Report output path — explicit path, typically the user's vault.

插件代码仓库路径 — 待验证的工作目录。
模式 —
```
static
```
或
```
runtime
```
。未指定时默认使用静态模式。
（仅运行时模式）环境启动命令 — 查看插件的
```
AGENTS.md
```
文档。常见命令如：
```
npm run wp-env start
```
、
```
npx wp-env start
```
或基于Composer的启动命令。拥有自研开发工具的插件家族会在文档中说明专属命令，请勿默认使用
```
npm run wp-env
```
。
（可选）审计文档路径 — 启用审计文档与已注册能力的交叉校验，并验证审计文档本身。
报告输出路径 — 明确的输出路径，通常为用户的存储目录。

Prerequisites

前置条件

```
wp-project-triage
```
has been run on the plugin.
The plugin has at least one registered ability in source. Zero hits on
```
wp_register_ability(
```
→ return a clear "no abilities registered" report, not an empty PASS.

已对插件运行
```
wp-project-triage
```
。
插件源码中至少注册了一个能力。若未找到
```
wp_register_ability(
```
调用，需返回清晰的“未注册任何能力”报告，而非空的通过结果。

Procedure

执行流程

1. (If audit provided) Validate the audit doc

1.（若提供审计文档）验证审计文档

Read

references/audit-schema-validation.md

. Validate the audit against the canonical schema owned by

wp-abilities-audit

. Surface missing required fields, multiple

reference_ability: true

, and

backing: null

entries that aren't paired with a

surfaced_gaps

entry.

backing: null

alone is WARN (intentional gap output), not FAIL.

阅读

references/audit-schema-validation.md

。对照

wp-abilities-audit

的标准架构验证审计文档，指出缺失的必填字段、多个

reference_ability: true

的情况，以及未搭配

surfaced_gaps

项的

backing: null

条目。仅

backing: null

属于警告（故意留空的输出），而非失败。

2. Enumerate abilities statically

2. 静态枚举能力

Read

references/static-enumeration.md

. Find each

wp_register_ability(

call, extract the name, the annotation block, and the execute-callback location. Use a multi-line tool (

rg --multiline --pcre2

) — the canonical formatting splits the call across lines. Record each ability's source-file + line + annotations + callback byte range.

阅读

references/static-enumeration.md

。查找每个

wp_register_ability(

调用，提取名称、注解块和执行回调的位置。使用多行工具（如

rg --multiline --pcre2

）——标准格式会将调用拆分为多行。记录每个能力的源文件+行号+注解+回调字节范围。

3. (Runtime only) Enumerate via REST + wp-cli

3.（仅运行时模式）通过REST与wp-cli枚举

Read

references/runtime-harness.md

. Bring the env up using the command from

AGENTS.md

, then enumerate via

wp_get_abilities()

over wp-cli and cross-check against the static inventory. Source-only → FAIL (registration not firing). Runtime-only → WARN (dynamic registration path).

阅读

references/runtime-harness.md

。使用

AGENTS.md

中的命令启动环境，然后通过wp-cli调用

wp_get_abilities()

枚举能力，并与静态枚举结果交叉校验。仅存在于源码中的能力→失败（未触发注册）。仅存在于运行时的能力→警告（动态注册路径）。

4. Annotation correctness (the adversarial core)

4. 注解正确性（对抗性核心）

Read

references/annotation-correctness.md

. Read each callback body and verify it matches the annotation claim:

```
readonly: true
```
→ callback must not write to the database, the options table, post / user / term / comment data, the filesystem, cron, or via non-GET HTTP / REST delegates.
```
destructive: false
```
→ callback must not delete, refund, void, cancel, or trash.
```
idempotent: true
```
→ repeated calls with the same input have no additional effect on the environment (per the
```
idempotent
```
annotation's docblock in
```
class-wp-ability.php
```
). Static catches counter writes and per-call cron schedules; runtime adds a twin-invocation heuristic for visible state changes.

The reference lists common write patterns as a starting set, not a checklist — plugin vocabularies vary, and the agent extends with verbs specific to the plugin under verification.

False positives get suppressed via an inline

// verify-ignore: <annotation> -- <reason>

comment.

阅读

references/annotation-correctness.md

。读取每个回调函数体，验证其是否符合注解声明：

```
readonly: true
```
→ 回调不得写入数据库、选项表、文章/用户/分类/评论数据、文件系统、定时任务，或通过非GET HTTP/REST委托执行写入。
```
destructive: false
```
→ 回调不得执行删除、退款、作废、取消或移入回收站操作。
```
idempotent: true
```
→ 使用相同输入重复调用对环境无额外影响（符合
```
class-wp-ability.php
```
中
```
idempotent
```
注解的文档块定义）。静态模式会捕捉计数器写入和每次调用创建的定时任务；运行时模式增加双调用启发式检查以识别可见状态变化。

参考文档列出了常见写入模式作为基础检查项，而非完整清单——插件词汇各不相同，工具会针对当前验证的插件扩展专属动词。

误报可通过行内注释

// verify-ignore: <annotation> -- <reason>

抑制。

5. Permission roundtrip

5. 权限往返校验

Read

references/permission-roundtrip.md

. Static: classify each

permission_callback

against the six shapes (preferred Shape A

current_user_can(...)

; FAIL on Shape B-bad

WP_REST_Request

patterns or Shape E literal

true

). Runtime: anon and subscriber denied; admin allowed (unless deliberately public). When an audit was provided, cross-check the registered cap against the audit's declared gate.

阅读

references/permission-roundtrip.md

。静态模式：将每个

permission_callback

归类为六种类型（推荐使用类型A

current_user_can(...)

；若使用类型B的错误

WP_REST_Request

模式或类型E的字面量

true

则判定为失败）。运行时模式：匿名用户和订阅者被拒绝；管理员被允许（除非刻意设置为公开）。若提供了审计文档，需将已注册的权限与审计文档中声明的网关进行交叉校验。

6. Schema lints

6. 架构校验

Read

references/schema-lints.md

. Six small principles applied to each ability's

input_schema

: object schemas declare

additionalProperties

; required fields have descriptions; enums non-empty; no

$ref

; defaults are statically constant (including

(object) array()

); reference abilities have no required inputs.

Cross-reference

../wp-abilities-api/references/input-schema-gotchas.md

for the four runtime gotchas (defaults not injected on the property-level path, pagination key drift,

empty()

on string IDs, direct vs indirect invocation strictness).

阅读

references/schema-lints.md

。对每个能力的

input_schema

应用六项原则：对象架构需声明

additionalProperties

；必填字段需包含描述；枚举值非空；无

$ref

引用；默认值为静态常量（包括

(object) array()

）；引用能力无必填输入。

对照

../wp-abilities-api/references/input-schema-gotchas.md

中的四个运行时陷阱（属性级路径未注入默认值、分页键偏移、字符串ID使用

empty()

、直接与间接调用的严格性差异）。

7. Error-code vocabulary

7. 错误码词汇校验

Cross-reference

../wp-abilities-api/references/error-code-vocabulary.md

. Inspect each callback's

WP_Error

returns; non-vocabulary codes → WARN.

对照

../wp-abilities-api/references/error-code-vocabulary.md

。检查每个回调返回的

WP_Error

；非标准词汇的错误码→警告。

Verification

验证报告

The run produces a structured markdown report at the user-specified path:

---
Last updated: <YYYY-MM-DD HH:MM>
---

运行后会在用户指定路径生成结构化Markdown报告：

---
Last updated: <YYYY-MM-DD HH:MM>
---

<Plugin> Abilities Verification — <Static|Runtime> Mode

<插件名称> Abilities 验证报告 — <静态|运行时>模式

Status: <PASS|WARN|FAIL>

状态: <通过|警告|失败>

Audit doc validation (if provided)

审计文档验证（若提供）

Static inventory

静态能力清单

Annotation correctness

注解正确性

Ability	Claim	Result	Evidence

能力	声明	结果	证据

Permission gates

权限网关

Schema lints

架构校验

Error-code vocabulary

错误码词汇


Every ability is OK, WARN, or FAIL. A single FAIL → top-line FAIL;
WARNs without FAILs → WARN; otherwise PASS.


每个能力的状态为通过、警告或失败。存在单个失败→整体状态失败；仅存在警告无失败→整体状态警告；否则为通过。

Failure modes / debugging

失败模式/调试

Env not reachable (runtime) — env-up failed or Docker isn't running. Re-run
```
wp-project-triage
```
, then fix the env. Don't fall back silently to static without noting it in the report.
No abilities in source — return a clear "nothing to verify" report.
Audit schema mismatch — point at
```
references/audit-schema-validation.md
```
; don't auto-fix the audit.
False positive on readonly-writes — see the
```
// verify-ignore
```
mechanism in
```
references/annotation-correctness.md
```
. Document why each suppression is legitimate.
Runtime enumeration smaller than static — registration hook isn't firing. Check init hook timing, activation state, autoloader order.

环境无法访问（运行时模式） — 环境启动失败或Docker未运行。重新运行
```
wp-project-triage
```
，然后修复环境。请勿静默切换为静态模式，需在报告中注明。
源码中无能力 — 返回清晰的“无内容可验证”报告。
审计架构不匹配 — 指向
```
references/audit-schema-validation.md
```
；请勿自动修复审计文档。
只读写入的误报 — 参考
```
references/annotation-correctness.md
```
中的
```
// verify-ignore
```
机制。记录每个抑制操作的合理原因。
运行时枚举结果少于静态枚举 — 注册钩子未触发。检查初始化钩子时机、激活状态、自动加载顺序。

Escalation

升级流程

Recurring legitimate pattern that trips the adversarial check across multiple plugins → propose adding it to the suppression guidance in
```
annotation-correctness.md
```
. Don't broaden the candidate-pattern list speculatively.
Audit-schema validator rejects a legitimate audit → the canonical schema in
```
../wp-abilities-audit/references/audit-schema.md
```
has evolved. Update
```
references/audit-schema-validation.md
```
to match.

多个插件中反复出现触发对抗性检查的合理模式→建议将其添加到
```
annotation-correctness.md
```
的抑制指南中。请勿随意扩展候选模式列表。
审计架构验证器拒绝合理的审计文档→
```
../wp-abilities-audit/references/audit-schema.md
```
中的标准架构已更新。需将
```
references/audit-schema-validation.md
```
更新为匹配版本。

Out of scope

超出范围

Token-budget measurement is a separate verification axis — an annotation-clean, schema-clean, runtime-passing ability set can still be unshippable if its

tools/list

form burns through an agent's context budget. That axis is tracked separately. Do not aggregate manual or external measurement into this skill's PASS / FAIL verdict.

令牌预算测量属于独立的验证维度——注解合规、架构合规、运行时通过的能力集仍可能因

tools/list

形式消耗过多智能体上下文预算而无法发布。该维度需单独跟踪，请勿将手动或外部测量结果纳入本工具的通过/失败结论。