Stabilize：持久化工作流引擎，AI Agent 的可靠调度底座

Stabilize 项目 Logo / 仓库截图（本项目 README 未内置图片，以上为作者 GitHub 头像）

---

场景切入：为什么你的 AI Agent 总在关键时刻"掉链子"？

深夜，你的 AI Agent 正在处理一份 200 页的法律合同摘要。它调用了 6 次外部 API，翻阅了数十个章节，进度已完成了 80%。就在这时——服务器断电了。进程被强制终止，所有中间状态丢失。第二天重启时，Agent 从头开始，重新花了两小时重复已经做过的工作。

这是每一个 AI 应用开发者都曾面对的噩梦。LLM Agent 具有"长时间运行、外部调用频繁、需要循环等待"的天然特性，传统任务队列（Celery）管不了它的状态，复杂编排引擎（Airflow）又太重。Stabilize 正是为解决这个痛点而生。

---

项目背景：Durable Execution 的轻量实现

Stabilize 是由 rodmena-limited 团队开发的持久化工作流执行引擎，定位介于简单任务队列与重型编排平台之间。它诞生于真实 AI Agent 项目的工程实践中，核心设计目标是为"长时间运行、有状态、不允许丢失进度"的 AI 工作流提供可靠调度。

项目的核心卖点可以归结为一句话：把 DAG 写好，Stabilize 来跑——自动并行、自动容错、自动从崩溃点恢复。

作者 Farshid Ashouri 在 README 中明确提到：项目不仅面向通用工作流编排，更是专为 Agentic AI 系统优化。这一明确的场景定位让 Stabilize 在同类工作流引擎中找到了差异化的生存空间。

---

核心功能：从 DAG 定义到智能执行的完整链路

1. DAG 驱动的任务编排

开发者通过 Python 代码定义有向无环图（DAG），Stabilize 自动分析依赖关系，在允许的地方并行执行，并在图节点之间传递状态：

from stabilize import Workflow, Stage, Task

workflow = Workflow(
    name="contract-analysis",
    stages=[
        Stage(name="fetch", task=FetchDocTask()),
        Stage(name="analyze", task=AnalyzeDocTask(), after=["fetch"]),
        Stage(name="report", task=GenerateReportTask(), after=["analyze"]),
    ]
)

Stabilize 不需要单独的服务器或调度进程——它以内嵌方式运行在你的 Python 进程中，数据存储在 SQLite（单进程）或 PostgreSQL（多节点部署）。

2. 崩溃恢复与状态持久化

这是 Stabilize 与 Celery、 Prefect 等主流任务队列最大的区别。每个 Stage 的执行结果（TaskResult）都会被持久化，一旦发生崩溃或重启，引擎从上次中断的 Stage 精确恢复，而不是从头重跑整个流程。这种"Durable Execution"能力对 AI Agent 至关重要——一次 LLM API 调用可能耗时数十秒，崩溃重跑的成本极高。

3. 内置 LLM Agent 工具包（stabilize.llm）

Stabilize 不满足于做一个通用引擎，它直接捆绑了一个专为 LLM 应用设计的工具包，零额外依赖（仅用标准库 urllib）：

• LLMClient：OpenAI 兼容客户端，同时支持 Ollama（本地部署）。同一套代码无缝切换本地模型和云端 API，对需要在开发环境用本地模型、正式环境用 GPT-4 的团队非常友好。
• AgentLoopTask：将 ReAct（Reason + Act）工具调用循环封装为单个工作流 Stage，内置重试和工具选择逻辑。
• tool 装饰器 + ToolRegistry：轻量注册机制，让 Agent 的工具定义和调度都变得声明式。

4. Human-in-the-Loop（人工介入）

hitl.py 模块提供了优雅的人工审批机制。当工作流执行到关键节点（如合同金额超阈值）时，自动暂停等待人工确认；确认结果通过持久化信号机制传递，即使审批期间系统崩溃也能正确恢复。这是企业级 AI 应用不可或缺的治理能力。

5. 与 Highway 工作流引擎的集成

Stabilize 还支持作为控制平面调用外部工作流引擎（如 Highway），自己只存储 run_id，具体执行委托给第三方。这种"编排之上的编排"设计让它可以融入已有的工程体系，而不是要求团队完全重构。

---

技术架构：模块化设计，专注持久化核心

技术栈

层次	技术选型
核心框架	Python 3.11+，Pydantic v2（数据建模）
消息队列	嵌入式 SQLite / PostgreSQL（原子化队列操作）
工作流持久化	bulkman（数据抽象）+ migretti（PostgreSQL 迁移）
容错机制	resilient-circuit（熔断/重试）
LLM 工具包	标准库 urllib（零额外依赖）
观测性	OpenTelemetry + structlog（可选接入）

目录结构（核心模块）

src/stabilize/
├── orchestrator.py     # 编排器：启动/暂停/恢复/取消工作流
├── dag/                # DAG 解析与拓扑排序
├── queue/              # 原子消息队列（SQLite/PostgreSQL）
├── persistence/        # 工作流状态持久化
├── stages/             # Stage 定义与执行
├── tasks/              # 内置任务类型
├── llm/                # LLM Agent 工具包（client, tasks, tools）
├── hitl.py             # Human-in-the-Loop 机制
├── events/             # 事件溯源（Event Sourcing）
├── handlers/           # 消息处理器（workflow_control 等）
├── monitoring/         # 监控与指标
└── tracing.py          # 分布式追踪

架构上，Stabilize 将消息队列与工作流存储进行了原子化整合——每次状态变更同时写入队列消息和数据库，确保两者一致。这种设计在分布式场景下避免了"队列有记录但数据库没更新"的漂移问题。

---

上手体验：开发者体验优于运维体验

安装与运行

pip install stabilize

安装后获得：

• Python API（from stabilize import ...）
• CLI 入口（stabilize 命令）

from stabilize import Workflow, Orchestrator, SqliteQueue, SqliteWorkflowStore

queue = SqliteQueue("workflows.db")
store = SqliteWorkflowStore("workflows.db")
orchestrator = Orchestrator(queue=queue, store=store)

没有 Dockerfile，也没有 docker-compose。对于习惯容器化部署的团队来说，这是当前版本的明显短板。不过项目自带的 examples/ 目录提供了 10+ 个完整示例，涵盖 HTTP 调用、Shell 脚本、多 Agent 协作、本地 Ollama 集成等常见场景，直接运行示例是最佳入门路径。

AI Coding Agent 集成（特色功能）

Stabilize 提供了一个极其贴心的功能——为 AI 编码助手自动生成 API 参考文档：

pip install stabilize
stabilize prompt > stabilize.md

生成的 stabilize.md 包含完整的 API 文档、可运行模板和工作流模式说明，AI Agent 只需读取这一个文件就能掌握全部用法。这对于 Cursor、Claude Code、Copilot 等 AI 辅助编程工具来说是真正的工程福利。

文档质量

项目配置了 ReadTheDocs 文档系统，目录结构清晰（docs/guide、docs/api、docs/references），README 本身即是完整的入门教程，篇幅长达 19,000 字符。代码中大量使用类型注解（pyright 配置），IDE 支持完善。

---

局限与挑战：不回避的工程现实

1. 容器化缺失

当前版本不提供 Dockerfile 或 docker-compose，对于需要在容器环境中运行的团队（Kubernetes 部署、微服务架构），需要自行编写 Dockerfile。这在 2024 年的开源生态中是一个不可忽视的短板。

2. 生态尚处早期

• Stars 仅 86（截至分析时），社区规模和活跃度有限
• 第三方插件和预置模板库尚未形成生态
• 与 LangGraph、AutoGen 等成熟 Agent 框架相比，知名度和社区支持差距明显

3. Python 版本门槛

仅支持 Python 3.11+（截至 3.14），无法在遗留 Python 3.9/3.10 项目中使用。这对于需要维护旧版代码库的团队是一个限制因素。

4. PostgreSQL 支持有额外依赖

PostgreSQL 多节点部署需要安装 psycopg[pool] 和 migretti，增加了运维复杂度；而 SQLite 单进程模式在并发场景下天然受限。

---

行业意义：填补 Agent 编排的中间地带

AI Agent 工作流编排领域存在一个典型矛盾：Celery/ RQ 等简单队列擅长"发任务等结果"，但管不了 DAG 依赖和状态恢复；Airflow/Dagster 等成熟平台功能强大，但运维成本高、启动慢，与 LLM Agent 的快速迭代节奏格格不入。

Stabilize 的价值主张是：在单进程内实现 DAG 编排 + 持久化 + 容错，让 AI Agent 的调度像写普通 Python 代码一样简单。 这种"Durable Execution as a Library"的思路，与 Temporal 的设计哲学高度共鸣，但更轻量、更 Pythonic。

v0.20.0 版本刚完成一次 Peer Review 安全审计，修复了 10 个发现项并验证了审计证书，展示了团队对代码质量的重视。随着 AI Agent 应用场景的持续扩展，像 Stabilize 这样专注于"Agent 可靠运行"的基础设施将会获得更多关注。

---

总结：谁应该关注 Stabilize？

适合场景：

• AI 应用开发团队，需要为 LLM Agent 添加可靠的进度保存和崩溃恢复
• 需要在 Python 中快速编排多阶段 DAG 任务的中小型项目
• 对接本地 Ollama 模型，希望零依赖运行 LLM Agent 工作流的开发者
• 有 Human-in-the-Loop 审批需求的企业 AI 应用

需要考虑的场景：

• 需要 Kubernetes 容器化部署 → 需自行编写 Dockerfile
• 需要与现有 Airflow/Dagster 生态集成 → 建议评估 Temporal 或直接使用成熟平台
• 低 Stars 项目，依赖社区支持 → 评估代码质量后谨慎采用

一句话评价： Stabilize 精准命中了 AI Agent 开发者"想要 Celery 的简单度 + Airflow 的可靠性 + LangChain 的 Agent 原生支持"的需求，是当前生态中少见的专注"Agent 持久化执行"的 Python 优先解决方案，值得在小型 AI 应用原型阶段优先测试。