japanese/docs/REVIEW_GUIDE.md

Review 确认指南

清洗任务处理完毕后,含多音字、分割失败、动词形式等需人工确认的条目会进入 review 桶（review_pinyin / review_split / review_verb / review_special）。你需要确认这些条目后才能继续合并到最终库。

两种交互方式

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

适合 review 桶条目较少（几十条以内）时使用。

jclean review <task_id> --bucket pinyin

进入交互界面,逐条显示待确认条目:

[12/236] 議|会 : ぎ|かい : yi|hui   # 多音字(会),请确认
  Enter=确认 / 输入新拼音=修正 / s=跳过 / q=存盘退出
>

操作:

• Enter — 当前拼音正确,确认通过 → 移入 auto_done
• 输入新拼音 — 如 yi|kuai → 用新拼音移入 auto_done,自动写入拼音字典
• s — 暂时跳过 → 留在 review 桶（下次 review 继续显示）
• q — 存盘退出 → 已确认的生效,未确认的保留

修正拼音格式:

• 与汉字段对应,用 | 分隔
• 非汉字段（假名/字母）留空
• 例: 議|会 → yi|hui, 積|み|重|ねる → ji||chong|

修正后自动写入 pinyin_dict.toml 的 [word_override] 区（整词覆盖,优先级最高）,未来批次自动生效。

禁止写入字典（仅本次生效）:

jclean review <task_id> --bucket pinyin --no-dict

方式2:文件标注批量处理（大量条目）

适合 review 桶条目较多（上百条）时使用。直接编辑 review 文件,通过行尾注释表达意图。

标注约定

你的编辑	含义	jclean 识别
保留 # ...请确认	待确认,暂不处理	跳过,留在桶里
删掉 # ... 注释	当前拼音无误	确认,移入 auto_done
改第3段拼音 + 删注释	修正拼音	用新拼音移入 auto_done
行首加 #（整行注释）	删除此条	丢弃不处理

示例

编辑前（jclean 生成的 review_pinyin.txt）:

L11  あっという|間:あっという|ま:|jian    # 多音字(間),请确认
L80  議|会:ぎ|かい:yi|hui    # 多音字(会),请确认
L90  責|任:せき|にん:ze|ren    # 多音字(責),请确认
L100 銀|行:ぎん|こう:yin|xing    # 多音字(行),请确认

编辑后（你的标注）:

L11  あっという|間:あっという|ま:|jian
L80  議|会:ぎ|かい:yi|hui    # 多音字(会),请确认
L90  責|任:せき|にん:ze|ren2
# L100 銀|行:ぎん|こう:yin|xing    # 多音字(行),请确认

• L11 — 删掉注释 → 确认,拼音 jian 无误
• L80 — 保留注释 → 跳过,仍需确认
• L90 — 改拼音 ze|ren → ze|ren2 + 删注释 → 修正
• L100 — 行首加 # → 删除

应用标注

编辑完毕后执行:

jclean review <task_id> --bucket pinyin --apply

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

--------------------------------------------------
确认: 1  修正: 1  跳过: 1  删除: 1
剩余 review 总数: 1
任务状态: reviewing

还有 1 条,继续: jclean review <task_id> --bucket <name>

结果:

• L11 → auto_done (拼音 jian)
• L80 → 留在 review_pinyin
• L90 → auto_done (拼音 ze|ren2)
• L100 → 丢弃

注意: 文件标注方式不自动写入字典,需要手工编辑 pinyin_dict.toml 或下次遇到同词时通过交互式修正。

拼音字典

位置和格式

• 文件: 与 jclean.toml 同目录的 pinyin_dict.toml
• 格式: TOML

[word_override]
"会計" = "kuai|ji"    # 整词覆盖,优先级最高
"銀行" = "yin|hang"   # 银行读 háng

[kana_hint]
"長|なが" = "chang"   # 假名提示:なが → cháng
"長|ちょう" = "zhang" # 假名提示:ちょう → zhǎng

两种覆盖方式

1. [word_override] — 整词汉字 → 完整拼音

   • 精确匹配整个汉字段（如 会計）
   • 优先级最高,命中后跳过多音字标记
   • 拼音用 | 分段,与汉字逐字对应

2. [kana_hint] — "汉字|假名前缀" → 该字拼音

   • 用假名读音辅助消歧（如 長 有 なが/ちょう 两种读音）
   • 整词未命中时,逐字尝试假名提示
   • 键格式: "汉字|假名前缀"（如 "長|なが"）

自动写入

交互式确认修正拼音时,自动写入 [word_override] 区:

jclean review task1 --bucket pinyin
# 输入新拼音 → 自动追加到 pinyin_dict.toml

未来批次遇到同词自动生效,无需重复确认。

手工编辑

你也可以直接编辑 pinyin_dict.toml:

1. 打开文件,在对应区块添加条目
2. 保存后,重跑 review 桶立即生效:

jclean run task1 --bucket pinyin

文件会规整化（写回时重新生成,保留固定说明头,条目按字典序排列）。

工作流完整示例

# 1. 创建任务
jclean create batch1 --source data/sources/xinbiaori_1.txt --start 1 --count 500

# 2. 处理源文件
jclean run batch1
# 输出: 进入 reviewing 状态,236 条进入 review_pinyin,93 条进入 review_split...

# 3a. 交互式确认 pinyin 桶
jclean review batch1 --bucket pinyin
# 逐条确认/修正/跳过...

# 3b. 或文件标注批量处理
# 编辑 tasks/batch1/review_pinyin.txt（删注释/改拼音/标记删除）
jclean review batch1 --bucket pinyin --apply

# 4. 确认其他桶（split/verb/special）
jclean review batch1 --bucket split --apply

# 5. 所有 review 清零后,合并到最终库
jclean run batch1
# 输出: 任务状态 ready,合并到 vocabulary.txt / skipped.txt,状态变为 merged

常见问题

Q: review 桶里的拼音大部分都对,只是被多音字黑名单拦下来的,如何快速放行?

A: 用文件标注方式,批量删除 # ...请确认 注释:

# 用编辑器正则替换（VSCode 等）
查找:    \s+#\s+多音字.*,请确认
替换为:  (空)

# 应用标注
jclean review batch1 --bucket pinyin --apply

确认无误的全部进 auto_done,有疑问的行保留注释即可。

Q: 修正后想立即验证,怎么重跑单个 review 桶?

A: 修改字典/规则后,用 --bucket 参数重跑:

# 修改 pinyin_dict.toml 后
jclean run batch1 --bucket pinyin

该桶内容会重新用更新后的字典/规则处理,重新分流。

Q: 文件标注方式会自动写入字典吗?

A: 不会。只有交互式确认修正拼音时才自动写入。文件标注适合批量"当前批次一次性处理",不改字典。如果想让修正在未来批次也生效,需要手工编辑 pinyin_dict.toml。

Q: 能否混用两种方式?

A: 可以。先用文件标注批量处理明显正确的,再用交互式逐条处理需要修正的。

Q: 删除（行首 #）的条目去哪了?

A: 直接丢弃,不进 auto_done 也不进 skip,最终库里不会出现。

Q: 拼音校验不通过怎么办?

A: --apply 执行时会校验修正后的行格式,不通过的会退回 review 桶并打印失败原因:

[!] 1 条校验未通过,已退回 review 桶:
    分段长度不匹配(汉字2/假名2/拼音1): 破|損:は|そん:broken

检查拼音段数是否与汉字段对应,修正后重新 --apply。

---

下一步: 所有 review 清零后,继续工作流 → WORKFLOW.md