evotraders/docs/project-layout.md

Project Layout

这个文件只描述当前仓库目录的职责划分，不记录历史迁移过程。

如果你想知道“系统现在怎么工作”，优先看 current-architecture.md。 如果你想知道“这个目录现在应该怎么理解”，看本文。

顶层目录

主线代码

• backend/
  • 后端运行时、服务、API、Pipeline、Agent、工具与测试
• frontend/
  • React/Vite 前端
• shared/
  • 前后端共享 schema 与 client 封装

当前有效的数据与状态目录

• runs/
  • 运行态真相源
  • 每个 run_id 下保存 BOOTSTRAP、agent 资产、state、logs、dashboard 导出
• workspaces/
  • 设计时注册表
  • 用于 control-plane CRUD，不是默认运行时执行目录
• data/
  • 项目使用的数据资产与本地数据文件

文档与部署

• docs/
  • 当前仍维护的架构、兼容边界、路线图、目录说明
• services/
  • 服务边界说明
• deploy/
  • 部署示例、systemd、nginx 配置
• scripts/
  • 启动、检查、烟测与辅助脚本

项目入口与元数据

• README.md
  • 英文主说明
• README_zh.md
  • 中文主说明
• pyproject.toml
  • Python 项目元数据与依赖
• start-dev.sh
  • 本地默认开发入口
• start.sh
  • 偏生产风格的本地启动入口

本地环境目录

这些目录通常只对当前机器有效，不应作为架构事实源：

• .venv/
  • 本地 Python 虚拟环境
• .pydeps/
  • 本地依赖落地目录
• .omc/
  • 本地工具状态
• .codex/
  • 本地代理/工具状态

阅读原则

• 看运行时行为，优先从 backend/、frontend/、runs/ 开始
• 看控制面编辑与设计态资产，优先看 workspaces/
• 看服务边界，优先看 services/README.md
• 看目录时，不要把本地环境目录当成项目结构的一部分
• 新增目录前，先判断它属于“主线代码 / 运行态数据 / 文档部署 / 本地环境”中的哪一类

当前约束

• 不再新增参考仓、副本仓、样例快照目录到顶层
• 不再把测试输出、PID、构建产物、缓存目录提交到仓库
• 运行态相关的新文件优先放到 runs/<run_id>/
• 设计态注册相关的新文件优先放到 workspaces/