Weather 语法版本对比

本文档清晰地对比 Weather 语法的两个版本，帮助你理解哪些字段用于前端展示，哪些字段用于后端存储。

版本概述

TradingFlow Weather 语法有两个版本：

🖥️ Full 版本（完整版）

用途： 前端展示和用户交互
包含： 所有字段，包括 UI 状态、样式配置、运行时数据
文件大小： 较大，包含冗余信息
使用场景： 前端 ReactFlow 渲染、用户编辑、实时状态展示

💾 Essential 版本（核心版）

用途： Agent 生成和后端存储
包含： 仅核心业务逻辑字段
文件大小： 精简，去除前端特定字段
使用场景： 数据库存储、API 传输、Agent 生成工作流

字段对比总览

📊 对比统计

层级

Full 版本字段数

Essential 版本字段数

保留率

顶层

100%

节点基础

8-10

40%

节点 data

55%

输入/输出

9-10

8-9

90%

边

71%

详细字段对比

1️⃣ 顶层结构

字段

Full

Essential

说明

thumbnailUrl

✅

工作流缩略图（可选）

name

✅

工作流名称

nodes

✅

节点数组

edges

✅

边数组

结论： 顶层字段全部保留，无变化。

2️⃣ 节点基础字段

字段

Full

Essential

类型

说明

position

✅

核心

节点位置坐标

id

✅

核心

节点唯一标识

type

✅

核心

节点类型

data

✅

核心

节点数据对象

className

✅

❌

前端

CSS 类名

width

✅

❌

前端

节点宽度

height

✅

❌

前端

节点高度

selected

✅

❌

前端

选中状态

positionAbsolute

✅

❌

前端

绝对位置（计算值）

dragging

✅

❌

前端

拖拽状态

保留字段： position, id, type, data

去除字段： className, width, height, selected, positionAbsolute, dragging

原因： 前端会根据节点内容自动计算尺寸和管理交互状态，无需存储。

3️⃣ 节点 data 对象

字段

Full

Essential

类型

说明

title

✅

核心

节点标题

description

✅

核心

节点描述

collection

✅

核心

节点分类

inputs

✅

核心

输入参数数组

outputs

✅

核心

输出定义数组

id

✅

核心

节点 ID（冗余）

edges

✅

❌

冗余

节点相关的边（顶层已有）

menuItems

✅

❌

前端

右键菜单项

isDeepEdit

✅

❌

前端

深度编辑模式

isFlowExecuting

✅

❌

前端

执行状态

isStopping

✅

❌

前端

停止状态

signals

✅

❌

运行时

运行时信号数据

保留字段： title, description, collection, inputs, outputs, id

去除字段： edges, menuItems, isDeepEdit, isFlowExecuting, isStopping, signals

原因：

edges - 顶层已有完整定义，节点内的是冗余引用
menuItems - 前端根据节点类型动态生成
isDeepEdit, isFlowExecuting, isStopping - UI 状态，不属于工作流定义
signals - 运行时数据，不应持久化

4️⃣ 输入/输出字段

字段

Full

Essential

类型

说明

id

✅

核心

参数标识符

title

✅

核心

参数显示名

type

✅

核心

数据类型

inputType

✅

核心

输入控件类型

required

✅

核心

是否必填

placeholder

✅

核心

提示文本

handle

✅

核心

句柄配置

value

✅

核心

参数值

options

✅

核心

选项列表

min

✅

验证

最小值（可选）

max

✅

验证

最大值（可选）

description

✅

说明

详细描述（输出）

isDeleted

✅

❌

前端

删除标记

disabled

✅

❌

前端

禁用状态

保留字段： id, title, type, inputType, required, placeholder, handle, value, options, min, max, description

去除字段： isDeleted, disabled

原因： isDeleted 和 disabled 是前端临时状态，真正删除的字段应该直接从数组中移除。

5️⃣ 边字段

字段

Full

Essential

类型

说明

id

✅

核心

边唯一标识

source

✅

核心

源节点 ID

target

✅

核心

目标节点 ID

sourceHandle

✅

核心

源句柄

targetHandle

✅

核心

目标句柄

type

✅

❌

前端

边类型（样式）

animated

✅

❌

前端

动画效果

保留字段： id, source, target, sourceHandle, targetHandle

去除字段： type, animated

原因： type 和 animated 仅控制前端渲染样式和动画，不影响数据流逻辑。

实际对比示例

Full 版本示例（节点）

{
    "position": {"x": 100, "y": 100},
    "positionAbsolute": {"x": 100, "y": 100},
    "id": "x_listener_node_1",
    "type": "x_listener_node",
    "className": "",
    "data": {
        "title": "Trump Twitter Listener",
        "description": "Monitors tweets",
        "collection": "input",
        "inputs": [...],
        "outputs": [...],
        "id": "x_listener_node_1",
        "edges": [...],
        "menuItems": [
            {"key": "delete", "label": "Delete", "danger": true}
        ],
        "isDeepEdit": true,
        "isFlowExecuting": false,
        "isStopping": false,
        "signals": []
    },
    "width": 343,
    "height": 464,
    "selected": false,
    "dragging": false
}

Essential 版本示例（节点）

{
    "position": {"x": 100, "y": 100},
    "id": "x_listener_node_1",
    "type": "x_listener_node",
    "data": {
        "title": "Trump Twitter Listener",
        "description": "Monitors tweets",
        "collection": "input",
        "inputs": [...],
        "outputs": [...]
    }
}

减少： 从 ~20 个字段减少到 ~7 个字段，文件大小减少约 60%。

Full 版本示例（边）

{
    "id": "edge_ai_model_node_1_ai_response_to_buy_node_1_buy_token",
    "type": "default",
    "animated": true,
    "source": "ai_model_node_1",
    "target": "buy_node_1",
    "sourceHandle": "ai_response",
    "targetHandle": "buy_token"
}

Essential 版本示例（边）

{
    "id": "edge_ai_model_node_1_ai_response_to_buy_node_1_buy_token",
    "source": "ai_model_node_1",
    "target": "buy_node_1",
    "sourceHandle": "ai_response",
    "targetHandle": "buy_token"
}

减少： 从 7 个字段减少到 5 个字段。

转换规则

Full → Essential 转换

后端在存储前会自动执行以下清理：

function toEssential(fullFlow: FullFlow): EssentialFlow {
    return {
        thumbnailUrl: fullFlow.thumbnailUrl,
        name: fullFlow.name,
        nodes: fullFlow.nodes.map(node => ({
            position: node.position,
            id: node.id,
            type: node.type,
            data: {
                title: node.data.title,
                description: node.data.description,
                collection: node.data.collection,
                inputs: node.data.inputs.map(cleanInput),
                outputs: node.data.outputs.map(cleanOutput)
            }
        })),
        edges: fullFlow.edges.map(edge => ({
            id: edge.id,
            source: edge.source,
            target: edge.target,
            sourceHandle: edge.sourceHandle,
            targetHandle: edge.targetHandle
        }))
    };
}

Essential → Full 转换

前端加载后会自动补充前端字段：

function toFull(essentialFlow: EssentialFlow): FullFlow {
    return {
        ...essentialFlow,
        nodes: essentialFlow.nodes.map(node => ({
            ...node,
            className: "",
            width: calculateWidth(node),
            height: calculateHeight(node),
            selected: false,
            data: {
                ...node.data,
                id: node.id,
                edges: [], // 从顶层 edges 填充
                menuItems: getDefaultMenuItems(),
                isDeepEdit: false,
                isFlowExecuting: false,
                isStopping: false,
                signals: []
            }
        })),
        edges: essentialFlow.edges.map(edge => ({
            ...edge,
            type: "default",
            animated: false
        }))
    };
}

特殊说明

1. edges 字段的特殊处理

节点内的 data.edges 数组：

Full 版本：包含该节点相关的所有边的完整信息（冗余）
Essential 版本：完全移除，因为顶层 edges 数组已包含所有信息

前端会根据顶层 edges 自动填充每个节点的 data.edges。

2. 可选字段的处理

某些字段在 Essential 版本中是可选的：

thumbnailUrl - 如果没有则前端自动生成
placeholder - 如果没有则显示默认提示
options - 如果是空数组可以省略

3. 向后兼容

如果 Essential 版本中包含了前端字段（如 width、selected），前端会：

优先使用 Essential 版本中的值
如果缺失则使用默认值或计算值

最佳实践

Agent 生成时

✅ 推荐：

{
    "name": "Trump Trading Strategy",
    "nodes": [
        {
            "position": {"x": 100, "y": 100},
            "id": "x_listener_node_1",
            "type": "x_listener_node",
            "data": {
                "title": "Twitter Listener",
                "description": "Monitors tweets",
                "collection": "input",
                "inputs": [...],
                "outputs": [...]
            }
        }
    ],
    "edges": [...]
}

❌ 避免：

{
    "name": "Trump Trading Strategy",
    "nodes": [
        {
            "position": {"x": 100, "y": 100},
            "id": "x_listener_node_1",
            "type": "x_listener_node",
            "width": 343,  // ❌ 不需要
            "selected": false,  // ❌ 不需要
            "data": {
                "title": "Twitter Listener",
                "isDeepEdit": true,  // ❌ 不需要
                "signals": []  // ❌ 不需要
            }
        }
    ]
}

后端存储时

始终存储 Essential 版本
在 API 响应时保持 Essential 格式
让前端负责补充 UI 相关字段

前端处理时

从后端加载 Essential 版本
自动转换为 Full 版本用于渲染
保存时转换回 Essential 版本

文件大小对比

以一个包含 7 个节点、7 条边的工作流为例：

版本

文件大小

压缩后

节省

Full

~25 KB

~8 KB

Essential

~10 KB

~4 KB

60%

结论： Essential 版本可以显著减少存储空间和网络传输开销。

快速参考表

需要去除的字段清单

节点级别：

❌ className
❌ width
❌ height
❌ selected
❌ positionAbsolute
❌ dragging

data 级别：

❌ data.edges
❌ data.menuItems
❌ data.isDeepEdit
❌ data.isFlowExecuting
❌ data.isStopping
❌ data.signals

输入/输出级别：

❌ isDeleted
❌ disabled

边级别：

❌ type
❌ animated

相关文档：

Weather 语法（Full 版本） - 完整字段说明
节点与工作流 - 概念介绍

PreviousWeather 语法（Full 版本）Next节点列表

Last updated 2 months ago

Good night

版本概述

🖥️ Full 版本（完整版）

💾 Essential 版本（核心版）

字段对比总览

📊 对比统计

详细字段对比

1️⃣ 顶层结构

2️⃣ 节点基础字段

3️⃣ 节点 data 对象

4️⃣ 输入/输出字段

5️⃣ 边字段

实际对比示例

Full 版本示例（节点）

Essential 版本示例（节点）

Full 版本示例（边）

Essential 版本示例（边）

转换规则

Full → Essential 转换

Essential → Full 转换

特殊说明

1. edges 字段的特殊处理

2. 可选字段的处理

3. 向后兼容

最佳实践

Agent 生成时

后端存储时

前端处理时

文件大小对比

快速参考表

需要去除的字段清单