🎨 TraceStudio

将 Unreal Insights 从"只读查看器"进化为"可编程实验室"

TraceStudio 是一个基于 ComfyUI 设计理念的 Unreal Engine 性能数据分析工具。通过可视化节点编辑器，让复杂的数据分析流程变得直观、可复用、可分享。

✨ 核心特性

• 🎯 节点式工作流 - 像搭积木一样构建分析逻辑
• 🔍 实时预览 - 采样模式快速验证，全量模式精确分析
• 📊 可视化优先 - 所有数据流通过连线可见，拒绝黑盒
• 🎨 ComfyUI 风格 - 深色工业风，保护工程师视力
• 🔌 可扩展 - 支持自定义节点和插件系统
• 💾 工作流资产化 - .tsflow 文件即文档

🚀 快速开始

前置要求

• Python 3.11+ (推荐使用 Conda)
• Node.js 18+
• npm 或 yarn

一键启动（推荐：Conda + 本地开发）

# 1. 创建并激活 Python 环境（推荐）
conda create -n tracestudio python=3.11
conda activate tracestudio

conda remove --name tracestudio --all
conda remove --name base --all
# 2. 安装后端依赖
cd server
pip install -r requirements.txt

# 3. 安装前端依赖
cd ../web
npm install

# 4. 启动服务（使用仓库根目录的一键脚本）
cd .. && .\start.ps1

然后访问：

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

详细的设置说明请查看 SETUP.md

📖 项目架构

TraceStudio/
├── web/              # React + TypeScript 前端
│   ├── src/
│   │   ├── components/    # UI 组件
│   │   ├── stores/        # Zustand 状态管理
│   │   └── utils/         # 工具函数
│   └── package.json
│
├── server/           # FastAPI + Python 后端
│   ├── main.py           # 服务入口
│   └── requirements.txt
│
├── start.ps1         # 启动脚本
├── SETUP.md          # 安装指南
└── README_PHASE1.md  # 第一阶段完成报告

🎯 开发阶段

✅ 第一阶段：核心功能布局（已完成）

• 智能算子侧边栏（搜索、分类、拖拽）
• 全局控制顶栏（运行、状态、配置）
• 响应式画布与侧板（编辑、预览、属性）
• 基础后端 API（插件列表、节点预览）

查看完整的功能列表：README_PHASE1.md

✅ 第二阶段：核心功能联通（已完成）

• 算子库动态加载（GET /plugins）
• 节点预览真实调用（POST /node/preview）
• 执行状态反馈（POST /graph/execute）
• API 通讯层（统一请求管理）
• 视觉反馈系统（状态灯、连线动画、提示消息）

查看完整的功能列表：PHASE2_COMPLETE.md

🚧 第三阶段：真实数据处理（计划中）

• DAG 执行引擎
• 节点数据传递
• 采样策略实现
• 缓存系统

🔮 第三阶段：Unreal Insights 集成（计划中）

• UTrace 文件解析
• 性能数据节点
• 可视化图表组件

🌟 第四阶段：高级功能（计划中）

• 工作流保存/加载
• 自定义节点支持
• 用户系统

🎨 设计哲学

ComfyUI 化的交互逻辑

"一切皆图"：所有的分析路径必须通过节点连线可见。禁止隐藏复杂的黑盒逻辑。

1. 原子化算子 - 将复杂分析拆解为极简算子
2. 实时反馈环 - 点击运行 → 节点流动 → 结果即现
3. 数据精炼厂 - 不造轮子，专注二次加工

专家级审美

• 极简工程风 - shadcn/ui 风格，深色模式
• 逻辑即文档 - .tsflow 工作流文件就是分析报告
• 透明性 - 错误可在图面上定位

查看完整的设计理念：.github/agents/utrace.agent.md

🛠️ 技术栈

前端：

• React 19
• TypeScript 5.9
• Zustand (状态管理)
• React Flow (节点编辑器)
• Vite (构建工具)
• Tailwind CSS 4

后端：

• Python 3.11
• FastAPI (Web 框架)
• Uvicorn (ASGI 服务器)
• Polars (数据处理)

📚 文档

• SETUP.md - 安装和配置指南
• README_PHASE1.md - 第一阶段完成报告
• PHASE1_COMPLETE.md - 详细的功能清单
• server/README.md - 后端 API 文档

🎯 使用场景

1. 性能瓶颈分析

UTraceLoader → TimeRangeFilter → FrameTimeChart
                                → CPUProfileFlame

2. 内存趋势监控

UTraceLoader → MemoryStatsAggregator → TimeSeriesChart

3. 自定义数据处理

CSVLoader → FilterRows → SelectColumns → CustomPython → Export

🤝 贡献

TraceStudio 目前处于早期开发阶段。欢迎：

• 🐛 报告 Bug
• 💡 提出功能建议
• 📝 改进文档
• 🔧 提交 Pull Request

📄 开源协议

MIT License

🙏 致谢

• ComfyUI - 设计灵感来源
• React Flow - 节点图库
• FastAPI - Python Web 框架
• Unreal Engine - 游戏引擎

📞 联系方式

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

---

当前版本: v0.1.0
开发状态: ✅ 第一阶段已完成
最后更新: 2026-01-07

---

Made with ❤️ for Unreal Engine developers