TraceStudio-dev/README.md

# 🎨 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

# 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>