# flowforge

**Repository Path**: cxunmz/flowforge

## Basic Information

- **Project Name**: flowforge
- **Description**: FlowForge 是一个开源项目，专注于提供强大的工作流编排工具，帮助开发者高效构建和管理复杂的应用流程。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-13
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎨 FlowForge

**可视化节点编程工具** - 支持自定义数据类型、自定义节点和实时执行

[![Status](https://img.shields.io/badge/状态-完成-brightgreen)]()
[![Version](https://img.shields.io/badge/版本-1.0.0-blue)]()

---

## ✨ 核心特性

- 🎨 **可视化节点编程** - 拖拽式流程图编辑器
- 🔧 **自定义节点** - 使用 Python 编写节点逻辑
- 📦 **自定义数据类型** - 定义数据结构和验证规则
- 💻 **Monaco Editor** - 专业代码编辑器（VS Code 内核）
- 🔄 **实时通信** - WebSocket 双向通信
- 🏷️ **分组管理** - 节点和数据类型分组组织

---

## 🚀 快速开始

### 方式一：Web 浏览器

```bash
# 终端 1 - 启动后端
./start-backend.sh

# 终端 2 - 启动前端
./start-frontend.sh
```

然后访问 http://localhost:5173

### 方式二：命令行运行工程（无 UI）

```bash
source backend/venv/bin/activate
python runner.py default.json
```

详见 [docs/quick-start.md](docs/quick-start.md)。

---

## 🛠️ 技术栈

### 前端
- **React** 19.2.0 - UI 框架
- **TypeScript** 5.9.3 - 类型安全
- **Monaco Editor** 4.7.0 - 代码编辑
- **React Flow** 11.11.4 - 流程图编辑
- **Zustand** 5.0.10 - 状态管理
- **Vite** 7.3.1 - 构建工具

### 后端
- **Python** 3.10+ - 后端语言
- **WebSocket** - 实时通信
- **asyncio** - 异步执行

---

## 📁 项目结构

```
cgraph/
├── runner.py              # 命令行运行器（python runner.py default.json）
├── frontend/              # React 前端
│   ├── src/               # 源代码
│   │   ├── components/    # UI 组件
│   │   ├── store/         # 状态管理
│   │   └── services/      # WebSocket 服务
│   └── dist/              # 构建输出
├── backend/               # Python 后端
│   ├── app/               # 应用模块
│   │   ├── server.py      # WebSocket 服务器
│   │   └── node_engine.py # 节点执行引擎
│   └── venv/              # 虚拟环境
├── docs/                  # 文档
├── start-backend.sh       # 后端启动脚本
└── start-frontend.sh      # 前端启动脚本
```

---

## 📖 文档

| 文档 | 说明 |
|------|------|
| [docs/quick-start.md](docs/quick-start.md) | 5分钟快速开始 |
| [docs/setup.md](docs/setup.md) | 开发环境搭建 |
| [docs/docker.md](docs/docker.md) | Docker 打包与运行 |
| [docs/mcp.md](docs/mcp.md) | MCP 协议与工具 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献指南 |
| [SECURITY.md](SECURITY.md) | 安全策略 |
| [docs/changelog.md](docs/changelog.md) | 更新日志 |

---

## 🎯 主要功能

### 1. 数据类型管理
- 创建自定义数据类型
- 编写验证和预览逻辑（check, default, preview）
- 分组组织管理

### 2. 节点编辑
- 使用 Monaco Editor 编写节点代码
- Python 语法高亮和代码补全
- 实时代码编辑

### 3. 流程图编辑
- 拖拽添加节点到画布
- 连接节点输入输出端口
- 可视化数据流

### 4. 项目执行
- 后端动态加载并执行节点代码
- 实时状态同步
- FlowForge API (ff.input/ff.output/ff.param)

---

## 🔧 开发指南

### 环境要求

- Node.js 18+
- Python 3.10+
- npm 或 yarn

### 安装依赖

**前端：**
```bash
cd frontend
npm install
```

**后端：**
```bash
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

**AI 助手配置（可选）：** 若需使用内置 AI 助手，请复制配置模板并填写 API Key：
```bash
cp backend/app/ai_config.example.json backend/app/ai_config.json
# 编辑 ai_config.json，将 key 替换为实际的 API Key
```

### 开发模式

**Web 开发：**
```bash
# 终端 1
cd backend && source venv/bin/activate && python main.py

# 终端 2
cd frontend && npm run dev
```

### 构建打包
```bash
cd frontend
npm run build
```

---

## 🎉 项目状态

**✅ 完全完成** - 所有核心功能已实现并测试通过

- ✅ React 前端应用
- ✅ Python 后端引擎
- ✅ 完整文档系统
- ✅ Docker 镜像支持

---

## 📞 获取帮助

- 查看 [docs/quick-start.md](docs/quick-start.md) 快速上手
- 查看 [docs/setup.md](docs/setup.md) 了解安装与配置

---

## 📄 许可证

MIT License

---

**立即开始使用 FlowForge！** 🚀

```bash
./start-backend.sh
# 另一终端
./start-frontend.sh
```