kb-skills/.planning/phases/14-robustness-cost/14-05-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
14-robustness-cost	05	execute	2	14-01 14-02 14-03 14-04	kb_workflow/srt/semantic_engine.py kb_workflow/srt/processor.py	true	COST-03	truths artifacts key_links 用户可通过配置开关启用/禁用 LLM 分段 禁用时使用简单规则分段，不影响其他平台 SRTProcessor.enable_semantic_segmentation 参数控制开关 path provides exports kb_workflow/srt/processor.py SRTProcessor 配置开关 SRTProcessor.__init__ from to via pattern SRTProcessor.__init__() SemanticSegmentationEngine enable_semantic_segmentation 参数 if enable_semantic_segmentation

集成所有鲁棒性和成本控制功能到 SRTProcessor，提供配置开关控制 LLM 分段。

Purpose: 完成阶段 14 的集成，确保所有功能可通过配置开关控制。 Output: 集成缓存、分块、重试、降级的 SRTProcessor，支持配置开关。

<execution_context> @/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md @/home/starmen1265/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/phases/14-robustness-cost/14-CONTEXT.md @.planning/phases/14-robustness-cost/14-RESEARCH.md @.planning/phases/14-robustness-cost/14-VALIDATION.md @.planning/ROADMAP.md @.planning/REQUIREMENTS.md @.planning/STATE.md

@kb_workflow/srt/processor.py @kb_workflow/srt/semantic_engine.py @.planning/phases/14-robustness-cost/14-01-PLAN.md @.planning/phases/14-robustness-cost/14-02-PLAN.md @.planning/phases/14-robustness-cost/14-03-PLAN.md @.planning/phases/14-robustness-cost/14-04-PLAN.md

From kb_workflow/srt/processor.py (Phase 13 Plan 07):

class SRTProcessor(BaseProcessor):
    def __init__(
        self,
        config: Optional[dict] = None,
        enable_semantic_segmentation: bool = False,
        **kwargs
    ):
        """初始化 SRT 处理器

        Args:
            config: 配置字典
            enable_semantic_segmentation: 是否启用语义分段（默认 False）
        """
        super().__init__(config=config, **kwargs)

        # 初始化子模块
        self.parser = SRTParser()
        self.corrector = ASRCorrector()

        # 语义分段开关
        self.enable_semantic_segmentation = enable_semantic_segmentation
        if self.enable_semantic_segmentation:
            self.semantic_engine = SemanticSegmentationEngine()
        else:
            self.semantic_engine = None
            self.segmenter = SemanticSegmenter()

    def _segment_subtitles(self, segments: List, metadata: dict) -> List[str]:
        """分段字幕

        Args:
            segments: 字幕分段列表
            metadata: 视频元数据

        Returns:
            分段后的文本列表
        """
        if self.enable_semantic_segmentation and self.semantic_engine:
            # 使用 LLM 语义分段
            video_segments = self.semantic_engine.segment(segments, metadata)
            # 转换为纯文本列表（保留标题）
            paragraphs = []
            for seg in video_segments:
                if seg.title:
                    paragraphs.append(f"## {seg.title}\n\n{seg.content}")
                else:
                    paragraphs.append(seg.content)
            return paragraphs
        else:
            # 使用规则分段
            return self.segmenter.segment(segments)

关键观察:

• enable_semantic_segmentation 参数控制是否启用 LLM 分段
• True: 使用 SemanticSegmentationEngine
• False: 使用 SemanticSegmenter (规则分段)
• 输出格式: 带标题的分段使用 "## {title}\n\n{content}" 格式

From 14-CONTEXT.md (User Decisions):

# Claude's Discretion
- 具体的重试逻辑实现细节 (Plan 01)
- 缓存文件命名规则和目录结构 (Plan 03)
- 分块算法的具体实现 (Plan 04)
- 日志消息的具体措辞和格式 (Plan 01, 02)

本计划需要:

1. 集成 SemanticCache 到 UnifiedSegmentationStrategy
2. 确保配置开关 (enable_semantic_segmentation) 正常工作
3. 添加集成测试验证完整流程

Task 1: 集成缓存到 UnifiedSegmentationStrategy kb_workflow/srt/semantic_engine.py - UnifiedSegmentationStrategy 接受可选的 cache 参数 - 在 segment() 方法中，调用 LLM 前先检查缓存 - 缓存命中: 直接返回缓存结果 - 缓存未命中: 调用 LLM，然后保存结果到缓存 - 缓存键仅基于字幕内容，不包含元数据 修改 UnifiedSegmentationStrategy 类，集成缓存:

1. 修改 __init__() 方法，添加 cache 参数:
   ```python
   def __init__(
       self,
       ai_client: Optional[AIClientProtocol] = None,
       fallback_segmenter: Optional['SemanticSegmenter'] = None,
       cache: Optional['SemanticCache'] = None
   ):
       """初始化统一分段策略

       Args:
           ai_client: AI 客户端实例
           fallback_segmenter: 降级时使用的规则分段器
           cache: 缓存管理器，如果为 None 则不使用缓存
       """
       self.ai_client = ai_client
       self.fallback_segmenter = fallback_segmenter
       self.cache = cache

       # Lazy AI Client 初始化（保持不变）
       if self.ai_client is None:
           try:
               from kb_workflow.deep_analyzer import SimpleAIClient
               self.ai_client = SimpleAIClient()
               if not self.ai_client.api_key:
                   logger.info("AI API key not configured")
                   self.ai_client = None
           except Exception as e:
               logger.warning(f"Failed to initialize AI client: {e}")
               self.ai_client = None

       # 初始化降级分段器
       if self.fallback_segmenter is None:
           from kb_workflow.srt.segmenter import SemanticSegmenter
           self.fallback_segmenter = SemanticSegmenter()
   ```

2. 修改 segment() 方法，添加缓存逻辑:
   ```python
   def segment(self, segments: List, metadata: dict) -> List[VideoSegment]:
       # AI 不可用，直接使用规则分段
       if self.ai_client is None:
           logger.info("AI client unavailable, using fallback segmenter")
           paragraphs = self.fallback_segmenter.segment(segments)
           return [
               VideoSegment(title=None, content=para, start_index=0, end_index=0)
               for para in paragraphs
           ]

       # 合并字幕文本
       content = " ".join(seg.text for seg in segments)

       # 检查缓存
       if self.cache is not None:
           cached_result = self.cache.get(content)
           if cached_result is not None:
               logger.info("Using cached segmentation result")
               return cached_result.segments

       # 检查是否需要分块
       if len(content) <= 5000:
           # 短文本直接处理
           video_segments = self._segment_single_chunk(content, metadata, segments)
       else:
           # 长文本分块处理
           video_segments = self._segment_multiple_chunks(content, metadata, segments)

       # 保存到缓存
       if self.cache is not None:
           # 构建完整的 SegmentationResult
           result = SegmentationResult(
               video_type=self._infer_video_type(metadata),
               segments=video_segments,
               actual_segment_count=len(video_segments)
           )
           self.cache.set(content, result)
           logger.debug("Saved segmentation result to cache")

       return video_segments
   ```

3. 修改 SemanticSegmentationEngine.__init__()，传递 cache 参数:
   ```python
   def __init__(
       self,
       strategy: Optional[SegmentationStrategy] = None,
       fallback_segmenter: Optional['SemanticSegmenter'] = None,
       cache: Optional['SemanticCache'] = None
   ):
       """初始化语义分段引擎

       Args:
           strategy: 分段策略实例
           fallback_segmenter: 降级时使用的规则分段器（已弃用）
           cache: 缓存管理器
       """
       if strategy is None:
           self.strategy = UnifiedSegmentationStrategy(
               fallback_segmenter=fallback_segmenter,
               cache=cache
           )
       else:
           self.strategy = strategy
   ```

遵守用户决策:
- 缓存是可选的，通过构造函数传入
- 缓存键仅基于内容哈希
- 缓存命中时记录 info 日志

pytest tests/test_semantic_robustness.py::test_cache_hit -x - UnifiedSegmentationStrategy 支持可选缓存 - 缓存命中时直接返回，不调用 LLM - 缓存未命中时调用 LLM 并保存结果 - SemanticSegmentationEngine 支持传递 cache 参数 Task 2: 在 SRTProcessor 中集成缓存和验证配置开关 kb_workflow/srt/processor.py - SRTProcessor 接受可选的 enable_cache 参数 - 启用语义分段时创建 SemanticCache 实例 - 禁用语义分段时不创建缓存 - 配置开关正确控制 LLM 分段和规则分段 修改 SRTProcessor 类，集成缓存:

1. 修改 __init__() 方法，添加缓存支持:
   ```python
   def __init__(
       self,
       config: Optional[dict] = None,
       enable_semantic_segmentation: bool = False,
       enable_cache: bool = True,
       **kwargs
   ):
   """初始化 SRT 处理器

   Args:
       config: 配置字典
       enable_semantic_segmentation: 是否启用语义分段（默认 False）
       enable_cache: 是否启用缓存（默认 True，仅在启用语义分段时有效）
   """
   super().__init__(config=config, **kwargs)

   # 初始化子模块
   self.parser = SRTParser()
   self.corrector = ASRCorrector()

   # 语义分段开关
   self.enable_semantic_segmentation = enable_semantic_segmentation
   if self.enable_semantic_segmentation:
       # 初始化缓存
       cache = None
       if enable_cache:
           from kb_workflow.srt.cache import SemanticCache
           cache = SemanticCache()

       self.semantic_engine = SemanticSegmentationEngine(cache=cache)
       self.segmenter = None
   else:
       self.semantic_engine = None
       self.segmenter = SemanticSegmenter()

       logger.info("Using rule-based segmenter (semantic segmentation disabled)")
   ```

2. 验证 _segment_subtitles() 方法正确使用配置开关:
   - 检查 enable_semantic_segmentation 为 True 时使用 SemanticSegmentationEngine
   - 检查 enable_semantic_segmentation 为 False 时使用 SemanticSegmenter
   - 输出格式正确（带标题的分段使用 "## {title}\n\n{content}"）

遵守用户决策:
- 配置开关控制是否启用 LLM 分段
- 默认禁用语义分段（向后兼容）
- 缓存默认启用（当语义分段启用时）

pytest tests/test_srt_processor.py::test_semantic_segmentation_toggle -x - SRTProcessor 支持配置开关控制语义分段 - 启用时创建 SemanticCache 和 SemanticSegmentationEngine - 禁用时使用 SemanticSegmenter，不创建缓存 - 集成测试验证完整流程 ## 整体验证标准

1. 配置开关: enable_semantic_segmentation=True 启用 LLM 分段，False 使用规则分段
2. 缓存集成: 启用语义分段时缓存工作，禁用时不创建缓存
3. 向后兼容: 默认禁用语义分段，不影响现有功能
4. 完整流程: 从 SRT 处理到 Markdown 生成的完整流程正常工作

运行完整测试套件:

python3 -m pytest tests/test_srt_processor.py::test_semantic_segmentation_toggle -v -x

运行鲁棒性测试:

python3 -m pytest tests/test_semantic_robustness.py -v -x

<success_criteria>

1. enable_semantic_segmentation=True 时使用 LLM 分段
2. enable_semantic_segmentation=False 时使用规则分段
3. 缓存在启用语义分段时正常工作
4. 禁用语义分段时不创建缓存
5. 所有功能集成测试通过
6. 所有鲁棒性测试通过 </success_criteria>

执行完成后创建 `.planning/phases/14-robustness-cost/14-05-SUMMARY.md`