workflows-modify

Zapier 工作流修改

修改已部署的工作流时，遵循发现、获取、编辑、测试、发布、验证的流程。所有更改都要经过工作流的服务端草稿（与 Zapier 编辑器共享的工作副本）：将更改保存到草稿中；如果有必要，测试尚未发布的草稿；然后发布已测试的草稿，或将其保留为打开状态，供用户审核并稍后发布。

发布会写入用户的 Zapier 账户，因此发布前必须获得明确确认。

使用公开的 SDK CLI 实验性命令界面。不要使用 zapier-sdk-code-substrate。

兼容性检查

使用此技能前，请运行 workflows-doctor 捆绑包兼容性检查。如果未安装或无法加载 workflows-doctor，请先运行 workflows-install，或从 zapier/agent-skills 安装 workflows-doctor，然后再继续。如果 workflows-doctor 报告 SDK/技能存在偏差，请按照其刷新说明操作，停止调用此技能；如有需要，重新加载 Agent 工作区，并请用户重新提交原始请求。

第 1 步：识别工作流

如果用户提供了工作流 ID，直接使用该 ID。否则，列出工作流，并根据名称或描述查找匹配项：

zapier-sdk --stability experimental list-workflows --json

如果匹配到多个工作流，请展示候选项并询问用户要修改哪一个。

第 2 步：检查是否有未关闭的草稿

zapier-sdk --stability experimental list-workflow-drafts <workflow-id> --json

列表会返回未关闭的草稿，并按最近编辑时间从新到旧排序。未关闭的草稿始终包含尚未发布的工作（发布会消耗草稿，因此遗留的草稿从未发布）。

• 存在未关闭的草稿： 继续使用该草稿。它包含用户正在进行的编辑，你的更改会叠加在其上。如果有多个未关闭的草稿，请告知用户并确认要使用哪一个。
• 没有未关闭的草稿： 在第 3 步创建一个草稿。

如果用户的请求已表明要立即发布（“修好并上线”），那么更改保存并测试后就发布。如果用户想先审核、逐步处理，或移交给编辑器，则将草稿保持为打开状态。如果意图不明确，请询问：准备好后立即发布，还是将其保留为草稿，以便稍后审核或发布？

第 3 步：获取当前源文件

如果草稿不存在，则创建草稿（它会从工作流当前的线上版本分叉），然后获取草稿：

zapier-sdk --stability experimental create-workflow-draft <workflow-id> --json
zapier-sdk --stability experimental get-workflow-draft <workflow-id> <draft-id> --json

从获取的草稿中记录：

• source_files，尤其是 source_files["workflow.ts"]——其中可能包含尚未发布的编辑；应将其视为用户正在进行的工作，而非过时数据。
• draft_revision——每次写入时都需要它来进行乐观并发控制。
• dependencies、zapier_durable_version、trigger、connections 和 app_versions。

还要获取工作流本身，以查看其名称、启用状态和元数据：

zapier-sdk --stability experimental get-workflow <workflow-id> --json

根据此次回读结果确定当前的启动模式——修改绝不能在无提示的情况下改变启动模式。 工作流有两种启动模式，重新发布时未保留原模式，正是触发型工作流会在无提示的情况下变成无触发器工作流的原因：

• trigger——任一信号显示存在触发器：获取的版本／草稿源文件中包含 trigger 对象，或者 get-workflow 的 triggers[] 非空。逐字记录完整的 trigger 配置；发布时（第 6 步）草稿仍必须携带此配置，否则新版本会丢失触发器。
• manual——两个信号都不存在：获取的源文件中没有 trigger 对象，且 triggers[] 为空。此工作流仅按需运行。

如果两个信号不一致——尤其是已保存 trigger 配置，但线上 triggers[] 为空或已过时（表示声明失败、待处理或已禁用）——不要将其标记为手动模式。应保留触发器，并暂停操作以便与用户确认：丢弃已保存的触发器会导致无提示地丢失触发器，而此判断正是为了防止这种问题。

triggers[] 和获取到的触发器配置是当前模式的权威依据——平台的启动模式输入项（只写的 manual 标志）不会出现在任何回读结果中，因此不要查找它。除非用户明确要求更改启动模式（为手动工作流添加触发器，或移除触发器），否则修改时必须保留现有模式——在编辑、发布和验证期间保留记录的模式。

本步骤中的其余检查仅适用于基于已有草稿进行操作的情况（跳过刚创建的草稿——新分叉草稿与其基准版本相同）：

检查是否有未发布的草稿更改。 发布草稿会发布其中的所有内容，而不只是你的编辑——因此你必须确认草稿是否已与线上版本存在差异。获取草稿的基准版本并进行比较：

zapier-sdk --stability experimental get-workflow-version <workflow-id> <base_version_id from the draft> --json

如果草稿的 source_files、触发器、连接或应用版本与基准版本不同，则草稿中包含尚未发布的工作。简要记录差异摘要——在第 6 步确认时告知用户。绝不能在无提示的情况下发布或丢弃这些更改。

检查草稿是否过时。 草稿在创建时从线上版本分叉，但线上版本可能已经更新——其他草稿可能已在此期间发布。发布过时的草稿会将其旧基准内容覆盖到之后发布的所有更改。将最新版本的 id 与草稿的 base_version_id 进行比较：

zapier-sdk --stability experimental list-workflow-versions <workflow-id> --json

• **基准版本是最新版本：**未过时——继续。

• 草稿已过时，且没有未发布的更改（上面的差异检查未发现任何差异）：该草稿只是旧版本遗留的空壳。不要基于此草稿继续操作——将其丢弃，从线上版本分叉出一个新草稿，告知用户你已这样做，然后在新草稿上继续：

  zapier-sdk --stability experimental discard-workflow-draft <workflow-id> <draft-id> --json
  zapier-sdk --stability experimental create-workflow-draft <workflow-id> --json
  

• **草稿已过时，且包含未发布的更改：**暂停并告知用户。直接发布此草稿会还原它分叉以来发布的所有版本中的更改。安全做法是从线上版本分叉出一个新草稿，并将原草稿中未发布的更改（以及你的编辑）移植到新草稿上——提出此方案，并请用户明确选择移植还是仍要发布过时的草稿。绝不能替用户做决定。

步骤 4：进行编辑

如果存在本地工作流文件，请优先编辑该文件。否则，将 source_files["workflow.ts"] 写入工作流专属目录中的本地 workflow.ts，然后编辑该副本。

仅针对所请求的更改进行修改。保留现有的 Zod 架构、ctx.step 边界、连接别名、依赖项固定版本、持久运行时版本、连接绑定、应用版本绑定、触发器配置以及可见性／启用状态，除非有理由更改它们。保留与所请求更改无关的所有未发布草稿内容。

将 new Date()、Date.now() 和 Math.random() 等重放时会变化的值放在步骤内，以便只记录一次。在步骤外计算的值会在重放时发生变化，并导致运行因 DeterminismViolation 失败。

如果编辑新增了 AI／LLM 步骤，请遵循 workflows-create 第 2 阶段中的 AI by Zapier 指南。

步骤 5：规划草稿测试

对于非简单的更改，请在发布前提出测试运行方案。测试运行的是已保存的草稿，因此应在步骤 6 中编辑保存后、发布草稿前进行。测试可能会运行实际的下游操作，因此请概述副作用并等待确认。

步骤 6：确认后发布

在写入任何内容之前，请向用户概述：

1. 诊断结果。
2. 代码或配置更改。
3. 要更新的工作流 ID 和草稿。
4. 将保留的值，包括依赖项、持久版本、启用状态、连接、应用版本和触发器配置。
5. 第 3 步中记录的启动模式（trigger 或 manual），并说明此编辑不会更改该模式；或者，如果请求是更改启动模式，请明确说明更改内容（为手动工作流添加触发器，或移除触发器）。修改操作不会以副作用的形式更改启动模式。
6. 是立即发布，还是将草稿留待审核（步骤 2），以及第 3 步中发现的任何未发布草稿更改（发布草稿也会一并发布这些更改）。

等待明确确认，然后将 source_files 构建为完整映射：包含已获取草稿的 source_files 中的每个键，并替换已编辑的文件。更新操作会替换整个映射，因此未包含的文件将被删除。将已获取的映射放入 FETCHED_SOURCE_FILES，并为每个已编辑文件添加一个 --rawfile：

SOURCE_FILES="$(jq -n --argjson base "$FETCHED_SOURCE_FILES" --rawfile workflow workflow.ts '$base + {"workflow.ts": $workflow}')"

发布前，请确认即将发布的版本与第 3 步记录的启动模式一致：trigger 模式的工作流草稿必须包含其触发器，发布时不得使用 --manual；manual 模式的工作流草稿不得包含触发器，发布时必须使用 --manual（除非请求明确要求更改模式，此时应与预期的新模式一致）。触发器与 --manual 只能二选一——平台契约是一个判别联合，二者同时传入会被视为矛盾并拒绝。trigger 模式的工作流重新发布时若丢失触发器，会导致触发器无声丢失。触发器存储在草稿中；请参阅下方的启动模式检查。

保存、测试并发布草稿

如果第 3 步发现未发布的草稿更改，请先处理这些更改——明确询问用户：将它们包含在本次更改中，还是从干净版本开始？

• **包含：**按原计划继续——草稿内容将与您的编辑一起发布。

• **从干净版本开始：**丢弃该草稿，并从线上版本创建一个新草稿，然后在新草稿上重新应用您的编辑（重新执行步骤 3–4）：

  zapier-sdk --stability experimental discard-workflow-draft <workflow-id> <draft-id> --json
  zapier-sdk --stability experimental create-workflow-draft <workflow-id> --json
  

丢弃并重新创建草稿是删除未发布内容的唯一获准方式——切勿为了移除草稿内容而在原草稿中直接覆盖。

将编辑保存到草稿中，并传入读取时获得的 draft_revision：

zapier-sdk --stability experimental update-workflow-draft <workflow-id> <draft-id> "$SOURCE_FILES" \
  --draft-revision <draft_revision from Step 3> \
  --json

省略的字段会保留其已存储的草稿值，因此只有在编辑更改这些字段时，才传入 --trigger、--connections、--app-versions、--dependencies 或 --zapier-durable-version。传入 null 作为 --trigger、--connections 或 --app-versions 的值会清除已存储的值——切勿为了“跳过”字段而这样做。 启动模式检查：触发器保存在草稿中，且 publish-workflow-draft 不接受 --trigger 标志——它会发布草稿中已有的内容。因此，正确发布 trigger 模式的草稿时，发布命令中不应带 --trigger；这是预期行为，并非触发器丢失。在调用 publish-workflow-draft 前，立即确认草稿中保存的 trigger 仍与已捕获（或预期）的启动模式一致——trigger 模式的草稿仍保留触发器，manual 模式的草稿则没有（如有疑问，可使用 get-workflow-draft 读回草稿）。然后在发布时声明启动模式：manual 模式的工作流在 publish-workflow-draft 中传入 --manual（见下文）；trigger 模式的工作流草稿已保存触发器，因此发布时不要传入 --manual。绝不要将已保存的触发器与 --manual 同时使用——平台契约不允许两者并存。在上面的 update-workflow-draft 中使用 --trigger null 清除触发器，正是让 trigger 模式工作流悄然变成手动模式的方式。

**按步骤 5 的要求测试已保存的修订版。**读取草稿以获取其当前的 draft_revision（更新响应中也会返回此值），然后运行该修订版：

zapier-sdk --stability experimental run-workflow-draft <workflow-id> <draft-id> <draft-revision> \
  --input '<JSON matching input schema>' \
  --json

如果工作流不接受输入，请省略 --input。运行会使用草稿中保存的依赖项、连接和应用版本。记录返回的 id，并轮询 get-workflow-run <run-id> --json。当 status 为 "finished"、output 符合此次更改预期、error 为 null、顶层 errors 为空、kind 为 "draft"，且 workflow_id、workflow_draft_id 和 draft_revision 与所测试的草稿一致时，测试即通过。如果测试失败，请修复源文件，再次更新草稿，并测试新的修订版。

**如果用户选择稍后发布，**请在此处停止：报告草稿 ID 和草稿的编辑器链接——https://zapier.com/workflow/<workflow-id>/draft/<draft-slug>/workflow.ts，其中使用草稿响应中的 slug——以便用户在编辑器中检查并发布，或在后续对话中要求你发布。最后一段是草稿 source_files 中的一个键（此技能流程中为 workflow.ts）。

**否则立即发布，**传入经过测试的 draft_revision（如果未测试，则传入更新响应中的值），以免并发编辑导致未经测试的内容上线。根据启动模式选择对应的发布命令（草稿已保存触发器，区别仅在于是否传入 --manual）：

trigger 模式——已保存的触发器即为信号，不传入 --manual：

zapier-sdk --stability experimental publish-workflow-draft <workflow-id> <draft-id> \
  --draft-revision <tested draft_revision> \
  --json

manual 模式——草稿中没有触发器，需声明 --manual：

zapier-sdk --stability experimental publish-workflow-draft <workflow-id> <draft-id> \
  --draft-revision <tested draft_revision> \
  --manual \
  --json

发布草稿会创建一个新的不可变版本，推进线上版本指针，并丢弃草稿——发布操作会消耗草稿，因此只要草稿仍处于打开状态，就表示尚有未发布的工作。响应会同时包含新版本 version 和已消耗的草稿 draft（status: "discarded"）。任何后续修改都必须从步骤 2 重新开始。

如果省略 --enabled，发布会保留工作流当前的启用状态。除非用户要求更改启用状态，否则请省略该参数。

**发生冲突（修订版不匹配）时：**有人在你读取和写入之间编辑了草稿，很可能是用户在编辑器中进行了修改。切勿盲目覆盖。重新读取草稿（get-workflow-draft），在最新的 source_files 基础上重新应用你的更改，然后使用新的 draft_revision 重试。如果最新内容与你的更改存在实质冲突，请停止并询问用户。

第 7 步：验证

如果更改已发布，请读取工作流和版本信息：

zapier-sdk --stability experimental get-workflow <workflow-id> --json
zapier-sdk --stability experimental list-workflow-versions <workflow-id> --json

确认最新版本反映了此次发布；如果工作流原本应处于启用状态，则确认它仍处于启用状态；并确认触发器、连接和应用版本元数据均已保留。

以启动模式保留情况作为通过条件。 将已部署的启动模式与第 3 步记录的模式进行比较。enabled 状态与触发器是否存在彼此独立——仅检查 enabled 无法发现触发器丢失，因此请直接检查 triggers[]：

• 记录的模式是 trigger（且此次编辑并非要移除触发器）→ 要求读取结果仍显示非空的 triggers[]，并且 enabled 与工作流保留的启用状态一致（在第 3 步记录），而不是无条件要求 enabled: true。编辑前处于禁用状态的工作流仍应保持禁用，并且仍可通过此检查；只有在编辑前工作流已启用（或用户要求启用）时，才要求 enabled: true。空的 triggers[] 表示已发布的草稿不再包含该触发器（最常见的原因是 update-workflow-draft 调用传入了 --trigger null 或更改了配置）——不要报告更改已完成；请使用 update-workflow-draft --trigger '<captured trigger JSON>' 恢复记录的配置，测试新的草稿修订版，发布并重新检查。证明触发器得以保留的是 triggers[] 检查，而不是 enabled 状态：触发式工作流可以合法地处于禁用状态，而丢失触发器的禁用工作流读取结果仍会显示 enabled: false。
• 记录的模式是 manual（且此次编辑并非要添加触发器）→ 要求 triggers[] 保持为空。意外出现触发器也属于不匹配——请停止操作并与用户确认。
• 如果请求明确要求更改启动模式，请改为验证读取结果是否符合预期的新模式。应以 triggers[] 作为比较依据；平台仅用于写入的 manual 标志不会显示在读取结果中，因此不要查找它。

无论触发器类型如何，都要检查 triggers[] 中匹配条目的 details.webhook_url——如果存在，这是外部服务调用的捕获 URL，应当分享；与工作流级别的 trigger_url 不同。大多数触发器没有此项，这属于正常情况。如果没有实际触发器事件就难以验证更改，请明确告知用户应发送什么测试事件，以及预期结果是什么。

最后报告：

• 工作流名称和 ID。
• 请求的更改是已发布，还是已保存为草稿以供之后发布（包含草稿 ID）。
• 启动模式（trigger 或 manual）以及它已保留（或者，如果更改要求修改启动模式，则报告其新值），并确认已通过第 7 步的检查。
• 触发器、连接和应用版本元数据是否已保留。
• 工作流是否已启用。
• 触发器的 webhook_url（如果存在）。
• Zapier 编辑器链接：https://zapier.com/workflow/<workflow-id>——或者，如果更改已暂存为草稿，则提供草稿链接 https://zapier.com/workflow/<workflow-id>/draft/<draft-slug>/workflow.ts。

还原

之前的版本仍可作为只读历史记录使用。要还原，请获取先前版本的源代码：

zapier-sdk --stability experimental list-workflow-versions <workflow-id> --json
zapier-sdk --stability experimental get-workflow-version <workflow-id> <version-id> --json

然后像发布其他更改一样，通过第 6 步发布：使用 update-workflow-draft 将先前版本的 source_files 和元数据载入草稿，测试并发布草稿。确认和冲突处理方式与第 6 步相同。