# kb-skills 工作流重构

## What This Is

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

## Core Value

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

## Requirements

### Validated

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

### Active

- [ ] **PIPE-01**: 统一的管道模型 - 每个步骤是独立管道，输入→处理→输出
- [ ] **PIPE-02**: 步骤级状态管理 - 每个主要步骤完成后记录状态到 workflow_state.json
- [ ] **PIPE-03**: 统一 JSON Schema - 所有子技能遵守统一的输入输出格式规范
- [ ] **PIPE-04**: 幂等执行保证 - 重复执行同一链接不会产生重复文件
- [ ] **PIPE-05**: 错误恢复策略 - 403/超时等错误有明确的降级策略
- [ ] **PIPE-06**: 清晰的流程定义 - 每个步骤的前置条件、输出格式、成功标准明确
- [ ] **PIPE-07**: Schema 验证机制 - 每个步骤输出通过 Schema 验证
- [ ] **PIPE-08**: 代码结构清晰化 - 模块化设计，新人能快速理解和修改

### Out of Scope

- 实时/流式处理 — 批量处理即可，不需要实时
- 并发限制 — 不需要限制并发数量
- 用户界面 — 命令行运行，不需要 Web/UI
- 多语言支持 — 中文即可，不需要国际化
- 微信公众号/小红书 — 当前只支持 B站和知乎

## Context

### 现有架构
- 技能集合：13 个技能模块（kb-* 系列 + gsd-openclaw）
- 主工作流：kb-workflow 协调多个子技能的执行
- 平台支持：B站（视频/专栏）、知乎（问答/专栏/视频）
- 处理类型：视频需要字幕/语音识别，文章直接提取文字

### 已知问题（来自审查报告）
1. **流程不清晰**：执行主体不明确（主代理 vs 子代理），步骤边界模糊
2. **完成要求不明确**：缺少成功标准，失败处理不一致
3. **缺少示例**：没有端到端成功案例，错误处理案例缺失
4. **无状态管理**：没有 workflow_state.json，无法断点续传
5. **格式不明确**：JSON Schema 缺失，字段名不统一，命名规范模糊

### 技术债务
- 环境变量配置分散（~/.kb_env, HF_TOKEN 在子章节, ZHIHU_COOKIE 在子技能）
- 超时和重试机制不明确
- 子技能文档质量参差不齐

## Constraints

- **Tech Stack**: Python 3.12+, 现有依赖库保持不变
- **Compatibility**: 可破坏性更新，不需要向后兼容
- **Scope**: 只支持 B站和知乎两个平台
- **State Granularity**: 步骤级状态管理（不是任务级）

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| 管道模型 | 每个步骤独立，输入→处理→输出，串联执行 | — Pending |
| 步骤级状态 | 记录主要步骤状态（解析→下载→识别→分析），支持断点续传 | — Pending |
| Schema 验证 | 只验证 JSON Schema，内容正确性由步骤保证 | — Pending |
| 全量重构 | 主流程 + 所有子技能一起重构，避免接口不兼容 | — Pending |

---
*Last updated: 2026-03-13 after initialization*