适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：
crates/cheng-nodes/src/nodes/builtin/utils
这些节点决定数据流向何处、以什么形状到达。utils/condition_router 是确定性分支 —— 简单模式是一条规则配一对真/假输出，高级模式是多规则 switch，每个分支一个输出端口。 只要规则能写下来，就优先用它而不是 LLM 分支。utils/to_items 把单个值展开成条目供下游逐条处理， utils/type_cast 在连接处修正类型不匹配，utils/smart_var 保存一个可在多处引用的具名值， utils/delay 则用来给有速率限制的服务放慢调用节奏。
条件路由 — utils/condition_router
根据字段条件进行路由分流:支持多种匹配运算符,点号嵌套路径,自动生成 Schema 提示以及增强的兜底元数据.
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
context |
object （端口） | — | null |
输入 Agent 上下文(可选). 连接端口，不是表单字段。 控件：code-editor |
response |
string | — | "" |
LLM 响应文本(JSON 格式). 控件：code-editor |
custom_data |
string | — | null |
自定义 JSON 数据. 控件：code-editor |
payload_source |
enum | — | response |
选择数据提取来源. 控件：select. 取值：response (从 response 字段解析 JSON), context (从完整 context 序列化为 JSON), custom (从 custom_data 字段取值) |
branch_fields |
array<object> | — | [] |
分流字段列表(点击 + 添加;每个条目自动生成对应的输出端口) |
strict_mode |
boolean | — | false |
JSON 解析失败时报错(false 则路由到兜底输出) |
generate_schema |
boolean | — | false |
启用自动生成的 JSON Schema 提示,并输出到 schema_hint 端口(可连接到上游 LLM 的 system_prompt). |
mode |
enum | — | advanced |
Simple(If:单规则,True/False)或 Advanced(Switch:多规则多输出). 控件：select. 取值：simple (If 模式：单条件，True / False 输出), advanced (Switch 模式：多规则多输出（默认，兼容旧行为）) |
match_policy |
enum | — | all |
First:首次匹配后停止;All:输出所有匹配的分支(默认). 控件：select. 取值：first (仅输出第一个命中的分支), all (所有命中的分支都输出（默认）) |
fallback_mode |
enum | — | fallback_output |
FallbackOutput:路由到 fallback_out(默认);None:跳过;Output0:路由到第一个分支端口. 控件：select. 取值：fallback_output (输出到 fallback_out 端口（默认）), none (不输出，下游自动跳过), output0 (输出到第一个分支端口) |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
branch_outputs |
array<any> （端口） | 分支输出列表,与 branch_fields 一一对应(匹配时为 Agent 上下文,未命中时为 null). 连接端口，不是表单字段。 |
fallback_out |
object | 兜底输出(在 Simple 模式下充当 ‘False’).当没有分支规则匹配时触发,包含诊断元数据. |
context_out |
object | 传统兜底输出(请使用 fallback_out).为保持向后兼容而镜像 fallback_out. |
schema_hint |
object （端口） | 自动生成的结构化输出提示(可连接到上游 LLM 节点的 system_prompt 端口). 连接端口，不是表单字段。 |
智能变量 — utils/smart_var
自动检测文本变量,动态生成端口,支持完整输出和选择性提取
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
template |
string | ✅ | — | 原始文本(支持 JSON,curl,YAML 等). 控件：textarea |
extract_mode |
enum | — | auto |
提取模式:auto=自动检测键名,manual=仅 {{var}} 语法. 控件：select. 取值：auto, manual |
output_vars |
array<string> | — | [] |
要包含在输出中的变量列表. 控件：multi-select. 选项来源：ports |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
full_text |
string | 变量替换后的完整文本 |
selected_vars |
object | 已选择的变量键值对 |
all_variables |
array<string> | 所有提取的变量名 |
preview_content |
string | 格式化后的预览内容 |
statistics |
object | 变量提取统计 |
转为项数组 — utils/to_items
将任何输入规范化为循环容器就绪的项数组
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
input |
any | — | — | 转换为循环项的数据 |
mode |
enum | — | auto |
如何转换输入. 控件：select. 取值：auto (Automatically detect input type.), array (Input is an array — pass through, normalizing each element.), single (Wrap any single value into a one-element array.), split_text (Split a string into text items.), refs (File / document / chunk reference passthrough — no content expansion.), object_values (Convert object key-value pairs into items.), range (Generate a numeric range as items.) |
chunkSize |
integer | — | 500 |
当 分割方式 = 块 时每个块的字符数. 控件：number |
maxItems |
integer | — | 0 |
发出的最大项数 (0 = 无限制). 控件：number |
rangeEnd |
integer | — | 0 |
范围结束 (不包含, 范围模式). 控件：number |
rangeStart |
integer | — | 0 |
范围开始 (包含, 范围模式). 控件：number |
rangeStep |
integer | — | 1 |
连续范围值之间的步长. 控件：number |
splitBy |
enum | — | paragraph |
文本分割策略 (分割文本模式). 控件：select. 取值：paragraph (Split on blank lines (two consecutive newlines).), line (Split on every newline.), sentence (Heuristic sentence splitting (punctuation-based).), chunk (Fixed character chunk size.) |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
items |
any | 循环就绪的项数组 |
count |
integer | 数组中的项数 |
mode_used |
string | 应用的转换模式 |
类型转换 — utils/type_cast
在常用端口类型之间转换,支持作为一等公民的 Agent 上下文
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
agent_context |
object （端口） | — | null |
在此连接 Agent 上下文类型对象. 连接端口，不是表单字段。 |
text |
string （端口） | — | null |
在此连接字符串/文本输出. 连接端口，不是表单字段。 |
json |
object （端口） | — | null |
在此连接对象输出. 连接端口，不是表单字段。 |
array |
array<any> （端口） | — | null |
在此连接数组输出. 连接端口，不是表单字段。 |
integer |
integer （端口） | — | null |
在此连接整数输出. 连接端口，不是表单字段。 |
number |
number （端口） | — | null |
在此连接数字输出. 连接端口，不是表单字段。 |
boolean |
boolean （端口） | — | null |
在此连接布尔值输出. 连接端口，不是表单字段。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
agent_context |
object （端口） | 转换后的 Agent 上下文. 连接端口，不是表单字段。 |
text |
string （端口） | 转换后的字符串. 连接端口，不是表单字段。 |
json |
object （端口） | 转换后的对象. 连接端口，不是表单字段。 |
array |
array<any> （端口） | 转换后的数组. 连接端口，不是表单字段。 |
number |
number （端口） | 转换后的数字. 连接端口，不是表单字段。 |
integer |
integer （端口） | 转换后的整数. 连接端口，不是表单字段。 |
boolean |
boolean （端口） | 转换后的布尔值. 连接端口，不是表单字段。 |
source_type |
string | 所选输入源类型 |
延迟 — utils/delay
在工作流中添加延迟,用于测试暂停和停止功能
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
delay_type |
enum | — | fixed |
固定,随机范围,直到时间戳,直到一天中某个时间,固定加抖动,或指数退避. 控件：select. 取值：fixed (固定时长延迟), random_range (随机区间延迟), until_timestamp (延迟到绝对时间戳), until_time_of_day (延迟到某个本地时间), fixed_with_jitter (固定延迟并附加抖动), exponential_backoff (指数退避) |
delay_value |
integer | — | 5 |
延迟时间值(配合单位使用). 控件：number |
delay_unit |
enum | — | seconds |
延迟时间单位:毫秒或秒. 控件：select. 取值：milliseconds (毫秒), seconds (秒), minutes (分钟), hours (小时) |
max_delay_value |
integer | — | null |
随机范围延迟的上限. 控件：number |
target_timestamp |
string | — | null |
RFC3339 时间戳,或带有时区的本地日期时间表达. 控件：datetime-local |
time_of_day |
string | — | null |
本地目标时间,格式为 HH:MM 或 HH:MM:SS |
timezone |
string | — | UTC |
本地日期时间表达所使用的 IANA 时区;默认为 UTC. |
jitter_percent |
integer | — | null |
固定加抖动模式的最大正负抖动百分比. 控件：number |
attempt |
integer | — | null |
指数退避模式的零基重试次数. 控件：number |
initial_delay_value |
integer | — | null |
指数退避模式的初始延迟值. 控件：number |
max_backoff_value |
integer | — | null |
指数退避模式的最大延迟值. 控件：number |
multiplier |
number | — | null |
指数退避模式的增长倍数. 控件：number |
log_message |
string | — | null |
日志消息:延迟前后输出 |
passthrough |
any | — | null |
透传数据:原样转发到输出端口 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
completed |
boolean | 延迟是否正常完成 |
actual_delay_ms |
integer | 实际延迟时长(毫秒) |
passthrough |
any | 从输入透传的数据 |
log_message |
string | 从输入透传的日志信息 |
context |
object | 组合了日志消息和透传数据的 Agent 上下文 |
info |
object | 详细的延迟执行信息 |
下一步
© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
暂无评论内容