# 配置文件简化总结

按用户要求移除不必要的配置项，简化配置文件和任务创建逻辑。

## 变更内容

### 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

**是否需要进一步简化，由用户决定。**