81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
# 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/`
|