Appearance
插件节点
插件节点用于调用某个插件中的一个具体工具，把工作流输入转换成插件请求，并将工具返回结果交给下游节点。插件是工具的集合；每个工具的参数、输出和调用方式都由插件定义，工作流不能在节点内任意改写这些接口字段。
适合使用插件节点的场景包括：
- 调用企业内部 API、第三方服务或 MCP 工具。
- 查询外部数据，或把工作流结果写入其他系统。
- 使用已经封装好的计算、检索、办公和多媒体能力。
如果只是向一个已知 URL 发起普通 HTTP 请求，并且不需要复用插件鉴权和工具协议，可以改用 HTTP 请求节点。
添加并选择工具
- 在画布底部单击 添加节点 → 插件。
- 在插件选择器中选择资源范围，再找到目标插件。
- 展开插件，核对工具名称、说明和参数。
- 单击具体工具右侧的 添加。系统会把工具的输入、输出和已发布版本写入节点。
一个插件可以包含多个工具。选择时必须核对工具说明和参数，不能只看插件名称。当前普通工作流选择器展示 资源库工具；应用模式下还可以出现当前应用可用的 应用内资源。实际可见范围同时受工作空间、资源状态和权限控制。
旧文档中的市场收藏、模拟集等入口不等同于当前节点选择器。本页只描述当前界面中可以直接使用的能力。
节点配置
选择工具后，右侧面板会显示工具名称、描述、运行模式、输入、输出和异常处理。以下示例调用表达式计算工具，输入固定表达式并返回数值结果。
输入
插件输入由工具协议生成，包含变量名、类型、是否必填和说明。
| 配置项 | 说明 |
|---|---|
| 变量名 | 来自工具定义，节点内不能改名。 |
| 类型 | 来自工具定义，节点内不能改类型。 |
| 固定值 | 直接填写字符串、数字、布尔值、对象或数组。复杂结构必须与工具声明一致。 |
| 引用变量 | 引用开始节点、上游节点或批处理变量。引用值的类型必须兼容当前参数。 |
| 必填参数 | 名称后带 *。未填写时，工作流校验会提示“参数值不可为空”。 |
对象和数组参数可以包含嵌套结构；运行时会继续解析其中的固定值和变量引用。不要把 API Key、OAuth Token 或其他密钥写入普通工作流变量，鉴权应在插件资源中配置。
输出与运行示例
输出名称、类型和层级同样来自工具协议，下游节点应按实际字段引用。部分插件会提供 查看示例，其中可能包含输入示例、输出结构、请求样例和响应样例；只有插件资源包含调试样例时才会显示该入口。
运行示例用于理解协议，不能替代试运行。第三方服务升级、权限差异或数据变化都可能让实际响应与示例不同。单次工具响应超过当前节点允许的大小时会失败，当前运行时上限为 2 MiB。
工具版本
节点保存 pluginID、apiID 和具体 pluginVersion。当前运行时要求使用确定的插件版本，不接受 latest、published 或 latest_published 之类的动态别名。
插件发布新版本后，已有节点不会自动获得业务兼容性。需要升级时应重新选择工具，并重新核对：
- 必填输入是否增加、删除或改名。
- 输入输出类型及嵌套结构是否变化。
- 鉴权、限流和副作用是否变化。
- 下游节点引用是否仍然有效。
切换到其他工具时，系统会重新生成输入输出，并把运行模式和异常处理恢复为默认值，原有参数映射需要重新检查。
单次运行
单次模式只调用一次工具。配置步骤如下：
- 填写所有必填输入。
- 为动态值选择类型兼容的上游变量。
- 根据工具耗时和幂等性配置超时、重试和异常处理。
- 单击节点上的运行按钮或执行工作流试运行。
- 在运行记录中核对真实请求结果，再将输出接入下游节点。
批处理运行
切换到 批处理 后，同一个工具会针对数组元素重复调用。当前节点已经内置批处理配置，不再要求像旧文档那样额外包一层批处理节点。
批处理输入
批处理至少需要一个数组输入。每个数组输入由“批处理变量名”和“上游数组值”组成，单次调用时可在工具参数中引用该批处理变量。
当配置多个数组时，系统按相同下标组合元素；实际迭代次数取所有输入数组长度的最小值。例如两个数组长度分别为 5 和 3，只执行 3 次，较长数组末尾的元素不会被处理。
每次迭代还会生成：
batch_index：从 0 开始的下标。iteration：从 1 开始的迭代序号。_batch_variables：本次迭代使用的批处理变量集合。
数量与并行配置
| 配置项 | 默认值 | 当前含义 |
|---|---|---|
| 批处理上限 | 100 | 限制本次最多处理的元素数量；运行时范围为 1～1000。 |
| 并行运行数量 | 10 | 保存为批处理配置和结果元数据；运行时允许范围为 1～100。 |
当前版本的插件执行器仍按列表顺序逐项调用工具，并行运行数量尚未用于并发调度。因此不要按该值推算吞吐量，也不能依靠调高数值缩短执行时间；应以真实试运行耗时为准。
批处理正常完成后会产生汇总结果，包括：
outputList/batch_results：每次工具调用的结果列表。batch_iterations/count：实际执行次数。_batch：批处理上限、并行配置和批处理变量等元数据。
当前执行器在某一项调用失败时会终止该插件节点，不保证继续执行剩余项，也不承诺返回可用的部分成功集合。需要容错时，应把整个插件节点的异常处理和业务幂等性一起设计。
异常处理
插件可能因为网络、限流、参数校验、授权失效、服务端错误或超时而失败。
| 配置项 | 当前行为 | 建议 |
|---|---|---|
| 整体执行超时 | 默认 180 秒；当前界面可填写 0.1～600 秒，运行时实际最小按 1 秒执行。 | 按插件正常耗时留出余量，不要用超长超时掩盖服务异常。 |
| 重试次数 | 0～3 次，默认为不重试。 | 仅对查询、计算等幂等工具启用。写入、发送、支付等工具可能产生重复副作用。 |
| 中断流程 | 插件失败后终止当前工作流。 | 结果不可缺失时使用。 |
| 返回设定内容 | 失败时返回预设内容，流程继续。 | 下游必须能够识别降级值，不能把降级结果当成真实数据。 |
| 执行异常流程 | 将失败交给异常分支。 | 适合告警、补偿和记录错误。批处理模式下当前界面不提供该分支选项。 |
启用非中断处理后，节点会补充 isSuccess 和 errorBody 等状态输出。下游应先判断成功状态，再读取业务字段。
授权与权限
OAuth、API Key 等授权由插件资源、工具提供方和当前调用身份共同决定。当前插件节点没有旧文档所述的“单独授权 / 共享授权”切换入口，因此不要在工作流节点里假设某种 OAuth 模式已经存在。
如果工具在选择器中不可见或调用返回无权限，应依次检查：
- 插件及目标工具是否已经发布，并且存在可用的具体版本。
- 插件是否进入当前工作空间的资源库或当前应用。
- 当前成员是否具有查看和调用权限。
- 插件所需授权是否已经在资源侧完成，令牌是否过期。
- 企业策略、网络出口或第三方服务是否限制调用。
试运行检查清单
- 已选择具体工具和具体插件版本。
- 所有带
*的输入均有值，引用变量类型一致。 - 对象、数组和文件类输入符合工具协议。
- 实际输出包含下游需要的字段，且大小未超限。
- 重试不会导致重复写入、重复发送或重复扣费。
- 超时和错误分支覆盖了授权失效、限流及服务不可用。
- 批处理使用数组输入，并核对最短数组长度、处理上限和实际执行次数。
常见问题
为什么插件输入输出不能修改？
这些字段来自插件工具的接口定义。需要变更字段时，应修改并发布插件工具，再回到工作流重新选择或升级版本。
为什么选择器中没有目标工具？
检查插件是否发布、当前空间是否有权限、资源是否进入当前资源库或应用，以及当前版本是否包含该工具。
为什么看不到“查看示例”？
只有插件资源提供调试样例时才显示。没有示例时仍可根据参数说明填写输入，并通过节点试运行查看真实输出。
为什么批处理配置了并行数量，执行仍然较慢？
当前插件执行器仍按顺序逐项调用，并行数量尚未用于实际并发调度。应以试运行耗时为准，并关注工具自身延迟和限流。
批处理为什么少处理了几项？
多个数组按下标组合，执行次数取最短数组长度，并且还受批处理上限约束。检查每个输入数组的实际长度和批处理上限。
旧文档中的模拟集和节点内 OAuth 授权模式在哪里？
当前插件节点页面没有这两个入口，因此本页不把它们作为现有功能。授权以插件资源的实际配置为准，调试使用当前系统提供的运行示例和试运行结果。