docs(14): create phase 14 plans (5 plans + wave 0 tests)
This commit is contained in:
@@ -0,0 +1,272 @@
|
||||
---
|
||||
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"
|
||||
---
|
||||
|
||||
<objective>
|
||||
实现基于内容哈希的智能缓存,避免重复 LLM 调用,降低成本和延迟。
|
||||
|
||||
Purpose: 相同内容的字幕直接使用缓存结果,减少 LLM API 调用次数。
|
||||
Output: SemanticCache 缓存管理器,支持内容哈希、文件存储、TTL 永久有效。
|
||||
</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/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
|
||||
</context>
|
||||
|
||||
<interfaces>
|
||||
<!-- Key contracts needed for cache implementation -->
|
||||
|
||||
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 对象
|
||||
- 缓存键应该仅基于内容哈希,不包含元数据
|
||||
</interfaces>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: 创建 SemanticCache 缓存管理器</name>
|
||||
<files>kb_workflow/srt/cache/semantic_cache.py, kb_workflow/srt/cache/__init__.py</files>
|
||||
<behavior>
|
||||
- compute_content_hash(): 计算内容的 SHA256 哈希
|
||||
- get(): 从缓存读取 SegmentationResult
|
||||
- set(): 保存 SegmentationResult 到缓存
|
||||
- 缓存目录不存在时自动创建
|
||||
- 缓存文件命名: {hash}.json
|
||||
- 缓存内容包含 version 字段(未来兼容性)
|
||||
- 缓存命中/未命中记录 debug 日志
|
||||
</behavior>
|
||||
<action>
|
||||
创建 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
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pytest tests/test_semantic_robustness.py::test_cache_hit -x</automated>
|
||||
</verify>
|
||||
<done>
|
||||
- SemanticCache 类实现完整的缓存读写功能
|
||||
- compute_content_hash() 使用 SHA256 计算内容哈希
|
||||
- 缓存目录不存在时自动创建
|
||||
- 缓存文件包含 version 字段,支持未来兼容性
|
||||
- 缓存命中/未命中记录 debug 日志
|
||||
- 缓存加载失败时返回 None,不中断流程
|
||||
</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
## 整体验证标准
|
||||
|
||||
1. **缓存键计算**: 相同内容产生相同的 SHA256 哈希
|
||||
2. **缓存命中**: 第二次调用时从缓存读取,不调用 LLM
|
||||
3. **缓存未命中**: 首次调用时保存结果到缓存
|
||||
4. **版本控制**: 缓存包含 version 字段,支持未来格式变更
|
||||
5. **错误处理**: 缓存读写失败时返回 None,不中断流程
|
||||
|
||||
运行完整测试套件:
|
||||
```bash
|
||||
python3 -m pytest tests/test_semantic_robustness.py::test_cache_hit -v -x
|
||||
```
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
1. 相同内容第二次调用时从缓存读取
|
||||
2. 缓存文件存储在 .planning/cache/semantic/ 目录
|
||||
3. 缓存文件命名格式: {sha256_hash}.json
|
||||
4. 缓存内容包含完整的 SegmentationResult (JSON 格式)
|
||||
5. 缓存命中时记录 debug 级别日志
|
||||
6. 所有测试通过
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
执行完成后创建 `.planning/phases/14-robustness-cost/14-03-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user