无耳 Solon (OpenSolon) | react - ReActInterceptor 拦截器

1、内置拦截器

拦截器	名称	描述
HITLInterceptor	人工介入拦截器	该拦截器通过 ReAct 协议的生命周期钩子实现流程管控
StopLoopInterceptor	逻辑死循环拦截器	该拦截器通过监控 LLM 的输出内容指纹，防止智能体陷入无效的迭代循环
ContextCompressionInterceptor	智能上下文压缩拦截器	该拦截器通过“滑动窗口”机制，在保证 ReAct 逻辑链完整性的前提下，对 ReActTrace 历史消息进行截断压缩。
ToolRetryInterceptor	工具执行重试拦截器	该拦截器为 ReAct 模式下的工具调用提供韧性支持，具备物理重试与逻辑自愈双重机制。
ToolSanitizerInterceptor	工具结果净化拦截器	该拦截器在 ReAct 模式的 Observation 阶段执行，负责对工具返回的原始数据进行加工。

2、ReActInterceptor 各时机点说明

层级	拦截方法	触发时机	典型应用场景
智能体级	onAgentStart	智能体开始运行（初始化后）	记录全流程追踪 ID、预加载 Session 数据
	onAgentEnd	智能体完成任务（Final Answer）或达到步数限制	统计总 Token 消耗、清理临时资源、持久化轨迹
循环级	onReasonStart	开始思考，发送 LLM 消息
	onReasonEnd	思考结束，接收到 LLM 返回的完整推理消息，尚未拆解为具体 Action/Thought 之前。	解析自定义标签（如非标准 Action 解析）、手动截断推理过程、提取推理元数据。
	onThought	模型推理结果解析出 Thought 部分时	UI 打字机效果展示、记录思维链（CoT）日志
	onAction	模型解析出工具调用（Action），执行前触发	工具调用权限校验、参数格式二次修正、计费预警
	onPlan	LLM 返回初步计划方案时。	审核并修正智能体生成的初步行动计划，注入强制约束。
	onObservation	工具执行完毕，获取到结果（Observation）后	观测外部系统返回数据、敏感信息脱敏、数据清洗

由于 ReActInterceptor 具备多重身份，还可以覆盖以下底层方法实现更精细的控制：

继承自	拦截方法	作用描述
ChatInterceptor	interceptCall	作用于最底层的 ChatModel 调用，可直接操作底层的 ChatRequest/Response。
ToolInterceptor	interceptTool	最实用的扩展点：可以直接拦截工具的执行链。例如：如果某工具返回 404，拦截器可以直接伪造一个“请检查参数”的返回给模型。

3、ReActInterceptor 拦截器接口参考

ReActInterceptor 拦截器，同时继承了 FlowInterceptor 和 ChatInterceptor，所以它还可以拦截流程图（Flow）和聊天模型（ChatModel）的执行。

ReActInterceptor

package org.noear.solon.ai.agent.react;

import org.noear.solon.ai.agent.AgentInterceptor;
import org.noear.solon.ai.agent.react.task.ToolExchanger;
import org.noear.solon.ai.chat.ChatResponse;
import org.noear.solon.ai.chat.interceptor.ChatInterceptor;
import org.noear.solon.ai.chat.message.AssistantMessage;
import org.noear.solon.ai.chat.message.ChatMessage;
import org.noear.solon.lang.Nullable;
import org.noear.solon.lang.Preview;

/**
 * ReAct 智能体拦截器
 * <p>提供对智能体起止、模型推理、工具执行等全生命周期的监控与干预能力</p>
 */
public interface ReActInterceptor extends AgentInterceptor, ChatInterceptor {

    /**
     * 智能体生命周期：开始执行前
     */
    default void onAgentStart(ReActTrace trace) {
    }

    /**
     * 推理节点：Reason 阶段开始前（在 systemPrompt 构建和消息组装之前触发）
     * <p>适合做上下文压缩、工作记忆窗口管理等预处理操作</p>
     */
    default void onReasonStart(ReActTrace trace, StringBuilder systemPromptBuf) {
    }

    /**
     * 推理节点：接收 LLM 返回的原始推理消息
     */
    default void onReasonEnd(ReActTrace trace, ChatResponse resp, AssistantMessage message, long durationMs) {
    }


    /**
     * 计划节点：接收 LLM 返回的原始推理消息
     */
    default void onPlan(ReActTrace trace, AssistantMessage message) {

    }

    /**
     * 思考节点：Reason 阶段完成后触发
     * <p>无论是否解析出有效的 thoughtContent，此方法都会被调用</p>
     *
     * @param trace            ReAct 追踪上下文
     * @param thoughtContent   提取后的思考内容（可能为空字符串）
     * @param assistantMessage 原始 LLM 响应消息（含 toolCalls、content、reasoning 等完整信息）
     */
    default void onThought(ReActTrace trace, String thoughtContent, AssistantMessage assistantMessage) {
    }

    /**
     * 动作节点：调用功能工具 (Action) 前触发
     * <p>可用于权限控制、参数合法性预检</p>
     */
    default void onAction(ReActTrace trace, ToolExchanger toolExchanger) {
    }

    /**
     * 观察节点：工具执行完成后触发（100% 强闭环，放在 finally 块中）
     * <p>无论成功、失败、挂起、中断，此方法保证被调用</p>
     *
     * @param trace         ReAct 追踪上下文
     * @param toolExchanger 工具交换器（含 toolName、args、result）
     * @param observation   观察结果消息（成功时为工具输出，失败时为错误描述；挂起/中断时为空消息）
     * @param durationMs    工具执行耗时（毫秒）
     * @param error         执行异常（成功时为 null）
     */
    default void onObservation(ReActTrace trace, ToolExchanger toolExchanger,
                               @Nullable ChatMessage observation,
                               @Nullable Throwable error,
                               long durationMs) {
    }

    /**
     * 智能体生命周期：任务结束（成功或异常中止）时触发
     */
    default void onAgentEnd(ReActTrace trace) {
    }
}

ChatInterceptor

package org.noear.solon.ai.chat.interceptor;

import org.noear.solon.ai.chat.ChatOptions;
import org.noear.solon.ai.chat.ChatRequest;
import org.noear.solon.ai.chat.ChatResponse;
import org.noear.solon.ai.chat.ChatSession;
import org.noear.solon.ai.chat.prompt.Prompt;
import reactor.core.publisher.Flux;

import java.io.IOException;

/**
 * 聊天拦截器
 */
public interface ChatInterceptor extends ToolInterceptor {
    /**
     * 预处理（在构建请求之前触发）
     * <p>用于动态调整配置、补充或修改提示词（Prompt）以及注入系统指令</p>
     *
     * @param session        当前聊天会话（可用于获取历史消息、元数据或状态标记）
     * @param options        聊天配置（可修改，影响模型参数等）
     * @param originalPrompt 原始提示词（包含用户消息和上下文）
     * @param systemMessage  系统指令容器（可追加，将作为 System Message 发送）
     */
    default void onPrepare(ChatSession session, ChatOptions options, Prompt originalPrompt, StringBuilder systemMessage){

    }

    /**
     * 拦截 Call 请求
     *
     * @param req   请求
     * @param chain 拦截链
     */
    default ChatResponse interceptCall(ChatRequest req, CallChain chain) throws IOException {
        return chain.doIntercept(req);
    }

    /**
     * 拦截 Stream 请求
     *
     * @param req   请求
     * @param chain 拦截链
     */
    default Flux<ChatResponse> interceptStream(ChatRequest req, StreamChain chain) {
        return chain.doIntercept(req);
    }
}

Solon v4.0.2

1、内置拦截器

2、ReActInterceptor 各时机点说明

3、ReActInterceptor 拦截器接口参考