# Stack Research

**Domain:** Skill-based Workflow Orchestration System (Python)
**Researched:** 2026-03-13
**Confidence:** HIGH

## Recommended Stack

### Core Technologies

| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| **Python** | 3.12+ | Runtime | 项目已使用，3.12 提供更好的性能和错误消息；类型提示增强；f-string 改进 |
| **Pydantic** | 2.11+ | 数据验证 & Schema | v2.11+ 提供更快的解析速度、更低的内存占用；原生支持 JSON Schema 生成；与项目 PIPE-07 需求完美匹配 |
| **pydantic-settings** | 2.8+ | 配置管理 | Pydantic 官方配置方案；支持环境变量、.env 文件、类型安全；解决现有 ~/.kb_env 分散配置问题 |
| **transitions** | 0.9.3+ | 状态机 | 轻量级、面向对象的状态机实现；支持回调、条件转换、嵌套状态；无需数据库，适合步骤级状态管理 |
| **Typer** | 0.15+ | CLI 框架 | 基于 Click 的现代 CLI 库；利用 Python 类型提示自动生成参数；比 argparse 更简洁，比 Click 更现代 |
| **Rich** | 14.1+ | 终端输出美化 | 提供彩色输出、进度条、表格；与 Typer 无缝集成；改善 CLI 用户体验 |

### Supporting Libraries

| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| **httpx** | 0.28+ | 异步 HTTP 客户端 | 现有项目已使用；替代 requests 用于需要异步的场景 |
| **tenacity** | 8.5+ | 重试机制 | 实现错误恢复策略 (PIPE-05)；支持指数退避、条件重试 |
| **python-dotenv** | 1.0+ | .env 文件加载 | 与 pydantic-settings 配合；可选，pydantic-settings 已内置支持 |
| **loguru** | 0.7+ | 日志 | 替代 stdlib logging；更简洁的 API；内置旋转、压缩、格式化 |

### Development Tools

| Tool | Purpose | Notes |
|------|---------|-------|
| **uv** | 依赖管理 | 10-100x 快于 pip；兼容 pyproject.toml；支持 lockfile |
| **pytest** | 8.3+ | 测试框架 | 现有项目已使用；配合 pytest-cov 做覆盖率 |
| **ruff** | 0.9+ | Linter + Formatter | 替代 flake8 + black + isort；速度快 |

## Installation

```bash
# Core dependencies
uv add pydantic pydantic-settings transitions typer rich

# Supporting dependencies
uv add httpx tenacity loguru

# Dev dependencies
uv add --dev pytest pytest-cov ruff
```

## Alternatives Considered

| Recommended | Alternative | When to Use Alternative |
|-------------|-------------|-------------------------|
| **transitions** | Prefect 3.0 | 当需要分布式执行、复杂 DAG、Web UI 监控时。但对于本项目的轻量级单机管道，Prefect 过于重量级 |
| **transitions** | Dagster | 当需要数据资产血缘追踪、强类型管道定义时。学习曲线较陡 |
| **transitions** | 纯 JSON 状态 | 当状态极其简单且不需要状态机特性时。但会失去转换验证、回调等安全特性 |
| **Typer** | Click | 当需要更底层的控制或 Typer 的类型推断有问题时。Typer 底层就是 Click |
| **Pydantic** | jsonschema 库 | 当需要验证外部 JSON Schema 且不关心 Python 对象映射时。Pydantic 更 Pythonic |
| **uv** | Poetry | 当团队已熟悉 Poetry 工作流时。但 uv 更快且兼容性更好 |

## What NOT to Use

| Avoid | Why | Use Instead |
|-------|-----|-------------|
| **Airflow** | 需要数据库后端；DAG 定义繁琐；过度工程化 | transitions + 简单状态文件 |
| **Celery** | 需要 message broker；面向任务队列而非工作流编排 | transitions（状态机模式） |
| **argparse** | 样板代码多；无自动帮助生成 | Typer |
| **dataclasses** | 无运行时验证；无 JSON Schema 支持 | Pydantic BaseModel |
| **requests** | 同步阻塞；httpx 提供同步+异步统一 API | httpx |
| **logging (stdlib)** | 配置繁琐；API 不友好 | loguru |

## Stack Patterns by Variant

**If 需要持久化工作流状态到数据库:**
- 添加 SQLAlchemy 2.0+ 作为 ORM
- 配合 alembic 做迁移
- 因为: transitions 状态可以序列化到数据库

**If 需要并发处理多个链接:**
- 使用 asyncio + httpx 异步模式
- 配合 transitions 的 AsyncMachine 扩展
- 因为: 提高吞吐量而不增加复杂度

**If 需要可视化工作流状态:**
- 使用 transitions 的 GraphMachine 扩展
- 生成 Mermaid 或 Graphviz 图表
- 因为: 内置支持，无需额外工具

## Version Compatibility

| Package A | Compatible With | Notes |
|----------|-----------------|-------|
| pydantic 2.11+ | pydantic-settings 2.8+ | 同一组织维护，版本同步更新 |
| typer 0.15+ | rich 14.1+ | Typer 内置 Rich 集成 |
| transitions 0.9.3+ | Python 3.12+ | 支持 Python 3.13 |

## Example Architecture

### 工作流状态 Schema
```python
from pydantic import BaseModel
from enum import Enum
from datetime import datetime

class StepStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    SUCCESS = "success"
    SKIPPED = "skipped"
    FAILED = "failed"

class WorkflowState(BaseModel):
    link: str
    current_step: str
    step_status: dict[str, StepStatus]  # 步骤名 -> 状态
    artifacts: dict[str, str]           # 步骤名 -> 输出文件路径
    errors: list[str]                   # 错误历史
    created_at: datetime
    updated_at: datetime
```

### 管道步骤 Schema 设计
```python
from pydantic import BaseModel
from typing import Literal

class StepInput(BaseModel):
    link: str
    work_dir: str
    # 通用字段...

class StepOutput(BaseModel):
    status: Literal["success", "skipped", "failed"]
    artifacts: dict[str, str]  # 输出文件路径
    error: str | None = None
```

### CLI 入口设计
```python
import typer
from rich.console import Console

app = typer.Typer()
console = Console()

@app.command()
def process(link: str, resume: bool = False):
    """处理单个链接"""
    # transitions 状态机驱动
```

## Sources

- [Pydantic v2.11 Release](https://pydantic.dev/articles/pydantic-v2-11-release) — 版本特性确认 (HIGH confidence)
- [Pydantic JSON Schema Docs](https://docs.pydantic.dev/latest/concepts/json_schema/) — JSON Schema 生成能力 (HIGH confidence)
- [transitions 0.9.3 on PyPI](https://pypi.org/project/transitions/) — 状态机库详情 (HIGH confidence)
- [Prefect vs Dagster Comparison](https://www.prefect.io/compare/dagster) — 编排工具对比 (MEDIUM confidence)
- [Python CLI Tools Comparison 2025](https://dasroot.net/posts/2025/12/building-cli-tools-python-click-typer-argparse/) — CLI 框架对比 (MEDIUM confidence)
- [uv Official Docs](https://docs.astral.sh/uv/) — 包管理器最佳实践 (HIGH confidence)
- [pydantic-settings Guide](https://levelup.gitconnected.com/pydantic-settings-2025-a-clean-way-to-handle-configs-f1c432030085) — 配置管理方案 (MEDIUM confidence)

---
*Stack research for: Skill-based Workflow Orchestration System*
*Researched: 2026-03-13*