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）
6.4 KiB
6.4 KiB
配置文件管理方案设计
📋 概述
用配置文件管理 tasks/ 和 data/db/ 等路径，支持相对路径和绝对路径。
📁 配置文件格式
文件名：jclean.toml 或 .jclean.toml
示例配置：
# Japanese Cleaner 配置文件
# 路径可以是相对路径（相对本配置文件所在目录）或绝对路径
[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
---
## 🔍 配置文件查找优先级
```text
1. 命令行参数 --config /path/to/config.toml（最高优先级）
2. 当前工作目录
./jclean.toml
./.jclean.toml
3. 向上查找项目根
../jclean.toml
../../jclean.toml
...（遇到 .git 目录停止）
4. 用户主目录
~/.jclean.toml
5. 硬编码默认值（兜底）
tasks_root = "tasks"
vocabulary = "data/db/vocabulary.txt"
skipped = "data/db/skipped.txt"
```text
---
## 🎯 路径解析规则
配置文件中的路径解析：
```python
# 规则：
# 1. 绝对路径 → 直接使用
# 2. 相对路径 → 相对配置文件所在目录
# 示例：配置文件在 /home/user/project/jclean.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
---
## 🛠️ CLI 更新
### **新增命令**
```bash
# 生成示例配置文件
jclean init-config [--output jclean.toml]
# 查看当前配置（调试用）
jclean show-config
```text
### **更新全局参数**
```bash
# 使用自定义配置文件
jclean --config /path/to/custom.toml create batch1 --source ...
# 配置文件中的值可被命令行参数覆盖（命令行优先级最高）
jclean --tasks-root /custom/tasks create batch1 --source ...
```text
---
## 📊 优先级总结
**从高到低**：
```text
1. 命令行参数（--tasks-root / --main / --skipped）
2. 命令行指定的配置文件（--config）
3. 自动查找的配置文件（当前目录 → 项目根 → 用户主目录）
4. 硬编码默认值
```text
---
## 🎨 使用场景
### **场景 1：单项目（最简单）**
在项目根目录创建 `jclean.toml`：
```toml
[paths]
tasks_root = "tasks"
vocabulary = "data/db/vocabulary.txt"
skipped = "data/db/skipped.txt"
```text
使用：
```bash
cd /path/to/project
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：全局配置 + 项目覆盖**
**用户主目录**：`~/.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_specific_vocab.txt" # 覆盖全局
# tasks_root 继承全局配置
```text
---
### **场景 4：共享权威库（多项目合并到同一个库）**
**项目 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
---
## 🚀 实现清单
### **已完成**
- ✅ `config.py` 模块：加载配置、查找配置文件、解析路径
### **待实现**（需要你确认是否继续）
1. **更新 CLI**（约 30 分钟）
- 添加 `--config` 全局参数
- 添加 `init-config` 命令生成示例配置
- 添加 `show-config` 命令查看当前配置
- 更新 `create` 命令使用配置文件中的默认值
2. **更新 TaskManager**（约 15 分钟）
- 构造函数接受 `config: JCleanConfig`
- 使用 `config.resolve_path()` 解析所有路径
3. **更新文档**（约 15 分钟）
- README_cleaner.md 添加配置文件说明
- 生成配置文件示例文档
4. **添加测试**（约 30 分钟）
- 测试配置文件查找逻辑
- 测试路径解析（相对/绝对）
- 测试优先级覆盖
5. **添加 tomli 依赖**（约 5 分钟）
- 更新 `pyproject.toml` 添加 `tomli` 依赖（Python 3.10 需要）
---
## 💡 设计优点
1. **灵活性**：相对路径/绝对路径都支持
2. **可扩展**：配置文件易于添加新配置项
3. **向后兼容**：没有配置文件时使用硬编码默认值
4. **多项目友好**：每个项目独立配置，或共享全局配置
5. **调试友好**：`show-config` 命令查看当前生效配置
---
## ❓ 需要你决定
**要继续实现吗？**
如果要，我会：
1. 更新 CLI 添加配置文件支持
2. 更新 TaskManager 使用配置
3. 添加测试
4. 更新文档
**如果不要**，当前设计也能工作：
- 继续使用命令行参数（`--tasks-root` / `--main` / `--skipped`）
- 在项目根目录运行 jclean（相对路径）
- 或者每次都传绝对路径
你希望我继续实现配置文件功能吗？还是当前的命令行参数方式已经足够？