stateforge 0.5.0

StateForge - 基于确定性状态机的 Agent 工作流框架

StateForge

基于确定性状态机的 Agent 工作流框架

用 State 树约束 AI 行为，算法优先，让 Agent 服务于流程而非主导流程。

---

这是什么？

StateForge 是一个全新的 Agent 开发框架。它不依赖“让 AI 自己琢磨该干什么”，而是用一棵确定性的状态树来定义所有可能性，然后让 AI 只在极窄的节点上做推理。

一句话：代码负责流程，AI 负责决策。代码走不通的才给 AI，AI 的输出立刻被代码验证。

---

为什么需要 StateForge？

现有的 Agent 框架有一个共同问题：把太多事交给 AI。

框架	问题
AutoGPT / BabyAGI	目标分解后自主循环，容易跑偏，无法与用户协同确认
LangChain / CrewAI	链式调用灵活但无状态约束，长对话中容易遗忘已确认事项
OpenAI Function Calling	无状态，无长期项目上下文，无法处理复杂多步确认

StateForge 的核心洞察是：项目中 80% 的"思考"其实是状态流转——确定性的事，不该消耗 AI Token。

传统 Agent：用户输入 → AI 全权处理 → 输出
StateForge：用户输入 → 代码遍历状态树 → 找到当前聚焦点 → 仅此节点交给 AI → AI 输出被代码验证 → 更新状态

---

StateForge 在 PRD / Vibe Coding中的用途

AI PRD 的核心痛点不是"AI 不够聪明"，而是上下文太长、Token 太贵、模型太容易跑偏。你和一个 Agent 聊了 30 轮，它忘了第 3 轮确认过的登录方式，开始在第 31 轮建议你"要不要考虑手机号验证码登录"——你已经确认过的事。

StateForge 解决这个问题的方式非常直接：把无限对话变成有限状态机。

聚焦当前模块节点

整个项目的所有功能、角色、风险、约束，都被组织成一棵 State 树。当前在讨论"微信支付"时，Agent 的视野里只有这一个节点和它的父节点约束。用户系统、商品管理、优惠券——那些几百个兄弟节点，Agent 完全不知道，也不需要知道。

不是"请为这个商城项目设计支付方案"，而是"当前支付方式已确认微信支付，请检查是否需要补充退款逻辑验收标准，约束：必须用 API v3。"

上下文从几千 Token 压到一两百 Token。便宜模型也能给出精准回答。

减少 Token，用便宜模型

在 StateForge 的确认分层体系里：

• L3 节点（按钮圆角、默认字体、分页数量）：AI 根本不参与，代码直接填充默认值。Token 消耗 = 0。
• L2 节点（登录方式组合、通知渠道）：规则 + 缓存命中，60-80% 的场景不需要模型。
• L1 节点（支付方式、隐私合规、直播资质）：才调用模型，上下文极窄，便宜模型即可胜任。

一个完整项目的 AI Token 消耗，从传统 Agent 的几十万 Token 降到几千 Token。你完全可以用 GPT-4o mini 甚至本地 1.5B 模型跑完大部分流程。

减少长上下文依赖

对话历史不再是无结构的文本流。每一轮对话的结果都被结构化地存入 State 树节点。下一轮 AI 拿到的不是"过去 20 轮的对话摘要"，而是：

当前节点：feat_payment_wx_refund
状态：in_progress
父节点约束：微信支付 API v3、需企业资质
已确认的兄弟节点：微信支付、支付宝支付

三行结构化上下文，替代三千字对话历史。AI 不会遗忘，因为它根本不需要"记住"——State 树替它记了。

---

核心架构

┌─────────────────────────────────────────┐
│              用户输入                    │
└───────────────┬─────────────────────────┘
                ▼
┌─────────────────────────────────────────┐
│          意图分类器（规则 + 轻量模型）    │
│     confirm / skip / modify / new / ...  │
└───────────────┬─────────────────────────┘
                ▼
┌─────────────────────────────────────────┐
│          输入路由器（分流决策）           │
│     ├─ 缓存/硬编码 → 直接更新 State      │
│     └─ RAG + Agent → 窄域推理            │
└───────────────┬─────────────────────────┘
                ▼
┌─────────────────────────────────────────┐
│          State 树引擎（确定性代码）       │
│     遍历 · 状态传播 · 完整性校验 · 回滚  │
└───────────────┬─────────────────────────┘
                ▼
┌─────────────────────────────────────────┐
│          事件溯源层（不可变日志）         │
│     一切状态变更是事件流重放的结果        │
└─────────────────────────────────────────┘

---

核心模块

模块	职责	一句话
stateforge.state	State 树引擎	遍历、状态传播、约束检查——纯 Python，零 AI 依赖
stateforge.workflow	Agent 工作流编排	Explorer / Confirmer / Summarizer / Compiler 四角色 Agent
stateforge.intent	意图分类	规则层（60-70%）+ 轻量模型兜底（LLM Intent Classifier）
stateforge.events	事件溯源	不可变事件流 + 回放重建 + 时间点快照
stateforge.providers	抽象基类	LLMProvider / VectorStore / StorageBackend / EventBus 注入接口
stateforge.rag	RAG 检索	三层知识库（L1 元数据 / L2 范式 / 关键词触发 + 内存缓存）
stateforge.domain	多领域扩展	领域骨架生成 + 预置领域定义（软件 / 设计 / 海报）
stateforge.sandbox	沙箱环境	WebSocket 对话后端 + 演示 State 树 + 意图分类端到端

---

与 LangGraph 的关系

StateForge 依赖 LangGraph 做 Agent 图编排，但提供了一整套 LangGraph 没有的能力：

• 内置状态树：LangGraph 的状态定义完全自由，StateForge 提供了为"项目共识"预置的树形结构
• 操作指令集：Agent 不能直接改状态，必须通过 add_child / confirm_node 等指令，由引擎执行
• 确认分层：L1（必确认）/ L2（建议确认）/ L3（自动填充）三级交互强度
• 事件溯源：所有变更可回放、可审计、可分支
• Compiler Agent：所有节点确认后自动生成《软件功能规格书》Markdown

StateForge 是 LangGraph 的上层建筑——给通用图编排加上了"项目共识达成"的特定骨架。

---

快速开始

安装

pip install stateforge

5 分钟跑通最小闭环

from stateforge.state import StateNode, StateTree
from stateforge.intent import IntentClassifier
from stateforge.events import InMemoryEventStore, ProjectState
import asyncio

async def main():
    # 1. 创建一棵 State 树（硬编码示例）
    root = StateNode(
        id="root",
        name="微信商城",
        description="基础微信商城需求确认",
        level="L1",
        children=[
            StateNode(id="feat_user", name="用户系统", description="选择登录方式", level="L1", children=[
                StateNode(id="login_phone", name="手机号登录", level="L2"),
                StateNode(id="login_wx", name="微信授权登录", level="L2"),
            ]),
            StateNode(id="feat_pay", name="支付系统", level="L1", children=[
                StateNode(id="pay_wx", name="微信支付", level="L2"),
            ]),
        ]
    )

    # 2. 初始化引擎
    tree = StateTree(root)
    event_store = InMemoryEventStore()
    project = ProjectState("demo-project", event_store)
    classifier = IntentClassifier()

    # 3. 主循环：找到当前聚焦点 → 模拟用户输入 → 更新状态
    while focus := tree.find_next_focus():
        print(f"\n当前聚焦: [{focus.level}] {focus.name} - {focus.description}")

        # 模拟用户确认
        intent = await classifier.classify("好的，就这个", focus)
        if intent.intent == "confirm":
            tree.confirm_node(focus.id, source="user")
            print(f"  ✅ 已确认: {focus.name}")
        elif intent.intent == "skip":
            tree.skip_node(focus.id)
            print(f"  ⏭️ 已跳过: {focus.name}")

    print("\n🎉 所有项目确认完毕！")

asyncio.run(main())

输出效果：

当前聚焦: [L1] 用户系统 - 选择登录方式
  ✅ 已确认: 用户系统

当前聚焦: [L2] 手机号登录
  ✅ 已确认: 手机号登录

当前聚焦: [L2] 微信授权登录
  ✅ 已确认: 微信授权登录

当前聚焦: [L1] 支付系统
  ✅ 已确认: 支付系统

当前聚焦: [L2] 微信支付
  ✅ 已确认: 微信支付

🎉 所有项目确认完毕！

---

开发路线图

Sprint	目标	状态
Sprint 1	State 树引擎 + 事件溯源 + 意图分类规则层 + 沙箱骨架	✅ 完成
Sprint 2	LLM 意图分类兜底 + RAG 检索 + Explorer Agent 工作流 + 沙箱 AI 集成	✅ 完成
Sprint 3	Compiler Agent 交付物生成 + 多领域扩展配置	✅ 完成
Sprint 4	模板市场 + 专家委员会 + 产能系统	📋 计划中

---

贡献指南

StateForge 是一个开源优先的项目。我们欢迎所有形式的贡献。

你可以做什么？

• 提 Issue：发现 Bug 或有功能建议？直接开 Issue
• 改进文档：README、API 文档、教程——文档是开源项目的脸面
• 写测试：我们追求 State 引擎和事件溯源 100% 测试覆盖
• 贡献代码：从 good first issue 标签开始
• 讨论架构：在 Discussions 区参与核心设计的讨论
• 开发State：使用[solomate-sandbox]来开发、测试state模板，你可以使用这个模板来完成自己的prd任务，也可以发布到[solomate]的市场（Sprint 5）
• 开发基于本框架的Agent工具：solomate和solomate-sandbox生成的最终产物包含了state树和文档，Agent工具可以基于这个state树来实现设计和开发等任务

开发环境搭建

git clone https://gitee.com/zhyeung/stateforge.git
cd stateforge
python -m venv .venv
.venv\Scripts\activate  # Windows
pip install -e ".[dev]"
pytest

提交规范

• feat: 新功能
• fix: 修复
• docs: 文档
• refactor: 重构
• test: 测试
• chore: 杂项

架构规则（不可妥协）

• stateforge/state/ 目录禁止 import langgraph 或 import openai
• 任何 State 变更必须通过 EventStore，禁止直接修改 StateNode
• Agent 只输出操作指令，由 InstructionExecutor 执行
• 所有外部依赖通过抽象基类注入

详见 AGENTS.md。

---

它是哪个产品的一部分？

StateForge 是 [SoloMate] 的核心引擎。SoloMate 是一个帮助独立开发者（SOLO）接单、挖掘需求、达成共识、生成交付物的 AI 平台。

StateForge 负责"状态机 + 工作流"部分，以 AGPLv3 协议独立开源。这意味着：

• 个人开发者可以免费使用 StateForge 构建自己的项目
• 如果你用它做 SaaS 服务，需要开源你的修改或购买商业授权
• 我们欢迎社区贡献，一起把"确定性约束 AI"这个范式做深

---

许可证

StateForge 采用 GNU Affero General Public License v3 (AGPLv3) 协议。

核心框架永久开源。商业授权（如闭源 SaaS 使用、多租户模块、商业知识库）请联系我们。

---

StateForge — 锻造共识引擎，让 AI 可控、可追溯、可验证。

Gitee · GitHub