流程节点

FengyuFlow 画布是一个数据流编辑器：每个节点对应一次工具调用，每条连线表示「这个节点在那个节点之后运行，并且可以读取它的输出」。本页说明线上流动的是什么、以及如何单独调试一个节点。节点声明协议的开发者侧文档见插件清单参考中的流程节点章节。

节点与连线

• 开始节点 —— 流程运行时输入的可视化编辑器。每个声明的输入渲染为一行带类型色标的字段；在画布上引用它写作 {{inputs.email}}。
• 动作节点 —— 每个节点对应一个工具。RPC JSON Schema 提供字段、类型、必填性与默认值； 可选的 flowNodes 增量只添加控件、标签、占位符、示例与帮助。
• 条件节点（IF） —— 内置的 flow_if 控制节点。它比较两个值并暴露两个输出端口：满足 / 不满足。动作节点只有一个输出端口；条件节点是唯一的例外，因为连线从哪个端口出发就是分支语义本身。

连线即依赖：上游全部完成后节点才会运行（就绪的步骤并发执行）。连线是整节点级的——你不连接单个字段；字段既可绑定上游节点的实际输入，也可绑定 Worker 结果。

数据怎么进来：引用

每个输入有三种来源状态：

状态	作用
✏️ 手动	直接在控件里填字面值
🔗 引用	从变量树选择：工作流输入、上游实际输入或上游结果字段，按期望类型过滤
ƒ 表达式	含 {{ }} 占位符的原始文本——面向专家的字符串模板

引用会直接序列化：{{node.<id>.input.<path>}} 读取模板解析后上游工具真正收到的参数，{{node.<id>.result.<path>}} 读取 Worker 结果，{{inputs.<name>}} 读取运行时输入。路径支持 result.files[0] 这样的数组下标。选择器明确分开输入与输出，未知引用会在保存前标出。

看节点输出了什么

任何列出输出的地方都提供三级降级，并诚实标注来源：

1. 节点声明 —— 插件声明的输出 schema（字段名与类型）。
2. 示例值 —— 声明附带的示例。
3. 上次运行 —— 该节点最近一次执行的真实输出（写入图时截断到 16 KB）。

悬停节点的输出端口可看声明契约；打开节点可浏览完整输出树、复制 {{node.…}} 引用路径、或固定上次运行。

分支条件与跳过

从 IF 节点的满足或不满足端口连线，编译时会在目标步骤上生成 runWhen 条件。运行时：

• IF 节点求值（contains、gt、is_empty 等——两个操作数都可以绑定上游引用），输出 {"branch":"true|false"}。
• 分支未命中的步骤记为已跳过——节点上显示灰色徽标，不产生结果，也不调用工具。
• 依赖全部被跳过的步骤会连带跳过（死分支级联）；只要有一个活跃依赖，步骤照常运行。

AI 生成节点（LLM）

内置的 AI 生成 节点把一次非交互式模型补全作为普通流程步骤执行，使用 AI 设置中当前启用的提供商：

• 提示词 —— 完整指令；用 🔗 像其它输入一样引用上游输出（例如把 Excel 汇总交给模型改写成邮件正文）。
• 系统提示词 / 温度（高级）—— 可选的角色设定（「你是邮件文案助手」）与 0–2 的采样温度；留空回退到全局 AI 设置。
• 输出 Schema（高级）—— JSON Schema 对象。填写后模型按 Schema 返回 JSON，在**结构化数据（data）**输出下可逐字段引用（{{node.x.result.data.sentiment}}）。若回复解析失败或缺少必填字段，会把确切的错误回填进提示词自动重试一次。**原文（text）**输出始终保留模型原始回复——结构化可能失败，回答永不丢失。可以把 data 字段接到 IF 节点上做分支。

节点每次调用都会新建独立的模型客户端，因此在并行步骤中、甚至在聊天中经 run_current_flow 执行的流程里都能正常工作，不会与当前会话争抢。

单步调试

节点检查器输出区的只运行此节点只执行当前节点：

• 上游结果引用从各节点的固定结果或上次运行取值；输入引用从该节点配置并解析后的实际参数取值——不重新执行任何祖先节点。
• 工作流输入取流程设置中的当前值绑定。
• 结果落位与完整运行一致：节点徽标、执行面板、运行历史、以及该节点的上次运行预览。

如果某个上游节点既没有固定也没有上次运行数据，会明确提示先运行或固定哪个节点。配合回退（完整运行后从第 N 步重跑）与固定，你可以在整条链路未跑通的情况下迭代单个节点。

执行前检查

宿主在任何节点执行之前检查工具可用性、引用路径、重试策略，以及声明类型明确不兼容的 整值绑定（例如把数组传入字符串参数）。错误会指出步骤和输入路径。文本插值仍然生成 字符串；类型未知或存在交集时，仍需运行时校验。 固定结果也会在首个节点执行之前检查失败信封和声明的输出 Schema，避免后续节点的无效 固定值导致前面的节点先执行。这些检查不能证明外部服务可用，也不能替代运行时输入、 输出校验。

固定结果

固定（pin）把节点的上次运行冻结为其 authored 结果：引擎原样返回固定值、不再调用工具——适合基于已知数据迭代下游。被固定的节点带 📌 角标；发布带固定的流程是允许的，但在解除固定之前固定值始终生效。

失败重试

只有工具可安全重试时，节点检查器才显示失败重试。可设置 1–5 次总尝试次数与初始等待时间； 每次失败后等待时间加倍，最长 30 秒。审批在整个尝试序列之前只发生一次，运行历史只记录一个 最终步骤结果。 重试期间，画布与执行面板会显示即将进行的尝试、等待时间和最近一次错误；重新打开已持久化 的运行时，同一条尝试时间线仍然可见。

只读工具自动视为可安全重试。写入或外部插件工具必须显式声明 idempotent: true，表示重复 完全相同的调用不会造成重复写入、消息、扣费或其它副作用。没有这一保证的工具不能配置重试； 即使绕过界面提交不安全策略，后端也会在首次调用前拒绝。

从外部启动已发布流程

运行对话框可以把已发布流程转换成持久化的环回 Webhook。对话框中的当前值会成为默认输入， 每个传入 JSON 对象的同名字段会覆盖它们。一次性密钥和可选事件 ID 协议见 工作流 Webhook。含文件选择器或自动共享目录输入的流程不能 创建 Webhook，因为这些授权属于会话而非持久化资源。

草稿与重启恢复

未保存的画布编辑会在短暂防抖后写入当前工作流专属的本地草稿；重新打开路由时可选择恢复， 保存或明确丢弃后会清除。运行期间若后端重启，历史会进入需要恢复检查点，而不是伪装成普通 失败。恢复前始终重新审阅计划，并复用稳定的逐步骤调用 ID，让具备幂等实现的 Worker 去重状态 不确定的调用。若剩余步骤含会话级文件授权，重启后不能恢复；需要新建运行并重新选择文件。