# ldu-reader

**Repository Path**: sifu-ye/ldu-reader

## Basic Information

- **Project Name**: ldu-reader
- **Description**: 汉语文本阅读难度评估 V5 完全本地离线版（官方 GF0025/HSK3.0 字词语法表 + LTP 分词）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 阅读难度评估 · V8 完全本地离线版

基于《国际中文教育中文水平等级标准》（GF0025，对外汉语部分 = HSK 3.0）官方数据
的汉语文本阅读难度评估工具。**完全本地运行（不联网）**，输出与 LDU-TGP 网站同构的
Word 分析报告。

## 功能

- 扫描目录下所有**分章文件 `x-x-x.docx`**（如 1-1-1.docx、3-2-10.docx）；其他文件名（含整册 `x-x.docx`）自动跳过，避免口径混用
- **输入约定**：每个分章文件 = 一课【纯正文】，不含练习内容；按文件全文整体分析（篇名/标题首行当前计入正文，如需排除请按"说明"并另行开发）
- **同组章节自动合并**：`x-x` 前缀的分章合并为 `x-x.docx`（仅语料存档），并生成 `x-x_分析报告.docx` = **整合统计报告**（每课结果表 + 分值均值/中位数/标准差/等级课数/全课字词语法并集；**不重算整册文本**）
- **LTP 分词**（与网站同一分词器），GF0025 官方字/词/语法表分级
- **整合统计**：每个 docx 内部全文整合分析，不分课统计；输出每个 docx 的全文语料
- **词汇按 (词形, 词性) 联合定级**，跨词性多级词不再一律取最低级；同词性仍多级者
  标记为“多级候选”并保守取最低级
- **LTP 依存句法检测器已接入主流程**（cws+pos+dep），把字句/被动句/兼语句/补语等
  句法点进入可信覆盖统计
- 语法表编号已修复为 1..572 唯一完整，正则均可编译；课标题支持“第X课”与“1. 标题”
  两种格式
- **语法规则更精确**：官方表自带正则才计入“可信覆盖/可自动检测”；补全正则仅作候选
  提示，不计分、不进入分级语法明细，避免为覆盖率而扩张规则
- 难度分值 = 论文 GF0025 公式（与网站存在约 0.3-0.4 差异，网站内部细节未公开）
- 统计字段：总字数/字种/总词数/词种/句子/平均句长
  - **词种数按“(词形,词性)”统计**，只统计官方词表内命中的词；同一词形不同词性分别计数
- 生成页面同构 Word 报告（含分值/级别/分级体系/基本情况/分级字词语法明细/语法覆盖/引用/方法说明）

## 使用

```bash
# 命令行运行
python batch_report_v4.py --dir ./教材目录

# 或打包为 exe（文件夹版）：exe 与 docx 同目录，双击运行
# 输出：分析报告/x-x-x_分析报告.docx、x-x_分析报告.docx（整合统计报告）、x-x.docx（语料存档）、
#       分析结果汇总.csv、逐课结果.json、整合统计.json（分值均值/中位数/标准差/等级课数/全课并集/次数累加）、
#       语料清单.csv（文件名/前缀/章节号/sha256/段落数/字数）、语料段落.jsonl（段落级溯源）、
#       {prefix}_语法可信命中/_候选触发/_候选触发汇总/_规则状态表.csv（四件套，逐条含文件列）
```

## 官方数据（data/ 目录）

| 文件 | 内容 | 来源 |
|---|---|---|
| GF0025_汉字.csv | 3000 分级汉字 | 官方 hsk30-chars（教育部标准 PDF 的 OCR 整理版） |
| GF0025_词汇.csv | 11129 条展开后词汇（10978 个不同表面词形，含词性） | 官方 hsk30-expanded |
| GF0025_词汇_规范.csv | 11092 条原始规范词条，保留唯一标准 ID | 原始标准词表 |
| GF0025_词汇_别名.csv | 规范写法到表面形式的别名映射，运行时核心加载此表 | 由规范表展开生成 |
| GF0025_语法_with_regex.csv | 572 条分级语法点（正则匹配） | 官方 hsk30-grammar |

> 部署说明：源码运行时数据目录 `DATA_DIR` 默认指向
> `../python-readability-cn-main/readability_cn/data`，可将本仓库 `data/` 下三份
> CSV 复制覆盖到该目录（或按需修改 `core.py` 的 `DATA_DIR`）。

## 依赖

```bash
pip install -r requirements.txt
```

- `ltp` + `torch` + `transformers<5`：LTP 分词模型（small，约 172MB；仓库自带分片，
  首次运行自动合并；缺失时回退从 `https://hf-mirror.com` 镜像下载模型名）
- 全项目分词统一 LTP（V23 起移除 jieba 依赖）
- LTP 兼容性说明：需 `transformers<5` 或按 `ltp/nerual.py` 中
  `batch_encode_plus` 兼容补丁修改（详见源码注释）
- 用户交付：`阅读难度评估V16离线版.spec` 打 exe（PyInstaller，经 collect_all
  固化依赖与模型，终端用户无需安装依赖）

## 标准对比与论文数据复现

```bash
# 3-1 单册逐项对比
python compare_with_standard.py

# 3-1~3-5 全五册论文数据复现（推荐）
python reproduce_paper.py
```

`compare_with_standard.py` 解析 `资料/3-1.docx` 的15篇课文，与《标准》论文（过文英 2025）
表1/表3 第1册及三级字/词/语法/文化指标逐项对比。

`reproduce_paper.py` 解析 3-1~3-5 全部75篇课文，复现论文：
- 表1 汉字等级分布（第1、3、4册完全复现）
- 表3 词汇等级分布（趋势一致，分词器差异为部分符合）
- 五册整体三级汉字覆盖 298/300、缺失 批/血、复现分布 245/11/16/14 完全复现
- 五册整体三级词汇可信自动覆盖 799/953（普通分词×官方唯一词表；论文881/973为GradeFind+人工校对口径）
- 词汇全等级覆盖与复现（1-5级重点，见 `分析报告/词汇等级覆盖复现_全等级.csv`）
- LTP 分词词汇复现（见 `分析报告/ltp_vocabulary_result.json`、`分析报告/词汇表3_LTP复现对比.csv`）：按完整句子切块（≤400字）分别送入 LTP，合并类型集合后统计，不再截断；三级词覆盖835/953（87.62%）
- LTP 运行方式：`LTP_PYTHON=/path/to/ltp-python python3 batch_report_v4.py ...`，或运行 `download_ltp_model.py` 下载模型后使用本机 LTP
- LTP 环境安装：`python3 install_ltp_env.py --install && python3 install_ltp_env.py --model`
- LTP 模型下载：`python download_ltp_model.py`（默认 hf-mirror.com）
- 三级语法原始正则覆盖 40/81、LTP可信句法合并覆盖 58/81、候选触发 72/81（全等级572个语法点已100%配置触发规则；LTP为分块合并）
- 文化一级项目 3/3 覆盖，二级32项全覆盖（官方目录 OCR，见 `data/参考框架_二级文化项目.csv`）

输出：`分析报告/论文数据复现报告.docx`、`.md`、`论文数据复现结果.json`。

## 模块结构

```
core.py             # 分析核心：GF0025 公式 + LTP 分词 + 分级明细 + 统计（词种=词表命中）
report.py           # Word 报告生成（页面同构，完全本地）
batch_report_v4.py  # 主入口：分章文件 x-x-x.docx → 完全本地 LTP 分析 → Word 报告
docx_io.py          # docx 读件/切分公共库（分章/整册读件，无分析入口）
build_grammar_evidence.py  # 金标证据与候选样本池生成（第6项门控数据管线）
server.py           # 本地 Web 服务版（文本输入）
```

## 说明

- 分值采用论文《基于新标准的汉语二语文本阅读难度分级体系构建及应用》（程勇等，
  《世界汉语教学》2023）公式；统计口径与网站一致（LTP 同分词器）
- 词表/字表/语法表全部为官方标准数据（教育部 GF0025 / HSK 3.0）