japanese/README_cleaner.md

Japanese Cleaner - 日语词表清洗工具

工程化的日语词表清洗流水线，自动化处理汉字-假名-拼音对齐。采用任务化架构： 每次清洗是一个跨会话、有状态、可并存的任务。

完整协作规范见 WORKFLOW.md。

功能特性

• 任务化：每次清洗是独立任务（独立配置 + 独立临时文件 + 状态机），多任务可并存
• 两层分离：单批临时工作区 / 最终只增去重的权威库
• 数据源只读：处理时不修改原文件，支持任意切片（起始行 + 条数）
• 严格校验：输入输出条数自动校验
• 半自动协作：自动分流 + 人工 review + 改代码重跑
• 单元测试：核心逻辑全覆盖

数据目录布局

data/
├── db/                          # 权威成品库（只增不删 + 去重）
│   ├── vocabulary.txt           # 所有批次累积的成品
│   └── skipped.txt              # 所有批次累积的跳过项
├── sources/                     # 原始数据源（只读）
│   └── xinbiaori_1.txt
└── backup/                      # 备份
    └── *.backup.txt

tasks/
└── {task_id}/                   # 每个任务独立目录
    ├── task.json                # 任务配置 + 状态
    ├── auto_done.txt            # 单批结果
    ├── skip.txt
    └── review_*.txt             # 待确认桶

入口方式

本项目的清洗流程需要人工介入（review 循环：改字典/规则 → 重跑），因此 推荐用测试驱动协作（见 tests/test_cleaner_workflow.py）， 命令行只是便捷入口。

三种等价的命令行入口：

jclean <cmd> ...                          # 安装后的 console 命令（推荐）
python -m pl_japanese.cleaner.cli <cmd> ... # 模块调用（无需 console 入口）
python scripts/clean.py <cmd> ...          # 兼容薄壳（未安装包时）

安装（开发模式，注册 jclean 命令）：

pip install -e .

快速开始

# 创建任务（数据源只读，可指定处理范围）
jclean create batch1 --source data/sources/xinbiaori_1.txt --start 1 --count 300

# 处理一批数据（分流到单批文件）
jclean process batch1

# 查看任务状态
jclean status batch1

# 列举所有任务
jclean list

# 重跑某个 review 桶（修正字典/规则后）
jclean reprocess batch1 --bucket pinyin

# 合并单批结果到权威库（review 全清零后）
jclean merge batch1 --dry-run   # 先校验
jclean merge batch1             # 正式合并

# 清空任务的单批文件
jclean clear batch1

代码调用

from pl_japanese.cleaner import TaskManager, BatchProcessor

tm = TaskManager()

# 创建任务（权威库路径默认全局，可覆盖）
task = tm.create_task(
    task_id='batch1',
    source='data/sources/xinbiaori_1.txt',
    start_line=1,
    count=300,
)

# 处理一批
bp = BatchProcessor(task)
result = bp.process_batch()
print(f"处理 {result['valid_lines']} 条，auto {result['buckets']['auto']} 条")

# review 全清零后合并
bp.merge_all(dry_run=True)   # 校验
bp.merge_all()               # 正式合并

任务状态机

created → processing → reviewing → ready → merged

• created — 已创建，未处理
• processing — 已跑分类
• reviewing — review 中，部分桶待确认
• ready — review 全清零，待合并
• merged — 已合并进权威库，完成

核心规则

规则	说明	例
无汉字词跳过	汉字段不含汉字 → skip	IT:アイティー:
混合词正常处理	字母作为独立段	`JC
含~自动处理	~ 是任意长通配，对齐后丢弃	経営～:けいえいします: → `経
ます形转原型	五段/一段动词转辞書形（词典验证）
完整表达保留	寒暄句保留 ます → review_verb
々展开	同字重复符号自动展开	我々:われわれ: → `我

完整规则见 tests/data/rules.md。

输出分类桶

自动分类：

• auto_done.txt — 高置信度，可直接使用
• skip.txt — 无汉字词，已跳过

需人工确认：

• review_pinyin.txt — 含多音字，需校对拼音
• review_split.txt — 假名分割失败，需手动处理
• review_verb.txt — 动词/完整表达，需确认形式
• review_special.txt — 含字母/片假名，需人工判断

关键设计原则

1. 任务化 — 每次清洗是有状态、可并存的任务，路径是任务配置而非全局配置
2. 数据源只读 — 处理时不修改原文件
3. 单批/最终两层分离 — 单批临时工作区，权威库只增去重
4. 改代码而非改文件 — 指出问题后改字典/规则重跑，不手改输出文件
5. 合并需授权 — 只有明确说"合并"才执行合并到权威库
6. 去重保证幂等 — 多次合并同一数据不会重复

项目结构

japanese/
├── src/pl_japanese/cleaner/     # 核心模块
│   ├── task.py                  # 任务模型（配置 + 状态机）
│   ├── task_manager.py          # 任务管理器
│   ├── batch_processor.py       # 批处理调度
│   ├── classifier.py            # 词条分类
│   ├── aligner.py               # 汉字-假名对齐
│   ├── pinyin_maker.py          # 拼音生成
│   ├── pinyin_overrides.py      # 多音字覆盖字典
│   ├── rules.py                 # 规则配置
│   ├── validator.py             # 格式校验
│   ├── cli.py                   # 命令行外壳（jclean 入口）
│   └── __main__.py              # python -m 入口
├── scripts/clean.py             # CLI 兼容薄壳（未安装包时用）
├── data/                        # 数据（db / sources / backup）
├── tasks/                       # 任务目录
└── tests/
    ├── test_cleaner_workflow.py # 工作流测试（任务驱动协作）
    └── ...

运行测试

pytest tests/ -v

工作流本身需要人工介入，日常"处理 → review → 重跑 → 合并"协作推荐用 tests/test_cleaner_workflow.py 里的任务驱动方式， 或 jclean / python -m pl_japanese.cleaner.cli 命令行。

依赖

• Python 3.11+
• jamdict / pypinyin / pydantic / loguru
• pytest（测试）