wp-abilities-verify

WP Abilities 验证

验证 WordPress 插件的 Abilities API 注册。核心环节是对抗式注释正确性检查：一个标注为 readonly: true、实际却会写入数据的能力（通过 $wpdb->update、update_option、非 GET 委托等方式）会造成安全和用户体验灾难，因为 Agent 会根据其检查到的注释来规划操作。这项技能会读取回调函数体，并将其实际行为与注释声明进行比较，从而发现这些谎报。

此技能还会验证由 wp-abilities-audit 生成的审计文档，检查权限门控和架构规范性，并可选择对每项能力执行实时环境测试。

适用场景

• 在插件中注册能力后、PR 合并前。
• 对已发布的插件进行健康检查（发现重构导致只读能力变为写入能力等回归）。
• 将审计文档交给实现者前对其进行验证。

两种模式

• 静态模式 — 在插件检出目录中运行。无需环境。通过源码检查枚举能力，执行对抗式正确性检查、架构和权限检查，并验证审计文档。
• 运行时模式 — 需要已运行的环境。包含静态模式的所有操作，另外还会：通过 wp_get_abilities() 权威枚举能力；使用精心挑选的输入执行每项能力；针对真实用户确认权限往返验证；并对标记为 idempotent: true 的能力执行双重调用启发式检查，以标记待审查项（返回值相等只是一个信号，并非定论——核心将幂等定义为“不会对环境产生额外影响”）。

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

静态模式的 PASS 表示“未发现明显形式上的违规”，不表示“已验证不会写入数据”。对于高风险插件，合并前应运行时模式——它能发现静态检查无法发现的引导顺序、权限往返验证和幂等性问题。有关静态检查的盲点，请参阅 references/annotation-correctness.md。

所需输入

1. 插件检出路径 — 要验证的工作树。
2. 模式 — static 或 runtime。未指定时默认为静态模式。
3. （仅运行时模式）启动环境的命令 — 阅读插件的 AGENTS.md。 常见模式：npm run wp-env start、npx wp-env start，或基于 composer 的启动方式。有自有开发工具的插件系列会记录各自的命令。切勿假设 npm run wp-env 可用。
4. （可选）审计文档路径 — 启用审计文档与已注册能力之间的交叉检查，并验证审计文档本身。
5. 报告输出路径 — 明确的路径，通常为用户的知识库。

前提条件

• 已对插件运行 wp-project-triage。
• 插件源码中至少注册了一项能力。如果在 wp_register_ability( 上没有任何匹配项，应返回明确的“未注册任何能力”报告，而不是空的 PASS。

流程

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

阅读 references/audit-schema-validation.md。根据 wp-abilities-audit 所维护的规范架构验证审计文档。指出缺少的必填字段、多个 reference_ability: true，以及未配对 surfaced_gaps 条目的 backing: null 项。单独出现 backing: null 属于 WARN（有意记录的缺口），不属于 FAIL。

2. 静态枚举能力

阅读 references/static-enumeration.md。查找每个 wp_register_ability( 调用，提取名称、注释块和执行回调位置。使用多行工具（rg --multiline --pcre2）——规范格式会将调用拆分为多行。记录每项能力的源文件、行号、注释和回调字节范围。

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

阅读 references/runtime-harness.md。使用 AGENTS.md 中的命令启动环境，然后通过 wp-cli 调用 wp_get_abilities() 枚举能力，并与静态清单交叉核对。仅源码中有、运行时没有 → FAIL（注册未生效）。仅运行时有 → WARN（动态注册路径）。

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

阅读 references/annotation-correctness.md。阅读每个回调主体，并核实其是否符合注解声明：

• readonly: true → 回调不得写入数据库、选项表、文章／用户／术语／评论数据、文件系统、cron，也不得通过非 GET HTTP／REST 委托执行写入。
• destructive: false → 回调不得删除、退款、作废、取消或移至回收站。
• idempotent: true → 使用相同输入重复调用时，不得对环境产生额外影响（参见 class-wp-ability.php 中 idempotent 注解的文档块）。静态检查会捕获计数器写入和每次调用时安排的 cron 任务；运行时检查则会增加一种针对可见状态变化的双重调用启发式检测。

参考文档列出的常见写入模式只是起始集合，并非检查清单——各插件使用的术语各不相同，Agent 会针对正在验证的插件补充特定动词。

误报可通过行内注释 // verify-ignore: <annotation> -- <reason> 抑制。

5. 权限往返验证

阅读 references/permission-roundtrip.md。静态检查：根据六种形式对每个 permission_callback 进行分类（首选形式 A：current_user_can(...)；形式 B-bad 的 WP_REST_Request 模式或形式 E 的字面值 true 均判定为 FAIL）。运行时检查：匿名用户和订阅者应被拒绝，管理员应获准（除非明确设为公开）。若提供了审计，则将注册的能力与审计中声明的权限门槛交叉核对。

6. Schema 检查

阅读 references/schema-lints.md。针对每个能力的 input_schema 应用六条简单原则：对象 schema 声明 additionalProperties；必填字段有描述；枚举非空；不使用 $ref；默认值在静态检查中为常量（包括 (object) array()）；参考能力没有必填输入。

交叉参考 ../wp-abilities-api/references/input-schema-gotchas.md，了解四种运行时陷阱（属性级路径不会注入默认值、分页键漂移、对字符串 ID 使用 empty()、直接调用与间接调用的严格程度不同）。

7. 错误代码词汇

交叉参考 ../wp-abilities-api/references/error-code-vocabulary.md。检查每个回调返回的 WP_Error；不在词汇表中的代码 → WARN。

验证

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

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

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

## Status: <PASS|WARN|FAIL>

## Audit doc validation (if provided)

## Static inventory

## Annotation correctness
| Ability | Claim | Result | Evidence |
|---|---|---|---|

## Permission gates

## Schema lints

## Error-code vocabulary

每个能力的状态为 OK、WARN 或 FAIL。只要出现一个 FAIL → 顶层状态为 FAIL；没有 FAIL 但有 WARN → WARN；否则为 PASS。

故障模式／调试

• 环境无法访问（运行时） — env-up 失败或 Docker 未运行。重新运行 wp-project-triage，然后修复环境。不要悄然退回静态检查，必须在报告中说明。
• 源代码中没有能力 — 返回一份明确说明“无需验证”的报告。
• 审计 schema 不匹配 — 指向 references/audit-schema-validation.md；不要自动修复审计。
• readonly-writes 误报 — 参见 references/annotation-correctness.md 中的 // verify-ignore 机制。说明每项抑制为何合理。
• 运行时枚举结果少于静态检查 — 注册钩子未触发。检查 init 钩子的时机、激活状态和自动加载器顺序。

升级处理

• 多个插件中反复出现、会触发对抗性检查的合理模式 → 建议将其加入 annotation-correctness.md 的抑制指南。不要臆测性地扩大候选模式列表。
• 审计 schema 验证器拒绝了合理的审计 → ../wp-abilities-audit/references/audit-schema.md 中的规范 schema 已更新。更新 references/audit-schema-validation.md 以保持一致。

不在范围内

Token 预算测量属于单独的验证维度——即使能力集的注解和 schema 均无问题，且通过了运行时检查，如果其 tools/list 形式耗尽了 Agent 的上下文预算，仍然无法发布。该维度单独跟踪。不要将手动或外部测量结果纳入此技能的 PASS／FAIL 判定。