# Requirements: kb-skills 工作流重构

**Defined:** 2026-03-13
**Core Value:** 可靠、可维护的处理管道 - 每个步骤独立、可验证、可恢复

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Pipeline Model (管道模型)

- [x] **PIPE-01**: 统一的管道模型 - 每个步骤是独立管道，定义清晰的输入→处理→输出
- [x] **PIPE-02**: 步骤级状态管理 - 主要步骤完成后记录状态到 workflow_state.json，支持断点续传
- [x] **PIPE-03**: 统一 JSON Schema - 所有子技能遵守统一的 StepInput/StepOutput 格式规范

### Reliability (可靠性)

- [x] **REL-01**: 幂等执行保证 - 重复执行同一链接不会产生重复文件或重复处理
- [x] **REL-02**: 错误恢复策略 - 403/超时/网络错误有明确的降级策略和重试机制
- [x] **REL-03**: 清晰的流程定义 - 每个步骤的前置条件、输出格式、成功标准明确

### Validation (验证)

- [x] **VAL-01**: Schema 验证机制 - 每个步骤输出通过 Pydantic Schema 验证，失败则阻止进入下一步

### Maintainability (可维护性)

- [ ] **MNT-01**: 代码结构清晰化 - 模块化设计，新人能快速理解和修改
- [x] **MNT-02**: 统一配置管理 - 环境变量集中在 ~/.kb_env，使用 pydantic-settings 管理
- [x] **MNT-03**: 结构化错误处理 - 错误包含上下文信息，便于调试和日志追踪

### Platform Support (平台支持)

- [x] **PLAT-01**: B站视频处理 - 支持 B站视频的元数据提取、字幕下载、语音识别、深度分析
- [x] **PLAT-02**: B站专栏处理 - 支持 B站专栏的文字提取和深度分析
- [x] **PLAT-03**: 知乎问答/专栏处理 - 支持知乎问答和专栏的文字提取和深度分析

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Advanced Features

- **ADV-01**: 进度可见性 - 实时显示工作流执行进度和预计剩余时间
- **ADV-02**: 并行步骤执行 - 支持独立步骤的并行执行（当前为顺序执行）
- **ADV-03**: 说话者分离默认启用 - HF_TOKEN 配置后自动使用带说话者分离的 Whisper

### Extended Platforms

- **EXT-01**: 微信公众号处理 - 支持微信公众号文章的内容提取
- **EXT-02**: 小红书笔记处理 - 支持小红书笔记的图片下载和文字提取

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| 实时/流式处理 | 批量处理即可，实时处理增加复杂性 |
| 并发限制 | 不需要限制并发数量，单机执行 |
| 用户界面 | 命令行运行，不需要 Web/UI |
| 多语言支持 | 中文即可，不需要国际化 |
| 分布式部署 | 单机执行，不需要分布式编排 |
| 工作流可视化 | 配置文件足够，不需要可视化编辑器 |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| PIPE-01 | Phase 1 | Complete |
| PIPE-02 | Phase 1 | Complete |
| PIPE-03 | Phase 1 | Complete |
| REL-01 | Phase 1 | Complete |
| REL-02 | Phase 1 | Complete |
| REL-03 | Phase 1 | Complete |
| VAL-01 | Phase 1 | Complete |
| MNT-02 | Phase 1 | Complete |
| MNT-03 | Phase 1 | Complete |
| PLAT-01 | Phase 2 | Complete |
| PLAT-02 | Phase 2 | Complete |
| PLAT-03 | Phase 2 | Complete |
| MNT-01 | Phase 4 | Pending |

**Coverage:**
- v1 requirements: 12 total
- Mapped to phases: 12
- Unmapped: 0

---
*Requirements defined: 2026-03-13*
*Last updated: 2026-03-13 after roadmap creation*