# Phase 4: Analysis & Orchestration - Context

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

<domain>
## Phase Boundary

集成深度分析能力和完整管道编排，实现从链接到分析报告的端到端全自动处理。包括：
- DeepAnalyzer 集成（复用现有实现）
- 统一 Processor 模式（parse → download → asr → analyze）
- 单命令工作流入口
- 端到端验证

此阶段不涉及新平台支持（Phase 2 已完成）、OCR 功能（Phase 3 已排除）。

</domain>

<decisions>
## Implementation Decisions

### 报告输出格式
- **Markdown 文件** — 延续现有 deep_analyzer.py 的输出格式
- 报告保存到内容目录，与元数据、内容文件同目录
- 文件命名：`{platform}_{id}_analysis.md`

### 管道编排方式
- **单命令全自动** — `kb-workflow process <url>` 一键完成所有步骤
- 自动跳过已完成步骤（幂等执行）
- 步骤顺序：parse → download → asr（视频）→ analyze
- 支持断点续传：中断后重新执行同一链接，从中断点继续

### 代码结构整理
- **统一处理器模式** — 所有步骤实现统一的 Processor 接口
- 处理器基类：`BaseProcessor`（定义 `process(input) -> output` 接口）
- 具体处理器：
  - `ParseProcessor` — 链接解析、平台识别
  - `DownloadProcessor` — 元数据提取、内容下载
  - `ASRProcessor` — 字幕下载/语音识别（已实现）
  - `AnalyzeProcessor` — AI 深度分析

### 错误恢复策略
- **自动重试** — 失败后自动重试 3 次，指数退避
- 复用 Phase 1 的 tenacity 重试机制
- 重试失败后记录到 workflow_state.json，标记步骤失败

### 进度可见性
- **简单日志** — 打印当前步骤名和状态
- 格式：`[Step 1/4] Parsing... → [✓] Parsed: BV1xxx (bilibili)`
- 不需要进度条或预计时间

### AI 配置管理
- **沿用现有配置** — 使用 ~/.kb_env 中的配置
- 配置项：AI_API_KEY, AI_PROVIDER, AI_MODEL, AI_BASE_URL
- 复用 pydantic-settings 的 KBSettings 类

### DeepAnalyzer 集成
- **直接复用** — 调用现有 kb-deep-analyzer/deep_analyzer.py
- 不修改现有实现，只创建 AnalyzeProcessor 包装器
- 包装器负责：读取输入文件、调用 DeepAnalyzer、保存输出

### 工作流入口
- **扩展现有 CLI** — 在 kb-workflow/kb_workflow.py 中添加 pipeline 函数
- 新增子命令：`kb-workflow process <url>`
- 保留现有功能：check-duplicate, archive 等

### 文档策略
- **基础文档** — README + 各模块 docstring
- README 内容：项目概述、安装、使用示例、配置说明
- docstring 内容：类/函数的用途、参数、返回值

### Claude's Discretion
- BaseProcessor 的具体接口设计
- 处理器注册和发现机制
- 错误信息的具体格式

</decisions>

<specifics>
## Specific Ideas

- "单命令全自动" — 类似 `yt-dlp` 的使用体验
- "简单日志" — 像 make 的输出一样，简洁清晰
- "直接复用" — 不破坏现有代码，降低风险

</specifics>

<code_context>
## Existing Code Insights

### Reusable Assets
- `kb-deep-analyzer/deep_analyzer.py`: 完整的 AI 分析实现，支持多提供商
- `kb_pipeline/processors/asr.py`: ASRProcessor 已实现，可作为 Processor 模式参考
- `kb_pipeline/schemas.py`: StepInput/StepOutput/WorkflowState 已定义
- `kb_pipeline/state.py`: WorkflowStateManager 已实现
- `kb_pipeline/config.py`: KBSettings 配置类已实现
- `kb-workflow/kb_workflow.py`: CLI 入口，可扩展添加 process 子命令

### Established Patterns
- 处理器模式：ASRProcessor 使用 `process(input: ASRInput) -> ASROutput` 接口
- 状态管理：WorkflowState.mark_step_completed/failed
- Schema 验证：Pydantic 模型自动验证
- 错误处理：KBError 体系（NetworkError, ValidationError 等）
- 重试机制：tenacity 装饰器 @retry_on_network_error

### Integration Points
- ParseProcessor → LinkParser（Phase 2）
- DownloadProcessor → PlatformAdapter（Phase 2）
- ASRProcessor → 已实现（Phase 3）
- AnalyzeProcessor → DeepAnalyzer（直接调用）
- Pipeline → WorkflowStateManager（状态持久化）

</code_context>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 04-analysis-orchestration*
*Context gathered: 2026-03-13*