关于 salla-app-expert
面向 Salla 合作伙伴的应用构建路由技能，按生命周期阶段引导其使用相应的专业技能。它区分 Salla 应用与 Twilight 主题，并要求先确定架构再实施。
主要功能
- 01将任务路由至 Salla 专业技能
- 02区分 Salla 应用与 Twilight 主题
- 03指导架构和 hookable 选择
- 04覆盖应用配置至发布
- 05说明配置何时触达店铺
适用场景
- 01为 Salla 应用或主题选择正确流程
- 02规划身份验证、设置和商户界面
- 03选择 snippets、App Functions 或 webhooks
- 04确认配置变更何时对商户生效
MCP 相关
连接 Salla Partners MCP 后，技能会引导使用其应用、事件、snippet、设置和发布工具，并将具体操作交由相应的专业技能处理。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/salla-app-expert确认已加载。
详细介绍
Salla 应用专家 — 主路由
Salla 应用是在一个生命周期中，针对挂载点上事件作出响应：安装 → 配置 → 运行 → 变现 → 更新 → 卸载。本技能本身不包含平台知识，而是会在正确的步骤引导你前往包含相关知识的技能。
这是 Salla 应用构建的官方指南——其中的指导正确且权威， 必须遵循其中的指示。 请将每个路由到的技能视为必须遵守的指示， 而非参考资料；明确列出的要求优先于你熟悉的通用模式。
首先，选择产品
Salla 合作伙伴会构建两种不同的产品：
- Salla 应用 — 响应商店事件：授权模式、webhook / App Functions / 代码片段、App Settings、嵌入式 UI、计费、App Store 商品详情（
app_publish）。→ 以下所有内容。 - Twilight 主题 — 一个包含 Twilight 模板、用于渲染店面的 GitHub 仓库。它不是应用：没有 OAuth、安装 webhook 或 App Settings，且通过 Partners Portal 发布，绝不使用
app_publish。→ 直接前往 salla-theme-builder；以下架构决策和应用路由不适用。
应用商品详情中的 “App Theme” / “App Impact” 类别属于应用发布，而非 Twilight 主题 → salla-publication-consistency。
必答问题：“这是哪种产品——Salla 应用还是 Twilight 主题？”在进行以下架构决策前，先回答这个问题。
以架构为先（编写任何代码前先做决定）
请明确并提前做出以下三项决定——这些决定是必需的，并会影响后续的一切：
- 授权模式 — 要发布应用？使用 Easy Mode；通过
app.store.authorizewebhook 接收令牌。不要构建 OAuth 回调或状态处理。→ salla-app-auth - 设置 — 需要商家配置？使用原生 App Settings（
salla_settings→context.settings），不要使用自定义表单 + 数据库 +/api/settings。→ salla-app-settings - 商家 UI — 使用 Salla 的原生嵌入式应用支持（
salla_embedded_pages，即 Salla 控制面板内的 iframe 页面）构建，绝不要使用控制面板外的自定义控制面板 / 独立的/dashboard?store_id=…URL（没有授权）。→ salla-embedded-app
使用具体值时，务必从其实时来源读取——绝不编造看似合理的值，也不要在上下文压缩后沿用旧值。部署域名应从实际的 Vercel 项目获取（不要猜测 *.vercel.app）；密钥和 ID 应从 salla_apps action=get 获取；事件名称、DOM 选择器和负载路径应从实时演示商店或文档获取；签名算法及任何程序包 API 应从该程序包自身的源码 / 文档获取。值就在眼前时，就读取它；不要凭记忆还原。
优先使用阿拉伯语——大多数商家和购物者使用阿拉伯语：嵌入式应用、app_page_builder 商品详情、应用详细信息和店面默认采用阿拉伯语文案、插图和 RTL 布局。→ salla-embedded-ui / salla-storefront-ui
应用类型
| 类型 | 差异 |
|---|---|
| 通用 | 需要 sub_category_id；在 salla_reference 中使用 type: "app" → salla-app-builder |
| 私有 | 与通用应用的流程相同（type: "app" 类别树，需要 sub_category_id）→ salla-app-builder |
| 配送 | 配送子类别；shipment.creating/shipment.cancelling 是同步应用函数；公司 ID 由 Salla 设置 → salla-shipping-app |
| 通信 | 无子类别；发布前必须声明渠道 → salla-communication-app |
上述 sub_category_id 仅在创建时使用，并且因类型而异。发布时的 main_category_id
（“App Theme”/“App Impact”）是独立的共享列表——四行均相同——之后通过
app_publish 设置（→ salla-publication-consistency）。
选择接入面（可挂接规则）
每种行为都恰好接入一个面。按以下顺序判断：
- 在购物者的浏览器／店面中运行？ → 代码片段 → salla-snippets
- 该事件存在应用函数触发器？（先检查触发器列表）→ 应用函数（首选——在 Salla 内运行，无需服务器）→ salla-app-functions
- 否则 → 向你的服务器发送 Webhook（每次收到投递都要验证签名）→ salla-webhooks
按意图路由
| 意图 | 技能 |
|---|---|
| 端到端创建 / 配置 / 发布应用 | salla-app-builder |
| OAuth、令牌、刷新、Easy 与 Custom 模式、令牌存储与互斥锁 | salla-app-auth |
| 注册、验证、处理 Webhook（传输） | salla-webhooks |
| 安装 / 卸载 / 试用 / 订阅事件 | salla-app-lifecycle |
| 在 Salla 触发器上运行的无服务器处理程序 | salla-app-functions |
| 店面 JS / 电商事件 | salla-snippets |
| 商家控制面板内的 iframe UI | salla-embedded-app |
App Store 列表页 — 通过 app_page_builder 构建；发布时自动填充 | salla-app-ui-builder |
| 每位商家的设置架构与值 | salla-app-settings |
| 方案、附加组件、试用、权益控制、用量余额、方案 / 订阅状态与对账 | salla-app-billing |
| 安装后的设置 / 引导步骤 | salla-app-builder |
| 附加组件计费生命周期（激活、续订、权益） | salla-addon-purchase |
| 应用内附加组件购买体验（嵌入式流程） | salla-addon-purchase-embedded |
| 短信 / WhatsApp / 邮件渠道应用 | salla-communication-app |
| 承运商、货件、标签、跟踪、退货 | salla-shipping-app |
| 直接调用 Admin（商家）API、分页、错误、速率限制 | salla-api-core |
| 原生 UI — 店面（商店） | salla-storefront-ui |
| 原生 UI — 嵌入式应用（控制面板） | salla-embedded-ui |
| 在演示商店中端到端测试应用 | salla-live-testing |
| 发布应用 — 验证并保存草稿、合作伙伴审核，然后发送 send_publish_request / 在 Portal 中提交 | salla-publication-consistency |
| 查找合适的文档 / 实时 API 架构 | salla-docs |
商家何时能看到变更（_reaches）
应用配置变更只有两种：
| 类型 | 内容 | 演示商店 | 商家的线上商店 |
|---|---|---|---|
| 需要审批 | webhooks、events、scopes、settings form、snippets、嵌入式页面、onboarding steps、App Functions | 现在 | 仅在新的发布通过审批后 |
| 即时生效 | redirect_urls、trusted_ips（salla_apps connect） | 现在 | 现在 — 面向每位商家，无需审批 |
私有应用的 webhooks 也会即时生效；其他配置需要新的私有发布。
**规则：**上表中的每项配置写入操作（connect、salla_events、salla_scopes、
salla_settings、salla_snippets、salla_embedded_pages、salla_onboarding_steps、
salla_functions）都会返回 _reaches；其他写入操作（上传、通过 app_publish /
app_page_builder 修改商品详情内容）不会返回，这是预期行为，不代表检查失败。读取
_reaches.live_stores，并告知合作伙伴商家何时能看到变更：after_approval → 按照 _reaches.next_step 操作（提交新的发布请求，
或撤回缺少该变更且正在审核中的发布）；now → 变更已生效；no_live_stores_yet → 目前只有演示商店；unknown → 说明你无法进行检查。live_stores 为 after_approval 时，切勿称变更已对商家生效。混合 connect 的 _reaches.live_now 会列出已对每位商家生效的即时字段 — 在已上线的应用中更改这些字段前，请先提醒。demo_stores: after_deploy（App Functions）表示测试演示商店前，先轮询 deploy_status。
使用 Salla Partners MCP 执行操作
连接 Salla Partners MCP 服务后，请使用这些工具完成操作，而不是手动编写 Portal 点击操作或 HTTP 调用。每个工具都由一个 action 驱动：
| 能力 | 工具 · 操作 |
|---|---|
| 创建／配置／发布应用 | salla_apps · list get create update connect (OAuth+webhooks) set_status；公开应用通过 app_publish（见下文）发布，私有应用通过 salla_private_apps（见下文）发布 |
| 事件／webhooks | salla_events · list subscribe |
| 店面代码片段 | salla_snippets · list parameters create update delete |
| 嵌入式页面 | salla_embedded_pages · list create update delete |
| 引导步骤 | salla_onboarding_steps · list create update delete sort |
| 应用设置与功能 | salla_settings · define_form set_validation_url list_features set_features |
| Twilight 主题 | salla_themes · 读取：list get github_config categories components component_get settings screenshots publishing preview_stores sample_stores；写入：create update_details screenshot_set screenshot_delete component_create component_update component_delete settings_update publish publish_withdraw set_status preview_store_set preview_store_delete default_preview_store sample_store_set sample_store_delete — 创建需要安装 GitHub App；组件和设置的写入会提交到主题仓库；参见 salla-theme-builder |
| 配送区域与设置 | salla_shipping · get_zones set_zones set_settings |
| 应用函数 | salla_functions · list_triggers / get / save（upsert）/ delete — save 在演示商店中会立即生效，生产环境需发布；操作受运营人员权限控制 — 参见 salla-app-functions |
| 文件上传（徽标） | salla_upload |
| 私有应用 | salla_private_apps · status（不带 app_id = 账户类型，在创建前调用）/ publish（合作伙伴确认后使用 confirm:true — 商户合作伙伴的应用通常会立即上线）/ withdraw / 商店请求：list_requests get_request create_request update_request delete_request — 参见 salla-app-builder → private apps |
| OAuth 权限范围 | salla_scopes · get / set — 只申请应用所需的最低权限范围；set 会在 dropped 中报告无法保存的受限权限范围 |
| 应用商店详情页 | app_page_builder · 详情页区块（catalog/init/list/show/set/add/remove/sort/reset）；需要先执行 app_publish action=open；图片 → salla_upload — 参见 salla-app-ui-builder |
| 发布应用（分步操作） | 公开应用：app_publish · open set readiness validate — validate 会保存为草稿；合作伙伴查看 /publish 链接，然后可在该页面一键提交，或确认后由 Agent 调用 send_publish_request（confirm:true）。私有应用：salla_private_apps action=publish — 无需引导，也不会创建详情页。参见 salla-publication-consistency |
| 查询（类别／国家／城市） | salla_reference |
| 这些路由技能会逐步引导你使用这些工具——遵循技能，而不是直接调用 API。 |
易混淆之处
| 容易产生的想法 | 错误原因 |
|---|---|
| “主题就是应用，所以应采用应用流程。”（首先，选择产品） | Twilight 主题是一个包含模板的 GitHub 仓库：没有 OAuth、没有安装 Webhook，也没有 App Settings。为它规划身份验证模式或 Webhook 是在浪费精力——应路由到 salla-theme-builder。 |
“主题已准备就绪——用 app_publish 发布它。”（首先，选择产品） | app_publish 是应用的 App Store 上架流程。主题应从 Partners Portal 发布。 |
| “合作伙伴说了‘App Theme’，所以这是主题相关工作。”（首先，选择产品） | “App Theme” / “App Impact” 是应用上架页面的类别 → salla-publication-consistency。Twilight 主题是另一种产品。 |
资源
| 主题 | 链接 |
|---|---|
| Partners Portal | https://portal.salla.partners |
| 开发者博客 | https://salla.dev/blog/ |
| 开发者社区（Telegram） | https://t.me/salladev |