kb-skills/.planning/phases/04-analysis-orchestration/04-CONTEXT.md

Phase 4: Analysis & Orchestration - Context

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

## Phase Boundary

集成深度分析能力和完整管道编排，实现从链接到分析报告的端到端全自动处理。包括：

• DeepAnalyzer 集成（复用现有实现）
• 统一 Processor 模式（parse → download → asr → analyze）
• 单命令工作流入口
• 端到端验证

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

## 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 的具体接口设计
• 处理器注册和发现机制
• 错误信息的具体格式

## Specific Ideas

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

<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 Ideas

None — discussion stayed within phase scope

---

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