# 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*