Weather 语法（Full 版本）
TradingFlow Weather 语言定义了工作流文件（.wt 文件）的完整结构和规范。Weather 文件本质上是一个 JSON 格式的超集，包含了工作流的所有信息：元数据、节点配置、连接关系等。
📌 版本说明： 本文档描述的是 Full 版本，包含前端展示所需的所有字段。Agent 生成和后端存储使用的是 Essential 版本，详见 Weather 语法对比。
.wt 文件结构
一个完整的 Weather 工作流文件由三个顶层字段组成：
{
"thumbnailUrl": "...",
"name": "...",
"nodes": [...],
"edges": [...]
}下面我们将详细解释每个字段的含义和作用。
工作流元数据
thumbnailUrl
工作流的缩略图，使用 Base64 编码的图片数据。这个缩略图会在工作流列表和预览界面中显示。
"thumbnailUrl": "data:image/png;base64,iVBORw0KGgoAAAANS..."格式说明：
数据 URI 格式：
data:image/png;base64,<encoded-data>支持的图片格式：PNG、JPEG、WebP
建议尺寸：800x600 像素
自动在用户保存工作流时生成
name
工作流的名称，用于标识和区分不同的工作流。
命名规则：
支持中英文字符
长度限制：1-100 字符
允许使用空格和特殊字符
默认名称为 "New Flow" 或 "新工作流"
节点定义（nodes）
nodes 数组包含了工作流中所有节点的完整定义。每个节点是一个独立的功能单元，负责特定的数据处理任务。
节点基础结构
position
节点在画布上的位置坐标，用于可视化渲染。
坐标原点在画布左上角
用户拖拽节点时会更新此值
保存时会记录节点的最终位置
id
节点的唯一标识符，用于在整个工作流中引用该节点。
命名规范：
格式：
<node_type>_<index>必须在工作流中唯一
创建节点时自动生成
用于边（edges）的连接引用
type
节点的类型标识，决定节点的功能和行为。
常见节点类型：
x_listener_node- X（Twitter）监听器节点ai_model_node- AI 模型节点buy_node- 买入交易节点sell_node- 卖出交易节点code_node- 代码执行节点binance_price_node- 币安价格节点dataset_output_node- 数据输出节点
width & height
节点在画布上的显示尺寸（像素）。
根据节点内容自动计算
不同类型节点有不同的默认尺寸
用户可以手动调整大小
selected
标识节点当前是否被选中，用于 UI 交互状态。
true- 节点被选中（高亮显示）false- 节点未选中（正常显示）
节点数据（data）
data 对象包含了节点的核心配置信息和业务逻辑。
title & description
节点的显示标题和描述信息。
title- 节点卡片顶部显示的名称description- 节点功能的简短说明用户可自定义编辑
collection
节点所属的功能分类。
分类类型：
input- 数据输入节点（如监听器、数据源）compute- 计算处理节点（如 AI 模型、代码执行）trade- 交易操作节点（如买入、卖出）core- 核心功能节点（如数据输出）
inputs
节点的输入参数配置数组，定义了节点接收的数据和参数。
输入字段说明：
id- 输入参数的标识符title- 参数显示名称type- 数据类型（paragraph,text,number,select,searchSelect,button,object,paramMatrix）inputType- 输入控件类型required- 是否必填placeholder- 输入提示文本handle- 连接句柄配置（颜色、样式）value- 参数当前值options- 可选项列表（用于下拉选择）
handle 颜色约定：
sky- 数据流类型（蓝色）emerald- 交易类型（绿色）amber- 配置类型（橙色）rose- 输出类型（粉色）
outputs
节点的输出定义数组，指定节点产生的数据输出。
输出字段说明：
id- 输出的标识符title- 输出显示名称type- 输出数据类型（text,number,object,array）handle- 连接句柄配置isDeleted- 标记输出是否已删除
edges
节点所参与的所有连接关系。这是一个包含完整边信息的数组，用于节点间的数据流管理。
注意：这里的 edges 数组是节点级别的引用，完整的边定义在顶层的 edges 字段中。
节点状态标志
isDeepEdit- 节点是否处于深度编辑模式isFlowExecuting- 工作流是否正在执行isStopping- 工作流是否正在停止signals- 节点运行时接收的信号数据
边定义（edges）
edges 数组定义了节点之间的连接关系，描述了数据在工作流中的流动路径。
边的基础结构
id
边的唯一标识符，用于引用和管理连接。
命名格式：
模式：
edge_<source_node>_<source_handle>_to_<target_node>_<target_handle>或简化格式：
edge-<timestamp>-<random>必须全局唯一
type & animated
边的显示样式配置。
type- 边的类型（default,step,smoothstep,straight）animated- 是否显示流动动画（true 表示数据正在传输）
source & target
边连接的源节点和目标节点。
source- 数据输出节点的 IDtarget- 数据接收节点的 ID必须引用存在的节点 ID
sourceHandle & targetHandle
边连接的具体输入输出端口。
sourceHandle- 源节点的输出参数 IDtargetHandle- 目标节点的输入参数 ID必须匹配节点定义中的 input/output ID
不包含
-handle后缀（这是 Weather 语言规范）
完整示例解读
让我们通过一个完整的工作流示例来理解 Weather 语法的实际应用：
工作流概述
这是一个基于 Trump 推文的自动交易策略：
X Listener 节点 - 监听 @realDonaldTrump 的推文
AI Model 节点 - 分析推文内容，判断是否有买入信号
Buy 节点 - 根据 AI 分析结果执行买入操作
Binance Price 节点 - 监控 BTC/USDT 价格
Code 节点 - 计算 5 倍买入价格作为卖出目标
Sell 节点 - 价格达到 5 倍时执行卖出
Dataset Output 节点 - 记录所有交易到 Google Sheets
数据流向
关键特性
多源输入：
Dataset Output 节点接收来自 Buy 和 Sell 节点的交易记录
通过两条独立的边实现数据汇聚
条件分支：
AI 分析结果决定是否触发买入
价格计算结果决定是否触发卖出
参数传递：
AI 输出直接连接到 Buy 节点的
buy_token输入Code 输出连接到 Sell 节点的
sell_token和amount_in_human_readable输入
语法验证规则
必填字段验证
所有节点必须包含以下字段：
id,type,position,data
所有边必须包含以下字段：
id,source,target,sourceHandle,targetHandle
引用完整性
边的
source和target必须引用存在的节点 IDsourceHandle必须存在于源节点的outputs中targetHandle必须存在于目标节点的inputs中
类型兼容性
边连接的输出类型和输入类型必须兼容
例如：
object类型输出可以连接到object类型输入
唯一性约束
节点 ID 必须全局唯一
边 ID 必须全局唯一
最佳实践
节点命名
使用有意义的 title 和 description，便于理解工作流逻辑：
参数配置
为必填参数设置合理的默认值和提示信息：
边的组织
使用描述性的边 ID，方便调试和维护：
状态管理
合理使用 animated 标志表示数据流动状态：
扩展与兼容性
Weather 语言设计为可扩展的格式：
向后兼容：
新增字段不会破坏旧版本的工作流
未知字段会被安全忽略
自定义扩展：
可以在
data对象中添加自定义字段节点开发者可以定义专有的配置参数
版本管理：
通过添加
version字段支持多版本格式平台会自动迁移旧版本工作流
常见问题
Q: 为什么句柄名称不包含 -handle 后缀？
A: 这是 Weather 语言的规范设计。在早期版本中使用了 -handle 后缀，但为了简化语法和提高可读性，新版本已经移除。前端会自动在需要时添加后缀。
Q: 如何处理节点的可选输入？
A: 将输入的 required 字段设置为 false，并提供合理的默认值或留空。
Q: 边的 type 字段有什么作用？
A: 决定边在画布上的渲染样式。default 是标准曲线，straight 是直线，step 是阶梯线。
Q: positionAbsolute 字段的用途？
A: 这是计算出的绝对位置，考虑了画布缩放和平移。通常由前端自动维护。
下一步： 查看 节点详情 了解每个节点类型的详细参数和用法。
Last updated