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-03-PLAN.md
T

223 lines
8.3 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: 03
type: execute
wave: 1
depends_on: [15-01, 15-02]
files_modified:
- tests/test_backward_compat.py
- tests/test_processors/test_analyze.py
autonomous: true
requirements:
- CONFIG-02
- CONFIG-03
must_haves:
truths:
- "规则分段行为与 Phase 12 完全一致,未受配置变更影响"
- "AnalyzeProcessor(知乎/文章)继续正常工作,不受 SRTProcessor 配置影响"
- "现有 API 调用保持兼容,不传参数时使用配置默认值"
- "禁用 LLM 分段时性能与 Phase 12 一致(无额外开销)"
artifacts:
- path: "tests/test_backward_compat.py"
provides: "向后兼容性测试"
contains: "TestBackwardCompatibility"
- path: "tests/test_processors/test_analyze.py"
provides: "AnalyzeProcessor 独立性验证"
contains: "现有测试"
key_links:
- from: "AnalyzeProcessor"
to: "SRTProcessor"
via: "独立的处理器类,无依赖"
pattern: "class AnalyzeProcessor"
- from: "规则分段器(SemanticSegmenter)"
to: "SRTProcessor"
via: "enable_semantic_segmentation=False"
pattern: "SemanticSegmenter\\(\\)"
---
<objective>
验证向后兼容性,确保配置变更不影响现有功能,特别是规则分段和 AnalyzeProcessor。
Purpose: 确保用户升级后无需修改代码,现有功能继续正常工作
Output: 向后兼容性测试通过,无破坏性变更
</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/12-srt-processor/12-01-SUMMARY.md
@.planning/phases/15-output-compat/15-01-SUMMARY.md
@.planning/phases/15-output-compat/15-02-SUMMARY.md
@kb_workflow/pipeline/processors/srt.py
@kb_workflow/pipeline/processors/analyze.py
@kb_workflow/srt/segmenter.py
</context>
<interfaces>
<!-- AnalyzeProcessor 独立性 -->
From kb_workflow/pipeline/processors/analyze.py (expected structure):
```python
class AnalyzeProcessor(BaseProcessor):
"""知乎/文章处理器,独立于 SRTProcessor"""
# AnalyzeProcessor 不依赖 SRTProcessor 的配置或分段逻辑
# 它有自己的分析流程和输出格式
```
<!-- 规则分段器(SemanticSegmenter) -->
From kb_workflow/srt/segmenter.py (expected structure):
```python
class SemanticSegmenter:
"""规则分段器,基于时间间隔和字符长度"""
def segment(self, segments: List[Segment]) -> List[str]:
# 简单规则:时间间隔 > 3秒 或 字符数 > 500 创建新分段
# 返回纯文本列表,不包含标题
```
<!-- 现有 API 调用模式 -->
```python
# Phase 12 的调用方式(应继续工作)
processor = SRTProcessor(state_manager)
# 或
processor = SRTProcessor(state_manager, enable_correction=False)
# 现在会从 KBSettings 读取 enable_semantic_segmentation(默认 True)
```
</interfaces>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 验证规则分段向后兼容性</name>
<files>tests/test_backward_compat.py</files>
<behavior>
- Test 1: enable_semantic_segmentation=False 时使用规则分段器
- Test 2: 规则分段输出格式与 Phase 12 一致("## 内容"标题)
- Test 3: 规则分段不调用 LLM,无网络开销
- Test 4: 规则分段的分段逻辑(时间/长度阈值)未改变
</behavior>
<action>
实现规则分段兼容性测试(移除 skip 标记):
1. test_rule_based_segmentation_unchanged:
- 创建 SRTProcessor(enable_semantic_segmentation=False)
- 验证 self.segmenter 是 SemanticSegmenter 实例
- 验证不是 SemanticSegmentationEngine 实例
- 调用 segment() 方法验证返回纯文本列表
- 验证输出 Markdown 包含 "## 内容" 标题
2. test_rule_based_no_llm_calls:
- Mock SimpleAIClient,验证 generate() 方法未被调用
- 确保规则分段不依赖 LLM
3. test_rule_based_thresholds_unchanged:
- 使用已知字幕数据测试分段边界
- 验证分段逻辑与 Phase 12 一致(时间间隔 3秒,字符数 500)
测试数据使用 Phase 12 的测试模式。
</action>
<verify>
<automated>pytest tests/test_backward_compat.py::TestBackwardCompatibility::test_rule_based_segmentation_unchanged tests/test_backward_compat.py::TestBackwardCompatibility::test_rule_based_no_llm_calls tests/test_backward_compat.py::TestBackwardCompatibility::test_rule_based_thresholds_unchanged -x -v</automated>
</verify>
<done>
- 规则分段测试通过
- 行为与 Phase 12 一致
- CONFIG-02 需求满足
</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: 验证 AnalyzeProcessor 独立性</name>
<files>tests/test_processors/test_analyze.py, tests/test_backward_compat.py</files>
<behavior>
- Test 1: AnalyzeProcessor 不受 KBSettings.enable_semantic_segmentation 影响
- Test 2: AnalyzeProcessor 正常初始化和处理
- Test 3: AnalyzeProcessor 输出格式未改变
</behavior>
<action>
实现 AnalyzeProcessor 独立性测试:
1. 在 test_backward_compat.py 中添加 test_analyze_processor_unaffected:
- 设置 KB_ENABLE_SEMANTIC_SEGMENTATION=true 或 false
- 创建 AnalyzeProcessor
- 验证处理器正常工作
- 验证 AnalyzeProcessor 不读取 enable_semantic_segmentation 配置
2. 验证 tests/test_processors/test_analyze.py 中现有测试全部通过:
- 确保 AnalyzeProcessor 的测试未被配置变更破坏
- AnalyzeProcessor 有独立的测试套件
AnalyzeProcessor 处理知乎/文章内容,与视频字幕处理完全独立。
</action>
<verify>
<automated>pytest tests/test_backward_compat.py::TestBackwardCompatibility::test_analyze_processor_unaffected tests/test_processors/test_analyze.py -x -v</automated>
</verify>
<done>
- AnalyzeProcessor 测试通过
- CONFIG-03 需求满足
- 现有测试未受影响
</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: 验证 API 调用兼容性</name>
<files>tests/test_backward_compat.py</files>
<behavior>
- Test 1: 不传 enable_semantic_segmentation 参数时使用配置默认值
- Test 2: 旧代码调用 SRTProcessor(state_manager) 继续工作
- Test 3: 显式传 False 时覆盖配置,使用规则分段
</behavior>
<action>
实现 API 兼容性测试:
1. test_existing_api_compatibility:
- 模拟 Phase 12 的调用方式:SRTProcessor(state_manager)
- 验证从 KBSettings 读取配置(默认 True)
- Mock get_settings() 返回 enable_semantic_segmentation=True
2. test_explicit_false_overrides_config:
- 设置配置 KB_ENABLE_SEMANTIC_SEGMENTATION=true
- 调用 SRTProcessor(state_manager, enable_semantic_segmentation=False)
- 验证使用规则分段器(参数优先)
3. test_migration_path:
- 验证用户可以通过两种方式启用语义分段:
a) 不传参数,配置文件设置 KB_ENABLE_SEMANTIC_SEGMENTATION=true
b) 代码中显式传入 enable_semantic_segmentation=True
确保升级路径平滑,用户无需立即修改代码。
</action>
<verify>
<automated>pytest tests/test_backward_compat.py::TestBackwardCompatibility::test_existing_api_compatibility tests/test_backward_compat.py::TestBackwardCompatibility::test_explicit_false_overrides_config tests/test_backward_compat.py::TestBackwardCompatibility::test_migration_path -x -v</automated>
</verify>
<done>
- API 兼容性测试通过
- 升级路径清晰
- 无破坏性变更
</done>
</task>
</tasks>
<verification>
- 规则分段行为与 Phase 12 一致(CONFIG-02 满足)
- AnalyzeProcessor 不受影响(CONFIG-03 满足)
- 现有 API 调用保持兼容
- 配置默认值为 True,提供开箱即用的语义分段体验
- 用户可选择禁用(配置或参数)
- 所有现有测试通过
</verification>
<success_criteria>
- CONFIG-02 需求满足:向后兼容,不破坏现有规则分段
- CONFIG-03 需求满足:AnalyzeProcessor 不受影响
- 无破坏性变更,用户可平滑升级
- 测试覆盖所有兼容性场景
</success_criteria>
<output>
After completion, create `.planning/phases/15-output-compat/15-03-SUMMARY.md`
</output>