# RUO-若

**Repository Path**: naza/ruo

## Basic Information

- **Project Name**: RUO-若
- **Description**: RUÒ ● 若，一个能自主创建数据库应用和专业角色来进行协同工作的Agent。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RUÒ ● 若

> 基于 AgentScope-Java 的个人 ReAct 智能体服务平台

“RUÒ ● 若”是一个功能丰富的智能体服务平台，通过配置驱动的方式帮助个人用户快速构建和部署智能体应用。

![Screenshot](docs/screenshot.png)

## ✨ 核心能力

### 🤖 智能体管理

- **自主创建**：个人助理可自主创建角色和应用 Agent
- **配置驱动**：通过 YAML 文件动态创建和管理智能体
- **多模型支持**：OpenAI、Anthropic、Google Gemini
- **长期记忆**：三层记忆架构（短期、会话持久化、长期记忆）
- **多智能体协作**：Agent 间对话、工具调用代理
- **定时任务**：支持一次性任务和周期性任务调度

### 📊 数据处理

- **数据库管理**：10+ 工具支持 CRUD 操作（H2、SQLite）
- **批量操作**：事务支持、批量处理

### 🎨 交互能力

- **A2UI 协议**：20+ 声明式 UI 组件，支持数据绑定
- **HITL 框架**：人机交互，支持暂停/继续执行
- **微信集成**：支持绑定微信 ClawBot 进行对话

### 🔌 扩展能力

- **MCP 集成**：支持 Model Context Protocol 服务器
- **技能包系统**：渐进式披露，按需加载
- **自定义工具**：Java 注解快速开发

## 💡 适用场景

- **数据管理应用**：CRM、库存管理、数据录入系统
- **数据分析**：报表生成、数据可视化、统计分析
- **自动化任务**：批量处理、工作流编排
- **多角色协作**：多 Agent 角色扮演、任务协作
- **交互式工具**：动态表单、配置面板、数据展示

## 🛠️ Agent 内置能力

| 能力类别 | 说明 |
|----------|------|
| 数据库管理 | CRUD 操作、表结构管理、批量处理 |
| Agent 管理 | 多 Agent 协作、角色/应用创建 |
| A2UI 协议 | 声明式 UI 组件渲染 |
| HITL 框架 | 人机交互、暂停/继续执行 |
| 微信集成 | 绑定 ClawBot 进行对话 |
| 协同配置 | Agent 辅助用户配置 Agent 职能 |

## 🚀 快速开始

### 前置要求

- Java 21 或更高版本
- Maven 3.6 或更高版本
- Node.js 20 或更高版本（前端开发）
- OpenAI API Key（或其他模型提供商的 API Key）

### 配置 API Key

在开始之前，需要配置模型提供商的 API Key。创建或编辑 `src/main/resources/application.yml`：

```yaml
ruo:
  models:
    default:
      provider: OpenAI
      base-url: https://open.bigmodel.cn/api/coding/paas/v4
      model-name: GLM-4.7
      api-key: ${OPENAI_AUTH_TOKEN}
```

设置环境变量（示例）：

```bash
# Linux/macOS
export OPENAI_AUTH_TOKEN="your-api-key-here"

# Windows
set OPENAI_AUTH_TOKEN=your-api-key-here
```

### 编译后端

```bash
mvn clean package
```

### 构建前端

```bash
# 安装前端依赖
cd web-client
npm install

# 开发模式（独立运行）
npm run dev

# 生产构建（构建到 Spring Boot static 目录）
npm run build
```

详细的前端开发说明请参考 [web-client/README-INTEGRATION.md](web-client/README-INTEGRATION.md)

### 运行

**方式一：完整启动（推荐）**

```bash
# 1. 构建前端（首次运行或前端代码更新时）
cd web-client
npm install  # 首次运行
npm run build

# 2. 启动后端（会自动提供前端静态文件）
cd ..
mvn spring-boot:run
```

**方式二：仅启动后端（前端已构建）**

```bash
mvn spring-boot:run
```

**方式三：开发模式（前端独立运行）**

```bash
# 终端 1：启动前端开发服务器
cd web-client
npm run dev

# 终端 2：启动后端
mvn spring-boot:run
```

### 访问应用

- **Web 前端**：http://localhost:8080/（生产模式）或 http://localhost:3000/（开发模式）
- **AG-UI 端点**：http://localhost:8080/agui

## 🏗️ 技术架构

| 层级 | 技术选型 |
|------|---------|
| Web 框架 | Spring Boot 4.0.3 + WebFlux |
| 智能体框架 | AgentScope-Java 1.0.8 |
| AG-UI 协议 | agentscope-agui-spring-boot-starter |
| 前端框架 | Next.js 16.1.6 + React 19.2.3 |
| UI 组件库 | shadcn/ui + Tailwind CSS 4 |
| 模型提供商 | OpenAI, Anthropic, Google Gemini |
| 数据库 | H2, SQLite |
| Java 版本 | 21+ |
| Node 版本 | 20+ |

## 📄 许可证

Apache License 2.0