## 回答:

下面我把“基因家族通用版”的规范**整理成一份可以直接落地/写进项目文档的 v2.0 版本**（保留你现有 `entities` / `relations` 两段式，向后兼容；同时补齐“可追溯、可约束、可带上下文”的硬要求）。

---

# 基因家族通用增强版实体-关系提取规范 v2.0（整理版）

## 1. 目标与原则

### 1.1 适用范围
适用于**任意植物/动物/真菌等物种的基因家族研究**：SPL、MYB、NLR、AP2/ERF、CYP、GRAS、bHLH、ABC、HSP、TPS…  
覆盖常见论文模块：家族鉴定、分组/系统树、结构域/基序、复制与共线性、表达谱、调控/互作、表型/性状关联、数据集与数据库证据。

### 1.2 三条硬约束（必须执行）
1) **可追溯**：任何中高置信断言必须带 `provenance[]`，能定位到文献 chunk / 图表 / 补充表 / 数据表行。  
2) **可约束**：关系必须满足 **domain/range**（源实体类型→目标实体类型）与**默认方向**。  
3) **可检索上下文**：条件信息（tissue/stage/treatment/time/assay/log2fc/p_adj 等）统一放 `qualifiers`，不要只写在 description 里。

---

## 2. 输出 JSON 顶层结构（保持兼容）

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

---

## 3. entities 规范（通用字段 + 类型模板）

### 3.1 entity 通用字段（所有实体都支持）
- `id`：唯一标识（必填）
- `name`：人类可读名称（必填）
- `type`：实体类型枚举（必填）
- `species`：所属物种（对 gene/protein/transcript/tissue 等强建议）
- `attributes`：结构化属性对象（建议）
- `description`：补充描述（可选）
- `provenance`：证据指针数组（可选；当 entity 是从文献/数据库抽取的关键事实时建议提供）

> 注意：**不要把关键字段都塞进 description**，优先进入 `attributes`。

### 3.2 实体类型枚举（基因家族通用“必备集合”）
按功能分组给你一份“推荐最小全集”（你可以先实现这批）：

#### A) 核心生物实体（Core Bioentities）
- `gene`
- `transcript`（可选）
- `protein`
- `gene_family`
- `gene_subfamily`（或 `phylo_clade`）

#### B) 家族定义资产（Family Definition Assets）
- `family_definition`
- `hmm_model`
- `protein_domain`
- `motif`
- `domain_architecture`

#### C) 进化与基因组（Evolution/Genome）
- `organism`
- `cultivar` / `strain`
- `genome_build`
- `genomic_region`
- `syntenic_block`
- `orthogroup`
- `duplication_event`

#### D) 表达/处理/表型（Expression/Treatment/Phenotype）
- `tissue`
- `cell_type`（可选）
- `developmental_stage`
- `treatment`
- `hormone`
- `environmental_factor`
- `phenotype`
- `trait`

#### E) 数据与证据（Data/Evidence）
- `publication`
- `doc_chunk`
- `figure`
- `table`
- `supplement`
- `dataset`
- `database`
- `assay`
- `method`

### 3.3 不同实体类型的最小必填模板（建议你做 validator）
- `gene / protein / transcript`：至少 `id + name + type + species`
- `protein_domain`：`pfam_id` 或 `interpro_id` 至少一个（放 `attributes`）
- `publication`：DOI 或 PMID（放 `id` 或 `attributes.external_id`）
- `genomic_region`：`chromosome/start/end/strand`（放 `attributes`）

---

## 4. relations 规范（通用字段 + 约束）

### 4.1 relation 通用字段
- `id`：唯一标识（建议）
- `source`：源实体 ID（必填）
- `target`：目标实体 ID（必填）
- `type`：关系类型枚举（必填）
- `confidence`：`high | medium | low`（必填，默认 low）
- `description`：自然语言描述（可选）
- `qualifiers`：结构化上下文（强建议）
- `provenance`：证据指针数组（**当 confidence ≥ medium 时强制**）

---

## 5. 关系类型枚举（按家族场景“最常用/最稳”的集合）

> 下面是 v2.0 建议优先支持的关系集合（能覆盖 80% 基因家族论文问答）。  
> 每个关系都有：**默认方向** + **domain/range 约束** + **推荐 qualifiers**。

### 5.1 家族归属与分组（Gene family essentials）
- `member_of`：`gene/protein → gene_family`
- `classified_into`：`gene/protein → gene_subfamily/phylo_clade`  
  - qualifiers：`tree_method, alignment_method, scheme`
- `defined_by`：`gene_family → family_definition`
- `uses_model`：`family_definition → hmm_model`  
  - qualifiers：`threshold, db_version`
- `has_domain`：`protein → protein_domain`  
  - qualifiers：`start, end, evalue, db`
- `has_motif`：`protein → motif`  
  - qualifiers：`start, end, score`
- `has_architecture`：`protein → domain_architecture`

### 5.2 表达关系（Expression）
> **统一命名与方向**：一律使用 `upregulated_in` 等形式，避免 `upregulates` 混乱。
- `expressed_in`：`gene/transcript/protein → tissue/cell_type`  
  - qualifiers：`assay, time_point, stage`
- `upregulated_in`：`gene/transcript → treatment/environmental_factor`  
  - qualifiers：`log2fc, p_adj, assay, time_point, tissue, stage`
- `downregulated_in`：同上
- `induced_by`：`gene/transcript → treatment/hormone`  
  - qualifiers：`assay, time_point, tissue, stage`
- `repressed_by`：同上
- `temporally_expressed`：`gene/transcript → developmental_stage`  
  - qualifiers：`assay, tissue`

### 5.3 调控与互作（Regulation/Interaction）
- `regulates`：`gene/protein/mirna → gene/transcript/protein/process`  
  - qualifiers：`direction(optional:+/-/unknown), assay`
- `activates`：`protein/transcription_factor → gene/process`
- `inhibits`：同上
- `binds_to`：`protein → promoter_element/genomic_region`  
  - qualifiers：`assay (ChIP/EMSA), motif`
- `targets`：`mirna → gene/transcript`  
  - qualifiers：`assay (degradome/5RACE)`
- `interacts_with`：`protein ↔ protein`  
  - qualifiers：`assay (Y2H/BiFC/CoIP)`

### 5.4 功能与表型（Function/Phenotype）
- `involved_in`：`gene/protein → biological_process/signaling_pathway`
- `affects`：`gene/protein → trait`
- `controls`：`gene/protein → phenotype`
- `associated_with`：`gene → trait/phenotype`  
  - qualifiers：`source (GWAS/QTL), p_value`

### 5.5 进化关系（Evolution）
- `homologous_to`：`gene/protein ↔ gene/protein`  
  - qualifiers：`method (BLAST/tree/HMM)`
- `orthologous_to`：`gene ↔ gene`（通常跨物种）  
  - qualifiers：`source (orthofinder/tree/synteny)`
- `paralogous_to`：`gene ↔ gene`（通常同物种）  
  - qualifiers：`dup_type`
- `belongs_to_orthogroup`：`gene/protein → orthogroup`
- `syntenic_with`：`gene/genomic_region ↔ gene/genomic_region`  
  - qualifiers：`block_id, score`
- `duplicated_from`：`gene → duplication_event`  
  - qualifiers：`dup_type`
- `duplicated_to`：`gene → gene`  
  - qualifiers：`dup_type, ks(optional)`

### 5.6 数据与来源（Data/Provenance glue）
- `annotated_in`：`gene/protein → database`  
  - qualifiers：`accession`
- `stored_in`：`dataset → database`
- `reported_in`：`entity/relation → publication`（可选；通常 provenance 已足够）

---

## 6. provenance（证据指针）统一标准：实现“可追溯答案”的关键

### 6.1 provenance 最小字段（推荐你做成强校验）
```json
"provenance": [{
  "source_type": "publication|dataset|database",
  "source_id": "doi:...|pmid:...|GSE...|UniProt:...",
  "doc_chunk_id": "chunk_xxx",
  "locator": { "page_start": 3, "page_end": 3, "figure": "Fig.1", "table": "Table S2", "supplement": "Additional file 4" },
  "snippet": "可复核的原文/图注/表格行（可截断）",
  "evidence_level": "experiment|omics|prediction|curation",
  "method": "qRT-PCR|RNA-seq|HMMER|MEGA|MCScanX|..."
}]
```

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

---

## 7. 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`

---

## 8. 校验规则（Validator 建议做的事）

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

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

---

## 9. 从你现有文档迁移到 v2.0 的最小改动清单（你马上能做）

1) **把 `evidence: "phylogenetic analysis"` 升级为 `provenance[]`**（含 chunk/page/snippet）  
2) **统一表达关系命名**：删掉/禁止 `upregulates`，统一 `upregulated_in / induced_by` 等  
3) **给每个 relation 加 qualifiers**：把组织/阶段/处理/时间点/方法从 description 迁移出来  
4) **加 domain/range 约束表**：作为配置或 schema 扩展（越早做越省事）  
5) **补齐家族专用实体**：`family_definition/hmm_model/domain_architecture/orthogroup/duplication_event/phylo_clade`

---

如果你希望我再“整理得更工程化一点”，我可以继续把上面 v2.0 输出成两份**可直接复制进仓库**的资产（你不需要再手工改）：
1) `relation_constraints.yaml`：每个关系的 domain/range/默认方向/必填 qualifiers/是否强制 provenance  
2) `enhanced_entity_relation_schema_v2.json`：JSON Schema 校验文件（支持自动 validator）