salla-app-ui-builder

Salla 应用商店详情页（app_page_builder）

详情页是应用的主页／落地页，商家可在应用商店中查看，并会在安装应用时看到。它由一组有序的区块组成（应用信息、功能、评价、品牌、常见问题、统计信息——由 init / catalog 动态展示），全部通过 app_page_builder MCP 工具编写——没有 REST 端点，也无需处理令牌。使用 app_page_builder 和 salla_upload 完成详情页相关工作。

编辑区块的元素值会将共享的详情页内容直接写入应用的草稿发布版本。此工具负责的字段：name、description、logo、screenshots、benefits（值的形状见 blocks-and-fields.md）。

short_description 属于其他部分——它位于发布版本的 basic_information 部分（50–200 个字符），通过 app_publish → salla-publication-consistency 写入。请在该处编写，而不是在这里。

前置条件：先打开草稿

应用公开且有草稿发布版本后，才能使用 app_page_builder。请先创建草稿：

app_publish action=open

发布／草稿生命周期（打开草稿、填写发布版本各部分、验证并保存草稿，然后由合作伙伴在 Portal 中提交）由 salla-publication-consistency 负责——请阅读该技能了解完整流程。草稿创建后，app_page_builder 会将共享的详情页内容写入草稿。

9 个操作

所有调用都使用 action=（以及 MCP 已持有的应用上下文）。写入前，请先通过读取操作（catalog、list、show）了解参数结构。

典型流程： app_publish action=open → app_page_builder action=init（初始化必需区块）→ action=list → action=show（逐个查看区块，以了解其元素键）→ action=set（写入值）→ 按需使用 action=add / remove / sort。

完整的操作契约（参数、返回值、错误）见 api-spec.md。

媒体（logo、screenshots）

图像元素（logo、screenshots）引用已上传媒体的 ID：

1. 使用 source_url 调用 salla_upload → 返回一个整数图像 id。
2. 将 [{ id, url }] 放入该元素的 set 值中。

调用 set 时，保留现有图像的方法是让已存储的 { id, url } 保持不变。

生成缺失的商品页图片（规范流程）

这是所有商品页／发布图片字段共用的流程，涵盖构建器、发布信息和嵌入式应用中的所有 App Store 图片字段：

图片字段	设置方式	是否必填	尺寸／限制
logo（图标）	app_page_builder 的 App Information	必填	1:1，≥ 250×250 px；JPG/JPEG/PNG
screenshots	app_page_builder 的 App Information	必填，≥ 3	每张 263×350 px；多张
优势图片	app_page_builder 的 App Features	必填，恰好 3 张	以 benefits.image 字段为准（通过 show 确认）
banner	app_publish 的功能部分	可选	图片文件（无强制尺寸）
embedded_image	app_publish 的功能部分	仅嵌入式应用适用	最小 710×260 px（建议 1420×520），最大 512 KB

上述尺寸和数量（logo 为 1:1 且 ≥250×250、≥3 张截图、恰好 3 张优势图片）会在保存时由 服务端强制校验——如果不符合要求，action=set 会返回 error.fields。请通过 app_page_builder action=show 确认构建器字段的实际要求，不要将这些数值视为构建器前端的保证。

banner 和 embedded_image 是发布信息字段，不是构建器字段——请通过 app_publish 的功能部分设置（salla-publication-consistency）；embedded_image 是嵌入式应用 横幅，仅适用于应用含 iframe 页面时（该字段也由 salla-embedded-app 负责， 后者还负责第二张 Salla 宣传图片）。创建应用时也会设置 logo （salla-app-builder 第 1 步）。

如果缺少其中任何图片，或者你正在准备首次发布，且你可以使用图片生成工具，请生成符合应用用途和品牌风格的图片，然后上传并设置：

1. 先确认该字段要求的尺寸／宽高比，可查看上表（构建器字段还可查看 action=catalog / action=show / blocks-and-fields.md）——以免上传被拒。
2. 生成符合该尺寸且与应用相匹配的图片。
3. 使用 salla_upload 上传图片 → 返回图片 id。
4. 通过对应字段的工具设置图片：构建器字段（logo、screenshots、优势图片）使用 app_page_builder；banner / embedded_image 使用 app_publish 的功能部分。

商品页图片必须是真实素材——先询问，只有提前说明时才使用占位图

完整的商品页需要真实图片：logo + ≥3 张截图（App Information）、 banner + embedded_image（App Features，具体要求见上表）。如果缺少图片，请按以下流程处理：

1. **请用户提供所有必需图片。**不要编造看起来像真实素材的图片，也不要默默跳过任何字段——应先核实，不要臆造。（如果有图片生成工具且用户希望使用生成的图片，请按上面的生成后上传流程操作。）
2. 如果用户跳过或拒绝，请使用明确标注的默认占位图继续操作，确保草稿仍能通过验证——然后明确告知合作伙伴，必须在一键提交前于 Portal 中替换占位图（提交步骤 → salla-publication-consistency）。绝不要把占位图当作最终图片呈现。

关卡：“每张商品页图片都是合作伙伴的真实素材，或者是已明确告知合作伙伴须在提交前替换的占位图？”

自动填充：默认模板

已发布的应用已有商品页：默认模板会根据发布数据渲染。app_page_builder 会写入同一份草稿，因此部分自定义会与默认模板混合显示。

模型

• 应用的列表 = action=list 返回的有序区块数组。
• 目录（action=catalog）是可供你 add 的所有区块类型。
• 区块包含 id、slug、order 和标志 is_required、editable、is_visible；可编辑的输入项是元素（键 → 值），通过 action=show 发现。
• app-information 是唯一固定置顶的区块——init 会创建它，remove 会拒绝移除它。其余必需／可选区块会由 init / catalog 动态显示；请在调用时确认当前区块集合。

请参阅 区块和字段，了解区块／元素模型以及如何发现类型和元素键；参阅 API 规范，了解操作约定；参阅 载荷，了解 set 的值格式。示例区块 ID 和元素键仅供说明——请通过 action=catalog / action=show 确认。

注意事项

• 在全新草稿上先运行 init——它会创建必需区块并返回当前页面。
• 在调用时通过 action=catalog（区块类型）和 action=show（元素键）确认 ID 和键；此技能中的示例 ID／键仅供说明。
• 应用信息是唯一固定置顶的区块——始终存在、保持第一位且无法移除。其余必需／可选区块会由 init / catalog 显示（slug 仅供说明——请在调用时确认）。应用套餐始终会在列表中显示为占位项（即使应用没有套餐）——但它不是可编辑的构建器区块；请通过发布流程的定价步骤 → salla-publication-consistency / salla-app-billing 填充。
• 联系详情位于发布内容的 contact_information 部分 → salla-publication-consistency。某些支持／联系渠道也可能以扁平的 support_* 元素显示在应用信息中——请通过 action=show 确认。
• 多语言元素同时包含阿拉伯语和英语（{ "ar": "…", "en": "…" }）。
• 集合元素的子项以集合 ID 为前缀作为键（features.title）。请参阅 payloads.md。
• image 和 richtext 值会作为公开的应用商店内容呈现——仅使用可信且经过净化的素材／HTML。

风险提示

看似可行的想法	错误原因
"没有提供 logo／截图——我来生成一张看起来真实的图片并提交。"	这会凭空捏造合作伙伴从未批准的素材。应先向用户索要真实图片（核实，不要捏造）。
"用户没提供图片，所以我放几个占位图继续操作。"	只有在明确标注占位图，并告知合作伙伴须在提交前于 Portal 中替换时，才可以使用占位图。
"我会悄悄跳过缺失的图片，让就绪状态检查通过。"	将占位图默默作为最终内容提交，就是失败。合作伙伴必须在一键提交前知道哪些图片只是临时代用。

交叉链接

• salla-publication-consistency — 草稿／发布生命周期（app_publish action=open、发布内容各部分、short_description、contact_information）。
• salla-app-builder — 端到端创建／配置／发布应用。
• salla-app-settings — 商家设置。
• salla-docs — 架构和文档查找。

Resources

Topic	Link
Partners Portal	https://portal.salla.partners
Developer blog	https://salla.dev/blog/
Developer community (Telegram)	https://t.me/salladev