代码节点

代码节点在隔离的执行环境中运行自定义 Python 或 JavaScript，适合完成字段转换、数值计算、条件校验、数组整理和轻量数据清洗。它通常放在已有节点之间，用来补足内置节点无法直接表达的小段确定性逻辑。

代码通过 params 读取节点输入，main 函数直接返回一个对象。返回对象中已在“输出”区域声明的字段，才能被下游节点稳定引用。默认模板中的 ret 只是局部变量名，不需要再包装成 { ret: ... }。

适用边界

代码节点适合无状态、执行时间短、输入输出明确的计算。调用外部接口应优先使用 HTTP 请求或插件节点；长耗时任务应使用异步任务节点；可复用的完整业务过程应拆成子工作流。

配置步骤

1. 在“输入”中定义参数名、数据类型和值。值既可以是固定值，也可以引用上游节点输出。
2. 选择 Python 或 JavaScript，并以当前语言的默认 main 函数签名为基础编写代码。
3. 在“输出”中逐项声明返回字段的名称、类型和嵌套结构。
4. 配置超时、重试次数和异常处理方式。
5. 保存后使用节点属性面板顶部的“测试节点”验证，再进行整条工作流试运行。

输入

每个输入项由变量名、类型和值三部分组成。代码中通过 params.<变量名> 或索引方式访问，例如 JavaScript 的 params.orderList、Python 的 params["orderList"]。

• 变量名必须以字母或下划线开头，后续可使用字母、数字、下划线和 $；不能使用界面限制的保留字。
• 引用上游变量时，应确认来源节点一定执行且返回类型匹配。
• 对可能为空或缺失的输入，应在代码中显式给出默认值或抛出可读异常。
• 文件等复杂输入可以传入节点，但当前输出区域不提供文件、图片、音视频、文档、压缩包等文件类输出类型。

语言与代码

当前可选语言为 JavaScript 和 Python。切换语言会改变默认模板和执行方式，应同步检查函数签名、参数读取、空值判断和返回语法，不能只替换局部语法。

JavaScript 示例：

async function main({ params }) {
  const quantity = Number(params.quantity ?? 0);
  const unitPrice = Number(params.unitPrice ?? 0);

  if (!Number.isFinite(quantity) || !Number.isFinite(unitPrice)) {
    throw new Error("quantity 和 unitPrice 必须是有效数字");
  }

  return {
    total: quantity * unitPrice,
    valid: quantity > 0 && unitPrice >= 0,
  };
}

Python 示例：

async def main(args: Args) -> Output:
    params = args.params
    quantity = float(params.get("quantity") or 0)
    unit_price = float(params.get("unitPrice") or 0)

    ret: Output = {
        "total": quantity * unit_price,
        "valid": quantity > 0 and unit_price >= 0,
    }
    return ret

“在 IDE 中编辑”会打开大尺寸代码编辑区，适合查看完整脚本和切换语言。修改完成后关闭 IDE，代码会回到节点配置中继续使用。

当前测试入口

IDE 顶部目前虽然显示“测试代码”，但当前版本尚未接入可用的测试动作。请使用节点属性面板顶部的“测试节点”，不要沿用旧文档中通过 IDE 测试代码并比较“原始输出/最终输出”的操作方式。

输出

输出区域相当于节点对下游公开的数据契约。当前可声明字符串、整数、数字、布尔、时间、对象、列表，以及这些基础类型或对象的数组。对象可以继续添加子项。

输出定义必须与 main 直接返回对象的真实结构一致：

检查项	正确做法	常见错误
字段名称	返回字段与输出变量同名	代码返回 totalPrice，输出却声明 total
数据类型	实际值与声明类型一致	把数字字符串声明为 Number
嵌套结构	Object 的子项层级一致	输出声明 user.name，代码返回扁平的 name
返回层级	直接返回结果对象	返回 { ret: { ... } }，额外增加一层
可序列化性	返回普通对象、数组和基础值	返回函数、循环引用或运行时对象

测试与联调

选中代码节点后，单击属性面板顶部的“测试节点”。测试时重点核对：

• 输入区显示的固定值和上游引用是否符合预期；
• 正常输入是否得到与输出声明一致的字段、类型和层级；
• 空值、缺失字段、非法格式和边界值是否有明确处理；
• 异常时是否按所选策略中断、返回设定内容或进入异常分支；
• 日志中是否出现超时、输出过大、权限限制或序列化失败。

节点测试通过后，再进行整条工作流试运行，确认上游引用和下游取值能够正确衔接。测试面板长时间无结果时，应停止本次运行并查看日志，不要把持续加载状态当作执行成功。

异常处理

当前界面默认整体执行超时为 30 秒，可配置范围为 0.1～60 秒；重试次数最多为 1 次。异常处理方式包括：

• 中断流程：代码异常后立即终止当前执行链路；适合关键计算。
• 返回设定内容：返回预先配置的 JSON，使下游继续执行；JSON 必须合法，并与输出定义兼容。
• 执行异常流程：从节点的异常分支继续处理；适合告警、补偿或人工介入。

启用相应异常处理后，节点会提供只读状态输出 isSuccess 和 errorBody；errorBody 包含 errorMessage、errorCode 等错误信息。涉及写入、扣减、发送通知等副作用时不要盲目重试，否则可能造成重复执行。

执行环境与安全限制

当前代码运行在临时隔离环境中，而不是完整的服务器开发环境：

• 默认禁止访问外部网络，不应在代码中直接使用 fetch、requests、http 等方式调用外部服务。
• 默认禁止创建子进程、读取进程环境变量或访问宿主机文件系统；工作目录随本次执行临时创建。
• 当前执行器默认代码大小上限为 128 KiB，输出与日志合计按 1 MiB 级别限制；超过限制可能被截断或终止。
• 不保证旧文档列出的固定运行时版本或第三方依赖包。只能使用当前执行环境实际提供的标准能力，不能在节点中任意安装依赖。
• 不要在代码中硬编码密码、Token、AK/SK、内网地址等敏感信息；敏感值应通过受控资源或变量传入。

常见问题

为什么代码运行成功，但下游找不到字段？

依次检查 main 是否直接返回对象、输出区域是否声明同名字段、字段类型和嵌套层级是否一致。特别注意不要返回 { ret: { ... } }。

为什么切换语言后代码无法执行？

Python 和 JavaScript 的默认函数签名、参数访问和返回语法不同。切换语言后应以新生成的模板为准，完整迁移逻辑，而不是只改文件语法或关键字。

为什么外部接口请求或文件访问失败？

代码沙箱默认关闭网络、子进程和宿主机文件系统访问。这类操作应改用 HTTP 请求、插件、数据库、知识库或文件处理等专用节点，让鉴权、超时和输出结构可配置、可审计。

哪些内容不应继续堆在代码节点里？

超长脚本、多个系统集成、长耗时处理和可复用的完整业务流程都不适合继续放在单个代码节点中。应拆成专用节点、插件、异步任务或子工作流，以便测试、复用和排错。