kb-skills/.planning/PROJECT.md

kb-skills 工作流重构

Current State: v1.6 Shipped (2026-03-23)

v1.6 语义分段改进 已交付 — 使用 LLM 语义分析实现智能分段

已交付特性:

• ✓ SemanticSegmentationEngine — 基于 LLM 的语义分段引擎
• ✓ 视频类型识别 — 知识类/故事类/访谈类/新闻类/vlog
• ✓ 主题边界检测 — 语义分析识别话题转换点
• ✓ 主题标题生成 — 为章节/主题分段生成标题
• ✓ 内容完整性保护 — 句边界、论点完整性、并列结构
• ✓ 中文句边界检测 — 基于语义停顿
• ✓ 可扩展策略架构 — Strategy Pattern
• ✓ 三层 Fallback — JSON → Markdown → 启发式
• ✓ 优雅降级 — LLM 失败降级到规则分段
• ✓ 智能缓存 — 基于内容
• ✓ 长文本分块 — 避免上下文窗口溢出
• ✓ 配置开关 — KB_ENABLE_SEMANTIC_SEGMENTATION
• ✓ 向后兼容 — 禁用时使用规则分段

Active

(无 — 下一里程碑规划待定)

Next Milestone Goals

(待规划 — 运行 /gsd:new-milestone 开始)

Previous Milestones

v1.4 Zhihu Anti-Crawler (Shipped: 2026-03-18):

• 浏览器指纹伪装 (Stealth) — 使用 playwright-stealth 隐藏自动化特征
• ZhihuCrawler 集成 — 默认启用 stealth，绕过反爬检测

v1.3 Proxy Pool (Shipped: 2026-03-18):

• 代理池管理 (ProxyPool) — 支持 YAML/环境变量配置，Round-Robin 轮换，健康检查

v1.2 Zhihu Crawler (Shipped: 2026-03-17):

• 知乎登录认证 — 二维码扫码登录 + 手动 Cookie 降级
• 知乎内容爬取 — 问答、专栏、评论

v1.1 Architecture Refactor (Shipped: 2026-03-16):

• 中间目录调整 — 统一到 ~/work/intermediate/analysis/
• 归档步骤 — 分析完成后自动归档到最终目录

v1.0 Pipeline Architecture (Shipped: 2026-03-15):

• 管道架构 — WorkflowStateManager, BaseProcessor, Pipeline 类
• 平台适配器 — BilibiliAdapter, ZhihuAdapter
• CLI 入口 — kb-workflow process <url>

What This Is

一个基于管道模型的知识库内容处理技能体系。将外部链接（B站视频/专栏、知乎问答/专栏）转换为结构化的深度分析报告，支持幂等执行和断点续传。

使用方式：

python3 kb-workflow/kb_workflow.py process "https://www.bilibili.com/video/BVxxx"

Core Value

可靠、可维护的处理管道 - 每个步骤独立、可验证、可恢复。无论何时失败，都能从断点继续，不会丢失已完成的进度。

Requirements

Validated

v1.6 语义分段改进 (2026-03-23):

• ✓ VIDEO-01: 视频类型识别 — 知识类/故事类/访谈类/新闻类/vlog
• ✓ 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: 多策略支持 — 至少 2 种分段策略
• ✓ STRAT-02: 自动适配 — 不同类型适配对应策略
• ✓ STRAT-03: 可扩展 — 便于未来添加新类型
• ✓ ROBUST-01: LLM 调用失败降级 — 自动降级到规则分段
• ✓ ROBUST-02: 解析失败降级 — 自动降级到规则分段
• ✓ ROBUST-03: AI 不可用降级 — 自动使用规则分段
• ✓ ROBUST-04: 日志记录 — 降级过程有日志
• ✓ COST-01: 长文本分块 — 避免上下文窗口溢出
• ✓ COST-02: 智能缓存 — 相同内容不重复调用
• ✓ OUTPUT-01: 标题 Markdown 结构 — 主题/章节带标题
• ✓ OUTPUT-02: 纯文本输出 — 论点/观点不加标题
• ✓ OUTPUT-03: 输出兼容 — 与现有 SRTProcessor 兼容
• ✓ CONFIG-01: 配置开关 — 可通过配置启用/禁用
• ✓ CONFIG-02: 向后兼容 — 不破坏现有规则分段
• ✓ CONFIG-03: AnalyzeProcessor 独立 — 知乎/文章不受影响

v1.5 B站字幕简化处理 (2026-03-21):

• ✓ SRT-01: SRT 字幕解析 — 读取 SRT 文件，提取纯文本和时间戳
• ✓ SRT-02: 去除时间戳 — 移除时间码，保留字幕文本
• ✓ SRT-03: 简单分段 — 基于时间间隔（3秒）和长度（500字符）分段
• ✓ SRT-04: LLM 纠正 — 使用 SimpleAIClient 纠正语音识别错误（可选）
• ✓ OUT-01: Markdown 输出 — 生成包含元数据和内容的 Markdown 文件
• ✓ OUT-02: 元数据保留 — 标题、作者、时长、标签等
• ✓ OUT-03: 标签生成 — 继续正常生成视频标签
• ✓ OUT-04: 平台路由 — B站视频使用 SRTProcessor，其他平台使用 AnalyzeProcessor
• ✓ SCOPE-01: DeepAnalyzer 弃用 — 添加弃用警告（仅针对 B站视频）
• ✓ SCOPE-02: 其他平台不受影响 — 知乎/文章继续使用 AnalyzeProcessor

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

• ✓ STEALTH-01: 隐藏 navigator.webdriver 属性
• ✓ STEALTH-02: 移除 Playwright 特有属性（__playwright, pwInspect 等）
• ✓ STEALTH-03: 模拟正常浏览器的 Chrome 属性
• ✓ STEALTH-04: 修改 User-Agent 为正常浏览器格式
• ✓ VERIFY-01: ZhihuCrawler 集成指纹伪装后能正常访问问答页面
• ✓ VERIFY-02: 保持现有功能不变（登录、Cookie、内容爬取）

v1.3 Proxy Pool (2026-03-18):

• ✓ PROXY-01: 代理池配置 — 支持从 YAML 文件或环境变量加载多个代理
• ✓ PROXY-02: 自动轮换 — Round-Robin 策略自动选择下一个代理
• ✓ PROXY-03: 健康检查 — 代理失败检测与冷却恢复机制
• ✓ PROXY-04: 失败回退 — 当前代理失败时自动切换到备用代理

v1.2 Zhihu Crawler (2026-03-17):

• ✓ ZHIHU-01: 二维码扫码登录 — playwright 提取二维码，用户扫码
• ✓ ZHIHU-02: 手动 Cookie 降级 — 扫码失败时支持手动设置 Cookie
• ✓ ZHIHU-03: Cookie 持久化 — 本地存储 Cookie，自动复用
• ✓ ZHIHU-04: 问答内容爬取 — 问题标题、回答内容、元数据
• ✓ ZHIHU-05: 专栏/文章爬取 — 文章标题、正文、元数据
• ✓ ZHIHU-06: 评论爬取 — 支持爬取内容下的评论
• ✓ ZHIHU-07: 代理 IP 支持 — 降低被封风险
• ✓ ZHIHU-08: Pipeline 整合 — 替换现有知乎处理器

v1.1 Architecture Refactor (2026-03-16):

• ✓ REF-01: 中间目录调整 — 统一到 ~/work/intermediate/analysis/
• ✓ REF-02: 归档步骤 — 分析完成后自动归档到最终目录
• ✓ REF-03: 最终目录结构 — 按平台分目录，文件前缀加时间戳
• ✓ REF-04: 元数据技能整合 — kb-bilibili-metadata + kb-zhihu-metadata → kb-workflow
• ✓ REF-05: Pipeline 整合 — kb-pipeline 合并进 kb-workflow

v1.0 管道架构 (2026-03-15):

• ✓ PIPE-01: 统一的管道模型 — kb_pipeline/pipeline.py
• ✓ PIPE-02: 步骤级状态管理 — WorkflowStateManager
• ✓ PIPE-03: 统一 JSON Schema — StepInput/StepOutput schemas
• ✓ PIPE-04: 幂等执行保证 — IdempotencyChecker
• ✓ PIPE-05: 错误恢复策略 — 重试机制 + 降级策略
• ✓ PIPE-06: 清晰的流程定义 — 每个处理器有明确的输入/输出
• ✓ PIPE-07: Schema 验证机制 — Pydantic 验证
• ✓ PIPE-08: 代码结构清晰化 — kb_pipeline/ 模块化设计
• ✓ REL-01~03: 可靠性要求 — 幂等执行、错误恢复、流程定义
• ✓ VAL-01: Schema 验证机制
• ✓ MNT-01~03: 可维护性要求 — 清晰结构、统一配置、错误处理
• ✓ PLAT-01~03: 平台支持 — B站视频/专栏、知乎问答/专栏

原有技能 (已验证):

• ✓ B站视频元数据提取 — bilibili_metadata.py
• ✓ B站视频/专栏内容下载 — bilibili_content.py
• ✓ B站字幕下载（官方字幕） — bilibili_content.py
• ✓ 知乎元数据提取 — zhihu_metadata.py
• ✓ 知乎文章/问答内容提取 — zhihu_content.py
• ✓ Whisper 语音识别 — whisper.py
• ✓ 说话者分离 — whisper_diarization.py
• ✓ FunASR 中文语音识别 — funasr_runner.py
• ✓ OCR 文字识别 — ocr_processor.py
• ✓ AI 深度分析 — deep_analyzer.py

Active

(当前无活跃需求 — 等待下一里程碑规划)

Deferred / Backlog

• ADV-01: 进度可见性 — 实时显示工作流执行进度
• ADV-02: 并行步骤执行 — 支持独立步骤的并行执行
• ADV-03: 说话者分离默认启用 — HF_TOKEN 配置后自动使用
• EXT-01: 微信公众号处理 — 支持微信公众号文章
• ZHIHU-F01: 问题下所有回答 — 爬取问题的所有热门回答
• ZHIHU-F02: 作者全部内容 — 爬取某作者的所有文章/回答

Out of Scope

• 实时/流式处理 — 批量处理即可
• 并发限制 — 不需要限制并发数量
• 用户界面 — 命令行运行
• 多语言支持 — 中文即可
• 小红书 — 当前不支持
• 知乎会员付费内容 — 不爬取付费内容
• 知乎视频 — v1.2 不支持
• 大规模爬取 — 仅用于个人知识库
• 付费打码服务 — 使用二维码登录替代

Context

当前架构 (v1.6)

• 核心模块: kb_workflow/ — Pipeline, Processors, Schemas
• SRT 处理: kb_workflow/srt/ — parser, segmenter, corrector, semantic_engine
• 语义分段: SemanticSegmentationEngine — LLM 驱动的智能分段
• CLI 入口: kb-workflow/kb_workflow.py process
• 平台适配器: BilibiliAdapter, ZhihuAdapter
• 处理器: ParseProcessor, DownloadProcessor, SRTProcessor, AnalyzeProcessor
• 测试覆盖: 76/76 测试通过 (100%)
• 配置: KBSettings.enable_semantic_segmentation (默认 True)

技术栈

• Python 3.12+
• Pydantic v2 (数据验证)
• asyncio (异步执行)
• pytest (测试框架)

技术债务

• 环境变量配置分散 (~/.kb_env, HF_TOKEN, ZHIHU_COOKIE)
• SKILL.md 需要更新为简化的 CLI 使用方式
• 语义分段 v1.5 使用简单规则（v1.6 中改进）

Constraints

• Tech Stack: Python 3.12+, Pydantic v2
• Compatibility: 可破坏性更新
• Scope: 只支持 B站和知乎
• State Granularity: 步骤级状态管理

Key Decisions

Decision	Rationale	Outcome
管道模型	每个步骤独立，输入→处理→输出，串联执行	✓ Good — 清晰的处理器边界
步骤级状态	记录主要步骤状态，支持断点续传	✓ Good — WorkflowStateManager 实现
Schema 验证	只验证 JSON Schema，内容正确性由步骤保证	✓ Good — Pydantic 验证
顺序执行	Pipeline 使用顺序执行而非并行	✓ Good — 简单性和可调试性
CLI subparsers	使用 argparse subparsers 组织命令	✓ Good — 可扩展的 CLI 结构
懒加载导入	AnalyzeProcessor 懒加载 DeepAnalyzer	✓ Good — 避免依赖问题
代理池索引指针	使用 index pointer 而非 itertools.cycle	✓ Good — 更好的可测试性
惰性冷却检查	get_next_proxy() 中惰性检查而非后台定时器	✓ Good — 简化实现
代理池优先级	ProxyPool 参数优先于 config.proxy	✓ Good — 向后兼容
playwright-stealth	使用外部库实现指纹伪装	✓ Good — 成熟方案，活跃维护
stealth 默认启用	stealth_config=None 时默认启用	✓ Good — 向后兼容，无需修改现有代码
SRT 独立模块	SRT 处理独立于 DeepAnalyzer，位于 kb_workflow/srt/	✓ Good — 职责分离
LLM 语义分段	使用 LLM 分析内容语义，实现智能分段	✓ Good — v1.6 已交付
视频类型推断	从元数据关键词推断类型，而非每个类型单独策略	✓ Good — 简化实现
三层 Fallback	JSON 解析 → Markdown 提取 → 启发式分段	✓ Good — 健壮的输出解析
智能缓存	基于内容的 LLM 结果缓存	✓ Good — 避免重复调用
配置优先级	参数 > KBSettings > 默认值	✓ Good — 灵活性
ASR 纠错可选	AI 不可用时返回原文	✓ Good — 降级策略
平台路由	B站视频使用 SRTProcessor，其他使用 AnalyzeProcessor	✓ Good — 灵活性
disable_reasoning 参数	ASR 纠错禁用思考模式获得直接结果	✓ Good — 避免 AI 分析过程输出

---

Last updated: 2026-03-23 after completing v1.6 milestone