# kb-skills 工作流重构

## Current Milestone: v1.6 语义分段改进

**Goal:** 使用 LLM 语义分析实现智能分段，解决当前基于时间+长度规则的问题

**目标特性:**
- LLM 语义分析 — 识别视频类型并适配分段策略
- 主题/章节识别 — 自动识别并添加标题
- 论点/观点分段 — 保持内容完整性
- 内容变化边界 — 自然分段位置
- 通用自适应 — 支持各种类型视频

### Active

- [ ] **语义分段改进** — 使用 LLM 替代简单规则，实现智能分段
- [ ] **视频类型识别** — 自动判断视频类型（知识类、故事类、对话类等）
- [ ] **主题识别与标题** — 识别主题章节并生成标题
- [ ] **内容完整性** — 保持话题/论点的完整性，避免错误截断
- [ ] **自然分段边界** — 在句子/段落边界处分段

## 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站视频/专栏、知乎问答/专栏）转换为结构化的深度分析报告，支持幂等执行和断点续传。

**使用方式：**
```bash
python3 kb-workflow/kb_workflow.py process "https://www.bilibili.com/video/BVxxx"
```

## Core Value

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

## Requirements

### Validated

**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.5)
- **核心模块**: `kb_workflow/` — Pipeline, Processors, Schemas
- **SRT 处理**: `kb_workflow/srt/` — parser, segmenter, corrector
- **CLI 入口**: `kb-workflow/kb_workflow.py process`
- **平台适配器**: BilibiliAdapter, ZhihuAdapter
- **处理器**: ParseProcessor, DownloadProcessor, SRTProcessor, AnalyzeProcessor
- **测试覆盖**: 单元测试 + E2E 集成测试

### 技术栈
- 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 分析内容语义，实现智能分段 | — Pending — v1.6 目标 |
| ASR 纠错可选 | AI 不可用时返回原文 | ✓ Good — 降级策略 |
| 平台路由 | B站视频使用 SRTProcessor，其他使用 AnalyzeProcessor | ✓ Good — 灵活性 |
| disable_reasoning 参数 | ASR 纠错禁用思考模式获得直接结果 | ✓ Good — 避免 AI 分析过程输出 |

---
*Last updated: 2026-03-21 after starting v1.6 milestone*