Elementor MCP 实战指南:WordPress 站点构建最佳实践——单一模板 + 动态标签,告别 N 个重复页面

原创2026-09-16 14:42:342,325 阅读
文章标签:低代码前端CMSUI组件

Elementor MCP 实战指南:WordPress 站点构建最佳实践——单一模板 + 动态标签,告别 N 个重复页面

本文以 Elementor MCP 模块内置的静态资源 elementor://wordpress/best-practices 为核心,详解通过 MCP(AI Agent 工具协议)驱动 Elementor 构建 WordPress 站点时的四条关键决策准则:V4 组件 + 动态标签优先于 V3 post-* 组件、用"一个 single 模板 + 动态数据"替代"N 个复制页面"、条件范围的"全量包含 + 逐项排除"策略,以及 theme-post-content 正文槽位的唯一放置模式。读完你可以掌握 Agent 构建 Elementor 站点结构时的正确姿势,并能对照源码资源加载链与 PHPUnit 测试验证每条准则的落地方式。

1. 这份文档是什么:Elementor MCP 的静态资源

在 Elementor 代码库中,这份最佳实践并不是一篇游离的说明文档,而是 modules/mcp/static-resources/wordpress/best-practices.md 承载的一个 MCP Resource——AI Agent 在执行结构决策(页面、文章、主题模板)之前应当先"加载"的指导性上下文。它的定位在文档首段就写明:

Opinionated guidance for building WordPress sites with Elementor via MCP. Load before making structural decisions about pages, posts, and theme templates.

也就是说,这是一份"有主见的"(opinionated)指导:不罗列所有可能,而是直接给出 Elementor 官方推荐的构建模式。文档开头给出的加载时机很关键——在做出任何结构性决策之前先读它,而不是建完再纠正。

1.1 资源如何被注册与加载

该 Markdown 文件由 modules/mcp/abilities/wordpress-best-practices-ability.php 包装为一个 ability:

  • 资源 URI 常量:const URI = 'elementor://wordpress/best-practices';
  • 文件路径:const FILE_PATH = __DIR__ . '/../static-resources/wordpress/best-practices.md',即直接指向本文分析的这份文件;
  • 注册元数据(mcp 段):type: resource、public: true、mimeType: text/markdown,描述为 "Opinionated WordPress patterns for Elementor builds: repeating layouts (single template vs N pages), include-all + exclude-exceptions condition scoping, Post Content placement, dynamic tags.";
  • 权限门槛:fn() => current_user_can( 'edit_posts' )——调用方需具备 edit_posts 能力;
  • execute() 实现极简:文件不存在时返回 resource_not_found(HTTP 404 语义的 WP_Error),存在则 file_get_contents 原样返回 Markdown 文本。

从源码结构看,该资源属于 modules/mcp/module.php 统一注册体系的一部分:模块构造函数在 McpAdapter 类与 wp_register_ability 函数存在时,通过 wp_abilities_api_categories_init / wp_abilities_api_init 钩子注册 elementor 分类与全部 abilities,并由 Mcp_Proxy_REST_API 提供代理端点。资源清单在官方文档 docs/atomic-builder/mcp/resources.md 中也有登记:

Resource URI Ability ID mimeType 类
elementor://style/best-practices elementor/style-best-practices text/markdown Style_Best_Practices_Ability
elementor://wordpress/best-practices elementor/wordpress-best-practices text/markdown Wordpress_Best_Practices_Ability

注意它与 elementor://style/best-practices(设计/样式层面)是两份不同资源:style 管"怎么排版好看",wordpress 管"站点结构怎么搭才对"。Agent 的常规上下文里,build-composition 能力描述(modules/mcp/static-resources/abilities/build-composition.md)会显式提示"Read [elementor://wordpress/best-practices] for repeating-layout patterns (one single template driven by dynamic data — not N duplicated pages)",即在构建组合前先把本资源读入上下文。

1.2 测试锁定了哪些"措辞"

tests/phpunit/elementor/modules/mcp/test-wordpress-best-practices-ability.php 的注释说明了这份文档的特殊性——它测试的是面向 LLM 的措辞本身:

/**
 * Locks in the LLM-facing phrasing that steers widget selection away from V3
 * post-* widgets and keeps `theme-post-content` out of loop items.
 */

两条断言分别验证:文档内容包含 theme-post-title / theme-post-featured-image / theme-post-excerpt(即明确点名要避开的 V3 组件)以及 e-heading / e-image(推荐的 V4 组件);文档包含 single-template body slot 与 loop item(即正文组件只属于单一模板正文槽、不得进入 loop item)的禁令。这意味着文档中的关键短语是"契约"的一部分,修改措辞会触发测试失败——从工程角度保证了指向 Agent 的引导不会在重构中意外丢失。

2. 组件选型:V4 组件 + 动态标签,优先于 V3 post-* 组件

2.1 准则原文

文档第一节 "Widget selection: V4 + dynamic tag over V3 post-* widgets" 给出的规则:

Title, featured image, excerpt, price, meta, CTA link → V4 widget(e-heading、e-image、e-paragraph、e-button)+ a dynamic tag from [elementor://dynamic-tags]. Do NOT use the V3 theme-post-title / theme-post-featured-image / theme-post-excerpt widgets when a V4 + dynamic tag combination works — reserve them for cases where the V4 equivalent is not viable. This applies everywhere: singles, archives, loop items, and standalone pages.

翻译成执行清单:

要渲染的数据 推荐做法(V4) 避免的做法(V3)
文章标题 e-heading + 标题动态标签 theme-post-title
特色图 e-image + 特色图动态标签 theme-post-featured-image
摘要 e-paragraph + 摘要动态标签 theme-post-excerpt
价格、meta、CTA 链接 对应 V4 组件(如 e-button 的 link 字段)+ 动态标签 —

适用面是全场景:single 模板、archive 模板、loop item 内、独立页面。V3 post-* 组件不是被全面禁止,而是被降级为兜底——"reserve them for cases where the V4 equivalent is not viable"(仅当 V4 等价方案不可行时才用)。

2.2 动态标签从哪里来

<a href="https://link.gitcode.com/i/271d8495cddb14d1f12d55ebc111a135" target="_blank">elementor://dynamic-tags] 指向动态标签资源:其 PHP 侧能力为 elementor/list-dynamic-tags([modules/mcp/abilities/list-dynamic-tags-ability.php 中 const URI = 'elementor://dynamic-tags'),编辑器内则对应 elementor://dynamic-tags 资源(见 docs/atomic-builder/dynamic-tags/discovery.md 的三通道映射表)。标准工作流是:先调用 list-dynamic-tags 获取合法的标签 name、categories 与 settings schema,再把标签对象绑定到组件字段上。绑定形状在 modules/mcp/static-resources/abilities/build-composition.md 中有定义——当 schema 允许 dynamic 类型时,字段值写成 { "name": "<tag from elementor://dynamic-tags>", "settings": { ... } },且标签的 categories 必须与字段声明的 categories 有交集,否则该字段会报错并跳过合并。这解释了为何准则要求"从 elementor://dynamic-tags 取标签":标签名不是自由文本,而是受 schema 约束的枚举值。

3. 重复布局:一个 single 模板,而不是 N 个页面

3.1 准则原文

"Repeating layouts / detail pages" 一节识别了一种高频需求模式:用户描述的设计在多个文章/页面间重复出现,典型话术包括 "each project"、"the product detail page"、"make every blog post look like this"、"each item links to a page like this"。对此,文档给出的判定非常强硬:

that is ONE single / single-<cpt> template driven by dynamic data — NOT N duplicated pages. Never loop elementor/manage-site-parts action: create to make one page per item.

要点拆解:

  • 正确形态:一个 single / single-<cpt> 站点模板(Theme Builder 的"单篇/自定义类型"模板),内部用动态标签渲染每个条目的差异内容,同一模板服务所有条目;
  • 反模式:循环调用 elementor/manage-site-parts 的 action: create 为每个条目复制一个页面。manage-site-parts / list-site-parts 是 Theme Builder 站点部件的增查工具,build-composition 资源说明(modules/mcp/static-resources/abilities/build-composition.md)指出 header、footer、404、single、archive、search-results 这类内容位于独立文档而非当前页面,需先调用 elementor/list-site-parts 拿到正确的 post_id,且该能力依赖 Elementor Pro(未注册时跳过);
  • 禁止行为:以"给每个项目建一个详情页"的方式批量 create 页面。

3.2 条件范围:全量包含 + 排除例外

真实站点通常是"一种重复设计 + 少量一次性例外"(比如定制首页、独立落地页)。"Condition scoping — include-all + exclude exceptions" 一节给出的默认策略是宽范围包含 + 显式排除:

  • 某 CPT 的文章:include/singular/<cpt>,每个例外条目加一条 exclude/singular/<cpt>/<id>。内置文章用 post,自定义类型如 project 就用 project;
  • 页面:include/singular/page,每个有独立设计的页面(Home、About…)各加一条 exclude/singular/page/<id>;
  • 当无法判断哪些是例外时,先问用户,并在新建 single 模板之前先调用 elementor/list-site-parts 查重,避免重复模板;
  • 只有当用户明确就是为某一篇具体文章设计时,才退化为 include/singular/<cpt>/<id> 的精确单点包含。

这套策略的工程价值在于:默认覆盖面大,后续新文章自动套用模板,不用逐条维护白名单;例外是少数,排除条件数量可控。它同时约束了 Agent 的行为顺序——list-site-parts 查重前置、向用户确认例外项、最后才 create。

4. Post Content 槽位模式:正文只有一个固定位置

4.1 准则原文

"Post Content slot pattern" 规定:每个 single 模板有一个可选的编辑内容槽位——一个 theme-post-content 组件,包在全宽的 e-div-block 里,放在固定的 hero 区块与固定的底部区块之间。无正文的文章在该槽位不渲染任何东西;有正文的渲染在那里。文档给出的结构示例:

<e-div-block configuration-id="Post Hero">...</e-div-block>
<e-div-block configuration-id="Post Body">
  <theme-post-content configuration-id="Post Content"></theme-post-content>
</e-div-block>
<e-div-block configuration-id="Post Bottom">...</e-div-block>

并强调:theme-post-content 是组件名,在 xml_structure 中直接输出 <theme-post-content> 且不携带 element_config——组合写入路径(composition write path)会按原样接受。

4.2 三条硬性约束

  • 用 e-div-block 包裹,而不是 e-flexbox:flexbox 的 row 方向默认会把文章正文挤扁(squeeze);样式(如 max-width / padding)应加在这个包裹容器上。
  • 每个 single 模板有且只有一个 theme-post-content。
  • 它只能出现在 single 模板的正文槽位——绝不能放进 loop item、archive、header、footer 或可复用组件里;原因文档写得很直白:"the surrounding loop already repeats the article body"(外层 loop 本身就在重复文章正文,再嵌一个正文组件会重复渲染)。这一点也被 PHPUnit 测试 test_execute__forbids_theme_post_content_inside_loop_items 固定为文档契约。从源码结构看,theme-post-content 同样出现在 V3 桥接注册表(modules/mcp/abilities/appliers/v3/v3-widget-bridge-registry.php)等实现中,说明它是真实存在的 V3 组件,而非文档杜撰的名词。

4.3 其余数据全部走动态标签

标题、特色图、摘要、meta、价格、CTA 链接——除正文槽位外的所有内容,都通过普通组件 + 动态标签实现(e-heading 的 title、e-image 的 src、e-button 的 link),标签名以 [elementor://dynamic-tags] 为准。文档再次警告:不要为每篇文章硬编码值——同一个模板要能渲染出每一篇文章。

5. Loop → 详情页的完整链路

"Loop → detail flow" 一节把前面各条准则串成一条端到端流程,针对"列表(循环)中每个条目链接到详情页"的需求:

  1. 列表侧:构建 loop,给条目包裹层(item wrapper)挂动态链接——链接值由动态标签解析,指向对应条目的 permalink;
  2. 详情侧:按第 4 节的模式只建一个 single 模板,条件为 include/singular/<cpt> + 必要的排除项;
  3. 结果:permalink 全部来自动态标签,不存在 per-item 页面。

换言之,"详情页"在 Elementor 语境下不是数据库里的一篇篇页面,而是"一个模板 × 动态数据"的渲染结果;Agent 不需要、也绝不应该为每个条目生成页面实体。

6. 实践检查清单与可验证依据

结合原文档与仓库实现,构建前可对照以下清单:

  • [ ] 是否在做出页面/文章/模板结构决策之前加载了 elementor://wordpress/best-practices?
  • [ ] 标题/特色图/摘要/价格/meta/CTA 是否都走 V4 组件 + 动态标签,而非 V3 theme-post-* 组件?
  • [ ] 重复设计是否落地为一个 single / single-<cpt> 模板,而非循环 create 页面?
  • [ ] 模板条件是否采用 include/singular/<cpt> 全量包含,例外用 exclude/singular/<cpt>/<id> 逐条排除;不确定时先询问用户,并先 elementor/list-site-parts 查重?
  • [ ] 模板中是否恰好一个 theme-post-content,包在全宽 e-div-block 中(非 e-flexbox),且不出现于 loop item / archive / header / footer / 可复用组件?
  • [ ] 列表条目链接是否使用动态标签生成 permalink?

每条准则在仓库中都有可验证的落点:资源定义在 modules/mcp/abilities/wordpress-best-practices-ability.php,资源清单与读取方式见 docs/atomic-builder/mcp/resources.md,构建组合的 XML 结构与动态字段写法见 modules/mcp/static-resources/abilities/build-composition.md 及 docs/atomic-builder/mcp/composition-workflow.md,动态标签发现见 docs/atomic-builder/dynamic-tags/discovery.md,措辞契约由 tests/phpunit/elementor/modules/mcp/test-wordpress-best-practices-ability.php 锁定。需要说明的适用前提:站点部件(single/archive 模板)相关能力依赖 Elementor Pro;elementor://dynamic-tags 在编辑器内是 JS 侧资源,外部 Agent 通过 elementor/list-dynamic-tags ability 获取等价数据。

登录后查看全文
elementor