PlantAI-rag/docs/CODING_STANDARDS.md

代码组织规范

📁 目录结构规范

核心原则

禁止在根目录直接放置代码文件！ 所有代码必须按功能分类放入对应目录。

---

📂 目录定义

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：创建文件

# 示例：创建新提取器
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：创建软链接（可选）

# 如果需要在根目录快速访问
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：添加新提取器

# 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：添加新文档

# 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的幸运星