261 lines
5.7 KiB
Markdown
Executable File
261 lines
5.7 KiB
Markdown
Executable File
# 代码组织规范
|
||
|
||
## 📁 目录结构规范
|
||
|
||
### 核心原则
|
||
**禁止在根目录直接放置代码文件！** 所有代码必须按功能分类放入对应目录。
|
||
|
||
---
|
||
|
||
## 📂 目录定义
|
||
|
||
### 1. 提取器 (extractors/)
|
||
|
||
```
|
||
extractors/
|
||
├── current/ # 当前使用的提取器
|
||
│ ├── fusion/ # PC融合版提取器
|
||
│ │ └── extractor_fusion_complete.py
|
||
│ └── llm/ # LLM提取器
|
||
│ └── llm_extractor_dashscope.py
|
||
├── archive/ # 归档的旧版提取器
|
||
│ └── extractor_suc5.py (等)
|
||
└── utils/ # 提取器工具模块
|
||
└── chunker.py
|
||
```
|
||
|
||
**规则**：
|
||
- 新提取器默认放入 `current/` 对应子目录
|
||
- 废弃提取器移入 `archive/`
|
||
- 通用工具放入 `utils/`
|
||
|
||
---
|
||
|
||
### 2. 文档 (docs/)
|
||
|
||
```
|
||
docs/
|
||
├── changelogs/ # 变更日志
|
||
├── reports/ # 报告文档
|
||
├── plans/ # 计划文档
|
||
├── analysis/ # 分析文档
|
||
└── guides/ # 指南文档
|
||
```
|
||
|
||
**规则**：
|
||
- 所有 `.md` 文件必须分类存放
|
||
- 根目录仅保留 `README.md` 和索引文件
|
||
|
||
---
|
||
|
||
### 3. 脚本 (scripts/)
|
||
|
||
```
|
||
scripts/
|
||
├── shell/ # Shell脚本
|
||
├── utils/ # Python工具脚本
|
||
├── extractors/ # 提取器脚本 (v7-v12系列)
|
||
└── tests/ # 测试脚本
|
||
```
|
||
|
||
**规则**：
|
||
- `.sh` 文件放入 `shell/`
|
||
- 工具类脚本放入 `utils/`
|
||
- 版本化提取器放入 `extractors/`
|
||
|
||
---
|
||
|
||
### 4. 源代码 (src/)
|
||
|
||
```
|
||
src/
|
||
├── rag/
|
||
│ ├── extractors/ # RAG集成提取器
|
||
│ ├── advanced/ # 高级功能
|
||
│ └── agentic/ # Agent功能
|
||
├── llm/ # LLM模块
|
||
├── memory/ # 记忆模块
|
||
└── db/ # 数据库模块
|
||
```
|
||
|
||
**规则**：
|
||
- 按功能模块组织
|
||
- 保持现有 `src/rag/extractors/` 结构
|
||
|
||
---
|
||
|
||
### 5. 数据 (data/)
|
||
|
||
```
|
||
data/
|
||
├── rule_bases/ # 规则库
|
||
├── samples/ # 样本数据
|
||
└── output/ # 输出数据
|
||
```
|
||
|
||
**规则**：
|
||
- 规则库文件放入 `rule_bases/`
|
||
- 不要混放代码和数据
|
||
|
||
---
|
||
|
||
### 6. 测试 (tests/)
|
||
|
||
```
|
||
tests/
|
||
├── unit/ # 单元测试
|
||
├── integration/ # 集成测试
|
||
└── fixtures/ # 测试数据
|
||
```
|
||
|
||
**规则**：
|
||
- 测试文件统一放此处
|
||
- 不要分散在根目录
|
||
|
||
---
|
||
|
||
### 7. 配置 (config/)
|
||
|
||
```
|
||
config/
|
||
├── nginx.conf
|
||
├── prometheus.yml
|
||
└── settings.yaml
|
||
```
|
||
|
||
**规则**：
|
||
- 配置文件集中管理
|
||
- 环境配置使用 `.env` 或 `config/`
|
||
|
||
---
|
||
|
||
## 🚫 禁止事项
|
||
|
||
### 根目录禁止放置
|
||
- ❌ 提取器文件 (`extractor_*.py`)
|
||
- ❌ 测试文件 (`test_*.py`)
|
||
- ❌ Shell脚本 (`*.sh`)
|
||
- ❌ 文档文件 (`*.md`，除README外)
|
||
- ❌ 工具脚本 (`*.py` 工具)
|
||
|
||
### 根目录允许保留
|
||
- ✅ `README.md` - 项目说明
|
||
- ✅ `LICENSE` - 许可证
|
||
- ✅ `.gitignore` - Git忽略配置
|
||
- ✅ `requirements.txt` - 依赖文件
|
||
- ✅ `pyproject.toml` - 项目配置
|
||
- ✅ `DOCS_INDEX.md` - 文档索引
|
||
- ✅ `EXTRACTORS_INDEX.md` - 提取器索引
|
||
- ✅ 核心入口文件（软链接）
|
||
|
||
---
|
||
|
||
## ✅ 新代码放置流程
|
||
|
||
### 步骤1：确定代码类型
|
||
| 代码类型 | 目标目录 |
|
||
|---------|---------|
|
||
| 新提取器 | `extractors/current/{fusion,llm,utils}/` |
|
||
| 文档 | `docs/{changelogs,reports,plans,analysis,guides}/` |
|
||
| Shell脚本 | `scripts/shell/` |
|
||
| Python工具 | `scripts/utils/` |
|
||
| 测试 | `tests/` |
|
||
| RAG提取器 | `src/rag/extractors/` |
|
||
| 规则库 | `data/rule_bases/` |
|
||
|
||
### 步骤2：创建文件
|
||
```bash
|
||
# 示例：创建新提取器
|
||
touch extractors/current/fusion/extractor_new_v1.py
|
||
|
||
# 示例：创建新文档
|
||
touch docs/guides/NEW_FEATURE_GUIDE.md
|
||
|
||
# 示例：创建新工具
|
||
touch scripts/utils/new_utility.py
|
||
```
|
||
|
||
### 步骤3：更新索引
|
||
- 更新 `DOCS_INDEX.md`（如添加文档）
|
||
- 更新 `EXTRACTORS_INDEX.md`（如添加提取器）
|
||
|
||
### 步骤4：创建软链接（可选）
|
||
```bash
|
||
# 如果需要在根目录快速访问
|
||
ln -s extractors/current/fusion/extractor_new_v1.py extractor_new.py
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 代码审查检查项
|
||
|
||
提交代码前检查：
|
||
- [ ] 代码文件不在根目录
|
||
- [ ] 文件放在正确的功能目录
|
||
- [ ] 已更新相关索引文档
|
||
- [ ] 没有重复文件
|
||
- [ ] 导入路径正确
|
||
|
||
---
|
||
|
||
## 📋 目录索引维护
|
||
|
||
### 必须维护的索引文件
|
||
1. `DOCS_INDEX.md` - 文档索引
|
||
2. `EXTRACTORS_INDEX.md` - 提取器索引
|
||
|
||
### 更新时机
|
||
- 新增/删除文档时更新 `DOCS_INDEX.md`
|
||
- 新增/归档提取器时更新 `EXTRACTORS_INDEX.md`
|
||
|
||
---
|
||
|
||
## 📝 示例
|
||
|
||
### 示例1：添加新提取器
|
||
```bash
|
||
# 1. 创建文件
|
||
touch extractors/current/fusion/extractor_v13.py
|
||
|
||
# 2. 编辑代码
|
||
# ... 实现提取器 ...
|
||
|
||
# 3. 更新索引
|
||
echo "- extractor_v13.py - v13提取器" >> EXTRACTORS_INDEX.md
|
||
|
||
# 4. 可选：创建软链接
|
||
ln -s extractors/current/fusion/extractor_v13.py extractor_v13.py
|
||
```
|
||
|
||
### 示例2：添加新文档
|
||
```bash
|
||
# 1. 创建文件
|
||
touch docs/guides/V13_USAGE.md
|
||
|
||
# 2. 编辑文档
|
||
# ... 编写文档 ...
|
||
|
||
# 3. 更新索引
|
||
echo "- V13_USAGE.md" >> DOCS_INDEX.md
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 遗留文件处理
|
||
|
||
根目录当前遗留文件（待处理）：
|
||
- `add_more_rules.py` → `scripts/utils/`
|
||
- `entity_disambiguation_prompt.py` → `src/rag/` 或归档
|
||
- `entity_disambiguation_system.py` → **保留**（核心功能）
|
||
- `extract_complete_sentence.py` → `extractors/archive/`
|
||
- `extractor_pc_based.py` → **保留**（有依赖）
|
||
- `prompt_v2_revised.py` → `scripts/utils/` 或归档
|
||
- `quick_validate.py` → `scripts/utils/`
|
||
- `rule_base_complete.py` → `data/rule_bases/`
|
||
- `rule_base_loader.py` → `data/rule_bases/`
|
||
|
||
---
|
||
|
||
*规范制定时间：2026-04-12*
|
||
*维护者：xialab的幸运星*
|