wp-abilities-audit

WP Abilities Audit

为 WordPress 插件的 REST 接口生成标准化审计文档，并按语义意图分组提出一组 Abilities API 注册项。审计文档是供实现者（人类、Agent，或两者）使用的规划材料，以结构化形式记录控制器清单、能力门控和建议的能力形态。审阅者阅读文档后即可界定工作范围，无需重新调查。

此技能适用于任何提供 REST 接口的插件。插件分类（用于可选的 plugin_family 注解）由用户决定；工作流本身与插件无关。

适用场景

• 任务是“为 WP 插件注册 Abilities API 能力”，且尚无审计文档。
• 参与多插件能力上线的规划，并需要一份可共享的标准化审计材料。
• 在实现能力之前，预先检查插件是否已做好 Agent 接入准备。
• PM 或非实现者希望在工程团队接手之前界定工作范围。

所需输入

1. 插件检出路径 — 要审计的插件工作树。
2. 分类输出 — 如果尚未运行，请先运行 wp-project-triage。审计会使用报告中的 signals.usesAbilitiesApi、versions.wordpress 和 project.kind。
3. 审计者身份 — 姓名和团队或上下文，记录在审计文档的 auditor 字段中。
4. 输出路径 — 审计文档的保存位置。默认明确优先于隐式；若未提供，请先询问，不要写入插件工作树。

前置条件

• 已成功运行 wp-project-triage，并对插件完成分类。
• 插件至少有一个 REST 控制器。如果枚举结果中没有控制器，则不适用此审计——请参阅下方的“故障情形”。

流程

1. 枚举 REST 控制器

现在阅读 references/controller-enumeration.md——其中介绍了两种已观察到的枚举方式（标准布局使用 glob，通用回退方式使用 grep），以及各自的适用场景。

在“控制器清单”表格中记录每个控制器类、文件、REST 基础路径和路由。即使最终只有部分控制器会成为建议的能力，清单也必须完整。

2. 提取每个控制器的后端字段

对找到的每个控制器，提取审计架构要求的字段：类、文件、HTTP 方法、路由、路由注册行号、回调名称、回调行号、权限回调、回调是否接受 WP_REST_Request 参数或不接受参数，以及返回类型。

现在阅读 references/audit-schema.md，了解确切的字段列表和 proposed_abilities 条目的结构。对于继承的回调，行号字段可以是 null——架构允许这种情况，并提供可选的 inherited_from 字段与之对应。

3. 确认能力门控

追踪每个控制器的 permission_callback，直到其 current_user_can() 调用（如果控制器继承自基于文章类型的基类，则追踪到文章类型的能力机制）。

现在阅读 references/capability-gate-tracing.md——其中介绍了两种常见机制（直接调用 check_permission() 与基于文章类型的 wc_rest_check_post_permissions()），以及如何在架构中表示它们。请明确注明读取和写入门控是否不同：复合门控应表示为 {read, write} 对象，而不是单个字符串。

4. 使用语义意图分组提出能力

不要为每个 HTTP 方法拆分出一个能力。应用语义意图分组启发式规则——这是本技能唯一使用的分组规则。

现在阅读 ../wp-abilities-api/references/grouping-heuristic.md——不要在此重新推导规则。简而言之：每个真实场景中的问题或状态转换对应一个能力；通过 input_schema 中的筛选参数，将 N 个变体合并为 1 个。

填充任何候选项前，先应用用例合理性检查。 根据 ../wp-abilities-api/references/domain-vs-projection.md 中的用例契约测试：人或 Agent 是否会有意通过受支持的插件工作流执行此行为？如果会，该候选项就是真实能力——继续填写字段。如果不会，该路由属于内部传输层管道（缓存失效、计划任务触发、记账端点、调试内省）——为保证完整性，将其保留在 Controller Inventory 部分，但不要将其提升到 proposed_abilities。该路由可能有助于清点，但拟议能力必须代表真实的用户／运维人员问题或操作。

对于通过合理性检查的每项拟议能力，填写 proposed_abilities 架构中的所有字段：name、intent、backing、permission、return_type、effort（S/M/L）、annotations（readonly/destructive/idempotent）、notes、risks、use_case_fit、side_effects、seed_data_needs。

最后三个字段是实现就绪所需的信息，实现者和验证模式工具都需要这些信息：此能力服务于哪种人类／Agent 工作流（use_case_fit）、每次调用时底层路径会产生什么（side_effects——空数组也是事实，而不是缺失值），以及要让能力通过公共边界执行，测试环境中必须有哪些代表性数据（seed_data_needs）。

5. 列出缺口和延后事项

分为三个类别：

• excluded_from_mvp — 因风险而有意延后的候选项（真实资金写入、不可逆状态变更或前置设计工作）。每个条目附上一句理由。
• surfaced_gaps — 没有底层端点的 MVP 候选项（backing: null 的能力），以及枚举时发现、虽不在 MVP 列表中但易于后续实现的高价值端点。
• 每项能力的风险 — 实现者必须处理的底层端点相关问题（没有幂等键、双阶段行为、状态转换注意事项，以及通过 permission_callback => '__return_true' 注册的零参数端点，不得在能力注册中照搬这一设置）。

6. 编写审计文档

写入“Inputs required”中收集到的明确输出路径。文档结构必须与 references/audit-schema.md 完全一致：

1. Last updated: YYYY-MM-DD HH:MM 标题。
2. 包含所有必需顶层元数据以及 proposed_abilities、excluded_from_mvp、surfaced_gaps 的 YAML 区块。
3. “Controller Inventory”表格。
4. “Notes and Surprises”说明部分。

references/audit-schema.md 的“Minimal valid example”中有展示完整结构、可直接复制粘贴的最简示例；编写新审计文档时从那里开始。

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

在实现者应首先完成的能力上设置 reference_ability: true——通常选择最小、最安全、杠杆效益最高的读取能力。这样下游工作流就有了确定的起点。

验证

• 审计文档符合 references/audit-schema.md（包含所有必需顶层字段、proposed_abilities 至少有一个条目，且每项能力的注释均完整）。
• 单能力插件的 capability_gate 是字符串；以文章类型为基础的插件则使用 {read, write} 对象。
• 每项 backing: null 的能力也必须出现在 surfaced_gaps 中。
• 文档通过 audit-schema.md“Known limitations”中的验证器往返验证，且无错误。

失败模式 / 调试

• 插件没有 REST 控制器——审计不适用。可考虑基于钩子/筛选器的能力（不在当前版本技能的范围内），或跳过对此插件的能力采用审计。
• 插件继承了其他代码仓库中的控制器（常见于扩展核心文章类型控制器（如 WP_REST_Posts_Controller）的插件，或基于父级 REST 类构建的扩展插件）——使用 backing.inherited_from: "<parent FQCN>" 记录。根据架构，行号字段可以是 null。
• 复合能力门控（读取/写入权限不同）——使用 references/capability-gate-tracing.md 中记录的结构化 {read, write} 格式。不要将用 / 分隔的字符串塞进类型为单个权限的字段。
• 分组不明确——参阅 ../wp-abilities-api/references/grouping-heuristic.md。不要在审计文档中自行制定其他分组规则。
• 使用 permission_callback => '__return_true' 的零参数端点——在 REST 层面合法，但能力自身的 permission_callback 必须与插件的商家权限门控一致。切勿将 '__return_true' 提升为能力注册项。请在该能力的 risks 中注明这一点。
• 输出路径默认为插件工作树——始终询问用户指定明确的输出目录（例如其知识库中的 plans/）。将审计写入插件自身的 git 历史会污染工作树，并使产物难以查找。

升级处理

• 如果插件采用的枚举惯例不在 references/controller-enumeration.md 涵盖范围内（标准 glob 和 grep 回退都无法生成完整清单），请更新该参考文档，补充新惯例，并提交 PR，以便未来的审计能够确定性地覆盖这种情况。
• 如果权限追踪遇到 references/capability-gate-tracing.md 未涵盖的机制，请扩展该文件，而不要只在审计的“注意事项与意外情况”中记录新案例。