# Roadmap: kb-skills 工作流重构

## Overview

将现有分散的技能模块重构为统一的管道处理系统。从基础设施（状态管理、Schema验证）开始，逐步集成平台技能（B站/知乎）、处理技能（ASR），最终形成完整的端到端工作流。每个阶段都交付可独立验证的能力，确保长时任务可恢复、可追溯。

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Foundation** - 状态管理、Schema验证、错误处理、统一配置
- [x] **Phase 2: Platform Skills** - B站/知乎链接解析、元数据提取、内容下载
- [ ] **Phase 3: Processing Skills** - ASR 集成、视频内容文字提取
- [ ] **Phase 4: Analysis & Orchestration** - 深度分析集成、完整管道编排、端到端验证

## Phase Details

### Phase 1: Foundation
**Goal**: 建立可靠的基础设施，支持步骤级状态持久化、Schema验证和结构化错误处理
**Depends on**: Nothing (first phase)
**Requirements**: PIPE-01, PIPE-02, PIPE-03, REL-01, REL-02, REL-03, VAL-01, MNT-02, MNT-03
**Success Criteria** (what must be TRUE):
  1. 执行任意步骤后，workflow_state.json 正确记录该步骤的完成状态
  2. 中断后重新执行，已完成的步骤被跳过，从中断点继续
  3. 每个步骤输出通过 Pydantic Schema 验证，格式错误阻止进入下一步
  4. 所有环境变量集中在 ~/.kb_env，启动时验证必需变量
  5. 错误信息包含步骤名、输入摘要、失败原因、可操作建议
**Plans:** 3 plans

Plans:
- [ ] 01-01-PLAN.md — State Manager: workflow_state.json 管理 (PIPE-02, REL-01, REL-03)
- [ ] 01-02-PLAN.md — Schema Registry: 统一输入输出格式定义 (PIPE-01, PIPE-03, VAL-01, REL-03)
- [x] 01-03-PLAN.md — Error Handler & Config: 结构化错误处理和统一配置 (REL-02, MNT-02, MNT-03)

### Phase 2: Platform Skills
**Goal**: 集成B站和知乎平台的内容获取能力，形成从链接到原始内容的完整流程
**Depends on**: Phase 1
**Requirements**: PLAT-01, PLAT-02, PLAT-03
**Success Criteria** (what must be TRUE):
  1. 输入B站视频链接，自动提取元数据（标题、作者、时长等）并保存为结构化JSON
  2. 输入B站专栏链接，自动提取文章内容并保存为Markdown
  3. 输入知乎问答/专栏链接，自动提取内容和元数据
  4. 重复执行同一链接，不产生重复文件（幂等）
  5. 403/超时错误触发降级策略，记录失败原因到状态文件
**Plans:** 3 plans

Plans:
- [x] 02-01-PLAN.md — Link Parser & Idempotency Checker (PLAT-01, PLAT-02, PLAT-03)
- [x] 02-02-PLAN.md — Bilibili Adapter: 视频元数据 + 专栏内容 (PLAT-01, PLAT-02)
- [x] 02-03-PLAN.md — Zhihu Adapter: 问答 + 专栏内容 (PLAT-03)

### Phase 3: Processing Skills
**Goal**: 集成 ASR 处理能力，支持视频内容的文字提取（官方字幕优先，无字幕时使用 Whisper.cpp）
**Depends on**: Phase 2
**Requirements**: None (平台支持已在Phase 2覆盖)
**Success Criteria** (what must be TRUE):
  1. B站视频自动下载字幕（优先官方字幕），无字幕时调用语音识别
  2. Whisper识别完成后，转录结果保存为结构化JSON（含时间戳）
  3. 处理结果自动关联到对应的内容目录
  4. HF_TOKEN配置时自动启用带说话者分离的Whisper
**Plans:** 1 plan

Plans:
- [ ] 03-01-PLAN.md — ASRProcessor: 官方字幕下载 + Whisper.cpp 集成 + 说话者分离

### Phase 4: Analysis & Orchestration
**Goal**: 集成深度分析能力，完成端到端工作流编排，实现从链接到分析报告的全自动处理
**Depends on**: Phase 3
**Requirements**: MNT-01
**Success Criteria** (what must be TRUE):
  1. 输入任意支持的平台链接，自动完成解析→下载→识别→分析全流程
  2. 深度分析报告保存到对应内容目录，包含结构化的核心观点和洞察
  3. 整个工作流可通过单个命令触发，无需手动干预
  4. 新人能通过清晰的模块结构和文档理解代码，在30分钟内定位并修改任意步骤
  5. 所有步骤的状态可通过 workflow_state.json 查询
**Plans**: TBD

Plans:
- [ ] 04-01: Deep Analyzer 集成
- [ ] 04-02: Pipeline Engine 完整编排
- [ ] 04-03: 代码结构整理与文档

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation | 3/3 | Complete | 01-02, 01-01, 01-03 |
| 2. Platform Skills | 3/3 | Complete | 02-01, 02-02, 02-03 |
| 3. Processing Skills | 0/1 | Not started | - |
| 4. Analysis & Orchestration | 0/3 | Not started | - |

---
*Roadmap created: 2026-03-13*
*Last updated: 2026-03-13 - Phase 3 planned (OCR excluded per user decision)*
*Granularity: coarse (4 phases)*