编辑器：节点配置与控件

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：chengflow-ui/src/features/editor/utils/controlUtils.tsx、chengflow-ui/src/features/editor/components/DynamicNodeInspector.tsx、chengflow/docs/i18n-node-convention-guide.md

选中一个节点，右侧属性面板就会显示它的配置。这些表单是生成的，不是手写的：后端把每个节点的输入发布为带 x-* 界面扩展的 JSON Schema，前端的字段控件注册表把每个字段转换成一个控件。在 Rust 里给节点加一个输入，对应的表单字段就会出现，前端无需任何改动。

理解这套映射机制，能让你预判面板长什么样，而不是被它的表现所困惑。

一个字段如何变成一个控件

注册表按固定顺序解析每个字段，在第一个命中处停止。顺序本身很关键：

1. 已连接状态——优先级最高。被外部连线喂入的字段会渲染成只读的「已连接」指示器，而不是可编辑的输入框。这就是为什么你连上线之后就无法再输入了：现在值来自那条连线。
2. 文件路径字段——渲染为路径选择器。
3. max_tokens——使用专门的控件。
4. 敏感字段——根据字段名推断。名称中含有 password、api_key/apikey、token/access_token 或 secret/private_key 的字段会自动变成掩码输入框。密码和 secret 完全掩码；API 密钥显示末 4 位，令牌显示末 6 位，这样你能区分两个密钥而不会暴露其中任何一个。
5. 显式指定的 x-control——节点作者声明的选择（见下表）。
6. 枚举 / 选项——带 enum 的字段变成下拉选择。
7. 类型匹配——兜底规则：string → 文本，number → 数字，boolean → 开关。

第 4 条在编写节点时值得记住：把字段命名为 api_key 可以免费获得掩码，而把一个非敏感字段命名为 token 会得到你并不想要的掩码。

可用控件

x-control 从一组固定的渲染器中选择：

改变行为的扩展

除了选择控件，x-* 扩展还会塑造面板本身：

可见性与分组

选项来源

x-options 提供静态列表。x-options-source / x-options-from 提供动态列表——特别是 ports，它会用节点自身的输入端口名生成选项，这就是「从我的输入中选一个」这类字段的实现方式。x-allow-custom 允许输入列表中没有的值。

模型选择

x-model-type、x-model-options、x-model-name-includes、x-model-name-excludes 和 x-provider-filter 用于收窄模型下拉——因此一个向量嵌入字段提供的是嵌入模型，而不是该供应商暴露的全部模型。

其他

x-rows（文本域高度）、x-step（数字步长）、x-dynamic-array（可重复的字段组）、x-list-modal / x-compact-list / x-list-max-visible（列表呈现方式）、x-auto-populate（从上下文自动填充）、x-fallback-control（首选控件不可用时的替代），以及 x-generic-kv 和 x-provider-presets（凭证表单）。

引用其他节点的值

不要写死数值，用 {{变量名}} 引用上游值。变量选择器——支持该功能的字段旁边那个选择器——会列出在图中那个位置实际可达的值，这比自己输入名字然后祈祷靠得住。

把值送进节点有两种方式，其区别很重要：

• 连线接到输入端口会直接传递数据。字段随之变为只读（第 1 条规则）。
• 文本字段内的 {{...}} 引用会把值插值到那段文本中。提示词就用这种方式，因为你需要在值周围包一整句话。

凭证

使用 credential-select 的字段会按供应商列出匹配的凭证库条目。选中一个条目后，节点保存的是一个引用。密钥在执行时于服务端获取，永远不会发送到浏览器，也不会进入模型的提示词。

已翻译的文案

标签、描述、占位符和选项文案来自以 x-i18n-key 为键的 i18n 语言包，从 /api/v1/i18n 加载。未翻译的条目会回落到 en-US，而不是渲染成空白——因此缺失的翻译只是降级，而不会导致界面损坏。

下一步

• 画布基础——组装图。
• 测试与调试——验证配置。
• 大语言模型与模型配置——填充模型下拉列表。