---
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. 所有测试通过