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

## 核心抽象：任务（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 交互测试（文件标注解析、裁决应用、字典写回）