ef3df73166
清洗管线重构为严格三层架构：
- tango_analyser.py（底层：单词分析）
- task_processor.py（中层：文件 I/O、桶管理）
- workflow.py（顶层：状态机、任务推进）
- 移除旧的 batch_processor.py
新增配置文件系统：
- config.py：TOML 配置，相对路径相对配置文件目录解析
- 查找优先级 --config > cwd > 项目根 > ~ > 默认值
- count=None 语义为处理到文件末尾
项目目录整理：
- 根脚本归档到 scripts/analysis 与 scripts/legacy
- 文档归档到 docs/{design,history,analysis}
- 临时报告移到 reports/（已 gitignore）
文档质量：
- 新增 .markdownlint.json 与 scripts/mdlint.cmd
- 修复全部 14 个 md 文件的 markdownlint 警告
测试：74 passed（8 cleaner + 31 workflow + 6 tango + 15 validator + 14 config）
269 lines
7.8 KiB
Markdown
269 lines
7.8 KiB
Markdown
# Japanese Vocabulary Cleaner
|
||
|
||
日语词表清理工具 — 半自动处理「汉字 + 假名 + 拼音」三段式词表。
|
||
|
||
---
|
||
|
||
## 项目简介
|
||
|
||
本项目用于清理和规范化日语词表数据，将原始格式转换为标准的三段式格式：
|
||
|
||
```text
|
||
输入：日本人:にほんじん:
|
||
输出：日|本|人:に|ほん|じん:ri|ben|ren
|
||
```
|
||
|
||
核心功能：
|
||
|
||
- 🔍 **自动分割** — 汉字/假名智能对齐，管道符分割
|
||
- 🔤 **拼音生成** — 基于 pypinyin + 多音字规则
|
||
- 🤖 **智能分类** — 成功/失败/待审核自动分流
|
||
- 📋 **任务管理** — 批次隔离、状态机、断点续处理
|
||
- ⚙️ **配置驱动** — TOML 配置文件，多项目友好
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 安装项目（开发模式）
|
||
pip install -e .
|
||
|
||
# 验证安装
|
||
jclean --help
|
||
```
|
||
|
||
### 创建第一个任务
|
||
|
||
```bash
|
||
# 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 文件后重跑
|
||
jclean run my_task --bucket pinyin
|
||
```
|
||
|
||
详细使用说明见 [README_cleaner.md](README_cleaner.md)。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
japanese/
|
||
├── src/pl_japanese/
|
||
│ ├── cleaner/ # 清理工具核心（三层架构）
|
||
│ │ ├── tango_analyser.py # 底层：单词分析
|
||
│ │ ├── task_processor.py # 中层：文件 I/O、桶管理
|
||
│ │ ├── workflow.py # 顶层：状态机、任务推进
|
||
│ │ ├── cli.py # 命令行接口
|
||
│ │ ├── config.py # 配置文件管理
|
||
│ │ └── ...
|
||
│ ├── tango/ # Tango 数据模型（下游）
|
||
│ └── dict_utils.py # 词典工具
|
||
│
|
||
├── tests/ # 测试（74 个）
|
||
│ ├── test_cleaner.py # 底层单元测试
|
||
│ ├── test_cleaner_workflow.py # 三层集成测试
|
||
│ ├── test_config.py # 配置管理测试
|
||
│ └── ...
|
||
│
|
||
├── scripts/
|
||
│ ├── analysis/ # 未来要集成的分析工具
|
||
│ │ ├── analyze_phonetics.py # 发音规律统计
|
||
│ │ └── validate_data.py # 数据质量校验
|
||
│ └── legacy/ # 已废弃的旧脚本
|
||
│
|
||
├── data/
|
||
│ ├── db/ # 权威库（最终成果）
|
||
│ │ ├── vocabulary.txt # 清理完成的词表
|
||
│ │ └── skipped.txt # 跳过的词条
|
||
│ └── sources/ # 原始数据源
|
||
│
|
||
├── tasks/ # jclean 任务目录（每任务一个子目录）
|
||
│ └── my_task/
|
||
│ ├── task.json # 任务元数据
|
||
│ ├── auto_done.txt # 自动处理成功
|
||
│ ├── skip.txt # 跳过（无汉字等）
|
||
│ └── review_*.txt # 待人工确认
|
||
│
|
||
├── docs/ # 项目文档
|
||
│ ├── design/ # 设计文档
|
||
│ ├── history/ # 历史记录
|
||
│ └── analysis/ # 分析报告
|
||
│
|
||
├── reports/ # 临时分析报告
|
||
├── jclean.toml # jclean 配置文件
|
||
├── pyproject.toml # 项目配置
|
||
└── README_cleaner.md # jclean 用户文档
|
||
```
|
||
|
||
---
|
||
|
||
## 核心特性
|
||
|
||
### 三层架构
|
||
|
||
```text
|
||
┌─────────────────────────────────────┐
|
||
│ 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](docs/design/WORKFLOW.md)。
|
||
|
||
### 智能分类
|
||
|
||
处理结果自动分流到 5 个桶：
|
||
|
||
| 桶名 | 说明 | 自动处理 |
|
||
| ------ | ------ | --------- |
|
||
| `auto_done.txt` | 成功：单音字、唯一分割 | ✅ |
|
||
| `skip.txt` | 跳过：无汉字、纯假名 | ✅ |
|
||
| `review_pinyin` | 多音字：已填最常见读音 | ⚠️ 人工 |
|
||
| `review_split` | 分割失败：假名对齐失败 | ⚠️ 人工 |
|
||
| `review_verb` | 动词形态：する/でした 结尾 | ⚠️ 人工 |
|
||
| `review_special` | 特殊格式：片假名/符号/～ | ⚠️ 人工 |
|
||
|
||
### 配置文件驱动
|
||
|
||
```toml
|
||
# 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](docs/design/CONFIG_FILE_DESIGN.md)。
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行全部测试（74 个）
|
||
pytest tests/ -v
|
||
|
||
# 按模块测试
|
||
pytest tests/test_config.py # 配置管理
|
||
pytest tests/test_cleaner_workflow.py # 三层集成
|
||
pytest tests/test_cleaner.py # 底层单元
|
||
pytest tests/test_validator.py # 格式校验
|
||
```
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
- **用户文档** → [README_cleaner.md](README_cleaner.md) — jclean 工具使用指南
|
||
- **设计文档** → [docs/design/](docs/design/) — 架构、工作流、配置方案
|
||
- **历史记录** → [docs/history/](docs/history/) — 重构总结、变更日志
|
||
- **分析报告** → [docs/analysis/](docs/analysis/) — 数据分析、Review 桶统计
|
||
|
||
完整文档索引见 [docs/README.md](docs/README.md)。
|
||
|
||
---
|
||
|
||
## 开发
|
||
|
||
### 环境搭建
|
||
|
||
```bash
|
||
# 克隆项目
|
||
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.3.0 (当前)
|
||
|
||
- ✅ 配置文件系统（TOML 格式，多项目支持）
|
||
- ✅ 配置简化（移除不必要的默认值）
|
||
- ✅ UTF-8 BOM 容错
|
||
- ✅ 项目目录清理（脚本归档、文档整理）
|
||
|
||
### v0.2.0
|
||
|
||
- ✅ 三层架构重构（底层/中层/顶层职责分离）
|
||
- ✅ 任务化管理（批次隔离、状态机）
|
||
- ✅ CLI 简化（统一 `jclean run` 命令）
|
||
- ✅ 73 个测试覆盖
|
||
|
||
### v0.1.0
|
||
|
||
- 🗑️ 单文件 500+ 行脚本（已废弃）
|
||
- 🗑️ 全局变量、硬编码路径（已重构）
|
||
|
||
---
|
||
|
||
## 许可
|
||
|
||
(待添加)
|
||
|
||
---
|
||
|
||
## 联系
|
||
|
||
(待添加)
|