架构设计

Xiuxian 模块采用分层架构设计，将 AI Agent 能力与传统业务逻辑分离，实现关注点分离。

整体架构

核心组件

1. XiuxianToolAgentService

Agent 核心服务，负责 LLM 交互和工具调用编排。

主要职责：

• 构建 System Prompt（包含用户身份、可用技能、可用工具）
• 管理对话历史
• 调用 LLM 并处理 Tool Calling
• SSE 流式输出

2. AgentCapabilityRegistry

能力注册中心，统一管理工具和技能。

主要职责：

• 扫描并注册带 @Tool 注解的方法
• 加载 resources/skills/*.md 技能定义
• 根据用户身份过滤可用工具
• 执行工具调用

3. AgentContext

Agent 执行上下文，存储当前请求的元信息。

包含信息：

• 会话 ID、用户 ID
• 用户身份（宗主/峰主/弟子）
• 所属峰 ID（用于权限判断）
• SSE Emitter（用于发送进度通知）

@Data
public class AgentContext {
    private String conversationId;
    private String userId;
    private XiuxianRole role;
    private String xiuxianName;
    private String peakId;
    private SseEmitter sseEmitter;

    public void sendProgress(String message) {
        if (sseEmitter != null) {
            sseEmitter.send(AgentResponse.thinking(message));
        }
    }
}

4. AgentContextHolder

使用 ThreadLocal 存储当前请求的上下文，供工具类访问。

public class AgentContextHolder {

    private static final ThreadLocal<AgentContext> CONTEXT = new ThreadLocal<>();

    public static AgentContext getContext() {
        return CONTEXT.get();
    }

    public static void setContext(AgentContext ctx) {
        CONTEXT.set(ctx);
    }

    public static void clear() {
        CONTEXT.remove();
    }
}

数据流

对话处理流程

工具调用流程

设计原则

1. 分层解耦

• Agent 层：只关心 LLM 交互和工具编排
• 工具层：只关心业务逻辑，不关心 LLM
• 业务层：传统 CRUD，可独立使用

2. 权限前置

• System Prompt 中告知 LLM 用户身份
• 工具注册时绑定所需权限
• 执行时再次校验权限（双重保障）

3. 上下文传递

• 通过 ToolContext 传递 AgentContext
• 工具类通过 ThreadLocal 访问
• 支持进度通知（sendProgress）

4. 模板渲染

• 工具输出使用 Velocity 模板
• 统一的表格、列表格式
• 支持 Markdown 格式化

下一步

• Meta-Tool 模式 - 理解工具调用机制
• 技能系统 - 学习技能定义方式
• 工具开发 - 开发业务工具