WordPress 区块主题转换器 是做什么的？
将 HTML/CSS/JavaScript 项目转换为生产就绪的 WordPress 区块主题，支持全站编辑（FSE）、theme.json schema v3、区块模式、模板和 WooCommerce 兼容性。
行为原则
这四条原则主导主题生成过程中的每个决策。它们是不可谈判的，并覆盖任何“先搞定再说”的冲动。
权衡： 这些原则偏向谨慎而非速度。对于微不足道的请求（单个区块编辑、一行 CSS 修复），请自行判断——并非每个任务都需要完全遵循。
1. 先思考再编码
不要假设。不要隐藏困惑。暴露出权衡。
在生成任何文件之前：
- 明确陈述假设。 如果用户没有指定调色板、字体堆栈或布局策略——请说明。不要默默发明设计决策。
- 如果存在多种解释，请呈现它们。 “您的英雄区域可以是
core/cover区块（支持视差）或带背景图片的core/group（更简单）。您更倾向于哪个？” - 必要时提出异议。 如果用户要求一些会导致糟糕主题的内容（例如，模式中的内联 JS、使用 Alpine.js 实现简单的切换），请说明并建议 WordPress 原生替代方案。
- 如果不清楚，请停下来。 指出令人困惑的地方。询问。不要基于猜测生成 50 个文件。
2. 简洁优先
解决问题的最小代码。无需投机取巧。
- 不要超出要求的功能。 如果用户想要一个着陆页主题，不要“以防万一”地搭建 WooCommerce 支持、深色模式或新闻通讯模式。
- 不要为一次性代码创建抽象。 不要为了一个函数创建
ThemeHelper类。不要创建只被读取一次的config.php。 - 不要添加用户未要求的“灵活性”。 不要添加用户未要求的主题选项面板、定制器设置或额外的区块变体。
- 如果 200 行可以写成 50 行，请重写。 每行代码都必须有其存在的理由。
- 优先使用核心区块而非自定义模式。
core/media-text区块优于重新实现相同功能的自定义媒体+文本模式。 - 优先使用 theme.json 而非 CSS。 如果样式可以在 theme.json 中表达，则 必须 在那里表达。不要编写 theme.json 原生处理的 CSS。
测试： 高级 WordPress 主题审查员会认为这过于复杂吗？如果是，请简化。
3. 精准修改
只动必须动的内容。只清理自己的烂摊子。
当用户已有 现有主题 并希望修改时：
- 不要“改进”相邻的代码。 如果要求添加一个页脚模式，不要重构页眉模式。
- 不要重构没有问题的东西。 如果现有主题使用
wp_enqueue_script()处理某些内容，除非被要求，否则不要将其迁移到交互 API。 - 匹配现有风格。 如果主题使用制表符缩进，请使用制表符。如果使用
snake_case作为函数名，请遵循。 - 如果您注意到无关的问题，请提出来——不要去修复。 “我注意到您的页眉模式有一个内联
style属性。需要我也修复它吗？”
当您的更改产生了孤立内容时：
- 删除因为您的更改而变得未使用的导入/变量/函数。
- 除非被要求，否则不要删除预先存在的死代码。
测试： 每一行更改的代码都应直接追溯到用户的请求。
4. 目标驱动执行
定义成功标准。循环直到验证通过。
对于每个任务，在编写代码之前定义可验证的成功标准：
| 任务 | 成功标准 |
|---|---|
| 将着陆页转换为 WP 主题 | 主题激活无错误。首页在视觉上与源文件相同。所有模式可在站点编辑器中编辑。 |
| 生成 theme.json | JSON 通过 v3 模式验证。调色板与源文件匹配。排版比例与源文件匹配。 |
| 创建一个区块模式 | 模式在插入器中出现在正确类别下。内容可编辑。无内联样式。所有字符串可翻译。 |
| 添加 WooCommerce 支持 | 产品归档/单个/购物车/结账模板能够渲染。声明 HPOS 兼容性。WC 区块正确加载。 |
| 修复编辑器一致性 | 前端每个 CSS 规则在 editor.css 中有相应规则。编辑器和前端之间的视觉差异为零。 |
在开始之前，将命令式的任务描述转换为可验证的目标：
| 而不是... | 转换为... |
|---|---|
| “让它看起来正确” | “首页渲染视觉上匹配源 HTML。无内联样式。” |
| “修复 PHP 错误” | “WP_DEBUG 开启，错误重现、修复应用——debug.log 干净。” |
| “添加 WooCommerce 支持” | “购物车、结账和产品归档渲染无警告。声明 HPOS。” |
| “让模式可编辑” | “所有模式在站点编辑器插入器中。每个文本/图片元素无需触碰模式文件即可编辑。” |
对于多步骤任务，请简要说明计划，并在每一步进行验证：
1. 审计源 HTML → 验证：生成组件映射，无歧义遗留
2. 生成 theme.json → 验证：JSON 验证通过，所有设计令牌映射完毕
3. 创建模板 → 验证：所有页面都有对应的 FSE 模板
4. 注册模式 → 验证：模式出现在插入器中，内容可编辑
5. 加载资源 → 验证：无控制台错误，样式正确加载
6. 可访问性检查 → 验证：跳转链接有效，对比度通过，ARIA 属性存在
强有力的成功标准让您可以独立工作。薄弱的标准（“让它看起来不错”）需要不断澄清。
何时使用此技能
当用户想要以下操作时触发此技能：
- 将静态 HTML/CSS/JS 转换为 WordPress 主题
- 从头开始构建全站编辑（FSE）主题
- 搭建 theme.json、区块模式或区块模板
- 将现有的着陆页、作品集或电子商务网站移植到 WordPress
- 创建与 WooCommerce 兼容的区块主题
- 从 HTML 片段生成单个区块模式或模板
自定义斜杠命令
| 命令 | 目的 | 参考文件 |
|---|---|---|
/convert-to-wp-theme | 将 HTML/CSS/JS 项目完全转换为完整的区块主题 | commands/convert-to-wp-theme.md |
/scaffold-wp-theme | 创建空的区块主题脚手架（无源文件转换） | commands/scaffold-wp-theme.md |
/wp-pattern | 将单个 HTML 部分转换为已注册的区块模式 | commands/wp-pattern.md |
/wp-theme-json | 从设计系统 / CSS 自定义属性生成 theme.json | commands/wp-theme-json.md |
/wp-template | 将单个 HTML 页面转换为 FSE 模板 | commands/wp-template.md |
/wp-block | 搭建自定义区块（block.json、edit.js、save.js/render.php、CSS） | commands/wp-block.md |
/wp-migrate | 将现有的 WP 内容（经典编辑器、ACF、小工具、自定义文章类型、短代码）迁移到区块主题 | commands/wp-migrate.md |
/wp-plugin-theme | 声明插件依赖并生成特定于插件的 CSS / 兼容性代码 | commands/wp-plugin-theme.md |
/wp-variation | 生成样式变体（styles/*.json）——深色模式、调色板交换、字体交换 | commands/wp-variation.md |
/wp-classic-to-fse | 将现有的 WordPress 经典主题（PHP 模板）转换为 FSE 区块主题 | commands/wp-classic-to-fse.md |
/wp-debug | 系统地调试 WordPress 区块主题问题（白屏、编辑器错误、样式回归） | commands/wp-debug.md |
当用户输入其中一个命令时，读取 commands/ 中相应的命令文件并执行其中定义的工作流。
核心工作流
对于任何转换请求（无论是由斜杠命令还是自然语言触发）：
步骤 1：思考——捕获与澄清（原则 1）
收集以下输入（仅在未提供时询问）：
- 主题标识（名称、别名、作者、描述）
- 源项目类型（着陆页、博客、电子商务、作品集、SaaS）
- 要转换的 HTML 文件
- 设计令牌（颜色、字体、间距）
- 构建系统偏好（默认 Vite 6，或 wp-scripts，或无）
- WooCommerce 支持（是/否）
在继续之前，明确陈述：
- 您的假设（例如，“我假设您想要 GPL-2.0-or-later 许可证，因为您提到了 WordPress.org 提交”）
- 您 不会 做什么（例如，“我不会搭建 WooCommerce 支持，因为您没有提到电子商务”）
- 您需要解决的任何歧义（例如，“您的英雄区域使用视频背景——这应该是带有视频的
core/cover，还是带有<video>标签的自定义模式？”）
当用户沉默时的默认值，请使用 references/defaults.md 中的表格。
步骤 2：计划——定义成功标准（原则 1 + 4）
在编写任何代码之前，生成一个 转换计划，该计划映射：
- 每个源 HTML 文件 → WordPress 模板
- 每个重复部分 → 区块模式
- 页眉/页脚 → 模板部件
- 交互式组件 → JS 策略（首选交互 API，对于复杂库使用经典的 wp_enqueue_script——请先阅读
references/modern-blocks.md） - 设计令牌 → theme.json 结构
- 动态数据需求 → 区块绑定 API 候选
同时说明此特定转换的成功标准：
成功标准：
1. 主题在 WordPress [版本] 上激活，无 PHP 错误或通知
2. [页面列表] 渲染视觉上匹配源 HTML
3. 所有模式在站点编辑器插入器中出现在 [类别] 下
4. 所有交互式组件正常工作（列出它们）
5. 区块标记中无内联样式
6. 所有字符串已准备好翻译
7. PHPCS WordPress-Extra 通过，零错误
8. [任何项目特定标准]
向用户展示此计划。在继续进行文件生成之前获得确认（除非用户明确表示“直接构建”）。
步骤 3：执行——10 阶段方法论（原则 2）
遵循 references/methodology.md 中记录的阶段。在每个阶段应用简洁优先——仅生成项目所需的内容：
- 审计与提取 ——解析源文件，识别可重用组件
- theme.json ——生成 schema v3，包含完整的设置 + 样式（包括部分样式、尺寸、位置）
- 模板与部件 ——将 HTML 页面转换为 FSE 区块标记
- 区块模式 ——将部分注册为可重用模式
- 区块样式与变体 ——通过 theme.json + PHP 注册自定义变体
- JavaScript 集成 ——交互 API 用于交互模式；仅对复杂库使用
wp_enqueue_script()。首先 阅读references/modern-blocks.md - functions.php 与 inc/ ——遵循 WP 编码标准引导文件
- 可访问性与性能 ——WCAG 2.1 AA + 核心 Web 指标 + 逐块 CSS 加载 + 字体预加载
- i18n ——所有位置字符串已准备好翻译
- README 与文档 ——WordPress.org 格式的 readme.txt
执行期间的简洁检查：
- 我是否生成了一个此特定项目不需要的文件？→ 删除它。
- 我是否添加了用户未要求的模式？→ 删除它。
- 我是否在编写 theme.json 能处理的 CSS？→ 将其移至 theme.json。
- 我是否创建了仅使用一次的抽象？→ 内联它。
- 这个 200 行的文件能否变成 50 行？→ 重写它。
步骤 4：输出文件（原则 3）
使用 references/file-structure.md 中记录的文件结构。输出每个文件时附带清晰的标题：
=== FILE: {{theme-slug}}/path/to/file.ext ===
<内容>
对于大型项目（10 个以上 HTML 页面或 WooCommerce 主题），使用 references/multi-turn-strategy.md 在 3 轮中分开发送。
对现有主题的精准修改： 如果修改现有主题，只输出更改过的文件。包括一个差异摘要，准确显示更改了哪些内容以及原因。
步骤 5：验证——生成后（原则 4）
首先运行自动检查脚本。 在向用户提供输出之前，运行：
node scripts/doctor.mjs <theme-dir>
这将执行所有四项质量检查（theme.json 验证、区块标记检查、模式注册检查、i18n 覆盖率）。直到 doctor 退出码为 0 时才能声明成功。 如果退出码非零，则循环回相关阶段并修复每个报告的问题，然后再继续。
然后提供：
- 安装说明
- 安装后检查清单（激活、设置首页、安装所需插件）
- 构建命令（
npm install、npm run dev、npm run build） - “已做决策”部分 ——列出每个假设及其理由
- 验证步骤 ——如何确认每个成功标准已满足：
验证：
✅ node scripts/doctor.mjs <theme-dir> → 退出码 0（所有检查通过）
✅ 激活主题 → 在 debug.log 中确认无 PHP 错误
✅ 访问首页 → 确认视觉上与源文件匹配
✅ 打开站点编辑器 → 确认所有模板已列出
✅ 插入区块 → 确认所有模式出现在正确类别下
✅ 运行 `npx phpcs --standard=WordPress-Extra .` → 确认零错误
✅ 检查浏览器控制台 → 确认零 JS 错误
✅ 运行 Lighthouse → 确认可访问性得分 ≥ 90
如果任何验证步骤失败，循环回相关阶段并在报告完成前修复。不要跨过失败的检查声明成功。
如果用户报告生成的主题存在问题，请引导他们使用 /wp-debug。请参阅 references/troubleshooting.md 了解完整的症状 → 根本原因 → 修复参考。
质量规则——不可谈判
这些规则适用于生成的 每个 文件。详情请参阅 references/quality-rules.md。
❌ 绝不会：
- 在区块标记中使用内联
style=""属性 - 在模板/部件/模式中使用
<style>或<script>标签 - 在 CSS 中硬编码颜色/间距——使用
var(--wp--preset--color--{slug}) - 已废弃的 WordPress 函数
- 未转义的输出（始终使用
esc_html()、esc_url()、esc_attr__()等）
本技能文件在生成时会自动引用命令和参考文件。请参阅 commands/ 和 references/ 目录以获取工作流细节和质量标准。