docs(13): capture phase context

2026-03-22 00:14:06 +08:00
parent ea2d6e4740
commit 6ae74f423d
1 changed files with 118 additions and 0 deletions
@@ -0,0 +1,118 @@
+# Phase 13: 核心 LLM 分段功能 - Context
+
+**Gathered:** 2026-03-22
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+实现基于 LLM 的智能语义分段，替代现有的基于时间+字符长度的简单规则分段。
+
+**核心能力：**
+- 视频类型识别（知识类、故事类、教程类等）— 虽不区分策略，但用于 Prompt 上下文
+- 语义边界检测 — 在话题转换处创建分段
+- 主题标题生成 — 为主题/章节类型分段生成标题
+- 内容完整性保护 — 不在句子中间截断，保持论点完整
+- 中文句边界检测 — 在自然停顿处分段
+
+**不包括：**
+- 降级策略、重试机制（Phase 14 - 鲁棒性）
+- 分块处理、缓存（Phase 14 - 成本控制）
+- 输出格式优化（Phase 15 - 兼容性）
+
+</domain>
+
+<decisions>
+## Implementation 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 模型的字段验证规则细节
+- 错误处理日志的具体级别和内容
+- 目标分段数的计算公式（如何根据视频长度动态调整）
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+
+- **kb_workflow/srt/segmenter.py** — 现有 SemanticSegmenter 类（规则分段：基于时间间隔 3 秒和段落长度 500 字符）— 将被 SemanticSegmentationEngine 替代
+- **kb_workflow/srt/corrector.py** — ASRCorrector 类（LLM 调用模式，批量处理，降级策略）— 可参考其 LazyAIClient 初始化模式
+- **kb_workflow/srt/parser.py** — parse_srt_file() 函数，Segment 数据类 — 解析 SRT 文件获取字幕分段列表
+- **kb_workflow/deep_analyzer/** — SimpleAIClient 类，支持 zhipu/openai/minimax 三种提供商 — LLM 调用的统一接口
+- **kb_workflow/pipeline/processors/srt.py** — SRTProcessor 类，process() 方法 — LLM 分段功能的集成点
+
+### Established Patterns
+
+- **Lazy AI Client 初始化**: ASRCorrector 模式 — 在 __init__ 中尝试创建 SimpleAIClient，如果 api_key 为空则跳过，AI 不可用时优雅降级
+- **AIClientProtocol**: 定义了 generate(prompt, max_tokens, disable_reasoning) 方法 — LLM 调用的标准接口
+- **BaseProcessor 模式**: 状态检查、幂等执行、错误记录 — 所有处理器继承的基础模式
+- **Pydantic v2 验证**: 用于 StepInput/StepOutput 验证 — 可复用于 LLM 响应验证
+
+### Integration Points
+
+- **SRTProcessor.process()**: 在解析 SRT 文件后，调用语义分段引擎生成段落列表
+- **SRTProcessor.__init__()**: 新增 `enable_semantic_segmentation` 参数，控制是否启用 LLM 分段
+- **SimpleAIClient.generate()**: LLM 分段引擎通过此方法调用 AI，需传入 max_tokens 和 disable_reasoning 参数
+- **Markdown 生成**: _generate_markdown() 需要更新以支持带标题的分段（H2 标题 + 内容）
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- **两阶段 vs 一阶段**: 虽然研究文档建议两阶段（先检测视频类型，再进行分段），但用户选择了无类型区分的统一策略，因此只需一次 LLM 调用进行分段
+- **Prompt 设计要点**:
+  - 强调语义完整性优先于数量目标
+  - 明确句边界应放在标点符号后
+  - 标题简洁（5-15 字）
+  - LLM 自主判断是否需要标题
+- **数量引导示例**: "将内容分为 5-8 个段落，根据语义完整性灵活调整数量"
+- **长度建议示例**: "每个段落约 1000-2000 字，但为保持语义完整性可以突破此范围"
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- **视频类型特定策略** — 用户选择统一策略，不针对不同视频类型设计不同 Prompt
+- **句边界代码后处理** — 用户选择纯 Prompt 约束，不进行代码层面的边界修正
+- **并列结构特殊处理** — 用户选择不特别指定，让 LLM 自然判断
+
+</deferred>
+
+---
+
+*Phase: 13-llm*
+*Context gathered: 2026-03-22*