generating-weaverse-project-json

生成 Weaverse 项目 JSON

生成有效且可直接导入的 Weaverse 项目导出 JSON 文件。

概述

此技能会生成符合 Weaverse 导入规范的 JSON 文件。它可独立使用——你可以将其用于网站迁移、设计规范、文字描述，或任何其他能说明应包含哪些页面和分区的输入。

输出为单个 JSON 文件，符合 references/project-json-schema.md 中的架构，并附有 references/demo.json 中的真实示例。

输入

此技能接受以下任意一种输入：

• 分区映射，来自 cloning-websites-to-weaverse（网站迁移流程）
• 分区映射 + 令牌表，来自 figma-to-weaverse（Figma 设计流程）
• 设计规范，描述页面、分区和内容
• 文字描述，说明店面应呈现的样子
• 现有导出文件，用于修改或扩展

唯一的硬性要求：你需要知道要使用哪些分区类型。阅读 app/weaverse/components.ts，获取已注册的分区和区块列表。

交付内容

此技能会生成一个导入 JSON，用于建立项目结构，包括页面、分区和初始内容。该 JSON 会导入一次到 Weaverse Studio 编辑器中，以创建项目。

结构创建完成后，后续内容编辑（文案、图片、本地化、批量更新）应通过 weaverse-content-api 技能完成，而不是重新导入。两者之间要保持项目条目 ID 稳定，这样后续补丁才能指向相同的条目。

如果项目已存在（为在线商店添加页面通常属于这种情况），则无需导入：使用 POST /projects/:projectId/pages 创建页面，并在一次 PATCH 请求中发送 JSON 的条目（参见 weaverse-content-api 中的“填充新建或空白页面”）。将 JSON 文件保留在代码库中，作为已推送内容的记录；之后若修改了在线页面，则将变更同步回该文件。

生成步骤

1. 阅读参考资料——加载 references/project-json-schema.md 了解规范，并阅读 references/demo.json 查看完整的真实示例
2. 识别已注册类型——阅读 app/weaverse/components.ts，了解可用的分区和区块类型
3. 阅读分区源代码——对于计划使用的每种分区类型，阅读其在 app/sections/ 或 app/components/ 中的源代码，了解有效的架构字段、枚举值和默认值
4. 按照下方结构构建 JSON
5. 运行验证器——执行 python3 scripts/validate.py <output-file>（适用于 Python 3.8+）以发现结构错误
6. 修复验证器报告的问题，然后重新运行，直到检查通过

JSON 结构

顶层

{
  "version": "1.0.0",
  "exportedAt": "<ISO timestamp>",
  "project": { "name": "<name>", "config": {} },
  "pages": [],
  "pageAssignments": []
}

project.config

包含主题设置、区域设置和颜色。支持的键：

键	类型	用途
previewHost	string	开发服务器 URL，通常为 http://localhost:3456
theme	object	全店通用设计令牌（颜色、排版、布局）
defaultLocale	object	{ label, language, country, currency, pathPrefix }
recentColors	string[]	编辑器颜色选择器中的最近使用颜色

对于 theme，请参阅 references/demo.json → project.config.theme，了解所有有效键。键的类别：

• 颜色：colorPrimary、colorText、colorBackground、colorLine、colorTextSubtle、colorLineSubtle、colorTextInverse、colorForeground
• 排版：bodyBaseSize、bodyBaseLineHeight、bodyBaseSpacing、h1BaseSize、headingBaseLineHeight、headingBaseSpacing
• 布局：pageWidth、footerWidth、headerWidth、navHeightDesktop、navHeightTablet、navHeightMobile
• 页眉/页脚：headerBgColor、headerText、footerBgColor、footerText、topbarBgColor、topbarTextColor、topbarHeight
• 按钮：buttonPrimaryBg、buttonPrimaryColor、buttonSecondaryBg、buttonSecondaryColor、btnCornerRadius
• 产品卡片：pcardAlignment、pcardImageRatio、pcardBorderRadius、pcardShowVendor、pcardShowReviews、pcardShowSalePrice 等
• 徽章：newBadgeText、newBadgeColor、saleBadgeText、saleBadgeColor、soldOutBadgeText、soldOutBadgeColor、bestSellerBadgeText、bestSellerBadgeColor
• 社交媒体：socialFacebook、socialInstagram、socialLinkedIn、socialX
• 新闻简报：newsletterTitle、newsletterDescription、newsletterButtonText、newsletterPlaceholder、newsletterPopupEnabled 等

仅包含你了解且打算设置的主题键。不要不加区分地复制整个示例主题。

页面

每个页面都有 id、name、rootId 和一个扁平的 items 数组：

{
  "id": "b98mnnqmv3tmce7wmw3l7vw4",
  "name": "Homepage",
  "rootId": "019b917a-f48f-72d4-aee7-3b1eae6b7dca",
  "items": [
    { "id": "019b917a-f48f-72d4-aee7-3b1eae6b7dca", "type": "main", "data": {}, "children": [{ "id": "019b917a-f48f-72d4-aee7-3b1f5ca586c1" }] },
    { "id": "019b917a-f48f-72d4-aee7-3b1f5ca586c1", "type": "hero-image", "data": { "height": "small" }, "children": [{ "id": "019b917a-f48f-72d4-aee7-3b22cd55e21b" }] },
    { "id": "019b917a-f48f-72d4-aee7-3b22cd55e21b", "type": "heading", "data": { "content": "Welcome" }, "children": [] }
  ]
}

主要规则：

• 扁平的 items — 所有项目都位于 items 数组中，层级关系通过 children ID 引用表示
• 每个页面有一个根 main 项目 — 其 ID 必须与 rootId 匹配
• 每个项目都必须包含 children — 叶子项使用 []，父项使用 [{ "id": "<item-id>" }]
• 每个项目都必须包含 data — 无需设置非默认值时使用 {}
• type 必须是 app/weaverse/components.ts 中已注册的区段或区块类型

重要： Weaverse 导入器要求每个项目都必须包含 data 和 children。省略它们会导致导入静默失败（页面渲染为空）。即使内容为空，也始终包含 "data": {} 和 "children": []。

页面分配

将页面映射到路由：

{ "pageId": "b98mnnqmv3tmce7wmw3l7vw4", "type": "INDEX", "handle": "", "locale": "en-us" }

常见类型：INDEX、PRODUCT、COLLECTION、ALL_PRODUCTS、COLLECTION_LIST、PAGE、BLOG、ARTICLE、CUSTOM。

对于 CUSTOM 页面，将 handle 设为路由段（例如 "reseller"）。对于标准模板页面，handle 通常为空 ""。

模板页面占位项

不进行自定义的标准页面（产品、系列、博客、文章）应为空占位项：

{
  "id": "qa8xa47ou35atbo1ik4w7v6y",
  "name": "Default product",
  "rootId": "019b917a-f490-794d-95d0-82a578d7cdfc",
  "items": [{ "id": "019b917a-f490-794d-95d0-82a578d7cdfc", "type": "main", "data": {}, "children": [] }]
}

数据值规则

仅使用已验证的枚举值

在填写任何 select、toggle-group 或 position 的值之前，请先阅读区段源代码。常见错误：

错误	正确	字段
"custom"	"small"、"medium"、"large"、"full"	height
"stretch"	"full"、"fixed"	width
"right" / "left"	"start"、"end"	desktopMediaPosition
"white" / "black"	"light"、"dark"	arrowsColor

仅包含非默认值

如果某个字段与架构默认值相同，请省略。Weaverse 编辑器会在保存时移除默认值。包含这些值会造成冗余。

架构预设值并非默认值：某个区块的 presets 启用的值（例如 enableOverlay: true），仅会在商家于 Studio 中添加该区块时应用，不会在导入或 Content API 写入时应用。请与输入中的 defaultValue 比较，并明确写入你实际需要的任何预设值。

Shopify 实体引用

集合和产品使用对象格式，而非裸字符串：

// Collections
"collections": [{ "id": 456905851102, "handle": "covers" }]

// Products
"product": { "id": 123456789, "handle": "my-product" }

如果不知道真实的 Shopify ID，请省略该字段或使用 []。不要编造虚假的 ID。

图片字段

外部图片使用裸 URL 字符串。Shopify 托管的图片使用媒体对象：

// External
"backgroundImage": "https://example.com/image.jpg"

// Shopify media
"backgroundImage": {
  "id": "gid://shopify/MediaImage/12345",
  "url": "https://cdn.shopify.com/...",
  "width": 1920, "height": 1080, "altText": "Description"
}

对于任何即将上线的内容，请使用 Shopify 媒体。Figma MCP 资源 URL（figma.com/api/mcp/asset/...）会在约 7 天后过期，而且某些店面图片转换会阻止这些 URL；请先将文件上传到 Shopify（weaverse-content-api → upload），然后使用返回的对象。SVG 会作为通用文件上传，返回为纯 CDN URL 字符串。

ID 格式规则

页面 ID 和项目 ID 使用不同的格式：

实体	格式	示例
页面 id	CUID（25 个字母数字字符）	b98mnnqmv3tmce7wmw3l7vw4
项目 id（以及 rootId）	UUID v7（带连字符）	019b917a-f48f-72d4-aee7-3b1eae6b7dca

完整性规则：

• 导出中的每个页面 id 都必须唯一
• 导出中的每个项目 id 都必须唯一
• rootId 必须与根 main 项目的 id 完全一致
• 每个子项引用都必须指向同一页面中的现有项目
• 页面 ID 是 CUID——请使用 CUID 生成器，或生成 25 个字符的小写字母数字字符串
• 项目 ID 是 UUID——请使用 UUID v7 格式（按时间戳排序，带连字符）
• 当一个仓库中包含多个导出文件（每个页面一个）时，为每个页面分配独立的 ID 范围（例如，首页使用 019b9400-…，下一页使用 019b9500-…），以确保将页面推送到同一项目时项目 ID 不会冲突

验证

生成 JSON 后，请运行随附的验证器：

python3 scripts/validate.py <path-to-output.json>

验证器会检查：

• JSON 结构是否有效
• 是否存在必需的顶层字段
• 每个页面是否都有 id、name、rootId、items
• 每个 rootId 是否都能解析到 type: "main" 的项目
• 每个项目是否都有 data 和 children 字段（两者均为必需字段）
• 项目 ID 是否重复
• 所有子项引用是否都能解析到同一页面中的现有项目
• 所有 pageAssignment.pageId 值是否都能解析到现有页面

修复报告中的任何错误并重新运行，直到验证通过。不要交付验证失败的 JSON。

常见错误

错误	修复方法
项目缺少 data 或 children	每个项目都必须包含这两个字段——即使为空，也请使用 "data": {} 和 "children": []
在 children 中嵌套完整项目	仅使用 { "id": "..." } 引用
rootId 与任何项目都不匹配	确保根 main 项目的 ID 与 rootId 相同
使用未注册的区块类型	请先阅读 app/weaverse/components.ts
ID 重复	页面 ID = CUID，项目 ID = UUID——每个 ID 都必须唯一
在 data 中包含默认值	省略与架构默认值相同的字段
猜测枚举值	请阅读区块源代码，确认有效选项
不加区分地复制整个演示主题	仅包含你了解并打算使用的键
缺少 pageAssignments	每个页面都需要路由分配
虚假的 Shopify ID	省略未知 ID，让用户在编辑器中选择
在上线导出中保留 Figma 资源 URL	上传到 Shopify 并使用媒体对象——Figma 资源 URL 会过期
依赖预设值	导入/API 写入时不会应用预设值；请明确设置这些值