ef3df73166
清洗管线重构为严格三层架构：
- tango_analyser.py（底层：单词分析）
- task_processor.py（中层：文件 I/O、桶管理）
- workflow.py（顶层：状态机、任务推进）
- 移除旧的 batch_processor.py
新增配置文件系统：
- config.py：TOML 配置，相对路径相对配置文件目录解析
- 查找优先级 --config > cwd > 项目根 > ~ > 默认值
- count=None 语义为处理到文件末尾
项目目录整理：
- 根脚本归档到 scripts/analysis 与 scripts/legacy
- 文档归档到 docs/{design,history,analysis}
- 临时报告移到 reports/（已 gitignore）
文档质量：
- 新增 .markdownlint.json 与 scripts/mdlint.cmd
- 修复全部 14 个 md 文件的 markdownlint 警告
测试：74 passed（8 cleaner + 31 workflow + 6 tango + 15 validator + 14 config）
204 lines
6.1 KiB
Markdown
204 lines
6.1 KiB
Markdown
# 清洗工作流完整协作规范（任务化架构）
|
||
|
||
## 核心抽象：任务（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 测试通过
|
||
- 清洗规则测试（含~处理、记号过滤）
|
||
- 格式校验测试
|