# 提取器清单 - 汇总整理

## 📁 目录结构建议

```
gene-family-mas-v2/
├── extractors/                    # 主提取器目录
│   ├── current/                   # 当前使用版本
│   │   ├── v12/                   # v12系列（最新）
│   │   ├── v10/                   # v10系列（附表支持）
│   │   └── fusion/                # 融合版（PC风格）
│   ├── archive/                   # 历史版本
│   │   ├── v7-v9/                 # 早期版本
│   │   └── phylogeny/             # 系统发育专用
│   └── utils/                     # 工具模块
├── src/rag/extractors/            # RAG集成提取器
└── scripts/extractors/            # 脚本提取器
```

---

## 🎯 当前推荐版本

### 1. 融合版提取器（推荐用于PC对标）

| 文件 | 版本 | 功能 | 状态 |
|------|------|------|------|
| `extractor_fusion_complete.py` | v1.0 | PC风格融合版，8种实体，7种关系 | ✅ 当前主用 |
| `extractor_pc_based.py` | v1.0 | 基于PC规则库（788模式） | ⚠️ 性能待优化 |
| `extractor_pc_complete.py` | - | PC完整版 | ⚠️ 未完成 |

**特点**：
- 8种实体类型（gene, tissue, metabolite, process, compartment, chromosome, species, phylogeny_group）
- 7种关系（expressed_in, transports, located_on, grouped_with, involved_in, localizes_to, identified_in）
- 支持复合基因展开
- 证据验证

### 2. v12系列（最新完整版）

| 文件 | 路径 | 功能 | 状态 |
|------|------|------|------|
| `extract_v12_final.py` | src/rag/extractors/ | v12最终版，附表下载+章节补充 | ✅ 完整 |
| `extract_v12_1_fixed.py` | src/rag/extractors/ | v12.1修复版，保存章节文本 | ✅ 可用 |
| `extract_v12_1_complete.py` | src/rag/extractors/ | v12.1完整版 | ⚠️ 待验证 |

**特点**：
- 附表自动下载（Europe PMC）
- marker-pdf章节识别
- 章节补充（PyMuPDF+正则）
- 实体过滤
- gene-centric chunks
- **缺点**：关系抽取不完整

### 3. v10系列（附表支持）

| 文件 | 路径 | 功能 | 状态 |
|------|------|------|------|
| `extract_v10_with_supplementary.py` | scripts/extractors/ | v10附表增强版 | ✅ 可用 |
| `extract_v10_final.py` | scripts/extractors/ | v10最终版 | ⚠️ 旧版 |
| `extract_v10_revised.py` | scripts/extractors/ | v10修订版 | ⚠️ 旧版 |

**特点**：
- 附表Excel解析
- 基因信息补充（染色体、蛋白等）
- 关系生成（belongs_to, located_in, expressed_in）
- **缺点**：无附表自动下载

---

## 📊 各版本功能对比

| 功能 | v7-v9 | v10 | v12 | Fusion |
|------|-------|-----|-----|--------|
| PDF解析 | ✅ | ✅ | ✅ | ✅ |
| 附表下载 | ❌ | ❌ | ✅ | ❌ |
| 附表解析 | ⚠️ | ✅ | ✅ | ❌ |
| 章节识别 | ⚠️ | ⚠️ | ✅ | ⚠️ |
| 实体识别 | ✅ | ✅ | ✅ | ✅ |
| 关系抽取 | ✅ | ✅ | ⚠️ | ✅ |
| 消歧系统 | ❌ | ❌ | ❌ | ❌ |
| PC规则库 | ❌ | ❌ | ❌ | ✅ |

---

## 🔧 工具模块

### 附表下载器
- `src/rag/extractors/supplementary_downloader.py` - Europe PMC附表下载
- `scripts/utils/fetch_supplementary_data.py` - 附表数据获取
- `scripts/utils/universal_supplementary_fetcher.py` - 通用附表获取

### 实体处理
- `src/rag/extractors/gene_entity_filter.py` - 基因实体过滤
- `src/rag/extractors/gene_centric_chunker.py` - gene-centric chunks生成

### 章节处理
- `src/rag/extractors/section_trigger.py` - 章节补充触发
- `src/rag/extractors/section_supplementer.py` - 章节补充器

---

## 🗂️ 归档版本（archive/old_extractors/）

### 系统发育专用（phylogeny系列）
- `extract_phylogeny_v5_*.py` - v5系列（ICL、universal、scrutiny等）
- `extract_phylogeny_v6*.py` - v6系列
- `extract_phylogeny_v7*.py` - v7系列

### 其他专用
- `extract_abstract_only.py` - 仅摘要
- `extract_by_sections.py` - 按章节
- `extract_expression_*.py` - 表达专用
- `extract_methods*.py` - 方法专用

---

## 🎯 使用建议

### 场景1：对标PC项目
**推荐**：`extractor_fusion_complete.py`
- 8种实体类型对齐PC
- 788个PC规则模式
- 关系标准化

### 场景2：完整提取（含附表）
**推荐**：`extract_v12_final.py`
- 自动下载附表
- 章节识别+补充
- gene-centric chunks

### 场景3：快速测试
**推荐**：`extractor_fusion_complete.py` 或 `extract_v12_1_fixed.py`
- 单文件运行
- 依赖少
- 结果直观

---

## 📝 待整理任务

1. [ ] 将旧版本（v7-v9）移动到 archive/
2. [ ] 将phylogeny系列归档到 archive/phylogeny/
3. [ ] 合并重复的附表下载器
4. [ ] 统一提取器接口
5. [ ] 添加版本说明文档
6. [ ] 删除重复文件（如 gene-family-mas-v3 嵌套目录）

---

## 🐛 已知问题

1. **v12系列**：关系抽取不完整，需要从附表生成关系
2. **Fusion版**：性能待优化（788个模式匹配慢）
3. **附表下载**：Europe PMC偶尔超时，需要重试机制
4. **章节识别**：marker-pdf对复杂格式PDF支持不佳

---

*最后更新：2026-04-12*
*维护者：xialab的幸运星*