6.8 KiB
6.8 KiB
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+ | 测试框架 |
| ruff | 0.9+ | Linter + Formatter |
Installation
# 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
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 设计
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 入口设计
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 — 版本特性确认 (HIGH confidence)
- Pydantic JSON Schema Docs — JSON Schema 生成能力 (HIGH confidence)
- transitions 0.9.3 on PyPI — 状态机库详情 (HIGH confidence)
- Prefect vs Dagster Comparison — 编排工具对比 (MEDIUM confidence)
- Python CLI Tools Comparison 2025 — CLI 框架对比 (MEDIUM confidence)
- uv Official Docs — 包管理器最佳实践 (HIGH confidence)
- pydantic-settings Guide — 配置管理方案 (MEDIUM confidence)
Stack research for: Skill-based Workflow Orchestration System Researched: 2026-03-13