.gen 文件定义

`.gen` 是 GenePad / Gene Editor 的完整项目文件，文件本质是 SQLite 3 数据库。它比 `.gjson` 更完整，适合保存工程状态、测序图谱、比对条目、撤销历史和附件。

SQLite format 3 1-based inclusive BLOCK_SIZE = 10000 SCHEMA_VERSION = 5

Overview

读取原则

无需自定义二进制 parser——用任意 SQLite 驱动打开 `.gen`，再按下方表结构查询。
`sequence_blocks` 需按 `block_index` 升序拼接，不能依赖数据库默认返回顺序。
`segments`、`qualifiers`、`components`、`alignment`、`references` 等字段是 JSON 字符串，需延迟解析。
`.gen` 不持久化 `restrictionSites`，通常由读取程序根据主序列重新检测。

Schema

核心表结构

project_meta项目元信息 key-value 表

字段	类型	说明
`key`	TEXT PRIMARY KEY	元信息键
`value`	TEXT	元信息值，布尔值也以字符串保存

布尔值以字符串 'true'/'false' 保存；未设置时键可能缺失（读为 undefined）。已知 key：name, description, isCircular, isDoubleStranded, isDamMethylated, isDcmMethylated, accession, organism, date, moleculeType, division, version, keywords, source, comments, references(JSON 数组字符串), typeOfDisplay, customName, fileName, isDirty。拓扑由 isCircular 表示，无独立 topology 列。

sequence_blocks主序列分块

字段	类型	说明
`block_index`	INTEGER PRIMARY KEY	0-based block index
`bases`	TEXT NOT NULL	该块碱基字符串，通常最多 10,000 bases

SELECT bases FROM sequence_blocks ORDER BY block_index;

分块规则：每块 BLOCK_SIZE = 10000 bp。block_index = floor(position / 10000)，即块 0 存 0–9999，块 1 存 10000–19999。block_index 本身是 0-based（与下方 feature 的 1-based 坐标不同）。无 start_pos 列，起始位置 = block_index × 10000。写入时全删全写（非增量更新）。

features序列注释

字段	类型	说明
`id`	TEXT PRIMARY KEY	feature id
`name`	TEXT NOT NULL	feature 名称
`type`	TEXT NOT NULL	如 gene, CDS, promoter
`start_pos`	INTEGER NOT NULL	1-based inclusive start
`end_pos`	INTEGER NOT NULL	1-based inclusive end
`strand`	TEXT NOT NULL	forward, reverse, none
`color`	TEXT	颜色
`label`	TEXT	显示标签
`note`	TEXT	备注
`frame`	INTEGER	阅读框
`visible`	INTEGER DEFAULT 1	1 可见，0 隐藏
`segments`	TEXT	JSON：FeatureSegment[]，多片段 feature 使用
`qualifiers`	TEXT	JSON：Record<string, string[]>

primers / primer_binding_sites引物与结合位点

表	关键字段	说明
`primers`	`id, name, sequence, description, visible`	引物基本信息
`primer_binding_sites`	`primer_id, start_pos, end_pos, bound_strand, components, alignment`	结合位点；components / alignment 为 JSON

base_color_ranges碱基颜色范围

字段	类型	说明
`id`	TEXT PRIMARY KEY	颜色段 id
`start_pos`	INTEGER NOT NULL	1-based inclusive start
`end_pos`	INTEGER NOT NULL	1-based inclusive end
`strand`	TEXT NOT NULL	forward 或 reverse
`color`	TEXT NOT NULL	颜色值

alignment_entries / chromatogram_data比对与测序图谱

表	关键字段	说明
`alignment_entries`	`id, name, sequence, visible, chromatogram_json`	比对条目；chromatogram_json 为 JSON
`chromatogram_data`	`trace_a, trace_c, trace_g, trace_t, peak_locations`	主序列 chromatogram；BLOB 中保存 JSON 数组 bytes

attachments / undo_entries / edit_history工程状态

表	说明
`attachments`	附件：id, name, mime_type, data
`undo_entries`	撤销/重做栈（`stack_type` 为 `undo`/`redo`）；undo 栈上限 200 条，超出删最旧；before_diff / after_diff 为 JSON
`edit_history`	编辑审计日志，before_snapshot / after_snapshot 为 JSON

Mapping

与内存模型的对应

DNASequence 字段	.gen 来源	备注
`sequence`	`sequence_blocks`	按 block_index 拼接
`features`	`features`	segments / qualifiers 需要 JSON 解析
`primers`	`primers` + `primer_binding_sites`	按 primer_id 关联
`baseColorRanges`	`base_color_ranges`	strand 仅 forward / reverse
`alignmentEntries`	`alignment_entries`	chromatogram_json 可选
`chromatogram`	`chromatogram_data`	id 固定为 primary
`accession, organism, date...`	`project_meta`	全部为字符串值

Conventions

坐标与环形序列

feature / primer / base_color_ranges 的 start_pos / end_pos 均为 1-based inclusive。例如 start=1, end=10 表示第 1 到第 10 个碱基（共 10 个）。

环形序列跨越原点时 start > end：长度 = seqLength - start + end + 1（从 start 走到序列末尾，再从 1 绕回到 end）。多段 feature 还可用 segments JSON 数组，每段独立 {start, end, strand?, name?, color?}。

注意：sequence_blocks.block_index 是 0-based，与上述 1-based 特征坐标是两套体系。

Quick Look

用 sqlite3 打开看一眼

# 打开 .gen（本质就是 SQLite）
sqlite3 example.gen

# 列出所有表
.tables

# 读取项目名 / 拓扑
SELECT key, value FROM project_meta WHERE key IN ('name','isCircular');

# 拼接完整序列（注意按 block_index 排序）
SELECT group_concat(bases, '') FROM (SELECT bases FROM sequence_blocks ORDER BY block_index);

# 查看前几个 feature
SELECT name, type, start_pos, end_pos, strand FROM features LIMIT 5;