kb-skills/.planning/milestones/v1.0-ROADMAP.md

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.

• Phase 1: Foundation - 状态管理、Schema验证、错误处理、统一配置
• 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)
• 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:

• 02-01-PLAN.md — Link Parser & Idempotency Checker (PLAT-01, PLAT-02, PLAT-03)
• 02-02-PLAN.md — Bilibili Adapter: 视频元数据 + 专栏内容 (PLAT-01, PLAT-02)
• 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: BaseProcessor + ParseProcessor + DownloadProcessor
• 04-02: ASRProcessor + AnalyzeProcessor
• 04-03: Pipeline schemas (PipelineInput/Output/Config)
• 04-04: Pipeline class with processor orchestration
• 04-05: CLI process subcommand and E2E tests

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	5/5	Complete	04-01, 04-02, 04-03, 04-04, 04-05

---

Roadmap created: 2026-03-13 Last updated: 2026-03-15 - Phase 4 complete (5 plans: 04-01 through 04-05) Granularity: coarse (4 phases)