theme-skill

概述

使用此技能通过仅限 JSON的更改来更新 Shopify 主题。支持的文件包括 templates/*.json、JSON 分区数据、config/settings_data.json、config/settings_schema.json，以及 JSON 文件中由 schema 定义的分区或区块设置。

将现有 Liquid schema 视为只读参考。不要编写、创建或修改自定义 Liquid，也不要在 sections/、blocks/、snippets/、assets/ 或其他主题代码路径下添加新文件。

仅使用目标主题已提供的现有分区、区块、嵌套区块结构和设置。如果主题现有的 JSON 模板、分区类型、区块类型和 schema 设置无法实现所请求的设计，请说明差距，并提出最接近的仅限 JSON 的方案。

适用场景

当任务涉及以下内容时，请使用此技能：

• templates/ 下的 Shopify JSON 模板，例如 product.json、index.json，或 page.contact.json 等备用模板
• 在基于区块的主题中，引用 blocks/ 下现有主题区块的分区 JSON
• 可通过 config/settings_data.json、config/settings_schema.json、分区设置或区块设置安全表达的主题设计设置
• 在 config/settings_schema.json 中更新全局设置 schema（当所请求的控件属于 Shopify 的 JSON 设置 schema 时）
• 主题 JSON 设置和 schema 已提供的布局、内容、颜色、字体排版、间距、可见性或行为调整
• 将屏幕截图、设计模型或书面请求转换为目标主题所支持的最接近的仅限 JSON 的结构

不适用场景

以下情况请勿使用此技能：

• 结账品牌设置或结账 UI 扩展
• extensions/ 下的主题应用扩展代码
• 创建或编辑 Liquid .liquid 文件，包括新的分区、区块、代码片段、schema 或主题资源
• 替换主题尚未为相应路由采用 JSON 的 Liquid .liquid 模板
• 为了实现某种设计而创建新的分区类型、区块类型、代码片段、JavaScript、样式表、资源或 Liquid schema

如果主题使用构建步骤来生成 JSON 模板、设置数据或设置 schema，请阅读该主题的 README，并编辑作为单一事实来源的 JSON/设置文件。如果事实来源是 Liquid、JavaScript、CSS 或非 JSON 主题代码，请说明该任务不属于此技能的适用范围。

快速开始

1. 了解需求 — 解析提示词或图像，确定布局、列/行、内容类型和样式（如果输入是视觉内容，请参阅 设计图像和模型图）。
2. 仅使用 JSON — 将现有 Liquid 架构视为只读参考。仅编辑 Shopify JSON；如果请求涉及全局设计设置，也包括 config/settings_data.json 和 config/settings_schema.json。
3. 发现允许的区块类型 — 列出 blocks/ 并读取父级 {% schema %}，确保你使用的每个 type 在此主题中都存在（必需；见下文）。
4. （可选）查看随附示例 — 如果存在 examples/，请按照 examples/README.md 中的 选择最适合参考的示例 操作：将工作区主题与每个已索引的示例进行比较，并最多打开一个匹配度最高的文件。如果没有合适的示例，则改用工作区主题中现有的 templates/*.json 来复制模式。在目标主题的允许集合中出现之前，绝不要输出随附示例中的 type 字符串。
5. 映射到实际区块 — 仅从允许集合中选择类型；对于模板级 JSON，从现有的 sections/*.liquid 中确定区段 type。
6. 分析架构 — 读取每个现有区块或区段的 {% schema %}，了解允许的子项、设置 ID、类型、默认值和预设。
7. 执行全局设置检查 — 对于新页面、首页、落地页或截图/模型图转换，在编写模板之前读取 config/settings_schema.json 和 config/settings_data.json。除非用户明确要求仅修改模板，否则在需要时更新启用的全局排版、颜色、配色方案、圆角、边框和按钮默认值，以匹配设计。
8. 建立设置清单 — 编写 JSON 之前，记录计划输出的每项全局、区段和区块设置的架构约束。
9. 应用主题设计设置 — 将颜色、排版、间距、边框和行为映射到目标主题声明的实际全局/区段/区块设置。
10. 编译 JSON — 按照 Shopify 的模板结构，构建有效的 sections、嵌套 blocks 以及 order / block_order 数组。
11. 通过严格上传验证 — 编辑 JSON 模板时跳过 Theme Check；完成前使用 Shopify 的严格上传验证器。

工作流

步骤 1 — 了解用户需求

来自文本：

• 布局：网格、弹性布局、滑块、行内布局等
• 列数／行数
• 内容：图片、按钮、文本、产品卡片等
• 样式：间距、颜色、响应式行为

来自图片：

• 视觉布局、列和行、元素及其关系、间距和对齐方式
• 视觉层级（标题与正文、CTA）、大致对齐方式（左对齐／居中／右对齐）和内容类别（主视觉区、卡片、徽标、页脚等）
• 不明确之处 — 静态图片无法可靠地呈现确切的断点、字号和像素间距；请指出这些信息无法确定，而不要猜测。

设计图片和模型图

当用户提供截图、Figma 导出文件或设计模型图时：

• 提取： 结构（区块、列、堆叠顺序）、内容类型和定性间距节奏（紧凑或宽松），不要提取确切像素值，除非用户另行提供。
• 默认进行全局设置： 对于完整页面模型图或品牌专属页面，假设 config/settings_data.json 可能需要先更新字体、调色板、配色方案、渐变、按钮样式、圆角、边框和全局间距默认值。只有在用户明确要求仅处理模板，或现有全局设置已与模型图一致时，才跳过此步骤。
• 忽略源文件中的图片： 不要复制、裁剪、重建、下载、重复使用、生成或虚构截图、Figma 导出文件、模型图或其他源文件中的图片素材。仅将这些图片用于推断图片／媒体区块的位置。
• 使用空白图片区块或分区： 如果设计需要主视觉、产品、生活方式、徽标或装饰性图片，请添加有效的图片／媒体区块或分区，并将其图片设置留空或省略。假设用户或商家会在主题编辑器中提供最终图片。
• 仅关联明确指定的素材： 只有当用户提供现有主题素材文件名、Shopify 媒体 ID／引用、已选定的分区设置，或明确要求用作店面素材的文件时，才设置图片／媒体值。
• 不要仅凭图片推断具体的 Shopify type 字符串、设置键或枚举值。务必通过目标主题的 Discover allowed block types 进行核对。
• 限制： JSON 模板无法表达所有视觉细节。任意字体设置、一次性 CSS、新标记或新行为，可能需要在此技能之外开发 Liquid／主题代码。不要在此处实现这些代码；如果仅靠现有模式定义的 JSON 设置无法匹配设计，请说明这一点。
• 如果主题现有区块和设置无法实现该设计，请说明缺失之处，并提供最接近的可行结构。

步骤 2 — 发现允许的区块类型

在 JSON 中命名或输出任何 type 之前，先执行此步骤。这是满足“每个 type 都存在于主题中”这一验证规则的实际操作方法。

1. 列出 blocks/ 中的文件 — 对于使用主题区块的主题，blocks/<name>.liquid 的基本名称通常是有效的区块 type（请在架构中确认）。
2. 读取模板中你添加或编辑的每个 section，以及你嵌套的每个 block 文件中的 {% schema %}。收集每个父级允许的所有区块 type（根据该父级的 Shopify 规则，可能包括特定类型、@theme、@app 等）。
   • 验证每条直接父级/子级关系，而不只是确认某个区块是否存在于主题中的某处。如果布局区块只允许特定的项目包装区块，那么即使内容区块是主题中其他位置的有效主题区块，也不能将其设为直接子级。只有在允许的子级区块支持这些内容区块时，才能将它们嵌套在该子级区块下。
   • 将显式的 blocks 数组视为允许列表。只有 @theme 才允许通用主题区块；特定列表只允许其中列出的类型，以及任何列出的 @app。

   _ 前缀注意事项： 文件名以 _ 开头的区块（例如 _stat-bar.liquid），即使带有 presets，也可能不会被父级架构中的 @theme 匹配。Shopify theme check 会将带 _ 前缀的区块视为私有/静态区块，因此可能要求在父级的 blocks 数组中显式列出。在仅声明 @theme 的父级中嵌套 _ 前缀区块之前，请检查现有模板或 presets 是否有先例。如果没有，请勿编辑父级架构；改用其他现有的允许区块，或说明该请求需要在此仅限 JSON 的技能范围之外修改 Liquid/主题代码。

3. 构建允许集合 — 合并以下内容：父级架构允许的 blocks/ 中的类型、父级 blocks 数组中声明的类型，以及模板级 sections 对应的 sections/<type>.liquid 中的 section type 值。
4. 只使用该集合中的类型。 如果用户要求的布局没有任何现有区块支持，请提出最接近的真实类型、复制同一主题中可用的模板，或说明添加新区块或 section 属于主题开发工作，不在仅限 JSON 的编辑范围内。

步骤 3 — 检查随附示例（可选）

如果此技能包中存在 examples/，请遵循 examples/README.md 中的“选择最佳参考示例”：

• 将工作区主题与每个已索引示例进行比较（主题名称、README、blocks/ 基本名称与示例所述类型的重合情况）。
• 最多打开一个最匹配的文件，以参考模式和示例 JSON。
• 如果没有合适的示例，请改用工作区主题中现有 templates/*.json 的模式。
• 在目标主题的允许集合中出现之前，绝不要输出随附示例中的 type 字符串。

步骤 4 — 将需求映射到真实区块

在步骤 2 得出的允许类型集合中：

• 搜索主题的 blocks/ 目录和 section 架构，查找符合布局和内容需求的区块。
• 对于模板级 sections，列出 sections/，并将 JSON type 映射到 section 文件（通常是 sections/<type>.liquid 的基本名称）。

第 5 步 — 分析区块和分区架构

对于每个区块或分区，读取 {% schema %}：

1. 嵌套区块 — "blocks": [{ "type": "@theme" }]、特定类型与 "blocks": [] 之间的区别。为要输出的每个嵌套层级建立一个简要的父级到子级映射，并在编写 JSON 前，根据每个子级直接所属父级的架构进行检查。
2. 设置 — 必填项与可选项、默认值、类型。请特别注意：
   • range — 值必须严格符合 min + (N * step)，其中 N 为整数，即使设置被 visible_if 隐藏也一样。min: 10, max: 48, step: 2 的范围会拒绝 13（请使用 14）。min: 100, step: 5 的范围会拒绝 158（请使用 160 或 155）。复制或创建设置时，请先计算最接近的有效步进值，再写入 JSON。
   • select — 值必须与某个 options[].value 字符串完全匹配。即使某个值看起来是有效的 CSS，也不要自行编造；只有列出的选项才能通过验证。
   • visible_if — 即使设置被隐藏，上传时仍可能会对其进行验证。除非控制设置会使其生效，否则最好完全省略仅供自定义使用的隐藏设置。如果将隐藏设置保留为编辑器默认值，它们仍必须符合目标架构的 range 和 select 限制。
3. 预设 — 推荐配置。

编写 JSON 前，先建立架构设置清单

对于要输出的每种分区或区块类型，收集计划设置的每项设置的架构约束。在起草或修改 JSON 前完成这项工作，以免无效值进入模板。

• range — 记录 min、max 和 step；将每个值规范为 min + (N * step)。
• select — 记录精确的 options[].value 字符串，并且只使用这些值。
• 类型化设置 — 记录 checkbox、number、text、richtext、image_picker、url、collection、product、blog 和 page 预期的 JSON 值类型。
• visible_if 设置 — 不要跳过验证。Shopify 可能会在上传时验证隐藏设置，因此请省略仅供自定义使用的隐藏设置，或将其值也规范化。

不同主题常见的仅在上传时触发的范围限制问题各不相同。选定捆绑示例作为参考后，请查阅该参考，了解主题特定的设置类别和常见验证失败情况。无论使用哪种主题，所有输出的范围值都必须符合目标架构的 min、max 和 step。

为新页面和视觉稿执行全局设置检查

根据截图、Figma 导出文件、品牌参考或其他视觉稿创建页面或对页面进行大幅修改时，应将全局设置纳入常规的首轮检查。即使页面的各个部分都正确，如果当前主题的字体、颜色、圆角和按钮默认值仍沿用其他品牌的设置，页面看起来也可能不对。

编辑目标模板前：

1. 阅读 config/settings_schema.json，了解实际的全局设置 ID、设置类型、范围限制、选择选项和配色方案结构。
2. 阅读 config/settings_data.json，检查当前生效的 current 值和现有的 color_schemes。
3. 将视觉稿与当前的全局设计系统进行对比：
   • 字体排版：正文和标题字体、基础字号、缩放比例、标题行高、标题大小写、按钮字体排版。
   • 颜色：正文前景色和背景色、主／次／第三级按钮颜色、移动端栏、叠加层颜色、链接颜色。
   • 配色方案：分区背景、前景色、边框、悬停颜色和渐变。
   • 形状和边框：按钮圆角、输入框圆角、元素／卡片圆角、边框宽度。
   • 会影响整个页面的默认值：边距、间距、按钮尺寸／样式默认值以及任何特定于主题的设计令牌。
4. 如果视觉方向取决于这些全局值，请更新 config/settings_data.json。然后通过模板分区／区块的架构定义设置，将它们关联到相应的全局选项。

对于整页视觉设计，建议按以下顺序分工：

• 先设置全局项，确定整体品牌系统：字体排版比例、调色板、配色方案、渐变、按钮默认值、圆角和边框默认值。
• 再设置分区项，确定页面布局：背景配色方案分配、间距、边距、对齐方式和行为。
• 最后设置区块项，处理局部例外：特定标题字号、局部颜色覆盖、局部对齐方式或一次性可见性规则。

首轮设计时，避免为正文、标签、按钮和商品卡片文字使用区块级自定义字号。优先使用主题的默认字体排版令牌和全局字体排版设置。仅在有意设计展示型标题或用户要求精确艺术指导时，使用区块级自定义字号。

如果主题支持在 settings_data.json 中自定义配色方案，则对于具有独特调色板和渐变的视觉稿，优先创建或更新命名配色方案，然后使用架构支持的设置（如 color_type: "custom" 和 color_scheme_custom）为分区指定方案。不要凭空设计配色方案结构；应仿照当前主题数据中现有方案的结构。

步骤 6 — 应用主题设计控件

优先使用架构定义的设计设置，而非任意的 custom_css。先阅读相关架构，只输出目标主题中实际存在的设置键和值。仅当目标架构已将 custom_css 公开为 JSON 设置，且用户明确要求调整 CSS 时，才使用 custom_css；否则，应将 CSS 需求视为 JSON 范围之外的内容。

全局设计设置（config/settings_schema.json 和 config/settings_data.json）：

• 对于影响整个店面的广泛更改，例如全站颜色、排版系统、间距默认值、圆角和边框默认值，请使用全局设置。
• 使用 config/settings_schema.json 定义主题编辑器中显示的全局设置，并使用 config/settings_data.json 存储这些设置的当前值。
• 编辑全局值前，请先阅读这两个文件。保留现有 current 对象的结构，并确保架构与数据中的设置 ID、值类型、默认值和选项保持一致。
• 创建新页面、主页、着陆页或完整页面视觉样稿时，如果当前全局设置与所需的视觉方向不符，默认更新 config/settings_data.json。不要等用户再次提示才调整排版、调色板、配色方案、圆角、边框或按钮默认值。
• 如果页面样稿需要独特的区块背景或渐变，请优先在 config/settings_data.json 中使用命名的 color_schemes，并为区块分配相应方案，而不是重复覆盖局部颜色。
• 对于排版，优先使用全局字体设置和默认的富文本／按钮令牌。除非用户要求精确的局部艺术指导，否则避免为普通文本自定义区块字号；局部自定义字号仅用于特殊的主视觉／展示标题。
• 添加或更改全局架构设置时，请遵循周边的架构分组结构和 Shopify 设置类型。不要将架构更改当作添加自定义 Liquid、JavaScript、CSS、新区块或新内容块的后门。
• 不要创建任意的实用类值或令牌名称。请使用架构中列出的选项。如果主题现有设置数据结构支持创建新的配色方案 ID，请使用描述性 ID，并创建与现有方案匹配的完整设置对象。
• 如果所需设计确立或更改了店面的视觉系统，请使用全局更改。如果只是调整单个区块，且不应影响整个店面，则优先使用区块／内容块设置。

区块设置（sections/*.liquid）：

• 对于布局和样式的整体区段，请使用区块设置，例如间距、宽度、边距、颜色、边框、对齐方式、可见性、行为，以及区块架构支持的背景媒体。
• 选择项必须与架构选项完全一致。不要臆造像素字符串、CSS 实用类字符串、动画名称或类名。
• 如果区块提供 custom_css，且用户明确要求进行 CSS 级别的调整，则每个条目都必须是包含选择器的完整 CSS 规则，例如 .rte { text-transform: uppercase; }。不要使用独立声明或不带选择器的规则，也不要添加或编辑样式表文件。

内容块设置（blocks/*.liquid）：

• 对于区块内部的局部视觉调整，请使用内容块设置，例如间距、颜色、边框、形状、排版、布局、可见性、继承，以及内容块架构支持的动画。
• 当内容块应使用父级区块／容器样式时，请遵循继承设置。只有当目标内容块架构声明了相应设置，且设计确有需要时，才覆盖局部颜色、排版或边框。
• 不同内容块的排版、布局和动画设置各不相同。请根据目标内容块架构验证每个设置 ID、范围步长、选择项和类似枚举的字符串。
• 布局容器内容块通常对子内容有严格限制。请遵循每个父内容块架构中规定的允许子内容块，并且只从同一目标主题或经过验证且匹配的捆绑示例中复制嵌套模式。
• 除非目标内容块架构声明了相同的设置 ID 且接受相同的值，否则不要将某种内容块的设置复制到另一种内容块中。

第 7 步 — 编译 JSON 结构

遵循 Shopify 的 JSON 模板结构。如果主题包含 Cursor 规则（例如 .cursor/rules/templates.mdc、blocks.mdc、schemas.mdc），请遵循你正在编辑的项目中的规则。

模板结构：

{
  "sections": {
    "<sectionId>": {
      "type": "<sectionType>",
      "settings": {},
      "blocks": {
        "<blockId>": {
          "type": "<blockType>",
          "name": "t:blocks.block_name",
          "settings": {},
          "blocks": {},
          "block_order": []
        }
      },
      "block_order": ["<blockId>"]
    }
  },
  "order": ["<sectionId>"]
}

区块实例 ID：

• 使用能体现角色的描述性前缀（例如 layout、container、item、image、text），并遵循你在主题现有 JSON 中看到的命名惯例。
• 不要以 _ 开头命名区块实例 ID。私有区块类型可以以 _ 开头（例如 "type": "_grid-products"），但该区块的 JSON 对象键必须是有效的实例 ID，例如 "grid_products_best"。
• 如有需要，追加简短的唯一后缀。
• 确保模板中的 ID 唯一（并遵循架构规则，确保每个嵌套 blocks 作用域内的 ID 唯一）。

静态区块和 block_order：

• 静态区块（"static": true）在父级 blocks 对象中声明，但不得列入该父级的 block_order。
• block_order 仅用于动态／可重新排序的同级区块。如果父级只包含静态子区块，请使用 "block_order": []，或在现有模板模式允许省略时将其省略。
• 完成前，请逐一对照每组同级 block_order 和 blocks：列出的每个 ID 都必须存在，且不能指向 "static": true 的区块对象。

设置（基于区块的主题）：

• 布局区块通常会提供列数、行数、间距、内边距和响应式行为等设置。只能使用目标架构中声明的设置 ID 和取值。
• 如果主题为区块 name 使用翻译键，请优先采用，例如 "t:blocks.image"。
• 使颜色和间距设置符合主题的设计系统。

整体替换模板保护措施：

整体替换 JSON 模板后，剥除 Shopify 生成的文件注释头，解析文件并确认顶层 JSON 对象恰好只有一个。新模板的右花括号后不得残留追加的旧模板副本。

node -e "const fs=require('fs'); const s=fs.readFileSync('templates/index.json','utf8').replace(/^\/\*[\s\S]*?\*\/\s*/, ''); JSON.parse(s);"

富文本内容规则：

Shopify 会清理 richtext 和 text（rich）设置中的 HTML。只允许使用有限的一组标签和属性：

• 允许的标签： p、h1–h6、ul、ol、li、a、br、strong、em、span
• 不允许使用 style 属性 — <span style="color: red"> 会被移除。请使用架构定义的富文本或排版设置（如果可用）；否则应注明这一限制，不要添加内联样式、样式表规则、自定义 Liquid 或新资源。
• 富文本中的行内元素不得使用 class 属性。
• 如果设计要求在同一个文本区块中使用彩色文字，而现有 JSON 设置不支持，这属于主题代码自定义缺口。请注明这一点，不要添加内联样式、样式表规则、自定义 Liquid 或新资源。

第 8 步 — 验证

完成前，请运行以下验证清单。

对于 JSON 模板编辑，请跳过 shopify theme check，改用 Shopify 上传验证器进行验证：

shopify theme push --strict --only templates/<name>.json

对于首页，请使用：

shopify theme push --strict --only templates/index.json

这不是试运行；验证通过后会上传指定文件。仅当可以接受上传该模板时才使用此命令。

对于非交互式 Agent，请避免触发主题选择提示。如果 npm run dev 或 shopify theme dev 已在运行，请检查其输出中的 preview_theme_id=<theme_id>，并使用同一个开发主题进行验证：

shopify theme push --strict --only templates/<name>.json --theme <theme_id>

如果没有可用的主题 ID，且命令会提示选择主题，请先询问用户要使用哪个主题，然后再推送。

即使命令以 0 退出，也必须将 Theme upload complete 之后打印的任何 templates/<name>.json 错误视为权威结果。如果验证失败，请将控制台中的确切错误复制到验证清单中，并针对该类错误添加本地防护后再重试。

当 npm run dev 或 shopify theme dev 已在运行时，请使用其上传日志作为 JSON 模板编辑的实际验证循环：

1. 保存或触碰已编辑的模板，使开发服务器尝试同步该模板。
2. 检查开发终端，查找 Failed to upload file "templates/<name>.json" to remote theme。
3. 将该行下方的消息视为权威的 Shopify 验证结果。
4. 修复对应类别的错误；如果此类错误尚未列入此技能/检查清单，也将其添加进去。
5. 重复以上步骤，直到开发终端报告同步成功，或没有针对该模板的新上传错误。

如果已有开发服务器正在运行，请勿启动重复的开发服务器。优先查看现有终端输出。本地应防范的已知、仅在上传时出现的 JSON 模板错误包括：

• Invalid CSS value：自定义 CSS 数组条目必须是带选择器的完整 CSS 规则，不能只是独立声明。

• Setting '<id>' must be a step in the range：范围设置的值必须符合 min + (N * step)，包括被 visible_if 隐藏的设置。

• Setting '<id>' can't be less than <min> 或 can't be greater than <max>：范围设置的值必须在架构规定的边界内，包括隐藏的设置。

• '<id>' is not a valid block id：区块实例 ID 不能包含无效字符，也不能以下划线 _ 开头。

• static block with id '<id>' must not be present in 'block_order'：从同级 block_order 中移除静态区块 ID。

• JSON 格式有效。

• 去除 Shopify 生成的文件注释头后，整份模板替换内容必须恰好包含一个顶层 JSON 对象；右花括号后不得残留追加的重复模板内容。

• 区段和区块实例 ID 在各自作用域内必须唯一。

• 区块实例 ID 不能以下划线 _ 开头；只有区块 type 字符串可以使用私有 _ 前缀。

• 每个 block_order 都必须与其同级 blocks 对象中的键一致。

• 同级 block_order 中不得出现 "static": true 的区块。

• 顶层 order 必须列出所有要渲染的区段键。

• 每个 type 都必须存在于 sections/ 或 blocks/ 中，并且符合父级架构的允许范围。

• 嵌套区块类型必须对父级有效。

• 设置键及其值类型必须与 {% schema %} 一致。

• JSON 中每个范围设置的值（包括被 visible_if 隐藏的值）都必须符合有效步长（min + N*step）。

• 选择项的值必须与 options[].value 完全一致。

• 根据样稿创建或大幅修改页面时，必须检查 config/settings_data.json，并更新它；如果当前全局设置已符合设计，则应有意保持不变。

• 全局 settings_data.json 的变更必须根据 config/settings_schema.json 进行验证，包括现有或已变更的范围值、选择项值、值类型和完整的配色方案对象。

• 忽略源文件中的图片；除非明确提供了店面资源值，否则使用空白图片/媒体区块或区段。

• 富文本内容字符串中不得包含 style 或 class 属性。

• 每个父级中都必须明确列出嵌套的 _ 前缀区块，不能只列出 @theme。

错误处理

问题	处理方法
未找到区块/分区	搜索 blocks/ 和 sections/；建议相近的匹配项
嵌套无效	重新读取父级 {% schema %} blocks 数组
不允许使用 _ 区块	区块名称带有 _ 前缀；选择一个现有的允许使用的区块，或说明架构/Liquid 工作不在此 JSON 专用技能的范围内
style 属性被移除	Shopify 会清理富文本；如果有可用的架构定义文本设置，请使用；否则说明主题代码自定义方面的限制
范围步长违规	读取架构中的 step 值；将数值四舍五入到最接近的有效步长
隐藏范围违规	省略仅适用于隐藏自定义项的设置，或仍对其进行验证；隐藏设置仍可能导致上传验证失败
范围最小值/最大值违规	即使从其他模板或示例复制设置，也要将数值保持在目标架构的边界范围内
选择值无效	只能使用架构 options 数组中的值；不要自行编造 CSS 表达式
复制了模型图图片	移除从截图中提取的图片值；使用有效的空图片/媒体区块保留布局
架构过大	从同一主题中可正常使用的模板复制模式
请求含糊	询问要更改哪个模板文件，以及哪些分区/区块实例
生成的主题输出	仅当真实数据源路径为 JSON/设置数据时才编辑源文件；否则说明主题代码工作不在此技能的范围内

延伸阅读

文件	用途
reference/shopify.md	官方文档链接、文件名、平台限制
examples/README.md	如何选择捆绑的主题示例；文件索引

在主题仓库中，如果 .agent/rules/ 下存在 templates.mdc、blocks.mdc 和 schemas.mdc 等项目规则，也请遵循。

来源

此技能的内容源自以下 Shopify 文档页面。当 Shopify 更新这些页面时，请检查上方相应的分区（由 `` 注释标示）。

Shopify 文档	本文件中的分区
主题架构	何时使用此技能
JSON 模板	第 4 步 — 编译 JSON 结构、验证清单
分区	探索允许的区块类型、第 3 步 — 分析架构
分区架构	探索允许的区块类型、第 3 步 — 分析架构
区块	探索允许的区块类型
主题区块	探索允许的区块类型、第 3 步 — 分析架构