webflow-mcp:cloud-apps

Webflow Cloud Apps

使用 data_apps_tool 创建源自 GitHub 的应用、回答运维问题，以及管理 Webflow Cloud 应用的环境。从用户期望的结果着手，只收集必要的证据，并区分观察结果与结论。

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

Instructions

1. 确定范围

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

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

确定目标区域后，请验证 CLI 能够读取确切的 MCP 应用 ID 和环境 ID，并在后续变更操作中明确指定该区域和这些 ID。仅凭登录状态或区域标签不足以完成验证。如果验证失败，请报告失败，但不要推断原因，并暂停依赖此目标的变更操作。继续处理目标已确定的独立工作。

1. 在调用任何其他 Webflow MCP 工具之前，先调用 webflow_guide_tool。实时指南和操作架构是当前参数和响应的权威依据。
2. 除明确交由 CLI 处理环境变量值外，所有 Webflow 操作都使用 Webflow MCP 工具。切勿直接调用 Webflow API。
3. 每次工具调用都必须包含必需的 context 参数。使用第三人称撰写 15-25 个词。
4. 根据任务所需的功能选择工具：
   • 使用 data_apps_tool 创建源自 GitHub 的应用；检查应用、环境、域名、部署记录、日志和变量元数据；管理 GitHub 源和环境；以及将 GitHub 部署任务加入队列。
   • 使用 data_variable_tool 处理 Designer 颜色、尺寸、字体和 CSS 变量。
   • 对于 CLI／本地源应用、本地构建与部署，或创建和更新环境变量值，请使用 webflow-cli:cloud。
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. 必须获得确认。确认后、执行前，立即记录开始时间并生成一个稳定的 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 和最新部署状态。如果 publicUrl 为 null，不要构造地址。
2. 将当前分支和挂载点与用户预期的映射进行比较。如果请求仅用于诊断，则报告不匹配后停止。
3. 如果更正会更改挂载点，请调用 get_app 并使用 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 重试、回滚或重新构建此部署？

使用 mutation 的默认试运行作为能力检查。不要根据缺失的日志、应用元数据或部署元数据推断是否符合条件。

要从已连接的分支或先前的确切提交创建新部署：

1. 解析环境。对于重试或回滚，还要解析确切的先前部署。
2. 仅当用户要求进行配置发现、部署证据表明变量缺失或分类错误、所选提交有记录的配置要求，或服务因配置问题拒绝部署时，才进行配置发现。满足上述任一条件时，请遵循“所需配置是否齐全？”。如果预览或执行被拒绝，从而满足了该条件，请先解决问题再重试。否则，不添加配置前置条件。
3. 对分支 HEAD 预览 trigger_deployment，或对先前的提交预览 redeploy。如果预览拒绝该来源，不要执行任何 mutation，并将本地来源部署转至 webflow-cli:cloud。
4. 对于 redeploy，说明较旧的提交会使用环境当前的配置运行，因此无法保证兼容性。
5. 显示返回的分支或提交，并说明执行会创建新的 GitHub 构建，而不是部署本地文件。
6. 要求输入 confirm。确认后立即将最新部署记录为关联基线，然后使用 dry_run: false 和一个稳定的 idempotency_key 执行。仅在对该请求进行精确重试时复用此键。
7. 监控前先解读执行结果：
   • queued：此次调用已将部署加入队列。
   • trigger_deployment 返回 skipped：分支没有提交，因此未将部署加入队列。
   • processing：使用此键的较早调用仍在处理中；此次调用未加入重复请求。
   • 状态未知或无法读取时，结果仍不确定。
8. 此操作不会返回部署 ID。对于 queued 或已有的处理中请求，轮询 list_deployments 和 get_deployment，查找在首次执行尝试前记录的基线上方出现的记录。如果基线不可用，请说明归因可能存在歧义。存在并发部署时，不要假设最新记录属于此请求。
9. 当可归因的部署离开活动状态，或有时限的监控期结束时，停止监控。如果监控期先结束，请报告最后的状态和时间戳；不要将其判定为失败，也不要因此加入替代部署。
10. 对于重试或回滚，请预览先前部署的确切提交哈希和消息。回滚会在该提交上创建新的构建，不会移动环境分支。

4. 应用共享的证据与安全规则

• 将构建、部署和运行时日志视为可能包含敏感客户输出。引用或保存日志前，检查其中是否含有令牌、凭据、Cookie、授权标头和预签名 URL。
• 仅引用必要的最少日志证据。对敏感值和 URL 进行脱敏。
• 检查、诊断或预览请求并不授权执行 mutation。
• 每次 mutation 前，都必须提供逐项列出的预览，并要求输入确切的单词 confirm。
• 重试前，先根据可观察状态核实结果不确定的 mutation。
• 仅在对同一逻辑请求进行精确重试时复用幂等键。
• 配置或部署失败时，绝不要自动删除新创建的应用或环境。请报告部分完成的状态。

5. 处理明确的管理请求

这些操作受支持，但不是此技能的主要工作流。

对于 update_app：

1. 使用 get_app 获取当前应用。
2. 对于名称或描述变更，准备并展示确切的变更。传入 description: null 可清除描述。
3. 对于 source_url，将当前的 sourceUrl 与请求的规范 GitHub 仓库 URL 进行比较。说明立即更新需要用户授权的令牌；机器令牌会返回 403。
4. 要求 confirm，调用一次 update_app，并使用 get_app 验证。响应 无法读取时，必须先协调状态再重试。
5. 更新来源不会更改环境分支或部署代码。将这些操作视为需要单独确认的变更。
6. 重命名独立应用时，也会尝试重命名其底层站点；同步失败可能导致站点保留旧名称。附加到站点的父级名称不会更改。

对于 delete_variable：

1. 使用默认的试运行进行预览。
2. 如果 exists 为 false，报告未删除任何内容并停止。
3. 如果 exists 为 true，展示应用、环境和键；警告删除不可撤销，并要求 confirm。
4. 使用 dry_run: false 调用一次。将 deleted: true 视为成功。响应 不确定时，在重试前通过精确的键查找协调状态。

对于 delete_environment：

1. 使用默认的试运行进行预览。指出应用、环境、分支和挂载点，并说明其 worker、KV/D1/R2 存储、部署和变量都将被永久删除。
2. 说明删除不可撤销，且应用的最后一个环境无法删除。要求 confirm。
3. 使用 dry_run: false 调用一次。将 deleted: true 视为成功。
4. mountRefreshStatus 失败或为 null，表示删除已成功，但路由清理失败或状态 不确定。报告此情况，绝不重试删除。
5. 响应不确定时，持续分页，直到找到原始 env_id 或列表结束。不要使用值 可能已更改的分支筛选条件。

对于 delete_app：

1. 使用默认的试运行进行预览，并报告 deletionMode。
2. 说明 archive 会取消发布应用并将其从控制面板移除，而 hard_delete 会永久删除应用及其所有环境，且无法撤销。
3. 要求 confirm，然后使用 dry_run: false 调用一次。
4. 将 deleted: true 视为成功。重试前，通过 get_app 或应用精确的站点和 名称查找来协调不确定状态。

6. 处理错误并报告

• 环境分支或挂载点重复：报告冲突的环境；不要静默更新或删除它。
• CLI 变量写入不完整：报告失败的键，不包含其值，并在部署前停止。不要回滚已成功写入的键，也不要删除环境。
• GITHUB_APP_NOT_INSTALLED 或 GITHUB_REPO_NOT_CONNECTED：提供返回的 installUrl，并且只在用户完成连接后重试。
• 不受支持的部署预览属于能力边界，不是绕过 MCP 并直接调用 API 的理由。

仅在适用时，才纳入以下最终报告字段：所选应用；已解析的环境；检查过的证据； 观察到的状态；有依据的原因；限制；已执行的变更；部分状态；以及受阻时用户 需要采取的下一步操作。

示例

创建附加到站点的 GitHub 应用

用户：“从 https://github.com/acme/search 的 main 分支创建 search-app，并将其挂载到我的营销站点的 /search 路径。”

解析站点，使用其站点 ID 和非根挂载点预览 create_app，并使用 GitHub 来源创建工作流。分别报告应用创建结果和自动初始部署结果。

诊断失败的部署

用户：“最新的生产部署为什么失败了？”

对最新的生产部署使用部署诊断工作流。仅在日志可用时检索日志，并将空结果 报告为证据不可用，而非成功。

修正环境映射

用户：“Production 正在 /app 提供预览分支的服务。请将其改回 / 上的 main。”

使用环境映射工作流，并针对 siteAttached 验证 /。 将部署请求视为单独的变更。

配置并部署分支环境

用户：“为 feature/search 创建一个 /preview 环境并部署。 它需要 .env.preview 中的变量。”

使用新建环境工作流，然后先通过强制配置门槛，再进行部署。若后续步骤失败，请保留该环境。

指南

• 从用户的操作问题出发，而非从操作清单出发。
• 优先采用可观察到的证据，而非假设应用的构建方式。
• 使用变更预览和返回的错误检查功能是否可用。
• 对于本地源代码应用和部署，以及变量值，使用 CLI。
• 切勿使用 data_apps_tool 设置 Designer 变量。
• 切勿泄露变量、日志、错误或 URL 中的机密。
• 未获得准确预览和明确的 confirm，切勿执行变更。
• 若某项变更的结果尚不确定，先核实可观察到的状态，再重试。
• 将代码仓库、环境、配置和部署变更分开处理。
• 保留部分创建的资源，除非用户明确要求删除。