165 lines
4.6 KiB
Markdown
165 lines
4.6 KiB
Markdown
---
|
||
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)*
|