kb-skills/.planning/ROADMAP.md

Roadmap: kb-skills

Milestones

• ✅ v1.0 Pipeline Architecture - Phases 1-4 (shipped 2026-03-15)
• ✅ v1.1 Architecture Refactor - Phases 5-6 (shipped 2026-03-16)
• ✅ v1.2 Zhihu Crawler - Phases 7-9 (shipped 2026-03-17)
• ✅ v1.3 Proxy Pool - Phase 10 (shipped 2026-03-18)
• ✅ v1.4 Zhihu Anti-Crawler - Phase 11 (shipped 2026-03-18)
• ✅ v1.5 B站字幕简化处理 - Phase 12 (shipped 2026-03-21)
• 🔄 v1.6 语义分段改进 - Phases 13-15 (in progress)

Phases

✅ v1.0 Pipeline Architecture (Phases 1-4) - SHIPPED 2026-03-15

Phase 1: Foundation

Goal: 项目基础设施和状态管理 Plans: 3 plans

Plans:

• 01-01: WorkflowStateManager 状态管理
• 01-02: LinkParser URL 解析
• 01-03: IdempotencyChecker 幂等检查

Phase 2: Adapters

Goal: 平台元数据适配器 Plans: 2 plans

Plans:

• 02-01: BilibiliAdapter B站适配器
• 02-02: ZhihuAdapter 知乎适配器

Phase 3: Processors

Goal: 管道处理器架构 Plans: 3 plans

Plans:

• 03-01: BaseProcessor 基类
• 03-02: 具体处理器实现
• 03-03: Schema 验证

Phase 4: Pipeline

Goal: 处理器编排和 CLI Plans: 2 plans

Plans:

• 04-01: Pipeline 编排引擎
• 04-02: CLI process 命令

✅ v1.1 Architecture Refactor (Phases 5-6) - SHIPPED 2026-03-16

Phase 5: 归档与目录优化

Goal: 统一中间目录结构，添加自动归档步骤，优化最终目录布局 Plans: 3 plans (all complete)

Phase 6: 代码整合

Goal: 将独立的元数据技能和 Pipeline 模块整合进 kb-workflow Plans: 3 plans (all complete)

✅ v1.2 Zhihu Crawler (Phases 7-9) - SHIPPED 2026-03-17

Phase 7: 登录认证体系

Goal: 建立知乎登录认证机制，支持二维码扫码和手动 Cookie 两种方式 Plans: 3 plans (all complete)

Phase 8: 内容爬取实现

Goal: 实现知乎问答、专栏/文章、评论的完整爬取功能 Plans: 3 plans (all complete)

Phase 9: Pipeline 整合

Goal: 将新爬虫实现整合进现有 Pipeline 架构 Plans: 1 plan (complete)

✅ v1.3 Proxy Pool (Phase 10) - SHIPPED 2026-03-18

Phase 10: Proxy Pool (代理池管理)

Goal: 建立代理池基础设施，支持多代理配置、自动轮换和健康检查 Requirements: PROXY-01, PROXY-02, PROXY-03, PROXY-04 Plans: 2 plans (all complete)

Plans:

• 10-01: ProxyPool 核心类实现 — 从 YAML/环境变量加载代理，Round-Robin 轮换
• 10-02: 健康检查与 ZhihuCrawler 集成 — 被动检测、冷却恢复、代理切换

Key Decisions:

• 使用索引指针而非 itertools.cycle 实现轮换
• 惰性冷却检查而非后台定时器
• ProxyPool 参数优先于 config.proxy 配置

---

✅ v1.4 Zhihu Anti-Crawler (SHIPPED 2026-03-18)

Milestone Goal: 绕过知乎反爬检测，让 Playwright 爬虫能正常工作

Phase 11: Stealth Fingerprinting (指纹伪装)

Goal: 隐藏 Playwright 自动化特征，让爬虫通过知乎的浏览器指纹检测 Depends on: Phase 10 Requirements: STEALTH-01, STEALTH-02, STEALTH-03, STEALTH-04, VERIFY-01, VERIFY-02 Success Criteria (what must be TRUE):

1. ZhihuCrawler 访问问答页面时不再被 40362 错误拦截
2. 爬虫的 navigator.webdriver 属性对知乎不可见
3. Playwright 特有的 JS 属性（__playwright, pwInspect 等）被移除
4. 现有功能（登录、Cookie 持久化、内容爬取）保持正常工作 Plans: 2 plans (all complete)

Plans:

• 11-01-PLAN.md — 创建 StealthConfig 模块和单元测试
• 11-02-PLAN.md — 集成 stealth 到 ZhihuCrawler 并验证

Key Decisions:

• 使用 playwright-stealth 库进行指纹伪装
• stealth_config=None 表示默认启用 stealth (向后兼容)
• launch 时添加 --disable-blink-features=AutomationControlled 参数

---

✅ v1.5 B站字幕简化处理 (Phase 12) - SHIPPED 2026-03-21

Phase 12: SRT 简化处理器

Goal: 实现 SRT 字幕处理，生成简化的 Markdown 文档，保留元数据和标签，移除深度分析 Plans: 2 plans (all complete)

Plans:

• 12-01: SRT 处理模块（parser、segmenter、corrector）和 SRTProcessor 实现
• 12-02: Pipeline 集成、平台路由、测试验证

Key Decisions:

• SRT 处理模块独立于 DeepAnalyzer，位于 kb_workflow/srt/
• 语义分段基于简单规则（时间间隔 + 长度限制），不依赖 LLM
• ASR 纠错可选，AI 不可用时返回原文
• B 站视频使用 SRTProcessor，知乎/文章继续使用 AnalyzeProcessor

---

🔄 v1.6 语义分段改进 (IN PROGRESS)

Milestone Goal: 使用 LLM 实现智能语义分段，识别视频类型并适配分段策略，保持内容完整性

Phase 13: 核心 LLM 分段功能

Goal: 实现基于 LLM 的智能语义分段，识别视频类型并生成主题标题 Depends on: Phase 12 Requirements: VIDEO-01, VIDEO-02, VIDEO-03, BOUND-01, BOUND-02, BOUND-03, BOUND-04, COMP-01, COMP-02, COMP-03, TITLE-01, TITLE-02, TITLE-03, SENT-01, SENT-02, SENT-03, STRAT-01, STRAT-02, STRAT-03 Success Criteria (what must be TRUE):

1. 系统能正确识别 B站视频的类型（知识类、故事类等），并根据类型选择分段策略
2. 语义分段在主题切换处正确创建边界，不会混入不同话题的内容
3. 分段不会在句子中间或论点未完成时截断，保持内容的语义完整性
4. 主题/章节分段生成简洁准确的标题，论点/观点分段不加标题
5. 不同类型视频使用对应的分段策略，策略可扩展 Plans: 7 plans

Plans:

• 13-01-PLAN.md — 视频类型识别（Pydantic 模型、类型推断、LazyAIClient 初始化）
• 13-02-PLAN.md — 语义边界检测（Prompt 模板、JSON 提取、Pydantic 验证）
• 13-03-PLAN.md — 内容完整性保护（句边界、论点完整性 Prompt 指令）
• 13-04-PLAN.md — 主题标题生成（title 字段、验证、Prompt 指令）
• 13-05-PLAN.md — 中文句边界检测（列举标点符号、语义停顿 Prompt 指令）
• 13-06-PLAN.md — 可扩展策略架构（Strategy Pattern、统一策略实现）
• 13-07-PLAN.md — SRTProcessor 集成（enable_semantic_segmentation 参数、降级策略）

Phase 14: 鲁棒性与成本控制

Goal: 提高系统稳定性，实现优雅降级和成本优化 Depends on: Phase 13 Requirements: ROBUST-01, ROBUST-02, ROBUST-03, ROBUST-04, COST-01, COST-02, COST-03 Success Criteria (what must be TRUE):

1. LLM 调用失败时自动降级到简单规则分段，不影响整体流程
2. LLM 响应解析失败时自动重试或降级，有日志记录便于诊断
3. AI 不可用时自动使用简单规则分段，保证基本功能可用
4. 长视频字幕自动分块处理，避免上下文窗口溢出
5. 相同内容使用缓存结果，避免重复 LLM 调用 Plans: 6 plans

Plans:

• 14-00-PLAN.md — 测试基础设施（Wave 0）
• 14-01-PLAN.md — LLM 调用失败时的重试和降级策略（ROBUST-01, ROBUST-03）
• 14-02-PLAN.md — LLM 响应解析失败的处理（ROBUST-02, ROBUST-04）
• 14-03-PLAN.md — 智能缓存实现（COST-02）
• 14-04-PLAN.md — 长文本分块处理（COST-01）(partially implemented in 14-05)
• 14-05-PLAN.md — 集成到 SRTProcessor 和配置开关（COST-03）

Wave Structure:

• Wave 0: Plan 00 (测试基础设施)
• Wave 1: Plan 01, 02, 03, 04 (并行执行，无依赖)
• Wave 2: Plan 05 (依赖 Wave 1 所有计划)

Phase 15: 输出优化与兼容性

Goal: 优化输出格式，确保向后兼容和可配置性 Depends on: Phase 14 Requirements: OUTPUT-01, OUTPUT-02, OUTPUT-03, CONFIG-01, CONFIG-02, CONFIG-03 Success Criteria (what must be TRUE):

1. 主题/章节分段输出带标题的 Markdown 结构，论点/观点分段输出纯文本
2. 输出格式与现有 SRTProcessor 兼容，不影响其他平台处理
3. LLM 分段功能可通过配置开关启用/禁用
4. 向后兼容，禁用时使用简单规则分段，不破坏现有功能
5. 知乎/文章平台继续使用 AnalyzeProcessor，不受影响 Plans: TBD

---

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → ... → 12 → 13 → 14 → 15

Phase	Milestone	Plans Complete	Status	Completed
1. Foundation	v1.0	3/3	Complete	2026-03-15
2. Adapters	v1.0	2/2	Complete	2026-03-15
3. Processors	v1.0	3/3	Complete	2026-03-15
4. Pipeline	v1.0	2/2	Complete	2026-03-15
5. 归档与目录优化	v1.1	3/3	Complete	2026-03-16
6. 代码整合	v1.1	3/3	Complete	2026-03-16
7. 登录认证体系	v1.2	3/3	Complete	2026-03-17
8. 内容爬取实现	v1.2	3/3	Complete	2026-03-17
9. Pipeline 整合	v1.2	1/1	Complete	2026-03-17
10. Proxy Pool	v1.3	2/2	Complete	2026-03-18
11. Stealth Fingerprinting	v1.4	2/2	Complete	2026-03-18
12. SRT 简化处理器	v1.5	2/2	Complete	2026-03-21
13. 核心 LLM 分段功能	v1.6	7/7	Complete	2026-03-22
14. 鲁棒性与成本控制	v1.6	Complete	2026-03-23
15. 输出优化与兼容性	1/4	In Progress		-

---

Context

技术栈

• Python 3.12+
• Pydantic v2 (数据验证)
• SimpleAIClient (LLM 调用)
• 现有 SemanticSegmenter (扩展点)

v1.6 关键集成点

• SemanticSegmentationEngine: 新模块，负责 LLM 调用和语义分析
• SRTProcessor: 扩展现有处理器，添加 LLM 分支
• Pydantic Schemas: 严格验证 LLM 输出格式

三层 Fallback 策略

1. 直接 JSON 解析（理想情况）
2. Markdown 代码块提取（常见情况）
3. 启发式均匀分段（保底方案）

需要避免的陷阱

• LLM-1: 上下文窗口溢出 — 实施分块策略
• LLM-2: 输出格式不稳定 — 多层 fallback
• LLM-3: 边界破坏完整性 — 句边界保护
• LLM-4: 分段不一致性 — 温度控制
• LLM-5: 成本失控 — 缓存策略

---

Last updated: 2026-03-22