# 日语词表处理规则（铁律）

本文件记录 xinbiaori_tobe.txt → xinbiaori.txt 的所有处理约定，流水线和人工都遵循。

## 数据格式

每行三段，用 `:` 分隔，段内用 `|` 对齐：

```text
汉字|分段:假名|分段:拼音|分段
```

示例：`中|国|人:ちゅう|ごく|じん:zhong|guo|ren`

- 汉字段：每个汉字单独一段；连续假名（送り仮名/前后缀）合并为一段
- 假名段：与汉字段一一对应
- 拼音段：汉字对应拼音，假名段留空

## 处理规则

### 1. 词中没有汉字的 → 跳过不处理

汉字段不含任何汉字（纯英文、纯符号、纯片假名外来语等），直接跳过，放入单批忽略文件 `skip.txt`。

- 例：`IT:アイティー:`、`WTO:...`、`Japan Railways:...`、`％:パーセント:`
- 判断标准：汉字段用正则 `[\u4e00-\u9fff]` 匹配不到任何字符

### 2. 含字母+汉字的混合词 → 正常处理

字母作为独立段，拼音填小写字母本身。

- 例：`阿|Q|正|伝:あ|キュー|せい|でん:a|q|zheng|zhuan`
- 例：`ＪＣ|自|動|車:ジェーシー|じ|どう|しゃ:jc|zi|dong|che`

### 3. `~` 标记 → 作为任意长通配符对齐，~ 对应部分不输出

`~`（全角 ～ 或半角 ~）表示"省略的、无对应汉字的假名部分"。处理时把 `~` 当作
任意长通配符，与汉字 token 一起对齐，`~` 吸收到的假名段和纯标点段都从输出中删除，
只保留汉字段和与汉字紧邻的送り仮名。

- する 动词：`発明～:はつめいします:` → `発|明:はつ|めい:fa|ming`（~ 吸收「します」）
- 名词省略前半：`～賞:ノーベルしょう:` → `賞:しょう:shang`（~ 吸收「ノーベル」）
- 名词省略后半：`飲料～:いんりょうメーカー:` → `飲|料:いん|りょう:yin|liao`
- 送り仮名保留：`干し～:ほしブドウ:` → `干|し:ほ|し:gan|`（し 保留，~ 吸收「ブドウ」）
- 对齐成功 → auto（无多音字）或 review_pinyin（含多音字）
- 对齐失败/多解无法定夺 → review_split，人工确认

### 4. ます形动词 → 转辞書形（原型）

- 五段：ます前 i段音 → u段音（かり→かる、き→く、し→す）
- 一段：ます → る（げます→げる）
- 用 jamdict 词典验证动词身份
- **词典唯一解** → 直接处理
- **词典歧义**（如 にます→にる/ぬ）→ 放入 review_verb，人工查证
- 例：`預かります:あずかります:` → `預|かる:あず|かる:yu|`

### 5. 完整表达/惯用句 → 保留原样（不砍词尾）

带 お/に/ください 等构成完整寒暄的整句，保留 します/でした。

- 例：`お先に失礼します` → `お|先|に|失|礼|します:お|さき|に|しつ|れい|します:|xian||shi|li|`

### 6. 々（同字重复符号）→ 展开为前一个字

- 例：`我々:われわれ:` → `我|我:われ|われ:wo|wo`
- 例：`佐々木:ささき:` → `佐|佐|木:さ|さ|き:zuo|zuo|mu`

### 7. 熟字训/特殊读音 → 词典无法分割的放 review_split 人工处理

- 例：田舎(いなか)、明日(あす)、お父さん(おとうさん)

## 拼音规则

- 多音字：只标记高频多音字黑名单（行/长/重/传等），其他直接用最常见读音
- 日本新字体：按对应的中文字标拼音（楽→le、伝→chuan、価→jia）

## 条数校验（铁律）

**输入条数 = 各输出文件条数之和**。条数不对，结果一定不对，必须排查。
去掉纯英文等跳过项后，剩余条数也要能对上。

## 工作流（任务化架构）

每次清洗是一个**任务**（Task），有独立配置、独立临时文件、状态机。
详见 `WORKFLOW.md`。核心流程：

1. **创建任务**：指定数据源 + 处理范围，任务独立目录 `tasks/{id}/`
   `jclean create <id> --source data.txt --start 1 --count 300`
2. **处理一批**：数据源只读，分流到单批文件（auto_done/skip/review_*）
   `jclean process <id>`
3. **逐个 review**：你指出问题 → AI 只记录 → 单文件说完后 AI 汇总
4. **改代码重跑**：AI 改字典/规则（不手改输出文件），重跑单个 review 桶
   `jclean reprocess <id> --bucket pinyin`
5. **核对总数**：review 全清零后，auto_done + skip == 原始输入有效条数
6. **你说合并**：AI 才合并（auto_done→vocabulary、skip→skipped，去重）
   `jclean merge <id>`

> 命令行等价写法：`jclean` = `python -m pl_japanese.cleaner.cli` = `python scripts/clean.py`。
> 流程需人工介入，推荐用 `tests/test_cleaner_workflow.py` 测试驱动协作。

### 两层文件结构

- **单批（临时，任务独立）**：auto_done / skip / review_{pinyin,split,verb,special}
- **最终权威（累积，只增去重）**：xinbiaori.txt / skipped_total.txt

### 铁律

- 数据源只读，绝不修改原文件
- review 是中间态，确认完必须清零
- 改代码而非手改输出文件
- 合并需人工授权，最终库只增不删
- 所有路径都是任务配置项，可覆盖

## 编码注意

- 所有文件用 UTF-8 无 BOM，换行 \n
- 写文件时禁止引入 BOM（EF BB BF）
- 控制台是 GBK，脚本输出避免使用非 ASCII 符号（如 ✅⚠️）