webflow/webflow-skills

Webflow Cloud Apps

使用 data_apps_tool 创建 GitHub 源码应用、回答操作性问题，以及管理 Webflow 云应用的环境。从用户的目标出发，仅收集必要的证据，并区分观察结果与结论。

当任务需要 CLI/本地源码应用创建或部署，或需要创建或更新环境变量时，请使用 webflow-cli:cloud 技能。客户端构建输出不会发送到 Webflow，也无法通过 MCP 恢复。

指令

1. 确定范围

使用用户请求或现有任务上下文建立的 Webflow MCP 连接。如果只有一个连接处于活动状态，直接使用它，无需要求用户选择或重新确认区域。如果有多个连接处于活动状态，且目标不明确，请在执行依赖于目标的操作之前要求用户明确。不要为了恢复缺失的资源或访问错误而切换区域。

在将现有的 MCP 应用或环境交给 CLI 进行配置写入或部署之前，比较它们配置的区域。如果区域不同，不要假设任何一个正确，也不要静默地重新定位任一工具。根据明确的任务上下文确定预期目标；如果无法解决冲突，请询问用户。在冲突解决之前，暂停所有依赖的变更操作。

一旦确定了预期区域，验证 CLI 能否读取确切的 MCP 应用和环境 ID，并在后续的变更操作中明确携带该区域和这些 ID。仅凭登录状态或区域标签是不够的。如果验证失败，报告失败，不要推断其原因，并暂停依赖的变更操作。继续执行目标已确定的独立工作。

1. 在任何其他 Webflow MCP 工具之前调用 webflow_guide_tool。实时指南和操作架构对当前参数和响应具有权威性。
2. 对于 Webflow 操作，使用 Webflow MCP 工具，除非明确将环境变量值的操作交给 CLI。绝不直接调用 Webflow API。
3. 在每次工具调用中包含必需的 context 参数。用第三人称写 15-25 个词。
4. 根据任务所需的能力进行路由：
   • 使用 data_apps_tool 创建 GitHub 源码应用；检查应用、环境、域名、部署记录、日志和变量元数据；管理 GitHub 源和环境；以及入队 GitHub 部署。
   • 使用 data_variable_tool 处理 Designer 颜色、尺寸、字体和 CSS 变量。
   • 使用 webflow-cli:cloud 处理 CLI/本地源码应用、本地构建和部署，或创建和更新环境变量值。
5. 如果 data_apps_tool 不可用，报告 Cloud Apps MCP 功能未启用。不要通过直接 API 请求绕过它。

永远不要要求用户将环境变量值或密钥粘贴到聊天中。对于创建或更新操作，委托给 webflow-cli:cloud，并要求使用隐藏提示、标准输入或受保护文件。永远不要将密钥作为位置参数传递。

2. 确定目标

按以下顺序发现标识符：

list_apps -> app_id
list_environments(app_id) -> env_id
list_deployments(app_id, env_id) -> deployment_id

应用名称仅在站点内唯一，因此使用 site_id + name 来解析指定名称的应用。如果多个资源匹配，请呈现区分元数据，并要求用户在执行任何变更操作之前选择一个。使用实时指南了解筛选、分页、游标和操作批处理机制。

3. 遵循匹配的用户故事

创建 GitHub 源码应用

1. 确定应用名称、规范的 GitHub 仓库 URL、分支、可选描述，以及它是独立的还是附加到现有站点。
2. 对于站点关联应用，解析站点 ID。对于独立应用，省略 site_id。
3. 在预览之前应用挂载合约：
   • 独立应用始终挂载在 /；省略 mount 或使用 /。
   • 站点关联应用默认为 /app，拒绝 /，并且在覆盖默认值时需要一个有效的非根挂载点。
4. 解释独立创建需要工作区范围的用户令牌。Webflow 会派生 GitHub 安装并验证仓库访问权限；无需请求安装 ID。
5. 以其默认的试运行方式调用 create_app。显示仓库、分支、附件、站点（如适用）、挂载点和初始部署尝试。
6. 要求 confirm。在确认后且执行前立即记录开始时间并生成一个稳定的 idempotency_key；以 dry_run: false 执行，然后记录完成时间。仅在对该创建的精确重试时复用该密钥。
7. 将创建和初始部署视为两个独立的结果。即使 deployStatus 为 skipped 或 failed，只要返回了应用，即表示创建成功。对于 triggered，检查环境和部署；对于 skipped，检查分支或推送提交；对于 failed，保留应用并单独检查或重试部署。
8. 如果应用或其结果无法读取，在重试前进行协调：
   • 对于站点关联应用，使用 site_id + name 收集候选；对于独立应用，按名称收集候选。
   • 在两种情况下，将每个候选的名称、sourceUrl 和 createdAt 与请求的仓库和记录的执行窗口进行比较。
   • 只有当恰好一个候选项匹配时，才继续检查环境和部署。在创建的应用仍然不明确时不要重试。
9. 切勿因部署失败而自动删除已创建的应用。不要将初始部署仪表盘链接视为环境的公网 URL。

我所查看的是哪个应用和环境？

1. 使用 list_apps 查找应用，使用 get_app 获取其元数据，包括 sourceUrl 和 siteAttached。
2. 使用 list_environments 报告分支、挂载点、publicUrl 和最新部署状态。如果 publicUrl 为 null，报告没有可用的面向用户的环境地址；不要构造一个。
3. 当用户询问应用在何处可访问时，使用 get_app_domains。
4. 解释自定义域名结果排除默认的 *.webflow.io 主机名。附加到常规 Webflow 站点的应用的域名可能属于父站点，并由兄弟应用共享。

部署了什么，健康状况如何？

1. 使用 list_environments 获取环境的最新部署状态。
2. 使用 list_deployments（最新优先），然后使用 get_deployment 获取所选部署的详细时间线和版本元数据。
3. 将 starting、building 和 deploying 视为活动状态。准确报告任何其他状态，不要猜测其含义。
4. 失败的阶段会设置 buildFailedAt 或 deployFailedAt，而其对应的完成时间戳仍为 null。单独的 null 完成时间戳并不能证明该阶段仍在运行。
5. 报告可观察到的情况：所选应用和环境、部署状态、返回的版本或提交元数据、阶段时间戳以及证据缺口。

为什么部署失败？

1. 使用 get_deployment 获取部署，并根据其状态和时间戳确定失败阶段。
2. 仅在 logsAvailable 为 true 时调用 get_build_logs。从较窄的 since 窗口或 q 过滤器开始，仅在需要时扩大范围。
3. 当需要完整结果时，一直翻页直到 nextCursor 为 null。
4. 将 logsAvailable 视为保留和检索信号，而不是证明每个阶段都产生了日志条目。
5. 将空结果视为“没有匹配的可检索服务端日志”，而不是证明构建成功或没有产生错误。
6. 用户在本地机器上产生的构建输出不在 MCP 范围内。仅在用户表示部署是使用 CLI 构建时才提及此点；将用户引导至原始的 CLI 输出以获取本地构建失败信息。
7. 报告失败阶段、相关时间戳、最小有用证据、推断的原因以及任何不确定性。不要仅仅复述原始日志。

为什么运行中的应用失败？

1. 确定确切的环境并调用 get_runtime_logs。
2. 在检索宽窗口之前使用 since 和 q 缩小范围。当结论依赖于不存在时，完全翻页。
3. 运行时日志可能因保留策略而不可用。将空结果视为没有可检索的日志，并报告此限制。
4. 在有用时将运行时证据与最新部署记录关联起来，但不要仅凭时间推断因果关系。
5. 报告观察到的错误模式、受影响的时间间隔、可能的原因、证据和限制。

所需的配置是否存在？

1. 从权威来源确定所需的密钥集：用户提供的密钥列表、项目配置架构或文档化要求，或用户明确指定为完整的参考环境。
2. 如果来源是包含值的受保护文件，则仅进行本地确定性密钥提取，并仅输出密钥名称。切勿通过模型可见的读取打开该来源，也不要将其值包含在聊天或工具输出中。
3. 针对每个必需密钥，从用户、项目架构或文档化要求，或明确指定为密钥机密性权威来源的参考环境中获取权威的机密性指定。.env 文件或纯密钥列表仅确定名称；切勿根据密钥名称推断机密性。
4. 解析环境，调用 list_variables，并将其密钥和机密性元数据与确定的要求进行比较。它证明的是已配置的内容，而不是所需的内容。在得出密钥缺失的结论之前，请耗尽所有分页。
5. 仅报告密钥和元数据。秘密条目有 isSecret: true 且没有值；缺少秘密值是预期的。
6. 如果所需集或任何机密性指定仍未确定，则在 CLI 变更操作或依赖的部署之前停止，除非用户明确确定不需要任何配置。
7. 对于缺失或分类错误的密钥，路由到 webflow-cli:cloud，不要在聊天中请求值。写入后，使用 list_variables 验证所需密钥和机密性。如果部分失败，报告失败的密钥（不含值）并在部署前停止；保留成功的密钥和环境。

为什么此环境服务于错误的分支或路由？

1. 解析确切的环境并报告其当前分支、挂载点、publicUrl 和最新部署状态。报告 null publicUrl 而不构造地址。
2. 将当前分支和挂载点与用户预期的映射进行比较。如果请求仅是诊断性的，则在报告不匹配后停止。
3. 如果更正会更改挂载点，则调用 get_app 并使用 siteAttached：仅当 siteAttached 为 false 时，/ 才有效；站点关联应用需要非根挂载点。不要从 siteId 推断附加状态。
4. 对于更正，显示精确的更改前后映射。解释 update_environment 是即时的，没有试运行，并且不会部署代码。
5. 要求 confirm，调用 update_environment 一次，并报告返回的环境、publicUrl 和 mountRefreshStatus。
6. 对于不可读或不确定的结果，定位原始的 env_id。如果使用预期的的新分支作为过滤器，则仅当返回的环境的 ID 等于该原始 env_id 时才接受它，然后将其分支和挂载点与请求的值进行比较。不同的 ID 或没有唯一匹配的原始目标是模糊的：不要继续或重试。在更改分支的更新后，切勿重用旧分支过滤器。
7. 挂载刷新失败或未知并不意味着环境更新已被回滚。将路由报告为不确定，不要仅因刷新失败而重试。
8. 如果分支已更改且用户希望部署其代码，则将 trigger_deployment 视为一个单独的、已预览并确认的变更操作。

为分支创建隔离环境并部署它

1. 解析现有的应用，调用 get_app，并在预览变更操作之前使用 siteAttached 验证提议的挂载点。
2. 翻页查看 list_environments 以检查请求的分支或挂载点是否已被使用。
3. 显示提议的分支和挂载点。解释 create_environment 是即时的，没有试运行，并且创建映射而不部署代码。
4. 生成一个稳定的 idempotency_key，要求 confirm，并调用 create_environment。仅在对该创建的精确重试时复用该密钥。
5. 报告返回的环境、publicUrl 和 mountRefreshStatus。如果结果不确定，搜索预期的分支并比较环境 ID、分支和挂载点；使用返回的 ID 来区分并发创建。在创建的环境仍然不明确时不要重试。
6. 刷新失败意味着创建成功但路由可能不完整。不要自动重试创建或删除环境。
7. 在部署此新环境之前，请遵循“所需的配置是否存在？”作为必经关卡。仅在需求与机密性得到验证后，或用户明确确定不需要任何需求时，才继续。然后，使用下面的部署工作流程进行预览、确认、归属和监控。

此部署可以从分支 HEAD 重试、回滚或重建吗？

使用变更操作的默认试运行作为能力检查。不要从缺失的日志、应用元数据或部署元数据推断资格。

对于来自连接分支或先前精确提交的新部署：

1. 解析环境。对于重试或回滚，还需解析确切的先前部署。
2. 仅当用户请求时、部署证据表明变量缺失或分类错误时、所选提交具有文档化的配置要求时，或服务器因配置拒绝部署时，才执行配置发现。