docs(04): capture phase context
This commit is contained in:
@@ -0,0 +1,125 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user