From ab952f4c69a56430944fce031a7a9f0ec32c0a03 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Fri, 13 Mar 2026 15:55:57 +0800 Subject: [PATCH] docs: define v1 requirements --- .planning/REQUIREMENTS.md | 93 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..aac952f --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,93 @@ +# Requirements: kb-skills 工作流重构 + +**Defined:** 2026-03-13 +**Core Value:** 可靠、可维护的处理管道 - 每个步骤独立、可验证、可恢复 + +## v1 Requirements + +Requirements for initial release. Each maps to roadmap phases. + +### Pipeline Model (管道模型) + +- [ ] **PIPE-01**: 统一的管道模型 - 每个步骤是独立管道，定义清晰的输入→处理→输出 +- [ ] **PIPE-02**: 步骤级状态管理 - 主要步骤完成后记录状态到 workflow_state.json，支持断点续传 +- [ ] **PIPE-03**: 统一 JSON Schema - 所有子技能遵守统一的 StepInput/StepOutput 格式规范 + +### Reliability (可靠性) + +- [ ] **REL-01**: 幂等执行保证 - 重复执行同一链接不会产生重复文件或重复处理 +- [ ] **REL-02**: 错误恢复策略 - 403/超时/网络错误有明确的降级策略和重试机制 +- [ ] **REL-03**: 清晰的流程定义 - 每个步骤的前置条件、输出格式、成功标准明确 + +### Validation (验证) + +- [ ] **VAL-01**: Schema 验证机制 - 每个步骤输出通过 Pydantic Schema 验证，失败则阻止进入下一步 + +### Maintainability (可维护性) + +- [ ] **MNT-01**: 代码结构清晰化 - 模块化设计，新人能快速理解和修改 +- [ ] **MNT-02**: 统一配置管理 - 环境变量集中在 ~/.kb_env，使用 pydantic-settings 管理 +- [ ] **MNT-03**: 结构化错误处理 - 错误包含上下文信息，便于调试和日志追踪 + +### Platform Support (平台支持) + +- [ ] **PLAT-01**: B站视频处理 - 支持 B站视频的元数据提取、字幕下载、语音识别、深度分析 +- [ ] **PLAT-02**: B站专栏处理 - 支持 B站专栏的文字提取和深度分析 +- [ ] **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 | Pending | +| PIPE-02 | Phase 1 | Pending | +| PIPE-03 | Phase 1 | Pending | +| REL-01 | Phase 1 | Pending | +| REL-02 | Phase 1 | Pending | +| REL-03 | Phase 1 | Pending | +| VAL-01 | Phase 1 | Pending | +| MNT-02 | Phase 1 | Pending | +| MNT-03 | Phase 1 | Pending | +| PLAT-01 | Phase 2 | Pending | +| PLAT-02 | Phase 2 | Pending | +| PLAT-03 | Phase 2 | Pending | +| MNT-01 | Phase 5 | Pending | + +**Coverage:** +- v1 requirements: 12 total +- Mapped to phases: 12 +- Unmapped: 0 ✓ + +--- +*Requirements defined: 2026-03-13* +*Last updated: 2026-03-13 after initial definition*