MADEVAL/BotBlocker-Add-on-Developer-Kit

# BotBlocker Add-on 开发工具包  本存储库是用于为 BotBlocker Security 构建第三方 add-on 的工作手册、模板、验证器和 AI 指令包。 BotBlocker Security 是一个 WordPress 防 bot 防火墙及主动防护插件。它通过请求检查、规则、CAPTCHA、日志、早期初始化保护以及基于 add-on 的扩展，来保护登录流程、XML-RPC、REST、评论、文件请求、支付回调和高风险流量。 ## 基准要求 - BotBlocker Security: `1.6.20+` - WordPress: `5.0+`，已测试至 `7.0` - PHP: `7.4+` - Add-on 格式: Add-on API v2，包含 `bbcs-addon.json` `1.6.20` 是支持 Add-on API v2 系统所需的最低 BotBlocker 版本。新的第三方 add-on 应将目标设定为 `1.6.20+`。 ## 内容概览 - `examples/acme-botblocker-sample`: 用于常规后期加载行为的规范 v2 示例 add-on。 - `examples/acme-traffic-guard`: 用于预运行 `traffic_decision_provider` 合约的高级 v2 示例 add-on。 - `docs/botblocker-runtime-contract.md`: BotBlocker 如何扫描、安装、激活和加载 add-on。 - `docs/addon-api-v2.md`: manifest、设置、生命周期、功能提供者 (feature providers) 及资产。 - `docs/botblocker-core-object.md`: 如何在 add-on 中安全读取实时的 `BotBlocker` 对象。 - `docs/botblocker-request-data.md`: BotBlocker 对象上可用的访客/请求/决策/浏览器数据映射。 - `docs/botblocker-settings-reference.md`: 用于只读 add-on 决策的 BotBlocker 核心设置参考。 - `docs/traffic-and-redirect-addons.md`: 面向流量管理器、重定向管理器和路由器的实用指南。 - `docs/core-hook-integration.md`: 必须在 BotBlocker 检查周期内运行的 add-on 的必需核心 hook 合约。 - `docs/settings-contract.md`: 第三方 v2 add-on 的确切设置保存合约。 - `docs/settings-ui-patterns.md`: BotBlocker 设置选项卡布局、帮助区块、字段类和字段示例。 - `docs/lifecycle-and-features.md`: 生命周期回调与功能提供者规则。 - `docs/code-quality-standard.md`: 必需的安全和代码质量标准。 - `docs/packaging-and-upload.md`: ZIP 结构、上传流程、常见上传错误。 - `docs/testing.md`: 静态、包、WordPress、生命周期、资产、multisite 及安全测试。 - `docs/compatibility-matrix.md`: 工具包/核心/运行时的兼容性对比。 - `docs/known-core-contract-gaps.md`: 需要在 BotBlocker 核心中验证或修复的已知实现缺口。 - `tools/validate-addon.php`: 用于文件夹和 ZIP 包的静态验证器。 - `tools/package-addon.ps1`: 用于构建正确的单根文件夹 ZIP 的 PowerShell 打包器。 - `ai/botblocker-addon-skill/SKILL.md`: 用于创建/审查 add-on 的 AI 指令。 ## 关键运行时模型 BotBlocker 不会从此存储库或您的源文件夹中直接加载第三方 add-on。它们只能在上传并安装后，从 WordPress 的 uploads 运行时目录中运行。 实际的运行时流程为： 1. 开发者构建一个以该 add-on slug 命名的源文件夹。 2. 开发者创建一个仅包含该唯一根文件夹的 ZIP。 3. 管理员在 `BotBlocker -> Add-ons` 中上传该 ZIP。 4. BotBlocker 验证该 ZIP 并将其安装到 `wp-content/uploads/botblocker/addons/{slug}`。 5. 在管理员激活之前，该 add-on 将保持非活跃状态。 6. 活跃且兼容的 add-on 将从运行时 uploads 目录中加载。 在编写代码之前，请先阅读 `docs/botblocker-runtime-contract.md`。 重要的时序说明：常规的活跃 v2 add-on 仍然会在主 BotBlocker 请求检查运行**之后**才被引入。流量 add-on 只有在明确选择加入 `docs/core-hook-integration.md` 中描述的预运行 (pre-run) 合约时，才能参与请求周期内部：manifest 的 `features` 必须包含 `traffic_decision_provider`，manifest 的 `runtime.pre_run` 必须指定一个安全的预运行文件，并且该文件必须暴露已声明的就绪标记 (readiness marker) 和注册回调 (registration callback)。 ## 关键流量控制警告 流量管理类 add-on 属于高风险的安全和运维代码。一条错误的规则可能会重定向真实访客、中断结账/支付回调、阻断支持/管理员工作流、隐藏 BotBlocker 的验证或拒绝页面、引发重定向循环，或削弱 BotBlocker 的保护能力。 仅当常规的检查后 WordPress hook 无法解决问题时，才应使用 `traffic_decision_provider`。发布流量 add-on 时应将其默认禁用，首先保持启用 `dry_run`，在 staging 环境下进行测试，记录回滚步骤，并且在生产环境的重定向、拦截、绕过或 CAPTCHA 决策被启用之前，必须要求管理员进行明确审查。 ## 新 Add-on 的快速路径 1. 将 `examples/acme-botblocker-sample` 复制到一个以您最终的 slug 命名的新文件夹中。 2. 重命名文件夹、manifest `slug`、根 PHP 文件、text domain、PHP 函数前缀、option 名称、句柄、CSS 类以及 JS 全局变量。 3. 在 `inc/core.php` 中定义行为。 4. 在 `inc/settings.php` 中定义管理员控件。 5. 在 `settings.option` 下声明每个设置字段，例如 `vendor_addon_settings[enabled]`。 6. 实现 manifest 中声明的 sanitizer。 7. 如果该 add-on 需要访客/请求数据，请阅读 `docs/botblocker-core-object.md` 和 `docs/botblocker-request-data.md`。 8. 如果该 add-on 执行重定向或管理流量，请阅读 `docs/traffic-and-redirect-addons.md`，检查 `examples/acme-traffic-guard`，并选择使用检查后的 WordPress hook 或更严格的预运行流量决策提供者 (pre-run traffic decision provider) 合约。 9. 仅在需要时实现生命周期回调。 10. 验证源文件夹。 11. 进行打包。 12. 验证 ZIP。 13. 通过 BotBlocker 管理后端上传并运行手动测试。 ## 验证 从此工具包的根目录运行： ``` php .\tools\validate-addon.php .\examples\acme-botblocker-sample php .\tools\validate-addon.php .\examples\acme-traffic-guard ``` 验证 ZIP： ``` php .\tools\validate-addon.php .\dist\acme-botblocker-sample.zip ``` ## 打包 PowerShell： ``` .\tools\package-addon.ps1 -AddonPath .\examples\acme-botblocker-sample -DestinationPath .\dist\acme-botblocker-sample.zip .\tools\package-addon.ps1 -AddonPath .\examples\acme-traffic-guard -DestinationPath .\dist\acme-traffic-guard.zip ``` 手动等效操作： ``` Compress-Archive -Path .\acme-botblocker-sample -DestinationPath .\acme-botblocker-sample.zip -Force ``` 请从包含该 add-on 文件夹的目录中运行手动打包命令。压缩该文件夹本身，而不是其中的文件。 正确的 ZIP： ``` acme-botblocker-sample.zip acme-botblocker-sample/ bbcs-addon.json acme-botblocker-sample.php inc/core.php inc/settings.php assets/icon.svg readme.txt ``` 错误的 ZIP： ``` acme-botblocker-sample.zip bbcs-addon.json inc/core.php ``` ## 最小 Manifest ``` { "schema": "2.0", "slug": "vendor-addon", "name": "Vendor Add-on", "version": "1.0.0", "requires_core": "1.6.20", "requires_php": "7.4", "author": "Vendor", "description": "Adds a focused BotBlocker extension with configurable runtime behavior.", "main": "vendor-addon.php", "core": "inc/core.php", "settings": { "view": "inc/settings.php", "option": "vendor_addon_settings", "sanitize": "vendor_addon_sanitize_settings" }, "lifecycle": { "activate": "vendor_addon_activate", "delete": "vendor_addon_delete" }, "features": [ "vendor_feature_provider" ], "assets": { "icon": "assets/icon.svg", "readme": "readme.txt" } } ``` 必填字段： - `schema` - `slug` - `name` - `version` - `requires_core` - `core` 针对常规 add-on 的质量必填字段： - `requires_php` - `author` - `description` - `main` - 存在管理员 UI 时的 `settings.view` - 保存设置时的 `settings.option` - 保存设置时的 `settings.sanitize` - `assets.icon` - `assets.readme` ## 设置合约 第三方 v2 设置必须使用 manifest 的 option 数组： ``` ``` 请勿复制 BotBlocker 内置的普通字段设置，例如： ``` ``` 这些字段之所以有效，仅仅是因为 BotBlocker 核心为其自身内置选项硬编码了内部保存逻辑。第三方 add-on 是通过 `BotBlockerAddons::saveSettingsFromPost()` 借由 `settings.option` 保存的。 ## 设置 UI 模式 `settings.view` 会作为 add-on 选项卡渲染在 `BotBlocker -> Tools` 内部。它应该以 BotBlocker 样式的帮助区块开始，然后渲染分组控件。 请使用此布局： ``` ``` 常见的 BotBlocker 字段包装器： - `bbcs_checkbox_input`, `bbcs_label_checkbox_box`, `bbcs_label_input_checkbox` 用于复选框。 - `bbcs_text_input`, `bbcs_label_input_box`, `bbcs-label-input`, `bbcs_text_input_inner`, `bbcs_text_input_input` 用于文本、URL 和数字字段。 - `bbcs_textarea_input`, `bbcs_textarea_input_inner`, `bbcs_textarea_input_input` 用于 textarea 字段。 - `bbcs_select_input`, `bbcs_select_input_inner`, `bbcs_select_input_select` 用于 select 字段。 复选框示例： ``` ``` 文本字段示例： ``` ``` Textarea 和 select 的示例请参见 `docs/settings-ui-patterns.md`。 ## 资产 已上传的 add-on 存在于 BotBlocker 插件源目录之外。请勿使用 `plugin_dir_url()` 来加载包内资产。 请使用： ``` function vendor_addon_asset_url( string $relative ): string { return class_exists( 'BotBlockerAddons' ) ? BotBlockerAddons::fileUrl( 'vendor-addon', $relative ) : ''; } ``` 服务器注意事项：BotBlocker 会将运行时包安装到一个受保护的 uploads 目录中。请务必在真实的 WordPress 安装中测试每个 icon/JS/CSS 的 URL，并确认返回 HTTP 200 状态码。详见 `docs/known-core-contract-gaps.md`。 ## 代码质量门禁 一个 add-on 只有在通过以下所有项后，才算开发完成： - 独特的 slug 和前缀 - 有效的 manifest - 有效的单根文件夹 ZIP - PHP 语法检查 (lint) - 验证器 - 经过转义的设置视图输出 - 显式的设置 sanitizer - 幂等的生命周期回调 - 不对运行时资产使用 `plugin_dir_url()` - 没有未添加前缀的全局变量 - 没有不安全的 superglobal 用法 - 不写入 BotBlocker 插件源目录 - WordPress 上传/激活/保存/停用/删除测试 - 使用静态资产时的资产 HTTP 200 测试 完整检查清单请阅读 `docs/code-quality-standard.md` 和 `docs/testing.md`。 ## 参考 Add-on 请将 `examples/acme-botblocker-sample` 作为标准的常规 add-on 模板。 仅当高级流量管理 add-on 必须参与 BotBlocker 请求周期内部时，才使用 `examples/acme-traffic-guard`。它演示了： - manifest `features: ["traffic_manager", "traffic_decision_provider"]` - manifest `runtime.pre_run` - 独立的 `inc/pre-run.php` - 就绪标记 (readiness marker) 和提供者注册回调 - dry-run 的 `log_only` 决策 - 受保护的 `redirect` 决策 - 位于 `settings.option` 下的 BotBlocker Tools 设置 - 包含哈希 IP 值的近期匹配日志记录 这两个工具包示例是第三方规范的参考。请直接复制并调整它们，而不要参考任何其他 add-on 源码。 ## 官方链接 - WordPress.org 插件页面: https://wordpress.org/plugins/botblocker-security/ - 产品网站: https://botblocker.top/products/ - 文档: https://botblocker.top/docs/ - 支持: https://botblocker.top/contacts/ - 社区: https://botblocker.top/community/ - 更新日志: https://botblocker.top/changelog/ - 开发者工作室: https://globus.studio/ - 架构与代码: https://leonidov.dev/ 截图、横幅、图标和公开链接请参见 `docs/links-and-assets.md`。 ## 完成标准 开发者或 AI 可以使用此工具包来创建 v2 add-on，对其进行验证、打包、通过 BotBlocker 管理后端上传、激活、查看其 Add-ons 卡片和 Tools 选项卡、保存设置、观察运行时行为、停用、删除并重新安装，且全程不会发生致命错误、PHP 警告、手动修改 BotBlocker 核心代码，或依赖未公开的假设前提。

标签：AI合规, API扩展, AppImage, ffuf, Homebrew安装, OpenVAS, PHP, WAF, Web应用防火墙, WordPress插件, 反机器人, 插件开发包, 文件完整性监控