From ea2d6e4740ba8ee0bc4b80066541321a8752c80e Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Sun, 22 Mar 2026 00:02:53 +0800 Subject: [PATCH] docs: create milestone v1.6 roadmap (3 phases, 30 requirements) --- .planning/REQUIREMENTS.md | 10 +++-- .planning/ROADMAP.md | 79 +++++++++++++++++++++++++++++++++++++-- .planning/STATE.md | 65 ++++++++++++++++++++++++++------ 3 files changed, 136 insertions(+), 18 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index c758740..a610cd0 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -92,7 +92,7 @@ ## Traceability -需求与阶段的映射关系（在路线图创建时填充）。 +需求与阶段的映射关系。 | Requirement | Phase | Status | |-------------|-------|--------| @@ -131,9 +131,11 @@ **Coverage:** - v1.6 requirements: 30 total -- Mapped to phases: 0 (待路线图创建) -- Unmapped: 30 ⚠️ +- Mapped to phases: 30 (100%) ✓ +- Phase 13: 18 requirements (60%) +- Phase 14: 7 requirements (23%) +- Phase 15: 5 requirements (17%) --- *Requirements defined: 2026-03-21* -*Last updated: 2026-03-21 after initial definition* +*Last updated: 2026-03-21 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 24536cc..921f709 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -8,6 +8,7 @@ - ✅ **v1.3 Proxy Pool** - Phase 10 (shipped 2026-03-18) - ✅ **v1.4 Zhihu Anti-Crawler** - Phase 11 (shipped 2026-03-18) - ✅ **v1.5 B站字幕简化处理** - Phase 12 (shipped 2026-03-21) +- 🔄 **v1.6 语义分段改进** - Phases 13-15 (in progress) ## Phases @@ -148,10 +149,52 @@ Plans: --- +## 🔄 v1.6 语义分段改进 (IN PROGRESS) + +**Milestone Goal:** 使用 LLM 实现智能语义分段，识别视频类型并适配分段策略，保持内容完整性 + +### Phase 13: 核心 LLM 分段功能 +**Goal**: 实现基于 LLM 的智能语义分段，识别视频类型并生成主题标题 +**Depends on**: Phase 12 +**Requirements**: VIDEO-01, VIDEO-02, VIDEO-03, BOUND-01, BOUND-02, BOUND-03, BOUND-04, COMP-01, COMP-02, COMP-03, TITLE-01, TITLE-02, TITLE-03, SENT-01, SENT-02, SENT-03, STRAT-01, STRAT-02, STRAT-03 +**Success Criteria** (what must be TRUE): + 1. 系统能正确识别 B站视频的类型（知识类、故事类等），并根据类型选择分段策略 + 2. 语义分段在主题切换处正确创建边界，不会混入不同话题的内容 + 3. 分段不会在句子中间或论点未完成时截断，保持内容的语义完整性 + 4. 主题/章节分段生成简洁准确的标题，论点/观点分段不加标题 + 5. 不同类型视频使用对应的分段策略，策略可扩展 +**Plans**: TBD + +### Phase 14: 鲁棒性与成本控制 +**Goal**: 提高系统稳定性，实现优雅降级和成本优化 +**Depends on**: Phase 13 +**Requirements**: ROBUST-01, ROBUST-02, ROBUST-03, ROBUST-04, COST-01, COST-02, COST-03 +**Success Criteria** (what must be TRUE): + 1. LLM 调用失败时自动降级到简单规则分段，不影响整体流程 + 2. LLM 响应解析失败时自动重试或降级，有日志记录便于诊断 + 3. AI 不可用时自动使用简单规则分段，保证基本功能可用 + 4. 长视频字幕自动分块处理，避免上下文窗口溢出 + 5. 相同内容使用缓存结果，避免重复 LLM 调用 +**Plans**: TBD + +### Phase 15: 输出优化与兼容性 +**Goal**: 优化输出格式，确保向后兼容和可配置性 +**Depends on**: Phase 14 +**Requirements**: OUTPUT-01, OUTPUT-02, OUTPUT-03, CONFIG-01, CONFIG-02, CONFIG-03 +**Success Criteria** (what must be TRUE): + 1. 主题/章节分段输出带标题的 Markdown 结构，论点/观点分段输出纯文本 + 2. 输出格式与现有 SRTProcessor 兼容，不影响其他平台处理 + 3. LLM 分段功能可通过配置开关启用/禁用 + 4. 向后兼容，禁用时使用简单规则分段，不破坏现有功能 + 5. 知乎/文章平台继续使用 AnalyzeProcessor，不受影响 +**Plans**: TBD + +--- + ## Progress **Execution Order:** -Phases execute in numeric order: 1 → 2 → ... → 10 → 11 → 12 +Phases execute in numeric order: 1 → 2 → ... → 12 → 13 → 14 → 15 | Phase | Milestone | Plans Complete | Status | Completed | |-------|-----------|----------------|--------|-----------| @@ -166,8 +209,38 @@ Phases execute in numeric order: 1 → 2 → ... → 10 → 11 → 12 | 9. Pipeline 整合 | v1.2 | 1/1 | Complete | 2026-03-17 | | 10. Proxy Pool | v1.3 | 2/2 | Complete | 2026-03-18 | | 11. Stealth Fingerprinting | v1.4 | 2/2 | Complete | 2026-03-18 | -| 12. SRT 简化处理器 | v1.5 | Complete | 2026-03-19 | 2026-03-19 | +| 12. SRT 简化处理器 | v1.5 | 2/2 | Complete | 2026-03-21 | +| 13. 核心 LLM 分段功能 | v1.6 | 0/0 | Not started | - | +| 14. 鲁棒性与成本控制 | v1.6 | 0/0 | Not started | - | +| 15. 输出优化与兼容性 | v1.6 | 0/0 | Not started | - | --- -*Last updated: 2026-03-19* +## Context + +### 技术栈 +- Python 3.12+ +- Pydantic v2 (数据验证) +- SimpleAIClient (LLM 调用) +- 现有 SemanticSegmenter (扩展点) + +### v1.6 关键集成点 +- **SemanticSegmentationEngine**: 新模块，负责 LLM 调用和语义分析 +- **SRTProcessor**: 扩展现有处理器，添加 LLM 分支 +- **Pydantic Schemas**: 严格验证 LLM 输出格式 + +### 三层 Fallback 策略 +1. 直接 JSON 解析（理想情况） +2. Markdown 代码块提取（常见情况） +3. 启发式均匀分段（保底方案） + +### 需要避免的陷阱 +- **LLM-1**: 上下文窗口溢出 — 实施分块策略 +- **LLM-2**: 输出格式不稳定 — 多层 fallback +- **LLM-3**: 边界破坏完整性 — 句边界保护 +- **LLM-4**: 分段不一致性 — 温度控制 +- **LLM-5**: 成本失控 — 缓存策略 + +--- + +*Last updated: 2026-03-21* diff --git a/.planning/STATE.md b/.planning/STATE.md index 1c13b21..b05c0f7 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,11 +3,11 @@ gsd_state_version: 1.0 milestone: v1.6 milestone_name: 语义分段改进 status: in_progress -stopped_at: Defining requirements -last_updated: "2026-03-21T16:00:00.000Z" -last_activity: 2026-03-21 — Milestone v1.6 started +stopped_at: Planning Phase 13 +last_updated: "2026-03-21T16:30:00.000Z" +last_activity: 2026-03-21 — Roadmap created for v1.6 progress: - total_phases: 0 + total_phases: 3 completed_phases: 0 total_plans: 0 completed_plans: 0 @@ -25,12 +25,23 @@ See: .planning/PROJECT.md (updated 2026-03-21) ## Current Position -Phase: Not started (defining requirements) -Plan: — -Status: Defining requirements -Last activity: 2026-03-21 — Milestone v1.6 started +Phase: Phase 13 - 核心 LLM 分段功能 +Plan: TBD +Status: Planning +Last activity: 2026-03-21 — Roadmap created for v1.6 -Progress: [░░░░░░░░░░] 0% +Progress: [░░░░░░░░░░] 0% (Phase 13/15) + +### Phase 13 Goal +实现基于 LLM 的智能语义分段，识别视频类型并生成主题标题 + +### Phase 13 Requirements (18 total) +- VIDEO-01, VIDEO-02, VIDEO-03 (视频类型识别) +- BOUND-01, BOUND-02, BOUND-03, BOUND-04 (语义边界检测) +- COMP-01, COMP-02, COMP-03 (内容完整性保护) +- TITLE-01, TITLE-02, TITLE-03 (主题标题生成) +- SENT-01, SENT-02, SENT-03 (中文句边界检测) +- STRAT-01, STRAT-02, STRAT-03 (分段策略) ## Accumulated Context @@ -51,6 +62,38 @@ v1.6 scope (待验证): - 主题识别与标题 — 主题章节生成标题 - 内容完整性 — 避免错误截断话题 +### Technical Context + +**架构集成:** +- 扩展现有 `SemanticSegmenter`，保持向后兼容 +- 新增 `SemanticSegmentationEngine` 模块（`kb_workflow/srt/semantic_engine.py`） +- 在 `SRTProcessor` 中添加 LLM 分支（`enable_semantic_segmentation` 参数） + +**技术栈:** +- SimpleAIClient（已集成 zhipu/openai/minimax） +- Pydantic v2（LLM 响应验证） +- 现有 SemanticSegmenter（规则分段保留） + +**数据流:** +``` +SRT Input → Parse Subtitles → Video Type Detection → +Semantic Segmentation → Extract Paragraphs → ASR Correction → +Deep Analysis +``` + +### Known Risks + +**高优先级风险:** +1. **上下文窗口溢出** — 长视频（>1小时）字幕超10万字符，需分块处理 +2. **LLM 输出格式不稳定** — 需多层 fallback 策略 +3. **分段边界破坏完整性** — 需句边界保护机制 +4. **分段不一致性** — LLM 随机性导致多次运行结果不同 +5. **成本失控** — 高频 LLM 调用可能导致费用激增 + +**缓解策略:** +- Phase 13: 实现 Pydantic 验证 + 句边界保护 +- Phase 14: 实现分块处理 + 缓存 + 温度控制 + ### Blockers/Concerns None. @@ -58,7 +101,7 @@ None. ## Session Continuity Last session: 2026-03-21 -Stopped at: Milestone v1.6 started +Stopped at: Roadmap created for v1.6 Resume file: None -**Next step:** Define requirements for semantic segmentation +**Next step:** `/gsd:plan-phase 13` - 开始 Phase 13 的详细规划