Back to Details

workflows-doctor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zapier Workflows Doctor

Zapier Workflows诊断工具

Diagnose whether the installed Zapier SDK CLI can support the Zapier Workflows skill bundle. Be diagnostic first. Do not refresh skills unless SDK/skill drift is detected or compatibility cannot be confirmed.
诊断已安装的Zapier SDK CLI是否支持Zapier Workflows技能包。首先执行诊断操作，除非检测到SDK/技能版本偏移或无法确认兼容性，否则不要刷新技能。

Compatibility Metadata

兼容性元数据

Workflow skills use these metadata fields:
  • sdk_cli_min
    : oldest SDK CLI version the skill is allowed to run against. Set it to the first SDK CLI version that supports the newest command or flag the skill depends on. If that exact first-supported version is uncertain, use the SDK CLI version used when introducing the skill instruction change.
  • sdk_cli_validated
    : SDK CLI version used during the latest validation pass. Update it whenever workflow skills are intentionally tested and republished against a newer SDK CLI, even if 
    sdk_cli_min
    does not change.
  • refresh_source
    : canonical skill source. For these skills, keep this as 
    zapier/agent-skills
    .
Command-surface checks verify required bundle capabilities only. They do not prove full workflow correctness or that JSON payload semantics are unchanged.
工作流技能使用以下元数据字段：
  • 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负载语义未发生变化。

Step 0: Daily Skill-Freshness Check

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

Run this before the SDK compatibility steps below. It keeps the workflow skills current with 
zapier/agent-skills
even when the SDK CLI has not changed, by occasionally running 
npx skills update
for the bundle. It is soft and non-blocking: it self-throttles to roughly once per day per project, never stops the calling skill, and prints nothing unless it actually applied an update.
Run it exactly once, then continue to Step 1 regardless of its output. Do not parse or branch on the result:
bash
bash scripts/skill-freshness-check.sh
Resolve 
scripts/skill-freshness-check.sh
relative to this skill's own directory. The script locates the installed skill bundle from its own path and runs the bundle update from the scope root that contains it (the directory holding 
.agents
/
.claude
), so it does not matter which directory you invoke it from.
  • If it prints a note that skills were refreshed, pass that note along to the user and keep going; the update takes full effect on the next workspace reload.
  • If it prints nothing, say nothing and continue.
This freshness check is independent of the SDK command-surface compatibility check in Steps 1–4 below, which is unchanged and remains a hard gate. For troubleshooting, set 
ZAPIER_WORKFLOWS_DEBUG=1
to see the freshness check's decision on stderr.
在执行以下SDK兼容性步骤前运行此检查。即使SDK CLI未发生变化，它也会通过偶尔对技能包执行
npx skills update
，确保工作流技能与
zapier/agent-skills
保持同步。此检查是轻量且非阻塞的：它会自动限制为每个项目每天大约一次，不会中断调用技能，仅在实际应用更新时才会输出内容。
仅运行一次，无论输出结果如何，继续执行步骤1。不要解析结果或根据结果分支处理：
bash
bash scripts/skill-freshness-check.sh
相对于此技能自身目录解析
scripts/skill-freshness-check.sh
。该脚本会从自身路径定位已安装的技能包，并从包含它的作用域根目录（即存放
.agents
/
.claude
的目录）执行技能包更新，因此无论从哪个目录调用它都不会影响结果。
  • 如果输出显示技能已刷新，请将该信息告知用户并继续操作；更新将在下次重新加载工作区后完全生效。
  • 如果没有输出内容，则无需告知用户，直接继续操作。
此新鲜度检查独立于以下步骤1-4中的SDK命令界面兼容性检查，后者保持不变且仍是硬性检查。如需排查问题，可设置
ZAPIER_WORKFLOWS_DEBUG=1
以在标准错误流中查看新鲜度检查的决策过程。

Step 1: Check Bundle Compatibility

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

Check the workflow skill bundle as one unit. Do not maintain separate compatibility checks for 
workflows-install
, 
workflows-create
, 
workflows-list
, 
workflows-history
, and 
workflows-modify
; users will normally use these skills together, and drift in any core workflow SDK surface should refresh the whole bundle.
Current workflow skills use 
sdk_cli_min: "0.67.4"
and 
sdk_cli_validated: "0.67.5"
unless the installed skills' metadata says otherwise.
将工作流技能包作为一个整体进行检查。不要为
workflows-install
、
workflows-create
、
workflows-list
、
workflows-history
和
workflows-modify
分别进行兼容性检查；用户通常会一起使用这些技能，任何核心工作流SDK界面的偏移都应刷新整个技能包。
当前工作流技能使用
sdk_cli_min: "0.67.4"
和
sdk_cli_validated: "0.67.5"
，除非已安装技能的元数据另有指定。

Step 2: Check SDK CLI Versions

步骤2：检查SDK CLI版本

Run:
bash
which zapier-sdk
zapier-sdk --version
npm view @zapier/zapier-sdk-cli version
If 
zapier-sdk
is missing or 
zapier-sdk --version
is below the bundle's 
sdk_cli_min
, update the SDK CLI before continuing:
bash
npm install -g @zapier/zapier-sdk-cli@latest
zapier-sdk --version
If global npm installs fail because of permissions, tell the user to fix their Node/npm setup before retrying. Prefer a user-owned Node install through nvm or Homebrew over 
sudo npm install -g
.
If the installed SDK CLI version is newer than the bundle's 
sdk_cli_validated
, continue to command-surface discovery. Do not refresh skills solely because the SDK CLI is newer.
执行以下命令：
bash
which zapier-sdk
zapier-sdk --version
npm view @zapier/zapier-sdk-cli version
如果
zapier-sdk
未安装，或
zapier-sdk --version
低于技能包的
sdk_cli_min
，请先更新SDK CLI再继续：
bash
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更新就刷新技能。

Step 3: Discover Current Command Surface

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

Start from the SDK help output:
bash
zapier-sdk --experimental --help
Use the help output to discover the current command names and flags for the required bundle capabilities below. Current command names in this skill are examples from the SDK CLI version the workflow skill bundle was validated against; they are not the compatibility contract. If the current help output exposes an equivalent way to perform a required capability, use the current help output.
For each discovered candidate command, inspect command-specific help:
bash
zapier-sdk --experimental <candidate-command> --help
从SDK帮助输出开始：
bash
zapier-sdk --experimental --help
使用帮助输出来发现以下技能包所需功能对应的当前命令名称和标志。此技能中的当前命令名称是工作流技能包验证时所使用的SDK CLI版本的示例，而非兼容性约定。如果当前帮助输出提供了实现所需功能的等效方式，请以当前帮助输出为准。
对于每个发现的候选命令，查看该命令的专属帮助信息：
bash
zapier-sdk --experimental <candidate-command> --help

Required Bundle Capabilities

技能包必备功能

Confirm that the SDK CLI exposes a clear way to perform these operations for the workflow skill bundle:
  • Create a workflow container.
  • Publish a workflow version.
  • List a workflow's open drafts.
  • Create (fork) a workflow draft.
  • Read a workflow draft.
  • Update a workflow draft, with optimistic concurrency via a draft revision.
  • Publish a workflow draft, with optimistic concurrency and enabled-state control.
  • Discard a workflow draft.
  • Run a durable workflow locally or synthetically.
  • List workflows.
  • List workflow runs.
  • Inspect a workflow run.
  • Discover or list app triggers.
  • Trigger a workflow.
  • Control workflow visibility, including private workflow creation or the current equivalent.
  • Bind app connections for test runs and published workflow versions.
  • Bind app implementation/version metadata when required.
  • Provide trigger configuration for published workflow versions.
  • Pass workflow input when running or triggering workflows.
  • Control enabled state when publishing workflow versions.
  • Run synthetic durable tests privately or with the current equivalent behavior.
Publishing has two paths. 
publish-workflow-draft
is the preferred one — it publishes and consumes the draft, so nothing stale is left behind. Direct 
publish-workflow-version
is for no-open-draft cases only, such as the first publish of a brand-new workflow or a headless deploy-from-source flow; the server rejects it with a conflict while any draft is open. The bundle invariant: never publish past an open draft.
When the current SDK help output is clear, prefer it over the example commands below. If discovery is ambiguous or a required capability appears absent, treat compatibility as unconfirmed and refresh the workflow skill bundle.
Example commands from the validated SDK CLI surface:
bash
zapier-sdk --experimental create-workflow --help
zapier-sdk --experimental publish-workflow-version --help
zapier-sdk --experimental run-durable --help
zapier-sdk --experimental list-workflows --help
zapier-sdk --experimental list-workflow-runs --help
zapier-sdk --experimental get-workflow-run --help
zapier-sdk --experimental list-triggers --help
zapier-sdk --experimental trigger-workflow --help
zapier-sdk --experimental get-trigger-run --help
zapier-sdk --experimental get-workflow --help
zapier-sdk --experimental get-workflow-version --help
zapier-sdk --experimental list-workflow-drafts --help
zapier-sdk --experimental create-workflow-draft --help
zapier-sdk --experimental get-workflow-draft --help
zapier-sdk --experimental update-workflow-draft --help
zapier-sdk --experimental publish-workflow-draft --help
zapier-sdk --experimental discard-workflow-draft --help
Example flags from the validated SDK CLI surface:
  • create-workflow
    : 
    --private
  • publish-workflow-version
    : 
    --connections
    , 
    --app-versions
    , 
    --trigger
    , 
    --enabled
  • update-workflow-draft
    : 
    --draft-revision
    , 
    --connections
    , 
    --app-versions
    , 
    --trigger
  • publish-workflow-draft
    : 
    --draft-revision
    , 
    --enabled
  • run-durable
    : 
    --connections
    , 
    --input
    , 
    --private
  • trigger-workflow
    : 
    --input
Equivalent current flags or command shapes are acceptable if the help text clearly supports the same required bundle capability.
确认SDK CLI为工作流技能包提供了执行以下操作的明确方式：
  • 创建工作流容器。
  • 发布工作流版本。
  • 列出工作流的未完成草稿。
  • 创建（复刻）工作流草稿。
  • 读取工作流草稿。
  • 更新工作流草稿，通过草稿修订实现乐观并发控制。
  • 发布工作流草稿，支持乐观并发控制和启用状态管理。
  • 丢弃工作流草稿。
  • 在本地或模拟环境中运行持久化工作流。
  • 列出工作流。
  • 列出工作流运行记录。
  • 查看工作流运行详情。
  • 发现或列出应用触发器。
  • 触发工作流。
  • 控制工作流可见性，包括创建私有工作流或当前等效功能。
  • 为测试运行和已发布工作流版本绑定应用连接。
  • 必要时绑定应用实现/版本元数据。
  • 为已发布工作流版本提供触发器配置。
  • 运行或触发工作流时传递工作流输入。
  • 发布工作流版本时控制启用状态。
  • 以私有方式或当前等效行为运行模拟持久化测试。
发布有两种路径。
publish-workflow-draft
是首选路径——它会发布并消耗草稿，不会留下任何过时内容。直接使用
publish-workflow-version
仅适用于无未完成草稿的场景，例如全新工作流的首次发布或无界面的从源码部署流程；当存在未完成草稿时，服务器会以冲突为由拒绝该操作。技能包的不变规则：永远不要跳过未完成草稿进行发布。
如果当前SDK帮助输出明确，请优先使用它而非以下示例命令。如果发现过程不明确或某项必备功能缺失，则视为兼容性未确认，需刷新工作流技能包。
已验证的SDK CLI界面示例命令：
bash
zapier-sdk --experimental create-workflow --help
zapier-sdk --experimental publish-workflow-version --help
zapier-sdk --experimental run-durable --help
zapier-sdk --experimental list-workflows --help
zapier-sdk --experimental list-workflow-runs --help
zapier-sdk --experimental get-workflow-run --help
zapier-sdk --experimental list-triggers --help
zapier-sdk --experimental trigger-workflow --help
zapier-sdk --experimental get-trigger-run --help
zapier-sdk --experimental get-workflow --help
zapier-sdk --experimental get-workflow-version --help
zapier-sdk --experimental list-workflow-drafts --help
zapier-sdk --experimental create-workflow-draft --help
zapier-sdk --experimental get-workflow-draft --help
zapier-sdk --experimental update-workflow-draft --help
zapier-sdk --experimental publish-workflow-draft --help
zapier-sdk --experimental discard-workflow-draft --help
已验证的SDK CLI界面示例标志：
  • create-workflow
    : 
    --private
  • publish-workflow-version
    : 
    --connections
    , 
    --app-versions
    , 
    --trigger
    , 
    --enabled
  • update-workflow-draft
    : 
    --draft-revision
    , 
    --connections
    , 
    --app-versions
    , 
    --trigger
  • publish-workflow-draft
    : 
    --draft-revision
    , 
    --enabled
  • run-durable
    : 
    --connections
    , 
    --input
    , 
    --private
  • trigger-workflow
    : 
    --input
如果帮助文本明确支持相同的技能包必备功能，当前等效的标志或命令形式也是可接受的。

Step 4: Decide Whether To Refresh Skills

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

If all required bundle capabilities are confirmed, tell the calling skill to continue without refreshing.
If any required capability is missing, or compatibility cannot be confirmed, update the entire workflow skill bundle so the skills stay in sync.
Prefer the standard day-2 update path first:
bash
npx skills update workflows-install workflows-doctor workflows-create workflows-list workflows-history workflows-modify -y
If 
skills update
cannot find the installed skills, updates the wrong scope, or otherwise fails, fall back to explicit installs from canonical GitHub:
bash
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
After updating skills, stop the current skill invocation. Tell the user to reload the agent workspace and rerun their original request. Do not promise that the current invocation has changed its already-loaded instructions.
如果所有技能包必备功能均已确认，告知调用技能无需刷新即可继续。
如果任何必备功能缺失，或兼容性无法确认，请更新整个工作流技能包以保持技能同步。
优先使用标准的日常更新路径：
bash
npx skills update workflows-install workflows-doctor workflows-create workflows-list workflows-history workflows-modify -y
如果
skills update
无法找到已安装的技能、更新了错误的作用域或出现其他失败情况，请退而求其次，从标准GitHub仓库显式安装：
bash
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
更新技能后，停止当前技能调用。告知用户重新加载代理工作区并重新执行其原始请求。不要承诺当前调用已更改其已加载的指令。