165 lines
6.8 KiB
Markdown
165 lines
6.8 KiB
Markdown
# 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*
|