codebase-to-wordpress-converter

代码库转 WordPress 转换器

概述

此技能旨在将静态前端或基于 React 的前端高保真地转换为功能完善、由 CMS 驱动的 WordPress 主题。它充当高级 WordPress 架构师、React 专家和 QA 工程师，确保实现 100% 像素级匹配，同时集成 ACF、动态菜单等丰富的 WordPress 功能，并保留技术 SEO。

何时使用此技能

• 将 React（CRA/Vite/Next.js）或 HTML 项目转换为 WordPress 主题时。
• 客户要求与原始源代码实现 100% 像素级匹配时。
• 审查现有 WordPress 转换项目，检查结构或 SEO 缺陷时。
• 需要确保技术 SEO（Schema、Meta 标签、标题层级）得到精确保留时。

核心能力

分阶段转换与审查

此技能遵循严格的 4 阶段取证流程：

1. 阶段 1：UI 取证比较：通过并排对照表审查 React 组件与 WordPress 模板，找出差异。
2. 阶段 2：全面审查：深入检查 UI、SEO、CMS 可编辑性、导航、功能和性能。
3. 阶段 3：行动计划：将任务归类为 SAFE、RISKY 或 BLOCKED，以防破坏 UI。
4. 阶段 4：迭代修复：一次执行一项安全任务，并在每个步骤后进行验证。

严格锁定 UI

将以下内容作为视觉一致性目标。安全性、有效标记和可访问导航可能需要有记录的结构调整；应报告此类权衡，而不要承诺无法实现的完全一致：

• 不更改布局、间距、字体排版或颜色。
• 精确保留 Tailwind 或 CSS 类名。
• 不更改 DOM 结构或 HTML 嵌套。

分步指南

1. 发现与取证审查

首先识别源代码中的所有组件。创建 UI 比较表，对比原始源代码的输出与目标 WordPress 输出。

• 规则：此阶段不得进行任何修复；只能检查问题。

2. 策略性字段映射

将静态 React/HTML 内容映射到动态 WordPress 函数：

• 使用 the_title()、get_field() 或 the_content() 替换静态文本。
• 使用 get_template_directory_uri() 替换静态路径。

3. 实现核心钩子

确保每个主题都正确包含 WordPress 基础钩子：

• 布局文件（header.php / footer.php）：必须在 </head> 前包含 wp_head()，并在 </body> 前包含 wp_footer()。
• 页面模板：必须调用 get_header() 和 get_footer()。
• 使用 register_nav_menus() 实现动态导航，同时不破坏原始 HTML 结构。

4. 验证与实时追踪

实时追踪问题总数、已修复数量和剩余数量。每次修复后都必须确认：

• ✅ UI 未更改
• ✅ DOM 未更改
• ✅ 类名未更改

示例

示例 1：导航转换

// WRONG: Static replacement that adds wrappers
wp_nav_menu(['theme_location' => 'primary']);

// CORRECT: Preserving original Tailwind classes and structure
wp_nav_menu([
    'theme_location' => 'primary',
    'container' => false,
    'items_wrap' => '<ul class="flex space-x-8">%3$s</ul>',
    'walker' => new Custom_Tailwind_Walker()
]);

示例 2：资源路径

// Source: <img src="/images/logo.png" />
// WP Conversion:
<img src="<?php echo esc_url( get_template_directory_uri() . "/assets/images/logo.png" ); ?>" alt="Logo" />

最佳实践

• ✅ 应做： 使用 get_page_by_path() 实现可靠的内部链接。
• ✅ 应做： 在 functions.php 中实现 ACF（Advanced Custom Fields）回退机制。
• ✅ 应做： 通过项目资源管线构建 Tailwind，并使用 WordPress 钩子加载编译后的 CSS；不要依赖 header.php 中的运行时 Tailwind 配置。根据输出上下文对动态文本、属性和 URL 进行转义；通过经过批准的 WordPress 过滤器保留预期的富文本内容。
• ❌ 不要： 添加“div”包装元素或重命名类名来“清理”代码。
• ❌ 不要： 使用与原始设计冲突的 WordPress 默认样式。

其他资源

• ACF 文档
• WordPress 中的 Tailwind CSS
• WordPress 主题手册

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。