ouczbs/TraceStudio-dev

Fork 0

Boshuang Zhao 021d032b7a TreaceStudio 初版，实现资源预加载功能

2026-01-09 21:37:02 +08:00

6.7 KiB

Raw Blame History

🎯 函数节点嵌套 - 新功能说明

新增功能发布: 支持工作流函数化和多层嵌套编辑

📢 功能亮点

什么是函数节点嵌套？

将任何工作流保存为可复用的函数节点，并支持无限层嵌套编辑。

核心特性

特性	说明
📦 函数封装	将工作流转为可复用的函数节点
🔄 即插即用	拖拽函数到其他工作流中使用
🔍 双击编辑	双击进入函数内部进行编辑
📍 面包屑导航	清晰定位当前所在层级
🌳 多层嵌套	函数中可以包含其他函数
💾 自动保存	所有修改自动保存到磁盘

🚀 5分钟快速开始

步骤 1: 创建函数

1. 在画布中设计任何工作流
2. 右键 → "保存为函数"
3. 输入函数名: my_function
4. 输入显示名: 我的函数
5. ✅ 完成！

步骤 2: 使用函数

1. 从 NodePalette 找到函数
2. 拖拽到新工作流
3. 连接输入/输出
4. ✅ 完成！

步骤 3: 编辑函数

1. 双击函数节点
2. 看到面包屑: 主工作流 / my_function (L1)
3. 编辑内部工作流
4. 点击面包屑或返回按钮退出
5. ✅ 完成！

📚 详细文档

快速开始 (15 分钟)

👉 FUNCTION_NESTING_QUICKSTART.md

5分钟快速上手
常见问题解答
最佳实践建议
命名规范说明

完整实现指南 (1 小时)

👉 FUNCTION_NESTING_IMPLEMENTATION.md

完整的架构设计
后端实现详解
前端实现详解
API 文档
代码示例
测试场景
调试指南

完成总结 (了解项目)

👉 COMPLETION_SUMMARY.md

交付物清单
代码统计
文档清单
技术亮点
下一步计划

🎓 使用场景

场景 1: 数据处理工厂

主工作流
├─ 加载数据节点
├─ extract_columns 函数 (可复用)
├─ transform_data 函数 (可复用)
└─ 保存结果节点

优势:

每个函数独立维护
在不同工作流中复用
易于测试和调试

场景 2: 业务流程编排

主工作流 (采购流程)
├─ 创建订单 (函数)
├─ 验证库存 (函数)
│  ├─ 查询库存 (函数)
│  └─ 计算可用量 (函数)
├─ 生成采购单 (函数)
└─ 发送通知 (函数)

优势:

业务逻辑清晰
功能模块化
支持多层嵌套

场景 3: 数据分析管道

分析工作流
├─ 数据加载 (函数)
├─ 数据清洗 (函数)
│  ├─ 去重 (内部函数)
│  ├─ 填充缺失 (内部函数)
│  └─ 异常检测 (内部函数)
├─ 特征工程 (函数)
└─ 模型预测 (函数)

优势:

流程透明
易于复用
支持版本管理

🔧 关键技术

后端

Python: FastAPI 框架
设计模式: 工厂模式（动态创建节点类）
参数传递: Context 特殊键 (__function_input_*, __function_output_*)

前端

状态管理: Zustand (栈式结构)
组件: React Hooks
交互: 双击进入、右键保存、面包屑导航

存储

格式: JSON
位置: cloud/custom_nodes/functions/
持久化: 磁盘 + localStorage

📊 API 接口

保存函数

POST /api/functions/save
Content-Type: application/json

{
  "function_name": "extract_data",
  "display_name": "提取数据",
  "description": "从源数据中提取列",
  "nodes": [...],
  "edges": [...],
  "inputs": [],
  "outputs": []
}

获取函数列表

GET /api/functions/list

响应:
{
  "success": true,
  "data": [
    {
      "function_name": "extract_data",
      "display_name": "提取数据",
      ...
    }
  ]
}

获取函数详情

GET /api/functions/extract_data

响应:
{
  "success": true,
  "data": {
    "function_name": "extract_data",
    "nodes": [...],
    "edges": [...],
    ...
  }
}

完整 API 文档见: FUNCTION_NESTING_IMPLEMENTATION.md

✨ 新增内容

后端新增

server/app/core/function_nodes.py (281 行)
- InputNode, OutputNode, FunctionNode, 工厂函数
server/app/core/node_loader.py 修改 (67 行新增)
- 函数节点加载器
server/app/api/endpoints_graph.py 修改 (120 行新增)
- 3 个 API 端点
cloud/custom_nodes/functions/ 目录
- 函数存储目录

前端新增

web/src/stores/useStore.ts 修改 (130 行新增)
- 函数嵌套状态管理
web/src/components/Workspace.tsx 修改 (95 行新增)
- 双击进入、右键保存功能
web/src/components/BreadcrumbNav.tsx (148 行)
- 面包屑导航组件

文档新增

FUNCTION_NESTING_QUICKSTART.md (700+ 行)
FUNCTION_NESTING_IMPLEMENTATION.md (2,300+ 行)
COMPLETION_SUMMARY.md (800+ 行)

❓ 常见问题

Q: 如何创建第一个函数？

A: 见快速开始

Q: 如何进入函数编辑？

A: 双击函数节点即可进入。见双击进入

Q: 支持多少层嵌套？

A: 理论无限制，建议不超过 5 层。

Q: 函数修改后如何保存？

A: 自动保存到 localStorage，可右键"保存工作流"永久保存。

Q: 如何分享函数？

A: 导出 functions/*.json 文件，发给其他用户。他们放入同目录即可使用。

更多问题见: 常见问题

🎯 下一步

立即体验

阅读快速开始
创建第一个函数
尝试多层嵌套

深入学习

阅读完整实现指南
查看代码实现
理解架构设计

贡献改进

提出功能建议
报告 Bug
贡献代码

📞 获取帮助

问题类型	查看文档
快速上手	快速开始
常见问题	常见问题
完整文档	实现指南
API 接口	API 文档
最佳实践	最佳实践
项目总结	完成总结

🎉 功能发布信息

版本: v1.0.0
发布日期: 2024-01-15
状态: ✅ 生产就绪
代码行数: ~843 行
文档行数: ~3,800 行
API 端点: 3 个
测试场景: 8 个

开始体验新功能吧！ 🚀

👉 立即开始

6.7 KiB Raw Blame History Unescape Escape