Initial commit

2026-06-11 01:49:21 +08:00
commit 1c0296fa80
@@ -0,0 +1,215 @@
+# GopherGraph
+
+A lightweight, high-performance, and type-safe Multi-Agent workflow orchestration engine written in Go.  
+基于 Go 语言（泛型）实现的轻量级、高性能、类型安全的多智能体（Multi-Agent）协同与任务编排引擎。  
+Go 言語（ジェネリクス）で書かれた、軽量・高性能・型安全なマルチエージェント・ワークフロー協調エンジン。
+
+---
+
+* [简体中文](#-简体中文)
+* [English](#-english)
+* [日本語](#-日本語)
+
+---
+
+## 简体中文
+
+### 简介
+`GopherGraph` 是一个用 Go 语言编写的代码即图（Code-as-Graph）智能体编排引擎，设计灵感来源于 Python 生态的 `LangGraph`。它利用 Go 1.18+ 的泛型机制，让工作流的上下文状态在编译期就具备强类型约束，并依靠 Go 原生的 Goroutines 和 Channels 实现极高并发的本地数据流转。它特别适合构建包含复杂循环（Looping）和人机协同（Human-in-the-Loop）的智能体工作流。
+
+### 核心特性
+- **强类型状态管理：** 利用 Go 泛型定义全局状态 `Graph[S]`，彻底告别松散的 `map[string]any` 和繁琐的类型断言。
+- **支持循环结构：** 突破了传统 DAG（有向无环图）工作流的限制，原生支持节点间的双向循环和条件路由。
+- **人机协同中断 (HITL)：** 支持在特定节点前自动挂起，返回执行线程快照，等待人工修改状态或审批通过后一键恢复 (`Resume`)。
+- **纯粹的高性能：** 基于内存流转，零外部依赖，极低的上下文切换开销。
+
+### 快速开始
+
+#### 1. 定义您的状态 (State)
+```go
+type MyState struct {
+    Query    string
+    Response string
+}
+```
+
+#### 2. 构建工作流图
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "GopherGraph"
+)
+
+func main() {
+    // 初始化一个强类型的图构建器
+    g := GopherGraph.NewGraph[MyState]()
+
+    // 注册节点 (Node)
+    g.AddNode("agentA", func(ctx context.Context, s MyState) (MyState, error) {
+        s.Response = "Hello from Agent A"
+        return s, nil
+    })
+
+    // 建立连线 (Edge)
+    g.AddEdge("agentA", "anotherNode")
+    
+    // 设置中断拦截点 (Interrupt)
+    g.AddInterrupt("anotherNode")
+
+    // 编译图
+    cg, _ := g.Compile()
+
+    // 启动运行
+    thread, _ := cg.Start(context.Background(), "agentA", MyState{Query: "Test"})
+}
+```
+
+#### 运行内置示例
+项目包含了一个完整的“AI翻译 -> 质量检测 -> 人工审核 -> 发布”的交互式 Demo：
+```bash
+go run examples/translation/main.go
+```
+
+#### 运行单元测试
+```bash
+go test -v ./...
+```
+
+---
+
+## English
+
+### Introduction
+`GopherGraph` is a Code-as-Graph agent orchestration engine built in Go, inspired by Python's `LangGraph`. By leveraging Go 1.18+ Generics, GopherGraph ensures that workflow states are strictly typed at compile-time. Powered by native Goroutines and Channels, it executes agent communication with microsecond latency, making it the perfect engine for building complex looping agent workflows with Human-in-the-Loop (HITL) requirements.
+
+### Key Features
+- **Strictly Typed State:** Bind your custom struct to `Graph[S]` via Go generics. Say goodbye to unsafe `map[string]any` and runtime type assertions.
+- **Support for Cycles/Loops:** Unlike traditional DAG (Directed Acyclic Graph) engines, GopherGraph natively supports loops and dynamic routing based on agent evaluation.
+- **Human-in-the-Loop (HITL):** Pause workflow execution *before* a designated node, capture a snapshot (`Thread`), modify the state, and `Resume` seamlessly.
+- **Zero-Dependency & High-Performance:** Written in pure Go with zero external dependencies, leveraging in-memory queues for lightning-fast orchestration.
+
+### Quick Start
+
+#### 1. Define Your State
+```go
+type MyState struct {
+    Query    string
+    Response string
+}
+```
+
+#### 2. Define and Run the Graph
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "GopherGraph"
+)
+
+func main() {
+    // Initialize the strongly-typed graph builder
+    g := GopherGraph.NewGraph[MyState]()
+
+    // Add nodes (agents)
+    g.AddNode("agentA", func(ctx context.Context, s MyState) (MyState, error) {
+        s.Response = "Hello from Agent A"
+        return s, nil
+    })
+
+    // Add edges
+    g.AddEdge("agentA", "anotherNode")
+    
+    // Add interrupts
+    g.AddInterrupt("anotherNode")
+
+    // Compile
+    cg, _ := g.Compile()
+
+    // Start execution
+    thread, _ := cg.Start(context.Background(), "agentA", MyState{Query: "Test"})
+}
+```
+
+#### Run the Interactive Demo
+An interactive "Translation -> Review -> Human Approval -> Publish" demo is included:
+```bash
+go run examples/translation/main.go
+```
+
+#### Run Unit Tests
+```bash
+go test -v ./...
+```
+
+---
+
+## 日本語
+
+### 概要
+`GopherGraph` は、Python エコシステムの `LangGraph` に着想を得て開発された、Go 言語向けの Code-as-Graph 型エージェントオーケストレーションエンジンです。Go 1.18+ のジェネリクスを活用することで、ワークフローの状態（State）をコンパイル時に厳密に型定義できます。Go 純正の Goroutines と Channels を利用したメモリ内メッセージングにより、高い並行性と極めて低いレイテンシを実現しています。自律的なループ（Looping）や人間参加型（Human-in-the-Loop）の意思決定を伴うエージェントワークフローの開発に最適です。
+
+### 主な特徴
+- **型安全な状態管理:** ジェネリクスを用いて `Graph[S]` に構造体をバインドします。冗長な `map[string]any` やランタイム時の型アサーションから解放されます。
+- **ループと条件付き分岐のサポート:** 従来の DAG（有向非巡回グラフ）の制限を超え、エージェントの判定に基づく条件付きルートや双方向のループをサポート。
+- **Human-in-the-Loop (HITL) の一時停止と再開:** 特定のノードの実行前に処理を自動停止し、スナップショット（`Thread`）を返します。承認や状態修正の後にシームレスに処理を再開（`Resume`）できます。
+- **ピュア Go & 高性能:** 外部依存関係ゼロ。メモリ内チャネルを用いた高速なコンテキスト切り替え。
+
+### クイックスタート
+
+#### 1. 状態（State）の定義
+```go
+type MyState struct {
+    Query    string
+    Response string
+}
+```
+
+#### 2. ワークフロー図の構築と実行
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "GopherGraph"
+)
+
+func main() {
+    // 型安全なグラフビルダーの初期化
+    g := GopherGraph.NewGraph[MyState]()
+
+    // ノード（エージェント）の追加
+    g.AddNode("agentA", func(ctx context.Context, s MyState) (MyState, error) {
+        s.Response = "Hello from Agent A"
+        return s, nil
+    })
+
+    // エッジ（遷移線）の接続
+    g.AddEdge("agentA", "anotherNode")
+    
+    // 割り込み（一時停止）ポイントの設定
+    g.AddInterrupt("anotherNode")
+
+    // コンパイル
+    cg, _ := g.Compile()
+
+    // 実行開始
+    thread, _ := cg.Start(context.Background(), "agentA", MyState{Query: "Test"})
+}
+```
+
+#### インタラクティブデモの実行
+「AI翻訳 -> 監査 -> 人間による確認 -> 公開」の一連のループを体験できるデモを用意しています：
+```bash
+go run examples/translation/main.go
+```
+
+#### ユニットテストの実行
+```bash
+go test -v ./...
+```