Xiuxian 模块介绍

Xiuxian（修仙）模块是一个演示性质的 AI Agent Demo，以"修仙世界"为业务背景，展示了如何将 LLM 接入企业业务系统。

模块定位

演示价值

虽然是一个演示模块，但它具有实际的参考意义：

场景	传统方式	AI Agent 方式
查询用户信息	记住 API 或操作界面	自然语言描述需求
批量操作	编写脚本或逐个操作	一句话完成
复杂决策	人工分析数据后决策	AI 自动分析并执行
权限控制	前端/接口层硬编码	AI 理解身份自动判断

业务场景

模拟一个修仙宗门管理系统：

• 宗主：最高权限，可管理全宗门事务
• 峰主：管理本峰弟子，查看本峰数据
• 弟子：查看和操作自己的信息

核心业务：

• 修士管理（查询、新增、修改、状态变更）
• 功法管理（推荐、兑换）
• 任务管理（分配、进度跟踪）
• 资源管理（灵石、贡献点）

技术架构

分层说明

层级	包路径	职责
Agent 层	agentic/	LLM 交互、工具调用、技能编排
业务层	biz/	传统 CRUD 业务逻辑
会话层	chat/	对话历史管理
任务层	task/	定时任务（如每月发放津贴）

核心设计

Meta-Tool 模式

LLM 不直接调用业务工具，而是通过 3 个 Meta-Tool 间接调用：

用户消息 → LLM → Meta-Tool → 业务工具 → 返回结果

三个 Meta-Tool：

• getSkillGuide - 获取技能执行指南
• getToolSchema - 获取工具参数格式
• executeTool - 执行工具

详见 Meta-Tool 模式

技能系统

复杂任务通过 Markdown 文件定义执行步骤：

# 功法推荐

根据修士的境界、灵根、身份，推荐最适合修炼的功法。

## 执行步骤

### 步骤1：查询修士信息
调用工具：`query_user_detail`

### 步骤2：查询功法列表
调用工具：`page_manuals`

### 步骤3：查询兑换规则
调用工具：`query_exchange_rules`

详见 技能系统

权限控制

基于 @RequiresRole 注解的工具权限控制：

@Tool(description = "查询修士详细信息")
@RequiresRole(value = XiuxianRole.PEAK_MASTER, message = "需要峰主及以上权限")
public String queryUserDetail(String userName) {
    // ...
}

详见 权限控制

技术栈

组件	版本	说明
Spring AI	1.1.2	AI 集成框架
Spring Boot	3.5.6	基础框架
MyBatis-Plus	3.5.12	ORM 框架
Velocity	2.4.1	模板引擎
Redisson	3.52.0	Redis 客户端

快速体验

1. 启动服务

cd molandev-backend/molandev-xiuxian
mvn spring-boot:run

2. 发起对话

curl -X POST http://localhost:9099/xiuxian/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "查询张三的基本信息", "mockUserId": "user001"}'

3. 示例响应

AI：正在查阅【张三】的基本信息...

### 【张三】修士信息
| 属性 | 值 |
|------|------|
| 境界 | 筑基初期 |
| 灵根类型 | 天灵根 |
| 灵根属性 | 火 |
| 资质 | 甲等 |
| 身份 | 内门弟子 |
| 所属峰 | 炼器峰 |
| 状态 | 正常 |

下一步

• 架构设计 - 了解模块架构细节
• Meta-Tool 模式 - 理解工具调用机制
• 技能系统 - 学习技能定义方式
• 工具开发 - 开发自己的业务工具