japanese/docs/design/WORKFLOW.md

清洗工作流完整协作规范（任务化架构）

核心抽象：任务（Task）

整个清洗流程无法全自动完成（中间必须人工 review 干预），所以每次处理是一个 跨会话、有生命周期状态的任务。所有文件路径都是任务的配置项，不是全局静态配置。

一个任务 = 独立配置 + 独立临时文件 + 状态机，多任务可并存。

任务目录结构

每个任务在 tasks/{task_id}/ 下有独立目录：

tasks/
└── {task_id}/
    ├── task.json          # 任务配置 + 状态
    ├── auto_done.txt       # 该任务的单批结果
    ├── skip.txt
    ├── review_pinyin.txt
    ├── review_split.txt
    ├── review_verb.txt
    └── review_special.txt

任务状态机

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 — 所有批次累积的跳过项

权威库路径也是任务配置项（默认指向全局那份，任务可覆盖）。

项目数据目录布局

data/
├── db/                          # 权威成品库（只增不删+去重）
│   ├── vocabulary.txt           # 成品词表
│   └── skipped.txt              # 累积跳过项
├── sources/                     # 原始数据源（只读）
│   └── xinbiaori_1.txt
└── backup/                      # 历史备份
    ├── xinbiaori.backup.txt
    └── xinbiaori_tobe.backup.txt

---

入口方式

清洗流程需要人工介入（review 循环），推荐用测试驱动协作 （tests/test_cleaner_workflow.py）。命令行是便捷入口，三种等价写法：

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

CLI 命令

# 创建任务（数据源只读，可指定处理范围）
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 执行：

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 文件检查

你打开任务目录下的 review_pinyin.txt / review_split.txt 等，逐条指出问题。

重要约定：

• 你只指出问题，AI 只记录（不立即修改代码）
• 单个文件你说完所有问题后，AI 才汇总处理

第3步：AI 汇总修正并重跑单个 review 桶

3.1 AI 汇总你指出的问题

• 多音字错误 → 更新 pinyin_overrides.py 字典
• 分割规则错误 → 修改 classifier.py / aligner.py 逻辑
• 新发现的特殊情况 → 补充规则

3.2 AI 重新处理该 review 桶

jclean reprocess batch1 --bucket pinyin

执行后：review_pinyin.txt 清零，重新分类的条目进入 auto_done / skip / 其他 review_*。

3.3 重复 3.1~3.2，直到该 review 桶清零

第4步：所有 review 清零后，核对总数

所有 review_* 清零后，AI 核对：

auto_done 条数 + skip 条数 == 本批原始输入有效行数

校验通过后，任务状态为 ready，AI 告诉你"本批单批处理完成，待合并"。

第5步：你说"合并"，AI 执行合并

你明确说"合并"后，AI 执行：

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. 改代码而非改文件 — 你指出问题，AI 改字典/规则后重跑，不是你手改输出文件
6. 合并需你授权 — 只有你明确说"合并"，AI 才执行合并到最终库
7. 去重保证幂等 — 多次合并同一数据不会重复，最终库始终去重

---

测试

pytest tests/ -v

当前测试覆盖：

• 29/29 测试通过
• 清洗规则测试（含~处理、记号过滤）
• 格式校验测试