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

## 核心抽象：任务（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 文件检查

你打开任务目录下的 `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 桶

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

---

## 测试

```bash
pytest tests/ -v
```

当前测试覆盖：

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