wp-site-audit-and-onboarding

WordPress 站点审计与接手入门技能

概述

为接手的或不熟悉的 WordPress 代码仓库和站点代码库提供系统化的入门指导。**核心原则：**在深入审查之前，先判断技术栈、梳理各个组成部分，并找出风险最高的后续审查方向。此技能旨在作为更广泛的 WordPress 技能包的入口，涵盖插件、主题、ACF、无头架构、WooCommerce、REST、迁移、性能、安全、CI/CD、WP-CLI、Playground 和 PHPStan。

目标不是一次性穷尽审查每个文件，而是：

1. 判断这是哪种 WordPress 系统
2. 找出架构上的关键区域
3. 揭示显而易见的风险信号
4. 按优先级推荐接下来使用的审查技能

适用场景

适用于：

• 接手新的 WordPress 代码仓库
• 首次审查客户站点的代码库
• 判断项目以插件、主题、无头架构、WooCommerce、多站点还是页面构建器为主
• 在迁移、审计、现代化改造或发布前评估风险
• 在深入的专项审查前，快速绘制架构图
• 用户提出如下问题：
  • “审计这个 WordPress 代码仓库”
  • “帮我熟悉这个站点”
  • “这个 WordPress 项目使用了什么技术栈？”
  • “我应该从哪里开始审查这个代码库？”
  • “这里风险最高的区域是什么？”

不适用于：

• 仅针对安全性的完整审查（使用 wp-security-review）
• 仅针对性能的完整审查（使用 wp-performance-review）
• 已明确插件范围后的深入插件架构审查（使用 wp-plugin-development）
• 已明确主题范围后的深入主题审查（使用 wp-theme-development）
• 已明确相关领域后的专项 WooCommerce、ACF、REST 或无头架构分析

审计工作流

遵循以下七步工作流。

1) 确定接手目标

明确要审计的对象：

• 整个代码仓库
• 单个插件
• 单个主题
• wp-content/ 子目录
• 将 WordPress 作为一个部分的 monorepo 应用
• 仅包含文档或仅包含 CI 配置的层

如果目标并非整个代码仓库，请注明有意排除的范围。

2) 首先判断项目形态

在评估代码库之前，先对其分类。

可能的技术栈信号：

• 以插件为主
  • 主插件头部信息
  • mu-plugins/
  • 自定义文章类型、分类法、管理页面
• 以主题为主
  • style.css、theme.json、templates/、parts/、functions.php
• 以区块/Gutenberg 为主
  • block.json、src/、build/、JSX、区块注册
• 以 WooCommerce 为主
  • woocommerce/ 模板、HPOS 声明、支付网关类、购物车/结账钩子
• 无头架构 / WPGraphQL
  • 前端应用目录、GraphQL 路由、webhook、重新验证流程、预览身份验证
• 以 REST/API 为主
  • register_rest_route()、schema 回调、外部集成
• 以 ACF/内容模型为主
  • acf-json/、CPT/分类法注册、字段组导出、大量使用 meta
• 多站点
  • 多站点常量、网络管理逻辑、站点/博客切换、全网范围的 CLI 或迁移代码
• Bedrock / Composer 管理
  • composer.json、web/、config/application.php、Roots/Bedrock 目录结构
• 以页面构建器为主 / 易受迁移影响
  • Elementor、Divi、WPBakery、Beaver Builder、短代码锁定

3) 梳理关键组成部分

为代码库绘制一份实用的结构图：

• 引导文件
• 仓库中包含的活跃插件/主题
• 自定义代码目录
• 构建工具（package.json、composer.json、GitHub Actions）
• 部署脚本和运维文档
• 测试（phpunit、playwright、集成/E2E 目录）
• 说明环境假设的文档

不要直接倾倒原始文件列表。应将结构归纳为有意义的组成部分。

4) 查找风险信号

尽早发现入门阶段的风险。

通常具有较高价值的信号：

• 多个自定义插件，或缺少清晰边界、范围庞大的主题逻辑
• 直接 SQL、自定义表或升级例程
• 自定义 REST/GraphQL/认证代码
• WooCommerce 结账、订单、支付或 webhook 集成
• 可能与已提交资源产生偏差的区块/主题构建系统
• 大量依赖 ACF/meta-query
• 多站点假设
• 门控机制不明确的发布/部署自动化
• 使用页面构建器导致锁定或存在迁移技术债的迹象
• 没有测试、静态分析或本地/开发文档

5) 转交给专项技能

建议下一步的审查路径，而不是超出本技能的范围。

后续转交示例：

• 自定义插件架构 → wp-plugin-development
• 自定义主题 / 区块主题 → wp-theme-development
• Gutenberg 区块 → wp-block-development
• WooCommerce 工作流 → wp-woocommerce-dev
• REST 路由 → wp-rest-api-development
• ACF/CPT/分类法建模 → wp-acf-and-content-modeling
• 无头架构 / WPGraphQL → wp-headless-and-wpgraphql
• 运维脚本 / WP-CLI / 多站点命令 → wp-wpcli-and-ops
• 迁移 / 架构变更 → wp-migration-upgrade-review
• 部署流水线 → wp-ci-cd-and-release-engineering
• 静态分析状况 → wp-phpstan-review
• 可复现演示或 Bug 复现 → wp-playground-development
• 跨领域安全风险 → wp-security-review
• 跨领域性能风险 → wp-performance-review

6) 确定后续行动的优先级

输出应分为：

• 优先立即审查 — 下一次审计应从何处开始
• 次要后续事项 — 重要，但不应优先处理
• 背景说明 — 有用的架构观察，但不是紧急问题

7) 根据具体情况评定严重程度

在入门阶段谨慎使用严重程度等级。

• CRITICAL： 可能存在生产风险、安全/电商/认证/迁移隐患，或仓库情况不明确，妨碍安全开展工作
• WARNING： 应尽快审查的重要风险或信息不明确之处
• INFO： 结构说明、现代化改进机会或低风险后续事项

本技能不应仅因架构复杂性通常较高，就将问题定为 CRITICAL。

文件与层面检查

仓库根目录 / 架构层

• CRITICAL：在复杂仓库中，没有明显的自定义代码唯一可信来源路径
• WARNING：存在多个重复的插件/主题副本，且无法明确哪个是当前目标
• WARNING：已提交构建产物，但没有明确的源文件夹或脚本
• INFO：可以改进仓库文档、本地设置或代码所有权说明

插件层面

• WARNING：自定义插件与供应商代码混在一起，且没有明确边界
• WARNING：多个自定义插件涉及相同领域（路由、结账、内容模型）
• INFO：可转交给 wp-plugin-development 进行更深入的架构审查

主题层面

• WARNING：主题中包含类似插件的业务逻辑、API 或迁移代码
• WARNING：经典主题与区块主题的边界不明确
• INFO：可转交给 wp-theme-development 或 wp-block-development

电商 / 集成层面

• CRITICAL：存在支付、webhook 或订单逻辑，但未经测试或隔离不充分
• WARNING：WooCommerce 定制程度较高，可能导致升级脆弱
• INFO：可转交给 wp-woocommerce-dev

无头架构 / API 层面

• CRITICAL：自定义认证、预览或缓存失效路径缺少明显文档
• WARNING：REST 和 GraphQL 层面混杂，且责任归属不明确
• INFO：可转交给 wp-headless-and-wpgraphql 或 wp-rest-api-development

运维 / 交付层面

• WARNING：存在部署/发布脚本，但没有回滚或环境说明
• WARNING：WP-CLI 自动化会操作多站点或类似生产环境的数据，但没有明显的保护措施
• INFO：可转交给 wp-ci-cd-and-release-engineering 或 wp-wpcli-and-ops

快速检测的搜索模式（ONBOARD-21）

使用这些 rg 命令快速分类项目。

技术栈发现

rg -n "Plugin Name:|register_activation_hook|register_deactivation_hook|register_uninstall_hook" . -g '*.php'
rg -n "theme\.json|Template Name:|add_theme_support\(|register_nav_menus\(|after_setup_theme" . -g '*.{php,json,css}'
rg -n "block\.json|registerBlockType|@wordpress/|wp\.blocks|useBlockProps|InnerBlocks" . -g '*.{json,js,jsx,ts,tsx,php}'

平台和软件包布局

rg -n "roots/bedrock|config/application\.php|composer install|wp core download" . -g '*.{json,php,md,yml,yaml,sh}'
rg -n "multisite|is_multisite\(|switch_to_blog\(|restore_current_blog\(|WP_ALLOW_MULTISITE|SUNRISE" . -g '*.{php,md,yml,yaml}'
rg -n "woocommerce|WC_|Automattic\\WooCommerce|FeaturesUtil::declare_compatibility|action_scheduler" . -g '*.{php,js,md,yml,yaml}'

内容、API 和无头模式信号

rg -n "acf-json|acf_add_local_field_group|register_post_type\(|register_taxonomy\(|meta_query|get_field\(|the_field\(" . -g '*.{php,json}'
rg -n "register_rest_route\(|WP_REST_Controller|permission_callback|rest_api_init" . -g '*.php'
rg -n "graphql|wpgraphql|revalidate|preview|previewData|headless|Next\.js|next build|ISR|webhook" . -g '*.{php,js,jsx,ts,tsx,md,yml,yaml}'

迁移和构建器信号

rg -n "elementor|divi|vc_|wpbakery|beaver builder|shortcode|\[[a-z0-9_-]+\]" . -g '*.{php,js,json,md,xml}'
rg -n "dbDelta\(|CREATE TABLE|ALTER TABLE|update_option\(\s*'[^']*version|schema" . -g '*.php'

交付和质量信号

rg -n "phpunit|WP_UnitTestCase|playwright|cypress|codecept|phpstan|psalm|eslint|wpcs|phpcs" . -g '*.{php,xml,json,js,ts,md,yml,yaml}'
rg -n "workflow|deploy|release|rollback|artifact|svn|wordpress\.org|rsync|capistrano" . -g '*.{md,yml,yaml,sh,json}'

参考文件

• references/stack-detection-and-signals.md - 如何快速对 WordPress 代码库进行分类，以及各项技术栈信号的含义
• references/audit-checklist.md - 用于仓库和代码库的实用初步接入检查清单
• references/routing-and-followups.md - 接入后如何将仓库交接给合适的 WordPress 专项技能
• references/sample-onboarding-output.md - 实用接入摘要的报告格式示例

输出格式（ONBOARD-23）

请使用以下输出结构。

1. 项目概况

• 仓库或目标路径
• 主要分类
• 次要分类
• 检测到的关键技术栈信号

2. 架构概览

• 主要代码区域
• 自定义组件
• 构建／测试／部署区域
• 特殊的平台特征

3. 优先发现

按严重程度分组：

• CRITICAL
• WARNING
• INFO

每项发现应包括：

1. 文件或区域
2. 简要的问题／风险摘要
3. 这对接入或安全开展后续工作的影响
4. 建议的下一项审查技能或操作

4. 建议的审查顺序

按顺序列出接下来的 2–5 项审查，例如：

1. wp-plugin-development，用于审查自定义电商插件
2. wp-woocommerce-dev，用于审查结账和 HPOS 兼容性
3. wp-ci-cd-and-release-engineering，用于审查发布和部署流程

5. 尚未明确的事项

指出根据现有文件无法确定的内容，例如：

• 生产环境中的插件启用状态
• 已提交的构建产物是否与源代码一致
• 多站点／网络模式是否确实已启用
• 是否存在未记录的外部服务

最后提醒

这是一项接入和路由技能。请提供实用、具体且有指导性的内容。不要将其扩展为一次性深入审查每个已检测子系统的完整评估。