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 中读取

---

🔧 技术细节

数据结构

参数绑定信息

node.bindings = {
  "batch_size": { mode: 'static', value: 100 },
  "threshold": { mode: 'context', contextRef: '$LoaderNode.threshold' },
  "filter_mode": { mode: 'exposed' }  // 无 value，表示值来自连线
}

暴露端口信息

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

连线元数据

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 - 技术实现细节
• FEATURES_TEST.md - 功能测试清单
• TEST_INTEGRATION.js - 浏览器测试脚本

---

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