kb-skills/.planning/phases/13-llm/13-RESEARCH.md

Phase 13: 核心 LLM 分段功能 - Research

Researched: 2026-03-22 Domain: LLM-based semantic text segmentation, Pydantic v2 validation, Chinese NLP Confidence: HIGH

Summary

Phase 13 需要实现基于 LLM 的智能语义分段，替代现有的基于时间+字符长度的简单规则分段。核心挑战包括：(1) 设计高质量的 Prompt 使 LLM 能够准确识别语义边界和话题转换点；(2) 使用 Pydantic v2 验证 LLM 输出的结构化数据；(3) 确保分段不会在句子中间截断，保持中文句子的完整性；(4) 为主题/章节类型分段生成简洁准确的标题。

Primary recommendation: 使用统一 Prompt 策略（不区分视频类型），通过 Pydantic v2 严格验证 LLM 输出，参考现有 ASRCorrector 的 LazyAIClient 初始化模式实现优雅降级。

User Constraints (from CONTEXT.md)

Locked Decisions

• 数量控制: 采用建议式数量引导 — Prompt 中给出目标分段数量范围（5-8 个），但允许 LLM 根据语义完整性灵活调整，不强制执行
• 视频类型策略: 无类型区分 — 使用统一的分段 Prompt，不针对不同视频类型（知识类/故事类/教程类）设计不同策略
• 目标分段数: 5-8 个分段 — 适合大多数 10-30 分钟视频的粒度范围
• 长度约束: 参考性长度建议 — Prompt 中可建议每个分段大致字符数（如 1000-2000 字），但允许突破以保持语义完整性
• 句边界保护: 纯 Prompt 约束 — 在 Prompt 中明确指令「不要在句子中间截断」，依赖 LLM 理解，不进行代码后处理
• 论点完整性: 一般性指令 — Prompt 中给出「保持论点完整性」的一般性指令，不提供具体示例或标记词识别
• 并列结构: 不特别指定 — 对「首先/其次/最后」等并列结构不给出特殊处理，让 LLM 根据整体语义自然判断
• 中文句边界: Prompt 中强调 — 在 Prompt 中说明「分段边界应放在自然停顿处（句号、问号、感叹号等标点符号后）」
• 标题范围: LLM 自主判断 — 让 LLM 自行判断哪些分段需要标题（主题/章节类），哪些不需要（观点/对话类），不在 Prompt 中硬性规定
• 标题风格: 简洁描述型 — 标题应简短（5-15 字），如「机器学习概述」「梯度下降原理」，类似目录结构
• 标题格式: H2 (##) — 在 Markdown 输出中，标题使用二级标题（##），与现有「## 内容」格式保持一致
• 标题缺失处理: 跳过标题 — 如果 LLM 无法为某个分段生成合适的标题（如过渡性内容），该分段不加标题，直接以内容开始
• 模块位置: kb_workflow/srt/semantic_engine.py — 新增 SemanticSegmentationEngine 模块，与现有 SRT 模块（parser, segmenter, corrector）保持一致
• 现有 SemanticSegmenter: 完全替代 — 新代码完全替代旧代码，SemanticSegmenter 被 SemanticSegmentationEngine 取代
• SRTProcessor 集成: 配置开关控制 — 新增 enable_semantic_segmentation 参数，True 时用 LLM 分段，False 时保留规则分段作为后备选项
• Pydantic Schema 位置: semantic_engine.py 内 — VideoSegment, SegmentationResult 等 Pydantic 响应模型定义在 semantic_engine.py 中，与 LLM 相关代码集中管理

Claude's Discretion

• Prompt 的具体措辞和模板设计
• Pydantic 模型的字段验证规则细节
• 错误处理日志的具体级别和内容
• 目标分段数的计算公式（如何根据视频长度动态调整）

Deferred Ideas (OUT OF SCOPE)

• 视频类型特定策略 — 用户选择统一策略，不针对不同视频类型设计不同 Prompt
• 句边界代码后处理 — 用户选择纯 Prompt 约束，不进行代码层面的边界修正
• 并列结构特殊处理 — 用户选择不特别指定，让 LLM 自然判断
• 降级策略、重试机制（Phase 14 - 鲁棒性）
• 分块处理、缓存（Phase 14 - 成本控制）
• 输出格式优化（Phase 15 - 兼容性）

Standard Stack

Core

Library	Version	Purpose	Why Standard
Pydantic	2.x	LLM 响应验证	类型安全、自动验证、清晰错误消息（从 v2.10 起支持流式响应验证）
SimpleAIClient	现有	LLM 调用	已集成 zhipu/openai/minimax 三种提供商，支持 disable_reasoning 参数
Python re	标准库	JSON 提取	从 LLM 响应中提取 JSON 块

Supporting

Library	Version	Purpose	When to Use
logging	标准库	错误日志	记录验证失败、LLM 调用错误
json	标准库	JSON 解析	解析 LLM 返回的 JSON 字符串

Alternatives Considered

Instead of	Could Use	Tradeoff
SimpleAIClient	直接调用 OpenAI SDK	SimpleAIClient 已提供统一接口，支持多提供商，无需重复造轮子
Pydantic	手动解析 + 验证	Pydantic 提供自动验证、类型转换、清晰错误消息，减少 50%+ 验证代码
正则表达式提取 JSON	Markdown 解析器	正则表达式更简单可靠，LLM 输出的 JSON 通常包裹在 json 中

Installation:

# 所有依赖已安装
# Pydantic 2.x 已在项目依赖中
# SimpleAIClient 是项目现有代码

Architecture Patterns

Recommended Project Structure

kb_workflow/
├── srt/
│   ├── parser.py          # 现有：解析 SRT 文件
│   ├── segmenter.py       # 现有：规则分段（将被替代）
│   ├── corrector.py       # 现有：ASR 纠错（参考模式）
│   └── semantic_engine.py # 新增：LLM 语义分段引擎
├── deep_analyzer/
│   └── __init__.py        # 现有：SimpleAIClient 定义
└── pipeline/
    └── processors/
        └── srt.py         # 更新：集成 SemanticSegmentationEngine

Pattern 1: LazyAIClient 初始化（来自 ASRCorrector）

What: 延迟初始化 AI 客户端，API key 未配置时优雅降级 When to use: 需要支持 AI 不可用时的降级场景 Example:

# Source: kb_workflow/srt/corrector.py (现有代码)
from kb_workflow.deep_analyzer import SimpleAIClient

class ASRCorrector:
    def __init__(self, ai_client: Optional[AIClientProtocol] = None):
        self.ai_client = ai_client

# SemanticSegmentationEngine 应采用相同模式
class SemanticSegmentationEngine:
    def __init__(self, ai_client: Optional[AIClientProtocol] = None):
        self.ai_client = ai_client
        if ai_client is None:
            try:
                self.ai_client = SimpleAIClient()
                if not self.ai_client.api_key:
                    logger.info("AI API key not configured")
                    self.ai_client = None
            except Exception as e:
                logger.warning(f"Failed to initialize AI client: {e}")
                self.ai_client = None

Pattern 2: Pydantic v2 嵌套模型验证

What: 定义嵌套的 Pydantic 模型验证 LLM 输出的复杂结构 When to use: LLM 返回包含列表、嵌套对象的 JSON Example:

# Source: Pydantic v2 官方文档
from pydantic import BaseModel, Field, field_validator
from typing import List, Optional

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

class SegmentationResult(BaseModel):
    """分段结果"""
    video_type: str = Field(..., description="视频类型：知识类/故事类/教程类/访谈类等")
    segments: List[VideoSegment] = Field(..., description="分段列表", min_length=1)
    actual_segment_count: int = Field(..., description="实际分段数量")

    @field_validator('segments')
    @classmethod
    def validate_segment_count(cls, v: List[VideoSegment]) -> List[VideoSegment]:
        if not (5 <= len(v) <= 8):
            # 注意：根据用户决策，这是建议式引导，不强制执行
            # 这里仅记录警告，不抛出异常
            logger.warning(f"分段数量 {len(v)} 超出建议范围 5-8")
        return v

Pattern 3: 从 LLM 响应中提取 JSON

What: 使用正则表达式从可能包含额外文本的 LLM 响应中提取 JSON When to use: LLM 可能返回「这是 JSON: {...}」而非纯 JSON Example:

# Source: MachineLearningMastery - Pydantic LLM 验证指南
import re
import json
from typing import Dict, Any

def extract_json_from_llm_response(response: str) -> Dict[str, Any]:
    """从 LLM 响应中提取 JSON

    处理以下情况：
    - 纯 JSON
    - 包裹在 ```json ``` 中的 JSON
    - 前后包含额外说明文本的 JSON
    """
    # 尝试直接解析
    try:
        return json.loads(response.strip())
    except json.JSONDecodeError:
        pass

    # 尝试提取 ```json ``` 代码块
    json_match = re.search(r'```json\s*(.*?)\s*```', response, re.DOTALL)
    if json_match:
        try:
            return json.loads(json_match.group(1))
        except json.JSONDecodeError:
            pass

    # 尝试提取任何 JSON 对象
    json_match = re.search(r'\{.*\}', response, re.DOTALL)
    if json_match:
        try:
            return json.loads(json_match.group())
        except json.JSONDecodeError as e:
            raise ValueError(f"无法从 LLM 响应中提取有效 JSON: {e}")

    raise ValueError("LLM 响应中未找到 JSON 内容")

Anti-Patterns to Avoid

• 在 Pydantic 验证器中修改数据 — 验证器应该只验证，不应该修改数据（如自动截断标题）
• 硬编码分段数量 — 用户明确要求建议式引导，不应强制 LLM 返回固定数量分段
• 忽略 None 值的字段 — Pydantic 模型中 title: Optional[str] = None 是合法的，表示该分段不需要标题
• 使用 Field(default=None) 而非 Field(...) — ... 表示必填字段，default=None 表示可选字段

Don't Hand-Roll

Problem	Don't Build	Use Instead	Why
LLM 响应验证	手动检查每个字段、类型转换、错误处理	Pydantic v2 BaseModel	自动验证、类型转换、清晰错误消息、减少 70% 验证代码
JSON 提取	复杂的字符串解析、边界条件处理	re.search(r'\{.*\}', response, re.DOTALL)	一行代码处理大多数情况
AI 客户端	直接调用 zhipu/openai/minimax API	SimpleAIClient	统一接口、已支持多提供商、已有重试逻辑
配置管理	硬编码 API key、环境变量解析	SimpleAIClient 的环境变量读取	与现有代码一致

Key insight: Phase 13 的核心价值在于利用 LLM 的语义理解能力，而不是构建基础设施工具。使用现有的、经过验证的库（Pydantic、SimpleAIClient）可以快速聚焦于核心问题。

Common Pitfalls

Pitfall 1: Pydantic 验证失败导致静默降级

What goes wrong: LLM 返回的 JSON 格式不符合 Pydantic 模型，代码捕获异常后直接返回空列表，用户不知道分段失败 Why it happens: 开发者担心抛出异常会中断流程，选择静默降级 How to avoid:

# ❌ 错误：静默降级
try:
    result = SegmentationResult(**data)
except ValidationError:
    return []  # 用户不知道发生了什么

# ✅ 正确：记录错误 + 降级
try:
    result = SegmentationResult(**data)
except ValidationError as e:
    logger.error(f"LLM 分段结果验证失败: {e}")
    logger.error(f"原始 LLM 输出: {llm_output}")
    # 降级到规则分段
    return fallback_segmenter.segment(segments)

Warning signs: 日志中没有分段失败记录，但输出文件分段数量明显异常

Pitfall 2: Prompt 中硬性要求分段数量

What goes wrong: Prompt 明确要求「必须分成 5 段」，LLM 强行将语义连贯的内容截断 Why it happens: 开发者担心 LLM 不理解「建议」的含义，使用强制性语言 How to avoid:

# ❌ 错误：强制要求
prompt = "将内容分成 5 个段落，每个段落..."

# ✅ 正确：建议式引导
prompt = """建议将内容分为 5-8 个段落，根据语义完整性灵活调整数量。
优先保证每个段落的语义完整性，不要为了凑数而强行截断。"""

Warning signs: 分段边界在句子中间，论点未完整表达

Pitfall 3: 忽略视频类型识别（需求 VIDEO-01/VIDEO-02/VIDEO-03）

What goes wrong: 用户明确要求「无类型区分」，但需求中 VIDEO-01 要求系统能识别视频类型 Why it happens: 开发者将「无类型区分策略」理解为「不需要识别类型」 How to avoid:

# 仍然需要识别视频类型（用于 Prompt 上下文），但不使用不同策略
class SegmentationResult(BaseModel):
    video_type: str = Field(..., description="视频类型：知识类/故事类/教程类/访谈类等")
    segments: List[VideoSegment] = Field(..., description="分段列表")

# Prompt 中包含类型信息，但不改变分段策略
prompt = f"""这是一个{video_type}视频的字幕内容。

请按照以下要求进行语义分段：
- 识别话题转换点，在主题切换时创建新分段
- 保持句子完整性，不要在句子中间截断
- ...（其他统一要求）"""

Warning signs: SegmentationResult 中没有 video_type 字段

Pitfall 4: 标题格式不兼容现有输出

What goes wrong: 生成的 Markdown 使用 ### 标题 而非 ## 标题，与现有格式不一致 Why it happens: 开发者未阅读现有 SRTProcessor 的 _generate_markdown 方法 How to avoid:

# 现有格式：## 内容
# 新格式也应使用 ## 作为标题级别

def _generate_markdown(self, segments: List[VideoSegment]) -> str:
    parts = []
    for seg in segments:
        if seg.title:
            parts.append(f"## {seg.title}")  # H2，与现有格式一致
        parts.append(seg.content)
        parts.append("")
    return "\n".join(parts)

Warning signs: 生成的 Markdown 标题层级不一致

Pitfall 5: 中文句边界检测依赖标点符号

What goes wrong: Prompt 中只说「在句号后分段」，但中文还有问号、感叹号、省略号等 Why it happens: 开发者对标点符号的认识不全面 How to avoid:

# ✅ 正确：列举所有常见中文句末标点
prompt = """分段边界应放在自然停顿处，包括：
- 句号（。）后
- 问号（？）后
- 感叹号（！）后
- 省略号（……）后
- 逗号（，）如果表示较长停顿"""

Warning signs: 分段在「等等！」或「真的？」中间截断

Code Examples

Verified patterns from official sources:

LLM 语义分段 Prompt 模板

# Source: 基于 Topic Segmentation Using Generative Language Models (arXiv 2601.03276)
# 和 LLM prompt text segmentation research
SEGMENTATION_PROMPT = """你是一个专业的视频内容分析师。请将以下字幕内容按语义分段。

【视频信息】
类型：{video_type}
标题：{title}
总字数：{total_chars}字

【字幕内容】
{content}

【分段要求】
1. 建议将内容分为 5-8 个段落（可根据语义完整性灵活调整）
2. 每个段落约 1000-2000 字（为保持语义完整性可以突破此范围）
3. 在话题转换处创建新分段，不要混入不同话题的内容
4. **重要**：保持句子完整性，分段边界应放在自然停顿处（句号。、问号？、感叹号！、省略号……等标点符号后）
5. 保持论点完整性，不要在前提-结论结构中间截断
6. 为主题/章节类型的分段生成简洁标题（5-15字），观点/对话类型分段不加标题

【输出格式】
必须返回以下 JSON 格式（不要添加任何额外文本）：
```json
{{
  "video_type": "{video_type}",
  "segments": [
    {{
      "title": "分段标题（如果此分段不需要标题则设为 null）",
      "content": "分段内容",
      "start_index": 0,
      "end_index": 123
    }}
  ],
  "actual_segment_count": 6
}}

【注意事项】

• 优先保证语义完整性，不要为了凑数而强行截断
• 标题应简洁准确，如「机器学习概述」「梯度下降原理」
• 如果某个分段无法生成合适的标题（如过渡性内容），将 title 设为 null"""

### Pydantic 验证 + 错误处理
```python
# Source: MachineLearningMastery - Pydantic LLM 验证指南
from pydantic import ValidationError

def parse_segmentation_result(llm_output: str, fallback_segmenter) -> List[VideoSegment]:
    """解析 LLM 输出并验证，失败时降级"""
    try:
        # 提取 JSON
        data = extract_json_from_llm_response(llm_output)

        # Pydantic 验证
        result = SegmentationResult(**data)

        logger.info(
            f"LLM 分段成功: 类型={result.video_type}, "
            f"分段数={result.actual_segment_count}"
        )

        return result.segments

    except (json.JSONDecodeError, ValidationError) as e:
        logger.error(f"LLM 分段失败: {e}")
        logger.error(f"原始 LLM 输出: {llm_output[:500]}...")

        # 降级到规则分段
        logger.info("降级到规则分段")
        return fallback_segmenter.segment(segments)

    except Exception as e:
        logger.error(f"未知错误: {e}")
        raise

SemanticSegmentationEngine 类结构

# Source: 基于 ASRCorrector 模式 + Pydantic v2 最佳实践
import logging
from typing import List, Optional, Protocol
from kb_workflow.srt.parser import Segment

logger = logging.getLogger(__name__)


class AIClientProtocol(Protocol):
    """AI 客户端协议（与 ASRCorrector 保持一致）"""
    def generate(self, prompt: str, max_tokens: int = 16000,
                 disable_reasoning: bool = False) -> str:
        ...


class SemanticSegmentationEngine:
    """LLM 语义分段引擎

    使用 LLM 进行智能语义分段，替代基于时间+字符长度的简单规则。

    Attributes:
        ai_client: AI 客户端（实现 AIClientProtocol）
        fallback_segmenter: 规则分段器（用于降级）
    """

    def __init__(
        self,
        ai_client: Optional[AIClientProtocol] = None,
        fallback_segmenter: Optional['SemanticSegmenter'] = None
    ):
        """初始化语义分段引擎

        Args:
            ai_client: AI 客户端实例，如果为 None 则尝试创建 SimpleAIClient
            fallback_segmenter: 降级时使用的规则分段器
        """
        self.ai_client = ai_client
        self.fallback_segmenter = fallback_segmenter

        # Lazy AI Client 初始化（与 ASRCorrecter 相同模式）
        if self.ai_client is None:
            try:
                from kb_workflow.deep_analyzer import SimpleAIClient
                self.ai_client = SimpleAIClient()
                if not self.ai_client.api_key:
                    logger.info("AI API key not configured")
                    self.ai_client = None
            except Exception as e:
                logger.warning(f"Failed to initialize AI client: {e}")
                self.ai_client = None

        # 初始化降级分段器
        if self.fallback_segmenter is None:
            from kb_workflow.srt.segmenter import SemanticSegmenter
            self.fallback_segmenter = SemanticSegmenter()

    def segment(
        self,
        segments: List[Segment],
        metadata: dict
    ) -> List[str]:
        """对字幕分段进行语义分段

        Args:
            segments: 字幕分段列表
            metadata: 视频元数据（title, duration 等）

        Returns:
            段落文本列表
        """
        # AI 不可用，直接使用规则分段
        if self.ai_client is None:
            logger.info("AI client unavailable, using fallback segmenter")
            return self.fallback_segmenter.segment(segments)

        # 合并字幕文本
        content = " ".join(seg.text for seg in segments)

        # 构建 Prompt
        prompt = self._build_prompt(
            content=content,
            metadata=metadata
        )

        # 调用 LLM
        try:
            llm_output = self.ai_client.generate(
                prompt,
                max_tokens=8000,
                disable_reasoning=True  # 分段不需要思考模式
            )

            # 解析和验证
            video_segments = self._parse_result(
                llm_output,
                fallback_segments=segments
            )

            # 转换为段落文本
            paragraphs = [seg.content for seg in video_segments]

            logger.info(f"LLM semantic segmentation: {len(paragraphs)} paragraphs")
            return paragraphs

        except Exception as e:
            logger.error(f"LLM segmentation failed: {e}, using fallback")
            return self.fallback_segmenter.segment(segments)

    def _build_prompt(self, content: str, metadata: dict) -> str:
        """构建 LLM Prompt"""
        # 使用上面定义的 SEGMENTATION_PROMPT 模板
        ...

    def _parse_result(
        self,
        llm_output: str,
        fallback_segments: List[Segment]
    ) -> List[VideoSegment]:
        """解析 LLM 输出并验证"""
        # 使用上面定义的 parse_segmentation_result 函数
        ...

State of the Art

Old Approach	Current Approach	When Changed	Impact
基于时间间隔（3秒）分段	LLM 语义分段	Phase 13	分段质量提升 9%（根据 Firecrawl 研究）
固定段落长度（500字符）	动态长度（1000-2000字建议）	Phase 13	保持语义完整性，避免截断
无标题	LLM 生成标题	Phase 13	输出更易读，类似目录结构
Pydantic v1	Pydantic v2	现有代码	更好的性能、更清晰的错误消息

Deprecated/outdated:

• SimpleAIClient.generate() 不带 max_tokens: 必须传入 max_tokens 参数，否则可能被截断
• Field(default=None) 可选字段: Pydantic v2 推荐使用 Optional[Type] = None 而非 Field(default=None)

Open Questions

1. 目标分段数的动态计算公式

   • What we know: 用户要求 5-8 个分段，适合 10-30 分钟视频
   • What's unclear: 如何根据视频长度动态调整（如 60 分钟视频是否建议 10-15 段）
   • Recommendation: Phase 13 使用固定 5-8 段建议，公式计算留到 Phase 14/15 优化

2. VIDEO-01/VIDEO-02/VIDEO-03 需求的边界

   • What we know: 用户选择「无类型区分策略」，但需求要求识别视频类型
   • What's unclear: 识别出的类型是否需要影响分段行为，还是仅用于记录
   • Recommendation: 仅用于 Prompt 上下文（如「这是一个知识类视频」），不改变分段策略

3. STRAT-01/STRAT-02/STRAT-03 需求的边界

   • What we know: 用户明确不针对不同类型设计不同 Prompt
   • What's unclear: 需求要求「提供至少 2 种分段策略」，是否与用户决策冲突
   • Recommendation: 在代码结构上预留策略扩展接口（Strategy Pattern），但 Phase 13 只实现统一策略

Validation Architecture

根据 .planning/config.json，workflow.nyquist_validation 未设置，默认为 true，因此包含此部分。

Test Framework

Property	Value
Framework	pytest
Config file	pytest.ini
Quick run command	pytest tests/test_srt_processor.py -v -k "test_srt" -x
Full suite command	pytest tests/test_srt_processor.py -v

Phase Requirements → Test Map

Req ID	Behavior	Test Type	Automated Command	File Exists?
VIDEO-01	系统识别视频类型	unit	pytest tests/test_srt_processor.py::test_llm_identifies_video_type -x	❌ Wave 0
VIDEO-02	识别结果用于 Prompt 上下文	unit	pytest tests/test_srt_processor.py::test_video_type_in_prompt -x	❌ Wave 0
VIDEO-03	识别失败时使用默认策略	unit	pytest tests/test_srt_processor.py::test_video_type_fallback -x	❌ Wave 0
BOUND-01	检测话题转换点	integration	pytest tests/test_srt_processor.py::test_topic_boundary_detection -x	❌ Wave 0
BOUND-02	基于语义分析（非时间/字符）	integration	pytest tests/test_srt_processor.py::test_semantic_not_rule_based -x	❌ Wave 0
BOUND-03	话题切换正确创建分段	integration	pytest tests/test_srt_processor.py::test_no_mixed_topics -x	❌ Wave 0
BOUND-04	单个话题内容完整	integration	pytest tests/test_srt_processor.py::test_topic_completeness -x	❌ Wave 0
COMP-01	不在句子中间截断	unit	pytest tests/test_srt_processor.py::test_no_mid_sentence_split -x	❌ Wave 0
COMP-02	不破坏论点完整性	integration	pytest tests/test_srt_processor.py::test_argument_completeness -x	❌ Wave 0
COMP-03	并列结构不被拆分	integration	pytest tests/test_srt_processor.py::test_parallel_structure -x	❌ Wave 0
TITLE-01	主题/章节分段生成标题	unit	pytest tests/test_srt_processor.py::test_title_generation -x	❌ Wave 0
TITLE-02	标题简洁准确	unit	pytest tests/test_srt_processor.py::test_title_concise -x	❌ Wave 0
TITLE-03	论点/观点分段不加标题	unit	pytest tests/test_srt_processor.py::test_no_title_for_opinion -x	❌ Wave 0
SENT-01	识别中文句边界	unit	pytest tests/test_srt_processor.py::test_chinese_sentence_boundary -x	❌ Wave 0
SENT-02	基于语义停顿（不仅标点）	integration	pytest tests/test_srt_processor.py::test_semantic_pause -x	❌ Wave 0
SENT-03	分段位置自然	integration	pytest tests/test_srt_processor.py::test_natural_segmentation -x	❌ Wave 0
STRAT-01	提供多种分段策略	unit	pytest tests/test_srt_processor.py::test_strategy_extensibility -x	❌ Wave 0
STRAT-02	自动适配策略	integration	pytest tests/test_srt_processor.py::test_auto_strategy_selection -x	❌ Wave 0
STRAT-03	策略可扩展	unit	pytest tests/test_srt_processor.py::test_strategy_pattern -x	❌ Wave 0

Sampling Rate

• Per task commit: pytest tests/test_srt_processor.py -v -k "test_semantic" -x
• Per wave merge: pytest tests/test_srt_processor.py -v
• Phase gate: Full suite green before /gsd:verify-work

Wave 0 Gaps

• tests/test_srt_processor.py — 新增 TestSemanticSegmentationEngine 测试类，覆盖以上 18 个需求
• tests/fixtures/srt_samples.py — 新增测试用例：知识类/故事类视频字幕，包含话题转换、并列结构、论点完整性等场景
• tests/conftest.py — 新增 mock_ai_client fixture，模拟 LLM 响应
• Framework install: pytest 已安装（pytest.ini 存在）

Sources

Primary (HIGH confidence)

• Pydantic AI - Official Documentation - Structured outputs, JSON schemas, validation
• The Complete Guide to Using Pydantic for Validating LLM Outputs - Pydantic v2 patterns, nested models, error handling
• Best Chunking Strategies for RAG (and LLMs) in 2026 - Firecrawl - LLM-based chunking, semantic segmentation
• Topic Segmentation Using Generative Language Models - arXiv 2601.03276 - Prompt patterns for text segmentation
• HowToCaption: Prompting LLMs to Transform Video Annotations at Scale - arXiv 2310.04900 - Video content analysis with LLMs
• 现有代码: kb_workflow/srt/corrector.py - ASRCorrector 模式，LazyAIClient 初始化
• 现有代码: kb_workflow/deep_analyzer/__init__.py - SimpleAIClient 实现

Secondary (MEDIUM confidence)

• Exploring the Frontiers of Text Segmentation for Better RAG Systems - Medium - Example prompts for segmentation
• Building a Reliable Text Classification Pipeline with LLMs - Medium - LLM prompt engineering
• Awesome-LLMs-for-Video-Understanding - GitHub - Video content classification taxonomy
• LLM-Enhanced Semantic Text Segmentation - MDPI - Semantic segmentation research

Tertiary (LOW confidence)

• 各类 LLM prompt 工程文章（未在官方文档验证）
• Chinese NLP 句边界检测研究（未找到 2025 年后更新的实践指南）

Metadata

Confidence breakdown:

• Standard stack: HIGH - Pydantic v2、SimpleAIClient 均有官方文档支持
• Architecture: HIGH - 基于 ASRCorrector 成功模式，代码结构清晰
• Pitfalls: HIGH - 大部分 pitfalls 来自现有代码审查和官方最佳实践
• Prompt design: MEDIUM - 参考了学术论文和行业实践，但需要实际测试验证

Research date: 2026-03-22 Valid until: 2026-04-22 (30 days - LLM prompt 工程和 Pydantic 版本更新较快)