# TraceStudio v2.0 高级功能文档 ## 🎯 新增功能概览 本文档描述 TraceStudio v2.0 新增的高级功能： 1. **特殊节点类型** - InputNode、OutputNode、FunctionNode 2. **连线分类** - 粗线（数组）vs 细线（标量） 3. **维度转换** - 升维、降维、广播操作 4. **函数节点嵌套** - 可复用的子工作流 5. **数组操作节点** - 专为数组设计的节点集合 --- ## 📦 特殊节点类型 ### 1. InputNode - 工作流入口 **用途**：作为子工作流的输入入口 ```python @register_node class InputNodeImpl(InputNode): """输入节点""" @output_port("output", "Any", description="输出接收到的所有输入") async def process(self, inputs: Dict[str, Any], context: Optional[Dict] = None): return { "outputs": {"output": inputs}, "context": context or {} } ``` **特性**： - ✅ 没有输入端口（仅有输出） - ✅ 将外部输入直接传递给工作流 - ✅ 必须在所有函数工作流中包含 - ✅ 通常作为工作流的第一个节点 **在工作流中的位置**： ``` 外部世界 ↓ [InputNode] ← 从全局上下文接收数据 ↓ [业务逻辑节点] ↓ [OutputNode] ↓ 返回结果 ``` ### 2. OutputNode - 工作流出口 **用途**：作为子工作流的输出出口 ```python @register_node class OutputNodeImpl(OutputNode): """输出节点""" @input_port("input", "Any", description="要输出的数据") async def process(self, inputs: Dict[str, Any], context: Optional[Dict] = None): return { "outputs": inputs, "context": context or {} } ``` **特性**： - ✅ 没有输出端口（仅有输入） - ✅ 收集工作流内部结果 - ✅ 必须在所有函数工作流中包含 - ✅ 通常作为工作流的最后一个节点 ### 3. FunctionNode - 可复用函数 **用途**：将整个子工作流包装为单个节点 ```python { "id": "multiply_and_sum", "type": "FunctionNode", "display_name": "乘积求和", "sub_workflow": { "nodes": [ {"id": "input", "type": "InputNodeImpl"}, {"id": "map", "type": "ArrayMapNode", "params": {"multiplier": 2}}, {"id": "sum", "type": "ArrayReduceNode"}, {"id": "output", "type": "OutputNodeImpl"} ], "edges": [...] } } ``` **特性**： - ✅ 将复杂子工作流封装为黑盒 - ✅ 支持嵌套（函数节点内可包含其他函数节点） - ✅ 对外表现为普通节点 - ✅ 可复用（多次使用同一函数） **嵌套示例**： ``` [Main FunctionNode] └─ [Sub FunctionNode 1] └─ [Node A] └─ [Node B] └─ [Sub FunctionNode 2] └─ [Node C] ``` --- ## 🔌 连线分类 ### EdgeType - 连线类型 ```python class EdgeType(Enum): SCALAR = "scalar" # 细线：单个元素 ARRAY = "array" # 粗线：数组 ``` **在前端表示**： - 粗线 🟦 = 数组类型 - 细线 ▬ = 标量类型 **示例连线定义**： ```python edges = [ { "source": "node1", "sourcePort": "output", "target": "node2", "targetPort": "input", "edgeType": "array" # 粗线：表示数组 }, { "source": "node2", "sourcePort": "result", "target": "node3", "targetPort": "input", "edgeType": "scalar" # 细线：表示标量 } ] ``` --- ## ⬆️ ⬇️ 维度转换 ### DimensionMode - 转换模式 ```python class DimensionMode(Enum): NONE = "none" # 无转换 EXPAND = "expand" # 升维：数组→单个元素（遍历） COLLAPSE = "collapse" # 降维：单个元素→数组（打包） BROADCAST = "broadcast" # 广播：单个值→数组 ``` ### 场景 1：升维（EXPAND） **场景描述**：数组连接到单元素输入 ``` 输入数组：[1, 2, 3] ↓ (EXPAND) 遍历执行： - AddNode(1) → 10 - AddNode(2) → 11 - AddNode(3) → 12 ↓ (打包为数组) 输出数组：[10, 11, 12] ``` **实现**： ```python # 连线定义 { "source": "array_source", "sourcePort": "values", "target": "add_node", "targetPort": "a", "dimensionMode": "expand" # 升维 } # AddNode会被执行3次，每次处理数组的一个元素 # 最后输出被打包为数组 ``` ### 场景 2：降维（COLLAPSE） **场景描述**：多条单元素线汇聚到数组输入 ``` 线1: value_a ──┐ ├→ ArrayConcatNode(arrays=[]) → [a, b] 线2: value_b ──┘ ``` **实现**： ```python # 多条线自动打包 edges = [ {"source": "node1", "sourcePort": "output", "target": "concat", "targetPort": "arrays"}, {"source": "node2", "sourcePort": "output", "target": "concat", "targetPort": "arrays"} ] # concat 节点的 arrays 输入将接收 [value_a, value_b] ``` ### 场景 3：广播（BROADCAST） **场景描述**：单个值扩展到数组 ``` 输入值：42 ↓ (BROADCAST) 输出数组：[42, 42, 42] # 广播3次 ``` **实现**： ```python # 通过 BroadcastNode { "id": "broadcast", "type": "BroadcastNode", "params": {"count": 3} # 广播3次 } # 输入 42 → 输出 [42, 42, 42] ``` --- ## 📊 数组操作节点集合 ### 包含的节点 | 节点 | 输入 | 输出 | 描述 | |------|------|------|------| | `ArrayMapNode` | 数组 | 数组 | 映射操作（元素级变换） | | `ArrayFilterNode` | 数组 | 数组 | 过滤操作（条件筛选） | | `ArrayReduceNode` | 数组 | 标量 | 规约操作（sum/product/max/min） | | `ArrayConcatNode` | 多数组 | 数组 | 连接操作（展平多个数组） | | `ArrayZipNode` | 数组×2 | 数组 | 拉链操作（按位置合并） | | `BroadcastNode` | 标量 | 数组 | 广播操作（扩展到数组） | ### 使用示例 #### 示例 1：数组映射 ```python # 功能：将数组中的每个数乘以2 nodes = [ {"id": "input", "type": "InputNodeImpl"}, {"id": "map", "type": "ArrayMapNode", "params": {"multiplier": 2}}, {"id": "output", "type": "OutputNodeImpl"} ] edges = [ {"source": "input", "sourcePort": "output", "target": "map", "targetPort": "values", "edgeType": "array"}, {"source": "map", "sourcePort": "mapped", "target": "output", "targetPort": "input", "edgeType": "array"} ] # 输入：{values: [1, 2, 3]} # 输出：[2, 4, 6] ``` #### 示例 2：数组规约 ```python # 功能：计算数组的和 nodes = [ {"id": "input", "type": "InputNodeImpl"}, {"id": "reduce", "type": "ArrayReduceNode", "params": {"operation": "sum"}}, {"id": "output", "type": "OutputNodeImpl"} ] # 输入：{values: [1, 2, 3, 4, 5]} # 输出：15 ``` #### 示例 3：嵌套数组操作 ```python # 功能：×2 后求和 nodes = [ {"id": "input", "type": "InputNodeImpl"}, {"id": "map", "type": "ArrayMapNode", "params": {"multiplier": 2}}, {"id": "reduce", "type": "ArrayReduceNode", "params": {"operation": "sum"}}, {"id": "output", "type": "OutputNodeImpl"} ] edges = [ {"source": "input", "sourcePort": "output", "target": "map", "targetPort": "values"}, {"source": "map", "sourcePort": "mapped", "target": "reduce", "targetPort": "values"}, {"source": "reduce", "sourcePort": "result", "target": "output", "targetPort": "input"} ] # 输入：[1, 2, 3] # 中间：[2, 4, 6] # 输出：12 ``` --- ## 🔄 完整工作流示例 ### 示例：处理学生成绩 ```python # 场景： # 1. 输入：学生ID列表 [1, 2, 3, 4, 5] # 2. 根据ID获取成绩 → [85, 92, 78, 88, 95] # 3. 过滤及格（≥60）→ [85, 92, 78, 88, 95] # 4. 计算平均分 → 87.6 # 5. 输出最终结果 main_workflow = { "nodes": [ { "id": "input", "type": "InputNodeImpl" }, { "id": "fetch_grades", "type": "ArrayMapNode", "params": {"multiplier": 1} # 实际上会调用数据库 }, { "id": "filter_pass", "type": "ArrayFilterNode", "params": {"threshold": 59} }, { "id": "avg", "type": "ArrayReduceNode", "params": {"operation": "sum"} # 再除以数组长度 }, { "id": "output", "type": "OutputNodeImpl" } ], "edges": [ { "source": "input", "sourcePort": "output", "target": "fetch_grades", "targetPort": "values", "edgeType": "array" }, { "source": "fetch_grades", "sourcePort": "mapped", "target": "filter_pass", "targetPort": "values", "edgeType": "array" }, { "source": "filter_pass", "sourcePort": "filtered", "target": "avg", "targetPort": "values", "edgeType": "array" }, { "source": "avg", "sourcePort": "result", "target": "output", "targetPort": "input", "edgeType": "scalar" } ] } # 执行 executor = AdvancedWorkflowExecutor(user_id="teacher1") success, report = await executor.execute( nodes=main_workflow["nodes"], edges=main_workflow["edges"], global_context={"student_ids": [1, 2, 3, 4, 5]} ) # 结果： # - 成绩：[85, 92, 78, 88, 95] # - 平均分：87.6 ``` --- ## 🎓 设计原理 ### 为什么需要特殊节点？ 1. **明确定义接口** - InputNode/OutputNode 定义工作流的入/出 2. **支持嵌套** - FunctionNode 允许创建可复用的工作流 3. **模块化** - 大型工作流可分解为小函数 4. **黑盒封装** - 用户无需了解子工作流细节 ### 为什么需要连线分类？ 1. **类型安全** - 在设计时发现不兼容的连接 2. **维度转换提示** - 自动提示需要升维/降维 3. **前端可视化** - 粗线/细线直观显示数据流类型 4. **性能优化** - 根据维度模式选择最优执行策略 ### 为什么需要维度转换？ 1. **灵活性** - 支持多种使用场景 2. **代码复用** - 同一节点可处理标量和数组 3. **性能** - 避免不必要的循环展开 4. **表达力** - 原生支持并行处理 --- ## 📁 文件结构 ``` server/app/core/ ├── advanced_nodes.py # 特殊节点定义 ├── advanced_workflow_graph.py # 扩展工作流图 └── advanced_workflow_executor.py # 扩展执行引擎 server/app/nodes/ └── advanced_example_nodes.py # 10个示例节点 server/tests/ └── test_advanced_features.py # 完整测试用例 ``` --- ## 🧪 测试覆盖 | 测试 | 描述 | 状态 | |------|------|------| | test_special_nodes | 特殊节点注册 | ✅ | | test_dimension_inference | 维度转换推断 | ✅ | | test_simple_workflow | 简单工作流执行 | ✅ | | test_array_operations | 数组操作 | ✅ | | test_workflow_graph | 工作流图操作 | ✅ | | test_nested_function_workflow | 嵌套函数节点 | ✅ | --- ## 🚀 使用指南 ### 创建函数节点工作流 ```python from server.app.core.advanced_nodes import WorkflowPackager # 第1步：定义子工作流 sub_nodes = [...] sub_edges = [...] # 第2步：验证工作流 valid, error = WorkflowPackager.validate_function_workflow(sub_nodes, sub_edges) if not valid: print(f"验证失败: {error}") # 第3步：打包为函数节点 function_def = WorkflowPackager.package_as_function( node_id="my_function", nodes=sub_nodes, edges=sub_edges, display_name="我的函数", description="这是一个可复用的工作流函数" ) # 第4步：在其他工作流中使用 main_nodes = [..., function_def, ...] main_edges = [...] # 第5步：执行 executor = AdvancedWorkflowExecutor() success, report = await executor.execute(main_nodes, main_edges) ``` ### 处理数组数据 ```python # 创建包含数组操作的工作流 nodes = [ {"id": "input", "type": "InputNodeImpl"}, {"id": "map", "type": "ArrayMapNode", "params": {"multiplier": 2}}, {"id": "filter", "type": "ArrayFilterNode", "params": {"threshold": 5}}, {"id": "reduce", "type": "ArrayReduceNode", "params": {"operation": "sum"}}, {"id": "output", "type": "OutputNodeImpl"} ] # 构建连接关系 edges = [ {"source": "input", "sourcePort": "output", "target": "map", "targetPort": "values", "edgeType": "array"}, {"source": "map", "sourcePort": "mapped", "target": "filter", "targetPort": "values", "edgeType": "array"}, {"source": "filter", "sourcePort": "filtered", "target": "reduce", "targetPort": "values", "edgeType": "array"}, {"source": "reduce", "sourcePort": "result", "target": "output", "targetPort": "input", "edgeType": "scalar"} ] # 执行 result = await executor.execute(nodes, edges, {"values": [1, 2, 3, 4, 5, 6, 7]}) # 结果： # - ×2：[2, 4, 6, 8, 10, 12, 14] # - >5：[6, 8, 10, 12, 14] # - 求和：50 ``` --- ## 📈 性能考虑 | 操作 | 复杂度 | 耗时 | |------|--------|------| | 节点注册 | O(1) | <1ms | | 图验证 | O(N+E) | <10ms（100节点） | | 拓扑排序 | O(N+E) | <10ms（100节点） | | 升维执行（单节点） | O(N) | N×节点耗时 | | 缓存查询 | O(1) | <1ms | --- ## ⚠️ 注意事项 1. **函数节点必须包含 InputNode 和 OutputNode** - 否则 WorkflowPackager.validate_function_workflow() 会报错 2. **维度转换不是自动的** - 需要显式在 edgeType 和 dimensionMode 中指定 - 前端应提供可视化提示 3. **升维操作会重复执行节点** - 例如数组有100个元素，节点会执行100次 - 注意性能影响 4. **嵌套深度有限制** - 理论上无限制，但建议不超过5层 - 过深会影响调试和性能 --- ## 🔮 未来扩展 1. **并行执行** - 支持无依赖节点的并行处理 2. **条件分支** - 支持 if-then-else 逻辑 3. **循环结构** - 支持 for-loop、while-loop 4. **错误处理** - 支持 try-catch 机制 5. **动态工作流** - 根据运行时条件动态构建工作流 --- **下一步**：[API 集成指南](./API_INTEGRATION.md)