84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# 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*
|