行为流

Zion 平台的行为流为用户提供了流程化操作编排和多种触发方式的工具，最终产出为自定义“行为”，类似于市面上的工作流编辑、自动化流程产品。

免费版用户仅支持配置 1 个行为流，高级版及以上用户可配置无限个行为流。

适用场景

适用于需要执行复杂数据处理和业务逻辑的自动化场景。

• 商城应用：如用户购买金额超 1 万元时自动升级为金卡会员。
• 定时任务：如每日检查所有未支付订单并发送通知。
• 支付：如收到支付成功信息后自动执行后续业务逻辑。

行为流的组成

基础属性

• ID：每个行为流有唯一 ID，可在日志功能中查询。详见 日志服务。
• 版本：每次变更并保存行为流都会生成新版本。
  • 更新预览：前端和后端同时更新到最新的版本
  • 同步变更：仅将后端变更同步到最新版本
  ⚠️

  如果只同步后端，而前端仍在调用旧版本的行为流，会导致不符合预期的情况。

• 执行方式：支持同步和异步两种执行方式（指行为流本身，不是节点）。
  • 同步：调用后会等待执行结果。同步行为流具备 ACID  特性：
    • 原子性：整个行为流被视为一个不可分割的最小单元，对数据库数据的修改要么全部成功，要么全部失败。不会出现只修改了部分数据的情况。大大增加了数据的可靠性。
    • 一致性：保证数据库数据始终处于合法的状态，不会出现脏数据。
    • 隔离性：行为流之间不会互相干扰，避免因数据争抢导致的混乱和错误，让结果更加可控和可预测。
    • 持久性：一旦行为流执行完成，对数据库的修改就会永久生效，保证数据安全。
  • 异步：先调用，后监听结果。 如果通过 webhook 方式触发异步行为流，需用 fz_listen_action_flow_result 订阅接口监听结果：

      subscription listenResult {
        fz_listen_action_flow_result(taskId: "_____") {
          output
          status
        }
      }

  • 同步和异步的详细对比：

    	同步	异步
    超时时长	整个行为流 15 秒（付费项目无限制）	每个节点 15 秒（付费项目无限制）
    超时/出错处理	所有数据库的数据修改都会被回滚	错误节点上的数据库的数据更改会被回滚

行为流变量

定义后可被行为流内所有节点引用，也可用“赋值行为流变量”节点赋值。

节点

目前已支持数据库操作、执行 AI、权限修改、API 调用、执行代码块等多类型节点。

数据库

可以选择一张表进行数据的查询、插入、修改和删除

调用 API

可以选择执行一个已在 API 功能中配置的 API，将返回结果绑定到出参上，即可在行为流中输出该 API 的执行结果。

运行 AI

执行配置好的 Agent（行为流执行方式需改为异步）。

运行行为流

调用另一个行为流。同步行为流无法调用异步行为流。

设置变量

对已经声明的行为流变量进行赋值。

当前用户

获取当前用户 ID，以及微信 Union ID、Open ID、Access Token。

权限

对指定用户进行角色授权或移除。

运行代码

执行自定义代码块，具体教程见 代码块。

文件

保存外部图片、视频和文件，并转换为 Zion 的对应类型。

条件分支

用于分支逻辑判断，执行顺序为从左到右依次判断。

列表循环

用于遍历列表中的每个元素，并对每个元素执行指定操作。循环的运行过程如下：

1. 输入： 此节点接收一个列表作为数据源。
2. 执行： 从列表第一项开始，执行循环体内的全部动作；完成后自动处理下一项，直至列表处理完毕。
3. 输出： 每次迭代中，可将「项数据 (item)」和「项索引 (index)」作为内部节点的输入。

条件循环

用于循环执行指定次数的逻辑。循环的运行过程如下：

1. 条件： 设置一个条件表达式。
2. 执行： 如果条件表达式为真，则执行循环体内的全部动作；否则跳出循环。
3. 结束： 当条件表达式为假时，循环结束。

跳出循环

用于跳出最近一层循环。

Gemini Veo 3.1

视频生成节点。Veo 3.1 可生成最长约 8 秒、720p / 1080p / 4K 的高保真视频，并支持原生音频（行为流执行方式需改为异步）。

参数说明

发送短信 - 阿里云

发送阿里云短信节点，用于在自动化流程中调用阿里云短信服务，向指定手机号发送验证码、通知或营销短信。

若需在用户注册、登录、重置密码等场景下使用该节点发送验证码，需要先在 设置 → 验证码 中添加自定义配置，然后在该节点中选择自定义配置。具体教程见 用户事件 - 发送验证码。

1. 准备工作 (在阿里云控制台完成)

在使用此节点前，您必须在阿里云平台完成以下准备：

• 开通服务：开通阿里云短信服务。
• 获取凭证：在阿里云 RAM 控制台创建一个子账号（建议），授予 AliyunDysmsFullAccess（或按需精细授权）权限，并获取对应的 AccessKey ID 和 AccessKey Secret。
• 申请签名：在短信控制台申请“短信签名”（如：阿里云），并等待审核通过。
• 申请模板：在短信控制台申请“短信模板”（例如：您的验证码为：${code}，5分钟内有效。），并获取对应的模板 Code（如：SMS_153055555）。

2. 配置行为流节点 (在 Zion 完成)

更详细的字段说明，见 阿里云短信 API 文档 。

• access_key

  • 填写说明：输入您在阿里云获取的 AccessKey ID。
  • 示例：LTAI5t7*******

• access_secret

  • 填写说明：输入与 AccessKey ID 对应的 AccessKey Secret。请注意保密，不要泄露。

• phone_numbers (接收手机号)

  • 填写说明：输入需要接收短信的手机号码。支持国内和国际手机号。
  • 支持群发：如果需要向多个手机号发送，可以以英文逗号 , 分隔（例如：+8613900000000,+8613811111111），最多支持 1000 个手机号。可以通过绑定前置节点的数据来动态填入。
  手机号格式必须为 E.164（含 + 与国家码），例如：+8613900000000。否则可能被识别为非法手机号，导致发送失败。

• sign_name (短信签名)

  • 填写说明：输入在阿里云控制台已审核通过的短信签名名称。
  • 示例：阿里云（不需要包含签名外面的【】括号）。

• template_code (短信模板 Code)

  • 填写说明：输入在阿里云控制台已审核通过的短信模板的 Code。
  • 示例：SMS_153055555

• template_params (模板参数)

  • 填写说明：如果您的短信模板中包含变量（如 ${code}），需要在此处传入变量的实际值。
  • 配置技巧： 该参数类型为 JSON，若编辑器无法直接填写 JSON，建议在发送短信节点前添加运行代码节点生成对象并绑定到本字段。示例：

  const code = context.getArg('code');
  context.setReturn('code_param', {
    code: code
  });

  代码说明：通过入参 code 将验证码传入，组装成 JSON 字符串后通过出参 code_param 返回。 实际返回的 JSON 为 {"code":"123456"}。

• sms_up_extend_code (上行短信扩展码 - 高级选项)

  • 填写说明：非必填。用于定制某种服务或完成查询的上行短信扩展码。无特殊业务需求请留空。

• out_id (外部流水扩展字段 - 高级选项)

  • 填写说明：非必填。外部系统的流水号。如果您需要在阿里云的短信回执中携带您自己系统的订单号或流水号以便对账，可以填入此字段。无特殊需要请留空。

发送短信 - Twilio

Twilio 是全球常用的云通信平台，该节点常用于向海外用户发送短信验证码、国际物流通知等，也支持发送国内短信。

若需在用户注册、登录、重置密码等场景下用该节点发送验证码，需要先在 设置 → 验证码 中添加自定义配置，并在自定义发送行为流中绑定本节点参数。具体教程见 用户事件 - 发送验证码。

1. 准备工作（在 Twilio 控制台完成）

在使用此节点前，请在 Twilio 完成以下准备：

• 注册并登录：拥有 Twilio 账号并进入 Console 。
• 获取凭证：在控制台查看 Account SID 与 Auth Token（Auth Token 需点击显示后复制，注意保密）。
• 发信号码：在 Twilio 购买或使用试用提供的、已具备短信（SMS）能力的发信号码；该号码将填在节点的 from_phone_number 中。号码格式需符合 Twilio 要求（通常为带国家码的 E.164，如 +12025550100）。

2. 配置行为流节点（在 Zion 完成）

右侧面板「输入」中的字段与 Twilio 发信所需信息一一对应。更完整的参数与限制说明见 Twilio 文档 。

• account_sid

  • 填写说明：Twilio 控制台 Account Info 中的 Account SID。
  • 示例：ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• auth_token

  • 填写说明：与上述 Account 配对的 Auth Token，用于接口鉴权。请勿泄露或提交到公开仓库。

• from_phone_number

  • 填写说明：Twilio 侧用于发短信的号码，须为你在控制台已启用短信能力、且允许作为发件方的号码。
  • 示例：+12025550100

• to_phone_number

  • 填写说明：接收短信的手机号。
  • 示例：+8613800138000
  from_phone_number 与 to_phone_number 均须为 E.164（含 + 与国家码），例如：+8613800138000。否则可能被识别为非法手机号，导致发送失败。

• message

  • 填写说明：短信正文，纯文本。长度与拆分条数受运营商与 Twilio 规则限制，请以 Twilio 文档与实际报错为准。若配合 发送验证码 自定义行为流，通常将行为流入参中的验证码拼进正文。

发送邮件 - 阿里云

该节点封装了阿里云邮件推送的单条发信接口，用于向指定邮箱发送通知、验证码或营销类邮件。

若需在用户注册、登录、重置密码等场景下使用该节点发送邮件，需要先在 设置 → 验证码 中添加自定义配置，然后在该节点中选择自定义配置。具体教程见 用户事件 - 发送验证码。

1. 准备工作（在阿里云控制台完成）

在使用此节点前，请在阿里云完成以下准备：

• 开通服务：开通「邮件推送」服务。
• 配置发信域名与地址：在控制台配置发信域名（按指引完成 DNS 解析与所有权验证），并新建已通过验证的发信地址（例如 noreply@mail.yourdomain.com）。
• 获取凭证：在 RAM 中创建子账号，授予邮件推送调用权限（如 AliyunDirectMailFullAccess，或按业务做精细授权），并获取 AccessKey ID 与 AccessKey Secret。
• 邮件标签（按需）：若需按标签统计到达率、打开率等，请在控制台预先创建邮件标签；开启数据追踪时通常必须配合使用标签（见下文 click_trace 说明）。

2. 配置行为流节点（在 Zion 完成）

更详细的字段说明，见 阿里云邮件推送 API 文档 。

• access_key

  • 填写说明：填入 RAM 子账号的 AccessKey ID。
  • 示例：LTAI5t7*******

• access_secret

  • 填写说明：与 AccessKey ID 配对的 Secret，注意保密，勿泄露或提交到公开仓库。

• account_name（发信地址）

  • 填写说明：填写在阿里云控制台已验证通过的发信地址。
  • 示例：notice@mail.example.com

• address_type（地址类型）

  • 填写说明：填数字。建议填 1（使用已配置的发信地址发信，收件人看到的是你的正式发信邮箱）。填 0 时，收件人侧可能显示为系统随机生成的长地址（多用于特定防退信场景）。

• reply_to_address

  • 填写说明：是否使用控制台配置的默认回信地址，填 true 或 false。为 true 时，用户点击「回复」将发往控制台默认回信地址。

• to_address（收信人）

  • 填写说明：收信邮箱；多人时用英文逗号 , 分隔，单次最多 100 个地址。可通过魔法棒绑定前置节点输出动态填入。

• subject（邮件主题）

  • 填写说明：邮件标题，例如「欢迎注册」。注意阿里云对主题长度有限制（常见为不超过 100 个字符，以官方文档为准）。

• html_body 与 text_body（正文）

  • 填写说明：两者至少填其一。需要排版、图片、按钮等时，将 HTML 填入 html_body；纯文字通知可只填 text_body。

• from_alias（发件人昵称）

  • 填写说明：选填。例如 XX公司官方团队，收件人可能看到昵称与发信地址的组合展示；注意昵称长度等限制以控制台与官方文档为准（常见建议不超过约 15 个字符）。

• reply_address / reply_address_alias（自定义回信）

  • 填写说明：若希望本封邮件的回复发往指定邮箱（而非控制台默认），可填 reply_address；reply_address_alias 为对应显示昵称。与 reply_to_address 的配合关系以实现与官方文档为准。

• tag_name 与 click_trace（数据追踪）

  • 填写说明：需要统计打开、点击等行为时，可将 click_trace 设为 1。若开启追踪（click_trace 为 1），通常必须同时填写已在控制台创建好的 tag_name，否则可能调用失败，具体以接口报错与官方文档为准。

触发方式

• 定时触发：设置周期性执行（支持 Cron 表达式）。
• 数据库变更触发：详情。
• Webhook 触发：通过 Webhook 触发（需要配置回调体）。

使用教程

整体流程为：创建并配置行为流节点内容、配置触发器、配置权限、前端调用/自动化执行行为流。

注意事项

1. API 在行为流中被调用，请求超过60s会被直接终止。
2. 行为流有版本的概念：行为流编辑是不会自动化保存的，必须点击右上角的保存后进行后端部署才会更新线上应用使用的版本，webhook 和定时触发器执行的是最新部署后端的最新版本
3. 行为流支持的公式较少，具体内容见产品内部