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 确认（两种交互方式）

任务处理完毕后进入 reviewing 状态,review 桶里的条目需要你确认。有两种交互方式:

方式1:交互式逐条确认（推荐少量条目）

jclean review batch1 --bucket pinyin

进入逐条确认界面:

[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
行首加 # (整行注释)	删除此条	丢弃

编辑完毕后执行:

jclean review batch1 --bucket pinyin --apply

jclean 读取你的标注,一次性处理所有裁决。

示例:

# 编辑前（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,继续推进:

jclean run batch1  # 合并到权威库

拼音字典（数据外置）

多音字拼音字典从 Python 源码中外置为数据文件:

• 位置: 与 jclean.toml 同目录的 pinyin_dict.toml（默认）
• 格式: TOML,两种覆盖方式:
  • [word_override] — 整词汉字 → 完整拼音（最高优先级）
  • [kana_hint] — "汉字|假名前缀" → 该字拼音（假名辅助消歧）
• 自动写入: jclean review 修正拼音时自动追加,未来批次自动生效
• 手工编辑: 可直接编辑该文件,重跑 review 立即生效

示例 (pinyin_dict.toml):

[word_override]
"会計" = "kuai|ji"    # 会计读 kuài
"銀行" = "yin|hang"   # 银行读 háng

[kana_hint]
"長|なが" = "chang"   # 长度义 cháng
"長|ちょう" = "zhang" # 首长义 zhǎng

配置路径（在 jclean.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 桶

jclean run 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. 字典是数据不是代码 — 拼音字典外置为 pinyin_dict.toml（项目级配置），review 修正自动写入
6. 两种 review 交互 — 交互式逐条确认（少量）或文件标注批量处理（大量）
7. 合并需你授权 — 只有你明确说"合并"，AI 才执行合并到最终库
8. 去重保证幂等 — 多次合并同一数据不会重复，最终库始终去重

---

测试

pytest tests/ -v

当前测试覆盖：

• 80/80 测试通过（+6 review 交互测试）
• 清洗规则测试（含~处理、记号过滤）
• 格式校验测试
• 三层架构集成测试
• 配置加载测试（含 BOM 容错）
• review 交互测试（文件标注解析、裁决应用、字典写回）