Metadata-Version: 2.4
Name: stateforge
Version: 0.5.0
Summary: StateForge - 基于确定性状态机的 Agent 工作流框架
Author-email: zhyeung <zhyeung@qq.com>
License: AGPL-3.0
Project-URL: Homepage, https://gitee.com/zhyeung/stateforge
Project-URL: Issues, https://gitee.com/zhyeung/stateforge/issues
Keywords: agent,state-machine,workflow,ai,langgraph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph>=0.2.0
Requires-Dist: openai>=1.0.0
Requires-Dist: qdrant-client>=1.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: redis>=5.0.0
Requires-Dist: minio>=7.2.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: sandbox
Requires-Dist: fastapi>=0.110.0; extra == "sandbox"
Requires-Dist: uvicorn[standard]>=0.27.0; extra == "sandbox"
Requires-Dist: websockets>=12.0; extra == "sandbox"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Dynamic: license-file

# StateForge

<div align="center">

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

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

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-AGPLv3-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/Status-Alpha-orange.svg)]()

</div>

---

## 这是什么？

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 的上层建筑——给通用图编排加上了"项目共识达成"的特定骨架。**

---

## 快速开始

### 安装

```bash
pip install stateforge
```

### 5 分钟跑通最小闭环

```python
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树来实现设计和开发等任务

### 开发环境搭建

```bash
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](../AGENTS.md)。

---

## 它是哪个产品的一部分？

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

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

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

---

## 许可证

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

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

---

<div align="center">
  <p>
    <strong>StateForge</strong> — 锻造共识引擎，让 AI 可控、可追溯、可验证。
  </p>
  <p>
    <a href="https://gitee.com/zhyeung/stateforge">Gitee</a> ·
    <a href="https://github.com/zhyeung/stateforge">GitHub</a>
  </p>
</div>
