每次回复之前，请确认一定要以中文进行回复与思考。
🏛️ 宏观愿景 (High-Level Vision)

TraceStudio 的目标是将 Unreal Insights 从一个“只读的查看器”进化为“可编程的实验室”。它不是在做数据展示，而是在做分析逻辑的资产化。

🎨 核心风格范式 (The Design Philosophy)
1. ComfyUI 化的交互逻辑

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

    原子化算子：提倡将复杂的分析拆解为极简的算子（Loader -> Filter -> Aggregator -> Visualizer）。

    实时反馈环：就像 Stable Diffusion 生成图像一样，性能数据的处理也应该是“点击运行 -> 节点流动 -> 结果即现”的感官体验。

2. “数据精炼厂”定位

    不造轮子：底层解析交给 Unreal Insights，我们只做Unreal Insights解析导出后的数据二次加工。

    采样驱动交互：宏观上坚持“预览用采样，生产用全量”的策略，确保海量数据下依然有丝滑的图表交互。

3. 专家级审美

    极简工程风：界面参考 shadcn/ui 的工业感，配色方案必须保护长期盯着数据的工程师视力（深色模式、低饱和度连线）。

    逻辑即文档：保存的工作流文件（.tsflow）本身就是一份完美的分析报告。

🕹️ 核心原则 (Guiding Principles)

    协议优先于实现： Agent 关心的是节点之间如何“对话”（数据契约），而不是具体的算子内部用了哪个库。

    可扩展性边界：任何新功能必须考虑“如果用户想用 Python 自己写这个逻辑，接口是否足够友好？”。

    透明性：当数据流通过程中出现错误或参数缺失，系统必须能够宏观地在图面上定位问题，而不是仅仅打印控制台报错。

⚠️ 负面约束 (What We Avoid)

    拒绝“报表化”：如果一个功能做成了不可拆解的巨大 DashBoard，Agent 必须予以否决。

    拒绝“中心化”：避免将过多的配置项埋在全局设置里，尽可能让配置项出现在节点面板上。

    拒绝“黑盒化”：严禁出现无法追溯数据源头的计算步骤。

📡 如何与用户合作

    决策咨询：当用户在两个技术路线间纠结时，Agent 依据“ComfyUI 风格一致性”给出建议。

    逻辑审查：用户提出功能设想时，Agent 审查该设想是否破坏了“计算图”的纯粹性。

项目核心结构（强烈建议多多参考comfyui）
TraceStudio/
├── web/                # React + React Flow (npm 环境)
└── server/             # FastAPI + Polars (Python 环境 conda activate tracestudio)

# 🧑‍💻 TraceStudio AI Coding Agent Instructions

## 1. 项目架构总览
- **TraceStudio** 由 `web/` (React + TypeScript + Vite) 前端 和 `server/` (FastAPI + Python + Polars) 后端组成。
- 设计理念参考 ComfyUI：所有分析逻辑以节点图方式表达，禁止黑盒和中心化。
- 主要数据流：前端通过 API 与后端交互，后端负责数据解析、节点执行和文件管理。

## 2. 关键开发流程
- **一键启动**：
  - `cd server  && conda activate tracestudio && pip install -r requirements.txt`
  - `cd ../web && npm install`
  - `cd .. && ./start.ps1` (Windows)
- **前端开发**：
  - `npm run dev` 启动本地开发服务器，访问 http://localhost:5173
  - API 地址由 `VITE_API_BASE_URL` 环境变量控制，详见 `web/README.md`
- **后端开发**：
  - 后端环境位于虚拟环境中 conda activate tracestudio; python -m uvicorn server.main:app --reload --host 127.0.0.1 --port 8000
  - `python main.py` 启动主服务，或 `python tests/web1.1_server.py` 启动旧版测试服务
  - 配置项集中于 `server/system_config.yaml`

## 3. 代码组织与约定
- **前端**：
  - 组件、状态、工具函数分别在 `src/components/`, `src/stores/`, `src/utils/`
  - 所有 API 调用统一在 `src/utils/api.ts`
  - 采用深色工程风格，UI 参考 shadcn/ui
- **后端**：
  - 核心代码在 `app/core/`, API 路由在 `app/api/`, 节点实现在 `app/nodes/`, 扩展节点在 `custom_nodes/`
  - 文件名用 `snake_case.py`，类名用 `PascalCase`
  - 路径安全、文件名验证见 `app/core/security.py`
  - 云存储结构见 `cloud/users/{username}/`

## 4. 扩展与自定义
- 新节点插件放在 `server/custom_nodes/`，需继承 `TraceNode` 并实现 `get_metadata()` 和 `execute()`
- 前端节点库和类型系统与后端保持一致，建议参考 ComfyUI 节点设计

## 5. 重要约束与风格
- 禁止黑盒逻辑和不可拆解的报表式功能
- 配置项优先出现在节点面板，避免全局中心化
- 错误需在图面上可定位，避免仅控制台报错
- 采样驱动交互：预览用采样，生产用全量

## 6. 典型场景示例
- 性能分析：`UTraceLoader → TimeRangeFilter → FrameTimeChart`
- 内存监控：`UTraceLoader → MemoryStatsAggregator → TimeSeriesChart`
- 自定义处理：`CSVLoader → FilterRows → CustomPython → Export`

## 7. 参考与文档
- 设计理念与风格见 `.github/agents/utrace.agent.md`
- 后端 API 详见 `server/README.md`
- 前端开发说明见 `web/README.md`
- 安装与配置见 `SETUP.md`

---

如有不清楚或遗漏之处，请反馈以便补充完善。