openJiuwen agent-core-java Runner 全局回调框架(callback)机制详解与实战指南
openJiuwen agent-core-java Runner 全局回调框架(callback)机制详解与实战指南
com.openjiuwen.core.runner.callback 是 openJiuwen agent-core-java 提供的 Runner 级全局事件回调框架,用于在整个 Agent 运行期以装饰器风格注册、触发和管理事件回调。本文从主类 AsyncCallbackFramework 出发,完整梳理其注册、触发、过滤器、链式回滚、指标、hooks、断路器、延迟触发与历史记录等能力,并结合仓库源码(core/src/main/java/com/openjiuwen/core/runner/callback)与测试用例逐项展开。读完本文,你将掌握如何在 Runner 全局挂接回调、如何用过滤器控制执行流程、如何用链式回滚保证数据一致性,以及如何通过指标与历史记录观测回调运行状态。
一、框架定位:Runner 级全局事件回调
在 openJiuwen agent-core-java 中,Runner 是分布式运行与资源调度的核心入口,而 callback 包正是挂在 Runner 上的全局事件回调框架。与某个具体 Agent 或 Session 内部的生命周期回调不同,这里的回调是 Runner 级(全局) 的:注册之后,任何一次事件触发都会按规则分发给对应的回调函数,适合做全局埋点、观测、鉴权、限流、熔断等横切能力。
- 对应 Python 版本的
AsyncCallbackFramework(源码注释明确标注 "Mirrors Python'sAsyncCallbackFrameworkinopenjiuwen/core/runner/callback/framework.py",见 AsyncCallbackFramework.java); - 真实主类是
AsyncCallbackFramework,它实现了DecoratorFramework接口(见 DecoratorFramework.java),因此天然支持装饰器风格(on(...)、wrap(...)等)的注册写法; - 常用入口是
Runner.getCallbackFramework(),返回AsyncCallbackFramework实例(见 Runner.java),也可以直接读取静态字段Runner.callbackFramework(Runner.java)。
从类结构看,AsyncCallbackFramework 内部用 ConcurrentHashMap 组织多类注册表:callbacks(事件 → 回调列表)、chains(事件 → 回调链)、filters(事件 → 过滤器列表)、hooks(事件 → HookType → hook 列表)、metrics(事件+回调 → 指标),并持有全局过滤器列表、断路器表和有界的历史队列(ArrayDeque,上限 1000 条),见 AsyncCallbackFramework.java。
二、核心主类 AsyncCallbackFramework
2.1 类声明与构造
public class AsyncCallbackFramework implements DecoratorFramework
构造函数有两个:
| 构造函数 | 说明 |
|---|---|
AsyncCallbackFramework() |
默认开启 metrics 和 logging。 |
AsyncCallbackFramework(boolean enableMetrics, boolean enableLogging) |
显式指定是否开启指标采集与回调日志。 |
对应源码实现为 AsyncCallbackFramework() 内部委托 this(true, true),见 AsyncCallbackFramework.java。框架还内置了共享的有界并行执行池(OpenJiuwenExecutors.newBoundedModulePool("callback-parallel", false))与延迟触发的调度器,供并行触发和延迟触发使用。
2.2 注册入口
框架提供了多种注册回调的方式:
| 方法 | 说明 |
|---|---|
on(event, ...) |
返回装饰器风格的注册函数,可一次指定 priority、once、namespace、tags、eventFilters、maxRetries、retryDelay、timeout、callbackType 等全部参数。 |
onChain(event, ...) |
注册链式回调,可同时配置 rollbackHandler 与 errorHandler。 |
registerSync(event, callback, ...) |
DecoratorFramework 接口要求的同步注册入口。 |
register(event, callback, ...) |
直接注册回调并返回 CallbackInfo,是 registerSync 的便捷封装。 |
unregister(event, callback) |
移除指定事件下的单个回调。 |
unregisterNamespace(namespace) |
按命名空间批量移除回调。 |
unregisterByTags(tags) |
按标签批量移除回调。 |
unregisterEvent(event) |
移除某个事件下的全部回调(连同该事件的 chains、hooks、filters 一并清理)。 |
源码中 registerSync 做了几件关键事情(AsyncCallbackFramework.java):
- 用
CallbackInfo.builder()构建回调元数据,namespace缺省为"default",tags缺省为空集合; - 写入
callbacks对应事件的同步列表并sortCallbacks(event)按优先级排序; - 若带了
eventFilters,则写入callbackFilters(按回调函数为 key); - 若带了
rollbackHandler或errorHandler,则将该回调加入该事件对应的CallbackChain; - 开启 logging 时输出
Registered callback: {event} -> {callbackName}。
2.3 触发入口
触发是回调框架最核心的运行时能力,源码中按用途划分了多种触发模式:
| 方法 | 说明 |
|---|---|
trigger(event, args, kwargs) |
DecoratorFramework 兼容入口,不返回结果(返回 void),内部委托 triggerResults(...)。 |
triggerResults(event, args, kwargs) |
顺序触发事件并返回回调结果列表 List<Object>,是最常用的“要结果”入口。 |
triggerAsync(event, args, kwargs) |
异步触发,返回 CompletableFuture<List<Object>>。 |
triggerDelayed(event, delaySeconds, args, kwargs) |
延迟触发,返回 ScheduledFuture<List<Object>>。 |
triggerParallel(event, args, kwargs) |
使用共享有界线程池并发执行当前事件的所有回调。 |
triggerUntil(event, condition, args, kwargs) |
按顺序执行,直到传入的 Predicate<Object> 命中某个回调结果为止。 |
triggerWithTimeout(event, timeoutSeconds, args, kwargs) |
给整个触发过程设置总超时,超时返回空列表并取消任务。 |
triggerStream(...) / triggerGenerator(...) |
把结果整理成 Iterator,支持流式逐项处理。 |
triggerTransform(event, args, kwargs) |
只执行 callbackType == "transform" 的回调,返回最后一个 transform 结果(无则返回 TRANSFORM_NOOP)。 |
triggerChain(event, args, kwargs) |
以链式方式执行该事件的回调链,返回 ChainResult。 |
triggerResults 的完整执行流水线(AsyncCallbackFramework.java)为:
- 若开启 history,先记录本次触发历史;
- 执行
HookType.BEFORE钩子; - 遍历该事件下按优先级排序的回调快照:
- 跳过被禁用(
enabled=false)或 transform 类型的回调; - 执行过滤器链:
STOP直接终止整个事件处理;SKIP跳过当前回调继续下一个;MODIFY使用过滤器返回的修改后参数执行; - 调用
invokeCallback(...),并携带CallbackInfo.timeout作为单回调执行超时; - 更新指标、向对应断路器记录成功、收集结果;
once回调执行后自动置为禁用;- 捕获到异常时更新指标、记录断路器失败并触发
HookType.ERROR钩子;
- 跳过被禁用(
- 执行
HookType.AFTER钩子,返回结果列表。
2.4 过滤器、hooks 与状态管理
| 能力 | 方法 | 说明 |
|---|---|---|
| 过滤器 | addFilter(event, filter) |
为指定事件追加过滤器。 |
addGlobalFilter(filter) |
追加全局过滤器,作用于所有事件。 | |
removeFilter(...) |
移除过滤器。 | |
addCircuitBreaker(event, callback, failureThreshold, timeout) |
为特定事件+回调绑定断路器(本质也是过滤器)。 | |
| hooks | addHook(event, hookType, hook) |
注册生命周期钩子,hookType 为 HookType 枚举(BEFORE/AFTER/ERROR/CLEANUP)。 |
removeHook(...) |
移除钩子。 | |
| 历史 | enableEventHistory(boolean) |
开关事件历史记录。 |
getEventHistory(event, since) |
按事件与时间戳过滤查询历史。 | |
replayEvents(since) |
重放某时间点之后的历史事件。 | |
| 持久化 | saveState(filepath) |
将回调注册信息、指标与历史序列化为 JSON 文件。 |
loadState(...) |
从文件恢复回调框架状态。 |
从源码看,saveState 使用 Jackson ObjectMapper 以 pretty-print 形式写出 callbacks、metrics、history 三部分(AsyncCallbackFramework.java);getStatistics() 可汇总 total_events、total_callbacks、namespaces、total_filters、total_chains、history_size、metrics_collected 等运行统计(AsyncCallbackFramework.java)。
三、回调元数据 CallbackInfo
CallbackInfo 描述单个回调的元数据与运行配置,字段定义见 CallbackInfo.md 与 CallbackInfo.java:
| Field | Type | Default | 说明 |
|---|---|---|---|
callback |
Function<Map<String, Object>, Object> |
- |
回调函数本体:接收 keyword-args Map,返回执行结果。 |
priority |
int |
0 |
执行优先级,数值越大越先执行。 |
once |
boolean |
false |
是否只执行一次,执行后自动禁用。 |
enabled |
boolean |
true |
当前是否可用。 |
namespace |
String |
"default" |
用于分组管理回调的命名空间。 |
tags |
Set<String> |
new HashSet<>() |
标签集合,用于按标签过滤/批量注销。 |
maxRetries |
int |
0 |
失败时的最大重试次数。 |
retryDelay |
double |
0.0 |
重试间隔(秒)。 |
timeout |
Double |
- |
单次执行超时(秒),为空表示不设超时。 |
createdAt |
double |
System.currentTimeMillis() / 1000.0 |
注册时间戳(epoch 秒)。 |
callbackName |
String |
- |
回调名称,用于日志与指标标识。 |
其中 priority 的语义在测试 AsyncCallbackFrameworkTest.java 中有明确验证:注册 priority=1、priority=20(transform)与 priority=10 三个回调后,triggerResults 实际执行顺序是 high(10) → low(1),transform 回调被跳过不参与普通触发。CallbackInfo.getCallbackDisplayName() 用于日志与指标展示。
四、链式回调与回滚:CallbackChain 与相关模型
链式回调适用于“多个步骤必须按序执行、失败时需要补偿回滚”的场景,例如多阶段资源分配、多服务调用等。
4.1 CallbackChain
CallbackChain 管理回调的顺序执行并支持回滚(CallbackChain.java):
| 成员 | 类型 | 说明 |
|---|---|---|
name |
String |
链名称。 |
callbacks |
List<CallbackInfo> |
链内回调列表,add 时按优先级降序排序。 |
rollbackHandlers |
Map<Function, Consumer<ChainContext>> |
每个回调对应的回滚处理器。 |
errorHandlers |
Map<Function, Function<ExceptionContext, Object>> |
每个回调对应的错误处理器。 |
主要方法:
| 方法 | 说明 |
|---|---|
add(callbackInfo, rollbackHandler, errorHandler) |
追加回调及对应的回滚/错误处理器。 |
remove(callback) |
移除回调并同步清理其处理器映射。 |
execute(ChainContext context) |
执行整条链,返回 CompletableFuture<ChainResult>。 |
add 与 remove 均为 synchronized 方法,保证并发注册/注销与链内排序互不交错(源码注释明确说明,见 CallbackChain.java)。
4.2 链式执行语义(ChainAction / ChainResult)
链内回调可以返回 ChainResult 来驱动控制流,ChainAction 枚举定义了四种动作(见 ChainAction.md):
| 值 | 说明 |
|---|---|
CONTINUE |
继续执行链中的下一个回调。 |
BREAK |
终止链式执行并返回当前结果。 |
RETRY |
重新执行当前回调。 |
ROLLBACK |
回滚已经执行过的回调。 |
CallbackChain.executeInternal 的执行逻辑(CallbackChain.java):
- 依次遍历链内回调,跳过禁用的;
- 每个回调最多执行
maxRetries + 1次尝试:正常结果加入context.results并记录到已执行列表;返回BREAK立即终止;RETRY重试当前回调;ROLLBACK触发回滚流程; - 回调抛异常时:若配置了
errorHandler且其返回“真值”,视为已恢复并继续;否则在重试次数耗尽后调用rollback(...),从已执行列表逆序调用各回调的rollbackHandler做补偿,最终返回ChainAction.ROLLBACK的ChainResult; - 全部成功则
context.setCompleted(true),返回ChainAction.CONTINUE与最后一个结果。
执行过程中,ChainContext 还向回调注入 _chain_context、_initial_args、_last_result、_args 等关键字(CallbackChain.java),便于回调读取链上下文与上一步结果。
4.3 ChainContext / ChainResult
ChainContext 是链式执行的运行时上下文(ChainContext.md):
| Field | 说明 |
|---|---|
event |
正在处理的事件名。 |
initialArgs / initialKwargs |
触发时传入的原始位置参数与关键字参数。 |
results |
已执行回调的结果列表。 |
metadata |
任意元数据,用于在链内各回调间共享数据。 |
currentIndex |
当前正在执行的回调下标。 |
completed |
链是否成功完成。 |
rolledBack |
链是否已回滚。 |
startTime |
链开始执行的时间戳(epoch millis)。 |
常用方法:getLastResult()(取上一个回调的结果)、getAllResults()、setMetadata(key, value) / getMetadata(key, defaultValue)、getElapsedTime()(自链开始以来的耗时)。
ChainResult 则封装链的最终结果(ChainResult.md):action(最终动作)、result(最终结果值)、context(完整执行上下文)、error(失败时的异常)。CallbackChain 还嵌套定义了 ExceptionContext(包含异常与链上下文),作为 errorHandler 的入参。
五、过滤器体系:事件控制的中枢
5.1 基类 EventFilter 与 FilterResult / FilterAction
EventFilter 是所有过滤器的基类(EventFilter.md):
public FilterResult filter(String event, CallbackInfo callback, Object[] args, Map<String, Object> kwargs)
自定义过滤器只需继承 EventFilter 并重写 filter(...) 方法。返回值 FilterResult 决定后续行为(FilterResult.md),其静态工厂方法覆盖了四种 FilterAction:
| FilterAction | 语义 | 推荐工厂方法 |
|---|---|---|
CONTINUE |
继续执行当前回调 | continueResult() / continueResult(args, kwargs) |
STOP |
停止整个事件处理流程 | stopResult(reason) |
SKIP |
跳过当前回调,继续后续回调 | skipResult(reason) |
MODIFY |
用修改后的参数继续执行 | modifyResult(modifiedArgs, modifiedKwargs) |
FilterResult 的四个字段(action、modifiedArgs、modifiedKwargs、reason)与工厂方法定义见 FilterResult.java。从 triggerResults 的过滤段(AsyncCallbackFramework.java)可以确认:STOP 直接 break 终止事件处理;SKIP 跳过当前回调;MODIFY/CONTINUE 的修改参数会替换最终传给回调的 args/kwargs。
过滤器可在三个层级生效:事件级(addFilter)、全局级(addGlobalFilter)、回调级(注册时传入 eventFilters,存入 callbackFilters)。执行时按“回调级 + 事件级 + 全局级”合并应用(见 applyFilters 实现,AsyncCallbackFramework.java)。
5.2 内置过滤器
框架开箱即用的过滤器如下(均继承 EventFilter,集中在 core/src/main/java/com/openjiuwen/core/runner/callback):
| 过滤器 | 职责 | 关键参数 | 判定行为 |
|---|---|---|---|
AuthFilter |
基于角色的访问控制 | requiredRole |
从 kwargs 读取 user_role(缺省 "guest"),不匹配则 skipResult,见 AuthFilter.java。 |
RateLimitFilter |
限流 | maxCalls、timeWindow(秒) |
以 event:callbackDisplayName 为维度做滑动窗口计数,窗口内超过 maxCalls 则 skipResult("Rate limit exceeded..."),见 RateLimitFilter.java。 |
CircuitBreakerFilter |
断路器熔断 | failureThreshold(默认 5)、timeout(默认 60 秒) |
连续失败达到阈值后打开断路器,超时窗口内对后续调用 skipResult,窗口过期自动半开恢复;成功调用 recordSuccess 复位,见 CircuitBreakerFilter.java。 |
ValidationFilter |
参数校验 | validator: Predicate<Map<String, Object>> |
校验 kwargs,不通过则返回失败结果。 |
ConditionalFilter |
条件过滤 | condition: ConditionPredicate、actionOnFalse |
条件不满足时按 actionOnFalse 指定的动作处理。 |
LoggingFilter |
日志 | Logger(可选) |
记录回调执行日志。 |
ParamModifyFilter |
参数改写 | modifier: BiFunction<Object[], Map<String, Object>, Object[]> |
返回 [newArgs, newKwargs] 二元数组以替换调用参数。 |
其中 ConditionalFilter 的 ConditionPredicate 签名是 (event, callback, args, kwargs) -> boolean(见 ConditionalFilter.md)。断路器的默认参数在无参构造中体现:new CircuitBreakerFilter() 等价于 (5, 60.0)(CircuitBreakerFilter.java)。
典型的组合用法:鉴权 → 限流 → 断路器 → 参数校验/改写,依次挂在同一个事件上,形成一条“安全加固 + 可靠性保护”的过滤链。
六、生命周期钩子 HookType
HookType 枚举定义了回调框架支持的四类生命周期钩子(HookType.md):
| 值 | 触发时机 |
|---|---|
BEFORE |
事件处理开始前。 |
AFTER |
事件处理完成后。 |
ERROR |
事件处理抛出异常时。 |
CLEANUP |
清理阶段(例如生成器模式异常退出时的收尾)。 |
钩子通过 addHook(event, hookType, hook) 注册,hook 签名为 Consumer<Map<String, Object>>。从 triggerResults 与 triggerGenerator 的源码可以确认钩子的落点:BEFORE 在遍历回调前触发、AFTER 在所有回调完成后触发(携带结果列表)、ERROR 在捕获异常后触发、CLEANUP 在生成器流程异常时触发(AsyncCallbackFramework.java)。钩子适合做跨回调的埋点、耗时统计与资源清理。
七、指标与观测 CallbackMetrics
框架默认开启指标采集(enableMetrics=true)。CallbackMetrics 维护单条(事件+回调)的统计(CallbackMetrics.md):
| Field | 类型 | 默认值 | 说明 |
|---|---|---|---|
callCount |
int |
0 |
调用次数。 |
totalTime |
double |
0.0 |
累计耗时。 |
minTime |
double |
Double.MAX_VALUE |
最小单次耗时。 |
maxTime |
double |
0.0 |
最大单次耗时。 |
errorCount |
int |
0 |
错误次数。 |
lastCallTime |
Double |
- |
最近一次调用时间。 |
方法包括 update(executionTime, isError)(同步更新统计)、getAvgTime()(平均耗时 = 累计/次数)、toMap()(转 Map 便于导出)。框架层提供 getMetrics() / getMetrics(event, callback) 查询、resetMetrics() 清零,以及 getSlowCallbacks(threshold) 按平均耗时降序筛选慢回调(AsyncCallbackFramework.java)。这些数据可配合 getStatistics() 做全局观测与调优。
八、事件命名与 scope 机制
事件名支持作用域(scope)前缀。Events 工具类(Events.java)提供:
DEFAULT_SCOPE = "_framework":默认作用域;buildEventName(scope, eventName):拼接形如scope:eventName的完整事件名;parseEventName(scopedEvent):按第一个:拆分为[scope, eventName],无:时按默认作用域处理;getEvent(eventName)/getEvent(scope, eventName):便捷构造。
仓库还在 callback 包下预置了多组业务事件常量类,如 AgentEvents、AgentTeamEvents、ContextEvents、LLMCallEvents、MemoryEvents、RetrievalEvents、SessionEvents、TaskManagerEvents、ToolCallEvents、WorkflowEvents 等,方便按模块统一管理事件名,可作为挂接全局回调时的事件源参考。
九、Runner 集成:全局入口
Runner 将回调框架作为全局能力暴露,两种取用方式等价(Runner.java):
AsyncCallbackFramework framework = Runner.getCallbackFramework();
// 或
AsyncCallbackFramework framework = Runner.callbackFramework;
Runner 内部持有一个 AsyncCallbackFramework 实例(构建于 Runner 内部类,见 Runner.java),这意味着在 Agent 运行、工作流执行、工具调用等任何环节,只要拿到 Runner 入口即可注册全局回调,实现跨模块的统一横切逻辑。
十、并发模型与使用注意
从源码可以确认以下几点运行时事实:
trigger(...)不返回结果:它是DecoratorFramework接口的兼容入口(返回void),内部仅调用triggerResults(...)(AsyncCallbackFramework.java)。需要回调结果时务必使用triggerResults(...),这是文档与测试反复强调的易错点;triggerParallel(...)使用共享有界线程池,而非虚拟线程池:并行执行池为OpenJiuwenExecutors.newBoundedModulePool("callback-parallel", false)(AsyncCallbackFramework.java),源码注释说明这是共享有界池而非每次触发的 cached 池,也不是虚拟线程池;- 线程安全设计:各注册表使用
ConcurrentHashMap,事件回调列表使用synchronizedList,过滤执行与链操作通过synchronized方法保证并发安全;CallbackChain.add/remove专门注释了与并发注册/注销的互斥保证; - 历史队列有界:
eventHistory为容量 1000 的ArrayDeque,超限自动淘汰最旧记录; - 延迟触发有调度裕量:
DELAYED_TRIGGER_SCHEDULER_LEEWAY_MILLIS = 90L,用于保证延迟回调的实际完成时间不早于预定时间(见 AsyncCallbackFramework.java)。
十一、兼容性与版本演进:关于过期类名 CallbackFramework
文档特别提示:早期文档把 Runner 回调框架主类写作 CallbackFramework,这是过期命名习惯。从当前仓库源码看,真实主类是 AsyncCallbackFramework;CallbackFramework 在文档中标记为过期页面(见 CallbackFramework.md),并建议统一使用:
AsyncCallbackFrameworkDecoratorFramework(接口)Runner.getCallbackFramework()Runner.callbackFramework
需要补充的源码事实是:当前仓库中仍保留 core/src/main/java/com/openjiuwen/core/runner/callback/CallbackFramework.java 作为 0.1.12 同步回调框架的兼容门面类,它继承 AsyncCallbackFramework 并提供旧的 register(event, callback, priority, callbackName) 便捷重载,用于老代码平滑迁移(见 CallbackFramework.java)。因此,新代码应以 AsyncCallbackFramework 为准,老代码可借助兼容门面过渡。
十二、测试验证:框架行为的可执行依据
仓库为回调框架配备了系统性的测试集,既是行为规范也是使用参考(路径 core/src/test/java/com/openjiuwen/core/runner/callback):
| 测试类 | 覆盖重点 |
|---|---|
AsyncCallbackFrameworkTest |
优先级排序、transform 回调隔离、once 语义、过滤器参数改写、triggerTransform 返回值等。 |
CallbackChainTest |
链式执行、回滚、错误恢复、重试与 ChainAction 控制流。 |
CallbackFiltersTest |
各类内置过滤器的判定行为(Auth/RateLimit/CircuitBreaker/Validation/Conditional/Logging/ParamModify)。 |
CallbackModelsTest |
CallbackInfo、CallbackMetrics、FilterResult、ChainContext 等数据模型。 |
CallbackEnumsTest / ChainActionTest / HookTypeTest / FilterActionTest |
枚举取值与语义。 |
CallbackFrameworkConcurrencyTest |
并发注册/触发/注销的线程安全。 |
各类 *PythonParityTest |
与 Python 版 AsyncCallbackFramework 行为对齐的一致性验证(注册、触发、hooks、metrics、wrap、transform-io、事件 scope、生成器、中断等)。 |
以 AsyncCallbackFrameworkTest.triggerRunsNonTransformCallbacksByPriority 为例(AsyncCallbackFrameworkTest.java),它同时验证了三件事:回调按优先级降序执行、transform 类型回调不参与普通 triggerResults、结果列表按执行顺序返回——这一测试可以直接作为自定义回调行为的参照。
结语
openJiuwen agent-core-java 的 com.openjiuwen.core.runner.callback 框架,以 AsyncCallbackFramework 为中枢,把回调注册、顺序/并行/延迟触发、过滤器控制、链式回滚、指标观测、生命周期钩子、事件历史与状态持久化整合为一套可投入生产的 Runner 级事件体系。无论是为 Agent 运行做全局日志与指标采集,还是用 AuthFilter + RateLimitFilter + CircuitBreakerFilter 构建可靠性保护链,都能在这个框架内以统一的装饰器风格完成。进一步深入可阅读 callback.README.md 及 callback 子文档目录,并对照 callback 源码目录 与 callback 测试目录 进行实践验证。