109 lines
5.3 KiB
Markdown
109 lines
5.3 KiB
Markdown
每次回复之前，请确认一定要以中文进行回复与思考。
|
||
🏛️ 宏观愿景 (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`
|
||
|
||
---
|
||
|
||
如有不清楚或遗漏之处，请反馈以便补充完善。
|