Xiuxian 模块介绍
Xiuxian（修仙）模块是一个单 Agent + 工具编排的 AI Demo，以"修仙宗门管理"为场景，展示了 LLM 接入企业业务系统的完整实践。
为什么值得关注
| 对比维度 | 传统 RPA / 脚本 | 普通 Tool Calling | Xiuxian Agent |
|---|---|---|---|
| 意图理解 | 硬编码 if-else | LLM 自行选择工具 | LLM 自主理解 + 6组领域工具 |
| 权限控制 | 接口层硬编码 | 注解声明 | System Prompt + 运行时双保障 |
| 模糊查询 | 静默取第一条 | 同上 | 前端候选人卡片交互确认 |
| 实时反馈 | 无 | thinking 混在一起 | PROGRESS / THINKING 分类型推送 |
| 角色感知 | 查表 | 单层 Prompt | System Prompt 注入角色身份 + 权限 |
核心特性
Agent + 工具编排
一个 XiuxianAgentService 管理对话，6 组业务工具让 LLM 自主调用：
用户消息 → XiuxianAgentService → LLM 分析意图 → 调用工具
├── 修士管理（查询、新增、修改、删除）
├── 任务管理（接取、完成、放弃）
├── 功法管理（推荐、查询）
├── 兑换交易（物品兑换）
├── 资源管理（资源查看、调整）
└── 世界知识（境界、灵根、功法体系）LLM 拥有所有工具的访问权，自主决定何时调用哪些工具。每步工具调用都有 PROGRESS 事件通知前端。
实时交互体验
SSE 流式推送，思考过程与执行进度分类型展示：
用户：查询张三的信息
🤔 正在思考... ← THINKING
📋 正在查询修士信息... ← PROGRESS
**【张三】修士信息** ← CONTENT
| 属性 | 值 |
|------|------|
| 境界 | 筑基初期 |
| 灵根类型 | 天灵根 |
| 状态 | 正常 |消歧确认
遇到重名时不静默取第一个，而是前端弹出选择卡片：
用户："查看张三的信息" → 匹配到 3 个张三
→ 前端弹出候选人卡片：
[张三（炼气期·丹峰）] [张三（筑基期·剑峰）] [张三（金丹期·炼峰）]
→ 用户点击 → selectedId 精确定位三级权限体系
- 宗主：全宗门管理权限
- 峰主：本峰弟子管理权限（数据范围自动过滤）
- 弟子：只能查看和操作自己的信息
LLM 在生成回复时自动识别身份，越权操作由运行时 XiuxianAgentContext.hasPermission() 拦截。
思考模式开关
前端可切换「思考模式」，控制 LLM 是否输出推理过程（enableThinking 参数）。默认开启，让用户看到 AI 的决策逻辑。
技术架构
| 层级 | 包路径 | 职责 |
|---|---|---|
| 控制层 | agentic/controller/ | SSE 流式接口 |
| 服务层 | agentic/service/ | 对话管理、ChatClient 调用 |
| 工具层 | agentic/skill/tools/ | 业务工具，调 Service |
| 支撑层 | agentic/skill/support/ | 模板渲染、分页、权限 |
| 业务层 | biz/service/ | 传统 CRUD，可独立使用 |
交互演示
场景1：弟子查询自己的信息
bash
curl -X POST http://localhost:9099/xiuxian/chat/stream \
-H "Content-Type: application/json" \
-d '{"message": "查看我的信息", "mockUserId": "U001", "enableThinking": true}'弟子身份 → 只能看到自己的基本信息，灵石余额等敏感字段不显示。
场景2：峰主查询本峰弟子
bash
curl -X POST http://localhost:9099/xiuxian/chat/stream \
-H "Content-Type: application/json" \
-d '{"message": "查看本峰所有弟子", "mockUserId": "U010", "enableThinking": true}'峰主身份 → 自动过滤只显示本峰弟子，其他峰的信息看不到。
场景3：消歧确认
bash
curl -X POST http://localhost:9099/xiuxian/chat/stream \
-H "Content-Type: application/json" \
-d '{"message": "查看张三的信息", "mockUserId": "U001", "enableThinking": true}'多个张三 → 返回 CONFIRMATION 类型 + 候选人列表，前端弹卡选择 → selectedId 精确定位。
技术栈
| 组件 | 版本 | 说明 |
|---|---|---|
| Spring AI | 1.1.2 | ChatClient + Tool Calling |
| Spring Boot | 3.5.6 | 基础框架 |
| MyBatis-Plus | 3.5.12 | ORM |
| Velocity | 2.4.1 | 工具输出模板 |
| PostgreSQL | - | 数据库 |