2e4dcf8980
新增学习资料生成器模块（learner），从权威库生成多维日语学习资料： - 拼音/假名/汉字/熟字训四类索引，带拼音↔假名↔汉字交叉跳转 - 逐字音训分类（KANJIDIC2 精确查表 + 启发式回退 + 排序键） - 音变标注体系：浊化（連濁）、半浊化、促音变（促音便）、连声（れんじょう） 独立配色 + 合并逻辑 + 音变规律说明 - 显式标注表：rendaku_marks（连用形连浊）、renjou_marks（连声） - 每索引独立例词数配置（jlearn.toml + --config） - HTML 单页应用 + 静态 HTML + PDF（playwright） 清洗工具增强： - 拼音校验器（pinyin_checker）集成到 jclean - 多音字拼音校正、ます形サ変動詞转原型 数据： - 权威库补充连声词（反応/天皇/陰陽/観音/因縁/三位/輪廻/安穏） - KANJIDIC2 音训分类表、拼音校正字典 整理 .gitignore：忽略生成产物（output/study_materials）、词典数据库、 任务运行日志、备份文件
325 lines
10 KiB
Markdown
325 lines
10 KiB
Markdown
# 清洗工作流完整协作规范（任务化架构）
|
||
|
||
## 核心抽象：任务（Task）
|
||
|
||
整个清洗流程**无法全自动完成**（中间必须人工 review 干预），所以每次处理是一个
|
||
**跨会话、有生命周期状态的任务**。所有文件路径都是任务的配置项，不是全局静态配置。
|
||
|
||
**一个任务 = 独立配置 + 独立临时文件 + 状态机**，多任务可并存。
|
||
|
||
### 任务目录结构
|
||
|
||
每个任务在 `tasks/{task_id}/` 下有独立目录：
|
||
|
||
```text
|
||
tasks/
|
||
└── {task_id}/
|
||
├── task.json # 任务配置 + 状态
|
||
├── auto_done.txt # 该任务的单批结果
|
||
├── skip.txt
|
||
├── review_pinyin.txt
|
||
├── review_split.txt
|
||
├── review_verb.txt
|
||
└── review_special.txt
|
||
```
|
||
|
||
### 任务状态机
|
||
|
||
```text
|
||
created → processing → reviewing → ready → merged
|
||
```
|
||
|
||
- `created` — 已创建，未处理
|
||
- `processing` — 已跑分类
|
||
- `reviewing` — review 中，部分桶待确认
|
||
- `ready` — review 全部清零，待合并
|
||
- `merged` — 已合并进最终库，完成
|
||
|
||
---
|
||
|
||
## 文件两层结构
|
||
|
||
### 单批处理结果（任务独立，临时，review 完成后归入 auto_done/skip）
|
||
|
||
- `auto_done.txt` — 本批成功处理的词条
|
||
- `skip.txt` — 本批无汉字跳过的词条
|
||
- `review_pinyin.txt` — 含多音字，待确认拼音
|
||
- `review_split.txt` — 假名无法分割，待判断能否处理
|
||
- `review_verb.txt` — 动词/完整表达，待确认形式
|
||
- `review_special.txt` — 含字母/片假名，待确认
|
||
|
||
### 最终权威数据（累积，只增不删+去重）
|
||
|
||
- `data/db/vocabulary.txt` — 所有批次累积的成品词表
|
||
- `data/db/skipped.txt` — 所有批次累积的跳过项
|
||
|
||
权威库路径也是任务配置项（默认指向全局那份，任务可覆盖）。
|
||
|
||
### 项目数据目录布局
|
||
|
||
```text
|
||
data/
|
||
├── db/ # 权威成品库（只增不删+去重）
|
||
│ ├── vocabulary.txt # 成品词表
|
||
│ └── skipped.txt # 累积跳过项
|
||
├── sources/ # 原始数据源（只读）
|
||
│ └── xinbiaori_1.txt
|
||
└── backup/ # 历史备份
|
||
├── xinbiaori.backup.txt
|
||
└── xinbiaori_tobe.backup.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 入口方式
|
||
|
||
清洗流程**需要人工介入**（review 循环），推荐用**测试驱动**协作
|
||
（`tests/test_cleaner_workflow.py`）。命令行是便捷入口，三种等价写法：
|
||
|
||
```bash
|
||
jclean <cmd> ... # 安装后 console 命令（推荐）
|
||
python -m pl_japanese.cleaner.cli <cmd> ... # 模块调用
|
||
python scripts/clean.py <cmd> ... # 兼容薄壳（未安装包时）
|
||
```
|
||
|
||
## CLI 命令
|
||
|
||
```bash
|
||
# 创建任务（数据源只读，可指定处理范围）
|
||
jclean create <task_id> --source data.txt [--start 1] [--count 300] [--name "..."]
|
||
|
||
# 列举所有任务
|
||
jclean list
|
||
|
||
# 查看任务状态
|
||
jclean status <task_id>
|
||
|
||
# 处理一批数据（分流到单批文件）
|
||
jclean process <task_id> [--start N] [--count N]
|
||
|
||
# 重跑某个 review 桶（修正字典/规则后）
|
||
jclean reprocess <task_id> --bucket <pinyin|split|verb|special>
|
||
|
||
# 合并单批结果到最终库（review 全清零后）
|
||
jclean merge <task_id> [--dry-run]
|
||
|
||
# 清空任务的单批文件
|
||
jclean clear <task_id>
|
||
```
|
||
|
||
---
|
||
|
||
## 完整协作流程（5步）
|
||
|
||
### 第1步：创建任务并处理一批数据
|
||
|
||
AI 执行：
|
||
|
||
```bash
|
||
jclean create batch1 --source data/sources/xinbiaori_1.txt --start 1 --count 300
|
||
jclean process batch1
|
||
```
|
||
|
||
输出分流到6个桶：`auto_done` / `skip` / `review_*`（4个）。
|
||
任务状态变为 `reviewing`（若有 review）或 `ready`（若无 review）。
|
||
|
||
### 第2步：review 确认（两种交互方式）
|
||
|
||
任务处理完毕后进入 `reviewing` 状态,review 桶里的条目需要你确认。有**两种交互方式**:
|
||
|
||
#### 方式1:交互式逐条确认（推荐少量条目）
|
||
|
||
```bash
|
||
jclean review batch1 --bucket pinyin
|
||
```
|
||
|
||
进入逐条确认界面:
|
||
|
||
```text
|
||
[12/236] 議|会 : ぎ|かい : yi|hui # 多音字(会)
|
||
Enter=确认 / 输入新拼音=修正 / s=跳过 / q=存盘退出
|
||
>
|
||
```
|
||
|
||
- **Enter** — 当前拼音无误,确认通过,移入 `auto_done`
|
||
- **输入新拼音** — 如 `yi|kuai`,用新拼音替换并移入 `auto_done`,**自动写入拼音字典**（`pinyin_dict.toml`）
|
||
- **s** — 暂时跳过,留在 review 桶（下次 review 继续显示）
|
||
- **q** — 存盘退出,未确认的条目保留
|
||
|
||
修正的拼音默认自动写入项目拼音字典,未来批次自动生效。用 `--no-dict` 阻止写入。
|
||
|
||
#### 方式2:文件标注（推荐批量确认）
|
||
|
||
直接编辑 review 文件（如 `tasks/batch1/review_pinyin.txt`）,通过行尾标注表达意图:
|
||
|
||
| 你的编辑 | 含义 | jclean 识别 |
|
||
|---|---|---|
|
||
| 保留 `# ...请确认` | 待确认 | 跳过,留在桶里 |
|
||
| 删掉 `# ...` 注释 | 当前拼音无误 | 确认,移入 auto_done |
|
||
| 改第3段拼音 + 删注释 | 修正拼音 | 用新拼音移入 auto_done |
|
||
| 行首加 `#` (整行注释) | 删除此条 | 丢弃 |
|
||
|
||
编辑完毕后执行:
|
||
|
||
```bash
|
||
jclean review batch1 --bucket pinyin --apply
|
||
```
|
||
|
||
jclean 读取你的标注,一次性处理所有裁决。
|
||
|
||
**示例**:
|
||
|
||
```text
|
||
# 编辑前（jclean 生成）
|
||
L11 あっという|間:あっという|ま:|jian # 多音字(間),请确认
|
||
L80 議|会:ぎ|かい:yi|hui # 多音字(会),请确认
|
||
L90 責|任:せき|にん:ze|ren # 多音字(責),请确认
|
||
|
||
# 编辑后（你标注）
|
||
L11 あっという|間:あっという|ま:|jian # ✓ 删注释=确认
|
||
L80 議|会:ぎ|かい:yi|hui # 多音字(会),请确认 # ✓ 保留注释=跳过
|
||
L90 責|任:せき|にん:ze|ren2 # ✓ 改拼音+删注释=修正
|
||
```
|
||
|
||
执行 `--apply` 后:
|
||
- L11 → auto_done (拼音 `jian`)
|
||
- L80 → 留在 review_pinyin
|
||
- L90 → auto_done (拼音 `ze|ren2`)
|
||
|
||
### 第3步:review 完成后推进工作流
|
||
|
||
所有 `review_*` 清零后,任务状态变为 `ready`,继续推进:
|
||
|
||
```bash
|
||
jclean run batch1 # 合并到权威库
|
||
```
|
||
|
||
### 拼音字典（数据外置）
|
||
|
||
多音字拼音字典从 Python 源码中**外置为数据文件**:
|
||
|
||
- **位置**: 与 `jclean.toml` 同目录的 `pinyin_dict.toml`（默认）
|
||
- **格式**: TOML,两种覆盖方式:
|
||
- `[word_override]` — 整词汉字 → 完整拼音（最高优先级）
|
||
- `[kana_hint]` — "汉字|假名前缀" → 该字拼音（假名辅助消歧）
|
||
- **自动写入**: `jclean review` 修正拼音时自动追加,未来批次自动生效
|
||
- **手工编辑**: 可直接编辑该文件,重跑 review 立即生效
|
||
|
||
**示例** (`pinyin_dict.toml`):
|
||
|
||
```toml
|
||
[word_override]
|
||
"会計" = "kuai|ji" # 会计读 kuài
|
||
"銀行" = "yin|hang" # 银行读 háng
|
||
|
||
[kana_hint]
|
||
"長|なが" = "chang" # 长度义 cháng
|
||
"長|ちょう" = "zhang" # 首长义 zhǎng
|
||
```
|
||
|
||
配置路径（在 `jclean.toml`）:
|
||
|
||
```toml
|
||
[paths]
|
||
pinyin_dict = "pinyin_dict.toml" # 相对配置文件所在目录
|
||
```
|
||
|
||
### 旧流程（仍支持）:人工指出 → AI 改代码 → 重跑桶
|
||
|
||
如果不想用 `jclean review`,仍可用原流程:
|
||
|
||
1. 你打开 review 文件,**口头/文字告诉 AI 哪几条错了,应该是什么拼音**
|
||
2. AI 修改 `pinyin_dict.toml`（或更底层规则）
|
||
3. 运行 `jclean run batch1 --bucket pinyin`,jclean 用更新后的字典/规则重新处理该桶
|
||
|
||
这种方式适合"需要改代码逻辑"的复杂问题（如分割算法bug）,而非单纯拼音修正。
|
||
|
||
---
|
||
|
||
## 旧文档归档
|
||
|
||
以下是原流程描述（仍有效,但新增了 `jclean review` 更便捷的交互）:
|
||
|
||
### 第2步（旧）：你逐个 review 文件检查
|
||
|
||
你打开任务目录下的 `review_pinyin.txt` / `review_split.txt` 等，**逐条指出问题**。
|
||
|
||
**重要约定**：
|
||
|
||
- **你只指出问题，AI 只记录**（不立即修改代码）
|
||
- **单个文件你说完所有问题后**，AI 才汇总处理
|
||
|
||
### 第3步（旧）：AI 汇总修正并重跑单个 review 桶
|
||
|
||
#### 3.1 AI 汇总你指出的问题
|
||
|
||
- 多音字错误 → 更新 `pinyin_dict.toml`
|
||
- 分割规则错误 → 修改 `classifier.py` / `aligner.py` 逻辑
|
||
- 新发现的特殊情况 → 补充规则
|
||
|
||
#### 3.2 AI 重新处理该 review 桶
|
||
|
||
```bash
|
||
jclean run batch1 --bucket pinyin
|
||
```
|
||
|
||
执行后：`review_pinyin.txt` 清零，重新分类的条目进入 `auto_done` / `skip` / 其他 `review_*`。
|
||
|
||
#### 3.3 重复 3.1~3.2，直到该 review 桶清零
|
||
|
||
### 第4步（旧）：所有 review 清零后，核对总数
|
||
|
||
所有 `review_*` 清零后，AI 核对：
|
||
|
||
```text
|
||
auto_done 条数 + skip 条数 == 本批原始输入有效行数
|
||
```
|
||
|
||
校验通过后，任务状态为 `ready`，AI 告诉你"本批单批处理完成，待合并"。
|
||
|
||
### 第5步：你说"合并"，AI 执行合并
|
||
|
||
**你明确说"合并"后**，AI 执行：
|
||
|
||
```bash
|
||
jclean merge batch1 --dry-run # 先校验
|
||
jclean merge batch1 # 正式合并
|
||
```
|
||
|
||
合并操作（两条并行去重管道）：
|
||
|
||
- `auto_done.txt` → 去重合并进 `data/db/vocabulary.txt`
|
||
- `skip.txt` → 去重合并进 `data/db/skipped.txt`
|
||
|
||
合并成功后单批文件自动清零，任务标记 `merged`。**最终权威数据永远只增不删**。
|
||
|
||
---
|
||
|
||
## 关键设计原则
|
||
|
||
1. **任务化** — 每次清洗是一个有状态、可并存的任务，路径是任务配置而非全局配置
|
||
2. **数据源只读** — 处理时不修改原文件，支持任意切片（起始行+条数）
|
||
3. **单批/最终两层分离** — 单批是临时工作区，最终库是只增去重的权威数据
|
||
4. **review 是中间态** — 处理中存在，确认完必须清零（条目归入 auto_done/skip）
|
||
5. **字典是数据不是代码** — 拼音字典外置为 `pinyin_dict.toml`（项目级配置），review 修正自动写入
|
||
6. **两种 review 交互** — 交互式逐条确认（少量）或文件标注批量处理（大量）
|
||
7. **合并需你授权** — 只有你明确说"合并"，AI 才执行合并到最终库
|
||
8. **去重保证幂等** — 多次合并同一数据不会重复，最终库始终去重
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
pytest tests/ -v
|
||
```
|
||
|
||
当前测试覆盖：
|
||
|
||
- 80/80 测试通过（+6 review 交互测试）
|
||
- 清洗规则测试（含~处理、记号过滤）
|
||
- 格式校验测试
|
||
- 三层架构集成测试
|
||
- 配置加载测试（含 BOM 容错）
|
||
- review 交互测试（文件标注解析、裁决应用、字典写回）
|