docs(15-01): complete enable_semantic_segmentation config integration plan
This commit is contained in:
@@ -0,0 +1,164 @@
|
||||
---
|
||||
phase: 15-output-compat
|
||||
plan: 01
|
||||
subsystem: configuration
|
||||
tags: [config, llm-segmentation, pydantic-settings, tdd]
|
||||
dependency_graph:
|
||||
requires: []
|
||||
provides: [enable_semantic_segmentation-config]
|
||||
affects: [srt-processor-integration]
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns: [pydantic-settings, tdd, boolean-env-parsing]
|
||||
key_files:
|
||||
created: []
|
||||
modified: [kb_workflow/pipeline/config.py, tests/test_pipeline/test_config.py]
|
||||
decisions: []
|
||||
metrics:
|
||||
duration: 54s
|
||||
completed_date: 2026-03-23T15:01:37Z
|
||||
---
|
||||
|
||||
# Phase 15 Plan 01: enable_semantic_segmentation 配置集成 Summary
|
||||
|
||||
为 KBSettings 添加 `enable_semantic_segmentation` 字段，允许用户通过环境变量或 `~/.kb_env` 文件控制 LLM 语义分段功能。
|
||||
|
||||
## One-Liner
|
||||
|
||||
Pydantic settings 集成 - 添加 `enable_semantic_segmentation` 布尔配置字段（默认 True），支持环境变量 `KB_ENABLE_SEMANTIC_SEGMENTATION` 覆盖。
|
||||
|
||||
## Completed Tasks
|
||||
|
||||
| Task | Name | Commit | Files |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| 1 | 添加 enable_semantic_segmentation 字段到 KBSettings | f2a1847, 8303cea | kb_workflow/pipeline/config.py, tests/test_pipeline/test_config.py |
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### KBSettings 字段添加
|
||||
|
||||
在 `kb_workflow/pipeline/config.py` 的 `KBSettings` 类中添加新字段：
|
||||
|
||||
```python
|
||||
# 工作流行为配置
|
||||
enable_semantic_segmentation: bool = Field(
|
||||
default=True,
|
||||
description="启用 LLM 语义分段（默认启用）"
|
||||
)
|
||||
```
|
||||
|
||||
**字段位置：** 在 `overwrite_archives` 字段之后，保持配置分类清晰。
|
||||
|
||||
### 测试实现 (TDD)
|
||||
|
||||
**RED 阶段：**
|
||||
- 提交 `f2a1847`: 添加 4 个失败测试
|
||||
- `test_kbsettings_has_enable_semantic_segmentation_field`: 验证字段存在性和类型
|
||||
- `test_enable_semantic_segmentation_default_value`: 验证默认值为 True
|
||||
- `test_enable_semantic_segmentation_from_env`: 验证环境变量覆盖
|
||||
- `test_enable_semantic_segmentation_boolean_parsing`: 验证多种布尔字符串解析
|
||||
|
||||
**GREEN 阶段：**
|
||||
- 提交 `8303cea`: 实现字段定义，所有测试通过
|
||||
- 运行验证：`pytest tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField -x -v`
|
||||
- 结果：4 个测试全部通过
|
||||
|
||||
### 环境变量解析
|
||||
|
||||
Pydantic-settings 自动支持以下布尔字符串表示（通过 `bool` 类型自动解析）：
|
||||
|
||||
**True 值：**
|
||||
- `"true"`, `"True"`, `"TRUE"`
|
||||
- `"yes"`, `"y"`
|
||||
- `"1"`
|
||||
|
||||
**False 值：**
|
||||
- `"false"`, `"False"`, `"FALSE"`
|
||||
- `"no"`, `"n"`
|
||||
- `"0"`
|
||||
|
||||
### 配置方式
|
||||
|
||||
用户可通过以下方式控制语义分段功能：
|
||||
|
||||
1. **环境变量：**
|
||||
```bash
|
||||
export KB_ENABLE_SEMANTIC_SEGMENTATION=true
|
||||
```
|
||||
|
||||
2. **~/.kb_env 文件：**
|
||||
```
|
||||
KB_ENABLE_SEMANTIC_SEGMENTATION=false
|
||||
```
|
||||
|
||||
3. **代码覆盖（用于测试）：**
|
||||
```python
|
||||
settings = KBSettings(
|
||||
base_path="/tmp/kb",
|
||||
archive_path="/tmp/archive",
|
||||
enable_semantic_segmentation=False
|
||||
)
|
||||
```
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Auth Gates
|
||||
|
||||
None.
|
||||
|
||||
## Requirements Satisfied
|
||||
|
||||
- **CONFIG-01**: LLM 分段功能可通过配置启用/禁用 ✅
|
||||
- `enable_semantic_segmentation` 字段存在，类型为 `bool`
|
||||
- 默认值为 `True`（启用语义分段）
|
||||
- 支持环境变量 `KB_ENABLE_SEMANTIC_SEGMENTATION` 覆盖
|
||||
- Pydantic 自动解析布尔字符串（true/false, yes/no, 1/0）
|
||||
|
||||
## Verification Results
|
||||
|
||||
### Automated Tests
|
||||
|
||||
```
|
||||
pytest tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField -x -v
|
||||
|
||||
tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField::test_kbsettings_has_enable_semantic_segmentation_field PASSED [ 25%]
|
||||
tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField::test_enable_semantic_segmentation_default_value PASSED [ 50%]
|
||||
tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField::test_enable_semantic_segmentation_from_env PASSED [ 75%]
|
||||
tests/test_pipeline/test_config.py::TestEnableSemanticSegmentationField::test_enable_semantic_segmentation_boolean_parsing PASSED [100%]
|
||||
|
||||
4 passed in 0.29s
|
||||
```
|
||||
|
||||
### Full Test Suite
|
||||
|
||||
```
|
||||
pytest tests/test_pipeline/test_config.py -v
|
||||
|
||||
18 passed in 0.32s
|
||||
```
|
||||
|
||||
所有现有测试继续通过，无破坏性变更。
|
||||
|
||||
## Next Steps
|
||||
|
||||
计划 15-02 将集成此配置到 SRTProcessor，使 `enable_semantic_segmentation` 从 `KBSettings` 读取而非硬编码默认值。
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- [x] 所有修改的文件存在
|
||||
- [x] 所有提交已创建（f2a1847, 8303cea）
|
||||
- [x] 所有测试通过（18/18）
|
||||
- [x] 配置字段类型和默认值正确
|
||||
- [x] 环境变量解析符合预期
|
||||
- [x] 无破坏性变更
|
||||
|
||||
---
|
||||
|
||||
*Phase: 15-output-compat, Plan: 01*
|
||||
*Completed: 2026-03-23T15:01:37Z*
|
||||
*Duration: 54s*
|
||||
*TDD Methodology: RED → GREEN → (no refactor needed)*
|
||||
Reference in New Issue
Block a user