# Review 确认指南

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

## 两种交互方式

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

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

```bash
jclean review <task_id> --bucket pinyin
```

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

```text
[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]` 区（整词覆盖,优先级最高）,未来批次自动生效。

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

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

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

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

#### 标注约定

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

#### 示例

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

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

**编辑后**（你的标注）:

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

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

#### 应用标注

编辑完毕后执行:

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

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

```text
--------------------------------------------------
确认: 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

```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]` 区:

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

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

### 手工编辑

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

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

```bash
jclean run task1 --bucket pinyin
```

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

## 工作流完整示例

```bash
# 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**: 用文件标注方式,批量删除 `# ...请确认` 注释:

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

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

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

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

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

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

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

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

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

### Q: 能否混用两种方式?

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

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

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

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

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

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

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

---

**下一步**: 所有 review 清零后,继续工作流 → [WORKFLOW.md](design/WORKFLOW.md)