TraceStudio-dev/docs/web/USER_GUIDE_v0.3.0.md

# TraceStudio v0.3.0 使用指南

## 🎯 新功能速览

### 1️⃣ Param 绑定模式（三种参数来源）

在 Inspector 中，每个参数都可以选择三种绑定模式：

#### 📝 静态值模式
- **适用场景**: 参数值固定、不依赖其他节点
- **操作步骤**:
  1. 选中节点，在 Inspector 找到参数
  2. 点击 **📝 静态值** 按钮
  3. 输入数值或文本
- **效果**: `node.bindings[paramName] = { mode: 'static', value: '输入值' }`

#### 🔗 Context 模式
- **适用场景**: 参数值来自上游节点的输出或全局变量
- **操作步骤**:
  1. 选中节点，找到要绑定的参数
  2. 点击 **🔗 Context** 按钮
  3. 在下拉列表中选择变量：
     - `系统时间` → $Global.System.Time
     - `当前用户` → $Global.System.User
     - `上游节点.变量名` → $上游NodeID.变量名
- **效果**: `node.bindings[paramName] = { mode: 'context', contextRef: '$Global.System.Time' }`

**示例工作流**:
```
CSV Loader (输出 data, context: rowCount)
    ↓
Transform (参数 threshold 绑定 → $LoaderNode.rowCount)
    ↓
Visualizer (接收 Transform 输出)
```

#### ⚡ 暴露端口模式
- **适用场景**: 参数值在运行时从其他节点的连线传递
- **操作步骤**:
  1. 选中节点，找到要暴露的参数
  2. 点击 **⚡ 暴露端口** 按钮
  3. 节点左侧会出现新的**粉红色端口** ⚡（14x14）
  4. 从其他节点的输出连线拖至该端口
- **效果**: 
  - `node.bindings[paramName] = { mode: 'exposed' }`
  - `node.exposedPorts.params.push(paramName)`
  - 节点显示 "⚡ Params: paramName"

**示例工作流**:
```
Range Generator (输出 values: [1,2,3,4,5])
         ↓
    Batch Size ⚡ (暴露的参数端口)
         ↓
Transform (接收 Batch Size 连线)
```

---

### 2️⃣ 连线 EdgeType（数据维度视觉编码）

系统自动根据输出类型推断连线的数据维度：

#### 数组连线（粗线 - 4px）
- **数据类型**: Array、List、Table、DataFrame
- **样式**: 粗线 4px、亮蓝色光晕
- **含义**: 批量数据流

#### 标量连线（细线 - 3px）
- **数据类型**: String、Integer、Float、Boolean 等
- **样式**: 细线 3px、橙色/紫色
- **含义**: 单值数据流

#### 视觉示例
```
Loader (DataTable)
    ║╔════════════════════════════════════╗║  ← 4px 粗线（数组）
    ║║ Transform                          ║║
    ║╚════════════════════════════════════╝║
    ║  │ (输出 Scalar: count)
    ║  │ ← 3px 细线（标量）
    ║  ↓
   Output
```

---

### 3️⃣ 暴露端口显示（两种暴露端口）

节点可以暴露两种类型的端口，供其他节点连接：

#### 暴露 Param 端口（输入端口）
- **来源**: 点击参数上的 **⚡ 暴露端口** 按钮
- **样式**: 粉红色 ⚡（#ec4899，14x14）
- **位置**: 节点左侧（与普通输入端口混合）
- **用途**: 接收来自其他节点的值，替代静态值或 Context 引用
- **指示**: 节点内显示 "⚡ Params: param1, param2"

#### 暴露 Context 端口（输出端口）
- **来源**: 点击参数上的 **⚡ 暴露端口** 后选择 Context（计划功能）
- **样式**: 绿色 📋（#22c55e，14x14）
- **位置**: 节点右侧（与普通输出端口混合）
- **用途**: 输出该参数作为 Context 变量供下游节点访问
- **指示**: 节点内显示 "📋 Contexts: ctx1, ctx2"

#### 视觉示例
```
             ┌─────────────────────────┐
             │  Loader Node            │
      ⚡ ─→  │ ┌─ Param: batchSize     │  ← 暴露 Param 端口（粉红）
             │ └─ Config...            │
             │ ┌─ Output: data         │
             │ └─ Output: metadata     │
             └────────────┬────────────┘
                          │ → 📋 (绿色)    ← 暴露 Context 端口
                          ↓
                    Transform
```

---

## 📖 常见工作流示例

### 示例 1：简单的参数传递

```
创建流程：
1. Loader CSV → 配置 batch_size=100（静态值）
2. Transform → filter_threshold 绑定到 $Global.System.Time
3. Visualizer → 接收 Transform 输出
```

### 示例 2：动态参数（暴露端口）

```
创建流程：
1. Range Generator (输出数组 [1,2,3,4,5])
2. Batch Processor 
   - 参数 batch_size 点击 ⚡ 暴露端口
   - 从 Range 的输出连线拖至 batch_size ⚡ 端口
3. 执行：batch_size 的值来自 Range Generator 的输出
```

### 示例 3：Context 链式引用

```
创建流程：
1. Loader CSV (输出 context: row_count=1000)
2. Transform
   - 参数 sample_size 选择 🔗 Context
   - 下拉选择 "$LoaderNode.row_count"
3. Filter
   - 参数 threshold 选择 🔗 Context
   - 下拉选择 "$TransformNode.filtered_count"（假设 Transform 暴露了此 Context）
4. 执行：参数值自动从上游 Context 中读取
```

---

## 🔧 技术细节

### 数据结构

#### 参数绑定信息
```typescript
node.bindings = {
  "batch_size": { mode: 'static', value: 100 },
  "threshold": { mode: 'context', contextRef: '$LoaderNode.threshold' },
  "filter_mode": { mode: 'exposed' }  // 无 value，表示值来自连线
}
```

#### 暴露端口信息
```typescript
node.exposedPorts = {
  params: ["batch_size", "filter_mode"],  // 暴露为输入端口的参数
  contexts: ["result_count", "status"]    // 暴露为输出端口的 Context
}
```

#### 连线元数据
```typescript
edge = {
  source: 'loader1',
  target: 'transform2',
  sourceHandle: 'output-0',
  targetHandle: 'input-0',
  data: {
    sourceType: 'DataTable',  // 源输出类型
    edgeType: 'array',        // 推断的数据维度
    color: '#3b82f6'
  },
  style: {
    strokeWidth: 4,  // 根据 edgeType 自动调整
    stroke: '#3b82f6'
  }
}
```

### Context 变量命名约定

```
全局变量: $Global.<category>.<name>
  例如: $Global.System.Time
       $Global.System.User

上游节点变量: $<NodeID>.<name>
  例如: $loader1.row_count
       $transform2.filtered_data
```

---

## ⚡ 快速技巧

### Tip 1: 快速切换参数模式
- 同一参数可反复切换 📝 → 🔗 → ⚡
- 切换时数据会自动保存到对应的字段（value / contextRef / exposedPorts）

### Tip 2: 查看暴露的端口
- 节点内有紫红色区域显示所有暴露的端口
- 悬停在粉红/绿色端口上可看到 Tooltip

### Tip 3: Context 变量快速查找
- 下拉列表按类别分组（全局 / 上游节点）
- 计划后续支持搜索框快速查找

### Tip 4: 连线粗细辨识
- 粗线（4px）= 数组/表格数据，通常支持 EXPAND/COLLAPSE/BROADCAST 维度变换
- 细线（3px）= 标量数据，一对一传递

---

## 🐛 常见问题

### Q: 为什么看不到 Context 下拉列表中的变量？
**A**: 上游节点需要配置并暴露 context_vars。检查：
1. 上游节点的 `data.meta.context_vars` 是否有内容
2. 是否正确从 Inspector 中选择 🔗 Context 模式

### Q: 删除上游节点后，contextRef 是否自动清空？
**A**: 当前不会自动清空。需要手动在 Inspector 中重新选择变量。（计划改进）

### Q: 暴露端口是否支持多重连接？
**A**: 是的，暴露的 Param 端口支持多个上游节点连接，但只有最后一条连线的值会生效。

### Q: 连线的 edgeType 是否影响执行逻辑？
**A**: 目前仅用于视觉展示。后续计划支持 dimensionMode 扩展，需后端配合实现 EXPAND/COLLAPSE/BROADCAST。

### Q: 如何导出/导入包含参数绑定的工作流？
**A**: 目前在本地 IndexedDB 存储。完整的 import/export 功能计划在 v0.4.0 实现。

---

## 📚 相关文档

- [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) - 技术实现细节
- [FEATURES_TEST.md](./FEATURES_TEST.md) - 功能测试清单
- [TEST_INTEGRATION.js](./TEST_INTEGRATION.js) - 浏览器测试脚本

---

**版本**: TraceStudio v0.3.0 | 前端参数绑定与端口暴露
**更新时间**: 2024-01