数据操作族：模板转换 / 代码执行 / 变量聚合 / 变量赋值 / 列表操作——数据五件套的选型与契约
基于 Dify 1.16.1 与 Hermes Agent 实战实测（2026-08/09）：代码节点模式库（C1-C11）+ E2 列表操作实验 + E4 变量赋值实验 + 模板转换实战
📖 摘要：数据五件套覆盖工作流里 80% 的数据处理：模板转换（格式变换）、代码执行（确定性计算）、变量聚合（跨分支合并）、变量赋值（会话状态累积）、列表操作（数组过滤排序）。本文给每件工具的选型判断 + 契约要点 + 实测坑：代码节点的正则双重转义（PII 脱敏静默失效的严重级事故）、模板转换的空值防护、变量赋值的 10 种操作与跨轮次记忆（实测）、列表操作对 object 数组的限制（实测）。
📌 本文要解决的核心痛点
- 数据处理该用哪个节点？模板 / 代码 / 聚合 / 赋值 / 列表，选错了绕大弯？
- 代码节点里正则写对了，跑起来却匹配不到——
\d和\\d的区别害死人？- 让会话记住用户说过的内容，为什么多轮对话里记忆丢了？
- 列表操作对对象数组报「不是数组类型」——这是 bug 还是限制？
- 本文给五件套的选型表 + 每件的契约要点 + 实测坑。
一、数据五件套是干什么的（先选型）
工作流里 80% 的数据处理是这五件事，各有各的工具：
| 工具 | 干什么 | 什么时候用 | 什么时候不用 |
|---|---|---|---|
| 模板转换 | 文本模板格式化（把变量拼进模板） | 输出格式固定、需要拼字段的文案 | 需要条件/循环逻辑（模板只支持简单引用） |
| 代码执行 | Python 沙箱确定性计算 | 清洗/解析/校验/组装/统计——任何「规则明确」的活 | 需要模型理解的活（那是 LLM 的） |
| 变量聚合 | 把多个分支/来源的变量合并 | 多分支汇聚、多源合并 | 单一路径（直接用上游引用） |
| 变量赋值 | 更新会话变量/循环状态 | 跨轮次记忆、循环累积、状态机 | 一次性计算（用代码节点） |
| 列表操作 | 数组过滤/排序/截断/取第一 | 数组的确定性操作 | 数组元素需要逐条加工（用迭代） |
选型口诀：格式变换 → 模板；确定性计算 → 代码；跨分支合并 → 聚合；跨轮次累积 → 赋值；数组操作 → 列表。
二、设计模式（每件的契约要点）
代码执行（最常用，坑最多）
| 契约 | 要点 |
|---|---|
| 入口 | 变量名 = 函数参数名（按名传参，def main(cd_input) 与
variables 声明一致） |
| 出口 | 每个 return 全键；输出字段类型声明与返回值一致 |
| 必填字段 | code_language: python3（写 python
报错）；outputs.<字段>.children 必须是空 dict
{}（写 [] 报错） |
| 沙箱限制 | 禁写文件（跨运行持久化用 KV/HTTP） |
模板转换
| 契约 | 要点 |
|---|---|
| 输出 | 固定 output 字段 |
| 防护 | 上游空值防护（空值除零/引用报错） |
| 语法 | 引用用 {{ 变量 }}（不是
{{#节点.字段#}}） |
变量聚合
| 契约 | 要点 |
|---|---|
| 结构 | variables 是嵌套数组
[[节点id, 字段], ...] |
| 时序 | 共享参数节点放 if-else 前；variables 只列互斥节点（避免聚合错值） |
变量赋值（E4 实测）
| 契约 | 要点 |
|---|---|
| version 必填 | version: "2" + items[]——不写按 v1 解析报
assigned_variable_selector Field required |
| 操作枚举 | 10 种：over-write / clear / append / extend / set / += / -= / *= / /= / remove-first / remove-last（源码确认） |
| 引用 | variable_selector: [conversation, 变量名]（会话变量）；循环状态同理 |
列表操作（E2 实测）
| 契约 | 要点 |
|---|---|
| 功能 | filter（过滤）+ order（排序）+ limit（截断）+ extract（取第 N 个） |
| 排序枚举 | 必须小写 asc / desc（大写
DESC 报 pydantic 枚举错） |
| 输出 | result（数组）+ first_record +
last_record（始终有） |
| 对象数组限制 | 1.16.1 对 object 数组输入报「not an array type」——只认 string/简单数组（实测） |
三、实测踩坑（五个高频坑）
坑 1：正则双重转义 → PII 脱敏静默失效（严重级）
现象：代码节点里正则 \d 写成
\\d，手机号脱敏完全不掩码，PII 完整泄露给 LLM，answer
直接回显完整手机号。
实测：2026-08-07 dify105_04_01 严重级实证——code 里
\\d 被 Python re
当「字面反斜杠+d」匹配不到数字，脱敏/校验/解析静默失效。
根治：code 里写单反斜杠
\d（注意多层模板的转义叠加）；生成后必须实测
re.findall(pattern, '13812345678') 验证匹配。
坑 2：模板转换空值除零
现象：模板引用上游空值，运行报除零/引用错误。
根治：模板引用前判空（条件分支分流），或 code 节点预处理（空值给默认）。
坑 3：变量赋值忘 version → 直接报错
现象：assigner 用 items 格式但不写
version: "2"，运行报
assigned_variable_selector Field required。
根治：assigner 显式 version: "2"（E4
实测）。
坑 4：列表操作对象数组不识别
现象：code 输出 array[object]（children
已声明子字段）→ list-operator 报
Variable [...] is not an array type。
实测：1.16.1 list-operator 不识别 object 数组为数组（只认 string/简单数组）——对象数组先 code 转 string 数组再过滤，或换 code/迭代实现（E2 实测）。
坑 5：聚合错值（共享参数节点位置错）
现象：mock/real 双分支共享参数节点放 if-else 后，聚合取到未执行分支的错值。
根治：共享参数放分流前；variables 只列互斥节点（实测教训）。
四、节点级验证清单
| 验证点 | 怎么验 | 取证 |
|---|---|---|
| 代码正确性 | 本地 exec 自测（同输入同输出） | python 直接跑函数 |
| 输出契约 | 类型声明 vs return 值核对 | 节点输出 |
| 确定性 | 同输入多次运行字节级一致 | 多次触发比对 |
| 跨轮次记忆 | 多轮对话（conversation_id 延续）验证累积 | 会话变量读回（实测 3 轮累积） |
| 列表操作 | 过滤/排序/截断各一条用例 | 输出数组比对 |
五、案例：数据清洗管线（CSV/JSON/文本三形态）
| 环节 | 工具 | 做法 |
|---|---|---|
| 输入解析 | 代码 | 自动检测分隔符（Tab/逗号）解析 CSV |
| 清洗 | 代码 | 去重/标准化/异常兜底（按 C1-C11 模式） |
| 格式化 | 模板转换 | 拼接成下游要的文本格式 |
| 多源合并 | 变量聚合 | 双源数据交错合并（各取前 5 zip） |
| 状态累积 | 变量赋值 | 多轮会话记录 append 到会话变量 |
核心结论：五件套选型对了，数据处理就是确定性链路（无 LLM 参与，字节级可复现）；选型错了（该用代码的用模板、该用赋值的用代码），就会踩进上面的坑。
下一篇预告：《外部交互族：HTTP + 工具调用 + Agent 节点 + 外部数据源》——与外部世界打交道的四种方式。Agent 节点 vs LLM 的实测成本对比（prompt 18 倍开销）、工具缓存与重建、外部数据源的三层能力。
- Dify 节点全景图：20 个节点、7 个功能族、3 个通用设计问题
- 内容生成族：LLM 节点怎么设计才稳定——六类 17 条自查清单 + 4 条进阶经验
- 知识接入族：知识检索节点——RAG 质量的三道闸门（分段 / 检索配置 / 清洗）
- 决策路由族：问题分类 + 条件分支——工作流的骨架是分流，分流只能在分类节点出边完成
- 数据操作族：模板转换 / 代码执行 / 变量聚合 / 变量赋值 / 列表操作——数据五件套的选型与契约
- 外部交互族：HTTP / 工具 / Agent 节点 / 外部数据源——与外部世界打交道的四种方式
- 流程编排族：迭代 / 循环 / 定时触发 / 子工作流 / 人工输入——复杂流程组织五件套
- 输入处理族：参数提取 + 文档提取器——非结构化输入结构化的两种方式
- 节点级验证方法论：每个节点怎么验——三层排查 + 验证清单总表
