workflows-install

Zapier Workflows 早期访问安装

指令式操作指南。每一步都必须通过后才能继续。失败的步骤不得跳过。

这是优先面向公众的早期访问路径。它使用 Zapier SDK CLI，不会安装旧版 @zapier/zapier-sdk-code-substrate 包。

流程

flowchart TD
  probe["1. Probe environment"] --> envOk{"Node 18+, npm, git OK?"}
  envOk -->|no| stopEnv["STOP: tell user what to install"]
  envOk -->|yes| installCli["2. Install or update SDK CLI"]
  installCli --> verifyExperimental["3. Verify experimental commands"]
  verifyExperimental --> commandsOk{"Code Workflows commands visible?"}
  commandsOk -->|no| stopCli["STOP: diagnose SDK CLI install"]
  commandsOk -->|yes| checkAuth["4. Check Zapier auth"]
  checkAuth --> authOk{"JSON has data and no errors?"}
  authOk -->|no| login["4b. Ask user to run interactive login"]
  login --> checkAuth
  authOk -->|yes| checkAccess["5. Check Zapier Workflows EA access"]
  checkAccess --> accessOk{"Read-only workflow list succeeds?"}
  accessOk -->|no| stopAccess["STOP: closed beta access required"]
  accessOk -->|yes| installSkills["6. Bootstrap companion skills"]
  installSkills --> report["7. Report success and next steps"]

安装内容

• @zapier/zapier-sdk-cli@latest — 提供 zapier-sdk、zapier-sdk-cli 和 zapier-sdk-experimental 的公开 npm 包。全局安装。
• 通过 skills CLI 安装六个配套技能：workflows/doctor、workflows/create、workflows/list、workflows/history、workflows/modify 和 workflows/ai-by-zapier（在工作流中配置 AI by Zapier 步骤；与 workflows/create 或 workflows/modify 搭配使用）。

以下内容不会安装：

• @zapier/zapier-sdk-code-substrate — 旧版私有 CLI 路径。早期访问期间请勿安装。
• 全局安装 @zapier/zapier-durable。需要时，create 技能会在工作流项目中安装或固定其版本。

步骤 1：检查环境

运行每项检查。如果任何一项失败，请停止并告知用户如何修复。

node --version
npm --version
git --version

预期输出：

v18.0.0   # or higher
10.x.x    # npm version; any current version is fine
git version 2.x.x

要求：

工具	最低版本	缺失时的安装方式
Node	18	brew install node 或使用 nvm
npm	任意当前版本	随 Node 捆绑
git	任意版本	通常已预装在 macOS 上；否则运行 brew install git

如果缺少 Node 或 npm，请说明 Node 包含 npm，用户需要先正常安装 Node 才能继续。对于 macOS 用户，建议使用 nodejs.org 上的 Node LTS 安装程序、Homebrew（brew install node）或他们已经在使用的 nvm。在 node --version 和 npm --version 均可正常运行前，不要继续。

如果缺少 git，请说明只有从 GitHub 下载配套技能时才需要 git。对于 macOS 用户，建议安装 Apple Command Line Tools 或 Homebrew git。在 git --version 可正常运行前，不要继续。

步骤 2：安装或更新 Zapier SDK CLI

检查现有二进制文件和最新发布的 CLI 版本：

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

如果缺少 zapier-sdk，请全局安装 CLI：

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

如果已存在 zapier-sdk，请将 zapier-sdk --version 显示的已安装版本与 npm view @zapier/zapier-sdk-cli version 显示的最新版本进行比较。如果两者不同，请更新 CLI：

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

更新后，重新运行：

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

只有在已安装的 CLI 版本与最新发布的 @zapier/zapier-sdk-cli 版本一致时，才能继续。

验证二进制文件位于 PATH 中：

which zapier-sdk
zapier-sdk --version

如果全局 npm 安装因权限问题失败，请告知用户先修复 Node/npm 环境，然后重试。优先使用由用户拥有的 Node 安装（通过 nvm 或 Homebrew），不要使用 sudo npm install -g。

步骤 3：验证 Code Workflows 实验性命令

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

预期输出中包含 Code Workflows 命令组，其中包括以下命令：

create-workflow
list-workflows
list-workflow-runs
get-workflow-run
list-workflow-drafts
create-workflow-draft
get-workflow-draft
update-workflow-draft
run-workflow-draft
publish-workflow-draft
discard-workflow-draft

特定命令的帮助信息必须显示配套技能所依赖的标志：

• create-workflow --help 包含 --private。
• update-workflow-draft --help 包含 --draft-revision、--connections、--app-versions、--trigger 和 --manual。
• run-workflow-draft --help 执行成功。
• publish-workflow-draft --help 包含 --draft-revision 和 --enabled。
• list-triggers --help 执行成功。
• get-workflow-run --help 执行成功。
• trigger-workflow --help 包含 --input。

等效的二进制文件也可能有效：

zapier-sdk-experimental --help

如果这两种形式都没有显示 Code Workflows 命令，请停止并排查 SDK CLI 安装问题。不要改用 @zapier/zapier-sdk-code-substrate。

如果存在 zapier-sdk，但缺少 Code Workflows 命令组或特定命令所需的标志，用户很可能使用的是较旧版本的 SDK CLI。运行：

npm install -g @zapier/zapier-sdk-cli@latest
zapier-sdk --stability experimental --help
zapier-sdk --stability experimental run-workflow-draft --help

更新后，再检查一次特定命令的帮助信息。只有在 Code Workflows 命令组和所需标志都显示出来后，才能继续。如果更新后仍缺少所需标志，请停止并报告已安装的 CLI 版本和 npm 最新版本；不要将配套技能安装到无法运行其文档所述命令格式的工作区中。

步骤 4：向 Zapier 进行身份验证

先检查身份验证状态：

zapier-sdk get-profile --json

仅当 JSON 中包含非 null 的 data 对象，其中有电子邮件地址，且 errors 数组为空时，才视为身份验证成功。不要仅依赖退出代码；部分 SDK CLI 身份验证失败时，退出代码为 0，但 JSON 正文中会包含错误。

预期的成功输出中包含用户的电子邮件地址：

{
  "data": {
    "email": "[email protected]"
  },
  "errors": []
}

如果 data 为 null、errors 不为空，或错误消息指出需要进行身份验证，请停止并让用户在真实终端中运行交互式登录命令：

zapier-sdk login

这会打开浏览器。CLI 错误文本可能会建议运行 npx zapier-sdk login，但在完成上述全局安装后，建议使用的命令是 zapier-sdk login。除非用户明确要求你管理交互式登录，否则不要在非交互式 shell 或后台进程中运行浏览器登录。用户完成登录后，重新运行 zapier-sdk get-profile --json 并再次检查 JSON。

Zapier 员工通常使用其 Zapier 工作账户登录。进行外部用户测试时，请使用已获准使用 Zapier Workflows EA 的账户。

不要向用户索要 Zapier 密码、API 密钥、npm 令牌或复制的身份验证令牌。除非用户明确表示他们要使用客户端凭据进行自动化，否则应通过基于浏览器的 zapier-sdk login 流程进行身份验证。

如果用户想要在自动化中使用非交互式身份验证，请注意 CLI 错误消息可能会提及 ZAPIER_CREDENTIALS 或客户端凭据环境变量。对于此 EA 安装路径，优先使用浏览器登录，除非用户已经拥有客户端凭据。

第 5 步：检查 Zapier Workflows EA 访问权限

SDK 配置文件认证成功后，使用只读的 Code Workflows 调用，确认已认证的账户具有 Zapier Workflows EA 访问权限：

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

预期输出为包含工作流数据或空列表的 JSON，且没有错误。此命令不应创建或修改云端状态。

只有当 JSON 包含工作流数据或空工作流列表，且 errors 为空时，才将访问检查视为成功。不要仅依赖退出代码；此命令可能返回退出代码 0，但 JSON 正文中包含错误。

如果响应提示需要认证，请返回第 4 步并排查 SDK 认证问题。

如果响应包含以下任一内容，请将其视为 Zapier Workflows EA 访问失败，并在安装配套技能前停止：

• None of the security schemes (userJwt) successfully authenticated this request
• allowlist、not allowlisted 或 not whitelisted
• forbidden、permission、unauthorized 或 access denied

EA 访问失败时，请告知用户：

You're logged in to Zapier as <email>, and the Zapier SDK CLI is installed, but this account does not currently have Zapier Workflows EA access.

Zapier Workflows is currently only available to members of our closed beta.

To request access, fill out the beta sign-up form:

https://next-gen-zaps.zapier.app/

Submitting the form does not grant access immediately. The Zapier team will review your request and let you know once access has been granted.

After your account is allowlisted, rerun the workflows-install skill in this workspace. Reinstalling Node, npm, git, or the SDK CLI will not fix this access check.

用 zapier-sdk get-profile --json 中的电子邮件替换 <email>。

第 6 步：初始化 Workflows 配套技能

只有在确认 SDK 认证和 Zapier Workflows EA 访问权限后，才将配套技能安装到当前工作区。

使用公开的 skills.sh 安装方式。npx 命令会运行 skills CLI；该仓库发布后，技能内容将来自公开的 zapier/agent-skills GitHub 仓库。

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

验证：

npx skills list --json

预期输出应包含已安装的工作流配套技能：workflows-doctor、workflows-create、workflows-list、workflows-history、workflows-modify 和 workflows-ai-by-zapier。

如果缺少任何配套技能，请重新运行对应的 npx skills add ... 命令，并在继续之前排查问题。

后续更新使用标准的 skills CLI 更新方式。如果配套技能检测到 SDK/技能不一致，请重新运行 workflows-install 或运行 workflows-doctor；这两种方式是规范的修复途径。

npx skills update --project

第 7 步：报告成功

告知用户：

• 已安装 Zapier SDK CLI，且位于 PATH 中，已通过 which zapier-sdk 确认。
• Code Workflows 实验性命令已可用。
• 通过 zapier-sdk get-profile --json 获取的已认证 Zapier 账户电子邮件。
• 已通过只读工作流列表确认 Zapier Workflows EA 访问权限。
• 已安装六个配套工作流技能：workflows/doctor、workflows/create、workflows/list、workflows/history、workflows/modify 和 workflows/ai-by-zapier。
• 这确认了 SDK CLI 安装、登录、Zapier Workflows EA 访问权限和技能初始化，但尚不能证明创建、发布、触发或运行完整工作流均可正常工作。

用户接下来的步骤：

• 在尝试创建工作流前，先配置应用连接：https://zapier.com/app/assets/connections
• 重新加载 Agent 工作区，以便加载新技能。Agent 要想可靠地自动发现已安装的工作流技能，必须执行此步骤。
• 请 Agent 创建工作流，例如：“创建一个 Zapier 工作流，接收手动输入并发送 Slack 消息。”

故障排查

症状	可能原因	解决方法
node --version 显示低于 v18	Node 版本过旧	运行 brew upgrade node，或使用 nvm 安装当前 LTS 版本
npm install -g 因权限错误而失败	全局 npm 前缀目录不可由当前用户写入	使用 nvm 或 Homebrew Node；除非用户明确接受这种系统级变更，否则避免运行 sudo npm install -g
zapier-sdk --stability experimental --help 中没有 Code Workflows 命令	CLI 版本过旧或安装了错误的软件包	安装 @zapier/zapier-sdk-cli@latest，然后重新运行 zapier-sdk --version 和帮助命令
zapier-sdk get-profile 提示尚未登录	用户尚未通过 CLI 身份验证	在交互式终端中运行 zapier-sdk login，然后重试
get-profile 成功，但 list-workflows 返回访问、权限、允许列表或 JWT／安全方案错误	Zapier 账户已通过身份验证，但没有 Zapier Workflows EA 访问权限	请勿继续安装配套技能。告知用户 Zapier Workflows 目前仅向封闭测试版成员开放，提供已通过身份验证的邮箱，并请用户在将其加入允许列表后重新运行 workflows-install。
zapier-sdk login 未打开浏览器	未配置默认浏览器，或处于远程／SSH 会话中	运行 zapier-sdk login --headless，在任意浏览器中打开显示的登录链接，并粘贴它要求提供的回调 URL；或者在本地终端中运行
zapier-sdk login 在非交互式 shell 中卡住	login 需要通过浏览器交互，无法在无人值守的情况下运行	请用户在实际终端中手动运行
npx skills add zapier/agent-skills --skill workflows-... 失败	公共技能源不可用、技能尚未发布，或网络访问失败	确认 zapier/agent-skills 公共仓库和工作流技能路径可用，然后重新运行相应的安装命令
安装后技能不会自动调用	Agent 工作区尚未重新加载技能目录	重新加载工作区或重启 Agent