workflows-doctor

Zapier 工作流诊断工具

诊断已安装的 Zapier SDK CLI 是否支持 Zapier Workflows 技能包。首先进行诊断。只有检测到 SDK/技能包不一致，或无法确认兼容性时，才刷新技能。

兼容性元数据

工作流技能使用以下元数据字段：

• sdk_cli_min：技能允许使用的最旧 SDK CLI 版本。将其设为支持该技能所依赖的最新命令或标志的首个 SDK CLI 版本。如果无法确定确切的首个支持版本，则使用引入该技能指令时所用的 SDK CLI 版本。
• sdk_cli_validated：最近一次验证时使用的 SDK CLI 版本。每当有意使用更新的 SDK CLI 测试并重新发布工作流技能时，都要更新此字段，即使 sdk_cli_min 没有变化。
• refresh_source：规范的技能来源。对于这些技能，请将其设为 zapier/agent-skills。

命令表面检查只验证所需的技能包功能，不代表工作流完全正确，也不代表 JSON 负载语义保持不变。

第 0 步：每日技能新鲜度检查

先于以下 SDK 兼容性步骤运行此检查。即使 SDK CLI 未发生变化，它也会通过偶尔对该技能包运行 npx skills update，使工作流技能与 zapier/agent-skills 保持同步。此检查仅作提示，不会阻塞流程：它会自行限流，确保每个项目大约每天运行一次，绝不会停止调用该技能，并且只在实际应用更新时打印内容。

恰好运行一次，然后无论输出如何都继续执行第 1 步。不要解析结果，也不要据此分支处理：

bash scripts/skill-freshness-check.sh

请根据此技能自身的目录解析 scripts/skill-freshness-check.sh。该脚本会根据自身路径定位已安装的技能包，并从包含该技能包的作用域根目录（存放 .agents/.claude 的目录）运行技能包更新，因此从哪个目录调用它都没有影响。

• 如果它打印了技能已刷新的提示，请将该提示告知用户，然后继续；更新会在下次重新加载工作区时完全生效。
• 如果它没有打印内容，则不必说明，直接继续。

此新鲜度检查独立于以下第 1–4 步中的 SDK 命令表面兼容性检查；后者保持不变，仍是硬性门槛。如需排查问题，请设置 ZAPIER_WORKFLOWS_DEBUG=1，以便在 stderr 中查看新鲜度检查的判断结果。

第 1 步：检查技能包兼容性

将工作流技能包作为一个整体进行检查。不要分别为 workflows-install、workflows-create、workflows-list、workflows-history 和 workflows-modify 维护兼容性检查；用户通常会一起使用这些技能，任何核心工作流 SDK 表面发生不一致，都应刷新整个技能包。

workflows-create 和 workflows-modify 使用 run-workflow-draft 测试未发布的草稿，并使用 publish-workflow-draft 发布已测试的草稿；通过在 update-workflow-draft 或 publish-workflow-draft 上使用 --manual，声明手动启动模式。每条命令都在 --stability experimental 下运行。技能包的最低版本门槛为 sdk_cli_min = 0.85.0，这是首个提供 --stability 的 @zapier/zapier-sdk-cli 版本（run-workflow-draft 于 0.82.0 引入；较旧的 --experimental 标志已弃用）。低于此版本的 CLI 会被标记为需要升级。

第 2 步：检查 SDK CLI 版本

运行：

which zapier-sdk
zapier-sdk --version
npm view @zapier/zapier-sdk-cli version

如果缺少 zapier-sdk，或 zapier-sdk --version 低于技能包的 sdk_cli_min，请先更新 SDK CLI，再继续：

npm install -g @zapier/zapier-sdk-cli@latest
zapier-sdk --version

如果全局 npm 安装因权限问题失败，请告知用户先修复 Node/npm 环境，再重试。优先使用通过 nvm 或 Homebrew 安装、归用户所有的 Node，而不是使用 sudo npm install -g。

如果已安装的 SDK CLI 版本高于技能包的 sdk_cli_validated，请继续进行命令表面检查。不要仅仅因为 SDK CLI 版本较新就刷新技能。

第 3 步：发现当前命令界面

从 SDK 帮助输出开始：

zapier-sdk --stability experimental --help

使用帮助输出，发现下方必需的工作流技能包功能对应的当前命令名称和标志。本技能中的当前命令名称只是工作流技能包验证所依据的 SDK CLI 版本中的示例，并非兼容性契约。如果当前帮助输出显示了执行某项必需功能的等效方式，请以当前帮助输出为准。

检查每个发现的候选命令的专属帮助信息：

zapier-sdk --stability experimental <candidate-command> --help

必需的技能包功能

确认 SDK CLI 提供了清晰的方式，可为工作流技能包执行以下操作：

• 创建工作流容器。
• 列出工作流未完成的草稿。
• 创建（分叉）工作流草稿。
• 读取工作流草稿。
• 更新工作流草稿，并通过草稿修订版实现乐观并发控制，同时声明其启动模式（使用 --trigger，或按需启动时使用 --manual）。
• 运行工作流草稿：启动给定草稿修订版的未发布测试运行（run-workflow-draft）。
• 发布工作流草稿，并通过乐观并发控制和启用状态进行管理，同时声明其启动模式（使用已存储的触发器，或按需启动时使用 --manual）。
• 丢弃工作流草稿。
• 列出工作流。
• 列出工作流运行记录。
• 检查工作流运行记录。
• 发现或列出应用触发器。
• 触发工作流。
• 控制工作流可见性，包括创建私有工作流或使用当前的等效方式。
• 在工作流草稿上绑定应用连接。
• 在必要时绑定应用实现/版本元数据。
• 在工作流草稿上提供触发器配置。
• 运行或触发工作流时传入输入。
• 发布工作流草稿时控制启用状态。

该技能包通过草稿发布：publish-workflow-draft 会发布经过测试的草稿修订版并消耗该草稿，因此不会遗留过时的草稿。该技能包不使用直接的 publish-workflow-version。该技能包的不变量是：绝不在存在未完成草稿时发布。

当当前 SDK 帮助输出清晰明确时，应优先使用它，而不是下方的示例命令。如果发现结果模糊，或似乎缺少某项必需功能，则将兼容性视为尚未确认，并刷新工作流技能包。

经过验证的 SDK CLI 界面中的示例命令：

zapier-sdk --stability experimental create-workflow --help
zapier-sdk --stability experimental list-workflows --help
zapier-sdk --stability experimental list-workflow-runs --help
zapier-sdk --stability experimental get-workflow-run --help
zapier-sdk --stability experimental list-triggers --help
zapier-sdk --stability experimental trigger-workflow --help
zapier-sdk --stability experimental get-trigger-run --help
zapier-sdk --stability experimental get-workflow --help
zapier-sdk --stability experimental get-workflow-version --help
zapier-sdk --stability experimental list-workflow-drafts --help
zapier-sdk --stability experimental create-workflow-draft --help
zapier-sdk --stability experimental get-workflow-draft --help
zapier-sdk --stability experimental update-workflow-draft --help
zapier-sdk --stability experimental run-workflow-draft --help
zapier-sdk --stability experimental publish-workflow-draft --help
zapier-sdk --stability experimental discard-workflow-draft --help

经过验证的 SDK CLI 界面中的示例标志：

• create-workflow：--private
• update-workflow-draft：--draft-revision、--dependencies、--connections、--app-versions、--trigger、--manual
• run-workflow-draft：--input
• publish-workflow-draft：--draft-revision、--manual、--enabled
• trigger-workflow：--input

只要帮助文本清晰地表明当前等效标志或命令形式支持相同的必需技能包功能，即可接受。

第 4 步：决定是否刷新技能

如果已确认所有必需的技能包功能，则告知调用技能无需刷新，可继续执行。

如果缺少任何必需功能，或无法确认兼容性，则更新整个工作流技能包，使各项技能保持同步。

优先使用标准的 day-2 更新路径：

npx skills update workflows-install workflows-doctor workflows-create workflows-list workflows-history workflows-modify workflows-ai-by-zapier -y

如果 skills update 找不到已安装的技能、更新了错误的作用域，或以其他方式失败，则改为从规范的 GitHub 仓库显式安装：

npx skills add zapier/agent-skills --skill workflows-install --yes
npx skills add zapier/agent-skills --skill workflows-doctor --yes
npx skills add zapier/agent-skills --skill workflows-create --yes
npx skills add zapier/agent-skills --skill workflows-list --yes
npx skills add zapier/agent-skills --skill workflows-history --yes
npx skills add zapier/agent-skills --skill workflows-modify --yes
npx skills add zapier/agent-skills --skill workflows-ai-by-zapier --yes

更新技能后，停止当前技能调用。告知用户重新加载 Agent 工作区，并重新运行其原始请求。不要承诺当前调用已更改其已加载的指令。