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）
7.8 KiB
7.8 KiB
配置文件集成完成总结
✅ 已完成的工作
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
🎯 配置文件功能
查找优先级
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
🚀 项目已就绪！