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）
297 lines
7.3 KiB
Markdown
297 lines
7.3 KiB
Markdown
# 配置文件简化总结
|
||
|
||
按用户要求移除不必要的配置项，简化配置文件和任务创建逻辑。
|
||
|
||
## 变更内容
|
||
|
||
### 1. 移除的配置项
|
||
|
||
**从 `JCleanConfig` 和配置文件移除**：
|
||
|
||
- `sources_dir` — 数据源路径应在创建任务时显式指定（`--source` 必需参数）
|
||
- `default_start_line` — 不指定时默认 1（硬编码）
|
||
- `default_count` — 不指定时默认 `None`（处理整个文件）
|
||
|
||
**理由**：
|
||
|
||
- 数据源必须每次任务显式指定，不应有全局默认路径
|
||
- 起始行 99% 的情况是 1，不需要配置
|
||
- count 默认"全部处理"比硬编码 300 更合理
|
||
|
||
---
|
||
|
||
### 2. 核心逻辑变更
|
||
|
||
#### **count 的语义**
|
||
|
||
- **之前**：`count: int = 300`（必须指定条数）
|
||
- **现在**：`count: Optional[int] = None`（`None` = 处理到文件末尾）
|
||
|
||
#### **处理范围解析**
|
||
|
||
```python
|
||
# TaskConfig
|
||
count: Optional[int] = None # None 表示从 start_line 处理到文件末尾
|
||
|
||
# _read_source_lines
|
||
if count is not None and len(lines) >= count:
|
||
break # count=None 时不限行数，读到文件末尾
|
||
```text
|
||
|
||
#### **CLI create 命令**
|
||
|
||
```bash
|
||
# 不指定 --count，处理整个文件
|
||
jclean create task1 --source data.txt
|
||
|
||
# 指定 --count，处理指定条数
|
||
jclean create task2 --source data.txt --count 100
|
||
|
||
# 指定 --start，从指定行开始
|
||
jclean create task3 --source data.txt --start 500
|
||
```text
|
||
|
||
#### **输出信息**
|
||
|
||
```text
|
||
范围: L1 起到文件末尾（全部） # count=None
|
||
范围: L1 起 300 条 # count=300
|
||
范围: L500 起到文件末尾（全部） # start=500, count=None
|
||
```text
|
||
|
||
---
|
||
|
||
### 3. 配置文件对比
|
||
|
||
#### **之前（冗余）**
|
||
|
||
```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]
|
||
level = "INFO"
|
||
```text
|
||
|
||
#### **现在（精简）**
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks"
|
||
vocabulary = "data/db/vocabulary.txt"
|
||
skipped = "data/db/skipped.txt"
|
||
|
||
[defaults]
|
||
backup_before_merge = true
|
||
backup_dir = "data/backup"
|
||
|
||
[logging]
|
||
level = "INFO"
|
||
```text
|
||
|
||
---
|
||
|
||
### 4. 文件变更清单
|
||
|
||
#### **核心代码**
|
||
|
||
- `src/pl_japanese/cleaner/config.py`
|
||
- 移除 `sources_dir`、`default_start_line`、`default_count`
|
||
- `load_config` 不再解析这些字段
|
||
- `generate_sample_config` 模板已精简
|
||
- `src/pl_japanese/cleaner/task.py`
|
||
- `TaskConfig.count: Optional[int] = None`
|
||
- `Task.create()` 参数 `count: Optional[int] = None`
|
||
- 文档更新：`count=None` 表示处理到文件末尾
|
||
- `src/pl_japanese/cleaner/task_processor.py`
|
||
- `_read_source_lines(count: Optional[int])` — 支持 `count=None`
|
||
- 循环逻辑：`if count is not None and len(lines) >= count: break`
|
||
- `src/pl_japanese/cleaner/task_manager.py`
|
||
- `create_task()` 参数 `count: Optional[int] = None`
|
||
- `src/pl_japanese/cleaner/cli.py`
|
||
- `--start` help: "起始行号（默认 1）"
|
||
- `--count` help: "处理条数（默认处理到文件末尾）"
|
||
- `_cmd_create`: `start_line = args.start if args.start else 1`
|
||
- `_cmd_create`: `count = args.count` (None = 全部)
|
||
- `_cmd_show_config`: 移除 `sources_dir`、`start_line`、`count` 显示
|
||
|
||
#### **配置文件**
|
||
|
||
- `jclean.toml` — 已更新为精简版本
|
||
|
||
#### **测试**
|
||
|
||
- `tests/test_config.py` — 移除 `default_start_line`、`default_count` 断言
|
||
- 所有测试通过（74 个）
|
||
|
||
---
|
||
|
||
### 5. 端到端验证
|
||
|
||
#### **测试用例**
|
||
|
||
```bash
|
||
# 创建 5 行测试文件
|
||
日本:にほん:
|
||
中国:ちゅうごく:
|
||
美国:べいこく:
|
||
英国:えいこく:
|
||
法国:ふらんす:
|
||
|
||
# 测试 1：不指定 count（应处理全部 5 行）
|
||
jclean create test1 --source source.txt
|
||
jclean run test1
|
||
# 结果：3 行 auto_done + 2 行 review_split = 5 行全部处理 ✅
|
||
|
||
# 测试 2：指定 count=3（应处理前 3 行）
|
||
jclean create test2 --source source.txt --count 3
|
||
jclean run test2
|
||
# 结果：2 行 auto_done + 1 行 review_split = 3 行 ✅
|
||
|
||
# 测试 3：创建时的输出信息
|
||
jclean create test3 --source source.txt
|
||
# 输出："范围: L1 起到文件末尾（全部）" ✅
|
||
```text
|
||
|
||
#### **JSON 序列化**
|
||
|
||
```json
|
||
// count=None 时的 task.json
|
||
{
|
||
"config": {
|
||
"source": "source.txt",
|
||
"start_line": 1,
|
||
"count": null // null ↔ None 往返正确 ✅
|
||
}
|
||
}
|
||
|
||
// count=3 时的 task.json
|
||
{
|
||
"config": {
|
||
"count": 3
|
||
}
|
||
}
|
||
```text
|
||
|
||
---
|
||
|
||
### 6. 兼容性
|
||
|
||
#### **旧任务**
|
||
|
||
- 旧 `task.json` 中 `count: 300` → 加载后仍为 300，行为不变 ✅
|
||
- 旧任务可正常运行，无需迁移
|
||
|
||
#### **旧配置文件**
|
||
|
||
- 如果旧 `jclean.toml` 包含 `sources_dir`/`start_line`/`count`：
|
||
- 加载时**静默忽略**（不报错）
|
||
- 但不再使用这些值
|
||
- 建议用户重新生成：`jclean init-config`
|
||
|
||
---
|
||
|
||
### 7. 设计原则确认
|
||
|
||
用户原话：
|
||
> "数据源目录是不必要的，我认为创建任务时必须提供数据源"
|
||
> "起始行和count也是没必要的，如果创建任务时没指定起始行就是1，如果没有指定count就是整个文件所有行都处理"
|
||
|
||
✅ **完全符合要求**：
|
||
|
||
- `--source` 必需参数，无全局默认
|
||
- `--start` 默认 1（硬编码，不可配置）
|
||
- `--count` 默认 None（全部处理，不限行数）
|
||
|
||
---
|
||
|
||
### 8. 测试结果
|
||
|
||
```text
|
||
============================= 74 passed in 12.23s ==============================
|
||
|
||
tests/test_config.py 14 passed (配置管理，已移除 count/start_line 相关)
|
||
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
|
||
|
||
---
|
||
|
||
## 影响总结
|
||
|
||
### **用户体验改进**
|
||
|
||
1. **配置文件更简洁** — 只保留真正需要配置的路径和备份选项
|
||
2. **默认行为更合理** — `count=None` 处理全部，比硬编码 300 更直观
|
||
3. **必需参数更明确** — `--source` 必需，避免路径混乱
|
||
|
||
### **代码质量改进**
|
||
|
||
1. **职责更清晰** — 配置文件不管任务级别的参数（start/count）
|
||
2. **类型更准确** — `count: Optional[int]` 明确表达"可以不限"
|
||
3. **文档更简单** — 减少需要解释的配置项
|
||
|
||
### **兼容性保证**
|
||
|
||
1. **旧任务正常运行** — `count=300` 的旧任务行为不变
|
||
2. **旧配置不报错** — 多余字段静默忽略
|
||
3. **迁移成本低** — 建议重新生成配置，但不强制
|
||
|
||
---
|
||
|
||
## 完成文件
|
||
|
||
- `config.py` ✅
|
||
- `task.py` ✅
|
||
- `task_processor.py` ✅
|
||
- `task_manager.py` ✅
|
||
- `cli.py` ✅
|
||
- `jclean.toml` ✅
|
||
- `tests/test_config.py` ✅
|
||
- 74 个测试全部通过 ✅
|
||
|
||
---
|
||
|
||
## 后续建议
|
||
|
||
用户可以考虑进一步简化：
|
||
|
||
- `backup_before_merge` 是否默认 `true` 就够了（不需要配置）？
|
||
- `backup_dir` 是否默认 `data/backup` 就够了？
|
||
|
||
如果这两个也不需要配置，`[defaults]` 整个段都可以删掉，配置文件只剩：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks"
|
||
vocabulary = "data/db/vocabulary.txt"
|
||
skipped = "data/db/skipped.txt"
|
||
|
||
[logging]
|
||
level = "INFO"
|
||
```text
|
||
|
||
甚至 `[logging]` 也可以考虑移除（命令行 `--verbose`/`--quiet` 覆盖）。
|
||
|
||
最终极简版配置文件：
|
||
|
||
```toml
|
||
[paths]
|
||
tasks_root = "tasks"
|
||
vocabulary = "data/db/vocabulary.txt"
|
||
skipped = "data/db/skipped.txt"
|
||
```text
|
||
|
||
**是否需要进一步简化，由用户决定。**
|