内容
<div align="center">
# 🧠 EasyAI
### 使用 AI 构建 AI — 用自然语言构建、编排、运行多 Agent 协作系统
[](LICENSE)
[](https://kotlinlang.org)
[](https://spring.io)
[](https://react.dev)
[⬇️ 快速开始](#-快速开始) · [✨ 示例](easyai-examples/) · [🏗️ 架构](#-架构) · [🇨🇳 中文版](README_CN.md)
</div>
---
## 🤔 什么是 EasyAI？
EasyAI 是一个**全栈 LLM Agent 框架**（Kotlin / Spring Boot），包含桌面和 Web 客户端。你可以用自然语言描述需求，EasyAI 会生成 Agent、分配工具、编排团队，并实时反馈每一步的结果。
**核心组件：**
- 🔄 **ReAct Agent Loop** — 全可控的 `调用 → 工具 → 观察 → 重复` 循环
- 🐝 **Swarm Runtime** — 基于 DAG 的多 Agent 编排：并行团队 + 对抗性辩论，带有裁判
- 🪄 **AI 配置生成器** — 自然语言 → 完整的 Agent / 工作流配置，内置校验 → 修复循环
- 🖥️ **桌面 + Web 客户端** — 一次下载：捆绑 JRE，嵌入式数据库，零运行时设置
**为什么选择 EasyAI？**
- 其他框架：编写 YAML/JSON 配置 → EasyAI：**用自然语言描述，AI 生成和校验**
- 其他框架：顺序 Agent 链 → EasyAI：**DAG 编排 + 多轮裁判裁决的辩论**
- 其他框架：仅 CLI → EasyAI：**可视化工作流编辑器 + 全功能聊天控制台 + 桌面应用程序**
---
## ✨ 主要功能
<table>
<tr>
<td width="50%">
### 🏛️ AI 辩论
- 多轮 **Bull vs Bear** 对抗性辩论
- 裁判自主决定何时达成共识
- 每个参与者每轮的个性化提示
- 消除单一 Agent 分析偏差
</td>
<td width="50%">
### 🪄 AI 创建 AI
- 描述需求 → AI 生成完整的 Agent 配置
- 内置校验 → 修复循环保证正确性
- 资源感知：发现您的工具和 MCP 服务器
- 通过对话迭代完善（"删除 QA，添加 DBA"）
</td>
</tr>
<tr>
<td width="50%">
### 🌐 DAG Swarm 编排
- 可视化拖拽式工作流编辑器
- 单个 / 团队 / 辩论任务类型
- 并行执行，依赖关系解析
- 通过 SSE 实现实时进度流式传输
</td>
<td width="50%">
### 📦 一键安装，零配置
- 捆绑 JRE + 胖包 — 无需 JDK
- 嵌入式 H2 数据库 — 无需 PostgreSQL
- macOS (DMG) / Windows (NSIS) / Linux (AppImage)
- 自动更新，带有本地通知
</td>
</tr>
</table>
---
## 🚀 你可以做的事情
| 任务 | 方法 | 输出 |
|------|-----|--------|
| 运行 14 Agent 的投资分析 | 粘贴一个提示 → AI 生成完整 DAG | 4D 报告 + Bull/Bear 辩论 + 结构化交易计划 |
| 部署 6 专家编码团队 | 粘贴一个提示 → AI 生成团队 Agent | 研究 → 实现 → 测试 → 审查，并行进行 |
| 在 30 秒内创建自定义 Agent | 用自然语言描述角色 | 完整的 Agent，包含工具和权限 |
| 100+ 轮深度研究会话 | 记忆系统 + 上下文压缩 | 上下文不会丢失，自动总结 |
| 集成任何外部工具 | 在 UI 中连接 MCP 服务器 | Agent 立即获得新能力 |
| 修改代码，安全无忧 | 每次更改前进行 Git 快照 | 一键恢复到任意检查点 |
---
## ⚡ 快速开始
### 选项 A：桌面应用程序（推荐，大约 5 分钟）
```bash
# 1. 构建桌面应用程序（需要 JDK 21+，Node 20+）
cd easyai-desktop
scripts/build-backend.sh # 控制台分发 → 胖包
scripts/fetch-jre.sh # 捆绑 Temurin JRE 21
npm ci && npm run desktop:build # → DMG / NSIS / AppImage
# 2. 安装并启动 — 嵌入式 JRE + H2 数据库，零运行时配置
# 3. 打开设置 → 配置您的 LLM API 密钥（DashScope / OpenAI / Anthropic）
```
### 尝试示例 ✨
每个示例都是**精心编写的提示** — 复制，粘贴，生成，完成。参见 [easyai-examples/](easyai-examples/) 获取完整指南。
**🧑💻 编码团队** — 6 位专家（研究员，工程师，QA，审查员，UI 操作员，调试器）协同工作：
> Agent → 创建 Agent → ✨ AI 面板 → 粘贴 [提示](easyai-examples/coding-team/) → 生成 → 应用 → 保存
**📈 投资分析** — 14 个 AI 分析师组成投资委员会，进行 Bull vs Bear 辩论：
> 工作流 → 创建预设 → ✨ AI 面板 → 粘贴 [提示](easyai-examples/investment-analysis/) → 生成 → 应用 → 保存 → 运行
### 选项 B：从源码启动开发服务器
```bash
# 后端（JDK 21+）
cd easyai && ./mvnw clean install
cd ../easyai-apps && ./mvnw spring-boot:run -pl easyai-web-server # → :8080
# 前端（Node 20+）
cd easyai-console && npm ci && npm run dev # → :5173
```
打开 `http://localhost:5173` → 设置 → 配置您的 LLM API 密钥 → 开始聊天。
---
## 🏗️ 架构
```
┌───────────────────────────────────────────────────────────┐
│ 桌面 Shell (Electron) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Web 控制台 (React + Vite + TailwindCSS) │ │
│ │ 聊天 │ Agent │ 工作流 DAG │ MCP │ 记忆 │ │
│ └─────────────────────────────────────────────────────┘ │
├───────────────────────────────────────────────────────────┤
│ Spring Boot 后端 (Kotlin) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
│ │ ReAct │ │ Swarm │ │ 技能 │ │ 上下文 │ │
│ │ Agent │ │ Runtime │ │ & 子 Agent │ │ │ │
│ │ 循环 │ │ (DAG) │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └─────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 工具：文件 │ 搜索 │ Shell │ Web │ MCP │ 记忆 │ │
│ │ 目标 │ 待办 │ 问题 │ 计算 │ │
│ └─────────────────────────────────────────────────────┘ │
│ SSE 流式传输 │ JWT 认证 │ 权限 │ 暴露的 R2DBC │
└───────────────────────────────────────────────────────────┘
```
| 项目 | 路径 | 技术 | 目的 |
|---------|------|------|---------|
| easyai | `easyai/` | Kotlin 2.3 / Spring Boot 4.1 | LLM 框架（Agent 循环，工具，Swarm，SSE，持久性） |
| easyai-console | `easyai-console/` | React 18 / TypeScript / Vite 6 | Web 控制台（聊天，Agent，工作流，MCP，记忆） |
| easyai-apps | `easyai-apps/` | Kotlin / Spring Boot | 可运行服务器（Web + 桌面后端） |
| easyai-desktop | `easyai-desktop/` | Electron 33 / esbuild | 桌面 Shell：启动捆绑 JRE 的胖包 |
| easyai-examples | `easyai-examples/` | 提示 | 边做边学：粘贴提示，AI 构建其他内容 |
---
## 🛠️ 技术栈
<p align="center">
<img src="https://img.shields.io/badge/Kotlin-2.3-7F52FF?logo=kotlin&logoColor=white" alt="Kotlin" />
<img src="https://img.shields.io/badge/Spring_Boot-4.1-6DB33F?logo=springboot&logoColor=white" alt="Spring Boot" />
<img src="https://img.shields.io/badge/Spring_AI-2.0-6DB33F?logo=spring&logoColor=white" alt="Spring AI" />
<img src="https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=black" alt="React" />
<img src="https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
<img src="https://img.shields.io/badge/Vite-6-646CFF?logo=vite&logoColor=white" alt="Vite" />
<img src="https://img.shields.io/badge/TailwindCSS-4-06B6D4?logo=tailwindcss&logoColor=white" alt="TailwindCSS" />
<img src="https://img.shields.io/badge/Electron-33-47848F?logo=electron&logoColor=white" alt="Electron" />
<img src="https://img.shields.io/badge/PostgreSQL-R2DBC-4169E1?logo=postgresql&logoColor=white" alt="PostgreSQL" />
</p>
---
## 🔬 内部实现 — 工程亮点
EasyAI 不是一个薄弱的 LLM API 封装。它是一个**生产级 Agent 运行时**，从头到尾使用 Kotlin 协程构建。下面是内部实现细节：
### 🔄 全可控的 ReAct 循环
- **自主实现的 Agent 循环** — 不是 Spring AI 内置的工具调用。每个迭代都可检查，可中断，可扩展。
- **3 阶段工具执行**：权限检查 → 并行批量执行 → 后钩子。被阻塞的工具会自动跳过剩余的调用。
- **完成检查奖励迭代** — 目标驱动的 Agent 可以为自己授予额外回合（预算限制），以完成工作。
- **上下文溢出自我修复** — 检测 LLM token 限制错误，自动压缩上下文，并透明地重试。
- **运行时消息注入** — 可以在循环中途注入引导/后续消息，并带有延迟到达的补救逻辑。
### 📡 基于通道的事件流式传输
- `EventStream<TEvent, TResult>` 基于 Kotlin `Channel` + `CompletableDeferred` 构建 — 生产者/消费者完全解耦。
- 15+ 类型化的 SSE 事件（思考，工具生命周期，权限请求，压缩，子 Agent 转发）。
- 子 Agent 事件透明地丰富了父上下文（`withSubAgentContext`），用于嵌套渲染。
- `CustomEvent` 扩展点 — 在不修改密封层次结构的情况下注入领域事件。
### 🐝 DAG Swarm 编排
- **Kahn 算法** 用于基于层的拓扑调度 — 同一层的任务并行运行，层依次执行。
- **DFS 循环检测** （白色-灰色-黑色着色），带有可读的循环路径报告。
- **故障级联** — BFS 传播将所有传递依赖标记为 BLOCKED。
- **信号量限制并发** + 原子信号的运行时暂停/恢复/取消。
### ⚔️ AI 辩论
- 裁判使用**中立的协调员提示**（去除个人色彩），在主持过程中消除偏差。
- 每轮：裁判审查完整历史 → 为每个参与者生成**个性化提示**（JSON Schema 约束）。
- **自主收敛** — 裁判通过结构化的 `converged` 输出决定何时达成共识。
- **从检查点恢复** — 重建 token 计数器，并在重启时定位上一个已完成的轮次。
### 👥 领导-成员反应团队
- 事件驱动协调：成员结果通过 `Channel` 流动，带有去抖/排空，然后呈现给领导者。
- 领导者输出**结构化决策**（新任务，重新分配，暂停并协助，用户咨询）。
- 成员可以被**阻塞，由同伴协助或升级** — 领导者动态适应。
- 完整的持久性：轮次记录 + 成员执行使崩溃恢复和恢复成为可能。
### 🗜️ 增量上下文压缩
- **每轮边界数据**：只有 "前一摘要 + 新消息" — 永远不会重新加载完整历史。
- 三个触发器：自动（token 阈值），手动，溢出（错误后紧急压缩）。
- `UsageAwareTokenEstimator` — 根据实际 LLM 使用情况反馈校准字符/token 比率。
- 在压缩过程中提取**会话变量**，用于实时前端状态。
### 🔐 防御性权限系统
- **开闭设计** — 每个 ToolBuilder 声明其自己的 `permissionEvaluator`；新工具无需修改核心代码。
- Shell 命令分为 3 个安全层级（SAFE_READ / SAFE_WRITE / UNSAFE），并带有复合命令拆分。
- Git 子命令粒度：`git log` 自动批准，`git push` 需要明确同意。
- 权限请求通过 SSE 暂停 Agent 循环 → 前端批准卡 → 恢复。
### 📸 阴影 Git 快照
- **独立 Git 仓库**，每个项目一个（ `--git-dir` 隔离）— 永远不会污染您的项目的 `.git` 历史。
- 作者归属：区分 USER 提交和 LLM_AGENT 提交（Agent ID 编码在作者名称中）。
- 每个仓库的 `Mutex` 防止并发快照写入；文件级恢复到任意检查点。
### ⚡ 弹性与错误分类
- 通过 Spring AI 异常层次结构（`NonTransientAiException` / `TransientAiException`）实现类型安全的错误分类。
- 4 级检测：结构化异常 → HTTP 状态 → 提供者特定 → 关键字回退。
- 跨提供者鲁棒性：OpenAI，Anthropic，DashScope 统一处理。
- 双流阻塞检测：240 秒 TTFT 超时 + 120 秒块间空闲超时（独立于 HTTP 层）。
### 🔌 异步 MCP 集成
- `McpAsyncClient` 搭配 Reactor Mono → 协程 `awaitSingle` 桥接 — 完全非阻塞。
- 每个用户延迟初始化，双重检查锁定；系统服务器在启动时连接。
- 支持 **Stdio** 和 **StreamableHTTP** 传输，带有每个用户-服务器的工具缓存。
---
## 🤝 贡献
欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发设置，代码风格和 PR 流程。
## 📄 许可证
[Apache License 2.0](LICENSE)
