297 lines
6.5 KiB
Markdown
297 lines
6.5 KiB
Markdown
# 函数节点嵌套 - 快速开始指南
|
||
|
||
## 🎯 5分钟快速上手
|
||
|
||
### 第1步: 创建一个函数
|
||
|
||
1. 在画布上设计任何工作流（建议包含 InputNode 和 OutputNode）
|
||
2. 在画布**空白处右键** → 选择 **"保存为函数"**
|
||
3. 输入函数名（英文，如: `my_first_function`）
|
||
4. 输入显示名（中文，如: `我的第一个函数`）
|
||
5. 点击确认 ✅
|
||
|
||
**完成！函数已保存到 `cloud/custom_nodes/functions/` 目录**
|
||
|
||
---
|
||
|
||
### 第2步: 使用函数节点
|
||
|
||
1. 在 NodePalette（左侧）中找到刚创建的函数节点
|
||
2. 拖拽到新的或现有的工作流中
|
||
3. 连接输入/输出端口
|
||
4. **本步完成**
|
||
|
||
---
|
||
|
||
### 第3步: 进入函数编辑
|
||
|
||
1. **双击**函数节点
|
||
2. 画布自动显示函数内部的工作流
|
||
3. 顶部会出现面包屑导航: **主工作流 / my_first_function (L1)**
|
||
4. 可以编辑、删除或添加节点
|
||
|
||
**你现在在函数内部！** 🎉
|
||
|
||
---
|
||
|
||
### 第4步: 返回主工作流
|
||
|
||
**3种方式选一种**:
|
||
|
||
#### 方式A: 点击面包屑的"返回"按钮
|
||
```
|
||
[← 返回] 主工作流 / my_first_function (L1)
|
||
```
|
||
|
||
#### 方式B: 点击面包屑的"主工作流"链接
|
||
```
|
||
[← 返回] [主工作流] / my_first_function (L1)
|
||
↑ 点击这里
|
||
```
|
||
|
||
#### 方式C: 按Ctrl+Z返回（如果实现了快捷键）
|
||
- 需要自定义扩展
|
||
|
||
---
|
||
|
||
### ✅ 就这么简单！
|
||
|
||
你现在已经掌握了函数嵌套的基本用法。
|
||
|
||
---
|
||
|
||
## 🚀 高级用法: 多层嵌套
|
||
|
||
### 场景: 函数套函数
|
||
|
||
```
|
||
主工作流
|
||
├─ InputNode (x1)
|
||
├─ 函数节点 A
|
||
│ ├─ InputNode
|
||
│ ├─ 函数节点 B ← 可以在这里再嵌套！
|
||
│ │ ├─ InputNode
|
||
│ │ ├─ 处理逻辑
|
||
│ │ └─ OutputNode
|
||
│ └─ OutputNode
|
||
└─ OutputNode
|
||
```
|
||
|
||
### 操作步骤
|
||
|
||
1. 进入函数A（双击）
|
||
2. 在函数A内创建一个函数B节点（拖拽）
|
||
3. 双击函数B节点进入
|
||
4. 面包屑显示: **主工作流 / 函数A / 函数B (L2)**
|
||
5. 编辑完成后，使用面包屑返回或跳转
|
||
|
||
### 支持的最大层级
|
||
|
||
- 理论无限制 (取决于内存和性能)
|
||
- 建议不超过 **5层** 以保证良好的用户体验
|
||
|
||
---
|
||
|
||
## 📋 命名规范
|
||
|
||
### 函数名称 (function_name)
|
||
|
||
- ✅ 使用英文字母、数字、下划线
|
||
- ✅ 以字母或下划线开头
|
||
- ❌ 不能有空格、中文、特殊符号
|
||
|
||
**示例**:
|
||
```
|
||
good_names: ✅
|
||
- extract_data
|
||
- process_csv_v2
|
||
- _private_function
|
||
- Transform123
|
||
|
||
bad_names: ❌
|
||
- Extract Data (有空格)
|
||
- 提取数据 (中文)
|
||
- function-name (有横杠)
|
||
- 123function (数字开头)
|
||
```
|
||
|
||
### 显示名称 (display_name)
|
||
|
||
- 可以使用中文、英文、特殊符号
|
||
- 在 NodePalette 中显示
|
||
- 在面包屑导航中显示
|
||
|
||
**示例**:
|
||
```
|
||
✅ 提取数据
|
||
✅ Extract Data
|
||
✅ 数据 → 转换 v2.0
|
||
✅ [高级] 复杂处理
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 常见问题
|
||
|
||
### Q1: 双击函数节点没有反应
|
||
|
||
**检查清单**:
|
||
- [ ] 确认是函数节点（不是 InputNode/OutputNode）
|
||
- [ ] 打开浏览器控制台查看错误
|
||
- [ ] 确认后端服务运行: `curl http://127.0.0.1:8000/api/functions/list`
|
||
- [ ] 检查网络连接
|
||
|
||
**解决方案**:
|
||
```javascript
|
||
// 在浏览器控制台执行
|
||
fetch('http://127.0.0.1:8000/api/functions/list')
|
||
.then(r => r.json())
|
||
.then(d => console.log(d))
|
||
```
|
||
|
||
### Q2: 保存函数时提示"函数名称无效"
|
||
|
||
**原因**: 函数名称不符合命名规范
|
||
|
||
**正确做法**:
|
||
- ✅ 只用英文字母、数字、下划线
|
||
- ✅ 以字母或下划线开头
|
||
- ✅ 不含空格或特殊符号
|
||
|
||
**错误做法**:
|
||
- ❌ 中文名称
|
||
- ❌ 包含空格
|
||
- ❌ 包含横杠或其他符号
|
||
|
||
### Q3: 面包屑导航不显示
|
||
|
||
**原因**:
|
||
- 尚未进入任何函数 (functionStack 为空)
|
||
- 或者 BreadcrumbNav 组件被隐藏
|
||
|
||
**解决方案**:
|
||
1. 双击函数节点进入
|
||
2. 如果还是不显示，打开浏览器开发者工具的"元素检查器"
|
||
3. 搜索 "BreadcrumbNav" 或检查 z-index
|
||
|
||
### Q4: 返回上一层时工作流数据丢失
|
||
|
||
**原因**:
|
||
- 进入函数时未正确保存上一层级的状态
|
||
- 浏览器 localStorage 被清空
|
||
|
||
**解决方案**:
|
||
1. 重新加载页面（会从 localStorage 恢复）
|
||
2. 检查浏览器控制台是否有错误
|
||
3. 确认 Workspace 中的 useStore 调用正确
|
||
|
||
### Q5: 能否在函数内直接编辑，然后自动保存？
|
||
|
||
**当前行为**:
|
||
- 编辑自动保存到 localStorage
|
||
- 但**不会更新** 函数定义文件 (`.json`)
|
||
|
||
**计划改进** (Phase 3):
|
||
- 添加"保存函数"按钮
|
||
- 自动检测函数内部工作流的变化
|
||
- 版本控制和历史记录
|
||
|
||
### Q6: 支持撤销/重做吗？
|
||
|
||
**当前**:
|
||
- 基本的 undo/redo (由 zustand store 提供)
|
||
- 在函数内编辑支持历史记录
|
||
|
||
**改进方向**:
|
||
- 函数版本控制
|
||
- 编辑历史跟踪
|
||
- 比较功能
|
||
|
||
---
|
||
|
||
## 💡 最佳实践
|
||
|
||
### ✅ DO (推荐)
|
||
|
||
1. **按功能划分函数**
|
||
- 每个函数执行单一功能
|
||
- 使用清晰的命名
|
||
|
||
2. **编写输入/输出节点**
|
||
- 明确定义函数的输入参数
|
||
- 明确定义输出数据
|
||
- 便于重用
|
||
|
||
3. **测试函数**
|
||
- 创建函数后先测试单独使用
|
||
- 确认输入/输出正确
|
||
|
||
4. **文档函数**
|
||
- 使用 `display_name` 和 `description` 记录用途
|
||
- 后续搜索和使用更方便
|
||
|
||
5. **保持层级深度**
|
||
- 不超过 3-5 层为佳
|
||
- 过深导致难以理解和维护
|
||
|
||
### ❌ DON'T (避免)
|
||
|
||
1. ❌ 创建无用的函数
|
||
- 只有一个节点的函数
|
||
- 从未使用过的函数
|
||
|
||
2. ❌ 过度嵌套
|
||
- 函数A包含函数B包含函数C包含函数D...
|
||
- 难以理解数据流
|
||
|
||
3. ❌ 混淆输入/输出
|
||
- 函数没有清晰的 InputNode/OutputNode
|
||
- 导致数据流不清楚
|
||
|
||
4. ❌ 频繁更改已发布的函数
|
||
- 可能破坏依赖该函数的工作流
|
||
- 建议版本管理 (v1, v2, ...)
|
||
|
||
5. ❌ 循环依赖
|
||
- 函数A包含函数B，函数B包含函数A
|
||
- 导致无限递归
|
||
|
||
---
|
||
|
||
## 🎓 学习路径
|
||
|
||
### 初级 (这节课)
|
||
- [x] 创建函数
|
||
- [x] 使用函数节点
|
||
- [x] 进入/退出函数
|
||
- [x] 面包屑导航
|
||
|
||
### 中级 (下一步)
|
||
- [ ] 函数参数验证
|
||
- [ ] 错误处理
|
||
- [ ] 函数文档生成
|
||
- [ ] 多版本管理
|
||
|
||
### 高级 (进阶)
|
||
- [ ] 函数库管理
|
||
- [ ] 函数搜索和发现
|
||
- [ ] 函数分享和导入
|
||
- [ ] 性能优化
|
||
|
||
---
|
||
|
||
## 📞 需要帮助？
|
||
|
||
1. **查看完整文档**: [FUNCTION_NESTING_IMPLEMENTATION.md](FUNCTION_NESTING_IMPLEMENTATION.md)
|
||
2. **检查示例函数**: `cloud/custom_nodes/functions/example_function.json`
|
||
3. **浏览器控制台**: 按 F12 查看错误和日志
|
||
4. **后端日志**: 检查 `server.log`
|
||
|
||
---
|
||
|
||
**祝你使用愉快！** 🎉
|
||
|
||
---
|
||
|
||
*版本: v1.0.0 | 最后更新: 2024-01-15*
|