---
title: "react - 内置拦截器（5个）"
---


| 拦截器 | 描述 | 备注 |
| -------- | -------- | -------- |
| HITLInterceptor     | 人工介入拦截器    | 配合 HITL 接口使用     |
| StopLoopInterceptor     | 避免逻辑死循环拦截器    |      |
| ContextCompressionInterceptor     | 语义保护型上下文压缩拦截器     | 配套可定制的 CompressionStrategy     |
| ToolRetryInterceptor     | 工具执行重试拦截器    |       |
| ToolSanitizerInterceptor     | 工具结果净化拦截器     |       |



### HITLInterceptor（人工介入拦截器）

- **作用**：在 ReAct 执行过程中触发人工介入（Human-In-The-Loop），支持外部审批或干预
- **注册方式**：通过 `.defaultInterceptorAdd(new HITLInterceptor(...))` 或通过 `HarnessEngine` 的 `hitlInterceptor` 配置
- **触发时机**：标准 HITL 由拦截器在 Action 预检发现待审核工具调用时触发，并产生 `HITLPendingEvent`。直接调用 `session.pending(true, reason)` 只是设置会话状态，不能替代完整的 HITL 事件协议。

### StopLoopInterceptor（防循环拦截器）

- **作用**：防止 ReAct 陷入无限循环，达到最大轮次时强制终止
- **注册方式**：`HarnessEngine` 默认已内置，也可手动创建：`new StopLoopInterceptor(maxLoops, maxTurns)`
- **触发时机**：每次 ReAct 循环时检查，超过阈值则抛出异常终止

### ContextCompressionInterceptor（上下文压缩拦截器）

- **作用**：当上下文过长时，自动压缩历史消息，避免超出模型上下文窗口
- **注册方式**：`HarnessEngine` 默认已内置，也可手动创建
- **触发时机**：每轮 Reason 前检查消息数量和估算 Token 数；启用该拦截器后，流中可能产生 `ContextSizeEvent`，它不等同于供应商 Usage

### 事件层级提示

- Chat 层 `TOOL_CALL_*` 表示模型响应中的工具调用内容。
- Agent 层 `ToolCallStartEvent` / `ToolCallEndEvent` 表示本地工具处理边界。
- 首次 HITL 挂起发生在 Action 开始前，不产生 ToolCall 开始/结束事件。
- 工具重试和异常路径下，不要只按事件次数推断真实副作用次数。

### ToolRetryInterceptor（工具重试拦截器）

- **作用**：工具调用失败时自动重试
- **注册方式**：`.defaultInterceptorAdd(new ToolRetryInterceptor(maxRetries))`
- **触发时机**：工具执行抛出异常时

### ToolSanitizerInterceptor（工具净化拦截器）

- **作用**：对工具调用的输入输出进行清洗、过滤或转换
- **注册方式**：`.defaultInterceptorAdd(new ToolSanitizerInterceptor(...))`
- **触发时机**：工具调用前后