starmen1265/kb-skills
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(12-srt-simplifier): create phase 12 plans

Browse Source
This commit is contained in:
starmen1265
2026-03-19 23:25:43 +08:00
parent 978613461b
commit 56039c5956
3 changed files with 613 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/ROADMAP.md
+8 -4
View File
@@ -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 |
|-------|-----------|----------------|--------|-----------|
.planning/phases/12-srt-simplifier/12-01-PLAN.md
+313
View File
@@ -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"
---
<objective>
创建 SRT 字幕处理模块，实现字幕解析、去时间戳、语义分段和 LLM 纠错功能。
Purpose: 将 B 站字幕文件转换为易读的 Markdown 文档，保留核心内容但移除时间戳等格式信息。
Output: SRT 处理模块（parser, segmenter, corrector）和 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/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 提供商
```
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: 创建 SRT 解析器模块</name>
<files>kb_workflow/srt/__init__.py, kb_workflow/srt/parser.py, tests/test_srt_processor.py</files>
<behavior>
- Test 1: 标准的 SRT 格式能被正确解析为 Segment 列表
- Test 2: 包含特殊字符的字幕能正确处理
- Test 3: 空文件或格式错误的文件抛出 ValueError
</behavior>
<action>
创建 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`，需要正确解析。
</action>
<verify>
<automated>pytest tests/test_srt_processor.py::test_parse_srt -v</automated>
</verify>
<done>
- SRT 文件能被解析为 List[Segment]
- 每个 Segment 包含 id, start_time, end_time, text
- 单元测试通过
</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: 创建语义分段器</name>
<files>kb_workflow/srt/segmenter.py, tests/test_srt_processor.py</files>
<behavior>
- Test 1: 连续短句被合并为段落
- Test 2: 主题变化时自动分段
- Test 3: 单个段落不超过 500 字符
</behavior>
<action>
创建语义分段模块:
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 进行分段判断（简化实现），仅基于时间和长度规则。
</action>
<verify>
<automated>pytest tests/test_srt_processor.py::test_segment -v</automated>
</verify>
<done>
- 字幕分段被合并为语义段落
- 时间戳被移除
- 段落长度合理（不超过 max_paragraph_chars）
</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: 创建 ASR 纠错器</name>
<files>kb_workflow/srt/corrector.py, tests/test_srt_processor.py</files>
<behavior>
- Test 1: 明显的同音字错误被纠正
- Test 2: 上下文相关的错误被纠正
- Test 3: 正确文本不被过度修改
</behavior>
<action>
创建 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 不可用则返回原文。
</action>
<verify>
<automated>pytest tests/test_srt_processor.py::test_correct -v</automated>
</verify>
<done>
- ASR 纠错器能纠正明显的语音识别错误
- AI 不可用时返回原文
- 长文本被分批处理
</done>
</task>
<task type="auto">
<name>Task 4: 创建 SRTProcessor 和 Markdown 生成</name>
<files>kb_workflow/pipeline/processors/srt.py, kb_workflow/pipeline/schemas.py, kb_workflow/srt/__init__.py</files>
<action>
创建 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` 导出所有公共接口
</action>
<verify>
<automated>pytest tests/test_srt_processor.py::test_srt_processor -v</automated>
</verify>
<done>
- SRTProcessor 能处理 SRT 文件生成 Markdown
- 输出包含 YAML frontmatter（元数据和标签）
- 处理器遵循 BaseProcessor 模式
</done>
</task>
</tasks>
<verification>
- 所有单元测试通过
- SRT 解析器能处理标准格式
- 语义分段器输出合理段落
- ASR 纠错器能调用 LLM
- SRTProcessor 生成有效 Markdown
</verification>
<success_criteria>
1. `parse_srt` 能将 SRT 内容解析为 Segment 列表
2. `SemanticSegmenter.segment` 能将字幕转换为语义段落
3. `ASRCorrector.correct` 能纠正语音识别错误
4. `SRTProcessor` 能生成包含元数据的 Markdown 文件
5. 所有测试通过（pytest tests/test_srt_processor.py）
</success_criteria>
<output>
After completion, create `.planning/phases/12-srt-simplifier/12-01-SUMMARY.md`
</output>
.planning/phases/12-srt-simplifier/12-02-PLAN.md
+292
View File
@@ -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"
---
<objective>
将 SRTProcessor 集成到 Pipeline，修改 B 站处理流程使用简化处理，移除 DeepAnalyzer 调用，同时保持知乎等其他平台处理不变。
Purpose: 实现需求 SCOPE-01（移除深度分析）和 SCOPE-02（仅针对 B 站），确保 B 站视频生成简化的 Markdown 文档。
Output: 修改后的 Pipeline 和 CLI，集成测试通过。
</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/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
</context>
<tasks>
<task type="auto">
<name>Task 1: 修改 Pipeline 支持平台特定处理流程</name>
<files>kb_workflow/pipeline/pipeline.py, kb_workflow/pipeline/schemas.py</files>
<action>
修改 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 行
</action>
<verify>
<automated>python -c "from kb_workflow.pipeline.pipeline import Pipeline; print('Pipeline imports OK')</automated>
</verify>
<done>
- Pipeline 能根据平台类型选择处理器
- B 站视频使用 SRTProcessor
- 其他平台保持 AnalyzeProcessor
</done>
</task>
<task type="auto">
<name>Task 2: 更新 CLI 处理器注册</name>
<files>kb_workflow/cli.py</files>
<action>
更新 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 会根据平台类型选择执行哪一个。
</action>
<verify>
<automated>python -c "from kb_workflow.cli import process_command; print('CLI imports OK')</automated>
</verify>
<done>
- CLI 正确导入 SRTProcessor
- 处理器列表包含所有处理器
- process_command 函数正常工作
</done>
</task>
<task type="auto">
<name>Task 3: 添加 B 站视频流程的端到端测试</name>
<files>tests/test_bilibili_pipeline.py</files>
<action>
添加 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 内容
</action>
<verify>
<automated>pytest tests/test_bilibili_pipeline.py -v</automated>
</verify>
<done>
- B 站视频流程测试通过
- 平台路由逻辑正确
- 生成的 Markdown 格式正确
</done>
</task>
<task type="auto">
<name>Task 4: 更新 DeepAnalyzer 添加弃用警告</name>
<files>kb_workflow/deep_analyzer/__init__.py</files>
<action>
更新 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。
</action>
<verify>
<automated>python -c "from kb_workflow.deep_analyzer import DeepAnalyzer; print('DeepAnalyzer imports OK')</automated>
</verify>
<done>
- DeepAnalyzer 仍可正常导入和使用
- 初始化时输出弃用警告
- 知乎处理流程不受影响
</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<what-built>
完整的 B 站视频简化处理流程：
- SRTProcessor 处理器（解析、分段、纠错、Markdown 生成）
- Pipeline 平台路由逻辑（B 站视频用 SRT，其他用 Analyze）
- CLI 集成和端到端测试
</what-built>
<how-to-verify>
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
```
</how-to-verify>
<resume-signal>Type "approved" or describe issues found</resume-signal>
</task>
</tasks>
<verification>
- 所有单元测试通过
- B 站视频使用 SRTProcessor
- 知乎处理使用 AnalyzeProcessor
- CLI 命令正常工作
- DeepAnalyzer 弃用警告正常输出
</verification>
<success_criteria>
1. 运行 `kb-workflow process <bilibili-url>` 生成 Markdown 文件（非深度分析报告）
2. Markdown 文件包含视频元数据（标题、作者、时长）
3. 元数据处理功能保持不变（BilibiliAdapter 正常工作）
4. 视频标签正常生成
5. DeepAnalyzer 对 B 站视频输出弃用警告
6. 知乎等其他平台处理器不受影响
7. 所有测试通过
</success_criteria>
<output>
After completion, create `.planning/phases/12-srt-simplifier/12-02-SUMMARY.md`
</output>