跳转至

Dictionary 键值对字典构建与结构化组装节点

节点核心功能 (What is it?)

Dictionary 节点允许创作者通过分别提供独立的键列表（Keys）与值列表（Values），快速在内存中动态组装并构建出一个标准的键值对字典（Dictionary）。它是将分散的数据整理为结构化命名字段、以便在工作流各处高效访问和传递的核心容器工具。

典型适用场景 (When would I use it?)

在以下情况下使用该节点：

  • 将多个分散的属性归集为具名的结构化键值对集合；
  • 为后续的 Agent、Prompt 模板或 API 节点生成标准的数据字典对象；
  • 动态组装各种组件的运行时配置参数表（Configuration Settings）；
  • 将数据组织为可以通过特定键名极速检索的键值映射表；
  • 将多个独立计算出的变量打包合并为单一的紧凑数据工件。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

  1. 在工作流画布中添加 Dictionary 节点。
  2. 设定或连接您的键列表（keys）与对应的值列表（values）。
  3. 节点将把两者按索引一一配对映射为字典。
  4. 在 dict 输出引脚处引出构建完毕的字典，供下游结构化算子消费。

参数输入插槽 (Parameters)

  • keys：用作字典键名的字符串列表（List of Strings）。
  • values：与各键名按索引顺位一一对应的数值列表（List of Values，支持字符串、数字、布尔值及嵌套列表/字典等多种数据类型）。

输出引脚 (Outputs)

  • dict：组装完成的完整原生键值对字典工件（dict）。

典型工作流示例 (Example)

假设您需要为一个用户个人资料构建一个运行配置字典：

  1. 添加一个 Dictionary 节点至画布。
  2. 将 keys 列表参数配置为： 
    ["name", "age", "premium_member", "interests"]
  3. 将 values 列表参数配置为： 
    ["Jane Smith", 32, true, ["hiking", "photography", "coding"]]
  4. 节点构建输出的标准字典工件为： 
    {
  "name": "Jane Smith",
  "age": 32,
  "premium_member": true,
  "interests": ["hiking", "photography", "coding"]
}
  5. 将此字典引脚直连至下游需要消费该用户属性的业务节点。

关键技术特性 (Important Notes)

  • 键名自动字符串化 (Key Stringification)：所有输入作为键名的元素均会被自动安全转换为标准字符串。
  • 长度不一致补位容错机制：若 keys 的长度大于 values，多出的键名将被自动赋予 None（空值）；多余的值若没有对应的键则会被安全忽略。
  • 无效键自动过滤：空字符串或 None 的无效键名会被自动忽略滤除（除非该键为唯一键且带有明确数值）。
  • 单值标量自动升级：如果接入的是单一标量而不是列表，节点会自动将其升维包裹为单元素列表进行配对。
  • 深层嵌套与全类型支持：值列表支持任意层级的嵌套对象（复杂字典、列表、布尔标量等）。

常见问题与排查 (Common Issues)

  • 键值列表长度不匹配：若键多值少，部分尾部字段的值将呈现为 null / None；请确保上游提供键和值的两个数组长度完全对应。
  • 复杂类型作为键名：字典键名严格遵循标准哈希字符串规范，若尝试将复杂字典或数组作为键，将被强制转为 str() 文本。