架构设计

Xiuxian 模块采用单 Agent + 工具编排架构，通过 Spring AI 的 @Tool 注解让 LLM 自主调用后端业务能力。

整体架构

核心组件

XiuxianAgentService — 对话服务

单 Agent 模式，通过 ChatClient 直接调用 6 组工具，LLM 自主决定调用哪些工具：

chatClient.prompt()
    .system(systemPrompt)
    .messages(history)
    .user(message)
    .tools(userTools, taskTools, manualTools, exchangeTools, resourceTools, knowledgeTools)
    .toolContext(toolContext)
    .options(OpenAiChatOptions.builder()
            .extraBody(Map.of("enable_thinking", enableThinking))
            .build())
    .stream()
    .chatResponse()

系统 Prompt 中已包含当前用户身份信息（角色、境界、灵石余额、权限说明），LLM 天然知晓操作者身份。

XiuxianAgentContext — 执行上下文

通过 ToolContext 传递，不依赖 ThreadLocal：

@Builder
public class XiuxianAgentContext {
    private String conversationId;
    private String userId;
    private XiuxianRole role;        // 宗主/峰主/弟子
    private String xiuxianName;
    private String peakId;           // 数据权限过滤
    private SseEmitter sseEmitter;

    public void notify(String message) {
        sseEmitter.send(AgentResponse.progress(message + "\n"));
    }

    public boolean hasPermission(XiuxianRole required) { ... }
    public String checkPeakPermission(String targetPeakId, String action) { ... }
}

BaseToolSupport — 工具基类

所有工具类继承此基类，提供模板渲染、进度通知、分页查询、字段更新、权限检查等公共方法。详见 工具开发。

响应协议 — 6 种 Event 类型

类型	来源	前端展示
CONTENT	LLM 最终回复	正文 Markdown 渲染
THINKING	LLM 推理过程	灰色思考气泡
PROGRESS	Tool 执行进度	思考气泡内进度文字
CONFIRMATION	消歧确认	候选人选择卡片
ERROR	错误	红色提示
DONE	对话结束	隐藏加载

数据流

设计亮点

分层解耦

层	只关心	不关心
服务层	对话管理 / SSE	业务细节
工具层	业务逻辑 + 模板渲染	SSE 传输、LLM 调度
业务层	CRUD	Agent、LLM

消歧机制

模糊查询不再静默取第一个：BaseToolSupport.checkPeakPermission() 上下文消歧 → 前端候选人卡片确认。

字段更新语义清晰

updateField(user::setName, dto.getName(), false);        // 不允许清空
updateIfPresent(user::setName, dto.getName());           // null 跳过
updateOrClear(manual::setDescription, dto.getDescription()); // 允许清空

下一步

• 工具架构 - 工具系统与扩展方式
• 对话流程 - SSE 协议与消歧交互
• 工具开发 - 开发业务工具