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）
289 lines
6.4 KiB
Markdown
289 lines
6.4 KiB
Markdown
# 配置文件管理方案设计
|
||
|
||
## 📋 概述
|
||
|
||
用配置文件管理 `tasks/` 和 `data/db/` 等路径，支持相对路径和绝对路径。
|
||
|
||
---
|
||
|
||
## 📁 配置文件格式
|
||
|
||
**文件名**：`jclean.toml` 或 `.jclean.toml`
|
||
|
||
**示例配置**：
|
||
|
||
```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（相对路径）
|
||
- 或者每次都传绝对路径
|
||
|
||
你希望我继续实现配置文件功能吗？还是当前的命令行参数方式已经足够？
|