变量协议

Agent、AgentLite、文本生成、Workflow 和 ChatFlow 使用同一套变量配置模型。变量的数据类型负责约束运行时值的结构，控件类型负责决定表单怎样收集这个值；两者不再混用。

一、变量定义与运行时输入

变量定义出现在应用详情、应用编排或工作流节点配置中。例如，一个下拉选择变量的定义为：

{
    "variable_name": "tone",
    "display_name": "语气",
    "description": "选择回复的表达方式",
    "schema": "{\"type\":\"string\"}",
    "control_type": "select",
    "control_spec": {
        "options": ["正式", "简洁"],
        "placeholder": "请选择语气"
    },
    "default_value_state": "value",
    "default_value": "正式",
    "required": false,
    "writable": false,
    "encrypted": false
}

发送消息时不需要重复提交变量定义，只需在 input 中以 variable_name 为 key 传入本次运行的值：

{
    "input": {
        "tone": "简洁"
    }
}

input 的 value 必须符合变量 schema。display_name 只用于界面展示，不能代替 variable_name 作为请求字段名。

二、变量定义字段

字段	类型	说明
variable_name	string	变量名称，也是提示词引用和运行时 input 的 key
display_name	string	显示名称，用于输入表单展示
description	string	变量用途、格式或填写说明
schema	string / object	数据结构定义。应用详情接口中为 JSON String，解析后的结构见下文
control_type	string	控件类型，决定输入表单的展示与交互方式
control_spec	object	控件补充配置，如选项、占位文字、最大长度或复选框映射值
default_value_state	string	默认值状态：unset、value 或 masked
default_value	any	default_value_state=value 时返回或提交的具体默认值，类型必须符合 schema
required	bool	是否必填
writable	bool	是否允许通过 Workflow / ChatFlow 的变量赋值节点写入
encrypted	bool	是否按加密变量处理；导出时不会直接暴露明文

默认值状态

状态	说明
unset	未设置默认值，不携带 default_value
value	已设置明确默认值，同时携带 default_value
masked	已存在默认值，但当前响应不返回明文；更新变量时应保留该状态，不要把掩码字符串当作真实值提交

三、Schema 数据类型

解析 schema 后，顶层 type 支持以下值：

schema.type	补充字段	对应数据
string	可选 assist_type	String、Time 或 File
integer	—	Integer
float	—	Number
boolean	—	Boolean
object	properties	Object；每个属性可继续声明名称、说明、是否必填、Schema 和默认值
list	items	Array；items 定义每一项的数据结构

string 的 assist_type 用于区分辅助类型：不传表示普通 String，10000 表示 Time，1 表示通用 File。list.items 为 string 时，assist_type 的 1 至 11 分别表示通用文件、图片、文档、代码、PPT、Txt、Excel、音频、压缩包、视频和 SVG。

对象示例：

{
    "type": "object",
    "properties": [
        {
            "name": "department",
            "description": "科室名称",
            "required": true,
            "schema": {"type": "string"}
        }
    ]
}

数组示例：

{
    "type": "list",
    "items": {"type": "integer"}
}

四、控件类型

control_type	控件	常用数据类型
text_input	输入框	String、Time
textarea	文本域	String
number_input	数字输入框	Integer、Number，也可用于需要保留字符串格式的数字文本
radio	单选框	String
checkbox	复选框	Boolean，或通过映射值表示 String
checkbox_group	复选框组	Array<String>
switch	开关	Boolean
select	下拉选择器	String
multi_select	多选下拉选择器	Array<String>
date_picker	日期选择器	Time 或日期格式的 String
code_editor	代码编辑器	String、Object、非文件 Array
file_upload	上传框	File、Array<File>

control_spec 可包含以下字段：

字段	说明
options	单选、下拉、复选框组或多选下拉的候选值
max_length	输入框或文本域的最大字符数
placeholder	控件的占位提示
checked_value / unchecked_value	String 使用复选框时，选中和未选中分别提交的字符串

控件不会改变数据类型。例如 String 可以使用输入框、文本域或下拉选择器，但运行时值仍然是字符串；Array<String> 使用多选下拉后，运行时值仍然是字符串数组。

五、不同场景的配置差异

场景	配置重点
Agent / AgentLite / 文本生成提示词变量	通过 variable_name 在提示词中引用，通过消息接口 input 传值；是否可写仅对 Workflow / ChatFlow 生效
Workflow / ChatFlow 开始节点	可配置类型、控件、默认值、说明和是否必填；试运行及 ChatFlow 预览表单按控件渲染
Workflow / ChatFlow 全局变量	可配置类型、控件、默认值、是否可写和是否加密；不支持 File，且不设置是否必填
普通输入节点	与开始节点共用变量编辑方式，但不会保存开始节点专用的表单控件配置

WARNING

旧字段 key、name、data_type、max_length 和 option 已由统一变量字段替代。接入方读取应用详情时，应按本页结构处理变量；不要根据旧的数字类型枚举推断表单控件。