From 56039c5956f1be7599600f95cc29cd29af56e9bd Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Thu, 19 Mar 2026 23:25:43 +0800 Subject: [PATCH] docs(12-srt-simplifier): create phase 12 plans --- .planning/ROADMAP.md | 12 +- .../phases/12-srt-simplifier/12-01-PLAN.md | 313 ++++++++++++++++++ .../phases/12-srt-simplifier/12-02-PLAN.md | 292 ++++++++++++++++ 3 files changed, 613 insertions(+), 4 deletions(-) create mode 100644 .planning/phases/12-srt-simplifier/12-01-PLAN.md create mode 100644 .planning/phases/12-srt-simplifier/12-02-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 51e0c69..c5fe9ab 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -147,18 +147,22 @@ Plans: **Plans**: 2 plans (pending) Plans: -- [ ] 12-01-PLAN.md — SRT 处理器实现（解析、去时间戳、分段、纠正） -- [ ] 12-02-PLAN.md — 集成与测试，移除 DeepAnalyzer +- [ ] 12-01-PLAN.md — SRT 处理模块（parser、segmenter、corrector）和 SRTProcessor 实现 +- [ ] 12-02-PLAN.md — Pipeline 集成、平台路由、测试验证 **Key Decisions:** -- (to be determined during planning) +- SRT 处理模块独立于 DeepAnalyzer，位于 kb_workflow/srt/ +- 语义分段基于简单规则（时间间隔 + 长度限制），不依赖 LLM +- ASR 纠错可选，AI 不可用时返回原文 +- B 站视频使用 SRTProcessor，知乎/文章继续使用 AnalyzeProcessor +- DeepAnalyzer 保留但添加弃用警告（仅针对 B 站视频） --- ## Progress **Execution Order:** -Phases execute in numeric order: 1 → 2 → ... → 10 → 11 +Phases execute in numeric order: 1 → 2 → ... → 10 → 11 → 12 | Phase | Milestone | Plans Complete | Status | Completed | |-------|-----------|----------------|--------|-----------| diff --git a/.planning/phases/12-srt-simplifier/12-01-PLAN.md b/.planning/phases/12-srt-simplifier/12-01-PLAN.md new file mode 100644 index 0000000..b681773 --- /dev/null +++ b/.planning/phases/12-srt-simplifier/12-01-PLAN.md @@ -0,0 +1,313 @@ +--- +phase: 12-srt-simplifier +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - kb_workflow/pipeline/processors/srt.py + - kb_workflow/pipeline/schemas.py + - kb_workflow/srt/__init__.py + - kb_workflow/srt/parser.py + - kb_workflow/srt/segmenter.py + - kb_workflow/srt/corrector.py + - tests/test_srt_processor.py +autonomous: true +requirements: + - SRT-01 + - SRT-02 + - SRT-03 + - SRT-04 + - OUT-01 + - OUT-02 + - OUT-04 +must_haves: + truths: + - "SRT 文件能被正确解析为结构化数据" + - "字幕时间戳被移除，只保留纯文本" + - "文本按语义主题自动分段" + - "明显的语音识别错误被 LLM 纠正" + - "生成结构化的 Markdown 文件" + artifacts: + - path: "kb_workflow/srt/parser.py" + provides: "SRT 格式解析" + contains: "def parse_srt" + - path: "kb_workflow/srt/segmenter.py" + provides: "语义分段" + contains: "class SemanticSegmenter" + - path: "kb_workflow/srt/corrector.py" + provides: "LLM 纠错" + contains: "class ASRCorrector" + - path: "kb_workflow/pipeline/processors/srt.py" + provides: "Pipeline 处理器" + exports: ["SRTProcessor"] + key_links: + - from: "kb_workflow/pipeline/processors/srt.py" + to: "kb_workflow/srt/parser.py" + via: "parse_srt function" + pattern: "parse_srt" + - from: "kb_workflow/pipeline/processors/srt.py" + to: "kb_workflow/srt/segmenter.py" + via: "SemanticSegmenter class" + pattern: "SemanticSegmenter" + - from: "kb_workflow/pipeline/processors/srt.py" + to: "kb_workflow/srt/corrector.py" + via: "ASRCorrector class" + pattern: "ASRCorrector" +--- + + +创建 SRT 字幕处理模块，实现字幕解析、去时间戳、语义分段和 LLM 纠错功能。 + +Purpose: 将 B 站字幕文件转换为易读的 Markdown 文档，保留核心内容但移除时间戳等格式信息。 +Output: SRT 处理模块（parser, segmenter, corrector）和 SRTProcessor 处理器。 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +## 现有架构 + +### Pipeline 处理器模式（from base.py） +```python +class BaseProcessor(ABC): + STEP_NAME: str + + def __init__(self, state_manager: Optional[WorkflowStateManager] = None): + self.settings = get_settings() + self.state_manager = state_manager + + @abstractmethod + async def process(self, input_data: StepInput) -> StepOutput: + pass +``` + +### ASRProcessor 输出格式（from asr.py） +```python +class ASROutput(StepOutput): + tool: Literal["subtitle", "whisper", "whisper-diarization"] + has_subtitle: bool + output_files: Dict[str, str] # {txt, srt, json} + segments: List[Dict[str, Any]] # [{id, start, end, text}] + text: str # 完整文本 + duration_seconds: float + speakers: Optional[List[str]] +``` + +### SRT 文件格式示例 +``` +1 +00:00:00,000 --> 00:00:05,000 +第一句字幕内容 + +2 +00:00:05,000 --> 00:00:10,000 +第二句字幕内容 +``` + +### DeepAnalyzer AI 客户端模式（from deep_analyzer/__init__.py） +```python +class SimpleAIClient: + def __init__(self, api_key: str, provider: str, model: str, base_url: str): + self.api_key = api_key or os.environ.get("AI_API_KEY", "") + self.provider = provider or os.environ.get("AI_PROVIDER", "") + self.model = model or os.environ.get("AI_MODEL", "glm-5") + self.base_url = base_url or os.environ.get("AI_BASE_URL", "") + + def generate(self, prompt: str, max_tokens: int = 16000) -> str: + # 支持 openai, zhipu, minimax 提供商 +``` + + + + + + Task 1: 创建 SRT 解析器模块 + kb_workflow/srt/__init__.py, kb_workflow/srt/parser.py, tests/test_srt_processor.py + + - Test 1: 标准的 SRT 格式能被正确解析为 Segment 列表 + - Test 2: 包含特殊字符的字幕能正确处理 + - Test 3: 空文件或格式错误的文件抛出 ValueError + + + 创建 SRT 解析模块: + + 1. 创建 `kb_workflow/srt/__init__.py` 导出公共接口 + 2. 创建 `kb_workflow/srt/parser.py`: + - `@dataclass class Segment`: id, start_time, end_time, text + - `def parse_srt(content: str) -> List[Segment]`: 解析 SRT 格式 + - `def parse_srt_file(file_path: Path) -> List[Segment]`: 从文件解析 + - 使用正则表达式匹配 SRT 块: `(\d+)\n(\d{2}:\d{2}:\d{2},\d{3}) --> (\d{2}:\d{2}:\d{2},\d{3})\n(.*?)(?=\n\n|\Z)` + 3. 创建单元测试文件 `tests/test_srt_processor.py`，测试解析功能 + + 注意：时间戳格式为 `HH:MM:SS,mmm`，需要正确解析。 + + + pytest tests/test_srt_processor.py::test_parse_srt -v + + + - SRT 文件能被解析为 List[Segment] + - 每个 Segment 包含 id, start_time, end_time, text + - 单元测试通过 + + + + + Task 2: 创建语义分段器 + kb_workflow/srt/segmenter.py, tests/test_srt_processor.py + + - Test 1: 连续短句被合并为段落 + - Test 2: 主题变化时自动分段 + - Test 3: 单个段落不超过 500 字符 + + + 创建语义分段模块: + + 1. 创建 `kb_workflow/srt/segmenter.py`: + - `class SemanticSegmenter`: 语义分段器 + - `def segment(self, segments: List[Segment], max_paragraph_chars: int = 500) -> List[str]`: + 将字幕分段转换为语义段落 + - 分段策略: + a. 基于简单启发式规则（可选未来用 LLM 增强） + b. 空行/长停顿（>3秒）作为分段点 + c. 段落长度限制（max_paragraph_chars） + - 返回段落文本列表（已去除时间戳） + + 2. 更新测试文件添加分段测试 + + 不使用 LLM 进行分段判断（简化实现），仅基于时间和长度规则。 + + + pytest tests/test_srt_processor.py::test_segment -v + + + - 字幕分段被合并为语义段落 + - 时间戳被移除 + - 段落长度合理（不超过 max_paragraph_chars） + + + + + Task 3: 创建 ASR 纠错器 + kb_workflow/srt/corrector.py, tests/test_srt_processor.py + + - Test 1: 明显的同音字错误被纠正 + - Test 2: 上下文相关的错误被纠正 + - Test 3: 正确文本不被过度修改 + + + 创建 ASR 纠错模块: + + 1. 创建 `kb_workflow/srt/corrector.py`: + - `class ASRCorrector`: ASR 纠错器 + - 复用 `SimpleAIClient`（from deep_analyzer） + - `def correct(self, text: str) -> str`: 纠正文本中的语音识别错误 + - Prompt 设计: + ``` + 你是一个文本校对专家。以下是语音识别生成的字幕，可能包含识别错误。 + 请只纠正明显的错误（如同音字、漏字、错字），不要改变原意和风格。 + + 原文： + {text} + + 纠正后的文本（只输出纠正后的文本，不要解释）： + ``` + - 分批处理长文本（每批 5000 字符） + + 2. 更新测试文件添加纠错测试 + + 注意：纠错是可选功能，如果 AI 不可用则返回原文。 + + + pytest tests/test_srt_processor.py::test_correct -v + + + - ASR 纠错器能纠正明显的语音识别错误 + - AI 不可用时返回原文 + - 长文本被分批处理 + + + + + Task 4: 创建 SRTProcessor 和 Markdown 生成 + kb_workflow/pipeline/processors/srt.py, kb_workflow/pipeline/schemas.py, kb_workflow/srt/__init__.py + + 创建 SRTProcessor 处理器和输出 Schema: + + 1. 更新 `kb_workflow/pipeline/schemas.py`: + - `class SRTInput(StepInput)`: srt_file, metadata_file, output_file, content_type + - `class SRTOutput(StepOutput)`: output_file, paragraphs, tags, corrected + + 2. 创建 `kb_workflow/pipeline/processors/srt.py`: + - `class SRTProcessor(BaseProcessor)`: SRT 处理器 + - `STEP_NAME = "srt"` + - `async def process(self, input_data: SRTInput) -> SRTOutput`: + a. 解析 SRT 文件（调用 parser.parse_srt_file） + b. 语义分段（调用 segmenter.segment） + c. ASR 纠错（调用 corrector.correct，可选） + d. 生成 Markdown 文件 + + 3. Markdown 输出格式: + ```markdown + --- + title: "视频标题" + date: 2026-03-19 + author: 作者名 + platform: bilibili + duration: 12:34 + bvid: BV1xx... + url: https://... + tags: ["标签1", "标签2"] + --- + + ## 摘要 + [LLM 生成的简短摘要，可选] + + ## 内容 + 段落1... + + 段落2... + + ... + ``` + + 4. 更新 `kb_workflow/srt/__init__.py` 导出所有公共接口 + + + pytest tests/test_srt_processor.py::test_srt_processor -v + + + - SRTProcessor 能处理 SRT 文件生成 Markdown + - 输出包含 YAML frontmatter（元数据和标签） + - 处理器遵循 BaseProcessor 模式 + + + + + + +- 所有单元测试通过 +- SRT 解析器能处理标准格式 +- 语义分段器输出合理段落 +- ASR 纠错器能调用 LLM +- SRTProcessor 生成有效 Markdown + + + +1. `parse_srt` 能将 SRT 内容解析为 Segment 列表 +2. `SemanticSegmenter.segment` 能将字幕转换为语义段落 +3. `ASRCorrector.correct` 能纠正语音识别错误 +4. `SRTProcessor` 能生成包含元数据的 Markdown 文件 +5. 所有测试通过（pytest tests/test_srt_processor.py） + + + +After completion, create `.planning/phases/12-srt-simplifier/12-01-SUMMARY.md` + diff --git a/.planning/phases/12-srt-simplifier/12-02-PLAN.md b/.planning/phases/12-srt-simplifier/12-02-PLAN.md new file mode 100644 index 0000000..520d159 --- /dev/null +++ b/.planning/phases/12-srt-simplifier/12-02-PLAN.md @@ -0,0 +1,292 @@ +--- +phase: 12-srt-simplifier +plan: 02 +type: execute +wave: 2 +depends_on: + - 12-01 +files_modified: + - kb_workflow/pipeline/pipeline.py + - kb_workflow/pipeline/schemas.py + - kb_workflow/cli.py + - kb_workflow/deep_analyzer/__init__.py + - tests/test_bilibili_pipeline.py +autonomous: true +requirements: + - OUT-03 + - SCOPE-01 + - SCOPE-02 +must_haves: + truths: + - "B 站视频处理流程使用 SRTProcessor 替代 AnalyzeProcessor" + - "知乎等其他平台处理器保持不变" + - "DeepAnalyzer 不再被 B 站视频处理调用" + - "kb-workflow process 命令正常工作" + artifacts: + - path: "kb_workflow/pipeline/pipeline.py" + provides: "Pipeline 编排" + contains: "bilibili pipeline steps" + - path: "kb_workflow/cli.py" + provides: "CLI 入口" + contains: "process_command" + key_links: + - from: "kb_workflow/cli.py" + to: "kb_workflow/pipeline/pipeline.py" + via: "Pipeline class" + pattern: "Pipeline" + - from: "kb_workflow/pipeline/pipeline.py" + to: "kb_workflow/pipeline/processors/srt.py" + via: "platform check" + pattern: "SRTProcessor" +--- + + +将 SRTProcessor 集成到 Pipeline，修改 B 站处理流程使用简化处理，移除 DeepAnalyzer 调用，同时保持知乎等其他平台处理不变。 + +Purpose: 实现需求 SCOPE-01（移除深度分析）和 SCOPE-02（仅针对 B 站），确保 B 站视频生成简化的 Markdown 文档。 +Output: 修改后的 Pipeline 和 CLI，集成测试通过。 + + + +@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md +@/home/starmen1265/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +## 现有 Pipeline 流程（from cli.py） + +```python +processors = [ + ParseProcessor(), + DownloadProcessor(), + ASRProcessor(), + AnalyzeProcessor(), # B 站视频：深度分析（需移除） + ArchiveProcessor(), +] + +config = PipelineConfig( + steps=["parse", "download", "asr", "analyze", "archive"], +) +``` + +## Pipeline 条件逻辑（from pipeline.py） + +```python +# 现有平台相关逻辑示例 +text_content_types = {"article", "answer", "zhuanlan", "question"} +if step_name == "asr" and parsed.content_type in text_content_types: + logger.info(f"Skipping ASR for text content type: {parsed.content_type}") + continue +``` + +## B 站 vs 知乎处理差异 + +| 平台 | 内容类型 | ASR | 分析 | +|------|----------|-----|------| +| bilibili | video | 需要 | 简化（SRTProcessor） | +| bilibili | article | 跳过 | AnalyzeProcessor（保留） | +| zhihu | answer | 跳过 | AnalyzeProcessor（保留） | +| zhihu | zhuanlan | 跳过 | AnalyzeProcessor（保留） | + +## 需要修改的文件 + +1. `pipeline.py`: 根据平台类型选择处理器 +2. `cli.py`: 更新处理器列表 +3. `schemas.py`: 添加必要的 Input/Output Schema + + + + + + + Task 1: 修改 Pipeline 支持平台特定处理流程 + kb_workflow/pipeline/pipeline.py, kb_workflow/pipeline/schemas.py + + 修改 Pipeline 支持平台特定处理流程: + + 1. 更新 `kb_workflow/pipeline/schemas.py`: + - 确认 `SRTInput` 和 `SRTOutput` 已在 12-01 中添加 + - 添加 `SRTInput` 到 imports + + 2. 修改 `kb_workflow/pipeline/pipeline.py` 的 `run` 方法: + - 在 step 处理循环中，检测 B 站视频 + analyze 步骤的情况 + - B 站视频（platform="bilibili", content_type="video"）时: + - 跳过 "analyze" 步骤 + - 执行 "srt" 步骤（使用 SRTProcessor） + - 其他情况保持原有逻辑 + + 3. 修改 `run` 方法中的步骤输入创建逻辑: + - 添加 `elif step_name == "srt":` 分支 + - SRTInput 需要: srt_file（从 ASR 结果获取）, metadata_file, output_file + + 4. 修改 `_populate_skipped_step_results` 方法: + - 添加 "srt" 步骤的现有文件扫描逻辑 + + 关键代码位置: pipeline.py 约 170-250 行 + + + python -c "from kb_workflow.pipeline.pipeline import Pipeline; print('Pipeline imports OK') + + + - Pipeline 能根据平台类型选择处理器 + - B 站视频使用 SRTProcessor + - 其他平台保持 AnalyzeProcessor + + + + + Task 2: 更新 CLI 处理器注册 + kb_workflow/cli.py + + 更新 CLI 处理器注册: + + 1. 修改 `kb_workflow/cli.py` 的 `process_command` 函数: + - 导入 SRTProcessor: `from .pipeline.processors import SRTProcessor` + - 将 SRTProcessor 添加到 processors 列表 + - 更新 PipelineConfig.steps: `["parse", "download", "asr", "srt", "analyze", "archive"]` + （Pipeline 会根据平台条件跳过不需要的步骤） + + 2. 处理器列表变为: + ```python + processors = [ + ParseProcessor(), + DownloadProcessor(), + ASRProcessor(), + SRTProcessor(), # 新增：B 站视频使用 + AnalyzeProcessor(), # 保留：知乎/文章使用 + ArchiveProcessor(), + ] + ``` + + 注意：Pipeline 步骤顺序保持不变，SRTProcessor 和 AnalyzeProcessor 都注册， + 但 Pipeline 会根据平台类型选择执行哪一个。 + + + python -c "from kb_workflow.cli import process_command; print('CLI imports OK') + + + - CLI 正确导入 SRTProcessor + - 处理器列表包含所有处理器 + - process_command 函数正常工作 + + + + + Task 3: 添加 B 站视频流程的端到端测试 + tests/test_bilibili_pipeline.py + + 添加 B 站视频流程的端到端测试: + + 1. 创建 `tests/test_bilibili_pipeline.py`: + - 使用 mock 模拟 BilibiliAdapter 的 fetch_metadata 和 download_video + - 使用 mock 模拟 ASRProcessor 的输出（返回 SRT 文件路径） + - 测试 B 站视频处理流程: + - 验证 SRTProcessor 被调用 + - 验证 AnalyzeProcessor 被跳过 + - 验证生成的 Markdown 文件格式正确 + + 2. 测试用例: + - `test_bilibili_video_uses_srt_processor`: 验证 B 站视频使用 SRTProcessor + - `test_bilibili_article_uses_analyze_processor`: 验证 B 站文章使用 AnalyzeProcessor + - `test_zhihu_answer_uses_analyze_processor`: 验证知乎回答使用 AnalyzeProcessor + + 3. 使用 pytest fixtures 创建测试数据: + - 模拟的 SRT 文件内容 + - 模拟的 metadata.json 内容 + + + pytest tests/test_bilibili_pipeline.py -v + + + - B 站视频流程测试通过 + - 平台路由逻辑正确 + - 生成的 Markdown 格式正确 + + + + + Task 4: 更新 DeepAnalyzer 添加弃用警告 + kb_workflow/deep_analyzer/__init__.py + + 更新 DeepAnalyzer 添加弃用警告（但保留功能）: + + 1. 修改 `kb_workflow/deep_analyzer/__init__.py`: + - 在 `DeepAnalyzer.__init__` 中添加日志警告: + ```python + import logging + logger = logging.getLogger(__name__) + logger.warning( + "DeepAnalyzer is deprecated for Bilibili video processing. " + "Use SRTProcessor instead." + ) + ``` + - 功能保持不变，以便知乎等其他平台继续使用 + + 2. 不删除任何代码，只是添加警告 + + 注意：DeepAnalyzer 仍被 AnalyzeProcessor 使用，知乎处理需要它。 + 此任务只是添加警告，提醒开发者 B 站视频应使用 SRTProcessor。 + + + python -c "from kb_workflow.deep_analyzer import DeepAnalyzer; print('DeepAnalyzer imports OK') + + + - DeepAnalyzer 仍可正常导入和使用 + - 初始化时输出弃用警告 + - 知乎处理流程不受影响 + + + + + + 完整的 B 站视频简化处理流程： + - SRTProcessor 处理器（解析、分段、纠错、Markdown 生成） + - Pipeline 平台路由逻辑（B 站视频用 SRT，其他用 Analyze） + - CLI 集成和端到端测试 + + + 1. 运行单元测试: `pytest tests/test_srt_processor.py tests/test_bilibili_pipeline.py -v` + 2. 测试 B 站视频处理（需要真实 SRT 文件或 mock）: + ```bash + # 使用测试模式运行 + python -m kb_workflow process "https://www.bilibili.com/video/BV1test" --no-skip + ``` + 3. 验证输出文件格式: + - 检查生成的 .md 文件包含 YAML frontmatter + - 检查时间戳已移除 + - 检查文本已分段 + 4. 验证知乎处理不受影响: + ```bash + python -m kb_workflow process "https://zhuanlan.zhihu.com/p/123456" --no-skip + ``` + + Type "approved" or describe issues found + + + + + +- 所有单元测试通过 +- B 站视频使用 SRTProcessor +- 知乎处理使用 AnalyzeProcessor +- CLI 命令正常工作 +- DeepAnalyzer 弃用警告正常输出 + + + +1. 运行 `kb-workflow process ` 生成 Markdown 文件（非深度分析报告） +2. Markdown 文件包含视频元数据（标题、作者、时长） +3. 元数据处理功能保持不变（BilibiliAdapter 正常工作） +4. 视频标签正常生成 +5. DeepAnalyzer 对 B 站视频输出弃用警告 +6. 知乎等其他平台处理器不受影响 +7. 所有测试通过 + + + +After completion, create `.planning/phases/12-srt-simplifier/12-02-SUMMARY.md` +