kb-skills/.planning/phases/03-processing-skills/03-CONTEXT.md

Phase 3: Processing Skills - Context

Gathered: 2026-03-13 Status: Ready for planning

## Phase Boundary

集成 ASR 处理能力，支持视频内容的多模态文字提取。将现有分散的 ASR 工具（B站字幕下载、Whisper.cpp、FunASR）整合为统一的管道步骤，与 Phase 2 的内容获取能力衔接。

明确排除：OCR 处理不需要集成。

## Implementation Decisions

ASR 引擎选择策略

• 优先级顺序：B站官方字幕 → Whisper.cpp 本地识别
• 官方字幕质量最高且无计算成本，优先使用
• 无官方字幕时，默认使用 Whisper.cpp 进行语音识别
• FunASR 保留作为备选，不作为默认选项

说话者分离

• HF_TOKEN 配置时自动启用带说话者分离的 Whisper（pyannote.audio）
• 无需显式参数控制，根据环境变量自动判断
• 说话者分离结果合并到标准输出格式中

输出格式

• 保留全部格式：txt（纯文本）+ srt（字幕）+ json（结构化数据）
• 与现有 ASR 工具输出保持一致
• JSON 包含 segments（带时间戳的分段）和完整文本

OCR 处理

• 不集成 OCR 功能
• Phase 3 专注于 ASR/字幕处理
• OCR 相关计划（03-02）移除

工作流集成

• ASR 作为管道步骤执行，完成后记录到 workflow_state.json
• B站字幕下载集成到 ASR 步骤（统一入口：先尝试官方字幕，无则 ASR）
• 输出文件与内容放在同一目录，不创建子目录

Schema 复用

• 复用 Phase 1 定义的 StepInput/StepOutput 格式
• ASR 输出符合统一的 JSON Schema 规范
• 包含 success、tool、segments、text 等标准字段

Claude's Discretion

• Whisper 模型默认选择（base/small/medium）
• 重试机制的具体参数（继承 Phase 1 的 tenacity 配置）
• 音频转换的临时文件处理策略

## Specific Ideas

• "官方字幕质量最高，优先使用" — 无需计算资源，直接复用
• "HF_TOKEN 配置时自动启用说话者分离" — 无需用户手动指定
• 输出与内容同目录，保持文件组织简洁

<code_context>

Existing Code Insights

Reusable Assets

• kb-whisper/whisper.py: Whisper.cpp 封装，已支持 txt/srt/json 输出，可直接复用核心逻辑
• kb-whisper-diarization/whisper_diarization.py: 说话者分离实现，pyannote.audio 集成
• kb-funasr/funasr_tool.py: FunASR 中文识别，备选方案
• Phase 1 的 Schema 体系：StepInput/StepOutput 定义，状态管理基础设施

Established Patterns

• CLI + JSON 输出模式：所有工具统一使用 {"success": true/false, ...} 格式
• 音频转换流程：ffmpeg 转 16kHz WAV → ASR 处理 → 清理临时文件
• 环境变量配置：从 ~/.kb_env 加载，pydantic-settings 管理

Integration Points

• Phase 2 内容目录：ASR 输出写入同一目录
• workflow_state.json：ASR 步骤状态记录
• B站内容下载器：需要添加官方字幕下载接口

</code_context>

## Deferred Ideas

• OCR 视频帧文字识别 — 不需要，明确排除
• 进度可见性（实时显示 ASR 进度）— v2 需求
• 并行 ASR 处理 — v2 需求

---

Phase: 03-processing-skills Context gathered: 2026-03-13