# 中国现代作家文言残留谱系（lineage）使用说明 v0.3.0

## 一、目录结构

```
lineage/
├── pipeline_author.py          # 主入口：六步流水线调度器（断点续跑）
├── author_split.py             # Step 1：语料切分 + 时期×语域双标注（输出 manifest JSON）
├── author_analyze.py           # Step 2：逐卷五维raw+六功能+潜语言四子特征
├── author_aggregate.py         # Step 3：总体/时期/语域聚合 + H1-H4 + 鲁迅/胡适对照
├── author_figures.py           # Step 4：9 张核心图表（fig1_core_5dim ~ fig9_3d_lineage）
├── author_paper.py             # Step 5：十章 Word 论文 + WPS 中文标准标点（_punct.py）
├── _punct.py                   # 共用标点规范化模块（修复小数点误转、引号配对等）
├── author_lineage_entry.py     # Step 6：输出谱系条目 JSON（供 lineage_viewer 汇总）
├── lineage_viewer.py           # 汇总 N 个作家谱系条目 → HTML + 3D 谱系 PNG
├── configs/
│   ├── 模板.yaml                # 作家配置模板（复制改作者名即可）
│   ├── 周作人.yaml              # 示例配置：周作人
│   └── 徐志摩.yaml              # 示例配置：徐志摩
└── README_lineage.md           # 本文档
```

## 二、快速起步

### 1. 准备依赖
```bash
pip install jieba numpy scipy matplotlib pyyaml python-docx   # 最小必需依赖
```

### 2. 为新作家创建配置
```
cp lineage/configs/模板.yaml lineage/configs/茅盾.yaml
```
修改：
- `author_name`：作家名
- `corpus_dir`：全集 txt 目录（命名规范：`01_书名.txt`、`02_书名.txt`……）
- `periods`：三时期 prefixes / 书名关键字 / 年份范围
- `register_rules`：三或四语域匹配关键字
- `calib_version`：对齐老项目论文数值固定用 `'v0.2.1'`（等 50 作家 100 卷基准库补齐后再切 `'v0.3.0'`）

### 3. 单跑某步（调试时）
```bash
# 从 Step 1 跑完整流水线
python lineage/pipeline_author.py --config lineage/configs/茅盾.yaml

# 只出图和论文（已完成 Step 1-3）
python lineage/pipeline_author.py --config lineage/configs/茅盾.yaml --from-step 4
```

### 4. 跑多位作家并汇总谱系图
```bash
# 先逐个作家跑 pipeline
for writer in 周作人 徐志摩 茅盾 老舍 巴金 沈从文 钱钟书 张爱玲
do
  python lineage/pipeline_author.py -c lineage/configs/$writer.yaml
done

# 汇总谱系
python lineage/lineage_viewer.py \
  --inputs "E:/Corpus/周作人/谱系条目/周作人_lineage.json;E:/Corpus/徐志摩/谱系条目/徐志摩_lineage.json" \
  --output 中国现代作家文言残留谱系_v030.html
```
浏览器打开 `中国现代作家文言残留谱系_v030.html` 即可看到排名表 + 3D 散点图。

## 三、流水线步骤与输出文件

| Step | 脚本 | 输出文件（默认路径，可在YAML中覆盖） | 作用 |
|------|------|------|------|
| 1 | `author_split.py` | `结果/{author}_split_manifest.json` | 切卷、时期/语域标注 |
| 2 | `author_analyze.py` | `结果/{author}_volumes_analysis_v030.json` | 逐卷五维 raw + 六功能 + 潜语言四子特征 |
| 3 | `author_aggregate.py` | `结果/{author}_full_analysis_v030.json` | 总体/时期/语域聚合 + H1~H4 + 鲁迅/胡适对照 |
| 4 | `author_figures.py` | `图表/{author}/` 下 9 张 PNG | fig1~fig9，可直接插入 Word |
| 5 | `author_paper.py` | `论文/文言{author}的计算批评研究.docx`（+同名 .txt 兜底）| 十章论文 + 中文标点规范化 |
| 6 | `author_lineage_entry.py` | `谱系条目/{author}_lineage.json` | 谱系坐标、假设验证结果、与鲁迅/胡适差幅 |

所有步骤均实现「断点续跑」：目标文件存在且卷/字数统计一致时自动跳过。

## 四、与旧项目（鲁迅/胡适 v0.2.1）的数值一致性

* 在作家 YAML 中 `calib_version: 'v0.2.1'`（默认）即会调用 `benchmark_loader.load_train_samples('v0.2.1')`，
  基于 JSON 前 30 条基准样本的 **顺序冻结**，校准分位数与《文言鲁迅的计算批评研究_最终版.docx》/《文言胡适的计算批评》完全一致。
* 等 50 作家 100 卷基准库全部补入 `benchmark_self_contained.json`（index ≥ 30）后，再把所有 YAML 切换到
  `calib_version: 'v0.3.0'`，可获得更稳定的分位数阈值（100 篇样本）。
* 兼容性回归测试（`tests_compatibility.py`，共 61 项）保证：
  - v0.3.0 calibrate('v0.2.1') 的 five_dims 分位数 ≡ 旧 v0.2.1 calibrate() 位级一致
  - 19 篇 train 样本的 cross_quantile / classification 完全相同

## 五、九张标准图表说明

| 图号 | 文件名标签 | 图名 | 对应章节 |
|------|------|------|------|
| Fig1 | `1_core_5dim` | 五维语体指标（总体）柱图 | 三 |
| Fig2 | `2_period_evolution_5d` | 五维时期演化折线 | 四、三 |
| Fig3 | `3_submerged_radar` | 潜语言四子特征 × 时期 雷达 | 五 |
| Fig4 | `4_period_reg_heatmap` | 时期 × 语域 文言密度热图 | 七 |
| Fig5 | `5_scatter_cd_fus` | 文言密度 × 融合度 散点（每卷） | 三、四 |
| Fig6 | `6_six_func` | 六功能文言 × 时期 簇状柱 | 六 |
| Fig7 | `7_submerged_vs_explicit` | 潜语言指数 vs 显性（引+修+结）双轴 | 五 |
| Fig8 | `8_register_5dim` | 语域 × 五维 簇状柱 | 七 |
| Fig9 | `9_3d_lineage` | 文言-潜语言-融合度 3D 谱系 | 八、谱系 viewer |

## 六、扩展为谱系时的建议流程

1. 先对每位作家执行 pipeline（第 1~6 步），产出 `谱系条目/{author}_lineage.json`
2. 把新 OCR 的作家全集的 **1~2 篇代表性卷** 补入 `general_stylistic_analyzer_v0.3.0/benchmark_self_contained.json`
   的 **末尾**（即 append，不要改动前 30 条顺序），并补齐第 6 项新字段（schema 见下一条 README）
3. 当基准库里已有 50+ 卷新样本后，把所有作家 YAML 的 `calib_version` 改为 `'v0.3.0'` 重跑，获得稳定分位数阈值
4. 用 `lineage_viewer.py` 汇总所有 `*_lineage.json` 生成谱系 HTML + PNG 排名表
