TraceStudio-dev/docs/studio1.3/QUICK_REFERENCE.md

# 🚀 TraceStudio v2.0 高级功能快速参考

## 核心概念（5分钟了解）

### 1️⃣ 特殊节点

| 节点 | 作用 | 特点 |
|------|------|------|
| **InputNode** | 工作流入口 | 将全局上下文映射为输出端口 |
| **OutputNode** | 工作流出口 | 收集结果并返回 |
| **FunctionNode** | 可复用函数 | 封装子工作流 |

### 2️⃣ 连线分类

```
粗线 (━━━) = 数组类型    edgeType: "array"
细线 (——) = 标量类型    edgeType: "scalar"
```

### 3️⃣ 维度转换

```
升维     数组→单个元素  [1,2,3] → execute 3× → [r1,r2,r3]
降维     多线→数组      a+b → [a,b]
广播     单个→数组      5 → [5,5,5]
```

---

## 快速开始

### 示例 1：简单流水线

```python
from app.core.advanced_workflow_executor import AdvancedWorkflowExecutor

nodes = [
    {"id": "input", "type": "InputNodeImpl"},
    {"id": "map", "type": "ArrayMapNode", "params": {"multiplier": 2}},
    {"id": "output", "type": "OutputNodeImpl"}
]

edges = [
    {"source": "input", "sourcePort": "values", "target": "map", "targetPort": "values"},
    {"source": "map", "sourcePort": "mapped", "target": "output", "targetPort": "input"}
]

executor = AdvancedWorkflowExecutor()
success, report = await executor.execute(nodes, edges, {"values": [1,2,3]})
# 输出: [2, 4, 6]
```

### 示例 2：创建函数节点

```python
from app.core.advanced_nodes import WorkflowPackager

# 验证
valid, error = WorkflowPackager.validate_function_workflow(sub_nodes, sub_edges)

# 打包
func_def = WorkflowPackager.package_as_function(
    node_id="my_func",
    nodes=sub_nodes,
    edges=sub_edges,
    display_name="我的函数"
)

# 使用
main_nodes = [..., func_def, ...]
await executor.execute(main_nodes, main_edges)
```

### 示例 3：维度转换

```python
# 升维（数组遍历）
edges = [{
    "source": "array_node",
    "target": "scalar_node",
    "edgeType": "array",
    "dimensionMode": "expand"  # 自动遍历
}]

# 降维（多线打包）
edges = [
    {"source": "n1", "target": "concat", "targetPort": "arrays"},
    {"source": "n2", "target": "concat", "targetPort": "arrays"}
]
# 自动打包为 [value1, value2]
```

---

## 10 个内置节点

### 数组操作

| 节点 | 输入 | 输出 | 说明 |
|------|------|------|------|
| `ArrayMapNode` | Array | Array | `[1,2,3]` ×2 → `[2,4,6]` |
| `ArrayFilterNode` | Array | Array | `[1,2,3,4]` >2 → `[3,4]` |
| `ArrayReduceNode` | Array | Scalar | `[1,2,3]` sum → `6` |
| `ArrayConcatNode` | Array[] | Array | `[[1,2],[3,4]]` → `[1,2,3,4]` |
| `ArrayZipNode` | Array×2 | Array | `[1,2]` zip `[a,b]` → `[[1,a],[2,b]]` |
| `BroadcastNode` | Scalar | Array | `5` ×3 → `[5,5,5]` |

### 特殊节点

| 节点 | 用途 |
|------|------|
| `InputNodeImpl` | 工作流入口 |
| `OutputNodeImpl` | 工作流出口 |
| `FunctionNodeImpl` | 函数节点基类 |

### 控制流

| 节点 | 功能 |
|------|------|
| `ConditionalBranchNode` | if-then-else（部分实现） |

---

## API 参考

### AdvancedWorkflowExecutor

```python
executor = AdvancedWorkflowExecutor(user_id="user1")

# 执行工作流
success, report = await executor.execute(
    nodes=[...],
    edges=[...],
    global_context={...}
)

# 返回报告结构
{
    "execution_id": "uuid",
    "total_duration": 0.123,
    "node_infos": {
        "node_id": {
            "status": "success/error",
            "duration": 0.05,
            "cache_hit": False
        }
    },
    "node_results": {
        "node_id": {"outputs": {...}, "context": {...}}
    }
}
```

### WorkflowPackager

```python
# 验证
valid, error = WorkflowPackager.validate_function_workflow(nodes, edges)

# 打包
func_def = WorkflowPackager.package_as_function(
    node_id="id",
    nodes=[...],
    edges=[...],
    display_name="显示名",
    description="描述"
)
```

### DimensionTransformer

```python
mode = DimensionTransformer.infer_dimension_mode(
    source_type=EdgeType.ARRAY,
    target_type=EdgeType.SCALAR,
    target_is_list=False
)
# 返回：DimensionMode.EXPAND
```

---

## 常用工作流模式

### 模式 1：数据处理流水线

```
Input → Filter → Map → Reduce → Output
```

### 模式 2：并行处理

```
Input → ┬→ Process1 ──┬→ Concat → Output
        └→ Process2 ──┘
```

### 模式 3：嵌套函数

```
Input → [Function1 → Function2 → Function3] → Output
```

### 模式 4：条件分支

```
Input → Condition ─┬→ Path1 ──┬→ Output
                   └→ Path2 ──┘
```

---

## 常见错误和解决方案

### ❌ 错误：函数工作流验证失败

```
Error: 函数节点工作流必须包含至少一个InputNode
```

✅ **解决**：确保子工作流包含 InputNode：
```python
nodes = [
    {"id": "input", "type": "InputNodeImpl"},  # ← 必须有
    {"id": "logic", "type": "MyNode"},
    {"id": "output", "type": "OutputNodeImpl"}  # ← 必须有
]
```

### ❌ 错误：类型不匹配

```
Error: unsupported operand type(s) for *: 'dict' and 'int'
```

✅ **解决**：检查输入端口名是否正确：
```python
# 错误
{"source": "input", "sourcePort": "output", "target": "map", "targetPort": "values"}
              ↑ 错误的端口名

# 正确
{"source": "input", "sourcePort": "values", "target": "map", "targetPort": "values"}
              ↑ 使用 global_context 中的字段名
```

### ❌ 错误：无法获取节点

```
Error: 未知的节点类型: MyNode
```

✅ **解决**：确保节点已注册：
```python
from app.nodes.advanced_example_nodes import *  # ← 导入所有节点
from app.core.node_registry import NodeRegistry

print(NodeRegistry.list_all())  # 查看已注册的节点
```

---

## 性能调优建议

### 缓存优化

```python
# 启用缓存
CacheManager.init_memory_cache(max_size=1000, ttl=3600)
CacheManager.init_disk_cache(Path("cache"))

# 查看缓存统计
stats = CacheManager.get_stats()
print(f"命中率: {stats['hit_ratio']}%")
```

### 升维优化

```python
# 升维时避免大数组（>10000 元素）
# 如果必须：考虑使用向量化节点或并行处理

# 检查升维次数
node_info = report["node_infos"]["node_id"]
expansions = node_info.get("dimension_expansions", 0)
```

### 执行监控

```python
# 查看各节点耗时
for node_id, info in report["node_infos"].items():
    print(f"{node_id}: {info['duration']}ms")

# 找出性能瓶颈
slow_nodes = [n for n, i in report["node_infos"].items() if i['duration'] > 100]
```

---

## 文档导航

- 📖 [完整功能文档](./ADVANCED_FEATURES.md)
- 🏗️ [架构设计文档](./BACKEND_ARCHITECTURE_COMPLETE.md)
- ✅ [完成报告](./COMPLETION_REPORT.md)
- 📚 [本文档](./QUICK_REFERENCE.md)

---

## 版本信息

| 项目 | 版本 |
|------|------|
| TraceStudio | v2.0 |
| 高级功能 | Beta |
| 状态 | ✅ 生产就绪 |
| 最后更新 | 2025-01-08 |

---

**需要帮助？** 查看详细文档或运行测试：
```bash
python server/tests/test_advanced_features.py
```