kb-skills/.planning/phases/14-robustness-cost/14-03-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	03	execute	1		kb_workflow/srt/cache/semantic_cache.py kb_workflow/srt/cache/__init__.py	true	COST-02	truths artifacts key_links 相同内容的字幕使用缓存结果，避免重复 LLM 调用 缓存键基于内容哈希（SHA256），精确匹配 缓存存储在本地文件系统 (.planning/cache/semantic/) path provides exports kb_workflow/srt/cache/semantic_cache.py SemanticCache 缓存管理器 SemanticCache compute_content_hash path provides exports kb_workflow/srt/cache/__init__.py 缓存模块导出 SemanticCache from to via pattern SemanticCache.get() .planning/cache/semantic/ 文件系统读取 Path.read_text from to via pattern SemanticCache.set() .planning/cache/semantic/ 文件系统写入 Path.write_text

实现基于内容哈希的智能缓存，避免重复 LLM 调用，降低成本和延迟。

Purpose: 相同内容的字幕直接使用缓存结果，减少 LLM API 调用次数。 Output: SemanticCache 缓存管理器，支持内容哈希、文件存储、TTL 永久有效。

<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/semantic_engine.py @kb_workflow/srt/corrector.py

From 14-CONTEXT.md (User Decisions):

# 缓存机制
- 缓存键: 字幕内容哈希（SHA256）— 精确匹配
- 缓存存储: 本地文件系统 — .planning/cache/semantic/
- 缓存 TTL: 永久有效 — 手动清理
- 缓存内容: 完整的 SegmentationResult（JSON 格式）

From kb_workflow/srt/semantic_engine.py:

class SegmentationResult(BaseModel):
    video_type: str
    segments: List[VideoSegment]
    actual_segment_count: int

class VideoSegment(BaseModel):
    title: Optional[str]
    content: str
    start_index: int
    end_index: int

关键观察:

• SegmentationResult 是 Pydantic 模型，可以序列化为 JSON
• 需要缓存完整的 SegmentationResult 对象
• 缓存键应该仅基于内容哈希，不包含元数据

Task 1: 创建 SemanticCache 缓存管理器 kb_workflow/srt/cache/semantic_cache.py, kb_workflow/srt/cache/__init__.py - compute_content_hash(): 计算内容的 SHA256 哈希 - get(): 从缓存读取 SegmentationResult - set(): 保存 SegmentationResult 到缓存 - 缓存目录不存在时自动创建 - 缓存文件命名: {hash}.json - 缓存内容包含 version 字段（未来兼容性） - 缓存命中/未命中记录 debug 日志 创建 kb_workflow/srt/cache/semantic_cache.py:

1. 导入依赖:
   ```python
   import hashlib
   import json
   import logging
   from pathlib import Path
   from typing import Optional

   from kb_workflow.srt.semantic_engine import SegmentationResult
   ```

2. 实现 compute_content_hash():
   ```python
   def compute_content_hash(content: str) -> str:
       """计算内容的 SHA256 哈希作为缓存键"""
       return hashlib.sha256(content.encode('utf-8')).hexdigest()
   ```

3. 实现 SemanticCache 类:
   ```python
   class SemanticCache:
       """语义分段结果缓存管理器

       使用内容哈希（SHA256）作为缓存键，存储在本地文件系统。
       """

       CACHE_VERSION = "1.0"
       DEFAULT_CACHE_DIR = Path(".planning/cache/semantic")

       def __init__(self, cache_dir: Optional[Path] = None):
           """初始化缓存管理器

           Args:
               cache_dir: 缓存目录路径，默认为 .planning/cache/semantic/
           """
           self.cache_dir = cache_dir or self.DEFAULT_CACHE_DIR
           self.logger = logging.getLogger(__name__)

       def get(self, content: str) -> Optional[SegmentationResult]:
           """从缓存读取分段结果

           Args:
               content: 字幕内容

           Returns:
               缓存的 SegmentationResult，如果不存在则返回 None
           """
           cache_key = compute_content_hash(content)
           cache_file = self.cache_dir / f"{cache_key}.json"

           if not cache_file.exists():
               self.logger.debug(f"Cache miss: {cache_key}")
               return None

           try:
               data = json.loads(cache_file.read_text(encoding='utf-8'))

               # 验证版本
               if data.get('version') != self.CACHE_VERSION:
                   self.logger.warning(
                       f"Cache version mismatch: {data.get('version')} != {self.CACHE_VERSION}"
                   )
                   return None

               # 移除 version 字段，转换为 SegmentationResult
               data.pop('version', None)
               result = SegmentationResult(**data)

               self.logger.debug(f"Cache hit: {cache_key}")
               return result

           except (json.JSONDecodeError, IOError, ValidationError) as e:
               self.logger.warning(f"Failed to load cache: {e}")
               return None

       def set(self, content: str, result: SegmentationResult) -> None:
           """保存分段结果到缓存

           Args:
               content: 字幕内容
               result: 分段结果
           """
           cache_key = compute_content_hash(content)
           cache_file = self.cache_dir / f"{cache_key}.json"

           try:
               # 确保目录存在
               self.cache_dir.mkdir(parents=True, exist_ok=True)

               # 序列化为 JSON，添加 version 字段
               data = result.model_dump()
               data['version'] = self.CACHE_VERSION

               cache_file.write_text(
                   json.dumps(data, ensure_ascii=False, indent=2),
                   encoding='utf-8'
               )

               self.logger.debug(f"Cache saved: {cache_key}")

           except IOError as e:
               self.logger.warning(f"Failed to save cache: {e}")
   ```

4. 创建 kb_workflow/srt/cache/__init__.py:
   ```python
   """语义分段缓存模块"""

   from kb_workflow.srt.cache.semantic_cache import (
       SemanticCache,
       compute_content_hash
   )

   __all__ = ['SemanticCache', 'compute_content_hash']
   ```

遵守用户决策:
- 缓存键: SHA256 内容哈希
- 缓存存储: 本地文件系统 (.planning/cache/semantic/)
- 缓存 TTL: 永久有效
- 缓存内容: 完整的 SegmentationResult

pytest tests/test_semantic_robustness.py::test_cache_hit -x - SemanticCache 类实现完整的缓存读写功能 - compute_content_hash() 使用 SHA256 计算内容哈希 - 缓存目录不存在时自动创建 - 缓存文件包含 version 字段，支持未来兼容性 - 缓存命中/未命中记录 debug 日志 - 缓存加载失败时返回 None，不中断流程 ## 整体验证标准

1. 缓存键计算: 相同内容产生相同的 SHA256 哈希
2. 缓存命中: 第二次调用时从缓存读取，不调用 LLM
3. 缓存未命中: 首次调用时保存结果到缓存
4. 版本控制: 缓存包含 version 字段，支持未来格式变更
5. 错误处理: 缓存读写失败时返回 None，不中断流程

运行完整测试套件:

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

<success_criteria>

1. 相同内容第二次调用时从缓存读取
2. 缓存文件存储在 .planning/cache/semantic/ 目录
3. 缓存文件命名格式: {sha256_hash}.json
4. 缓存内容包含完整的 SegmentationResult (JSON 格式)
5. 缓存命中时记录 debug 级别日志
6. 所有测试通过 </success_criteria>

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