如何搭建一个与 Agent 原生协作的 WordPress 网站

用 Agent 生成一个页面很容易，把需求写清楚，HTML 就出来了。但要让 Agent 长期维护一个 WordPress 网站，光会生成页面远远不够。它需要理解项目背景、设计规范和技术约束，知道每个文件归谁管，改动之前先确认线上的真实状态，发布之前跑一遍完整的检查。

这篇文章把整套流程整理成八个阶段：准备 staging、建立项目工作区、设计系统、本地验收、主题工程化、SEO 与结构化数据、staging 验收、发布 production。前三个阶段打基础，中间四个阶段产页面，最后一个阶段收尾上线。整个过程都在非生产环境开发和验收，最后才发布到生产站。

三条基本原则

进入阶段之前，先记住三条原则，后面的每一步都建立在它们上面。

先确认线上真实状态，再修改本地文件。本地文件可能落后于线上。开始同步、重构或镜像任务前，先从线上读取页面、文章、产品、分类、slug、特色图、AIOSEO 的 meta 和 schema、functions.php、主题目录以及已加载的 CSS 和 JS。本地快照可以作为工作基线，但不能自动视为线上最终事实。涉及同步时，以明确指定的线上站点为准，并记录抓取时间。

所有生产改动都应可备份、可验证、可回滚。生产发布前至少保存数据库备份、wp-content 及当前子主题备份、本次变更清单、变更前后关键对象的 JSON 快照。任何批量更新都要有明确的目标范围、幂等逻辑（重复运行不会创建重复内容）、dry-run 或只读审计步骤、成功和失败统计、回滚脚本或可恢复备份。

凭据不进项目目录。WordPress Application Password、SSH 私钥、AIOSEO API 凭据、数据库密码和第三方 API Key 只保存在本机的 secrets 目录或受控密码管理器中。不要把密码写进 AGENTS.md、脚本、JSON payload 或 Git，不要把包含真实凭据的 .env 上传到网站目录，也不要在聊天记录、命令输出或日志中打印完整密钥。

阶段一：准备 staging 环境

在 Hostinger 或其他主机上创建 staging 环境，用独立的 staging 域名或子域名，例如 staging.example.com。开启 SSH，本机生成 SSH key 并把公钥加入服务器，配置 ~/.ssh/config 使用明确的 Host 别名。然后配置 SSL、PHP 版本、PHP memory limit、上传限制和数据库字符集，再加一层访问保护，比如 HTTP Basic Auth、IP 限制或临时密码。

staging 必须禁止搜索引擎索引。可以同时使用 WordPress 的阻止搜索引擎索引设置、HTTP Basic Auth 或其他访问控制、noindex 响应头或页面 meta。不要只依赖 robots.txt，它不能阻止 URL 被发现或被收录。

WordPress 初始设置完成后才开始页面开发：修改管理员用户名和强密码、设置站点标题和固定链接、删除示例内容、安装备份缓存安全工具、确认 HTTPS 和 REST API 正常、关闭 XML-RPC 和公开用户注册、记录 WordPress 和插件版本。

主题基础用 Hello Elementor 加子主题。子主题目录名称以服务器实际目录为准，不要假定一定是 hello-theme-child-master。激活后确认 style.css 包含有效的子主题 header、functions.php 没有 PHP fatal error、父主题和子主题加载顺序正确。同时明确页面用哪种渲染方式：Elementor Canvas、Elementor Full Width、主题默认模板、自定义 page.php 或项目自己的页面模板。不同模板决定是否输出主题的 .site-main、最大宽度和内边距，不能把 Elementor Full Width 当成所有网站的通用必选项。

子主题建议的结构：

hello-elementor-child/
├── style.css
├── functions.php
├── assets/
│   ├── css/
│   ├── js/
│   ├── images/
│   └── fonts/
├── inc/
├── template-parts/
└── page-templates/

template-parts、page-templates 和 inc 是否需要，取决于项目规模，不要为了形式创建大量空目录。

阶段二：建立项目工作区和 Agent 上下文

项目目录建议这样组织：

your-website/
├── AGENTS.md
├── DESIGN.md
├── PROGRESS.md
├── TO-DO.md
├── README.md
├── source-content/
├── assets-source/
├── page-design/
├── pages/
├── templates/
├── seo/
├── schemas/
├── snapshots/
├── deploy/
├── scripts/
└── hello-elementor-child/

AGENTS.md 写项目级事实和约束，不是一次性任务描述。至少包括：公司、产品、客户和业务模式；目标市场、语言和品牌语气；技术栈、主题、插件和服务器结构；线上与 staging 的连接别名；页面、产品、文章和资源中心的 URL 规则；CSS、JS、PHP、schema 和 SEO 的归属规则；禁止修改的页面或 Elementor 内容；发布前测试清单；凭据所在位置，但不写凭据本身。

CLAUDE.md、AGENTS.md 这类文件名取决于 Agent 工具。如果团队用多个 Agent，优先维护一份通用项目规范，再用工具专属文件补充差异，避免出现互相矛盾的规则。

PROGRESS.md 和 TO-DO.md 记录每个阶段：已完成事项、当前处理中的事项、下一步任务、阻塞原因、变更日期、线上环境和验证结果。任务写成可验证的动作，例如完成产品分类页 12 个 slug 的 SEO 检查，不要只写优化 SEO。

阶段三：先建设计系统，再制作页面

第一次和 Agent 沟通时，提供完整背景：公司介绍和制造能力、核心产品和应用场景、目标客户和采购流程、目标国家和市场定位、品牌 logo 和颜色、产品图和工厂图、希望的视觉方向、不能使用的视觉元素和文案表达。

先完成 Home 定稿，再做一个代表性 Landing Page，验证设计系统能否迁移到具体营销任务。视觉要求包括层级、对比、留白、字体、色彩和交互，但应与行业、客户和转化任务匹配。不要只追求设计感，还要检查首屏是否清楚表达产品和价值、CTA 是否明确、移动端是否可用、对比度和点击区域是否合格、图片是否真实反映产品而不是泛化 stock photo、页面加载是否可接受。

Home 和 Landing Page 定稿后，要求 Agent 把实际设计规则提炼成 DESIGN.md：色彩 token、背景色和状态色；字体、字号、行高和标题层级；容器宽度、网格、间距和响应式断点；Hero、CTA、按钮、表单、表格、FAQ 和卡片规范；图片比例、圆角、阴影和边框规则；Header、Footer 和导航行为；移动端布局规则；可复用 CSS class 和命名空间；不应出现的组件或视觉模式。

DESIGN.md 是设计约束，不是代替人工审查的自动保证。每次生成新页面后仍需进行视觉和功能验收。

阶段四：本地生成、预览与验收

Agent 根据 DESIGN.md、页面目录资料和项目规则生成本地 HTML 预览。每个页面至少检查：

• 桌面、平板和手机布局。
• 导航、按钮、表单和弹窗。
• 图片、视频、iframe 和字体加载。
• 内部链接、邮件链接和产品链接。
• 长标题、长表格、FAQ 和错误状态。
• 键盘导航、焦点状态、语义标题和颜色对比度。
• 页面在无 JS 或网络较慢时的合理降级。
• 控制台错误、404、混合内容和重复 ID。

本地预览满意后再进入 WordPress 适配。不要一边上传一边继续修改未验收的 HTML。

阶段五：WordPress 主题工程化

页面内容与主题代码分离，推荐的职责划分：

• style.css：子主题声明和极少量全局基础样式。
• assets/css/ 和 assets/js/：按功能或页面拆分的 CSS 和 JS。
• template-parts/：可复用 PHP 片段。
• page-templates/：带 WordPress Template Name 的页面模板。
• inc/：注册、过滤器、辅助函数和配置。
• WordPress 页面正文：页面专属 HTML 内容。

CSS 使用项目命名空间，避免污染 Elementor、WooCommerce 或其他插件：

.agent-site--contact .agent-contact-form {
  border: 1px solid #e6e4df;
  border-radius: 8px;
  padding: 1rem;
}

JS 使用明确的依赖、初始化入口和错误处理，避免在所有页面加载不需要的脚本。

所有 CSS、JS、模板支持代码都通过 functions.php 或 inc/ 中的注册函数加载，不要把大量 style、script 或 PHP 逻辑散落在页面正文中。enqueue 时明确 handle、文件路径、依赖关系、版本号或文件修改时间、in_footer、页面模板或 post type 条件、是否需要 defer、async 或模块化加载。新增、删除或重命名 CSS、JS、PHP 模板时，必须同步检查 functions.php、条件加载逻辑和模板引用。删除文件前先搜索引用，避免线上出现 404 或 PHP fatal error。

修改 slug 不只是改一个 URL，必须同步检查：WordPress 当前 slug 和 canonical、页面或模板的条件判断、functions.php 中的 enqueue 条件、schema 中的 URL 和 @id、内部链接和 sitemap、301 redirect、AIOSEO title 和 description。修改前保存旧 URL，发布后验证旧 URL 301 到新 URL，而不是直接 404。

WordPress 后台的模板可能指不同概念：页面模板文件、Elementor Theme Builder 模板、WooCommerce 单产品模板、主题层级中的 single.php 和 single-product.php。不能简单地认为上传一个 PHP 文件并 enqueue 后，后台就可以选择它。如果需要后台切换模板，应使用正确的 WordPress 页面模板 header、Elementor Theme Builder 条件、WooCommerce hooks 或主题过滤器。按产品分类或文章分类加载模板时，使用稳定的条件函数，并验证优先级、缓存和回退模板。

阶段六：SEO、AIOSEO 与结构化数据

安装 AIOSEO 后激活 Pro 许可，设置站点基础信息、Organization、WebSite、Breadcrumb 和 sitemap，确认 title、description、canonical、robots 和 Open Graph 输出，检查是否与 Elementor、WooCommerce、缓存或其他 SEO 插件重复输出。

WordPress REST API 默认不一定提供 AIOSEO schema 的完整写入接口。批量更新时使用受控方式：AIOSEO 官方可用 API、受保护的临时插件或 mu-plugin bridge、WP-CLI 或服务器端一次性脚本。必要时才直接读写 AIOSEO 数据表，并先确认插件版本、字段结构和备份。临时接口必须限制权限、限制来源、执行后删除或禁用，不要把数据库写入逻辑直接暴露为公开 REST endpoint。

自定义 schema 不应盲目替换所有 AIOSEO 输出，先判断页面类型：

• Home：Organization、WebSite、WebPage。
• 产品分类：CollectionPage、ItemList、BreadcrumbList。
• 单产品：Product、Offer、AggregateRating（只有真实数据时才使用）。
• 文章：Article 或 TechArticle、BreadcrumbList。
• FAQ：只有页面真实展示 FAQ 内容时才使用 FAQPage。

如果自定义 graph 已经承担 WebPage 的职责，可以关闭重复的默认 WebPage graph，但保留仍然需要的 Organization、WebSite、Breadcrumb 或其他合法 graph。禁止为了有 schema 而制造重复、虚假或页面不可见的信息。

发布后用 Google Rich Results Test 和 Schema Markup Validator 检查：JSON-LD 是合法 JSON、URL 使用正确域名、@id 和 canonical 与页面 URL 一致、schema 内容与页面可见内容一致、没有重复或互相冲突的 graph。

阶段七：上传 staging 并验收

把本地 cleaned HTML 上传到 WordPress 时，先确认目标对象类型：普通 WordPress 页面、Elementor 页面、文章、WooCommerce 产品、分类 archive 或自定义 post type。普通页面可以写入 post_content 或 Custom HTML block。Elementor 页面依赖 _elementor_data 和 _elementor_edit_mode 等 post meta，不能用普通 HTML REST 更新方式覆盖。对于现有 Elementor 页面，除非明确要求迁移 Elementor 数据，否则保留其内容。

页面需要 Elementor Full Width 时，通过页面模板字段或 WordPress API 设置正确的 template value，并在线上确认实际渲染结果，不能只依赖页面编辑器里显示的选项名称。如果网站没有安装 Elementor，或者子主题已经自定义了 page.php 或 front-page.php，可以直接使用 Default Template。只要该模板没有调用父主题带最大宽度和 padding 的内容容器，Default Template 一样可以实现全宽布局。

上传主题文件不要直接无备份地删除线上整个主题目录。推荐的做法：备份线上子主题、比较本地和线上文件清单与 hash、只上传本次变更文件、排除 .env 私钥和临时文件、运行 PHP lint、检查文件权限、清除主题插件对象缓存和 CDN 缓存。只有在本地目录确实代表完整可发布的子主题，并且已有备份和回滚方案时，才进行目录级同步。

staging 验收至少测试：首页、导航、Footer 和主要页面；产品分类、单产品、文章归档和单文章；表单提交、邮件到达、reCAPTCHA 和成功错误状态；桌面、平板、手机和常见浏览器；页面速度、图片尺寸、缓存和控制台错误；404、301、canonical、sitemap 和 robots；AIOSEO meta 和 schema；WooCommerce 价格、库存、购物车或询盘流程（如果适用）。

阶段八：发布 production

发布前清单：staging 已完成验收；production 数据库和文件已备份；已明确本次发布对象；已检查 slug、旧 URL、301 和 canonical；已确认没有把 staging URL、测试邮箱或测试 schema 带入 production；已确认秘密信息没有进入发布包；已准备回滚步骤。

推荐的发布顺序：发布主题代码和静态资源；发布必要的插件、mu-plugin 或配置；更新页面、文章、产品和分类；更新 SEO、schema 和内部链接；清除缓存和 CDN；进行生产 smoke test。如果生产站已有用户、订单、询盘或新内容，不能用 staging 数据库整体覆盖生产数据库，应使用经过审查的增量迁移或 API 同步。

生产 smoke test 立即检查：首页和 5 至 10 个关键 URL 返回 200；无 PHP fatal error、白屏或 502/504；CSS、JS、字体和图片没有 404；表单和邮件正常；关键页面 title、description、canonical 和 schema 正确；sitemap、robots 和 Search Console 状态正常；移动端首屏和主要 CTA 没有错位。上线后观察错误日志、服务器资源、缓存命中、表单邮件和搜索引擎抓取情况。上线前别忘了把安全配置一起做完，之前写过一篇在 Cloudflare 配置安全响应头的教程，正好接上。

把流程沉淀成项目级 skill

当某个流程已经稳定重复使用，再把它提炼为项目级 skill。不要在第一次成功后立即把不稳定流程固化。适合提炼的包括：页面预览 HTML 生成、WordPress cleaned HTML 转换、AIOSEO meta 和 schema 批量更新、资源中心文章导入和内部链接挂载、共享 CSS 维护、单产品或单文章模板发布、线上快照差异审计和回滚。

每个 skill 包含 SKILL.md、scripts、references、templates 和 examples。SKILL.md 写清楚触发条件、输入文件、前置检查、执行步骤、禁止事项、验证方式、回滚方式和输出文件。脚本支持 dry-run、日志、错误退出码和幂等执行。

项目专属 skill 放在项目目录，跨项目通用的才安装到 Agent 全局。涉及公司品牌、服务器、域名或内部凭据的内容不要做成无隔离的通用模板。

长期运维周期

最终交付标准

一个页面或一组页面只有同时满足以下条件，才算完成：

• 本地预览通过。
• 内容、图片、链接和表单通过检查。
• CSS、JS 和 PHP 归属清晰且条件加载正确。
• SEO meta、canonical 和 schema 已验证。
• staging 页面通过响应式和功能验收。
• production 发布前已备份。
• production URL、资源、表单和日志检查通过。
• 变更记录、快照和回滚信息已保存。
• 可重复的部分已沉淀到项目级 skill 或脚本。

完整流程回顾

八个阶段串起来就是一套完整的搭建流程，从 staging 环境一直走到生产上线。之后每个新页面、新产品、新文章都能复用同一套资产和规则，配合项目级 skill 的沉淀，Agent 会越来越懂你的网站，维护成本会持续下降。