From 62c33cdfd54f29e97a2a89f02d9ca10ed832c4f3 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Fri, 13 Mar 2026 22:37:52 +0800 Subject: [PATCH] docs(04): capture phase context --- .../04-analysis-orchestration/04-CONTEXT.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 .planning/phases/04-analysis-orchestration/04-CONTEXT.md diff --git a/.planning/phases/04-analysis-orchestration/04-CONTEXT.md b/.planning/phases/04-analysis-orchestration/04-CONTEXT.md new file mode 100644 index 0000000..668da81 --- /dev/null +++ b/.planning/phases/04-analysis-orchestration/04-CONTEXT.md @@ -0,0 +1,125 @@ +# 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 ` 一键完成所有步骤 +- 自动跳过已完成步骤（幂等执行） +- 步骤顺序：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 ` +- 保留现有功能：check-duplicate, archive 等 + +### 文档策略 +- **基础文档** — README + 各模块 docstring +- README 内容：项目概述、安装、使用示例、配置说明 +- docstring 内容：类/函数的用途、参数、返回值 + +### Claude's Discretion +- BaseProcessor 的具体接口设计 +- 处理器注册和发现机制 +- 错误信息的具体格式 + + + + +## Specific Ideas + +- "单命令全自动" — 类似 `yt-dlp` 的使用体验 +- "简单日志" — 像 make 的输出一样，简洁清晰 +- "直接复用" — 不破坏现有代码，降低风险 + + + + +## 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（状态持久化） + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 04-analysis-orchestration* +*Context gathered: 2026-03-13*