Elementor MCP 实战指南:WordPress 站点构建最佳实践——单一模板 + 动态标签,告别 N 个重复页面
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 V3theme-post-title/theme-post-featured-image/theme-post-excerptwidgets 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 loopelementor/manage-site-partsaction: createto 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" 一节把前面各条准则串成一条端到端流程,针对"列表(循环)中每个条目链接到详情页"的需求:
- 列表侧:构建 loop,给条目包裹层(item wrapper)挂动态链接——链接值由动态标签解析,指向对应条目的 permalink;
- 详情侧:按第 4 节的模式只建一个 single 模板,条件为
include/singular/<cpt>+ 必要的排除项; - 结果: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 获取等价数据。