japanese/README.md

Japanese Vocabulary Cleaner

日语词表清理工具 — 半自动处理「汉字 + 假名 + 拼音」三段式词表。

---

项目简介

本项目用于清理和规范化日语词表数据，将原始格式转换为标准的三段式格式：

输入：日本人:にほんじん:
输出：日|本|人:に|ほん|じん:ri|ben|ren

核心功能：

• 🔍 自动分割 — 汉字/假名智能对齐，管道符分割
• 🔤 拼音生成 — 基于 pypinyin + 多音字字典（数据外置）
• 🤖 智能分类 — 成功/失败/待审核自动分流
• 📋 任务管理 — 批次隔离、状态机、断点续处理
• 🔄 Review 交互 — 交互式逐条确认或文件标注批量处理
• ⚙️ 配置驱动 — TOML 配置文件，多项目友好

---

快速开始

安装

# 安装项目（开发模式）
pip install -e .

# 验证安装
jclean --help

创建第一个任务

# 1. 初始化配置文件（可选）
jclean init-config

# 2. 创建清理任务
jclean create my_task --source data/sources/xinbiaori_1.txt

# 3. 运行任务
jclean run my_task

# 4. 查看状态
jclean status my_task

# 5. Review 确认（两种方式）
# 方式1: 交互式逐条确认
jclean review my_task --bucket pinyin

# 方式2: 编辑 review 文件标注后批量应用
jclean review my_task --bucket pinyin --apply

# 6. 所有 review 清零后，继续推进（合并到最终库）
jclean run my_task

详细使用说明:

• 完整工作流 → docs/design/WORKFLOW.md
• Review 交互指南 → docs/REVIEW_GUIDE.md
• CLI 命令参考 → README_cleaner.md

生成学习资料

清洗完成的权威库可以生成多维学习资料（汉字读音手册、拼音对照表、音读规律、Anki 卡片等）：

# 列出所有可生成的资料类型
jlearn list

# 生成全套学习资料（默认输出到 ./study_materials）
jlearn generate

# 指定权威库和输出目录
jlearn generate --vocab data/db/vocabulary.txt --output-dir my_materials

# 只生成指定类型
jlearn generate --only handbook,anki

详细说明 → docs/LEARNER.md

---

项目结构

japanese/
├── src/pl_japanese/
│   ├── cleaner/              # 清理工具核心（三层架构）
│   │   ├── tango_analyser.py    # 底层：单词分析
│   │   ├── task_processor.py    # 中层：文件 I/O、桶管理
│   │   ├── workflow.py           # 顶层：状态机、任务推进
│   │   ├── cli.py                # 命令行接口
│   │   ├── config.py             # 配置文件管理
│   │   └── ...
│   ├── learner/              # 学习资料生成器
│   │   ├── builder.py            # 加载权威库、预建索引
│   │   ├── generators.py         # 文本类资料生成器 + 音训读判断
│   │   ├── html_generator.py     # 交互式 HTML 单页应用
│   │   └── cli.py                # jlearn 命令行接口
│   ├── tango/                # Tango 数据模型（下游）
│   └── dict_utils.py         # 词典工具
│
├── tests/                    # 测试（92 个）
│   ├── test_cleaner.py           # 底层单元测试
│   ├── test_cleaner_workflow.py  # 三层集成测试
│   ├── test_config.py            # 配置管理测试
│   ├── test_learner.py           # 学习资料生成器测试
│   └── ...
│
├── scripts/
│   ├── clean.py              # jclean 便捷入口（未安装包时）
│   └── mdlint.cmd            # Markdown lint 检查
│
├── data/
│   ├── db/                   # 权威库（最终成果）
│   │   ├── vocabulary.txt        # 清理完成的词表
│   │   └── skipped.txt           # 跳过的词条
│   └── sources/              # 原始数据源
│
├── tasks/                    # jclean 任务目录（每任务一个子目录）
│   └── my_task/
│       ├── task.json             # 任务元数据
│       ├── auto_done.txt         # 自动处理成功
│       ├── skip.txt              # 跳过（无汉字等）
│       └── review_*.txt          # 待人工确认
│
├── study_materials/          # jlearn 生成的学习资料
│   ├── overview.txt              # 数据总览
│   ├── kanji_handbook.txt        # 汉字读音手册
│   ├── jukujikun.txt             # 熟字训词表
│   ├── pinyin_kana_mapping.txt   # 拼音→汉字→假名对照表
│   ├── pinyin_kana_kanji_mapping.txt  # 拼音→假名→汉字对照表（读音规律复用）
│   ├── phonetic_rules.txt        # 音读规律总结
│   ├── anki_deck.txt             # Anki 卡片（TSV）
│   └── study_app.html            # 交互式单页应用（多维互链查询）
│
├── docs/                     # 项目文档
│   ├── design/                   # 设计文档
│   ├── history/                  # 历史记录
│   ├── LEARNER.md                # jlearn 使用指南
│   └── REVIEW_GUIDE.md           # Review 交互指南
│
├── jclean.toml               # jclean 配置文件
├── pyproject.toml            # 项目配置
└── README_cleaner.md         # jclean 用户文档

---

核心特性

数据清洗（jclean）

三层架构

┌─────────────────────────────────────┐
│  CleanerWorkflow (顶层)              │  状态机、任务推进
│  - run() 统一入口                    │
│  - 状态转换：CREATED → PROCESSING   │
│              → REVIEWING → READY    │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  TaskProcessor (中层)                │  文件 I/O、桶管理
│  - process_source()                 │  无状态更新
│  - reprocess_bucket()               │
│  - merge_to_authoritative()         │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  TangoAnalyser (底层)                │  单词级分析
│  - analyze(kanji, kana)             │  无文件/桶概念
│  - 返回 AnalysisResult              │
└─────────────────────────────────────┘

设计细节见 docs/design/WORKFLOW.md。

智能分类

处理结果自动分流到 5 个桶：

桶名	说明	自动处理
auto_done.txt	成功：单音字、唯一分割	✅
skip.txt	跳过：无汉字、纯假名	✅
review_pinyin	多音字：已填最常见读音	⚠️ 人工
review_split	分割失败：假名对齐失败	⚠️ 人工
review_verb	动词形态：する/でした 结尾	⚠️ 人工
review_special	特殊格式：片假名/符号/～	⚠️ 人工

配置文件驱动

# jclean.toml
[paths]
tasks_root = "tasks"
vocabulary = "data/db/vocabulary.txt"
skipped = "data/db/skipped.txt"

[defaults]
backup_before_merge = true
backup_dir = "data/backup"

[logging]
level = "INFO"

配置文件查找顺序：--config > 当前目录 > 项目根 > ~/.jclean.toml > 默认值

详细说明见 docs/design/CONFIG_FILE_DESIGN.md。

学习资料生成（jlearn）

从清洗完成的权威库生成多维学习资料，借助拼音帮助母语者快速掌握日语汉字读音：

8 种学习资料

资料类型	说明	适用场景
数据总览	汉字统计、一字多音分布、高频核心字	了解数据全貌、规划学习重点
汉字读音手册	每个单字按读音分组 + 例词（拼音锚定）	系统掌握一字多音（生 9 音、日 8 音）
熟字训词表	整词读音无法拆字的条目（如 今日→きょう）	整体记忆特殊词汇
拼音→汉字→假名	从中文拼音出发，按汉字分组	利用母语直觉迁移记忆
拼音→假名→汉字	按假名分组，发现读音规律复用（如 an→あん 在 安/暗/案 中都成立）	提炼可推理规律、减少死记硬背
音读规律总结	拼音与假名对应模式统计（如 -ng 结尾 74% 带长音）	发现宏观统计规律
Anki 卡片	TSV 格式，可直接导入 Anki	间隔重复背诵
交互式 HTML 应用	单页应用，拼音·汉字·假名多维互链，可搜索、离线可用	随点随查、交叉导航

性能优化

• 预建 (汉字,假名)→拼音 反查索引，避免 O(N²) 遍历
• 7552 词权威库全量生成 < 5 秒

详细说明 → docs/LEARNER.md

---

测试

# 运行全部测试（92 个）
pytest tests/ -v

# 按模块测试
pytest tests/test_config.py          # 配置管理
pytest tests/test_cleaner_workflow.py # 三层集成
pytest tests/test_cleaner.py          # 底层单元
pytest tests/test_validator.py        # 格式校验
pytest tests/test_learner.py          # 学习资料生成器

---

文档

• 用户文档
  • README_cleaner.md — jclean 工具使用指南
  • docs/LEARNER.md — jlearn 学习资料生成器指南
• 设计文档 → docs/design/ — 架构、工作流、配置方案
• 交互指南 → docs/REVIEW_GUIDE.md — Review 确认流程
• 历史记录 → docs/history/ — 重构总结、变更日志

完整文档索引见 docs/README.md。

---

开发

环境搭建

# 克隆项目
git clone <repo>
cd japanese

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖（开发模式）
pip install -e .
pip install pytest

# 运行测试
pytest tests/

目录约定

• src/ — 源代码（src-layout）
• tests/ — 测试（pytest，pythonpath = ["src"]）
• tasks/ — jclean 任务工作目录（git ignore）
• data/db/ — 权威库（最终成果，git 跟踪）
• data/sources/ — 原始数据源（git 跟踪）
• docs/ — 项目文档
• scripts/ — 工具脚本

---

版本历史

v0.4.0 (当前)

• ✅ 学习资料生成器（jlearn）
  • 8 种资料：汉字手册、熟字训表、拼音→汉字→假名、拼音→假名→汉字（读音规律复用）、音读规律、Anki 卡片、数据总览、交互式 HTML 应用
  • 音读/训读启发式标注（音读可迁移、训读需单记）
  • 交互式 HTML 单页应用：拼音·汉字·假名多维互链，可搜索、离线可用
  • 单字/熟字训自动区分（1784 单字 + 35 熟字训）
  • 性能优化：预建反查索引，7552 词 < 5 秒生成
• ✅ 92 个测试（+8 learner 测试）

v0.3.0

• ✅ 配置文件系统（TOML 格式，多项目支持）
• ✅ 配置简化（移除不必要的默认值）
• ✅ UTF-8 BOM 容错
• ✅ 项目目录清理（脚本归档、文档整理）

v0.2.0

• ✅ 三层架构重构（底层/中层/顶层职责分离）
• ✅ 任务化管理（批次隔离、状态机）
• ✅ CLI 简化（统一 jclean run 命令）
• ✅ 73 个测试覆盖

v0.1.0

• 🗑️ 单文件 500+ 行脚本（已废弃）
• 🗑️ 全局变量、硬编码路径（已重构）

---

许可

(待添加)

---

联系

(待添加)