This repository has been archived on 2026-08-07. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
kb-skills/.planning/phases/15-output-compat/15-02-PLAN.md
T

244 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
phase: 15-output-compat
plan: 02
type: execute
wave: 1
depends_on: [15-01]
files_modified:
- kb_workflow/pipeline/processors/srt.py
- tests/test_processors/test_srt.py
autonomous: true
requirements:
- CONFIG-01
- CONFIG-02
- OUTPUT-01
- OUTPUT-02
- OUTPUT-03
must_haves:
truths:
- "SRTProcessor 从 KBSettings 读取 enable_semantic_segmentation 配置"
- "构造函数参数可覆盖配置值(优先级:参数 > 配置)"
- "配置禁用时使用规则分段器(SemanticSegmenter)"
- "配置启用时使用 LLM 语义分段器(SemanticSegmentationEngine)"
- "输出格式与配置匹配:LLM 分段输出 H2 标题,规则分段输出 '## 内容'"
artifacts:
- path: "kb_workflow/pipeline/processors/srt.py"
provides: "SRTProcessor 配置集成"
exports: ["SRTProcessor.__init__()", "SRTProcessor.process()"]
- path: "tests/test_processors/test_srt.py"
provides: "配置集成测试"
contains: "TestConfigIntegration"
key_links:
- from: "SRTProcessor.__init__()"
to: "get_settings()"
via: "from kb_workflow.pipeline.config import get_settings"
pattern: "get_settings\\(\\)"
- from: "SRTProcessor.__init__()"
to: "KBSettings.enable_semantic_segmentation"
via: "settings.enable_semantic_segmentation"
pattern: "settings\\.enable_semantic_segmentation"
- from: "SRTProcessor.process()"
to: "SemanticSegmenter or SemanticSegmentationEngine"
via: "self.segmenter.segment()"
pattern: "self\\.segmenter\\.segment\\(\\)"
---
<objective>
修改 SRTProcessor 以从 KBSettings 读取 enable_semantic_segmentation 配置,实现配置驱动的分段策略选择,并验证输出格式兼容性。
Purpose: 用户通过配置文件控制 LLM 分段,无需修改调用代码
Output: SRTProcessor 集成 KBSettings,配置优先级正确,输出格式符合预期
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/phases/15-output-compat/15-CONTEXT.md
@.planning/phases/15-output-compat/15-RESEARCH.md
@.planning/phases/14-robustness-cost/14-05-SUMMARY.md
@.planning/phases/15-output-compat/15-01-SUMMARY.md
@kb_workflow/pipeline/processors/srt.py
@kb_workflow/srt/semantic_engine.py
</context>
<interfaces>
<!-- SRTProcessor 现有构造函数 -->
From kb_workflow/pipeline/processors/srt.py (lines 48-66):
```python
def __init__(
self,
state_manager: Optional[WorkflowStateManager] = None,
enable_correction: bool = True,
enable_semantic_segmentation: bool = False, # 当前硬编码默认值 False
enable_cache: bool = True
):
super().__init__(state_manager)
self.enable_correction = enable_correction
self.enable_semantic_segmentation = enable_semantic_segmentation
# ... 初始化分段器
```
<!-- Pattern: 从 KBSettings 读取配置 -->
```python
# 如果未明确指定,从配置读取
if enable_semantic_segmentation is None:
settings = get_settings()
enable_semantic_segmentation = settings.enable_semantic_segmentation
```
<!-- _generate_markdown 现有逻辑(lines 302-324) -->
From kb_workflow/pipeline/processors/srt.py:
```python
# 检查是否是 VideoSegment 类型(LLM 分段结果)
is_semantic_segmentation = (
paragraphs and
hasattr(paragraphs[0], 'title') and
hasattr(paragraphs[0], 'content')
)
if is_semantic_segmentation:
# LLM 语义分段:包含标题和内容
for seg in paragraphs:
if seg.title:
content_parts.append(f"## {seg.title}")
content_parts.append("")
content_parts.append(seg.content)
content_parts.append("")
else:
# 规则分段:纯文本
content_parts.append("## 内容")
content_parts.append("")
for para in paragraphs:
content_parts.append(para)
content_parts.append("")
```
</interfaces>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 修改 SRTProcessor 从 KBSettings 读取配置</name>
<files>kb_workflow/pipeline/processors/srt.py, tests/test_processors/test_srt.py</files>
<behavior>
- Test 1: enable_semantic_segmentation=None 时从 KBSettings 读取配置
- Test 2: 显式传入参数时覆盖配置值(参数优先级高于配置)
- Test 3: 配置为 True 且无参数时使用 LLM 分段
- Test 4: 配置为 False 且无参数时使用规则分段
- Test 5: 初始化日志记录配置状态(INFO 级别)
</behavior>
<action>
1. 修改 SRTProcessor.__init__() 签名,将 enable_semantic_segmentation 默认值改为 None:
```python
def __init__(
self,
state_manager: Optional[WorkflowStateManager] = None,
enable_correction: bool = True,
enable_semantic_segmentation: Optional[bool] = None, # 改为 None
enable_cache: bool = True
):
```
2. 在初始化代码中添加配置读取逻辑(在 super().__init__() 之后):
```python
# 如果未明确指定,从配置读取
if enable_semantic_segmentation is None:
settings = get_settings()
enable_semantic_segmentation = settings.enable_semantic_segmentation
logger.info(
f"SRTProcessor using config: "
f"semantic_segmentation={'enabled' if enable_semantic_segmentation else 'disabled'}"
)
elif enable_semantic_segmentation:
logger.info("SRTProcessor using explicit parameter: semantic_segmentation=enabled")
else:
logger.info("SRTProcessor using explicit parameter: semantic_segmentation=disabled")
self.enable_correction = enable_correction
self.enable_semantic_segmentation = enable_semantic_segmentation
```
3. 实现测试(移除 skip 标记):
- test_srt_processor_reads_from_kbsettings
- test_srt_processor_constructor_overrides_config
- test_config_disabled_uses_rule_based
- test_config_enabled_uses_llm_segmentation
测试需要 mock get_settings() 和环境变量。
</action>
<verify>
<automated>pytest tests/test_processors/test_srt.py::TestConfigIntegration -x -v</automated>
</verify>
<done>
- SRTProcessor 从 KBSettings 读取配置
- 构造函数参数可覆盖配置
- 日志记录配置状态
- 4 个测试全部通过
</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: 验证输出格式兼容性</name>
<files>tests/test_processors/test_srt.py</files>
<behavior>
- Test 1: LLM 分段输出带 H2 标题的 Markdown(OUTPUT-01)
- Test 2: title=None 时不输出标题(OUTPUT-02)
- Test 3: 规则分段输出 "## 内容" 标题(OUTPUT-03)
- Test 4: 两种模式输出结构不同但都有效
</behavior>
<action>
实现 _generate_markdown 输出格式验证测试(移除 skip 标记):
1. test_output_format_with_semantic_enabled:
- Mock SemanticSegmentationEngine 返回 VideoSegment 对象
- 验证生成 Markdown 包含 "## {title}" 格式
- 验证有 title 的分段输出标题
2. test_output_format_with_semantic_disabled:
- 使用规则分段器(SemanticSegmenter)
- 验证生成 Markdown 包含 "## 内容" 标题
- 验证段落直接输出,无分段标题
3. test_output_format_with_null_title:
- Mock 返回 title=None 的 VideoSegment
- 验证不输出标题,直接输出内容
这些是集成测试,需要创建完整的 SRTProcessor 并调用 _generate_markdown。
</action>
<verify>
<automated>pytest tests/test_processors/test_srt.py::TestConfigIntegration::test_output_format_with_semantic_enabled tests/test_processors/test_srt.py::TestConfigIntegration::test_output_format_with_semantic_disabled tests/test_processors/test_srt.py::TestConfigIntegration::test_output_format_with_null_title -x -v</automated>
</verify>
<done>
- 输出格式测试通过
- LLM 分段输出 H2 标题(OUTPUT-01 满足)
- title=None 时不输出标题(OUTPUT-02 满足)
- 规则分段输出 "## 内容"(OUTPUT-03 满足)
</done>
</task>
</tasks>
<verification>
- SRTProcessor 正确读取 KBSettings 配置
- 构造函数参数优先级正确(参数 > 配置)
- 配置禁用时使用规则分段器(CONFIG-02 满足)
- 输出格式符合预期(OUTPUT-01, OUTPUT-02, OUTPUT-03 满足)
- 日志记录配置状态便于调试
- 不影响现有测试
</verification>
<success_criteria>
- CONFIG-01 需求满足:SRTProcessor 从 KBSettings 读取配置
- CONFIG-02 需求满足:禁用时使用规则分段
- OUTPUT-01, OUTPUT-02, OUTPUT-03 需求满足:输出格式正确
- 向后兼容:现有代码不传参数时使用配置默认值(True)
</success_criteria>
<output>
After completion, create `.planning/phases/15-output-compat/15-02-SUMMARY.md`
</output>