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