247 lines
6.3 KiB
Markdown
247 lines
6.3 KiB
Markdown
# 🎉 TraceStudio v0.3.0 - 快速开始
|
||
|
||
> **新功能**: Param 绑定模式 + EdgeType 视觉编码 + 暴露端口系统
|
||
|
||
---
|
||
|
||
## 🚀 三分钟快速体验
|
||
|
||
### 第一步：启动开发环境
|
||
```bash
|
||
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](./USER_GUIDE_v0.3.0.md) | **最终用户** | 如何使用新功能、工作流示例、常见问题 |
|
||
| [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) | **开发者** | 技术细节、API 变更、集成说明 |
|
||
| [FEATURES_TEST.md](./FEATURES_TEST.md) | **测试者** | 测试场景、验收标准、已知问题 |
|
||
| [ACCEPTANCE_CHECKLIST.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 → 粘贴下列代码快速验证：
|
||
|
||
```javascript
|
||
// 加载测试脚本
|
||
const script = document.createElement('script')
|
||
script.src = '/TEST_INTEGRATION.js'
|
||
document.head.appendChild(script)
|
||
|
||
// 运行完整测试（需创建至少一个节点）
|
||
await testCompleteWorkflow()
|
||
```
|
||
|
||
**测试项**:
|
||
- ✅ testParamBinding() - Param 绑定按钮
|
||
- ✅ testEdgeType() - 连线粗细
|
||
- ✅ testExposedPorts() - 暴露端口
|
||
- ✅ testNodeDataStructure() - 数据结构
|
||
- ✅ testAPIResponse() - API 响应
|
||
|
||
---
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 如何添加新的 Param 绑定模式
|
||
|
||
```typescript
|
||
// 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 添加新的暴露端口类型
|
||
|
||
```typescript
|
||
// 在 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](./USER_GUIDE_v0.3.0.md)
|
||
- 🔧 **技术文档**: [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)
|
||
- ✅ **测试指南**: [FEATURES_TEST.md](./FEATURES_TEST.md)
|
||
- 📋 **验收清单**: [ACCEPTANCE_CHECKLIST.md](./ACCEPTANCE_CHECKLIST.md)
|
||
|
||
---
|
||
|
||
## 📝 更新日志
|
||
|
||
**v0.3.0** (2024-01)
|
||
- ✨ 新增 Param 绑定模式系统（static/context/exposed）
|
||
- 🎨 新增 EdgeType 视觉编码（数组粗线、标量细线）
|
||
- 📌 新增暴露端口显示（Param 输入、Context 输出）
|
||
- 📚 完整文档和测试工具
|
||
|
||
**v0.2.0** (前版本)
|
||
- ✅ 四大属性 API 规范化
|
||
- ✅ 基础节点系统
|
||
|
||
---
|
||
|
||
**快速链接**: [用户指南](./USER_GUIDE_v0.3.0.md) | [技术文档](./IMPLEMENTATION_SUMMARY.md) | [测试指南](./FEATURES_TEST.md) | [验收清单](./ACCEPTANCE_CHECKLIST.md)
|
||
|
||
**版本**: v0.3.0 | **状态**: ✅ 生产就绪 | **最后更新**: 2024-01
|