# GeneFamily-RAG 落地规范 vFINAL
> 面向"基因家族研究"场景的 Graph-first + Evidence-second RAG 总体设计与数据规范
> 整合版本：基于 gpt_rag.md (工程规范) + rag_gpt5.2.md (需求分析)
> 生成日期：2026-03-27

---

## 目录

1. [背景与目标](#1-背景与目标)
2. [总体架构](#2-总体架构)
3. [数据分层设计](#3-数据分层设计)
4. [实体与关系规范](#4-实体与关系规范)
5. [证据与溯源标准](#5-证据与溯源标准)
6. [数据资产规划](#6-数据资产规划)
7. [实施路线图](#7-实施路线图)
8. [多智能体输出规范](#8-多智能体输出规范)
9. [附录：校验规则与迁移指南](#9-附录校验规则与迁移指南)

---

## 1. 背景与目标

### 1.1 为什么要单独做"基因家族版"RAG

基因家族论文/报告的问答，和"通用植物知识图谱问答"最大的差异在于：

1. **结构化优先**：家族成员、系统发育分组、结构域/基序、复制事件、共线性、同源/旁系/直系同源等是主干信息；文本证据是支撑层。
2. **强规范化需求**：同一基因会以多种形式出现（symbol / locus / protein / accession / 旧ID / 物种前缀）；不做 alias-first，召回会不稳定。
3. **可追溯是硬门槛**：科研写作/审稿需要能落到"哪篇文献/哪一段/哪张图/哪张补表/哪条数据行"。

### 1.2 科研人员的核心痛点

#### A. 把"分散的证据"变成"可检索的结论 + 依据"
科研做基因家族最常卡在：信息散在 TAIR/Ensembl/UniProt/InterPro/文章/补充材料里，结论不好复用。

RAG应该做到：
- 给出**结论**（家族定义、关键结构域、分类标准、命名惯例、已知功能）
- 同时给出**依据**（来自哪些数据库条目/哪篇文献/哪张图表/哪条实验事实）

#### B. 让"分析结果解释"不再靠记忆与经验
分析模块会吐出很多结果：树、motif、Ka/Ks、表达热图、共线性等。RAG要帮你把这些结果放进"研究共同体的语境"里：
- 某类拓扑在该家族里是否常见？是否对应已知亚家族？
- 某个结构域组合是否提示新功能/新亚型？
- 某个表达模式在文献中常见于什么胁迫/组织？

#### C. 跨物种/跨版本/跨命名的对齐与消歧
植物基因家族最痛：同源基因多个命名体系、基因组版本更新、同名不同物种。

RAG要提供：
- **实体消歧**（gene_id / transcript / protein / locus / synonyms）
- **版本追踪**（基因组版本、注释版本）
- **同源/旁系/直系**关系的证据汇总（不是只给一个结论）

#### D. 把"下一步该怎么做"变成可复用 SOP
科研人员常问的不是"是什么"，而是"我下一步该做什么、怎么做最靠谱"。

RAG要能回答：
- 推荐哪些验证实验（qPCR、亚细胞定位、转录激活、突变体、互作等）
- 常用参数区间/工具选择/常见坑（例如HMM阈值、树构建模型、去冗余策略）

### 1.3 RAG应该能回答的科研问题

#### Ⅰ. 家族定义与边界（最常问）
- "XX家族在植物里**标准定义**是什么？必须包含哪些结构域/保守位点？"
- "我鉴定到的候选基因里，哪些是**真成员**，哪些可能是**假阳性/相近家族串门**？"
- "亚家族怎么划分更符合前人？有哪些主流分类体系？"

#### Ⅱ. 命名、同源与进化（写文章必用）
- "拟南芥/水稻/玉米里该家族的**命名规则**与历史沿革？"
- "某基因在不同物种的**直系同源**是谁？证据是什么（树/共线性/域架构）？"
- "家族扩张主要由**串联重复**还是**片段复制/WGD**驱动？已有研究怎么看？"

#### Ⅲ. 功能假设与优先级排序（指导实验）
- "哪些成员与**抗逆/激素/发育阶段**相关证据最强？"
- "如果我要挑3个基因做功能验证，按证据（文献+表达+保守性）怎么排序？"
- "这个motif/结构域组合在文献里通常对应什么功能模块？"

#### Ⅳ. 表达与调控（组学解释）
- "该家族在不同组织/胁迫下的典型表达模式是什么？关键条件有哪些？"
- "哪些转录因子/顺式元件经常调控该家族？有无已验证案例？"
- "是否存在典型共表达模块/通路关联（如ABA、SA、JA等）？"

#### Ⅴ. 方法学与参数（减少踩坑）
- "家族鉴定用BLAST vs HMMER怎么选？阈值怎么设更合理？"
- "树构建、比对裁剪、模型选择在该家族里常见做法是什么？"
- "Ka/Ks、共线性、结构域注释的常见误区是什么？如何自检？"

---

## 2. 总体架构

### 2.1 Graph-first + Evidence-second（强推荐作为默认路由）

#### 两级检索（默认路由）

1) **Graph-first（结构化召回）**：
   - 先在图谱/关系表里召回候选实体/边/路径（尤其：member_of / classified_into / has_domain / orthologous_to / syntenic_with / duplicated_to / expressed_in / upregulated_in）。

2) **Evidence-second（证据回填）**：
   - 用每条候选边的 `provenance` 去取到证据 chunk（本地 chunk 库优先；没有则在线拉取并缓存）。

3) **Cite Gate（引用门控）**：
   - 置信度 ≥ medium 的结论必须能回填证据，否则回答自动降级为"可能/提示/需要进一步核查"。

### 2.2 参考 PlantConnectome 的"可借鉴点"与"必须补强点"

#### 可直接借鉴的工程思想
- **边表（Edges）**：一行一条关系，包含 `source/type/relationship/target/type + pubmedID + p_source + basis`，并额外保存 `resolved` 版本与 alias 字段。
- **Resolve 是独立阶段**：同时保存"原始抽取"和"归一化后"字段，便于调试与回溯。
- **关系同义词归并**：把大量自然语言关系词归并到少量类别/枚举（例如 activation/induction 类）。

#### 必须补强的关键缺口
- `p_source` 的格式是 `{pmid}_{section}`（如 `23031218_abstract`），但 **当前数据库无法用 `p_source` 直接取到原文 chunk**；需要从 `p_source` 提取 PMID，再通过 PubMed API 在线获取摘要/原文。
- 这意味着：**你的系统必须补一层"文献证据库（pmid → chunks）"**，否则只能做"弱可追溯"（指到 PMID+section，但没有可复核原句）。

---

## 3. 数据分层设计

### 3.1 需要的最小 6 个数据域（强推荐）

1) **Edges（关系边表）**：核心事实/关系。
2) **Entities（实体表）**：规范化实体（含 type、species、primary_id）。
3) **Alias（别名表）**：alias-first 的基础。
4) **Documents（文献元数据）**：PMID/DOI ↔ title/year/journal。
5) **Chunks（证据库）**：pmid → section → chunk_id → text + locator。
6) **FamilyLayer（家族专用层）**：家族成员、分组、结构域架构、复制/共线、orthogroup 等。

### 3.2 统一 JSON Schema（项目的"最终输出格式"）

#### 顶层
```json
{"entities":[...], "relations":[...]}
```

#### Entity 通用字段
```json
{
  "id": "唯一ID（内部稳定）",
  "name": "展示名",
  "type": "gene|protein|gene_family|protein_domain|treatment|phenotype|...（枚举）",
  "species": "物种（对 gene/protein 强制）",
  "primary_id": "稳定外部ID（AGI/Ensembl/UniProt/NCBI等）",
  "attributes": {},
  "description": "可选",
  "provenance": [ ... ]
}
```

#### Relation 通用字段（核心）
```json
{
  "id": "关系ID",
  "source": "源实体ID",
  "target": "目标实体ID",
  "type": "关系枚举（canonical）",
  "confidence": "high|medium|low",
  "qualifiers": {},
  "provenance": [ ... ],
  "description": "可选"
}
```

---

## 4. 实体与关系规范

### 4.1 分阶段实施策略

```
阶段1（现在，1篇文章）
  - 实体：25种（核心）
  - 关系：35种（核心）
  
阶段2（100篇文章）
  - 实体：40种（扩展）
  - 关系：60种（扩展）
  
阶段3（几千到几万篇文章）
  - 实体：80-100种（按需从190种中选择）
  - 关系：150-200种（按需从788种中选择）
  
阶段4（可选，扩展到其他植物生物学领域）
  - 实体：190种（全部）
  - 关系：788种（全部）
```

### 4.2 阶段1核心实体类型（25种）

#### 核心生物实体
- `gene`, `protein`, `gene_family`, `protein_domain`, `motif`

#### 物种/组织/表型
- `organism`, `cultivar`, `tissue`, `cell_type`, `developmental_stage`
- `treatment`, `hormone`, `environmental_factor`
- `phenotype`, `trait`

#### 过程/分子
- `biological_process`, `signaling_pathway`
- `metabolite`, `mirna`, `transcription_factor`, `promoter`

#### 数据/证据
- `dataset`, `publication`, `method`, `assay`

### 4.3 基因家族通用实体类型（推荐最小全集）

- **Core**：`gene`, `protein`, `gene_family`, `gene_subfamily/phylo_clade`
- **家族鉴定**：`family_definition`, `hmm_model`, `protein_domain`, `motif`, `domain_architecture`
- **演化**：`orthogroup`, `duplication_event`, `syntenic_block`, `genomic_region`, `genome_build`
- **表达与表型**：`tissue`, `developmental_stage`, `treatment`, `phenotype`, `trait`
- **证据**：`publication`, `doc_chunk`, `figure`, `table`, `dataset`, `database`, `assay`, `method`

### 4.4 阶段1核心关系类型（35种）

#### 调控关系
- `activates`, `inhibits`, `regulates`

#### 表达关系
- `expressed_in`, `upregulated_in`, `downregulated_in`, `induced_by`, `repressed_by`

#### 功能关系
- `involved_in`, `controls`, `affects`, `promotes`, `mediates`

#### 进化关系
- `homologous_to`, `orthologous_to`, `paralogous_to`, `syntenic_with`

#### 层级关系
- `member_of`, `contains`, `part_of`, `belongs_to`

#### 互作关系
- `binds_to`, `interacts_with`, `targets`

#### 数据关系
- `annotated_in`, `stored_in`, `originated_from`

### 4.5 基因家族通用关系类型（Canonical Enum）

#### 家族
- `member_of`, `classified_into`, `defined_by`, `uses_model`, `has_domain`, `has_motif`, `has_architecture`

#### 演化
- `homologous_to`, `orthologous_to`, `paralogous_to`, `belongs_to_orthogroup`, `syntenic_with`, `duplicated_to`, `duplicated_from`

#### 表达
- `expressed_in`, `upregulated_in`, `downregulated_in`, `induced_by`, `repressed_by`, `temporally_expressed`

#### 功能/表型
- `involved_in`, `affects`, `controls`, `associated_with`

#### 互作/调控（可选）
- `regulates`, `activates`, `inhibits`, `binds_to`, `interacts_with`, `targets`

### 4.6 Domain/Range 约束示例

```yaml
expressed_in:
  direction: "source->target"
  domain: ["gene","transcript","protein"]
  range:  ["tissue","cell_type","developmental_stage"]

orthologous_to:
  direction: "bidirectional"
  domain: ["gene"]
  range:  ["gene"]
  constraints:
    - "species(source) != species(target)"
```

---

## 5. 证据与溯源标准

### 5.1 Provenance（证据指针）标准

```json
{
  "source_type": "publication|dataset|database",
  "source_id": "pmid:23031218|doi:...|GSE...|UniProt:...",
  "p_source": "23031218_abstract",
  "doc_chunk_id": "pmid23031218_abs_c03",
  "locator": {
    "section": "abstract|results|figure_legend|table|supp",
    "page_start": null,
    "page_end": null,
    "figure": null,
    "table": null
  },
  "snippet": "可复核原句（尽量原文）",
  "evidence_level": "experiment|omics|prediction|curation",
  "method": "RNA-seq|qRT-PCR|HMMER|MCScanX|..."
}
```

### 5.2 证据强度分层

- **Level 1：实验验证**（遗传学/生化/互作）
- **Level 2：组学支持**（转录组/蛋白组/表观组）
- **Level 3：计算预测**（结构域/定位/共表达/同源推断）

### 5.3 强规则

- `confidence = high/medium` ⇒ 必须有 `provenance[]`，且每条至少含 `source_id + doc_chunk_id + locator.page + snippet`
- `confidence = low` ⇒ 可无 provenance（但下游回答要降级措辞）

### 5.4 Qualifiers（上下文限定）统一格式

统一放在 relation 的 `qualifiers`，建议支持这些常用键：
- **表达类**：`tissue, stage, treatment, time_point, assay, log2fc, p_adj`
- **结构域类**：`start, end, evalue, db`
- **系统树/分组**：`tree_method, alignment_method, bootstrap, scheme`
- **共线性/复制**：`dup_type, ks, ka_ks, block_id, score`

---

## 6. 数据资产规划

### 6.1 必备（MVP就要有）

#### 1) 基因组与注释
- genome build、GFF3/GTF、CDS/protein序列、转录本结构、基因ID映射与别名表

#### 2) 结构域与功能注释
- InterPro/Pfam/SMART/CDD结果、GO、关键词、亚细胞定位预测（可作为"计算证据"层）

#### 3) 家族定义资产
- 该家族的**HMM profile**（或域组合规则）、保守motif、关键位点描述、已知亚家族规则

#### 4) 核心文献库（强建议做"精读级"结构化）
- 综述 + 领域标杆文章：把"家族分类、关键基因、实验结论、图表信息"抽成结构化卡片

### 6.2 推荐（让RAG真正"懂科研"）

#### 5) 同源与进化证据集
- OrthoGroup、系统树（或树的关键分叉解释）、共线性块、复制类型标签（tandem/WGD/segmental）

#### 6) 转录组表达与差异表达
- RNA-seq/微阵列：组织、时期、胁迫、品种；DEG结果；共表达模块（WGCNA等）

#### 7) 蛋白互作/修饰/定位证据
- Y2H/BiFC/CoIP-MS、磷酸化/泛素化、定位实验图、结构预测摘要（可当"功能支持"）

#### 8) 表型与遗传证据
- 突变体/过表达/CRISPR表型、QTL/GWAS关联、遗传互作

### 6.3 进阶（让RAG变成"领域专家"）

#### 9) 通路与网络
- KEGG/Reactome/MapMan、调控网络、TF-靶基因证据、cis元件富集结果

#### 10) 实验SOP与"隐性知识"
- 你们实验室做家族项目的模板：从鉴定到文章写作的流程、参数默认值、审稿人常问点

---

## 7. 实施路线图

### Phase 1：可用（1个家族 → 1套可追溯答案）
- 把"家族定义 + 20–50篇关键文献 + 1–3个模式物种的注释/结构域/同源"做成高质量KB
- 重点：**实体消歧 + 证据片段引用**（没有引用的回答一律降级为"推测"）

### Phase 2：好用（跨物种扩展 + 研究问题模板化）
- 加入表达数据、共线性、复制类型标签
- 建一套"问题模板 → 检索策略 → 输出格式"的库（让多智能体稳定产出）

### Phase 3：专家（自动更新 + 证据冲突处理）
- 定期增量抓取新文献/新版本注释
- 做"证据冲突"机制：不同论文结论不一致时，列出分歧点与证据等级，而不是强行给唯一答案

---

## 8. 多智能体输出规范

### 8.1 让RAG输出"可计算的中间结构"

不要只让RAG吐一段文字。更强的做法是让RAG同时输出：

#### 结论摘要（人读）
- 自然语言回答核心问题

#### 证据清单（可追溯）
- 来源ID、片段、证据等级、适用物种

#### 实体与关系（给分析代理）
- 候选基因列表、同源对、亚家族标签、条件/组织标签

#### 不确定性声明
- 哪些是推断，哪些是实验

### 8.2 输出格式示例

```json
{
  "answer": {
    "summary": "FtSPL1属于SPL基因家族，包含SBP结构域(PF03110)...",
    "confidence": "high"
  },
  "evidence": [
    {
      "source_id": "pmid:31196111",
      "snippet": "FtSPL1 contains the SBP domain (PF03110)...",
      "evidence_level": "experiment",
      "locator": {"figure": "Fig.1", "table": null}
    }
  ],
  "entities": [
    {"id": "FtSPL1", "type": "gene", "species": "Fagopyrum tataricum"},
    {"id": "SPL", "type": "gene_family"},
    {"id": "PF03110", "type": "protein_domain"}
  ],
  "relations": [
    {"source": "FtSPL1", "target": "SPL", "type": "member_of", "confidence": "high"},
    {"source": "FtSPL1", "target": "PF03110", "type": "has_domain", "confidence": "high"}
  ],
  "uncertainty": [
    "亚家族分类存在分歧：文献A分为3组，文献B分为5组"
  ]
}
```

---

## 9. 附录：校验规则与迁移指南

### 9.1 实体校验
- id 唯一
- type 在枚举中
- gene/protein/transcript 必须有 species
- protein_domain 必须有 pfam_id 或 interpro_id

### 9.2 关系校验
- source/target 必须存在
- type 在枚举中
- 满足 domain/range 约束（例如 expressed_in 不允许 gene → treatment）
- confidence≥medium ⇒ provenance 强制存在且字段完整

### 9.3 Resolve（归一化）流水线（必须独立）

- **Entity resolve（alias-first）**：优先稳定 ID（AGI/Ensembl/UniProt）> locus > symbol > name
- **Relationship resolve（同义词归并）**：把自然语言关系统一到 canonical enum，方向固定
- **Type resolve**：把 `gene identifier / gene(s) / protein(s)` 等不稳定类型统一到枚举

### 9.4 最小实现顺序（最优计划）

1) 导入边表到 `Edges`（保留 raw/resolved + pmid/p_source/basis）
2) alias-first：建 `Alias` + 统一 `entity_id/primary_id/species`
3) relationship resolve + domain/range 校验
4) 在线证据回填缓存：pmid → abstract chunks（先把"可追溯"做起来）
5) 家族专用层：member/clade/domain/duplication/synteny（来自你自己的分析）
6) Cite Gate：高置信必须能回填 snippet，否则降级措辞

### 9.5 PlantConnectome 边表字段 → 你的 v2 映射

- `pubmedID` → provenance.source_id = `pmid:{pubmedID}`
- `p_source` → provenance.p_source
- `basis` → provenance.snippet（短期可用；长期建议用原句替换）
- `* resolved` → 你的 canonical entity/type/relation
- `* gene alias` → Alias 表的候选 ID 列表

---

## 附录：建议补充的 2 个高频关系
- `localized_to`：`protein → subcellular_compartment`
- `essential_for`：`gene/protein → process/metabolite/phenotype`（或归并到 involved_in + qualifiers.role=essential）

---

*文档版本：FINAL*
*整合日期：2026-03-27*
*状态：可直接执行*