1f64c87d0e
- 任务化清洗流程：Task/TaskManager + BatchProcessor 三方法
- 数据目录规范化：data/{db,sources,backup}
- CLI 入口移进包，注册 jclean 命令
- 工作流测试驱动（tests/test_cleaner_workflow.py）
- 40 测试通过
193 lines
6.5 KiB
Markdown
193 lines
6.5 KiB
Markdown
# Japanese Cleaner - 日语词表清洗工具
|
||
|
||
工程化的日语词表清洗流水线，自动化处理汉字-假名-拼音对齐。采用**任务化架构**：
|
||
每次清洗是一个跨会话、有状态、可并存的任务。
|
||
|
||
> 完整协作规范见 [`WORKFLOW.md`](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`](tests/test_cleaner_workflow.py)），
|
||
命令行只是便捷入口。
|
||
|
||
三种等价的命令行入口：
|
||
|
||
```bash
|
||
jclean <cmd> ... # 安装后的 console 命令（推荐）
|
||
python -m pl_japanese.cleaner.cli <cmd> ... # 模块调用（无需 console 入口）
|
||
python scripts/clean.py <cmd> ... # 兼容薄壳（未安装包时）
|
||
```
|
||
|
||
安装（开发模式，注册 `jclean` 命令）：
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 创建任务（数据源只读，可指定处理范围）
|
||
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
|
||
```
|
||
|
||
## 代码调用
|
||
|
||
```python
|
||
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|自|動|車:...` |
|
||
| 含~自动处理 | ~ 是任意长通配，对齐后丢弃 | `経営～:けいえいします:` → `経|営:けい|えい:jing|ying` |
|
||
| ます形转原型 | 五段/一段动词转辞書形（词典验证） | |
|
||
| 完整表达保留 | 寒暄句保留 ます → `review_verb` | |
|
||
| 々展开 | 同字重复符号自动展开 | `我々:われわれ:` → `我|我:われ|われ:wo|wo` |
|
||
|
||
完整规则见 [`tests/data/rules.md`](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 # 工作流测试（任务驱动协作）
|
||
└── ...
|
||
```
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
pytest tests/ -v
|
||
```
|
||
|
||
工作流本身需要人工介入，日常"处理 → review → 重跑 → 合并"协作推荐用
|
||
[`tests/test_cleaner_workflow.py`](tests/test_cleaner_workflow.py) 里的任务驱动方式，
|
||
或 `jclean` / `python -m pl_japanese.cleaner.cli` 命令行。
|
||
|
||
## 依赖
|
||
|
||
- Python 3.11+
|
||
- jamdict / pypinyin / pydantic / loguru
|
||
- pytest（测试）
|