--- phase: 14-robustness-cost plan: 03 type: execute wave: 1 depends_on: [] files_modified: - kb_workflow/srt/cache/semantic_cache.py - kb_workflow/srt/cache/__init__.py autonomous: true requirements: - COST-02 must_haves: truths: - "相同内容的字幕使用缓存结果,避免重复 LLM 调用" - "缓存键基于内容哈希(SHA256),精确匹配" - "缓存存储在本地文件系统 (.planning/cache/semantic/)" artifacts: - path: "kb_workflow/srt/cache/semantic_cache.py" provides: "SemanticCache 缓存管理器" exports: ["SemanticCache", "compute_content_hash"] - path: "kb_workflow/srt/cache/__init__.py" provides: "缓存模块导出" exports: ["SemanticCache"] key_links: - from: "SemanticCache.get()" to: ".planning/cache/semantic/" via: "文件系统读取" pattern: "Path.read_text" - from: "SemanticCache.set()" to: ".planning/cache/semantic/" via: "文件系统写入" pattern: "Path.write_text" --- 实现基于内容哈希的智能缓存,避免重复 LLM 调用,降低成本和延迟。 Purpose: 相同内容的字幕直接使用缓存结果,减少 LLM API 调用次数。 Output: SemanticCache 缓存管理器,支持内容哈希、文件存储、TTL 永久有效。 @/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md @/home/starmen1265/.claude/get-shit-done/templates/summary.md @.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): ```python # 缓存机制 - 缓存键: 字幕内容哈希(SHA256)— 精确匹配 - 缓存存储: 本地文件系统 — .planning/cache/semantic/ - 缓存 TTL: 永久有效 — 手动清理 - 缓存内容: 完整的 SegmentationResult(JSON 格式) ``` From kb_workflow/srt/semantic_engine.py: ```python 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,不中断流程 运行完整测试套件: ```bash python3 -m pytest tests/test_semantic_robustness.py::test_cache_hit -v -x ``` 1. 相同内容第二次调用时从缓存读取 2. 缓存文件存储在 .planning/cache/semantic/ 目录 3. 缓存文件命名格式: {sha256_hash}.json 4. 缓存内容包含完整的 SegmentationResult (JSON 格式) 5. 缓存命中时记录 debug 级别日志 6. 所有测试通过 执行完成后创建 `.planning/phases/14-robustness-cost/14-03-SUMMARY.md`