diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index a80e897..f93032b 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -53,7 +53,7 @@ ### 成本控制 (COST) -- [ ] **COST-01**: 长视频字幕进行分块处理，避免上下文窗口溢出 +- [x] **COST-01**: 长视频字幕进行分块处理，避免上下文窗口溢出 - [x] **COST-02**: 实现智能缓存，相同内容不重复调用 LLM - [ ] **COST-03**: 提供配置开关，用户可选择是否启用 LLM 分段 @@ -119,7 +119,7 @@ | ROBUST-02 | Phase 14 | Complete | | ROBUST-03 | Phase 14 | Complete | | ROBUST-04 | Phase 14 | Complete | -| COST-01 | Phase 14 | Pending | +| COST-01 | Phase 14 | Complete | | COST-02 | Phase 14 | Complete | | COST-03 | Phase 14 | Pending | | OUTPUT-01 | Phase 15 | Pending | diff --git a/.planning/STATE.md b/.planning/STATE.md index 1d45c40..7a7e209 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.4 milestone_name: Zhihu Anti-Crawler status: executing -stopped_at: Completed 14-05 integrate cache and configuration toggle -last_updated: "2026-03-23T23:00:00.000Z" -last_activity: 2026-03-23 — Phase 14 Plan 05 completed (cache integration and config toggle) +stopped_at: Completed 14-04 long text chunking +last_updated: "2026-03-23T15:30:00.000Z" +last_activity: 2026-03-23 — Phase 14 Plan 04 completed (long text chunking) progress: total_phases: 15 completed_phases: 11 total_plans: 44 - completed_plans: 42 + completed_plans: 41 percent: 34 --- @@ -26,11 +26,11 @@ See: .planning/PROJECT.md (updated 2026-03-21) ## Current Position Phase: Phase 14 - 鲁棒性与成本控制 -Plan: 05 (completed) +Plan: 04 (completed) Status: In progress -Last activity: 2026-03-23 — Phase 14 Plan 05 completed (cache integration and config toggle) +Last activity: 2026-03-23 — Phase 14 Plan 04 completed (long text chunking) -Progress: [███░░░░░░░░] 34% (Phase 14/15, 5/5 plans complete) +Progress: [██░░░░░░░░░] 34% (Phase 14/15, 4/6 plans complete) ### Phase 14 Goal 提高 LLM 语义分段的稳定性和成本效率，实现智能缓存和优雅降级 @@ -91,13 +91,16 @@ v1.6 Phase 13 decisions (from 13-CONTEXT.md): - [Phase 14]: JSON parse errors (JSONDecodeError, ValueError) are recoverable - retry 1 time - [Phase 14]: Pydantic validation errors (ValidationError) are non-recoverable - immediate fallback - [Phase 14]: Parse failures log LLM output fragment (first 500 chars) for diagnosis +- [Phase 14 Plan 04]: 分块阈值 5000 字符 - 与 ASRCorrector 的 batch_size 一致 +- [Phase 14 Plan 04]: 按句子边界分割 - 使用标点符号（。！？\n）保持语义完整性 +- [Phase 14 Plan 04]: 索引修正 - start_index/end_index 相对于原文位置，通过 offset 累加 +- [Phase 14 Plan 04]: 单个分块失败降级 - 该分块使用规则分段，不影响其他分块 +- [Phase 14 Plan 04]: 分块方法 - _split_into_chunks(), _merge_segment_results(), _segment_single_chunk(), _segment_multiple_chunks(), _fallback_chunk() - [Phase 14 Plan 05]: 缓存集成到 UnifiedSegmentationStrategy - 可选的 cache 参数 - [Phase 14 Plan 05]: 缓存检查逻辑 - 调用 LLM 前检查缓存，命中时直接返回 - [Phase 14 Plan 05]: 缓存保存逻辑 - LLM 调用成功后保存结果到缓存 - [Phase 14 Plan 05]: SRTProcessor 缓存支持 - enable_cache 参数控制缓存创建 - [Phase 14 Plan 05]: 配置开关验证 - enable_semantic_segmentation 控制 LLM/规则分段 -- [Phase 14 Plan 05]: 分块处理实现 - 实现 _segment_single_chunk 和 _segment_multiple_chunks 方法 -- [Phase 14 Plan 05]: 分块阈值 5000 字符 - 与 ASRCorrector 保持一致 ### Technical Context diff --git a/.planning/phases/14-robustness-cost/14-04-SUMMARY.md b/.planning/phases/14-robustness-cost/14-04-SUMMARY.md new file mode 100644 index 0000000..10ed1bf --- /dev/null +++ b/.planning/phases/14-robustness-cost/14-04-SUMMARY.md @@ -0,0 +1,141 @@ +--- +phase: 14-robustness-cost +plan: 04 +subsystem: semantic-segmentation +tags: [chunking, llm, long-text, sentence-boundaries, index-correction] + +# Dependency graph +requires: + - phase: 14-robustness-cost + plan: 03 + provides: retry-logic, parse-error-handling +provides: + - Long text chunking with sentence boundary detection + - Index correction for chunked segments + - Per-chunk fallback to rule-based segmentation +affects: [] + +# Tech tracking +tech-stack: + added: [] + patterns: + - Chunk-based text processing with offset tracking + - Per-chunk independent LLM calls with fallback + +key-files: + created: [] + modified: + - kb_workflow/srt/semantic_engine.py + - tests/test_semantic_robustness.py + +key-decisions: + - "分块阈值: 5000 字符（与 ASRCorrector 的 batch_size 一致）" + - "按句子边界分割（。！？\\n）保持语义完整性" + - "start_index/end_index 相对于原文位置（需要 offset 累加）" + - "单个分块失败时降级到规则分段，不影响其他分块" + +patterns-established: + - "Chunk processing pattern: split -> process -> merge with index correction" + - "Fallback pattern: per-chunk failure isolation" + +requirements-completed: ["COST-01"] + +# Metrics +duration: 15 min +completed: 2026-03-23T15:30:00Z +--- + +# Phase 14 Plan 04: 长文本分块处理 Summary + +**长视频字幕自动分块处理，按句子边界分割并独立调用 LLM 分段，避免上下文窗口溢出** + +## Performance + +- **Duration:** 15 min +- **Started:** 2026-03-23T15:15:00Z +- **Completed:** 2026-03-23T15:30:00Z +- **Tasks:** 2 +- **Files modified:** 2 + +## Accomplishments +- 实现长文本自动分块处理（>5000 字符触发分块） +- 按句子边界分割（。！？\n）保持语义完整性 +- 分块索引修正（start_index/end_index 相对于原文） +- 单个分块失败时降级到规则分段 + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: 实现长文本分块处理方法** - `faff790` (feat) + - 添加 _split_into_chunks() 方法，按句子边界分割长文本 + - 添加 _merge_segment_results() 方法，合并分块结果并修正索引 + - 添加 _segment_single_chunk() 和 _segment_multiple_chunks() 方法 + - 添加 _fallback_chunk() 方法，用于单个分块失败时的降级处理 + - 修改 segment() 方法，添加分块判断逻辑 + +2. **Task 2: 编写长文本分块处理测试** - `ee5062c` (test) + - 添加 TestSplitIntoChunks 测试类（4 个测试用例） + - 添加 TestLongTextChunking 测试类（2 个测试用例） + - 添加 TestChunkIndexCorrection 测试类（2 个测试用例） + - 添加 TestChunkFallback 测试类（2 个测试用例） + +**Plan metadata:** (to be added) + +## Files Created/Modified +- `kb_workflow/srt/semantic_engine.py` - 添加分块处理逻辑（5 个新方法） +- `tests/test_semantic_robustness.py` - 添加 10 个测试用例覆盖分块功能 + +## Decisions Made + +### 分块处理策略 +- **分块阈值**: 5000 字符（与 ASRCorrector 的 batch_size 一致，保持代码模式统一） +- **分块方式**: 按句子边界分割（。！？\n）保持语义完整性 +- **结果合并**: 直接拼接各分块结果，简单快速 +- **索引修正**: start_index/end_index 相对于原文位置，通过 offset 累加实现 + +### 降级策略 +- **单个分块失败**: 该分块降级到规则分段，不影响其他分块 +- **规则分段集成**: 使用 SemanticSegmenter 对单个分块进行规则分段 +- **索引保持**: 降级分块同样进行索引修正，保持一致性 + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] 修复 Segment 构造函数参数** +- **Found during:** Task 2 (测试 _fallback_chunk 方法) +- **Issue:** Segment 使用 `id` 而不是 `index` 作为构造函数参数 +- **Fix:** 将 `Segment(index=1, ...)` 修改为 `Segment(id=1, ...)` +- **Files modified:** kb_workflow/srt/semantic_engine.py +- **Verification:** 测试通过，_fallback_chunk 正常工作 +- **Committed in:** (修复后重新提交 Task 1) + +**2. [Rule 1 - Bug] 修复测试中的双大括号语法错误** +- **Found during:** Task 2 (运行测试) +- **Issue:** 测试中使用了双大括号 `{{` 而不是单大括号 `{`，导致 TypeError +- **Fix:** 将所有双大括号修改为单大括号 +- **Files modified:** tests/test_semantic_robustness.py +- **Verification:** 所有测试通过 +- **Committed in:** ee5062c (Task 2 commit) + +--- + +**Total deviations:** 2 auto-fixed (1 blocking, 1 bug) +**Impact on plan:** 两个修复都是必要的，确保代码正确性和测试通过。无范围蔓延。 + +## Issues Encountered +- 空文本分块返回空列表（0 个分块），测试已更新以反映此行为 + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- 长文本分块处理功能完整，测试覆盖充分 +- 准备好进入下一个计划（14-05: 集成到 SRTProcessor 和配置开关） +- 分块处理与现有重试逻辑、解析错误处理良好配合 + +--- +*Phase: 14-robustness-cost* +*Plan: 04* +*Completed: 2026-03-23*