docs: complete project research
This commit is contained in:
@@ -0,0 +1,188 @@
|
||||
# Project Research Summary
|
||||
|
||||
**Project:** kb-skills (Skill-based Workflow Orchestration System)
|
||||
**Domain:** Content Processing Pipeline with LLM Agent Orchestration
|
||||
**Researched:** 2026-03-13
|
||||
**Confidence:** HIGH
|
||||
|
||||
## Executive Summary
|
||||
|
||||
这是一个技能型工作流编排系统，专门用于内容处理管道（视频/文章的元数据提取、ASR识别、AI深度分析）。专家构建此类系统时，通常采用分层架构将编排层、技能定义层、执行层和基础设施层分离，并使用步骤级状态管理实现断点续传和幂等执行。
|
||||
|
||||
基于研究，推荐采用**串行管道编排模式**，使用 `transitions` 状态机管理步骤状态，`Pydantic` 定义 Schema 并实现验证。核心原则是：每个步骤完成后立即持久化状态，失败时可以从断点恢复，重复执行不会产生重复文件。这与 Airflow/Prefect 等重量级编排工具不同——本项目专注于单机批处理场景，无需分布式执行。
|
||||
|
||||
关键风险在于**无状态执行**和**错误上下文丢失**。长时间运行的任务（Whisper识别可能需要30分钟）如果失败后需要从头开始，成本极高。缓解措施是在 Phase 1 就实现 `workflow_state.json` 状态文件，并确保每个步骤输出结构化错误信息。
|
||||
|
||||
## Key Findings
|
||||
|
||||
### Recommended Stack
|
||||
|
||||
推荐使用 Python 3.12+ 作为运行时，配合 Pydantic 2.11+ 进行数据验证和 JSON Schema 生成，transitions 0.9.3+ 实现步骤状态机，Typer + Rich 构建现代化 CLI。这套组合轻量、Pythonic，与项目的 SKILL.md 规范模式完美契合。
|
||||
|
||||
**Core technologies:**
|
||||
- **Pydantic 2.11+**: 数据验证 & Schema 生成 — v2.11+ 解析速度更快，原生支持 JSON Schema，与 PIPE-07 需求匹配
|
||||
- **transitions 0.9.3+**: 状态机 — 轻量级、支持回调和嵌套状态，无需数据库
|
||||
- **pydantic-settings 2.8+**: 配置管理 — 解决现有 `~/.kb_env` 分散配置问题
|
||||
- **Typer 0.15+**: CLI 框架 — 基于 Click 的现代 CLI，利用类型提示自动生成参数
|
||||
- **tenacity 8.5+**: 重试机制 — 实现指数退避重试，处理 API 调用失败
|
||||
|
||||
**避免使用:** Airflow/Celery（过重）、argparse（样板代码多）、requests（同步阻塞）
|
||||
|
||||
### Expected Features
|
||||
|
||||
**Must have (table stakes):**
|
||||
- **步骤级状态管理** — 用户期望能从断点恢复，不重新执行已完成的步骤
|
||||
- **幂等执行** — 相同输入重复执行产生相同结果，无重复文件
|
||||
- **JSON Schema 验证** — 数据契约确保步骤间接口一致性
|
||||
- **结构化错误处理** — 错误消息包含上下文和可操作建议
|
||||
- **平台特定内容处理** — B站/知乎元数据和内容提取
|
||||
|
||||
**Should have (competitive):**
|
||||
- **SKILL.md 声明式技能定义** — AI 代理可发现和执行技能
|
||||
- **多模态内容处理** — 视频(ASR/OCR)+文本统一管道
|
||||
- **Tmux 会话持久化** — 长时间运行操作可断开终端
|
||||
|
||||
**Defer (v2+):**
|
||||
- **并发执行** — 当前串行模式足够，并发增加复杂度
|
||||
- **Web UI** — CLI 优先，可视化需求低
|
||||
- **多租户** — 单用户工具
|
||||
|
||||
### Architecture Approach
|
||||
|
||||
推荐四层架构：编排层（Workflow Coordinator、State Manager、Error Handler）、技能定义层（SKILL.md specs、Schema Definitions）、执行层（Platform/Processing/Analysis Skills）、基础设施层（File System、External APIs、AI Services）。
|
||||
|
||||
**Major components:**
|
||||
1. **State Manager** — 管理 `workflow_state.json`，实现步骤级状态持久化和原子写入
|
||||
2. **Schema Registry** — 统一的输入输出 JSON Schema 定义和验证
|
||||
3. **Pipeline Engine** — 串行执行技能，检查状态跳过已完成步骤
|
||||
4. **Platform Skills** — B站/知乎的元数据提取和内容下载
|
||||
5. **Processing Skills** — Whisper/FunASR 语音识别、OCR 处理
|
||||
6. **Analysis Skills** — kb-deep-analyzer AI 深度分析
|
||||
|
||||
### Critical Pitfalls
|
||||
|
||||
1. **无状态执行 = 从头重来** — Whisper 识别 20 分钟后失败，没有状态文件则需要重新识别。避免：每个步骤完成后写入 `workflow_state.json`
|
||||
|
||||
2. **错误上下文丢失** — 步骤 6 失败只报告 "API error"，不知道是哪个内容、什么输入。避免：结构化 JSON 错误，包含步骤名、输入摘要、失败原因、可操作建议
|
||||
|
||||
3. **假设模型"理解上下文"** — 主代理期望子代理知道之前发生了什么，但每次调用是独立会话。避免：显式传递所有需要的上下文，输入 JSON 自包含
|
||||
|
||||
4. **非幂等操作** — 每次执行创建 `output_1.mp4`、`output_2.mp4`。避免：基于输入生成确定性文件名，已存在则跳过
|
||||
|
||||
5. **环境变量分散** — `~/.kb_env`、子技能配置、HF_TOKEN 分散各处。避免：统一配置文件，启动时检查所有必需变量
|
||||
|
||||
## Implications for Roadmap
|
||||
|
||||
Based on research, suggested phase structure:
|
||||
|
||||
### Phase 1: Foundation (基础设施层)
|
||||
|
||||
**Rationale:** 状态管理和 Schema 验证是所有后续组件的基础，必须首先实现。没有状态文件就无法实现断点续传和幂等执行。
|
||||
**Delivers:** State Manager、Schema Registry、Error Handler、统一配置管理
|
||||
**Addresses:** 步骤级状态管理、幂等执行、JSON Schema 验证、结构化错误处理
|
||||
**Avoids:** 无状态执行、错误上下文丢失、环境变量分散
|
||||
|
||||
**Components:**
|
||||
- `skills/core/state_manager.py` — workflow_state.json 管理
|
||||
- `skills/core/schema_registry.py` — JSON Schema 定义和验证
|
||||
- `skills/core/error_handler.py` — 统一错误处理
|
||||
- `config.py` — pydantic-settings 配置管理
|
||||
|
||||
### Phase 2: Core Skills (核心技能集成)
|
||||
|
||||
**Rationale:** 基于现有技能进行集成，将分散的技能统一到管道模型中。Link Parser 是入口点，无依赖；Platform Skills 依赖其输出。
|
||||
**Delivers:** Link Parser 集成、B站/知乎 Metadata 和 Content 技能适配
|
||||
**Uses:** Pydantic (Schema)、transitions (状态)、Typer (CLI)
|
||||
**Implements:** Pipeline Engine 原型
|
||||
|
||||
**Components:**
|
||||
- Link Parser 技能适配（已有 kb-link-parser）
|
||||
- B站/知乎技能适配（已有 kb-bilibili-*、kb-zhihu-*）
|
||||
- 管道执行引擎原型
|
||||
|
||||
### Phase 3: Processing Skills (处理技能集成)
|
||||
|
||||
**Rationale:** ASR 和 OCR 依赖视频文件，必须在内容下载后执行。这些技能已有实现，需要集成到管道。
|
||||
**Delivers:** Whisper/FunASR 集成、OCR 集成、处理技能状态管理
|
||||
**Addresses:** 多模态内容处理
|
||||
**Avoids:** 假设模型理解上下文 — 显式传递转录结果给分析步骤
|
||||
|
||||
**Components:**
|
||||
- Whisper/FunASR 技能适配
|
||||
- OCR 技能适配
|
||||
- 处理结果 Schema 定义
|
||||
|
||||
### Phase 4: Analysis & Orchestration (分析技能与编排)
|
||||
|
||||
**Rationale:** 深度分析是管道的最终输出，依赖所有前置步骤。编排层整合所有技能形成完整工作流。
|
||||
**Delivers:** Deep Analyzer 集成、完整管道编排、工作流定义文件
|
||||
**Uses:** 所有前置组件
|
||||
**Implements:** 声明式工作流定义 (YAML)
|
||||
|
||||
**Components:**
|
||||
- Deep Analyzer 技能适配
|
||||
- Pipeline Engine 完善
|
||||
- `workflows/video_pipeline.yaml`
|
||||
- `workflows/article_pipeline.yaml`
|
||||
|
||||
### Phase 5: Polish & Testing (完善与测试)
|
||||
|
||||
**Rationale:** 核心功能完成后，补充测试、文档和边缘情况处理。
|
||||
**Delivers:** 单元测试、集成测试、错误恢复策略完善、用户文档
|
||||
**Addresses:** 错误恢复策略、进度可见性
|
||||
|
||||
### Phase Ordering Rationale
|
||||
|
||||
- **依赖关系决定顺序:** State Manager 是所有组件的基础，必须 Phase 1；Analysis 依赖 Processing，Processing 依赖 Platform Skills
|
||||
- **架构模式指导分组:** Foundation -> Skills -> Orchestration 符合分层架构
|
||||
- **避免陷阱:** Phase 1 就实现状态文件和 Schema，防止无状态执行和接口不一致
|
||||
|
||||
### Research Flags
|
||||
|
||||
Phases likely needing deeper research during planning:
|
||||
- **Phase 3:** ASR/OCR 集成可能需要研究 FunASR vs Whisper 选择逻辑，以及 HuggingFace token 缺失时的降级策略
|
||||
- **Phase 4:** AI API 调用的重试策略和超时配置可能需要根据实际使用调整
|
||||
|
||||
Phases with standard patterns (skip research-phase):
|
||||
- **Phase 1:** 状态管理和 Schema 验证是成熟模式，Pydantic/transitions 文档充分
|
||||
- **Phase 2:** 现有技能适配，无需额外研究
|
||||
- **Phase 5:** 测试和文档是标准实践
|
||||
|
||||
## Confidence Assessment
|
||||
|
||||
| Area | Confidence | Notes |
|
||||
|------|------------|-------|
|
||||
| Stack | HIGH | Pydantic/transitions/Typer 都是成熟库，官方文档完善，与项目需求匹配度高 |
|
||||
| Features | HIGH | 基于现有代码库分析和行业标准，功能边界清晰 |
|
||||
| Architecture | HIGH | 四层架构是工作流系统的标准模式，管道编排模式适合内容处理场景 |
|
||||
| Pitfalls | HIGH | 基于多篇研究论文和行业实践，坑点识别充分 |
|
||||
|
||||
**Overall confidence:** HIGH
|
||||
|
||||
### Gaps to Address
|
||||
|
||||
- **ASR 后端选择:** Whisper vs FunASR 的选择逻辑需要根据实际性能测试确定，目前建议支持配置切换
|
||||
- **错误恢复策略细节:** 403/超时等具体错误类型的处理策略需要在实现时细化
|
||||
- **进度汇报机制:** 长时间运行的 Whisper 任务需要进度汇报，具体实现方式待定
|
||||
|
||||
## Sources
|
||||
|
||||
### Primary (HIGH confidence)
|
||||
- Pydantic v2.11 Release & JSON Schema Docs — 技术选型验证
|
||||
- transitions 0.9.3 on PyPI — 状态机库详情
|
||||
- Dagster: Data Pipeline Architecture Design Patterns — 管道模式
|
||||
- AI Architecture Patterns 101: Workflows, Agents — 架构模式
|
||||
- Demystifying Failures in Platform-Orchestrated Workflows (arxiv) — 失败模式研究
|
||||
|
||||
### Secondary (MEDIUM confidence)
|
||||
- Prefect vs Dagster Comparison — 编排工具对比
|
||||
- Multi-Step LLM Chains: Best Practices — LLM 链最佳实践
|
||||
- Data Pipeline State Management (Fivetran) — 状态管理挑战
|
||||
- 9 Things I Hate About Environment Variables — 配置管理问题
|
||||
|
||||
### Tertiary (LOW confidence)
|
||||
- AI Agent Anti-Patterns (Medium) — 反模式识别，需要结合实践验证
|
||||
|
||||
---
|
||||
*Research completed: 2026-03-13*
|
||||
*Ready for roadmap: yes*
|
||||
Reference in New Issue
Block a user