207 lines
5.4 KiB
Markdown
207 lines
5.4 KiB
Markdown
# 🎨 TraceStudio
|
||
|
||
> 将 Unreal Insights 从"只读查看器"进化为"可编程实验室"
|
||
|
||
TraceStudio 是一个基于 **ComfyUI 设计理念**的 Unreal Engine 性能数据分析工具。通过可视化节点编辑器，让复杂的数据分析流程变得直观、可复用、可分享。
|
||
|
||
## ✨ 核心特性
|
||
|
||
- 🎯 **节点式工作流** - 像搭积木一样构建分析逻辑
|
||
- 🔍 **实时预览** - 采样模式快速验证，全量模式精确分析
|
||
- 📊 **可视化优先** - 所有数据流通过连线可见，拒绝黑盒
|
||
- 🎨 **ComfyUI 风格** - 深色工业风，保护工程师视力
|
||
- 🔌 **可扩展** - 支持自定义节点和插件系统
|
||
- 💾 **工作流资产化** - .tsflow 文件即文档
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- **Python 3.11+** (推荐使用 Conda)
|
||
- **Node.js 18+**
|
||
- **npm 或 yarn**
|
||
|
||
### 一键启动（推荐：Conda + 本地开发）
|
||
|
||
```powershell
|
||
# 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](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 # 第一阶段完成报告
|
||
```
|
||
|
||
## 🎯 开发阶段
|
||
|
||
### ✅ 第一阶段：核心功能布局（已完成）
|
||
|
||
- [x] 智能算子侧边栏（搜索、分类、拖拽）
|
||
- [x] 全局控制顶栏（运行、状态、配置）
|
||
- [x] 响应式画布与侧板（编辑、预览、属性）
|
||
- [x] 基础后端 API（插件列表、节点预览）
|
||
|
||
查看完整的功能列表：[README_PHASE1.md](README_PHASE1.md)
|
||
|
||
### ✅ 第二阶段：核心功能联通（已完成）
|
||
|
||
- [x] 算子库动态加载（GET /plugins）
|
||
- [x] 节点预览真实调用（POST /node/preview）
|
||
- [x] 执行状态反馈（POST /graph/execute）
|
||
- [x] API 通讯层（统一请求管理）
|
||
- [x] 视觉反馈系统（状态灯、连线动画、提示消息）
|
||
|
||
查看完整的功能列表：[PHASE2_COMPLETE.md](PHASE2_COMPLETE.md)
|
||
|
||
### 🚧 第三阶段：真实数据处理（计划中）
|
||
|
||
- [ ] DAG 执行引擎
|
||
- [ ] 节点数据传递
|
||
- [ ] 采样策略实现
|
||
- [ ] 缓存系统
|
||
|
||
### 🔮 第三阶段：Unreal Insights 集成（计划中）
|
||
|
||
- [ ] UTrace 文件解析
|
||
- [ ] 性能数据节点
|
||
- [ ] 可视化图表组件
|
||
|
||
### 🌟 第四阶段：高级功能（计划中）
|
||
|
||
- [ ] 工作流保存/加载
|
||
- [ ] 自定义节点支持
|
||
- [ ] 用户系统
|
||
|
||
## 🎨 设计哲学
|
||
|
||
### ComfyUI 化的交互逻辑
|
||
|
||
> "一切皆图"：所有的分析路径必须通过节点连线可见。禁止隐藏复杂的黑盒逻辑。
|
||
|
||
1. **原子化算子** - 将复杂分析拆解为极简算子
|
||
2. **实时反馈环** - 点击运行 → 节点流动 → 结果即现
|
||
3. **数据精炼厂** - 不造轮子，专注二次加工
|
||
|
||
### 专家级审美
|
||
|
||
- **极简工程风** - shadcn/ui 风格，深色模式
|
||
- **逻辑即文档** - .tsflow 工作流文件就是分析报告
|
||
- **透明性** - 错误可在图面上定位
|
||
|
||
查看完整的设计理念：[.github/agents/utrace.agent.md](.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](SETUP.md) - 安装和配置指南
|
||
- [README_PHASE1.md](README_PHASE1.md) - 第一阶段完成报告
|
||
- [PHASE1_COMPLETE.md](PHASE1_COMPLETE.md) - 详细的功能清单
|
||
- [server/README.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](https://github.com/comfyanonymous/ComfyUI) - 设计灵感来源
|
||
- [React Flow](https://reactflow.dev/) - 节点图库
|
||
- [FastAPI](https://fastapi.tiangolo.com/) - Python Web 框架
|
||
- [Unreal Engine](https://www.unrealengine.com/) - 游戏引擎
|
||
|
||
## 📞 联系方式
|
||
|
||
- GitHub Issues: (待创建)
|
||
- Email: (待添加)
|
||
|
||
---
|
||
|
||
**当前版本**: v0.1.0
|
||
**开发状态**: ✅ 第一阶段已完成
|
||
**最后更新**: 2026-01-07
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
Made with ❤️ for Unreal Engine developers
|
||
</p>
|