TraceStudio-dev/docs/web/QUICK_START.md

🎉 TraceStudio v0.3.0 - 快速开始

新功能: Param 绑定模式 + EdgeType 视觉编码 + 暴露端口系统

---

🚀 三分钟快速体验

第一步：启动开发环境

cd web
npm install
npm run dev

浏览器自动打开 http://localhost:5173

第二步：创建第一个使用新功能的节点

1. 从左侧节点库拖拽 Loader 和 Transform 节点到画布
2. 连接它们: Loader 的输出拖到 Transform 的输入
3. 选中 Transform 节点 → 右侧 Inspector 面板出现

第三步：尝试 Param 绑定

📝 静态值模式

1. 在 Inspector 找到 "batch_size" 参数
2. 点击 📝 静态值 按钮
3. 输入数值 100
4. 保存

🔗 Context 模式

1. 同一参数点击 🔗 Context 按钮
2. 下拉列表选择：$Global.System.Time 或 $LoaderNode.xxx
3. 完成绑定

⚡ 暴露端口

1. 同一参数点击 ⚡ 暴露端口 按钮
2. 节点左侧出现新的粉红色端口
3. 从其他节点连线拖到该端口

第四步：观察连线粗细

Loader (输出 DataTable - 数组)
    ║║ ← 粗线 4px（edgeType='array'）
Transform (输出 count - 标量)
    ║  ← 细线 3px（edgeType='scalar'）
Visualizer

---

📚 文档导航

文档	适合人群	内容
USER_GUIDE_v0.3.0.md	最终用户	如何使用新功能、工作流示例、常见问题
IMPLEMENTATION_SUMMARY.md	开发者	技术细节、API 变更、集成说明
FEATURES_TEST.md	测试者	测试场景、验收标准、已知问题
ACCEPTANCE_CHECKLIST.md	项目经理	完成度统计、验收清单、后续计划

---

🎯 核心功能速览

Param 绑定模式（三种来源）

模式	按钮	用途	示例
静态值	📝	固定参数值	batch_size = 100
Context	🔗	从变量读取	threshold = $LoaderNode.avg
暴露端口	⚡	从连线接收	filter_mode ← input port

连线 EdgeType（数据维度编码）

类型	粗细	颜色	数据例子
数组	4px	蓝色	DataTable, Array, List
标量	3px	橙色	String, Integer, Float

暴露端口（两种端口）

端口	颜色	来源	用途
Param ⚡	粉红	参数暴露	接收其他节点的值
Context 📋	绿色	Context 暴露	输出给下游节点

---

🧪 验证功能

浏览器控制台测试

打开 F12 → 粘贴下列代码快速验证：

// 加载测试脚本
const script = document.createElement('script')
script.src = '/TEST_INTEGRATION.js'
document.head.appendChild(script)

// 运行完整测试（需创建至少一个节点）
await testCompleteWorkflow()

测试项:

• ✅ testParamBinding() - Param 绑定按钮
• ✅ testEdgeType() - 连线粗细
• ✅ testExposedPorts() - 暴露端口
• ✅ testNodeDataStructure() - 数据结构
• ✅ testAPIResponse() - API 响应

---

🔧 开发指南

如何添加新的 Param 绑定模式

// 1. 在 useStore.ts 添加新模式
export type ParamBindingMode = 'static' | 'context' | 'exposed' | 'formula'

// 2. 在 Inspector.tsx 添加按钮
<button onClick={() => handleModeChange('formula')}>🧮 公式</button>

// 3. 添加对应的输入控件
if (binding.mode === 'formula') {
  // <FormulaEditor />
}

如何为 UniversalNode 添加新的暴露端口类型

// 在 UniversalNode.tsx 中扩展
const allOutputs = [
  ...outputs,
  ...(exposedPorts.contexts || []),
  ...(exposedPorts.variables || [])  // 新增类型
]

---

📖 工作流示例

例子 1: 简单的参数传递

CSV Loader
 └─ 暴露参数: batch_size = 50 (📝 静态值)
   └─ Transform
       └─ threshold = $LoaderNode.max (🔗 Context)
         └─ Visualizer

例子 2: 动态参数（暴露端口）

Range Generator (输出 [1,2,3,4,5])
  │
  └─ Batch Processor
      ├─ batch_size ⚡ (暴露端口)
      │  ↑ (从 Range 输出连线)
      └─ Transform

例子 3: Context 链式传递

Loader1 → ctx: row_count
  │
  └─ Processor → param: threshold = $Loader1.row_count (🔗 Context)
       │
       └─ Filter → param: limit = $Processor.filtered_count
            │
            └─ Visualizer

---

❓ 常见问题

Q: 如何看到节点的暴露端口？

A:

1. 选中节点查看 Inspector
2. 参数选择 ⚡ 暴露端口
3. 节点上会出现粉红色新端口，内部会显示 "⚡ Params: ..."

Q: Context 下拉列表为什么是空的？

A:

1. 检查是否有上游节点
2. 上游节点需要暴露 context_vars
3. 确保选择了 🔗 Context 模式

Q: 连线粗细什么时候才会变化？

A: 创建连线时根据源节点的输出类型自动推断：

• Array/List/Table → 4px 粗线
• 其他类型 → 3px 细线

---

🐛 已知限制

问题	影响	规划修复
删除上游节点不清空 contextRef	低	v0.3.1
参数名变更未同步 bindings	低	v0.3.1
暴露端口仅前端支持，后端未处理	中	v0.4.0
无 Dimension Mode（EXPAND/COLLAPSE/BROADCAST）	低	v0.5.0

---

📞 获取帮助

• 📖 用户文档: USER_GUIDE_v0.3.0.md
• 🔧 技术文档: IMPLEMENTATION_SUMMARY.md
• ✅ 测试指南: FEATURES_TEST.md
• 📋 验收清单: ACCEPTANCE_CHECKLIST.md

---

📝 更新日志

v0.3.0 (2024-01)

• ✨ 新增 Param 绑定模式系统（static/context/exposed）
• 🎨 新增 EdgeType 视觉编码（数组粗线、标量细线）
• 📌 新增暴露端口显示（Param 输入、Context 输出）
• 📚 完整文档和测试工具

v0.2.0 (前版本)

• ✅ 四大属性 API 规范化
• ✅ 基础节点系统

---

快速链接: 用户指南 | 技术文档 | 测试指南 | 验收清单

版本: v0.3.0 | 状态: ✅ 生产就绪 | 最后更新: 2024-01