From 2148f1632a0184bb454c941e73cee7457af77d5e Mon Sep 17 00:00:00 2001
From: starmen1265 <starmen1265@163.com>
Date: Fri, 13 Mar 2026 18:49:57 +0800
Subject: [PATCH] docs(03): capture phase context

---
 .../phases/03-processing-skills/03-CONTEXT.md | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 .planning/phases/03-processing-skills/03-CONTEXT.md

diff --git a/.planning/phases/03-processing-skills/03-CONTEXT.md b/.planning/phases/03-processing-skills/03-CONTEXT.md
new file mode 100644
index 0000000..e676baf
--- /dev/null
+++ b/.planning/phases/03-processing-skills/03-CONTEXT.md
@@ -0,0 +1,98 @@
+# Phase 3: Processing Skills - Context
+
+**Gathered:** 2026-03-13
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+集成 ASR 处理能力，支持视频内容的多模态文字提取。将现有分散的 ASR 工具（B站字幕下载、Whisper.cpp、FunASR）整合为统一的管道步骤，与 Phase 2 的内容获取能力衔接。
+
+**明确排除**：OCR 处理不需要集成。
+
+</domain>
+
+<decisions>
+## 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 配置）
+- 音频转换的临时文件处理策略
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "官方字幕质量最高，优先使用" — 无需计算资源，直接复用
+- "HF_TOKEN 配置时自动启用说话者分离" — 无需用户手动指定
+- 输出与内容同目录，保持文件组织简洁
+
+</specifics>
+
+<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>
+## Deferred Ideas
+
+- OCR 视频帧文字识别 — 不需要，明确排除
+- 进度可见性（实时显示 ASR 进度）— v2 需求
+- 并行 ASR 处理 — v2 需求
+
+</deferred>
+
+---
+
+*Phase: 03-processing-skills*
+*Context gathered: 2026-03-13*