# Agent Project Structure 规范

## 目录结构规范

### 标准结构

```
agent-project/
├── projects/          # 项目文件目录
│   ├── project-a/
│   │   ├── src/
│   │   ├── tests/
│   │   └── docs/
│   └── project-b/
├── log/               # 日志文件目录
│   ├── app.log
│   └── error.log
├── temp/              # 临时文件目录（截图、缓存等）
│   ├── screenshots/
│   └── cache/
├── config/            # 配置文件目录
│   ├── settings.json
│   └── secrets.json
├── data/              # 数据文件目录
│   ├── input/
│   └── output/
├── scripts/           # 脚本文件目录
└── docs/              # 文档目录
```

### 目录说明

| 目录 | 说明 | 包含内容 |
|------|------|----------|
| `projects/` | 项目文件目录 | 所有项目代码、资源文件 |
| `log/` | 日志文件目录 | 应用运行日志、错误日志 |
| `temp/` | 临时文件目录 | 截图、缓存、临时数据 |
| `config/` | 配置文件目录 | 环境配置、密钥、参数 |
| `data/` | 数据文件目录 | 输入数据、输出结果、中间数据 |
| `scripts/` | 脚本文件目录 | 自定义脚本、工具脚本 |
| `docs/` | 文档目录 | 项目文档、说明文档 |

## 文件分类原则

### 1. 项目文件
- 与项目核心功能直接相关的代码
- 配置文件（非环境敏感）
- 资源文件（图片、样式等）
- **不应混入**：日志、临时文件、密钥

### 2. 日志文件
- 应用运行时生成的日志
- 调试信息、错误堆栈
- **统一存放**：`log/` 目录
- **命名约定**：`app.log`、`error.log`、`access.log`

### 3. 临时文件
- 运行时生成的临时数据
- 截图、缓存、会话数据
- **与正式文件分离**：`temp/` 目录
- **子目录**：`temp/screenshots/`、`temp/cache/`

### 4. 配置文件
- 环境配置、密钥、参数
- **敏感信息**：使用环境变量或密钥管理
- **统一存放**：`config/` 目录

### 5. 数据文件
- 输入数据、输出结果
- 中间数据、处理结果
- **统一存放**：`data/` 目录

## 命名约定

- 目录名：小写字母，使用连字符 `-` 分隔单词
- 文件名：小写字母，使用连字符 `-` 分隔单词
- 配置文件：使用 `.json` 或 `.yaml` 格式
- 日志文件：使用 `.log` 扩展名

## 常见问题

### Q: 日志文件可以放在项目目录下吗？
**A**: 不建议。日志文件是运行时生成的临时数据，应该与项目代码分离。统一放在 `log/` 目录便于管理和清理。

### Q: 截图应该放在哪里？
**A**: 截图属于临时文件，应该放在 `temp/screenshots/` 目录。这样可以避免与正式的项目资源文件混淆。

### Q: 配置文件中的密钥如何处理？
**A**: 敏感信息不应直接写入配置文件。建议使用环境变量或密钥管理工具，配置文件中只保留占位符。

### Q: 项目文件和数据文件如何区分？
**A**: 项目文件是代码和资源，数据文件是输入/输出。例如：训练脚本是项目文件，训练数据和模型输出是数据文件。

## 最佳实践

1. **明确分类**：每个文件都有明确的归属目录
2. **统一命名**：遵循命名约定，便于查找和管理
3. **定期清理**：定期清理 `temp/` 目录的临时文件
4. **版本控制**：只将项目文件和配置文件纳入版本控制
5. **文档记录**：在 `docs/` 中记录目录结构和文件说明

## .gitignore 模板

使用 `references/GITIGNORE.md` 模板，排除以下内容：

- 日志文件：`log/`、`*.log`
- 临时文件：`temp/`、`*.tmp`、`*.cache`
- 截图：`temp/screenshots/`、`*.png`、`*.jpg`
- IDE 文件：`.idea/`、`.vscode/`
- 环境变量：`.env`、`.env.local`
- 密钥文件：`*.key`、`*.pem`、`secrets.json`

## 相关资源

- [SKILL.md](SKILL.md) - Skill 主文件
- [QUICK_START.md](QUICK_START.md) - 快速开始指南