From 2bcaf05d52b0d3134431872829d7fd47c37d8ce8 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Sun, 22 Mar 2026 00:21:30 +0800 Subject: [PATCH] docs(13): create phase 13 plan (7 plans) --- .planning/ROADMAP.md | 15 +- .planning/phases/13-llm/13-01-PLAN.md | 170 ++++++++++++++++++++ .planning/phases/13-llm/13-02-PLAN.md | 184 +++++++++++++++++++++ .planning/phases/13-llm/13-03-PLAN.md | 143 +++++++++++++++++ .planning/phases/13-llm/13-04-PLAN.md | 183 +++++++++++++++++++++ .planning/phases/13-llm/13-05-PLAN.md | 148 +++++++++++++++++ .planning/phases/13-llm/13-06-PLAN.md | 207 ++++++++++++++++++++++++ .planning/phases/13-llm/13-07-PLAN.md | 222 ++++++++++++++++++++++++++ 8 files changed, 1269 insertions(+), 3 deletions(-) create mode 100644 .planning/phases/13-llm/13-01-PLAN.md create mode 100644 .planning/phases/13-llm/13-02-PLAN.md create mode 100644 .planning/phases/13-llm/13-03-PLAN.md create mode 100644 .planning/phases/13-llm/13-04-PLAN.md create mode 100644 .planning/phases/13-llm/13-05-PLAN.md create mode 100644 .planning/phases/13-llm/13-06-PLAN.md create mode 100644 .planning/phases/13-llm/13-07-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 921f709..06a87dc 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -163,7 +163,16 @@ Plans: 3. 分段不会在句子中间或论点未完成时截断，保持内容的语义完整性 4. 主题/章节分段生成简洁准确的标题，论点/观点分段不加标题 5. 不同类型视频使用对应的分段策略，策略可扩展 -**Plans**: TBD +**Plans**: 7 plans + +Plans: +- [ ] 13-01-PLAN.md — 视频类型识别（Pydantic 模型、类型推断、LazyAIClient 初始化） +- [ ] 13-02-PLAN.md — 语义边界检测（Prompt 模板、JSON 提取、Pydantic 验证） +- [ ] 13-03-PLAN.md — 内容完整性保护（句边界、论点完整性 Prompt 指令） +- [ ] 13-04-PLAN.md — 主题标题生成（title 字段、验证、Prompt 指令） +- [ ] 13-05-PLAN.md — 中文句边界检测（列举标点符号、语义停顿 Prompt 指令） +- [ ] 13-06-PLAN.md — 可扩展策略架构（Strategy Pattern、统一策略实现） +- [ ] 13-07-PLAN.md — SRTProcessor 集成（enable_semantic_segmentation 参数、降级策略） ### Phase 14: 鲁棒性与成本控制 **Goal**: 提高系统稳定性，实现优雅降级和成本优化 @@ -210,7 +219,7 @@ Phases execute in numeric order: 1 → 2 → ... → 12 → 13 → 14 → 15 | 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 | 2/2 | Complete | 2026-03-21 | -| 13. 核心 LLM 分段功能 | v1.6 | 0/0 | Not started | - | +| 13. 核心 LLM 分段功能 | v1.6 | 0/7 | Planning | - | | 14. 鲁棒性与成本控制 | v1.6 | 0/0 | Not started | - | | 15. 输出优化与兼容性 | v1.6 | 0/0 | Not started | - | @@ -243,4 +252,4 @@ Phases execute in numeric order: 1 → 2 → ... → 12 → 13 → 14 → 15 --- -*Last updated: 2026-03-21* +*Last updated: 2026-03-22* diff --git a/.planning/phases/13-llm/13-01-PLAN.md b/.planning/phases/13-llm/13-01-PLAN.md new file mode 100644 index 0000000..47ef020 --- /dev/null +++ b/.planning/phases/13-llm/13-01-PLAN.md @@ -0,0 +1,170 @@ +--- +phase: 13 +plan: 01 +type: tdd +wave: 1 +depends_on: [] +files_modified: + - kb_workflow/srt/semantic_engine.py + - tests/test_semantic_engine.py + - tests/conftest.py +autonomous: true +requirements: + - VIDEO-01 + - VIDEO-02 + - VIDEO-03 +must_haves: + truths: + - "系统能识别视频类型（知识类/故事类/访谈类/新闻类/vlog 等）" + - "视频类型用于 Prompt 上下文，但不改变分段策略" + - "类型识别失败时使用默认类型，不影响分段功能" + artifacts: + - path: "kb_workflow/srt/semantic_engine.py" + provides: "SemanticSegmentationEngine 类和 Pydantic 模型" + min_lines: 200 + exports: ["VideoSegment", "SegmentationResult", "SemanticSegmentationEngine"] + - path: "tests/test_semantic_engine.py" + provides: "视频类型识别测试" + min_lines: 50 + - path: "tests/conftest.py" + provides: "共享测试 fixtures" + contains: "mock_ai_client, sample_segments" + key_links: + - from: "SemanticSegmentationEngine._build_prompt" + to: "SegmentationResult.video_type" + via: "Prompt 中包含视频类型信息" + pattern: "video_type.*prompt" + - from: "tests/test_semantic_engine.py" + to: "kb_workflow/srt/semantic_engine.py" + via: "单元测试验证类型识别" + pattern: "test.*video.*type" +--- + + +实现视频类型识别功能，用于 Prompt 上下文 + +目的：让 LLM 了解视频类型（知识类/故事类等）以优化分段质量，但不针对不同类型使用不同策略（统一 Prompt） +输出：VideoSegment 和 SegmentationResult Pydantic 模型，视频类型识别逻辑 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/phases/13-llm/13-CONTEXT.md +@.planning/phases/13-llm/13-RESEARCH.md +@.planning/ROADMAP.md + +# Existing Code Patterns + +From kb_workflow/srt/corrector.py: +```python +class ASRCorrector: + def __init__(self, ai_client: Optional[AIClientProtocol] = None): + self.ai_client = ai_client + # Lazy initialization pattern +``` + +From kb_workflow/deep_analyzer/__init__.py: +```python +class SimpleAIClient: + def generate(self, prompt: str, max_tokens: int = 16000, disable_reasoning: bool = None) -> str: + # Supports zhipu, openai, minimax providers + # disable_reasoning parameter for cost control +``` + + + + 视频类型识别 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + 定义 Pydantic 模型验证 LLM 输出： + - VideoSegment: title (可选), content, start_index, end_index + - SegmentationResult: video_type, segments[], actual_segment_count + + 视频类型识别： + - 从元数据推断类型（基于标题、标签、分类） + - 默认类型为"知识类"（最常见） + - 类型用于 Prompt 上下文，不改变分段策略 + + LLM 调用失败时： + - 返回默认 SegmentationResult（video_type="知识类", 使用规则分段） + + + 在 semantic_engine.py 中： + 1. 定义 VideoSegment 和 SegmentationResult Pydantic 模型 + 2. 实现 _infer_video_type() 方法，从元数据推断类型 + 3. 在 _build_prompt() 中包含视频类型信息 + 4. 实现 LazyAIClient 初始化模式（参考 ASRCorrector） + + 测试文件： + 1. test_video_type_detection() - 验证类型推断 + 2. test_video_type_in_prompt() - 验证类型出现在 Prompt 中 + 3. test_video_type_fallback() - 验证默认类型处理 + + + + + + Task 1: 创建 Pydantic 模型和类型推断 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + RED 阶段 - 测试预期行为： + - test_video_type_detection: 从元数据正确推断视频类型 + - test_video_type_in_prompt: Prompt 包含视频类型信息 + - test_video_type_fallback: 元数据缺失时使用默认类型 + + GREEN 阶段 - 实现功能： + - 定义 VideoSegment Pydantic 模型（title 可选，content 必填） + - 定义 SegmentationResult Pydantic 模型（video_type, segments 列表） + - 实现 _infer_video_type() 从 metadata 推断类型 + - 实现 _build_prompt() 包含类型信息 + + REFACTOR 阶段 - 优化代码： + - 提取视频类型映射常量 + - 优化类型推断逻辑 + + + 创建 semantic_engine.py，实现： + 1. VideoSegment(title: Optional[str], content: str, start_index: int, end_index: int) + 2. SegmentationResult(video_type: str, segments: List[VideoSegment], actual_segment_count: int) + 3. _infer_video_type(metadata: dict) -> str 方法 + 4. _build_prompt(content: str, metadata: dict) -> str 方法（包含类型信息） + + 参考 ASRCorrector 的 LazyAIClient 初始化模式，但暂时不实现完整 LLM 调用（留待后续计划） + + 测试覆盖类型推断的各种场景： + - 从 title 包含"教程""课程"推断为"知识类" + - 从 category 包含"影视"推断为"故事类" + - 元数据为空时返回"知识类"（默认） + + + pytest tests/test_semantic_engine.py::test_video_type_detection -x + + + - Pydantic 模型定义完成，包含字段验证 + - _infer_video_type() 能从元数据正确推断类型 + - _build_prompt() 包含视频类型上下文 + - 三个测试全部通过 + + + + + +- pytest tests/test_semantic_engine.py -v 全部通过 +- 代码符合 PEP 8 规范 +- Pydantic 模型通过类型检查 + + + +1. VideoSegment 和 SegmentationResult Pydantic 模型定义完成 +2. _infer_video_type() 能正确推断视频类型 +3. _build_prompt() 包含视频类型信息 +4. 所有测试通过（test_video_type_detection, test_video_type_in_prompt, test_video_type_fallback） + + + +After completion, create `.planning/phases/13-llm/13-01-SUMMARY.md` + diff --git a/.planning/phases/13-llm/13-02-PLAN.md b/.planning/phases/13-llm/13-02-PLAN.md new file mode 100644 index 0000000..c2d6ca2 --- /dev/null +++ b/.planning/phases/13-llm/13-02-PLAN.md @@ -0,0 +1,184 @@ +--- +phase: 13 +plan: 02 +type: tdd +wave: 1 +depends_on: [] +files_modified: + - kb_workflow/srt/semantic_engine.py + - tests/test_semantic_engine.py +autonomous: true +requirements: + - BOUND-01 + - BOUND-02 + - BOUND-03 + - BOUND-04 +must_haves: + truths: + - "系统能检测字幕中的话题转换点" + - "边界检测基于语义分析，而非时间间隔或字符长度" + - "话题切换时正确创建分段，不混入不同话题的内容" + - "单个话题的内容保持完整，不会被错误截断" + artifacts: + - path: "kb_workflow/srt/semantic_engine.py" + provides: "语义边界检测 Prompt 模板" + min_lines: 250 + exports: ["SEGMENTATION_PROMPT", "_parse_result"] + - path: "tests/test_semantic_engine.py" + provides: "话题边界检测测试" + min_lines: 80 + key_links: + - from: "SEGMENTATION_PROMPT" + to: "LLM 输出" + via: "Prompt 指令要求识别话题转换点" + pattern: "话题转换.*分段" + - from: "_parse_result" + to: "SegmentationResult" + via: "解析 LLM 返回的 JSON" + pattern: "extract.*json.*validate" +--- + + +实现语义边界检测功能 + +目的：让 LLM 识别话题转换点，在不同主题之间创建分段边界 +输出：SEGMENTATION_PROMPT 模板，_parse_result 解析方法 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/phases/13-llm/13-CONTEXT.md +@.planning/phases/13-llm/13-RESEARCH.md + +# Existing Code + +From kb_workflow/srt/segmenter.py: +```python +class SemanticSegmenter: + # 规则分段：基于时间间隔（>3秒）和字符长度（>500） + def segment(self, segments: List[Segment]) -> List[str]: + # 简单启发式规则 +``` + +SemanticSegmentationEngine 将替代这个规则分段器，使用 LLM 进行语义分析。 + + + + 语义边界检测 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + Prompt 设计： + - 明确指令「在话题转换处创建新分段，不要混入不同话题的内容」 + - 强调「基于语义完整性，而非时间或字符长度」 + - 建议分段数量 5-8 个（可灵活调整） + - 每段约 1000-2000 字（为保持语义完整性可突破） + + LLM 输出解析： + - 提取 JSON 格式的分段结果 + - 验证每个分段的 start_index 和 end_index + - 验证分段内容不重叠且覆盖原文 + + 边界检测质量： + - 话题切换时正确创建边界 + - 单个话题内容保持完整 + + + 在 semantic_engine.py 中： + 1. 定义 SEGMENTATION_PROMPT 常量（包含话题转换检测指令） + 2. 实现 extract_json_from_llm_response() 方法（参考研究文档） + 3. 实现 _parse_result() 方法，解析 LLM 输出并验证 + + 测试： + 1. test_topic_boundary_detection() - 验证话题转换检测 + 2. test_semantic_completeness() - 验证单个话题完整性 + + + + + + Task 1: 实现语义边界检测 Prompt 和解析 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + RED 阶段 - 测试预期行为： + - test_topic_boundary_detection: LLM 正确识别话题转换点 + - test_semantic_completeness: 单个话题内容完整，不混入其他话题 + + GREEN 阶段 - 实现功能： + - SEGMENTATION_PROMPT 包含「在话题转换处创建新分段」指令 + - extract_json_from_llm_response() 从 LLM 响应提取 JSON + - _parse_result() 使用 Pydantic 验证 SegmentationResult + + REFACTOR 阶段 - 优化代码： + - 提取 JSON 提取逻辑为独立函数 + - 优化 Prompt 指令的清晰度 + + + 在 semantic_engine.py 中实现： + + 1. SEGMENTATION_PROMPT 模板（基于研究文档）： + ```python + SEGMENTATION_PROMPT = """你是一个专业的视频内容分析师。请将以下字幕内容按语义分段。 + + 【视频信息】 + 类型：{video_type} + 标题：{title} + 总字数：{total_chars}字 + + 【字幕内容】 + {content} + + 【分段要求】 + 1. 建议将内容分为 5-8 个段落（可根据语义完整性灵活调整） + 2. 每个段落约 1000-2000 字（为保持语义完整性可以突破此范围） + 3. **在话题转换处创建新分段，不要混入不同话题的内容** + 4. 保持句子完整性，分段边界应放在自然停顿处 + ...""" + ``` + + 2. extract_json_from_llm_response(response: str) -> Dict: + - 尝试直接解析 JSON + - 提取 ```json ``` 代码块 + - 使用正则提取任何 JSON 对象 + + 3. _parse_result(llm_output: str, fallback_segments) -> List[VideoSegment]: + - 调用 extract_json_from_llm_response + - 使用 SegmentationResult.validate() 验证 + - 失败时返回 fallback_segments + + 测试使用 mock_ai_client 模拟 LLM 响应，验证： + - 话题转换点正确识别 + - 分段内容不重叠 + - 覆盖完整原文 + + + pytest tests/test_semantic_engine.py::test_topic_boundary_detection -x + + + - SEGMENTATION_PROMPT 包含话题转换检测指令 + - extract_json_from_llm_response() 能从各种格式提取 JSON + - _parse_result() 能正确解析和验证 LLM 输出 + - 测试验证边界检测质量 + + + + + +- pytest tests/test_semantic_engine.py -v 相关测试通过 +- Prompt 指令清晰明确 +- JSON 解析健壮（处理多种格式） + + + +1. SEGMENTATION_PROMPT 包含话题转换检测指令 +2. extract_json_from_llm_response() 能处理纯 JSON、代码块、混合文本 +3. _parse_result() 使用 Pydantic 验证 LLM 输出 +4. 测试验证边界检测功能 + + + +After completion, create `.planning/phases/13-llm/13-02-SUMMARY.md` + diff --git a/.planning/phases/13-llm/13-03-PLAN.md b/.planning/phases/13-llm/13-03-PLAN.md new file mode 100644 index 0000000..c8c6abc --- /dev/null +++ b/.planning/phases/13-llm/13-03-PLAN.md @@ -0,0 +1,143 @@ +--- +phase: 13 +plan: 03 +type: tdd +wave: 1 +depends_on: [] +files_modified: + - kb_workflow/srt/semantic_engine.py + - tests/test_semantic_engine.py +autonomous: true +requirements: + - COMP-01 + - COMP-02 + - COMP-03 +must_haves: + truths: + - "分段不会在句子中间截断内容" + - "分段不会破坏论点的完整性（如前提-结论结构）" + - "并列结构（首先、其次、最后）不会被错误拆分" + artifacts: + - path: "kb_workflow/srt/semantic_engine.py" + provides: "内容完整性保护 Prompt 指令" + contains: "SEGMENTATION_PROMPT" + - path: "tests/test_semantic_engine.py" + provides: "内容完整性测试" + min_lines: 80 + key_links: + - from: "SEGMENTATION_PROMPT" + to: "LLM 输出分段" + via: "Prompt 中的完整性约束指令" + pattern: "不要在句子中间截断.*保持论点完整性" +--- + + +实现内容完整性保护功能 + +目的：通过 Prompt 约束确保分段不破坏句子和论点完整性 +输出：SEGMENTATION_PROMPT 中的完整性保护指令 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/phases/13-llm/13-CONTEXT.md +@.planning/phases/13-llm/13-RESEARCH.md + +# User Decision (Locked) +- **句边界保护**: 纯 Prompt 约束 — 在 Prompt 中明确指令「不要在句子中间截断」，依赖 LLM 理解，不进行代码后处理 +- **论点完整性**: 一般性指令 — Prompt 中给出「保持论点完整性」的一般性指令，不提供具体示例或标记词识别 +- **并列结构**: 不特别指定 — 对「首先/其次/最后」等并列结构不给出特殊处理，让 LLM 根据整体语义自然判断 + + + + 内容完整性保护 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + Prompt 约束（用户决策：纯 Prompt，无代码后处理）： + - 「不要在句子中间截断」 + - 「分段边界应放在自然停顿处（句号。、问号？、感叹号！、省略号……等标点符号后）」 + - 「保持论点完整性，不要在前提-结论结构中间截断」 + - 对并列结构不特别指定（让 LLM 自然判断） + + 测试验证： + - 分段边界在标点符号后 + - 论点结构完整（前提-结论不被拆分） + - 并列结构保持完整 + + + 在 SEGMENTATION_PROMPT 中添加完整性保护指令： + 1. 明确句边界要求（列举所有中文句末标点） + 2. 添加论点完整性指令 + 3. 不添加并列结构特殊处理（按用户决策） + + 测试： + 1. test_sentence_boundary_protection() - 验证句边界保护 + 2. test_argument_completeness() - 验证论点完整性 + + + + + + Task 1: 添加内容完整性保护指令 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + RED 阶段 - 测试预期行为： + - test_sentence_boundary_protection: 分段边界在标点符号后 + - test_argument_completeness: 论点结构完整 + + GREEN 阶段 - 实现功能： + - SEGMENTATION_PROMPT 添加句边界指令 + - SEGMENTATION_PROMPT 添加论点完整性指令 + - 不添加并列结构特殊处理（遵守用户决策） + + REFACTOR 阶段 - 优化代码： + - 优化指令措辞（更清晰明确） + + + 更新 SEGMENTATION_PROMPT，添加完整性保护指令： + + ```python + 【分段要求】 + ... + 4. **重要**：保持句子完整性，分段边界应放在自然停顿处（句号。、问号？、感叹号！、省略号……等标点符号后） + 5. 保持论点完整性，不要在前提-结论结构中间截断 + ``` + + 注意：不添加并列结构特殊处理（遵守用户决策：让 LLM 自然判断） + + 测试使用包含以下场景的字幕： + - 句子中间不应截断（如「机器学习是...」不应被拆开） + - 论点完整性（如「因此...所以...」不应被拆开） + - 并列结构（如「首先...其次...最后...」应保持完整） + + + pytest tests/test_semantic_engine.py::test_sentence_boundary_protection -x + + + - SEGMENTATION_PROMPT 包含句边界保护指令 + - SEGMENTATION_PROMPT 包含论点完整性指令 + - 不包含并列结构特殊处理（遵守用户决策） + - 测试验证完整性保护效果 + + + + + +- pytest tests/test_semantic_engine.py -v 相关测试通过 +- Prompt 指令清晰明确 +- 不包含并列结构特殊处理（符合用户决策） + + + +1. SEGMENTATION_PROMPT 包含句边界保护指令（列举所有标点符号） +2. SEGMENTATION_PROMPT 包含论点完整性指令 +3. 测试验证完整性保护效果 + + + +After completion, create `.planning/phases/13-llm/13-03-SUMMARY.md` + diff --git a/.planning/phases/13-llm/13-04-PLAN.md b/.planning/phases/13-llm/13-04-PLAN.md new file mode 100644 index 0000000..cb7c450 --- /dev/null +++ b/.planning/phases/13-llm/13-04-PLAN.md @@ -0,0 +1,183 @@ +--- +phase: 13 +plan: 04 +type: tdd +wave: 1 +depends_on: [] +files_modified: + - kb_workflow/srt/semantic_engine.py + - tests/test_semantic_engine.py +autonomous: true +requirements: + - TITLE-01 + - TITLE-02 + - TITLE-03 +must_haves: + truths: + - "系统能为主题/章节类型的分段生成描述性标题" + - "标题简洁准确（5-15字），反映分段的主要内容" + - "论点/观点类型的分段只分段，不加标题" + artifacts: + - path: "kb_workflow/srt/semantic_engine.py" + provides: "标题生成 Prompt 指令和验证" + contains: "VideoSegment.title 字段验证" + - path: "tests/test_semantic_engine.py" + provides: "标题生成测试" + min_lines: 60 + key_links: + - from: "SEGMENTATION_PROMPT" + to: "VideoSegment.title" + via: "Prompt 指导 LLM 生成标题" + pattern: "为主题.*生成标题.*5-15字" + - from: "VideoSegment.validate_title_length" + to: "Pydantic 验证" + via: "标题长度限制" + pattern: "len.*title.*15" +--- + + +实现主题标题生成功能 + +目的：让 LLM 为主题/章节类型分段生成简洁准确的标题，论点/观点分段不加标题 +输出：VideoSegment.title 字段和验证，Prompt 中的标题生成指令 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/phases/13-llm/13-CONTEXT.md +@.planning/phases/13-llm/13-RESEARCH.md + +# User Decision (Locked) +- **标题范围**: LLM 自主判断 — 让 LLM 自行判断哪些分段需要标题（主题/章节类），哪些不需要（观点/对话类），不在 Prompt 中硬性规定 +- **标题风格**: 简洁描述型 — 标题应简短（5-15 字），如「机器学习概述」「梯度下降原理」，类似目录结构 +- **标题格式**: H2 (##) — 在 Markdown 输出中，标题使用二级标题（##），与现有「## 内容」格式保持一致 +- **标题缺失处理**: 跳过标题 — 如果 LLM 无法为某个分段生成合适的标题（如过渡性内容），该分段不加标题，直接以内容开始 + + + + 主题标题生成 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + Prompt 设计（用户决策）： + - 让 LLM 自主判断哪些分段需要标题 + - 标题简洁（5-15字），如「机器学习概述」 + - 过渡性内容可将 title 设为 null + + Pydantic 验证： + - title: Optional[str] = None + - 标题长度验证（不超过 15 字） + + 测试验证： + - 主题/章节分段生成标题 + - 标题简洁准确 + - 论点/观点分段标题为 null + + + 在 VideoSegment 模型中： + 1. title: Optional[str] = Field(None, description="分段标题（5-15字）") + 2. @field_validator('title') 验证长度 + + 在 SEGMENTATION_PROMPT 中： + 1. 添加标题生成指令 + 2. 说明 LLM 自主判断是否需要标题 + 3. 标题简洁（5-15字） + 4. 无法生成标题时设为 null + + 测试： + 1. test_title_generation() - 验证标题生成 + 2. test_title_omission() - 验证不需要标题时为 null + + + + + + Task 1: 实现标题生成功能 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + RED 阶段 - 测试预期行为： + - test_title_generation: 主题/章节分段生成标题 + - test_title_omission: 论点/观点分段不加标题（title=null） + + GREEN 阶段 - 实现功能： + - VideoSegment.title: Optional[str] = None + - @field_validator 验证标题长度（5-15 字） + - SEGMENTATION_PROMPT 添加标题生成指令 + - 说明 LLM 自主判断是否需要标题 + + REFACTOR 阶段 - 优化代码： + - 优化标题验证逻辑 + + + 在 semantic_engine.py 中实现： + + 1. 更新 VideoSegment 模型： + ```python + class VideoSegment(BaseModel): + title: Optional[str] = Field( + None, + description="分段标题（5-15字），主题/章节类型有标题，观点/对话类型为空" + ) + content: str = Field(..., description="分段内容，保持句子完整性") + start_index: int = Field(..., description="在原文中的起始字符位置") + end_index: int = Field(..., description="在原文中的结束字符位置") + + @field_validator('title') + @classmethod + def validate_title_length(cls, v: Optional[str]) -> Optional[str]: + if v is not None and len(v) > 15: + raise ValueError("标题长度不应超过 15 字") + return v + ``` + + 2. 在 SEGMENTATION_PROMPT 中添加标题指令： + ```python + 【分段要求】 + ... + 6. 为主分/章节类型的分段生成简洁标题（5-15字），论点/观点类型分段不加标题 + + 【输出格式】 + ... + "title": "分段标题（如果此分段不需要标题则设为 null）", + ... + ``` + + 3. 在 Prompt 示例中说明标题判断标准（自主判断） + + 测试验证： + - 主题分段有标题（如「机器学习概述」） + - 过渡性内容标题为 null + - 标题长度不超过 15 字 + + + pytest tests/test_semantic_engine.py::test_title_generation -x + + + - VideoSegment.title 字段定义为 Optional[str] + - @field_validator 验证标题长度（5-15 字） + - SEGMENTATION_PROMPT 包含标题生成指令 + - 说明 LLM 自主判断是否需要标题 + - 测试验证标题生成和省略 + + + + + +- pytest tests/test_semantic_engine.py -v 相关测试通过 +- 标题长度验证生效 +- Prompt 指令清晰（LLM 自主判断） + + + +1. VideoSegment.title 定义为 Optional[str] +2. @field_validator 验证标题长度（5-15 字） +3. SEGMENTATION_PROMPT 包含标题生成指令 +4. 测试验证标题生成和省略 + + + +After completion, create `.planning/phases/13-llm/13-04-SUMMARY.md` + diff --git a/.planning/phases/13-llm/13-05-PLAN.md b/.planning/phases/13-llm/13-05-PLAN.md new file mode 100644 index 0000000..8d03a6c --- /dev/null +++ b/.planning/phases/13-llm/13-05-PLAN.md @@ -0,0 +1,148 @@ +--- +phase: 13 +plan: 05 +type: tdd +wave: 1 +depends_on: [] +files_modified: + - kb_workflow/srt/semantic_engine.py + - tests/test_semantic_engine.py +autonomous: true +requirements: + - SENT-01 + - SENT-02 + - SENT-03 +must_haves: + truths: + - "系统能识别中文字幕的句子边界" + - "句边界检测基于语义停顿，而不仅依赖标点符号" + - "分段位置自然，保持内容的连贯性和可读性" + artifacts: + - path: "kb_workflow/srt/semantic_engine.py" + provides: "中文句边界检测 Prompt 指令" + contains: "SEGMENTATION_PROMPT" + - path: "tests/test_semantic_engine.py" + provides: "中文句边界测试" + min_lines: 60 + key_links: + - from: "SEGMENTATION_PROMPT" + to: "LLM 分段决策" + via: "Prompt 中的句边界指令" + pattern: "句号.*问号.*感叹号.*省略号.*语义停顿" +--- + + +实现中文句边界检测功能 + +目的：让 LLM 在自然停顿处分段，保持中文内容的连贯性和可读性 +输出：SEGMENTATION_PROMPT 中的中文句边界指令 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/phases/13-llm/13-CONTEXT.md +@.planning/phases/13-llm/13-RESEARCH.md + +# User Decision (Locked) +- **中文句边界**: Prompt 中强调 — 在 Prompt 中说明「分段边界应放在自然停顿处（句号、问号、感叹号等标点符号后）」 +- **句边界保护**: 纯 Prompt 约束 — 依赖 LLM 理解，不进行代码后处理 + +# Research Document +Common Pitfall 5: 中文句边界检测依赖标点符号 +What goes wrong: Prompt 中只说「在句号后分段」，但中文还有问号、感叹号、省略号等 +How to avoid: 列举所有常见中文句末标点 + + + + 中文句边界检测 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + Prompt 设计（用户决策 + 研究文档）： + - 列举所有常见中文句末标点（。？！……） + - 强调「自然停顿处」（语义停顿，不仅标点） + - 保持内容连贯性和可读性 + + 测试验证： + - 分段边界在标点符号后 + - 分段位置自然（不会在「等等！」或「真的？」中间截断） + - 保持中文内容的连贯性 + + + 在 SEGMENTATION_PROMPT 中更新句边界指令： + 1. 列举所有中文句末标点（。？！……） + 2. 强调「自然停顿处」和「语义停顿」 + 3. 说明「不仅依赖标点符号」 + + 测试： + 1. test_chinese_sentence_boundary() - 验证句边界检测 + 2. test_semantic_pause_detection() - 验证语义停顿检测 + + + + + + Task 1: 添加中文句边界检测指令 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + RED 阶段 - 测试预期行为： + - test_chinese_sentence_boundary: 分段边界在标点符号后 + - test_semantic_pause_detection: 基于语义停顿（不仅标点） + + GREEN 阶段 - 实现功能： + - SEGMENTATION_PROMPT 列举所有中文句末标点 + - 强调「自然停顿处」和「语义停顿」 + - 说明「不仅依赖标点符号」 + + REFACTOR 阶段 - 优化代码： + - 优化指令措辞（更清晰明确） + + + 更新 SEGMENTATION_PROMPT，优化句边界指令： + + ```python + 【分段要求】 + ... + 4. **重要**：保持句子完整性，分段边界应放在自然停顿处 + - 包括：句号（。）后、问号（？）后、感叹号（！）后、省略号（……）后 + - 基于语义停顿判断，不仅依赖标点符号 + - 保持内容的连贯性和可读性 + ... + ``` + + 测试使用包含以下场景的中文字幕： + - 各种标点符号（。？！……） + - 语义停顿（即使没有标点） + - 连贯性验证（分段后内容自然流畅） + + + pytest tests/test_semantic_engine.py::test_chinese_sentence_boundary -x + + + - SEGMENTATION_PROMPT 列举所有中文句末标点 + - 强调「自然停顿处」和「语义停顿」 + - 说明「不仅依赖标点符号」 + - 测试验证句边界检测效果 + + + + + +- pytest tests/test_semantic_engine.py -v 相关测试通过 +- Prompt 指令清晰明确 +- 列举所有常见中文句末标点 + + + +1. SEGMENTATION_PROMPT 列举所有中文句末标点（。？！……） +2. 强调「自然停顿处」和「语义停顿」 +3. 说明「不仅依赖标点符号」 +4. 测试验证句边界检测效果 + + + +After completion, create `.planning/phases/13-llm/13-05-SUMMARY.md` + diff --git a/.planning/phases/13-llm/13-06-PLAN.md b/.planning/phases/13-llm/13-06-PLAN.md new file mode 100644 index 0000000..41ce086 --- /dev/null +++ b/.planning/phases/13-llm/13-06-PLAN.md @@ -0,0 +1,207 @@ +--- +phase: 13 +plan: 06 +type: execute +wave: 2 +depends_on: + - 13-01 + - 13-02 + - 13-03 + - 13-04 + - 13-05 +files_modified: + - kb_workflow/srt/semantic_engine.py + - tests/test_semantic_engine.py +autonomous: true +requirements: + - STRAT-01 + - STRAT-02 + - STRAT-03 +must_haves: + truths: + - "系统提供可扩展的分段策略架构" + - "Phase 13 实现统一策略（用户决策：无类型区分）" + - "策略架构支持未来添加新策略（扩展性）" + artifacts: + - path: "kb_workflow/srt/semantic_engine.py" + provides: "可扩展的策略架构（Strategy Pattern 预留）" + min_lines: 300 + exports: ["SemanticSegmentationEngine", "SegmentationStrategy"] + - path: "tests/test_semantic_engine.py" + provides: "策略扩展性测试" + min_lines: 50 + key_links: + - from: "SegmentationStrategy" + to: "SemanticSegmentationEngine" + via: "策略模式架构" + pattern: "class.*Strategy.*segment" + - from: "tests" + to: "SegmentationStrategy" + via: "验证策略可扩展性" + pattern: "test.*strategy.*extensibility" +--- + + +实现可扩展的分段策略架构 + +目的：提供策略架构支持未来扩展（Phase 13 实现统一策略，遵守用户决策） +输出：SegmentationStrategy 接口，统一策略实现 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/phases/13-llm/13-CONTEXT.md +@.planning/phases/13-llm/13-RESEARCH.md + +# User Decision (Locked) +- **视频类型策略**: 无类型区分 — 使用统一的分段 Prompt，不针对不同视频类型（知识类/故事类/教程类）设计不同策略 + +# Research Document +Open Question 3: STRAT-01/STRAT-02/STRAT-03 需求的边界 +Recommendation: 在代码结构上预留策略扩展接口（Strategy Pattern），但 Phase 13 只实现统一策略 + + + + 分段策略架构 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + 架构设计（研究文档建议）： + - 预留 Strategy Pattern 接口（SegmentationStrategy） + - Phase 13 实现统一策略（UnifiedSegmentationStrategy） + - 支持未来添加知识类/故事类等特定策略 + + Phase 13 实现（遵守用户决策）： + - 统一策略适用于所有视频类型 + - 视频类型仅用于 Prompt 上下文，不改变分段策略 + + 测试验证： + - 策略接口可扩展 + - 统一策略适用于所有视频类型 + + + 在 semantic_engine.py 中： + 1. 定义 SegmentationStrategy Protocol（接口） + 2. 实现 UnifiedSegmentationStrategy（统一策略） + 3. SemanticSegmentationEngine 使用策略接口 + + 测试： + 1. test_strategy_selection() - 验证策略选择 + 2. test_strategy_extensibility() - 验证策略可扩展性 + + + + + + Task 1: 实现可扩展策略架构 + kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py + + 在 semantic_engine.py 中实现策略架构： + + 1. 定义 SegmentationStrategy Protocol： + ```python + from typing import Protocol, List + from kb_workflow.srt.parser import Segment + + class SegmentationStrategy(Protocol): + """分段策略接口""" + + def segment( + self, + segments: List[Segment], + metadata: dict + ) -> List[str]: + """对字幕分段进行语义分段 + + Args: + segments: 字幕分段列表 + metadata: 视频元数据 + + Returns: + 段落文本列表 + """ + ... + ``` + + 2. 实现 UnifiedSegmentationStrategy（统一策略）： + ```python + class UnifiedSegmentationStrategy: + """统一分段策略 + + 适用于所有视频类型（知识类、故事类、访谈类等）。 + 视频类型仅用于 Prompt 上下文，不改变分段策略。 + + 遵守用户决策：无类型区分，使用统一 Prompt。 + """ + + def __init__(self, ai_client: Optional[AIClientProtocol] = None): + self.ai_client = ai_client + # Lazy initialization... + + def segment( + self, + segments: List[Segment], + metadata: dict + ) -> List[str]: + # 调用 LLM 进行语义分段 + # 使用统一的 SEGMENTATION_PROMPT + ... + ``` + + 3. 更新 SemanticSegmentationEngine： + ```python + class SemanticSegmentationEngine: + def __init__( + self, + strategy: Optional[SegmentationStrategy] = None, + fallback_segmenter: Optional['SemanticSegmenter'] = None + ): + # 默认使用统一策略 + self.strategy = strategy or UnifiedSegmentationStrategy() + self.fallback_segmenter = fallback_segmenter or SemanticSegmenter() + + def segment( + self, + segments: List[Segment], + metadata: dict + ) -> List[str]: + return self.strategy.segment(segments, metadata) + ``` + + 测试验证： + - 策略接口可扩展（可实现新策略） + - 统一策略适用于所有视频类型 + - 策略切换不影响功能 + + + pytest tests/test_semantic_engine.py::test_strategy_extensibility -x + + + - SegmentationStrategy Protocol 定义完成 + - UnifiedSegmentationStrategy 实现完成 + - SemanticSegmentationEngine 使用策略接口 + - 测试验证策略可扩展性 + + + + + +- pytest tests/test_semantic_engine.py -v 相关测试通过 +- 策略接口清晰（Protocol 定义） +- 统一策略符合用户决策（无类型区分） +- 架构支持未来扩展 + + + +1. SegmentationStrategy Protocol 定义完成 +2. UnifiedSegmentationStrategy 实现完成 +3. SemanticSegmentationEngine 使用策略接口 +4. 测试验证策略可扩展性 + + + +After completion, create `.planning/phases/13-llm/13-06-SUMMARY.md` + diff --git a/.planning/phases/13-llm/13-07-PLAN.md b/.planning/phases/13-llm/13-07-PLAN.md new file mode 100644 index 0000000..32d01b8 --- /dev/null +++ b/.planning/phases/13-llm/13-07-PLAN.md @@ -0,0 +1,222 @@ +--- +phase: 13 +plan: 07 +type: execute +wave: 2 +depends_on: + - 13-01 + - 13-02 + - 13-03 + - 13-04 + - 13-05 + - 13-06 +files_modified: + - kb_workflow/pipeline/processors/srt.py + - tests/test_srt_processor_integration.py +autonomous: true +requirements: + - CONFIG-03 +must_haves: + truths: + - "SRTProcessor 支持启用/禁用 LLM 语义分段" + - "启用时使用 SemanticSegmentationEngine，禁用时使用规则分段" + - "知乎/文章平台继续使用 AnalyzeProcessor，不受影响" + artifacts: + - path: "kb_workflow/pipeline/processors/srt.py" + provides: "SRTProcessor 集成 LLM 分段" + min_lines: 350 + exports: ["SRTProcessor.__init__", "SRTProcessor.process"] + - path: "tests/test_srt_processor_integration.py" + provides: "SRTProcessor 集成测试" + min_lines: 100 + key_links: + - from: "SRTProcessor.__init__" + to: "SemanticSegmentationEngine" + via: "enable_semantic_segmentation 参数" + pattern: "enable_semantic.*segmentation" + - from: "SRTProcessor.process" + to: "SemanticSegmentationEngine.segment" + via: "条件分支选择分段方式" + pattern: "if.*semantic.*else.*rule" + - from: "Pipeline.run" + to: "AnalyzeProcessor/SRTProcessor" + via: "平台路由逻辑（保持不变）" + pattern: "platform.*bilibili.*srt" +--- + + +集成 SemanticSegmentationEngine 到 SRTProcessor + +目的：让 SRTProcessor 支持 LLM 语义分段（可选），保持向后兼容 +输出：更新的 SRTProcessor，集成测试 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/phases/13-llm/13-CONTEXT.md +@.planning/phases/13-llm/13-RESEARCH.md + +# User Decision (Locked) +- **SRTProcessor 集成**: 配置开关控制 — 新增 `enable_semantic_segmentation` 参数，True 时用 LLM 分段，False 时保留规则分段作为后备选项 +- **现有 SemanticSegmenter**: 完全替代 — 新代码完全替代旧代码，SemanticSegmenter 被 SemanticSegmentationEngine 取代 + +# Existing Code (from srt.py) +```python +class SRTProcessor(BaseProcessor): + def __init__( + self, + state_manager: Optional[WorkflowStateManager] = None, + enable_correction: bool = True + ): + ... + self.segmenter = SemanticSegmenter() # 规则分段 +``` + + + + + Task 1: 集成 SemanticSegmentationEngine 到 SRTProcessor + kb_workflow/pipeline/processors/srt.py, tests/test_srt_processor_integration.py + + 更新 SRTProcessor，集成 LLM 语义分段： + + 1. 在 __init__ 中添加 `enable_semantic_segmentation` 参数： + ```python + def __init__( + self, + state_manager: Optional[WorkflowStateManager] = None, + enable_correction: bool = True, + enable_semantic_segmentation: bool = False # 新增参数 + ): + super().__init__(state_manager) + self.enable_correction = enable_correction + self.enable_semantic_segmentation = enable_semantic_segmentation + + # 初始化分段器 + if enable_semantic_segmentation: + try: + from kb_workflow.srt.semantic_engine import SemanticSegmentationEngine + from kb_workflow.deep_analyzer import SimpleAIClient + + ai_client = SimpleAIClient() + if ai_client.api_key: + self.segmenter = SemanticSegmentationEngine(ai_client=ai_client) + logger.info("Semantic segmentation enabled") + else: + logger.info("AI API key not configured, using rule-based segmenter") + self.segmenter = SemanticSegmenter() + except Exception as e: + logger.warning(f"Failed to initialize semantic engine: {e}, using rule-based segmenter") + self.segmenter = SemanticSegmenter() + else: + self.segmenter = SemanticSegmenter() + + # 初始化纠错器（保持不变） + ... + ``` + + 2. 更新 process() 方法中的分段调用： + ```python + # Step 2: 语义分段 + logger.info("Segmenting subtitles into paragraphs") + if self.enable_semantic_segmentation and isinstance(self.segmenter, SemanticSegmentationEngine): + # LLM 语义分段 + paragraphs = self.segmenter.segment(segments, metadata=metadata) + else: + # 规则分段 + paragraphs = self.segmenter.segment(segments) + logger.info(f"Generated {len(paragraphs)} paragraphs") + ``` + + 3. 更新 _generate_markdown() 以支持带标题的分段： + ```python + def _generate_markdown( + self, + output_file: Path, + metadata: Dict[str, Any], + paragraphs: List[str], # 或 List[VideoSegment] + tags: List[str] + ) -> None: + ... + # 如果 paragraphs 包含 VideoSegment（LLM 分段结果） + if paragraphs and hasattr(paragraphs[0], 'title'): + for seg in paragraphs: + if seg.title: + content_parts.append(f"## {seg.title}") + content_parts.append(seg.content) + content_parts.append("") + else: + # 规则分段（纯文本） + content_parts.append("## 内容") + content_parts.append("") + for para in paragraphs: + content_parts.append(para) + content_parts.append("") + ... + ``` + + 4. 更新 SRTInput/Output Schema（如果需要）： + - 考虑是否需要添加 semantic_segmentation_enabled 字段 + + 5. 创建集成测试： + ```python + # tests/test_srt_processor_integration.py + def test_srt_processor_semantic_mode(): + """测试 SRTProcessor 语义分段模式""" + # mock AI client + # enable_semantic_segmentation=True + # 验证调用 SemanticSegmentationEngine + + def test_srt_processor_rule_based_mode(): + """测试 SRTProcessor 规则分段模式""" + # enable_semantic_segmentation=False + # 验证使用 SemanticSegmenter + + def test_srt_processor_semantic_fallback(): + """测试 AI 不可用时降级到规则分段""" + # AI client 无效 + # 验证降级到 SemanticSegmenter + ``` + + 6. 确保 Pipeline 平台路由逻辑不受影响（Phase 12 已实现）： + - B站视频使用 SRTProcessor + - 知乎/文章继续使用 AnalyzeProcessor + - 不修改 Pipeline.run() 中的路由逻辑 + + + pytest tests/test_srt_processor_integration.py::test_srt_processor_semantic_mode -x + + + - SRTProcessor 支持 enable_semantic_segmentation 参数 + - 启用时使用 SemanticSegmentationEngine + - 禁用时使用 SemanticSegmenter（向后兼容） + - AI 不可用时自动降级到规则分段 + - _generate_markdown() 支持带标题的分段 + - 集成测试验证所有场景 + - 平台路由逻辑不受影响（知乎/文章继续使用 AnalyzeProcessor） + + + + + +- pytest tests/test_srt_processor_integration.py -v 全部通过 +- pytest tests/test_srt_processor.py -v 现有测试不回归 +- 平台路由逻辑不受影响 +- 向后兼容（enable_semantic_segmentation=False 时行为不变） + + + +1. SRTProcessor 支持 enable_semantic_segmentation 参数 +2. 启用时使用 LLM 分段，禁用时使用规则分段 +3. AI 不可用时自动降级 +4. 集成测试验证所有场景 +5. 平台路由逻辑不受影响 + + + +After completion, create `.planning/phases/13-llm/13-07-SUMMARY.md` +