TraceStudio-dev/.github/copilot-instructions.md

每次回复之前，请确认一定要以中文进行回复与思考。 🏛️ 宏观愿景 (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

---

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