docs(13): create phase 13 plan (7 plans)

This commit is contained in:
2026-03-22 00:21:30 +08:00
parent da4b2d563a
commit 2bcaf05d52
8 changed files with 1269 additions and 3 deletions
+12 -3
View File
@@ -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*
+170
View File
@@ -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"
---
<objective>
实现视频类型识别功能,用于 Prompt 上下文
目的:让 LLM 了解视频类型(知识类/故事类等)以优化分段质量,但不针对不同类型使用不同策略(统一 Prompt)
输出:VideoSegment 和 SegmentationResult Pydantic 模型,视频类型识别逻辑
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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
```
</context>
<feature>
<name>视频类型识别</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
定义 Pydantic 模型验证 LLM 输出:
- VideoSegment: title (可选), content, start_index, end_index
- SegmentationResult: video_type, segments[], actual_segment_count
视频类型识别:
- 从元数据推断类型(基于标题、标签、分类)
- 默认类型为"知识类"(最常见)
- 类型用于 Prompt 上下文,不改变分段策略
LLM 调用失败时:
- 返回默认 SegmentationResult(video_type="知识类", 使用规则分段)
</behavior>
<implementation>
在 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() - 验证默认类型处理
</implementation>
</feature>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 创建 Pydantic 模型和类型推断</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
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 阶段 - 优化代码:
- 提取视频类型映射常量
- 优化类型推断逻辑
</behavior>
<action>
创建 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 包含"影视"推断为"故事类"
- 元数据为空时返回"知识类"(默认)
</action>
<verify>
<automated>pytest tests/test_semantic_engine.py::test_video_type_detection -x</automated>
</verify>
<done>
- Pydantic 模型定义完成,包含字段验证
- _infer_video_type() 能从元数据正确推断类型
- _build_prompt() 包含视频类型上下文
- 三个测试全部通过
</done>
</task>
</tasks>
<verification>
- pytest tests/test_semantic_engine.py -v 全部通过
- 代码符合 PEP 8 规范
- Pydantic 模型通过类型检查
</verification>
<success_criteria>
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)
</success_criteria>
<output>
After completion, create `.planning/phases/13-llm/13-01-SUMMARY.md`
</output>
+184
View File
@@ -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"
---
<objective>
实现语义边界检测功能
目的:让 LLM 识别话题转换点,在不同主题之间创建分段边界
输出:SEGMENTATION_PROMPT 模板,_parse_result 解析方法
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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 进行语义分析。
</context>
<feature>
<name>语义边界检测</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
Prompt 设计:
- 明确指令「在话题转换处创建新分段,不要混入不同话题的内容」
- 强调「基于语义完整性,而非时间或字符长度」
- 建议分段数量 5-8 个(可灵活调整)
- 每段约 1000-2000 字(为保持语义完整性可突破)
LLM 输出解析:
- 提取 JSON 格式的分段结果
- 验证每个分段的 start_index 和 end_index
- 验证分段内容不重叠且覆盖原文
边界检测质量:
- 话题切换时正确创建边界
- 单个话题内容保持完整
</behavior>
<implementation>
在 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() - 验证单个话题完整性
</implementation>
</feature>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 实现语义边界检测 Prompt 和解析</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
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 指令的清晰度
</behavior>
<action>
在 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 响应,验证:
- 话题转换点正确识别
- 分段内容不重叠
- 覆盖完整原文
</action>
<verify>
<automated>pytest tests/test_semantic_engine.py::test_topic_boundary_detection -x</automated>
</verify>
<done>
- SEGMENTATION_PROMPT 包含话题转换检测指令
- extract_json_from_llm_response() 能从各种格式提取 JSON
- _parse_result() 能正确解析和验证 LLM 输出
- 测试验证边界检测质量
</done>
</task>
</tasks>
<verification>
- pytest tests/test_semantic_engine.py -v 相关测试通过
- Prompt 指令清晰明确
- JSON 解析健壮(处理多种格式)
</verification>
<success_criteria>
1. SEGMENTATION_PROMPT 包含话题转换检测指令
2. extract_json_from_llm_response() 能处理纯 JSON、代码块、混合文本
3. _parse_result() 使用 Pydantic 验证 LLM 输出
4. 测试验证边界检测功能
</success_criteria>
<output>
After completion, create `.planning/phases/13-llm/13-02-SUMMARY.md`
</output>
+143
View File
@@ -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: "不要在句子中间截断.*保持论点完整性"
---
<objective>
实现内容完整性保护功能
目的:通过 Prompt 约束确保分段不破坏句子和论点完整性
输出:SEGMENTATION_PROMPT 中的完整性保护指令
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/phases/13-llm/13-CONTEXT.md
@.planning/phases/13-llm/13-RESEARCH.md
# User Decision (Locked)
- **句边界保护**: 纯 Prompt 约束 — 在 Prompt 中明确指令「不要在句子中间截断」,依赖 LLM 理解,不进行代码后处理
- **论点完整性**: 一般性指令 — Prompt 中给出「保持论点完整性」的一般性指令,不提供具体示例或标记词识别
- **并列结构**: 不特别指定 — 对「首先/其次/最后」等并列结构不给出特殊处理,让 LLM 根据整体语义自然判断
</context>
<feature>
<name>内容完整性保护</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
Prompt 约束(用户决策:纯 Prompt,无代码后处理):
- 「不要在句子中间截断」
- 「分段边界应放在自然停顿处(句号。、问号?、感叹号!、省略号……等标点符号后)」
- 「保持论点完整性,不要在前提-结论结构中间截断」
- 对并列结构不特别指定(让 LLM 自然判断)
测试验证:
- 分段边界在标点符号后
- 论点结构完整(前提-结论不被拆分)
- 并列结构保持完整
</behavior>
<implementation>
在 SEGMENTATION_PROMPT 中添加完整性保护指令:
1. 明确句边界要求(列举所有中文句末标点)
2. 添加论点完整性指令
3. 不添加并列结构特殊处理(按用户决策)
测试:
1. test_sentence_boundary_protection() - 验证句边界保护
2. test_argument_completeness() - 验证论点完整性
</implementation>
</feature>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 添加内容完整性保护指令</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
RED 阶段 - 测试预期行为:
- test_sentence_boundary_protection: 分段边界在标点符号后
- test_argument_completeness: 论点结构完整
GREEN 阶段 - 实现功能:
- SEGMENTATION_PROMPT 添加句边界指令
- SEGMENTATION_PROMPT 添加论点完整性指令
- 不添加并列结构特殊处理(遵守用户决策)
REFACTOR 阶段 - 优化代码:
- 优化指令措辞(更清晰明确)
</behavior>
<action>
更新 SEGMENTATION_PROMPT,添加完整性保护指令:
```python
【分段要求】
...
4. **重要**:保持句子完整性,分段边界应放在自然停顿处(句号。、问号?、感叹号!、省略号……等标点符号后)
5. 保持论点完整性,不要在前提-结论结构中间截断
```
注意:不添加并列结构特殊处理(遵守用户决策:让 LLM 自然判断)
测试使用包含以下场景的字幕:
- 句子中间不应截断(如「机器学习是...」不应被拆开)
- 论点完整性(如「因此...所以...」不应被拆开)
- 并列结构(如「首先...其次...最后...」应保持完整)
</action>
<verify>
<automated>pytest tests/test_semantic_engine.py::test_sentence_boundary_protection -x</automated>
</verify>
<done>
- SEGMENTATION_PROMPT 包含句边界保护指令
- SEGMENTATION_PROMPT 包含论点完整性指令
- 不包含并列结构特殊处理(遵守用户决策)
- 测试验证完整性保护效果
</done>
</task>
</tasks>
<verification>
- pytest tests/test_semantic_engine.py -v 相关测试通过
- Prompt 指令清晰明确
- 不包含并列结构特殊处理(符合用户决策)
</verification>
<success_criteria>
1. SEGMENTATION_PROMPT 包含句边界保护指令(列举所有标点符号)
2. SEGMENTATION_PROMPT 包含论点完整性指令
3. 测试验证完整性保护效果
</success_criteria>
<output>
After completion, create `.planning/phases/13-llm/13-03-SUMMARY.md`
</output>
+183
View File
@@ -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"
---
<objective>
实现主题标题生成功能
目的:让 LLM 为主题/章节类型分段生成简洁准确的标题,论点/观点分段不加标题
输出:VideoSegment.title 字段和验证,Prompt 中的标题生成指令
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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 无法为某个分段生成合适的标题(如过渡性内容),该分段不加标题,直接以内容开始
</context>
<feature>
<name>主题标题生成</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
Prompt 设计(用户决策):
- 让 LLM 自主判断哪些分段需要标题
- 标题简洁(5-15字),如「机器学习概述」
- 过渡性内容可将 title 设为 null
Pydantic 验证:
- title: Optional[str] = None
- 标题长度验证(不超过 15 字)
测试验证:
- 主题/章节分段生成标题
- 标题简洁准确
- 论点/观点分段标题为 null
</behavior>
<implementation>
在 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
</implementation>
</feature>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 实现标题生成功能</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
RED 阶段 - 测试预期行为:
- test_title_generation: 主题/章节分段生成标题
- test_title_omission: 论点/观点分段不加标题(title=null)
GREEN 阶段 - 实现功能:
- VideoSegment.title: Optional[str] = None
- @field_validator 验证标题长度(5-15 字)
- SEGMENTATION_PROMPT 添加标题生成指令
- 说明 LLM 自主判断是否需要标题
REFACTOR 阶段 - 优化代码:
- 优化标题验证逻辑
</behavior>
<action>
在 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 字
</action>
<verify>
<automated>pytest tests/test_semantic_engine.py::test_title_generation -x</automated>
</verify>
<done>
- VideoSegment.title 字段定义为 Optional[str]
- @field_validator 验证标题长度(5-15 字)
- SEGMENTATION_PROMPT 包含标题生成指令
- 说明 LLM 自主判断是否需要标题
- 测试验证标题生成和省略
</done>
</task>
</tasks>
<verification>
- pytest tests/test_semantic_engine.py -v 相关测试通过
- 标题长度验证生效
- Prompt 指令清晰(LLM 自主判断)
</verification>
<success_criteria>
1. VideoSegment.title 定义为 Optional[str]
2. @field_validator 验证标题长度(5-15 字)
3. SEGMENTATION_PROMPT 包含标题生成指令
4. 测试验证标题生成和省略
</success_criteria>
<output>
After completion, create `.planning/phases/13-llm/13-04-SUMMARY.md`
</output>
+148
View File
@@ -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: "句号.*问号.*感叹号.*省略号.*语义停顿"
---
<objective>
实现中文句边界检测功能
目的:让 LLM 在自然停顿处分段,保持中文内容的连贯性和可读性
输出:SEGMENTATION_PROMPT 中的中文句边界指令
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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: 列举所有常见中文句末标点
</context>
<feature>
<name>中文句边界检测</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
Prompt 设计(用户决策 + 研究文档):
- 列举所有常见中文句末标点(。?!……)
- 强调「自然停顿处」(语义停顿,不仅标点)
- 保持内容连贯性和可读性
测试验证:
- 分段边界在标点符号后
- 分段位置自然(不会在「等等!」或「真的?」中间截断)
- 保持中文内容的连贯性
</behavior>
<implementation>
在 SEGMENTATION_PROMPT 中更新句边界指令:
1. 列举所有中文句末标点(。?!……)
2. 强调「自然停顿处」和「语义停顿」
3. 说明「不仅依赖标点符号」
测试:
1. test_chinese_sentence_boundary() - 验证句边界检测
2. test_semantic_pause_detection() - 验证语义停顿检测
</implementation>
</feature>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 添加中文句边界检测指令</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
RED 阶段 - 测试预期行为:
- test_chinese_sentence_boundary: 分段边界在标点符号后
- test_semantic_pause_detection: 基于语义停顿(不仅标点)
GREEN 阶段 - 实现功能:
- SEGMENTATION_PROMPT 列举所有中文句末标点
- 强调「自然停顿处」和「语义停顿」
- 说明「不仅依赖标点符号」
REFACTOR 阶段 - 优化代码:
- 优化指令措辞(更清晰明确)
</behavior>
<action>
更新 SEGMENTATION_PROMPT,优化句边界指令:
```python
【分段要求】
...
4. **重要**:保持句子完整性,分段边界应放在自然停顿处
- 包括:句号(。)后、问号(?)后、感叹号(!)后、省略号(……)后
- 基于语义停顿判断,不仅依赖标点符号
- 保持内容的连贯性和可读性
...
```
测试使用包含以下场景的中文字幕:
- 各种标点符号(。?!……)
- 语义停顿(即使没有标点)
- 连贯性验证(分段后内容自然流畅)
</action>
<verify>
<automated>pytest tests/test_semantic_engine.py::test_chinese_sentence_boundary -x</automated>
</verify>
<done>
- SEGMENTATION_PROMPT 列举所有中文句末标点
- 强调「自然停顿处」和「语义停顿」
- 说明「不仅依赖标点符号」
- 测试验证句边界检测效果
</done>
</task>
</tasks>
<verification>
- pytest tests/test_semantic_engine.py -v 相关测试通过
- Prompt 指令清晰明确
- 列举所有常见中文句末标点
</verification>
<success_criteria>
1. SEGMENTATION_PROMPT 列举所有中文句末标点(。?!……)
2. 强调「自然停顿处」和「语义停顿」
3. 说明「不仅依赖标点符号」
4. 测试验证句边界检测效果
</success_criteria>
<output>
After completion, create `.planning/phases/13-llm/13-05-SUMMARY.md`
</output>
+207
View File
@@ -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"
---
<objective>
实现可扩展的分段策略架构
目的:提供策略架构支持未来扩展(Phase 13 实现统一策略,遵守用户决策)
输出:SegmentationStrategy 接口,统一策略实现
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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 只实现统一策略
</context>
<feature>
<name>分段策略架构</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<behavior>
架构设计(研究文档建议):
- 预留 Strategy Pattern 接口(SegmentationStrategy)
- Phase 13 实现统一策略(UnifiedSegmentationStrategy)
- 支持未来添加知识类/故事类等特定策略
Phase 13 实现(遵守用户决策):
- 统一策略适用于所有视频类型
- 视频类型仅用于 Prompt 上下文,不改变分段策略
测试验证:
- 策略接口可扩展
- 统一策略适用于所有视频类型
</behavior>
<implementation>
在 semantic_engine.py 中:
1. 定义 SegmentationStrategy Protocol(接口)
2. 实现 UnifiedSegmentationStrategy(统一策略)
3. SemanticSegmentationEngine 使用策略接口
测试:
1. test_strategy_selection() - 验证策略选择
2. test_strategy_extensibility() - 验证策略可扩展性
</implementation>
</feature>
<tasks>
<task type="auto">
<name>Task 1: 实现可扩展策略架构</name>
<files>kb_workflow/srt/semantic_engine.py, tests/test_semantic_engine.py</files>
<action>
在 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)
```
测试验证:
- 策略接口可扩展(可实现新策略)
- 统一策略适用于所有视频类型
- 策略切换不影响功能
</action>
<verify>
<automated>pytest tests/test_semantic_engine.py::test_strategy_extensibility -x</automated>
</verify>
<done>
- SegmentationStrategy Protocol 定义完成
- UnifiedSegmentationStrategy 实现完成
- SemanticSegmentationEngine 使用策略接口
- 测试验证策略可扩展性
</done>
</task>
</tasks>
<verification>
- pytest tests/test_semantic_engine.py -v 相关测试通过
- 策略接口清晰(Protocol 定义)
- 统一策略符合用户决策(无类型区分)
- 架构支持未来扩展
</verification>
<success_criteria>
1. SegmentationStrategy Protocol 定义完成
2. UnifiedSegmentationStrategy 实现完成
3. SemanticSegmentationEngine 使用策略接口
4. 测试验证策略可扩展性
</success_criteria>
<output>
After completion, create `.planning/phases/13-llm/13-06-SUMMARY.md`
</output>
+222
View File
@@ -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"
---
<objective>
集成 SemanticSegmentationEngine 到 SRTProcessor
目的:让 SRTProcessor 支持 LLM 语义分段(可选),保持向后兼容
输出:更新的 SRTProcessor,集成测试
</objective>
<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.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() # 规则分段
```
</context>
<tasks>
<task type="auto">
<name>Task 1: 集成 SemanticSegmentationEngine 到 SRTProcessor</name>
<files>kb_workflow/pipeline/processors/srt.py, tests/test_srt_processor_integration.py</files>
<action>
更新 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() 中的路由逻辑
</action>
<verify>
<automated>pytest tests/test_srt_processor_integration.py::test_srt_processor_semantic_mode -x</automated>
</verify>
<done>
- SRTProcessor 支持 enable_semantic_segmentation 参数
- 启用时使用 SemanticSegmentationEngine
- 禁用时使用 SemanticSegmenter(向后兼容)
- AI 不可用时自动降级到规则分段
- _generate_markdown() 支持带标题的分段
- 集成测试验证所有场景
- 平台路由逻辑不受影响(知乎/文章继续使用 AnalyzeProcessor)
</done>
</task>
</tasks>
<verification>
- pytest tests/test_srt_processor_integration.py -v 全部通过
- pytest tests/test_srt_processor.py -v 现有测试不回归
- 平台路由逻辑不受影响
- 向后兼容(enable_semantic_segmentation=False 时行为不变)
</verification>
<success_criteria>
1. SRTProcessor 支持 enable_semantic_segmentation 参数
2. 启用时使用 LLM 分段,禁用时使用规则分段
3. AI 不可用时自动降级
4. 集成测试验证所有场景
5. 平台路由逻辑不受影响
</success_criteria>
<output>
After completion, create `.planning/phases/13-llm/13-07-SUMMARY.md`
</output>