From 2dde3a3dc871f2b913eadc69754f2fc656985595 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Mon, 23 Mar 2026 20:51:29 +0800 Subject: [PATCH] docs(14): capture phase context --- .../phases/14-robustness-cost/14-CONTEXT.md | 113 ++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 .planning/phases/14-robustness-cost/14-CONTEXT.md diff --git a/.planning/phases/14-robustness-cost/14-CONTEXT.md b/.planning/phases/14-robustness-cost/14-CONTEXT.md new file mode 100644 index 0000000..a483a2c --- /dev/null +++ b/.planning/phases/14-robustness-cost/14-CONTEXT.md @@ -0,0 +1,113 @@ +# Phase 14: 鲁棒性与成本控制 - Context + +**Gathered:** 2026-03-23 +**Status:** Ready for planning + + +## Phase Boundary + +提高 LLM 语义分段的稳定性和成本效率。 + +**核心能力：** +- LLM 调用失败时的重试和降级策略 +- 长视频字幕的分块处理，避免上下文窗口溢出 +- 智能缓存，避免重复 LLM 调用 +- 详细的日志记录，便于问题诊断 + +**不包括：** +- 输出格式优化（Phase 15 - 兼容性） +- 新的分段策略（Phase 13 已实现统一策略） + + + + +## Implementation Decisions + +### 重试策略 + +- **重试次数**: 重试 1 次 — 失败后立即降级到规则分段，简单快速，避免浪费配额 +- **重试条件**: 仅可恢复错误触发重试 — 网络错误/超时/限流重试，API 错误（如 400）直接降级 +- **重试延迟**: 立即重试 — 失败后立即重试，大多数情况下网络抖动是瞬时的 +- **不可恢复错误**: API 错误（4xx）、解析失败、验证失败等直接降级，不重试 + +### 分块处理 + +- **分块阈值**: 5000 字符（约 10-15 分钟字幕）— 与 ASRCorrector 的 batch_size 一致，保持代码模式统一 +- **分块方式**: 按句子边界分割 — 在句号、问号、感叹号等标点符号后分割，保持语义完整性 +- **结果合并**: 直接拼接各分块结果 — 每个分块独立分段后直接拼接，简单快速 +- **分块策略**: 长字幕按句子边界分成多个 5000 字符以内的块，每块独立调用 LLM 分段 + +### 缓存机制 + +- **缓存键**: 字幕内容哈希（SHA256）— 精确匹配，相同内容一定命中 +- **缓存存储**: 本地文件系统 — 存储在 `.planning/cache/semantic/` 目录，简单持久化 +- **缓存 TTL**: 永久有效 — 字幕内容不变，分段结果应该一致，手动清理过期缓存 +- **缓存内容**: 完整的 SegmentationResult（JSON 格式），包含 video_type 和 segments + +### 日志详细程度 + +- **降级日志**: 记录原因 + 降级方式 — 如 "API key 未配置，降级到规则分段" +- **日志级别**: 区分级别 + - 降级：warning 级别 + - 重试：info 级别 + - 成功：debug 级别 +- **重试日志**: 记录重试原因和次数 +- **缓存日志**: 记录缓存命中/未命中，使用 debug 级别 + +### Claude's Discretion + +- 具体的重试逻辑实现细节 +- 缓存文件命名规则和目录结构 +- 分块算法的具体实现（句子边界检测） +- 日志消息的具体措辞和格式 + + + + +## Existing Code Insights + +### Reusable Assets + +- **kb_workflow/srt/semantic_engine.py** — UnifiedSegmentationStrategy 类，已有基本降级逻辑（AI 不可用时使用规则分段） +- **kb_workflow/srt/corrector.py** — ASRCorrector 类，有 `_correct_long_text()` 方法处理长文本分批（batch_size=5000，按句子分割） +- **kb_workflow/deep_analyzer/__init__.py** — SimpleAIClient 类，统一的 LLM 调用接口 + +### Established Patterns + +- **Lazy AI Client 初始化**: ASRCorrector 模式 — 在 __init__ 中尝试创建 SimpleAIClient，如果 api_key 为空则设为 None +- **AIClientProtocol**: 定义了 generate(prompt, max_tokens, disable_reasoning) 方法 +- **降级策略**: UnifiedSegmentationStrategy.segment() 中已有 try-except，异常时返回规则分段 +- **日志模式**: 使用 `logger.info/warning/error`，已在 semantic_engine.py 中使用 + +### Integration Points + +- **UnifiedSegmentationStrategy.segment()**: 需要添加重试逻辑和分块处理 +- **SemanticSegmentationEngine**: 可以添加缓存层 +- **SimpleAIClient.generate()**: LLM 调用点，需要捕获可恢复错误进行重试 +- **缓存目录**: `.planning/cache/semantic/` — 需要创建目录结构 + + + + +## Specific Ideas + +- **分块与 ASRCorrector 一致**: 复用 ASRCorrector 的分批处理模式（batch_size=5000，按句子分割） +- **重试仅网络错误**: 区分可恢复错误（网络、超时、限流）和不可恢复错误（API 错误、解析失败） +- **缓存与内容绑定**: 使用内容哈希而非视频 ID，避免同一视频更新后缓存失效问题 +- **日志便于诊断**: 降级时记录具体原因（如 "ConnectionError: 请求超时，重试后仍失败，降级到规则分段"） + + + + +## Deferred Ideas + +- **缓存清理命令**: 自动清理过期缓存的功能 — 延后到未来版本，当前手动删除缓存文件 +- **缓存压缩**: 压缩缓存文件以节省空间 — 延后到缓存文件较大时再考虑 +- **分块智能合并**: 检测相邻分段语义相似度并合并 — 增加复杂度，当前直接拼接足够 + + + +--- + +*Phase: 14-robustness-cost* +*Context gathered: 2026-03-23*