kscz0000 Codebase to WordPress Converter
概述
本技能专为将静态或 React 前端高保真转换为功能完整、CMS 驱动的 WordPress 主题而设计。它扮演资深 WordPress 架构师、React 专家和QA 工程师三重角色，确保 100% 像素级完美匹配，同时深度集成 ACF、动态菜单和技术 SEO 保留等 WordPress 核心功能。
使用场景
- 将 React（CRA/Vite/Next.js）或 HTML 项目转换为 WordPress 主题
- 客户要求与原始源码 100% 像素级完美匹配
- 审计现有 WordPress 转换的结构或 SEO 缺陷
- 确保技术 SEO（Schema、Meta 标签、标题层级）完整保留
核心能力
分阶段转换与审计
本技能遵循严格的 4 阶段取证流程：
- 阶段 1：取证 UI 对比：React 组件与 WordPress 模板的并排表格审计，发现差异
- 阶段 2：全面审计：深入检查 UI、SEO、CMS 可编辑性、导航、功能和性能
- 阶段 3：行动计划：任务分类为 安全、有风险 或 阻塞，防止破坏 UI
- 阶段 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：导航转换
// 错误：静态替换会添加包装器
wp_nav_menu(['theme_location' => 'primary']);
// 正确：保留原始 Tailwind 类和结构
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：资源路径处理
// 源码: <img src="/images/logo.png" />
// WP 转换:
<img src="<?php echo get_template_directory_uri(); ?>/assets/images/logo.png" alt="Logo" />
最佳实践
- ✅ 推荐： 使用
get_page_by_path()实现健壮的内部链接 - ✅ 推荐： 在
functions.php中实现 ACF（Advanced Custom Fields）回退机制 - ✅ 推荐： 将 Tailwind 配置保留在
header.php中，确保全局样式生效 - ❌ 禁止： 添加 div 包装器或重命名类名以"清理"代码
- ❌ 禁止： 使用 WordPress 默认样式（如果与原始设计冲突）
附加资源
局限性
- 仅在任务明确匹配上述范围时使用本技能
- 输出不能替代环境特定的验证、测试或专家审查
- 若缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清