wp-guard

WP Guard

在 WordPress 代码发布前，你正在审查生成或修改过的代码。首轮实现完成后，请按以下规则进行防护审查。做一名敏锐而非吹毛求疵的审查者：标出会引入漏洞、破坏翻译或压垮服务器的问题——忽略 WPCS 工具已处理的外观偏好。

这些规则之所以存在，是因为 AI Agent 会系统性地生成有问题的 WordPress 代码：直接 echo 请求数据、既没有 nonce 也没有权限检查的 AJAX 处理程序、通过字符串插值构建 SQL、用户可见字符串中硬编码的英文、在拥有百万篇文章的网站上使用 posts_per_page => -1，以及手动实现核心已有 API 的替代方案。这些做法在演示中看起来都没问题，却会在生产环境中出故障。

如何使用此技能

防护审查模式（推荐）：生成或编辑 WordPress 代码后，针对差异或目标文件应用这些规则，然后在交付前运行自检。向用户展示前先修复违规项。

实时模式（明确指定）：用户在编写 WordPress 代码前调用此技能时，编写过程中应用相同规则，然后在交付前运行自检。

审查模式（用户要求你审查、审计或评估 WordPress 代码时）：根据目标文件逐项检查 references/review-checklist.md，并生成结构化问题报告。除非用户要求，否则审查模式下不要编辑代码。

如果同时安装了 clean-code-guard，请将此技能与它配合使用：clean-code-guard 负责通用代码质量；wp-guard 负责 WordPress 层面。

先适配项目

1. 阅读项目的 Agent 指令（CLAUDE.md、AGENTS.md）、phpcs.xml/WPCS 配置和 composer.json。发生冲突时，以项目约定为准。
2. 确定既定前缀（函数、选项、元键、句柄）以及最低支持的 WP/PHP 版本。两者都要遵循。
3. 判断项目上下文：如果使用 WooCommerce API，则在已安装时同时应用 woo-guard；否则依据 WooCommerce 开发者文档遵循其 HPOS、CRUD 和结账规则。如果是多语言网站（WPML/Polylang/多站点），i18n 规则必须执行，不是建议。
4. 编写代码前先阅读一个相邻文件。沿用其中的错误处理、钩子注册风格和转义习惯——但若它们违反以下安全规则，则必须改正，这些规则不可妥协。

规则

安全——必须修复，无例外

1. 延后转义，全部转义。 每个进入 HTML 输出的变量都必须使用符合上下文的函数：esc_html()、esc_attr()、esc_url()，或用于富文本内容的 wp_kses()/wp_kses_post()。传入内联 JS 的数据必须通过 wp_json_encode() + wp_add_inline_script() 处理——esc_js() 已过时，仅适用于内联属性中的单引号字符串。转义应在输出时进行，而不是存储时。未使用 esc_* 包装的 echo $anything; 不通过审查。

2. 尽早清理，并先移除转义斜杠。 请求数据（$_POST、$_GET、$_REQUEST、$_SERVER）不得未经处理就参与逻辑：先用 wp_unslash()，再使用类型相符的清理函数（sanitize_text_field()、sanitize_key()、absint()、sanitize_email()，等等）。清理不等于转义；做了其中一项，不能免除另一项。

3. 每次状态变更都必须验证身份和意图。 会更改任何内容的表单处理程序、AJAX 端点和 REST 路由，都必须同时进行权限检查（current_user_can()）和 nonce 验证（check_admin_referer()、check_ajax_referer() 或 REST nonce 处理）。nonce 不等于授权。写入路由的 REST permission_callback 使用 __return_true 不通过审查。

4. 所有包含变量的查询都必须使用 $wpdb->prepare()。 使用占位符（%s、%d、%f，以及 WP ≥ 6.2 时标识符用的 %i），绝不进行插值或拼接。如果 WP_Query、元数据 API 和选项 API 能够表达该查询，应优先使用它们，而不是直接编写 SQL。

核心 API 规范

5. 使用平台功能，不要重复造轮子。 出站 HTTP 请求使用 wp_remote_get()/wp_remote_post()，绝不使用 curl。加载资源使用 wp_enqueue_script()/wp_enqueue_style()，绝不输出 <script>/<style> 标签。使用 WP-Cron 或 Action Scheduler 安排任务。重定向使用 wp_safe_redirect()，随后调用 exit。使用 WP_Filesystem 写入文件。简单的持久化数据使用选项/瞬态，不要创建自定义表。

6. 确认每个钩子和函数都存在。 在调用 add_action()、add_filter() 或核心/插件函数之前，确认其在受支持的版本中存在——阅读源代码或项目已安装的代码。凭空编造的钩子在 WordPress 中会静默失效：既没有错误，也没有行为。还要确保钩子与执行时机匹配——前端代码不会在 admin_init 上加载，查询也不会在 init 之前运行。

7. 为所有公开名称添加前缀或命名空间。 函数、类、选项、瞬态、元键、脚本句柄、AJAX 操作、REST 命名空间——都必须带有项目的前缀。通用名称（get_settings、data、api_key）迟早会与其他已启用的插件冲突。

8. 防止直接访问。 每个执行操作的 PHP 文件都必须以 ABSPATH 检查（或项目约定的等效检查）开头。

国际化

9. 每个面向用户的字符串都必须支持翻译。 根据上下文使用正确的包装函数（__()、_e()、_x()、_n() 或转义组合 esc_html__()、esc_attr__()）；文本域必须是与插件 slug 匹配的字面量——不能使用变量或常量；每个占位符都要附上译者注释；复数形式使用 _n()（绝不使用 sprintf 硬编码单复数选择）；不得通过拼接来组合句子。日期和数字使用 date_i18n()/wp_date() 和 number_format_i18n()。详情及 JS 国际化见：references/i18n.md。

性能

10. 规范查询。 绝不使用 posts_per_page => -1 或 query_posts()。只需要 ID 时使用 'fields' => 'ids'，不分页时使用 'no_found_rows' => true；绝不要在循环中执行本可以一次性预加载的查询（元数据/分类缓存）。详情见：references/performance.md。

11. 缓存开销大的工作，并在需要处加载资源。 远程调用和繁重计算应通过瞬态或对象缓存，并设置合理的 TTL。较大或很少读取的选项应注册为 autoload => false。脚本和样式只在使用它们的页面中加载。

交付前自查

1. 对 diff 执行 grep，查找 echo、print、<?=：所有变量输出是否都使用了符合上下文的函数进行转义？
2. 对 $_POST、$_GET、$_REQUEST 执行 grep：是否已去除斜杠、清理、验证 nonce 并检查权限？
3. 对 $wpdb-> 执行 grep：所有变量是否都通过占位符传入？
4. 是否有面向用户的字符串未使用国际化包装函数？是否有非字面量文本域？
5. 是否有尚未确认存在的钩子或函数？
6. 是否有无界查询、未缓存的远程调用或无条件加载的资源？
7. 每个新增的公开名称是否都带有项目的前缀？
8. 这是否能通过 WPCS（WordPress-Extra + WordPress-Security），且不会出现无法解释的警告？

如果任何一项不符合要求，请先修复，再展示给用户。

报告格式（审查模式）

**Rule N violation** in `path/file.php:<line or function>`
- What: <one sentence>
- Risk: <XSS / SQLi / CSRF / broken i18n / scaling — one phrase>
- Fix: <one sentence>

按文件分组，并优先列出安全问题。如果某个文件没有问题，不要提及。

严重程度指南

• 必须修复： 规则 1–4——这些问题可被利用（XSS、SQLi、CSRF、权限提升）
• 应该修复： 规则 5–9——这些问题会导致冲突、静默失败或发布内容无法翻译
• 值得注意： 规则 10–11——这些问题决定代码能否承受流量；对于每次请求都会运行的代码，必须解决

参考资料

• references/security.md — 转义／净化函数表、nonce 生命周期、REST 权限、$wpdb->prepare 详情、文件上传
• references/i18n.md — 包装函数选择、文本域规则、复数形式、译者注释、JS 翻译、RTL、多语言插件常见问题
• references/performance.md — WP_Query 标志、transient 与对象缓存的比较、自动加载规范、资源加载、cron、扩展性陷阱
• references/review-checklist.md — 审查模式的结构化检查流程
• references/sources.md — 手册和研究资料的网址；仅在引用来源时阅读

此技能不做什么

• 不运行 PHPCS、PHPStan 或 Plugin Check — 机械验证请使用项目的工具；此技能负责更高层面的判断。
• 不决定插件架构或业务逻辑 — 它负责把关 WordPress 代码的发布方式，而非代码的功能。
• 不替代 clean-code-guard 或 test-guard — 通用代码质量和测试质量仍由它们负责。