cn-era 0.1.1 → 0.3.0

package/README.md

@@ -11,28 +11,62 @@ A lightweight JavaScript/TypeScript library for converting Gregorian calendar ye
 
 ## Current Status
 
-**Early Development (v0.1.1)**
+**Beta Release (v0.3.0)**
 
-This library is in early development. Currently includes:
-- **Tang Dynasty** - Complete (618-907 CE)
-- **Wu Zhou** - Complete (684-705 CE)
-- **Song Dynasty** - Complete (960-1279 CE)
-- **Yuan Dynasty** - Complete (1260-1368 CE)
-- **Ming Dynasty** - Complete (1368-1644 CE)
-- **Qing Dynasty** - Complete (1644-1912 CE)
-- **Republic of China** - Complete (1912-present)
+This library now includes **complete era name coverage from 140 BCE to present**, covering all major Chinese dynasties and regimes:
 
-We are actively working on adding complete historical era data for other dynasties. Contributions are welcome! See [TODO.md](TODO.md) for the data completion roadmap.
+**Ancient Period:**
+- **Western Han** (140 BCE - 8 CE) - Complete
+- **Xin Dynasty** (9-23 CE) - Complete
+- **Eastern Han** (25-220 CE) - Complete
+
+**Three Kingdoms & Jin:**
+- **Cao Wei** (220-265 CE) - Complete
+- **Shu Han** (221-263 CE) - Complete
+- **Eastern Wu** (222-280 CE) - Complete
+- **Western Jin** (265-316 CE) - Complete
+- **Eastern Jin** (317-420 CE) - Complete
+
+**Northern and Southern Dynasties:**
+- **Southern Dynasties**: Liu Song, Southern Qi, Liang, Chen (420-589 CE) - Complete
+- **Northern Dynasties**: Northern Wei, Eastern Wei, Western Wei, Northern Qi, Northern Zhou (386-581 CE) - Complete
+
+**Unified Dynasties:**
+- **Sui Dynasty** (581-618 CE) - Complete
+- **Tang Dynasty** (618-907 CE) - Complete
+- **Wu Zhou** (690-705 CE) - Complete
+
+**Five Dynasties and Ten Kingdoms:**
+- **Five Dynasties**: Later Liang, Later Tang, Later Jin, Later Han, Later Zhou (907-960 CE) - Complete
+
+**Medieval Period:**
+- **Song Dynasty** (960-1279 CE) - Complete
+- **Liao Dynasty** (916-1125 CE) - Complete (concurrent with Song)
+- **Western Xia** (1038-1227 CE) - Complete (concurrent with Song)
+- **Jin Dynasty** (1115-1234 CE) - Complete (concurrent with Song)
+- **Yuan Dynasty** (1271-1368 CE) - Complete
+
+**Late Imperial:**
+- **Ming Dynasty** (1368-1644 CE) - Complete
+- **Qing Dynasty** (1644-1912 CE) - Complete
+
+**Modern:**
+- **Republic of China** (1912-present) - Complete
+
+**Total Coverage**: 498 historical era names spanning 2,164 years (140 BCE - 2024 CE)
 
 ## Features
 
-- Accurate era conversion: Supports historical era names from Qin Dynasty to Qing Dynasty
-- Comprehensive historical data: Covers all major Chinese dynasties
-- Multiple era support: Handles cases where multiple era names coexist in the same year (e.g., era changes)
-- Zero dependencies: No additional packages required
-- TypeScript support: Complete type definitions included
-- Lightweight: Small bundle size, minimal impact on your project
-- Traditional Chinese output: All era names in Traditional Chinese characters
+- **Smart Mainline Mode**: Automatically returns the orthodox/mainline dynasty for practical use (new in v0.3.0)
+- **Dynasty Enum System**: Uses standardized CBDB (China Biographical Database) dynasty codes for reliable identification (new in v0.3.0)
+- **Flexible Querying**: Filter by specific dynasties or view all concurrent regimes (new in v0.3.0)
+- **Accurate Era Conversion**: Supports historical era names from 140 BCE to present
+- **Comprehensive Historical Data**: Covers all major Chinese dynasties (498 era names)
+- **Multiple Era Support**: Handles cases where multiple era names coexist in the same year
+- **Zero Dependencies**: No additional packages required
+- **TypeScript Support**: Complete type definitions included
+- **Lightweight**: Small bundle size (~37KB minified), minimal impact on your project
+- **Traditional Chinese Output**: All era names in Traditional Chinese characters
 
 ## Installation
 
@@ -57,93 +91,148 @@ pnpm add cn-era
 **ESM (ES Modules)**
 
 ```javascript
-import { convertYear } from 'cn-era';
+import { convertYear, Dynasty } from 'cn-era';
 
-// Basic usage
+// Basic usage - returns mainline dynasty by default
 const result = convertYear(618);
 console.log(result);
-// Output: [{ dynasty: '唐', reign_title: '武德', year_num: '元年' }]
+// Output: [{ dynasty: 6, dynasty_name: '唐', reign_title: '武德', year_num: '元年' }]
 ```
 
 **CommonJS**
 
 ```javascript
-const { convertYear } = require('cn-era');
+const { convertYear, Dynasty } = require('cn-era');
 
 const result = convertYear(618);
 console.log(result);
-// Output: [{ dynasty: '唐', reign_title: '武德', year_num: '元年' }]
+// Output: [{ dynasty: 6, dynasty_name: '唐', reign_title: '武德', year_num: '元年' }]
 ```
 
 **More Examples**
 
 ```javascript
-import { convertYear } from 'cn-era';
+import { convertYear, Dynasty } from 'cn-era';
 
-// Multiple eras in one year (era change)
+// Default mode: returns only the mainline/orthodox dynasty
 convertYear(690);
+// [{ dynasty: 6, dynasty_name: '唐', reign_title: '載初', year_num: '二年' }]
+
+// Get all concurrent eras (including Wu Zhou)
+convertYear(690, { mode: 'all' });
+// [
+//   { dynasty: 6, dynasty_name: '唐', reign_title: '載初', year_num: '二年' },
+//   { dynasty: 77, dynasty_name: '武周', reign_title: '天授', year_num: '元年' }
+// ]
+
+// Filter by specific dynasty using Dynasty enum
+convertYear(618, { dynasty: Dynasty.SUI });
 // [
-//   { dynasty: '唐', reign_title: '載初', year_num: '二年' },
-//   { dynasty: '武周', reign_title: '天授', year_num: '元年' }
+//   { dynasty: 5, dynasty_name: '隋', reign_title: '大業', year_num: '十四年' },
+//   { dynasty: 5, dynasty_name: '隋', reign_title: '義寧', year_num: '二年' },
+//   { dynasty: 5, dynasty_name: '隋', reign_title: '皇泰', year_num: '元年' }
 // ]
 
 // Republic of China era (post-1912)
 convertYear(2024);
-// [{ dynasty: '中華民國', reign_title: '民國', year_num: '一百一十三年' }]
+// [{ dynasty: 21, dynasty_name: '中華民國', reign_title: '民國', year_num: '一百一十三年' }]
 ```
 
 ## API Documentation
 
-### `convertYear(year: number): EraResult[]`
+### `convertYear(year: number, opts?: ConvertYearOptions): EraResult[]`
 
 Convert a Gregorian calendar year to Chinese historical era name(s).
 
 #### Parameters
 
 - `year` (number): Gregorian calendar year (range: -841 to 3000, 0 is invalid)
+- `opts` (ConvertYearOptions, optional): Conversion options
+  - `mode?: 'mainline' | 'all'` - Conversion mode (default: `'mainline'`)
+    - `'mainline'`: Returns only the orthodox/mainline dynasty (recommended for most use cases)
+    - `'all'`: Returns all concurrent eras including non-orthodox regimes
+  - `dynasty?: Dynasty` - Filter by specific dynasty using Dynasty enum
 
 #### Returns
 
-Returns an array containing all era information for that year (some years may have multiple eras).
+Returns an array containing all era information for that year.
 
 Each result object contains the following fields:
 
 ```typescript
 interface EraResult {
-  dynasty: string;      // Dynasty name, e.g., "唐", "宋"
+  dynasty: Dynasty;     // Dynasty enum value (e.g., Dynasty.TANG = 6)
+  dynasty_name: string; // Dynasty name in Chinese, e.g., "唐", "宋"
   reign_title: string;  // Era name, e.g., "武德", "貞觀"
   year_num: string;     // Year in era, e.g., "元年", "三年"
 }
+
+enum Dynasty {
+  XI_HAN = 29,      // Western Han
+  DONG_HAN = 25,    // Eastern Han
+  SUI = 5,          // Sui
+  TANG = 6,         // Tang
+  SONG = 15,        // Song
+  YUAN = 18,        // Yuan
+  MING = 19,        // Ming
+  QING = 20,        // Qing
+  ROC = 21,         // Republic of China
+  // ... and more (see src/dynasty.ts for full list)
+}
 ```
 
 #### Examples
 
 ```javascript
-// Regular year
+import { convertYear, Dynasty } from 'cn-era';
+
+// Regular year - mainline mode (default)
 convertYear(627);
-// [{ dynasty: '唐', reign_title: '貞觀', year_num: '元年' }]
+// [{ dynasty: 6, dynasty_name: '唐', reign_title: '貞觀', year_num: '元年' }]
+
+// Era change within same dynasty
+convertYear(626, { mode: 'all' });
+// [
+//   { dynasty: 6, dynasty_name: '唐', reign_title: '武德', year_num: '九年' },
+//   { dynasty: 6, dynasty_name: '唐', reign_title: '貞觀', year_num: '元年' }
+// ]
+
+// Mainline mode filters to orthodox dynasty (Song, not Liao)
+convertYear(1000);
+// [{ dynasty: 15, dynasty_name: '宋', reign_title: '咸平', year_num: '三年' }]
 
-// Era change year (multiple eras in one year)
-convertYear(626);
+// All mode shows concurrent regimes
+convertYear(1000, { mode: 'all' });
 // [
-//   { dynasty: '唐', reign_title: '武德', year_num: '九年' },
-//   { dynasty: '唐', reign_title: '貞觀', year_num: '元年' }
+//   { dynasty: 16, dynasty_name: '遼', reign_title: '統和', year_num: '十八年' },
+//   { dynasty: 15, dynasty_name: '宋', reign_title: '咸平', year_num: '三年' }
 // ]
 
-// Coexisting regimes (e.g., Northern and Southern Dynasties)
-convertYear(420);
+// Filter by specific dynasty
+convertYear(1000, { dynasty: Dynasty.LIAO });
+// [{ dynasty: 16, dynasty_name: '遼', reign_title: '統和', year_num: '十八年' }]
+
+// Three Kingdoms - mainline returns Wei (orthodox)
+convertYear(221);
+// [{ dynasty: 26, dynasty_name: '魏', reign_title: '黃初', year_num: '二年' }]
+
+// Three Kingdoms - all mode shows concurrent states
+convertYear(221, { mode: 'all' });
 // [
-//   { dynasty: '南朝宋', reign_title: '永初', year_num: '元年' },
-//   { dynasty: '北魏', reign_title: '泰常', year_num: '五年' }
+//   { dynasty: 26, dynasty_name: '魏', reign_title: '黃初', year_num: '二年' },
+//   { dynasty: 53, dynasty_name: '蜀漢', reign_title: '章武', year_num: '元年' }
 // ]
 
 // Republic of China
-convertYear(1912);
-// [{ dynasty: '中華民國', reign_title: '民國', year_num: '元年' }]
+convertYear(1912, { mode: 'all' });
+// [
+//   { dynasty: 20, dynasty_name: '清', reign_title: '宣統', year_num: '四年' },
+//   { dynasty: 21, dynasty_name: '中華民國', reign_title: '民國', year_num: '元年' }
+// ]
 
 // BCE year
 convertYear(-140);
-// [{ dynasty: '西漢', reign_title: '建元', year_num: '元年' }]
+// [{ dynasty: 29, dynasty_name: '西漢', reign_title: '建元', year_num: '元年' }]
 ```
 
 ## Supported Historical Periods
@@ -171,18 +260,28 @@ This library supports era name conversion from **Western Zhou Gonghe Regency (84
 
 ## Important Notes
 
-1. **Era changes**: Some years return multiple results, which typically occurs when:
+1. **Mainline vs All Mode** (New in v0.3.0):
+   - **`mode: 'mainline'`** (default): Returns only the orthodox/mainline dynasty. Best for most use cases where you want the "standard" historical reference.
+   - **`mode: 'all'`**: Returns all concurrent eras including non-orthodox regimes. Useful for detailed historical research.
+   - Example: In year 1000, mainline mode returns Song (宋), while all mode returns both Song and Liao (遼).
+
+2. **Dynasty Enum System** (New in v0.3.0):
+   - Dynasty values are now represented by `Dynasty` enum using CBDB entity IDs
+   - Each result includes both `dynasty` (enum value) and `dynasty_name` (Chinese name)
+   - Use `Dynasty.TANG`, `Dynasty.SONG`, etc. for type-safe dynasty filtering
+
+3. **Era Changes**: Years with multiple results typically occur when:
    - Emperor changes era name (multiple era names within the same year)
    - Dynasty transitions
-   - Coexisting regimes during periods of division
+   - Coexisting regimes during periods of division (use `mode: 'all'` to see all)
 
-2. **Year range**: Currently supports 841 BCE to 3000 CE. Years outside this range will throw an error.
+4. **Year Range**: Currently supports -140 to 3000 CE. Years outside this range will throw an error.
 
-3. **Historical accuracy**: Era name data is based on mainstream historical records. Disputed years follow standard histories.
+5. **Historical Accuracy**: Era name data is based on mainstream historical records. Disputed years follow standard histories. Dynasty priorities follow orthodox historical tradition.
 
-4. **BCE years**: Negative numbers represent BCE years (e.g., -221 = 221 BCE)
+6. **BCE Years**: Negative numbers represent BCE years (e.g., -140 = 140 BCE, first year with era names)
 
-5. **Traditional Chinese**: All output is in Traditional Chinese characters, which matches historical documents. Users can convert to Simplified Chinese as needed.
+7. **Traditional Chinese**: All output is in Traditional Chinese characters, which matches historical documents. Users can convert to Simplified Chinese as needed.
 
 ## Development
 

package/README.zh-CN.md

@@ -11,28 +11,62 @@
 
 ## 当前状态
 
-**早期开发版本 (v0.1.1)**
+**测试版本 (v0.3.0)**
 
-本库目前处于早期开发阶段，已包含数据：
-- **唐朝** - 已完成（618-907 年）
-- **武周** - 已完成（684-705 年）
-- **宋朝** - 已完成（960-1279 年）
-- **元朝** - 已完成（1260-1368 年）
-- **明朝** - 已完成（1368-1644 年）
-- **清朝** - 已完成（1644-1912 年）
-- **中华民国** - 已完成（1912 年至今）
+本库现已包含**从公元前140年至今的完整年号覆盖**，涵盖中国历史所有主要朝代和政权：
 
-我们正在积极补充其他朝代的完整历史年号数据。欢迎贡献！请查看 [TODO.md](TODO.md) 了解数据补充计划。
+**上古时期：**
+- **西汉**（公元前140年 - 公元8年）- 已完成
+- **新朝**（9-23年）- 已完成
+- **东汉**（25-220年）- 已完成
+
+**三国两晋：**
+- **曹魏**（220-265年）- 已完成
+- **蜀汉**（221-263年）- 已完成
+- **孙吴**（222-280年）- 已完成
+- **西晋**（265-316年）- 已完成
+- **东晋**（317-420年）- 已完成
+
+**南北朝：**
+- **南朝**：刘宋、南齐、梁、陈（420-589年）- 已完成
+- **北朝**：北魏、东魏、西魏、北齐、北周（386-581年）- 已完成
+
+**大一统王朝：**
+- **隋朝**（581-618年）- 已完成
+- **唐朝**（618-907年）- 已完成
+- **武周**（690-705年）- 已完成
+
+**五代十国：**
+- **五代**：后梁、后唐、后晋、后汉、后周（907-960年）- 已完成
+
+**中古时期：**
+- **宋朝**（960-1279年）- 已完成
+- **辽朝**（916-1125年）- 已完成（与宋并存）
+- **西夏**（1038-1227年）- 已完成（与宋并存）
+- **金朝**（1115-1234年）- 已完成（与宋并存）
+- **元朝**（1271-1368年）- 已完成
+
+**近古时期：**
+- **明朝**（1368-1644年）- 已完成
+- **清朝**（1644-1912年）- 已完成
+
+**近现代：**
+- **中华民国**（1912年至今）- 已完成
+
+**总覆盖范围**：498个历史年号，跨越2164年（公元前140年 - 公元2024年）
 
 ## 特性
 
-- 精确的年号转换：支持从秦朝到清朝的历史年号
-- 完整的历史数据：涵盖中国历史各主要朝代
-- 多年号支持：处理同一年份多个年号并存的情况（如改元）
-- 零依赖：无需额外安装其他包
-- TypeScript 支持：提供完整的类型定义
-- 轻量化：体积小巧，不影响项目大小
-- 繁体输出：所有年号使用繁体中文，符合历史文献原貌
+- **智能主线模式**：自动返回正统朝代年号，实用性更强（v0.3.0 新增）
+- **朝代枚举系统**：使用标准化的 CBDB（中国历代人物传记数据库）朝代编码，可靠识别（v0.3.0 新增）
+- **灵活查询**：可按朝代筛选或查看所有并存政权（v0.3.0 新增）
+- **精确的年号转换**：支持从公元前140年至今的历史年号
+- **完整的历史数据**：涵盖中国历史各主要朝代（498个年号）
+- **多年号支持**：处理同一年份多个年号并存的情况
+- **零依赖**：无需额外安装其他包
+- **TypeScript 支持**：提供完整的类型定义
+- **轻量化**：体积小巧（~37KB minified），不影响项目大小
+- **繁体输出**：所有年号使用繁体中文，符合历史文献原貌
 
 ## 安装
 
@@ -57,85 +91,148 @@ pnpm add cn-era
 **ESM (ES Modules)**
 
 ```javascript
-import { convertYear } from 'cn-era';
+import { convertYear, Dynasty } from 'cn-era';
 
-// 基础用法
+// 基础用法 - 默认返回主线朝代
 const result = convertYear(618);
 console.log(result);
-// 输出: [{ dynasty: '唐', reign_title: '武德', year_num: '元年' }]
+// 输出: [{ dynasty: 6, dynasty_name: '唐', reign_title: '武德', year_num: '元年' }]
 ```
 
 **CommonJS**
 
 ```javascript
-const { convertYear } = require('cn-era');
+const { convertYear, Dynasty } = require('cn-era');
 
 const result = convertYear(618);
 console.log(result);
-// 输出: [{ dynasty: '唐', reign_title: '武德', year_num: '元年' }]
+// 输出: [{ dynasty: 6, dynasty_name: '唐', reign_title: '武德', year_num: '元年' }]
 ```
 
 **更多示例**
 
 ```javascript
-import { convertYear } from 'cn-era';
+import { convertYear, Dynasty } from 'cn-era';
 
-// 多个年号的情况（改元年份）
+// 默认模式：只返回主线/正统朝代
 convertYear(690);
+// [{ dynasty: 6, dynasty_name: '唐', reign_title: '載初', year_num: '二年' }]
+
+// 查看所有并存年号（包括武周）
+convertYear(690, { mode: 'all' });
+// [
+//   { dynasty: 6, dynasty_name: '唐', reign_title: '載初', year_num: '二年' },
+//   { dynasty: 77, dynasty_name: '武周', reign_title: '天授', year_num: '元年' }
+// ]
+
+// 使用朝代枚举筛选特定朝代
+convertYear(618, { dynasty: Dynasty.SUI });
 // [
-//   { dynasty: '唐', reign_title: '載初', year_num: '二年' },
-//   { dynasty: '武周', reign_title: '天授', year_num: '元年' }
+//   { dynasty: 5, dynasty_name: '隋', reign_title: '大業', year_num: '十四年' },
+//   { dynasty: 5, dynasty_name: '隋', reign_title: '義寧', year_num: '二年' },
+//   { dynasty: 5, dynasty_name: '隋', reign_title: '皇泰', year_num: '元年' }
 // ]
 
 // 民国纪年
 convertYear(2024);
-// [{ dynasty: '中華民國', reign_title: '民國', year_num: '一百一十三年' }]
+// [{ dynasty: 21, dynasty_name: '中華民國', reign_title: '民國', year_num: '一百一十三年' }]
 ```
 
 ## API 文档
 
-### `convertYear(year: number): EraResult[]`
+### `convertYear(year: number, opts?: ConvertYearOptions): EraResult[]`
 
 将公元年份转换为中国历史年号纪年。
 
 #### 参数
 
-- `year` (number): 公元年份，必须是正整数
+- `year` (number): 公元年份（范围：-841 到 3000，0 不合法）
+- `opts` (ConvertYearOptions, 可选): 转换选项
+  - `mode?: 'mainline' | 'all'` - 转换模式（默认：`'mainline'`）
+    - `'mainline'`：只返回正统/主线朝代（推荐用于大多数场景）
+    - `'all'`：返回所有并存的年号，包括非正统政权
+  - `dynasty?: Dynasty` - 使用朝代枚举筛选特定朝代
 
 #### 返回值
 
-返回一个数组，包含该年份对应的所有年号信息（某些年份可能有多个年号）。
+返回一个数组，包含该年份对应的所有年号信息。
 
 每个结果对象包含以下字段：
 
 ```typescript
 interface EraResult {
-  dynasty: string;      // 朝代名称，如 "唐"、"宋"
-  reign_title: string;  // 年号，如 "武德"、"贞观"
+  dynasty: Dynasty;     // 朝代枚举值（如 Dynasty.TANG = 6）
+  dynasty_name: string; // 朝代中文名称，如 "唐"、"宋"
+  reign_title: string;  // 年号，如 "武德"、"貞觀"
   year_num: string;     // 年份，如 "元年"、"三年"
 }
+
+enum Dynasty {
+  XI_HAN = 29,      // 西汉
+  DONG_HAN = 25,    // 东汉
+  SUI = 5,          // 隋
+  TANG = 6,         // 唐
+  SONG = 15,        // 宋
+  YUAN = 18,        // 元
+  MING = 19,        // 明
+  QING = 20,        // 清
+  ROC = 21,         // 中华民国
+  // ... 更多朝代（详见 src/dynasty.ts）
+}
 ```
 
 #### 示例
 
 ```javascript
-// 普通年份
+import { convertYear, Dynasty } from 'cn-era';
+
+// 普通年份 - 主线模式（默认）
 convertYear(627);
-// [{ dynasty: '唐', reign_title: '贞观', year_num: '元年' }]
+// [{ dynasty: 6, dynasty_name: '唐', reign_title: '貞觀', year_num: '元年' }]
 
-// 改元年份（一年内有多个年号）
-convertYear(626);
+// 同一朝代改元
+convertYear(626, { mode: 'all' });
 // [
-//   { dynasty: '唐', reign_title: '武德', year_num: '九年' },
-//   { dynasty: '唐', reign_title: '贞观', year_num: '元年' }
+//   { dynasty: 6, dynasty_name: '唐', reign_title: '武德', year_num: '九年' },
+//   { dynasty: 6, dynasty_name: '唐', reign_title: '貞觀', year_num: '元年' }
 // ]
 
-// 南北朝等分裂时期（多个政权并存）
-convertYear(420);
+// 主线模式过滤到正统朝代（宋而非辽）
+convertYear(1000);
+// [{ dynasty: 15, dynasty_name: '宋', reign_title: '咸平', year_num: '三年' }]
+
+// all 模式显示并存政权
+convertYear(1000, { mode: 'all' });
+// [
+//   { dynasty: 16, dynasty_name: '遼', reign_title: '統和', year_num: '十八年' },
+//   { dynasty: 15, dynasty_name: '宋', reign_title: '咸平', year_num: '三年' }
+// ]
+
+// 按朝代筛选
+convertYear(1000, { dynasty: Dynasty.LIAO });
+// [{ dynasty: 16, dynasty_name: '遼', reign_title: '統和', year_num: '十八年' }]
+
+// 三国 - 主线模式返回魏（正统）
+convertYear(221);
+// [{ dynasty: 26, dynasty_name: '魏', reign_title: '黃初', year_num: '二年' }]
+
+// 三国 - all 模式显示并存政权
+convertYear(221, { mode: 'all' });
+// [
+//   { dynasty: 26, dynasty_name: '魏', reign_title: '黃初', year_num: '二年' },
+//   { dynasty: 53, dynasty_name: '蜀漢', reign_title: '章武', year_num: '元年' }
+// ]
+
+// 民国元年
+convertYear(1912, { mode: 'all' });
 // [
-//   { dynasty: '南朝宋', reign_title: '永初', year_num: '元年' },
-//   { dynasty: '北魏', reign_title: '泰常', year_num: '五年' }
+//   { dynasty: 20, dynasty_name: '清', reign_title: '宣統', year_num: '四年' },
+//   { dynasty: 21, dynasty_name: '中華民國', reign_title: '民國', year_num: '元年' }
 // ]
+
+// 公元前年份
+convertYear(-140);
+// [{ dynasty: 29, dynasty_name: '西漢', reign_title: '建元', year_num: '元年' }]
 ```
 
 ## 使用场景
@@ -162,14 +259,28 @@ convertYear(420);
 
 ## 注意事项
 
-1. **改元情况**：某些年份会返回多个结果，这通常发生在：
+1. **主线模式 vs All 模式**（v0.3.0 新增）：
+   - **`mode: 'mainline'`**（默认）：只返回正统/主线朝代。适合大多数需要"标准"历史参考的场景。
+   - **`mode: 'all'`**：返回所有并存的年号，包括非正统政权。适合详细的历史研究。
+   - 示例：公元 1000 年，主线模式返回宋（宋），all 模式同时返回宋和辽（遼）。
+
+2. **朝代枚举系统**（v0.3.0 新增）：
+   - 朝代值现在使用 `Dynasty` 枚举表示，采用 CBDB 实体 ID
+   - 每个结果同时包含 `dynasty`（枚举值）和 `dynasty_name`（中文名称）
+   - 使用 `Dynasty.TANG`、`Dynasty.SONG` 等进行类型安全的朝代筛选
+
+3. **改元情况**：某些年份会返回多个结果，通常发生在：
    - 皇帝改元（同一年内更换年号）
    - 朝代更替
-   - 历史分裂时期的多个政权并存
+   - 历史分裂时期的多个政权并存（使用 `mode: 'all'` 查看全部）
+
+4. **年份范围**：目前支持 -140 到 3000 年，超出范围会抛出错误
+
+5. **历史准确性**：年号数据基于主流历史记载，个别争议年份以通史为准。朝代优先级遵循正统历史传统。
 
-2. **年份范围**：目前支持公元前 221 年到公元 1912 年，超出范围会返回空数组
+6. **公元前年份**：负数表示公元前年份（如 -140 = 公元前140年，年号制度开始）
 
-3. **历史准确性**：年号数据基于主流历史记载，个别争议年份以通史为准
+7. **繁体中文**：所有输出使用繁体中文字符，符合历史文献原貌。用户可根据需要转换为简体中文。
 
 ## 开发