kb-skills/.planning/research/SUMMARY.md

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