---
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. 测试验证边界检测功能