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）
351 lines
7.8 KiB
Markdown
351 lines
7.8 KiB
Markdown
# 配置文件集成完成总结
|
||
|
||
## ✅ 已完成的工作
|
||
|
||
### 1. 核心模块 ✅
|
||
|
||
- **`config.py`** (220 行)
|
||
- `JCleanConfig` 数据类
|
||
- `find_config_file()` — 查找配置文件（5 级优先级）
|
||
- `load_config()` — 加载并解析配置
|
||
- `generate_sample_config()` — 生成示例配置
|
||
- `resolve_path()` — 路径解析（绝对/相对）
|
||
|
||
### 2. CLI 更新 ✅
|
||
|
||
- **新增命令**：
|
||
- `jclean init-config` — 生成示例配置文件
|
||
- `jclean show-config` — 查看当前配置
|
||
- **全局参数**：
|
||
- `--config` — 指定配置文件路径
|
||
- `--tasks-root` — 覆盖配置文件中的 tasks_root
|
||
- **create 命令**：使用配置文件默认值（可被命令行参数覆盖）
|
||
|
||
### 3. 依赖管理 ✅
|
||
|
||
- 添加 `tomli>=2.0; python_version<'3.11'` 到 `pyproject.toml`
|
||
- Python 3.11+ 自带 `tomllib`，无需额外依赖
|
||
|
||
### 4. 测试覆盖 ✅
|
||
|
||
- **新增 13 个配置测试** (`test_config.py`)
|
||
- 默认配置
|
||
- 路径解析（绝对/相对/父目录）
|
||
- 配置文件查找
|
||
- 配置加载
|
||
- 示例生成
|
||
- **总计 73 个测试全部通过** ✅
|
||
|
||
### 5. 文档更新 ✅
|
||
|
||
- **README_cleaner.md**
|
||
- 配置文件章节（生成/示例/查找顺序/路径解析/优先级）
|
||
- 功能特性增加配置文件管理
|
||
- 版本历史更新到 v0.3.0
|
||
- **CONFIG_FILE_DESIGN.md** — 完整设计文档
|
||
|
||
### 6. 导出更新 ✅
|
||
|
||
- `__init__.py` 导出 `JCleanConfig` / `load_config` / `generate_sample_config`
|
||
|
||
---
|
||
|
||
## 🎯 配置文件功能
|
||
|
||
### **查找优先级**
|
||
|
||
```text
|
||
1. --config /path/to/custom.toml (命令行指定，最高优先级)
|
||
2. ./jclean.toml 或 ./.jclean.toml (当前目录)
|
||
3. ../jclean.toml, ../../... (向上查找，遇到 .git 停止)
|
||
4. ~/.jclean.toml (用户主目录)
|
||
5. 硬编码默认值 (兜底)
|
||
```text
|
||
|
||
### **路径解析规则**
|
||
|
||
- **绝对路径** → 直接使用
|
||
- **相对路径** → 相对配置文件所在目录
|
||
|
||
**示例**（配置文件在 `/home/user/project/jclean.toml`）：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks" # → /home/user/project/tasks
|
||
vocabulary = "/data/global/vocab.txt" # → /data/global/vocab.txt
|
||
sources_dir = "../shared/sources" # → /home/user/shared/sources
|
||
```text
|
||
|
||
### **配置优先级**
|
||
|
||
```text
|
||
命令行参数 > 配置文件 > 默认值
|
||
```text
|
||
|
||
**示例**：
|
||
|
||
```bash
|
||
# 配置文件中 count = 500
|
||
# 命令行参数覆盖
|
||
jclean create batch1 --source data.txt --count 300 # 使用 300
|
||
```text
|
||
|
||
---
|
||
|
||
## 📝 配置文件示例
|
||
|
||
```toml
|
||
# jclean.toml
|
||
|
||
[paths]
|
||
# 任务根目录
|
||
tasks_root = "tasks"
|
||
|
||
# 权威库（所有任务最终合并的目标）
|
||
vocabulary = "data/db/vocabulary.txt"
|
||
skipped = "data/db/skipped.txt"
|
||
|
||
# 数据源目录（可选）
|
||
sources_dir = "data/sources"
|
||
|
||
[defaults]
|
||
# 创建任务时的默认值
|
||
start_line = 1
|
||
count = 300
|
||
|
||
# 是否在合并前自动备份权威库
|
||
backup_before_merge = true
|
||
backup_dir = "data/backup"
|
||
|
||
[logging]
|
||
# 日志级别：DEBUG / INFO / WARNING / ERROR
|
||
level = "INFO"
|
||
|
||
# 日志输出位置（可选）
|
||
# log_file = "logs/jclean.log"
|
||
```text
|
||
|
||
---
|
||
|
||
## 🚀 使用示例
|
||
|
||
### **场景 1：单项目（最简单）**
|
||
|
||
```bash
|
||
# 在项目根目录生成配置
|
||
cd /path/to/project
|
||
jclean init-config
|
||
|
||
# 编辑 jclean.toml（可选）
|
||
|
||
# 使用默认配置创建任务
|
||
jclean create batch1 --source data/sources/xinbiaori_1.txt
|
||
jclean run batch1
|
||
```text
|
||
|
||
---
|
||
|
||
### **场景 2：多项目隔离**
|
||
|
||
**项目 A** (`/home/user/project_a/jclean.toml`)：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks"
|
||
vocabulary = "vocab/main.txt"
|
||
skipped = "vocab/skip.txt"
|
||
```text
|
||
|
||
**项目 B** (`/home/user/project_b/jclean.toml`)：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks"
|
||
vocabulary = "data/vocab.txt"
|
||
skipped = "data/skip.txt"
|
||
```text
|
||
|
||
**使用**：
|
||
|
||
```bash
|
||
cd /home/user/project_a
|
||
jclean create batch1 --source data/source.txt # 使用项目 A 配置
|
||
|
||
cd /home/user/project_b
|
||
jclean create batch1 --source data/source.txt # 使用项目 B 配置（独立）
|
||
```text
|
||
|
||
---
|
||
|
||
### **场景 3：共享权威库（多项目合并到同一库）**
|
||
|
||
**项目 A** (`/home/user/project_a/jclean.toml`)：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks" # 各自独立
|
||
vocabulary = "/shared/japanese/vocabulary.txt" # 共享（绝对路径）
|
||
skipped = "/shared/japanese/skipped.txt" # 共享
|
||
```text
|
||
|
||
**项目 B** (`/home/user/project_b/jclean.toml`)：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks" # 各自独立
|
||
vocabulary = "/shared/japanese/vocabulary.txt" # 共享（同一个库）
|
||
skipped = "/shared/japanese/skipped.txt" # 共享
|
||
```text
|
||
|
||
**结果**：
|
||
|
||
- 各项目任务独立（`tasks/` 目录独立）
|
||
- 最终成果合并到同一个权威库
|
||
|
||
---
|
||
|
||
### **场景 4：全局配置 + 项目覆盖**
|
||
|
||
**用户主目录** (`~/.jclean.toml`)：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "~/japanese_tasks"
|
||
vocabulary = "~/japanese_vocab.txt"
|
||
|
||
[defaults]
|
||
count = 300
|
||
```text
|
||
|
||
**项目目录** (`/work/project1/jclean.toml`)：
|
||
|
||
```toml
|
||
[paths]
|
||
vocabulary = "data/project_vocab.txt" # 覆盖全局
|
||
# tasks_root 继承全局配置
|
||
```text
|
||
|
||
---
|
||
|
||
## 📊 测试覆盖
|
||
|
||
```text
|
||
============================= 73 passed in 11.96s ==============================
|
||
|
||
tests/test_config.py 13 passed (配置管理)
|
||
tests/test_cleaner.py 8 passed (底层单元)
|
||
tests/test_cleaner_workflow.py 31 passed (三层集成)
|
||
tests/test_tango.py 6 passed (下游模型)
|
||
tests/test_validator.py 15 passed (格式校验)
|
||
```text
|
||
|
||
---
|
||
|
||
## 🎨 CLI 命令
|
||
|
||
### **配置相关**
|
||
|
||
```bash
|
||
jclean init-config [--output jclean.toml] # 生成示例配置
|
||
jclean show-config # 查看当前配置
|
||
```text
|
||
|
||
### **全局参数**
|
||
|
||
```bash
|
||
jclean --config /path/to/config.toml ... # 指定配置文件
|
||
jclean --tasks-root /custom/tasks ... # 覆盖 tasks_root
|
||
```text
|
||
|
||
### **工作流**
|
||
|
||
```bash
|
||
jclean create <task_id> --source <file> [options]
|
||
jclean list
|
||
jclean status <task_id>
|
||
jclean run <task_id> [--bucket <name>]
|
||
jclean clear <task_id>
|
||
```text
|
||
|
||
---
|
||
|
||
## 💡 关键设计决策
|
||
|
||
### **1. 路径相对配置文件所在目录**
|
||
|
||
**理由**：
|
||
|
||
- 配置文件可以放在项目根目录
|
||
- 所有相对路径相对项目根，符合直觉
|
||
- 移动项目不需要修改配置
|
||
|
||
**示例**：
|
||
|
||
```text
|
||
/home/user/project/
|
||
├── jclean.toml # 配置文件
|
||
├── tasks/ # tasks_root = "tasks" → 此目录
|
||
└── data/
|
||
└── db/
|
||
└── vocabulary.txt # vocabulary = "data/db/vocabulary.txt" → 此文件
|
||
```text
|
||
|
||
---
|
||
|
||
### **2. 命令行参数优先级最高**
|
||
|
||
**理由**：
|
||
|
||
- 配置文件是默认值，方便日常使用
|
||
- 命令行参数是临时覆盖，灵活调试
|
||
- 符合 Unix 传统（`--flag` > 配置文件 > 默认值）
|
||
|
||
---
|
||
|
||
### **3. 向上查找项目根（遇到 .git 停止）**
|
||
|
||
**理由**：
|
||
|
||
- 在子目录运行时自动找到项目根配置
|
||
- 遇到 `.git` 说明到达项目根，不再向上
|
||
- 用户体验好，无需每次 cd 到项目根
|
||
|
||
---
|
||
|
||
### **4. 配置文件可选**
|
||
|
||
**理由**：
|
||
|
||
- 没有配置文件时使用默认值，兼容旧版本
|
||
- 小项目/快速测试无需配置文件
|
||
- 大项目/团队协作推荐使用配置文件
|
||
|
||
---
|
||
|
||
## 🎉 完成总结
|
||
|
||
**配置文件集成已全部完成！**
|
||
|
||
**核心成果**：
|
||
|
||
- ✅ 完整的配置文件支持（加载/查找/解析/优先级）
|
||
- ✅ CLI 新增 `init-config` / `show-config` 命令
|
||
- ✅ 路径灵活（相对/绝对都支持）
|
||
- ✅ 多项目友好（独立配置/共享权威库都支持）
|
||
- ✅ 73 个测试全部通过
|
||
- ✅ 文档完整更新
|
||
|
||
**总耗时**：约 1.5 小时（如预期）
|
||
|
||
**可立即使用**：
|
||
|
||
```bash
|
||
cd /path/to/project
|
||
jclean init-config # 生成配置
|
||
jclean show-config # 查看配置
|
||
jclean create batch1 --source data/sources/xinbiaori_1.txt
|
||
jclean run batch1
|
||
```text
|
||
|
||
🚀 项目已就绪！
|