team - TeamInterceptor 拦截器

在多智能体协作（Multi-Agent System）中，流程的透明度与可控性至关重要。TeamInterceptor 提供了对 TeamAgent 全生命周期的深度观察与干预能力。它不仅是一个日志记录点，更是实现合规审计、动态权限控制、成本熔断及内容安全的核心组件。

1、核心治理维度

TeamInterceptor 通过三个互补的切面维度，构建了一套立体的治理体系：

维度 1：团队级 (Team Level) —— 会话生命周期

监控整个协作任务的起止，适用于全局性的初始化与资源清理。

• onTeamStart: 任务初始化。可用于初始化外部 TraceId、分配全局上下文或记录审计日志的起点。
• onTeamEnd: 任务归档。可在此处将最终的 TeamTrace 轨迹持久化到数据库或发送至监控平台。

维度 2：决策级 (Supervisor Level) —— 调度治理

针对团队中的“主管（Supervisor）”或“决策逻辑”进行干预，这是控制团队流转方向的关键。

• shouldSupervisorContinue: 准入熔断。例如：当检测到会话步骤过多或 Token 余额不足时，返回 false 强制中止决策，防止死循环或过度消耗。
• onModelStart / onModelEnd: 模型感知。在 Supervisor 调用 LLM 进行路由决策时，可以动态微调请求参数（如降低随机性）或审计模型的原始推理响应。
• onSupervisorDecision: 路径追踪。捕获主管最终决定将任务派发给谁，用于实时观察团队的协作路径。

维度 3：成员级 (Agent Level) —— 执行准入

针对具体的“执行者（Agent）”进行管控，确保每个成员在安全、合规的边界内工作。

• shouldAgentContinue: 成员权限校验。例如：在执行敏感的 RefundAgent（退款智能体）前，校验当前用户是否具备审批权限。如果返回 false，则任务跳过该成员并回退至决策层。
• onAgentEnd: 执行反馈。成员工作完成后的钩子，常用于统计单个 Agent 的耗时与资源消耗。

2、应用场景示例

场景 A：全局成本与步骤熔断

public class CostLimitInterceptor implements TeamInterceptor {
    @Override
    public boolean shouldSupervisorContinue(TeamTrace trace) {
        // 如果协作步骤超过 10 步，自动熔断，防止 Agent 陷入思考黑洞
        return trace.getStepCount() <= 10;
    }
}

场景 B：内容安全审计 (Censor)

public class SecurityInterceptor implements TeamInterceptor {
    @Override
    public void onModelEnd(TeamTrace trace, ChatResponse resp) {
        // 对 Supervisor 的输出进行关键词过滤
        if (resp.getContent().contains("敏感词")) {
            throw new SecurityException("检测到不合规决策内容");
        }
    }
}

3、技术契约说明

TeamInterceptor 继承了 Solon AI 体系中的多个拦截器规范，具备极强的整合能力：

• AgentInterceptor: 赋予其对独立智能体的拦截能力。
• FlowInterceptor: 使其能够感知底层的 Solon Flow 状态机跳转。
• ChatInterceptor: 提供对底层 LLM 原始对话流的直接干预能力。

所有的拦截操作都持有 TeamTrace 对象，这意味着拦截器可以基于历史推导未来——通过查阅之前的执行轨迹，来决定当前的决策是否应该被允许。

4、快速决策参考

5、TeamInterceptor 接口参考

import org.noear.solon.ai.agent.Agent;
import org.noear.solon.ai.agent.AgentInterceptor;
import org.noear.solon.ai.chat.ChatRequestDesc;
import org.noear.solon.ai.chat.ChatResponse;
import org.noear.solon.ai.chat.interceptor.ChatInterceptor;
import org.noear.solon.flow.intercept.FlowInterceptor;
import org.noear.solon.lang.Preview;

/**
 * 团队协作拦截器 (Team Interceptor)
 * * <p>核心职责：提供对 TeamAgent 协作全生命周期的观察与干预能力。支持团队、决策、成员三个维度的切面注入。</p>
 *
 * @author noear
 * @since 3.8.1
 */
@Preview("3.8.1")
public interface TeamInterceptor extends AgentInterceptor, FlowInterceptor, ChatInterceptor {

    // --- [维度 1：团队级 (Team Level)] ---

    /**
     * 团队协作开始
     */
    default void onTeamStart(TeamTrace trace) {}

    /**
     * 团队协作结束
     */
    default void onTeamEnd(TeamTrace trace) {}


    // --- [维度 2：决策级 (Supervisor Level)] ---

    /**
     * 决策准入校验（主管发起思考前）
     * * @return true: 继续执行; false: 熔断并中止协作
     */
    default boolean shouldSupervisorContinue(TeamTrace trace) {
        return true;
    }

    /**
     * 模型请求前置（LLM 调用前）
     * <p>常用于动态调整 Request 参数（如 Temperature, MaxTokens 等）。</p>
     */
    default void onModelStart(TeamTrace trace, ChatRequestDesc req) {}

    /**
     * 模型响应后置（LLM 返回后，解析前）
     * <p>常用于内容安全审计或原始 Token 统计。</p>
     */
    default void onModelEnd(TeamTrace trace, ChatResponse resp) {}

    /**
     * 决策结果输出（指令解析后）
     * * @param decision 经解析确定的目标 Agent 名称或终结指令
     */
    default void onSupervisorDecision(TeamTrace trace, String decision) {}


    // --- [维度 3：成员级 (Agent Level)] ---

    /**
     * 成员执行准入校验（Agent 运行前）
     * * @param agent 即将运行的智能体
     * @return true: 允许运行; false: 跳过并回滚至决策层
     */
    default boolean shouldAgentContinue(TeamTrace trace, Agent agent) {
        return true;
    }

    /**
     * 成员执行结束
     */
    default void onAgentEnd(TeamTrace trace, Agent agent) {}
}