名称: wp-plugin-development 描述: “在开发WordPress插件时使用：架构和钩子、激活/停用/卸载、管理界面和设置API、数据存储、定时任务/任务、安全性（随机数/权限/清理/转义）以及发布打包。” 兼容性: “目标WordPress 6.9+ (PHP 7.2.24+)。基于文件系统的代理，使用bash + node。部分工作流需要WP-CLI。”
WordPress插件开发
何时使用
此技能适用于插件开发工作，例如：
- 创建或重构插件结构（引导程序、包含文件、命名空间/类）
- 添加钩子/动作/过滤器
- 激活/停用/卸载行为及数据迁移
- 添加设置页面/选项/管理界面（设置API）
- 安全修复（随机数、权限、清理/转义、SQL安全）
- 打包发布（构建产物、说明文档、资源文件）
所需输入
- 代码库根目录 + 目标插件（如果已知，提供插件主文件路径）。
- 插件运行环境：单站点 vs 多站点；如果适用，说明WP.com的约定。
- 目标WordPress + PHP版本（影响可用API和
$wpdb->prepare()中的占位符支持）。
操作流程
0) 初步排查并定位插件入口点
- 运行初步排查：
node skills/wp-project-triage/scripts/detect_wp_project.mjs
- 检测插件头部信息（确定性扫描）：
node skills/wp-plugin-development/scripts/detect_plugins.mjs
如果这是一个完整的站点代码库，请在修改代码前，选择wp-content/plugins/或mu-plugins/下的特定插件。
1) 遵循可预测的架构
指导原则：
- 保持单一的引导程序（带有头部信息的主插件文件）。
- 避免在文件加载时产生大量副作用；应在钩子上加载。
- 优先使用专用的加载器/类来注册钩子。
- 将仅限管理员的代码放在
is_admin()（或管理员钩子）后面，以减少前端开销。
参见：
references/structure.md
2) 钩子和生命周期（激活/停用/卸载）
激活钩子较为脆弱；请遵循以下防护措施：
- 在顶层注册激活/停用钩子，而不是在其他钩子内部
- 仅在需要时刷新重写规则，并且要在注册自定义文章类型/规则之后进行
- 卸载操作应明确且安全（使用
uninstall.php或register_uninstall_hook）
参见：
references/lifecycle.md
3) 设置和管理界面（设置API）
对于选项，优先使用设置API：
register_setting(),add_settings_section(),add_settings_field()- 通过
sanitize_callback进行清理
参见：
references/settings-api.md
4) 安全基线（始终遵守）
发布前：
- 尽早验证/清理输入；在输出时进行转义。
- 使用随机数防止CSRF攻击并且进行权限检查以授权。
- 避免直接信任
$_POST/$_GET；使用wp_unslash()和特定的键。 - 对于SQL，使用
$wpdb->prepare()；避免使用字符串拼接构建SQL。
参见：
references/security.md
5) 数据存储、定时任务、迁移（如果需要）
- 小型配置优先使用选项；仅在必要时使用自定义表。
- 对于定时任务，确保幂等性并提供手动运行路径（WP-CLI或管理界面）。
- 对于模式更改，编写升级例程并存储模式版本。
参见：
references/data-and-cron.md
验证
- 插件激活时无致命错误/通知。
- 设置正确保存和读取（强制执行权限和随机数检查）。
- 卸载时移除预期数据（且仅移除预期数据）。
- 运行代码库的代码检查/测试（如果存在PHPUnit/PHPCS），以及插件打包资源时的任何JS构建步骤。
故障模式 / 调试
- 激活钩子未触发：
- 钩子注册不正确（不在主文件作用域内）、主文件路径错误，或插件是网络激活的
- 设置未保存：
- 设置未注册、选项组错误、缺少权限、随机数检查失败
- 安全回归：
- 存在随机数但缺少权限检查；或输入已清理但在输出时未转义
参见：
references/debugging.md
升级处理
在发明新模式之前，请查阅插件手册和安全指南以获取规范细节。