ouczbs/TraceStudio-dev

Fork 0

Boshuang Zhao 60a53876f7 Tracestudio web 1.0

2026-01-07 19:34:45 +08:00

9.9 KiB

Raw Blame History

🎉 TraceStudio 第一阶段完成报告

📝 执行摘要

TraceStudio 第一阶段核心功能布局已成功完成！我们基于 ComfyUI 设计哲学，实现了一个现代化的节点式数据分析工具的前端界面和基础后端 API。

✅ 完成清单

前端开发 (React + TypeScript)

1️⃣ Step 1.1: 智能算子侧边栏 (NodePalette)

实现功能：

✅ 搜索框置顶固定，不随滚动移动
✅ 实时搜索过滤，输入即时响应
✅ 分类折叠管理（Loaders、Transforms、Filters、Visualizers）
✅ 跨类别搜索支持
✅ 拖拽视觉反馈（透明度、边框高亮）
✅ 每种类别独特的 emoji 图标
✅ 支持预览的节点显示 ⚡ 徽章
✅ 显示每个类别的算子数量
✅ 搜索框清除按钮

技术亮点：

完全自定义的折叠逻辑，无需第三方组件
优雅的 hover 效果和过渡动画
响应式设计，支持滚动

2️⃣ Step 1.2: 全局控制顶栏 (HeaderBar)

实现功能：

✅ 醒目的主运行按钮（渐变色、大尺寸）
✅ 运行状态指示灯（带呼吸动画）
✅ 实时图统计（节点数、连接数）
✅ 采样率四档选择（1%、10%、25%、100%）
✅ 时间窗口配置
✅ 视图切换按钮（隐藏/显示侧边栏）
✅ 语言切换（中文/English）
✅ 设置入口按钮
✅ 开发版本提示条

技术亮点：

渐变背景和阴影效果
按钮状态根据图的有效性自动禁用
所有交互元素都有 hover 反馈
CSS 动画（pulse 呼吸效果）

3️⃣ Step 1.3: 响应式画布与侧板

Workspace (画布编辑器)：

✅ React Flow 完整集成
✅ 节点拖拽放置
✅ 自动坐标转换（考虑缩放和平移）
✅ 背景网格
✅ 小地图导航
✅ 缩放控件
✅ 空状态引导界面
✅ 运行时连线动画
✅ 点击画布取消选择

Inspector (属性检查器)：

✅ 空状态概览面板（显示图统计）
✅ 节点属性编辑
✅ 数据预览功能
✅ 全局配置显示
✅ 优雅的卡片式布局
✅ 滚动支持
✅ 错误提示
✅ 加载状态

AppShell (主布局)：

✅ 响应式三栏布局
✅ 侧边栏动态宽度（可折叠）
✅ 平滑的展开/收起动画
✅ 深色主题配色
✅ 阴影层次感

4️⃣ 设置模态框 (SettingsModal)

实现功能：

✅ 模态对话框
✅ 背景遮罩和模糊效果
✅ 语言设置
✅ 关于信息
✅ 淡入和滑动动画
✅ 点击外部关闭

后端开发 (FastAPI + Python)

基础架构

实现功能：

✅ FastAPI 框架搭建
✅ CORS 跨域支持
✅ 自动 API 文档（Swagger UI）
✅ 健康检查端点

核心 API

1. GET /plugins - 算子列表

返回 8 种预定义算子
包含完整的元数据（显示名称、类别、参数模式）
支持 4 大类别：Loaders、Transforms、Filters、Visualizers

2. POST /node/preview - 节点预览

接收节点定义
返回模拟数据
包含列名和数据行

3. POST /graph/execute - 图执行（占位）

接收完整计算图
返回执行状态

测试数据

8 种算子类型：

CSVLoader - CSV 数据加载器
UTraceLoader - UTrace 文件加载器
FilterRows - 行过滤器
SelectColumns - 列选择器
Aggregator - 数据聚合
TimeRangeFilter - 时间范围过滤
ChartVisualizer - 图表可视化
TableOutput - 表格输出

🎨 设计亮点

ComfyUI 风格体现

节点即视觉 - 所有数据流通过连线可见
原子化算子 - 每个节点职责单一
搜索优先 - 快速定位算子
深色工业风 - 保护视力的配色
即时反馈 - 实时的视觉响应

UI/UX 细节

🎯 一致的 Hover 效果 - 所有可交互元素
🎨 渐变按钮 - 主要操作突出显示
✨ 平滑动画 - 0.15-0.3s 过渡
📊 信息密度 - 紧凑但清晰
🔍 视觉层次 - 颜色/大小/间距区分

技术栈

前端：

React 19
TypeScript 5.9
Zustand 4.4（状态管理）
React Flow 11.11（节点编辑器）
Vite 7（构建工具）
Tailwind CSS 4（样式）

后端：

Python 3.11
FastAPI 0.104
Uvicorn（ASGI 服务器）
Polars/Pandas（数据处理，已预留）

📁 项目结构

TraceStudio/
├── web/                          # React 前端
│   ├── src/
│   │   ├── components/          # UI 组件
│   │   │   ├── AppShell.tsx     ✅ 主布局容器（120行）
│   │   │   ├── HeaderBar.tsx    ✅ 全局控制栏（276行）
│   │   │   ├── NodePalette.tsx  ✅ 算子侧边栏（266行）
│   │   │   ├── Workspace.tsx    ✅ 画布编辑器（137行）
│   │   │   ├── Inspector.tsx    ✅ 属性检查器（385行）
│   │   │   └── SettingsModal.tsx✅ 设置弹窗（220行）
│   │   ├── stores/
│   │   │   └── useStore.ts      ✅ 状态管理（120行）
│   │   ├── utils/
│   │   │   └── nodeRegistry.ts
│   │   ├── i18n.ts              ✅ 国际化
│   │   └── ...
│   └── package.json             ✅ 已添加 zustand
│
├── server/                      # Python 后端
│   ├── main.py                  ✅ FastAPI 入口（250行）
│   ├── requirements.txt         ✅ 依赖列表
│   └── README.md                ✅ 后端文档
│
├── start.ps1                    ✅ 启动脚本
├── SETUP.md                     ✅ 设置指南
├── PHASE1_COMPLETE.md           ✅ 完成总结
└── README.md                    项目说明

代码统计：

前端组件：6 个文件，约 1400 行 TypeScript
后端 API：1 个文件，约 250 行 Python
文档：4 个 Markdown 文件

🚀 如何启动

快速启动（推荐）

# 1. 安装依赖
cd server
pip install -r requirements.txt

cd ../web
npm install

# 2. 启动服务
cd ..
.\start.ps1

手动启动

终端 1 - 后端：

cd server
python main.py

终端 2 - 前端：

cd web
npm run dev

访问地址

🎨 前端界面: http://localhost:5173
📡 后端 API: http://127.0.0.1:8000
📊 API 文档: http://127.0.0.1:8000/docs

✅ 测试清单

前端功能测试

搜索功能：输入 "CSV" 能过滤显示相关节点
节点拖拽：从侧边栏拖拽 "CSV 数据加载器" 到画布
节点选择：点击画布中的节点，右侧显示属性
属性编辑：修改节点的 file_path 参数
视图切换：点击 📦 和 ⚙️ 按钮切换侧边栏
语言切换：Header 中切换中文/English
运行按钮：点击 ▶ Run 按钮，状态灯变绿
概览面板：未选中节点时，右侧显示图统计
设置对话框：点击设置按钮打开模态框

后端 API 测试

健康检查：访问 http://127.0.0.1:8000 返回 JSON
插件列表：访问 http://127.0.0.1:8000/plugins 返回 8 种算子
API 文档：访问 http://127.0.0.1:8000/docs 显示 Swagger UI
预览功能：在前端点击 "运行预览" 返回模拟数据

视觉验证

深色主题：整体采用深蓝黑色调
悬停效果：鼠标移到按钮/节点/算子卡片时有视觉反馈
动画流畅：展开/收起侧边栏动画平滑
响应式：侧边栏折叠时，画布自动扩展

🎯 下一阶段路线图

第二阶段：数据流引擎（2-3 周）

核心目标：实现真实的数据处理能力

节点执行引擎
- DAG 拓扑排序
- 节点依赖解析
- 异步执行管线
数据传递机制
- 节点输入/输出端口定义
- 数据类型校验
- 缓存系统（Parquet）
采样策略
- 粗线（10% 采样，快速预览）
- 细线（100% 全量，生产运行）
- 自动采样率调整
真实算子实现
- CSVLoader 读取本地文件
- FilterRows 数据过滤
- Aggregator 聚合计算

第三阶段：Unreal Insights 集成（3-4 周）

UTrace 解析器
- 调用 UnrealInsights 命令行工具
- 解析导出的 CSV/JSON
- 数据预处理
性能数据节点
- FrameTimeLoader
- CPUProfileLoader
- MemoryStatsLoader
可视化组件
- 时间序列图表（帧时间）
- 火焰图（CPU Profile）
- 内存瀑布图

第四阶段：高级功能（4-6 周）

工作流管理
- .tsflow 文件格式
- 保存/加载工作流
- 工作流模板
自定义节点
- Python 脚本节点
- 自定义节点 API
- 插件系统
用户系统
- 用户目录隔离
- 工作流分享
- 团队协作

📚 参考资料

ComfyUI GitHub - 节点编辑器灵感来源
React Flow Docs - 节点图库文档
FastAPI Docs - Python Web 框架
Unreal Insights - 性能分析工具

🙏 致谢

感谢 ComfyUI 项目提供的优秀设计理念，以及 React Flow、FastAPI 等开源项目的支持。

📞 联系方式

如有问题或建议，请通过以下方式联系：

GitHub Issues: (待创建)
Email: (待添加)

状态: ✅ 第一阶段完成
日期: 2026-01-07
版本: v0.1.0
下一里程碑: 第二阶段 - 数据流引擎

🚦 现在就试试吧！

# 克隆项目（如果还没有）
# cd TraceStudio

# 安装依赖
cd server && pip install -r requirements.txt
cd ../web && npm install

# 启动！
cd .. && .\start.ps1

然后访问 http://localhost:5173 开始探索 TraceStudio！ 🎉

9.9 KiB Raw Blame History Unescape Escape

🎉 TraceStudio 第一阶段完成报告

📝 执行摘要

✅ 完成清单

前端开发 (React + TypeScript)

1️⃣ Step 1.1: 智能算子侧边栏 (NodePalette)

2️⃣ Step 1.2: 全局控制顶栏 (HeaderBar)

3️⃣ Step 1.3: 响应式画布与侧板

4️⃣ 设置模态框 (SettingsModal)

后端开发 (FastAPI + Python)

基础架构

核心 API

测试数据

🎨 设计亮点

ComfyUI 风格体现

UI/UX 细节

技术栈

📁 项目结构

🚀 如何启动

快速启动（推荐）

手动启动

访问地址

✅ 测试清单

前端功能测试

后端 API 测试

视觉验证

🎯 下一阶段路线图

第二阶段：数据流引擎（2-3 周）

第三阶段：Unreal Insights 集成（3-4 周）

第四阶段：高级功能（4-6 周）

📚 参考资料

🙏 致谢

📞 联系方式

🚦 现在就试试吧！

9.9 KiB

Raw Blame History