openJiuwen agent-core 异步回调框架 AsyncCallbackFramework 完全指南:事件驱动、过滤熔断、链式回滚与 I/O 变换
openJiuwen agent-core 异步回调框架 AsyncCallbackFramework 完全指南:事件驱动、过滤熔断、链式回滚与 I/O 变换
openjiuwen.core.runner.callback.framework.AsyncCallbackFramework 是 openJiuwen agent-core 中面向 asyncio 的生产级异步回调框架,为 Agent 运行时(Runner)与业务代码提供事件注册、优先级执行、多级过滤、链式执行与回滚、性能指标与生命周期钩子等能力。读完本文,你将掌握该框架的全部 API 用法:既能用 @on 等装饰器快速接入事件,也能用 8 种触发模式编排并发、超时、流式与生成器聚合流程,还能通过 transform 管道全局拦截 Tool / LLM / Workflow 的入参与返回值,构建可观测、可回滚、可治理的 Agent 运行管线。
框架定位与核心能力
异步回调框架是 openJiuwen 中事件驱动机制的中枢。Runner 在初始化时即创建框架实例,并通过 Runner.callback_framework 暴露给上层使用;不依赖 Runner 时也可以直接实例化 AsyncCallbackFramework 独立运行。
框架的核心能力包括:
- 异步优先:所有操作(注册、触发、过滤、回滚)均基于 asyncio 实现,天然支持高并发;
- 优先级执行:
priority数值越大越先执行,便于安排鉴权、校验等关键步骤与通知、统计等辅助步骤; - 三级过滤系统:全局 / 事件 / 回调三级过滤器,内置限流、熔断、鉴权、校验等 8 种过滤器,支持自定义;
- 回调链与回滚:
trigger_chain按优先级顺序执行并把上一步结果传给下一步,任一步失败可按逆序调用已注册的rollback_handler; - 多种触发模式:顺序、并行、条件、超时、延迟、流式、生成器聚合等 8 种触发方式;
- 装饰器生态:
@on注册以及trigger_on_call、emits、emit_around、emits_stream、transform_io等自动触发与 I/O 变换装饰器; - 性能监控:调用次数、平均/最慢耗时、错误率等指标,以及慢回调排查能力;
- 生命周期钩子:BEFORE / AFTER / ERROR / CLEANUP 四种钩子;
- 事件历史与重放:可记录事件触发历史并支持按时间重放;
- 异步生成器支持:流式输入(
trigger_stream)、流式/多源聚合输出(trigger_generator、emits_stream)。
从源码结构看,框架代码位于 openjiuwen/core/runner/callback/ 目录,各模块职责清晰:framework.py 为核心类实现,decorator.py 承载全部装饰器逻辑,enums.py 定义 FilterAction、ChainAction、HookType,models.py 定义 CallbackMetrics、FilterResult、ChainContext、ChainResult、CallbackInfo 等数据模型,filters.py 实现内置过滤器,chain.py 实现回调链与回滚,events.py 定义 Agent / Tool / LLM / Workflow 等预置事件名,utils.py 提供框架单例的简化访问。
快速开始
通过 Runner 使用回调框架(Runner 实例内部即持有框架实例,见 runner.py 中 callback_framework 属性):
import asyncio
from openjiuwen.core.runner import Runner
framework = Runner.callback_framework
@framework.on("user_login", priority=10)
async def send_welcome(username: str):
print(f"Sending welcome to {username}")
return f"welcome_{username}"
async def main():
results = await framework.trigger("user_login", username="alice")
print(results) # ['welcome_alice']
asyncio.run(main())
不依赖 Runner 时,可单独创建框架实例:
from openjiuwen.core.runner.callback import AsyncCallbackFramework
framework = AsyncCallbackFramework(enable_metrics=True)
@framework.on("my_event", priority=5)
async def handler(x: int):
return x * 2
results = await framework.trigger("my_event", 3) # [6]
框架构造函数签名与参数如下:
class AsyncCallbackFramework(enable_metrics: bool = True, enable_logging: bool = True)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enable_metrics |
bool | True | 是否收集回调性能指标(调用次数、耗时、错误率等) |
enable_logging |
bool | True | 是否输出注册、触发、错误等日志 |
框架初始化时即建立如下只读视图属性,可在运行时检查注册状态:
callbacks -> Dict[str, List[CallbackInfo]]:事件名到回调信息列表的映射;chains -> Dict[str, CallbackChain]:事件名到回调链的映射;circuit_breakers -> Dict[str, CircuitBreakerFilter]:熔断器 key 到实例的映射(key 格式为事件名:回调名);callback_filters -> Dict[Callable, List[EventFilter]]:回调到其专属过滤器列表的映射。
事件、回调与优先级
框架的基本抽象是 事件 与 回调:
- 事件:字符串标识(如
"user_login"、"order.created"),用于绑定一组回调。建议使用有语义的点分形式(如user.login、order.created),避免event1、do_something等泛用名; - 回调:异步函数,在事件触发时按优先级执行;同一事件可注册多个回调;
- 优先级:
priority=N中 N 越大越先执行,未指定时默认为 0。register_sync在注册后即对回调列表按 priority 降序排序(见 framework.py)。
框架还提供了预置的标准事件名,定义在 events.py,按 Agent / Tool / LLM / Workflow / Context / Session / Memory / Retrieval / TaskManager 等类别组织,例如 AgentEvents.AGENT_STARTED、ToolCallEvents.TOOL_INVOKE_INPUT、LLMCallEvents.LLM_INVOKE_OUTPUT、WorkflowEvents.WORKFLOW_STARTED 等。事件名支持 scope:event_name 的作用域分隔格式,未指定作用域时默认使用 _framework。
注册回调:装饰器方式
@framework.on:普通事件回调
on 是核心注册装饰器,用于注册普通事件回调,支持所有触发模式:
def on(
self,
event: str,
*,
priority: int = 0,
once: bool = False,
namespace: str = "default",
tags: Optional[Set[str]] = None,
filters: Optional[List[EventFilter]] = None,
max_retries: int = 0,
retry_delay: float = 0.0,
timeout: Optional[float] = None,
callback_type: str = ""
)
| 参数 | 默认值 | 说明 |
|---|---|---|
event |
必填 | 事件名,用于绑定回调函数 |
priority |
0 | 执行优先级,数值越大越先执行 |
once |
False | 是否仅执行一次,执行后自动禁用该回调 |
namespace |
"default" |
命名空间,用于分组管理回调 |
tags |
None | 标签集合(如 {"user", "login"}),用于分类和批量管理 |
filters |
None | 该回调专属过滤器,仅对该回调生效 |
max_retries |
0 | 最大重试次数(回调链场景下生效) |
retry_delay |
0.0 | 重试间隔(秒) |
timeout |
None | 单次执行超时(秒) |
callback_type |
"" |
语义类型标记,如 "transform"、"chain" |
使用示例:
@framework.on("user_login", priority=10, once=False, namespace="auth", tags={"user", "login"})
async def handle_login(username: str, **kwargs):
print(f"User {username} logged in")
return f"welcome_{username}"
从源码实现看,on 委托给 create_on_decorator(decorator.py):它通过 framework.register_sync 完成同步注册,并返回一个 @wraps 包装的异步 wrapper,该 wrapper 记录了 callback_info.wrapper,因此 unregister 时既可以传入原始函数,也可以传入装饰器返回的包装函数。
@framework.on_transform:transform 类型回调
on_transform 是注册 transform 类型回调的便捷方式,等价于 on(event, callback_type="transform", priority=priority):
def on_transform(self, event: str, *, priority: int = 0)
此类回调仅被 trigger_transform 和 transform_io 的事件模式触发;普通 trigger 不会调用。在 trigger 的执行循环中,callback_type == "transform" 的回调会被直接跳过(见 framework.py 中 trigger 的实现)。示例:
@framework.on_transform(ToolCallEvents.TOOL_INVOKE_INPUT)
async def preprocess(inputs, **kwargs):
return ((modified_inputs,), kwargs)
@framework.on_chain:回调链专用
on_chain 专门用于注册回调链的回调。与 on() 类似,但自动设置 filters=None(回调链不支持过滤器),更适合配置回滚与错误处理函数:
def on_chain(
self,
event: str,
*,
priority: int = 0,
once: bool = False,
namespace: str = "default",
tags: Optional[Set[str]] = None,
rollback_handler: Optional[Callable] = None,
error_handler: Optional[Callable] = None,
max_retries: int = 0,
retry_delay: float = 0.0,
timeout: Optional[float] = None,
callback_type: str = ""
)
| 参数 | 默认值 | 说明 |
|---|---|---|
rollback_handler |
None | 回滚处理函数,链执行失败时按执行顺序的逆序调用(仅回调链中有效) |
error_handler |
None | 错误处理函数,回调执行出错时调用(仅回调链中有效) |
当提供了 rollback_handler 或 error_handler 时,register_sync 会自动为该事件创建 CallbackChain 并把回调及其处理器加入链中(见 framework.py 的 register_sync)。示例:
@framework.on_chain("order_process", priority=30, rollback_handler=rollback_payment)
async def process_payment(order: dict, **kwargs):
order["paid"] = True
return ChainResult(ChainAction.CONTINUE, result=order)
@framework.on_chain("order_process", priority=20, rollback_handler=rollback_inventory)
async def reserve_inventory(order: dict, **kwargs):
if order.get("quantity", 0) > 100:
return ChainResult(ChainAction.ROLLBACK, error=Exception("库存不足"))
order["reserved"] = True
return ChainResult(ChainAction.CONTINUE, result=order)
动态注册与注销回调
register:编程式注册
除装饰器外,可在运行时通过 register 动态注册回调,适用于配置驱动、插件扩展、按条件启用等场景:
async def register(
self,
event: str,
callback: Callable[..., Awaitable[Any]],
*,
priority: int = 0,
once: bool = False,
namespace: str = "default",
tags: Optional[Set[str]] = None,
filters: Optional[List[EventFilter]] = None,
rollback_handler: Optional[Callable] = None,
error_handler: Optional[Callable] = None,
max_retries: int = 0,
retry_delay: float = 0.0,
timeout: Optional[float] = None
) -> None
参数含义与 on 装饰器一致。register 内部通过 self._locks["registration"] 异步锁保护注册操作,并复用 register_sync 完成实际注册,保证并发注册的安全性。示例:
await framework.register(
"user_signup",
notify_email,
priority=20,
namespace="channels",
tags={"email"},
)
注意:当前版本中,
filters参数在使用trigger_chain触发事件时不会生效;rollback_handler与error_handler参数仅在使用trigger_chain触发事件时生效。
注销方式
框架提供四类注销操作,均通过异步锁保护:
unregister(event, callback) -> None:从事件上注销单个回调,支持传入原始回调或@on返回的包装函数(内部按「原始函数匹配 → 包装函数匹配 →__wrapped__指向原始函数」三种方式查找,见 framework.py 的unregister_sync);unregister_namespace(namespace) -> None:注销指定命名空间下的所有回调;unregister_by_tags(tags) -> None:注销带有给定标签中任意一个的回调(标签集合求交集判断);unregister_event(event) -> None:注销某事件的全部回调,并移除该事件关联的过滤器、链、钩子和熔断器。
await framework.unregister("temp_event", my_async_handler) # 单个
await framework.unregister_namespace("temp") # 按命名空间整批收回
await framework.unregister_by_tags({"temporary"}) # 按标签收回
await framework.unregister_event("temp_event") # 整事件清理
触发模式:8 种事件执行方式
框架通过 trigger 系列方法提供多种触发方式,覆盖顺序、并行、条件、超时、延迟、链式、流式与生成器聚合场景。
| 方法 | 说明 | 适用场景 |
|---|---|---|
trigger |
按优先级顺序执行,收集所有结果 | 默认方式,有依赖或需顺序时 |
trigger_parallel |
并发执行(asyncio.gather) | 多路拉取、并行请求等 I/O 密集场景 |
trigger_until |
按顺序执行,直到某回调返回值使 condition(result) 为 True 即返回 |
降级、首选/备选 |
trigger_chain |
链式执行,上一步结果传下一步,支持回滚 | 订单/支付等事务流程 |
trigger_with_timeout |
在给定总时间内执行,超时返回已收集结果 | 控制最大耗时、SLA |
trigger_delayed |
延迟指定秒数后执行 | 定时、延迟任务 |
trigger_stream |
对异步输入流逐项触发事件并流式产出结果 | 大文件、日志流、传感器数据 |
trigger_generator |
聚合各回调的异步生成器或普通返回值并逐项 yield | 多源数据聚合、流式 API |
trigger:顺序触发
async def trigger(self, event: str, *args, **kwargs) -> List[Any]
按优先级顺序执行所有已注册回调(经过滤、指标与钩子),返回所有被执行回调的返回值列表。底层执行流程(对应 framework.py 的 trigger 实现):
- 若开启事件历史,记录
{"event", "args", "kwargs", "timestamp"}; - 执行 BEFORE 钩子;
- 遍历该事件回调(
callback_type == "transform"的跳过),未启用则跳过; - 依次经过全局过滤器 → 事件过滤器 → 该回调专属过滤器:
STOP停止整次触发,SKIP跳过当前回调,MODIFY用新参数继续; - 通过
_narrow_call按函数签名裁剪多余参数,并通过_inject_session_if_needed为需要session参数的回调自动注入当前会话(来自openjiuwen.core.session.get_current_session); - 执行回调并收集结果;回调返回异步生成器时不 await,直接作为结果返回;
once=True的回调执行后自动禁用; - 单回调抛错不中断整次触发:记录指标、执行 ERROR 钩子后继续处理后续回调(
AbortError则会中止并向上抛出); - 全部完成后执行 AFTER 钩子,最后输出整条回调链的耗时拆分日志(
[RailChain],慢回调超过 1.0 秒会以 INFO 单独上报)。
trigger_parallel:并行触发
async def trigger_parallel(self, event: str, *args, **kwargs) -> List[Any]
使用 asyncio.gather 并发执行所有回调,适用于 I/O 密集型场景(多路请求、数据库查询等)。每个回调独立应用过滤器与超时(anyio.fail_after);失败的执行被记录日志并排除在返回结果之外。典型场景下并行可比顺序快约 2~4 倍(例如 3 个 0.15s 的 I/O 回调:顺序约 0.45s,并行约 0.2s)。
trigger_until:条件触发
async def trigger_until(
self,
event: str,
condition: Callable[[Any], bool],
*args,
**kwargs
) -> Optional[Any]
按优先级依次执行回调,直到某个返回值使 condition(result) 为 True 则停止并返回该结果;若无满足条件的结果返回 None。可用于首选/备选降级逻辑。
trigger_chain:链式执行与回滚
async def trigger_chain(self, event: str, *args, **kwargs) -> ChainResult
按链方式触发:按优先级顺序执行回调,将上一回调的返回值作为下一回调的第一个位置参数,其余 initial_kwargs 不变;链中可通过 kwargs["_chain_context"] 访问 ChainContext(如 get_last_result()、set_metadata()、get_metadata())。返回 ChainResult,包含最终动作、结果、上下文及可能的异常。
实现上,若该事件已有 CallbackChain(注册 on_chain 回调时创建)则直接复用,否则临时为事件下所有回调构建链(见 framework.py 的 trigger_chain)。链的执行逻辑位于 chain.py:每个回调可返回 ChainResult:
ChainResult(ChainAction.CONTINUE, result=...):继续下一回调;ChainResult(ChainAction.BREAK, result=...):中断链并返回当前结果;ChainResult(ChainAction.RETRY, ...):重试当前回调;ChainResult(ChainAction.ROLLBACK, error=...):回滚所有已执行回调。
一旦返回 ROLLBACK 或回调抛错(且重试次数用尽),框架按执行顺序的逆序调用已执行回调注册的 rollback_handler(用于退款、恢复库存、释放资源等),并在 ChainContext 上标记 is_rolled_back = True。回调超时(timeout 参数)同样触发回滚。完整示例:
from openjiuwen.core.runner import Runner
from openjiuwen.core.runner.callback import ChainAction, ChainResult
framework = Runner.callback_framework
async def rollback_payment(ctx):
print("Rollback payment")
async def rollback_inventory(ctx):
print("Rollback inventory")
@framework.on_chain("order_create", priority=30, rollback_handler=rollback_payment)
async def pay(order: dict, **kwargs):
order["paid"] = True
return ChainResult(ChainAction.CONTINUE, result=order)
@framework.on_chain("order_create", priority=20, rollback_handler=rollback_inventory)
async def reserve(order: dict, **kwargs):
if order.get("quantity", 0) > 100:
return ChainResult(ChainAction.ROLLBACK, error=Exception("Insufficient stock"))
order["reserved"] = True
return ChainResult(ChainAction.CONTINUE, result=order)
result = await framework.trigger_chain("order_create", order={"quantity": 150})
if result.action == ChainAction.ROLLBACK:
print("Order failed, rolled back")
链中数据传递:下一个回调的第一个位置参数是上一个回调的返回值;此外可通过 kwargs["_chain_context"](ChainContext)的 set_metadata(key, value) / get_metadata(key, default)、get_last_result()、get_all_results() 传递更多状态。
trigger_with_timeout:限时触发
async def trigger_with_timeout(
self,
event: str,
timeout: float,
*args,
**kwargs
) -> List[Any]
在限定总时间内触发事件(底层用 anyio.fail_after 包裹 trigger);超时则中止并返回已收集的结果(可能不完整),同时记录 warning 日志。
trigger_delayed:延迟触发
async def trigger_delayed(self, event: str, delay: float, *args, **kwargs) -> List[Any]
先 await asyncio.sleep(delay) 延迟指定秒数,再执行 trigger。
trigger_stream:流式输入触发
async def trigger_stream(
self,
event: str,
input_stream: AsyncIterator[Any],
*args,
**kwargs
) -> AsyncIterator[Any]
对异步输入流中的每一项触发事件,逐项执行回调并流式产出结果,无需将全部数据加载到内存。回调可返回普通值或异步生成器;若返回生成器,其 yield 出的每一项都会作为该次触发的产出。单个 item 处理失败不会中断整条流,错误被记录到日志和指标,失败的 item 不产生输出。适用于大文件逐行/逐块处理、实时日志分析、流式数据管道:
async def log_stream():
with open("app.log") as f:
for line in f:
yield line.strip()
@framework.on("process_log")
async def analyze_log(line: str):
if "ERROR" in line:
return {"level": "error", "line": line}
return {"level": "info", "line": line}
async for analysis in framework.trigger_stream("process_log", log_stream()):
if analysis["level"] == "error":
await alert_admin(analysis)
trigger_generator:生成器输出聚合
async def trigger_generator(self, event: str, *args, **kwargs) -> AsyncIterator[Any]
执行事件下所有回调并聚合产出:若回调返回异步生成器则迭代其产出,否则将其返回值作为单项产出;按优先级顺序逐项 yield。同时执行 BEFORE / AFTER / CLEANUP 钩子(CLEANUP 在 finally 中保证执行)。适用于多源数据聚合(DB + 缓存 + API)、流式 API 响应:
@framework.on("fetch_users")
async def from_database():
users = await db.query("SELECT * FROM users")
for user in users:
yield user
@framework.on("fetch_users")
async def from_cache():
for user in await redis.get_all("user:*"):
yield user
async for user in framework.trigger_generator("fetch_users"):
process(user)
trigger_transform:仅触发 transform 回调
async def trigger_transform(self, event: str, *args, **kwargs) -> Any
仅触发 callback_type="transform" 的回调,返回最后一个回调的结果。无 transform 回调时返回内部哨兵值 _TRANSFORM_NOOP,调用方应据此透传原始值。通常不需要直接调用此方法——transform_io 事件模式在内部使用它。
自动触发与 I/O 变换装饰器
除 @on 系列注册装饰器外,框架还提供了一组将事件触发"织入"普通函数调用的装饰器,均由 decorator.py 实现,支持异步函数、同步函数(自动提升为异步)、异步生成器与同步生成器(自动提升为异步生成器)。
trigger_on_call:函数被调用时触发
def trigger_on_call(
self,
event: str,
pass_result: bool = False,
pass_args: bool = True
)
在被装饰函数被调用时触发指定事件(函数执行前触发一次;若 pass_result 为 True 则在执行后再触发一次并传入返回值)。pass_args=True 时把函数参数传给回调。
emits:函数返回后触发
def emits(
self,
event: str,
result_key: str = "result",
include_args: bool = False
)
在被装饰函数返回后触发事件,并以 result_key 为键将返回值传给回调(默认键名 "result");include_args=True 时同时传入原始参数。对应的底层实现为 create_emit_after_decorator,支持普通函数与生成器,生成器默认按每项触发(stream_mode="per_item"),也可用 stream_mode="once" 收集全部项后触发一次。
emits_stream:异步生成器逐项触发
def emits_stream(self, event: str, item_key: str = "item") -> Callable
装饰异步生成器函数:每次 yield 时自动触发指定事件,并以 item_key(默认 "item")为键将该项传给该事件的回调;原生成器仍向调用方正常 yield。适用于实时指标发布、日志流监控、进度通知、事件溯源。流式相比批处理的特点:内存占用 O(1)、首字节延迟低、适合无限长数据、实时性好。
emit_around:前后环绕触发
def emit_around(
self,
before_event: str,
after_event: str,
pass_args: bool = True,
pass_result: bool = True,
on_error_event: Optional[str] = None
)
在函数执行前触发 before_event,执行成功后触发 after_event;若发生异常且指定了 on_error_event 则触发该事件(异常以 error 键传入),并重新抛出原异常。对于生成器函数,after_event 在全部项 yield 完成后触发(pass_result=True 时传入收集的结果列表)。
transform_io:输入输出变换
transform_io 是在调用被装饰函数前后对入参和返回值做变换的装饰器,适用于参数规范化、结果序列化、统一加解密等场景:
def transform_io(
self,
*,
input_event: Optional[str] = None,
output_event: Optional[str] = None,
result_key: str = "result",
input_transform: Optional[InputTransform] = None,
output_transform: Optional[OutputTransform] = None,
output_mode: Literal["frame", "generator"] = "frame",
)
支持两种变换方式:
- 事件模式:设置
input_event/output_event。调用被装饰函数前先触发 input_event,回调接收(*args, **kwargs)并返回(new_args, new_kwargs),框架用最后一个回调结果作为新参数;返回后(或生成器每项)触发 output_event,回调接收result_key=value并返回新值,框架用最后一个回调结果作为最终结果。注意:事件模式中只触发callback_type="transform"的回调,必须用@framework.on_transform(event)或@framework.on(event, callback_type="transform")注册;普通@framework.on注册的回调不会被transform_io触发。 - 直接回调模式:设置
input_transform/output_transform。input_transform(*args, **kwargs)返回(new_args, new_kwargs);output_transform(value)返回新值。支持同步/异步。
output_mode 控制对生成器函数的输出变换方式:
'frame'(默认):逐帧模式,对每个 yield 项单独调用 output 变换;事件模式下 output_event 对每项触发一次;'generator':生成器模式,将整个 source 异步迭代器一次性传给 output 变换。直接回调模式下output_transform须为异步生成器函数(source: AsyncIterator) -> AsyncIterator,可对每项 yield 0/1/多次,支持过滤、展开、有状态变换;事件模式下 output_event 触发一次、以 source 为参数,回调应返回可迭代对象;同步生成器自动提升为异步。对非生成器函数使用generator模式时抛出ValueError。
事件模式示例:
@framework.on_transform("transform_input")
async def normalize_input(*args, **kwargs):
return (args, {**kwargs, "limit": kwargs.get("limit", 10)})
@framework.on_transform("transform_output")
async def serialize_output(result):
return json.dumps(result) if isinstance(result, dict) else result
@framework.transform_io(
input_event="transform_input",
output_event="transform_output",
)
async def fetch_data(limit: int):
return {"count": limit}
生成器模式(直接回调)示例:
async def expand_chunks(source):
"""将每个分块拆分为独立 token。"""
async for chunk in source:
for token in chunk.split():
yield token
@framework.transform_io(output_transform=expand_chunks, output_mode="generator")
async def stream_response():
yield "hello world"
yield "foo bar baz"
# 实际 yield: "hello", "world", "foo", "bar", "baz"
从源码实现看,transform_io 根据是否设置 input_event/output_event 分别委托 create_transform_io_by_events_decorator 或 create_transform_io_decorator;在传递变换后的参数时使用 _bind_args_no_duplicate 优先以关键字传递、避免出现 "multiple values for argument" 的重复传参错误,并通过 lru_cache 缓存函数签名解析结果以降低每次调用的开销(见 decorator.py)。
过滤器与熔断器
过滤器层级与执行顺序
过滤器在回调执行前拦截并决定是否执行、如何执行。共三级:
- 全局过滤器:
add_global_filter(filter),对所有事件生效,适合日志、监控; - 事件过滤器:
add_filter(event, filter),仅对指定事件生效,适合限流、鉴权; - 回调过滤器:
on(event, filters=[...])中传入,仅对该回调生效。
执行顺序为 全局 → 事件 → 回调;任一层返回 STOP 或 SKIP 会短路后续执行或跳过当前回调(见 framework.py 的 _apply_filters,过滤器按顺序执行,MODIFY 会逐层更新参数)。
过滤动作由 enums.py 中的 FilterAction 定义:
| 动作 | 含义 |
|---|---|
CONTINUE |
继续执行回调 |
STOP |
停止整个事件的处理 |
SKIP |
跳过当前回调,继续下一个 |
MODIFY |
修改参数后继续 |
内置过滤器一览
所有内置过滤器均位于 openjiuwen.core.runner.callback,继承自 EventFilter(见 filters.py):
| 过滤器 | 功能 | 典型用途 |
|---|---|---|
RateLimitFilter(max_calls, time_window) |
在时间窗口内限制调用次数 | 防止回调执行过于频繁 |
CircuitBreakerFilter(failure_threshold, timeout) |
失败次数达到阈值后熔断,超时后尝试恢复 | 保护下游服务 |
ValidationFilter(validator) |
用自定义函数校验参数 | 参数合法性检查 |
LoggingFilter |
记录事件、回调名、参数 | 审计、调试 |
AuthFilter(required_role) |
要求 kwargs 中 user_role 等于指定角色 |
基于角色的访问控制 |
ParamModifyFilter(modifier) |
用 modifier(*args, **kwargs) 返回 (new_args, new_kwargs) 修改参数 | 转换或增强参数 |
ConditionalFilter(condition, action_on_false) |
根据 condition 决定 CONTINUE 或 action_on_false | 条件执行 |
自定义过滤器可子类化 EventFilter 并实现 async def filter(self, event, callback, *args, **kwargs) -> FilterResult。RateLimitFilter 内部使用 deque(maxlen=max_calls) 与 asyncio.Lock 保证线程安全;CircuitBreakerFilter 以 事件名:回调名 为 key 维护失败计数、熔断状态与恢复时间。
限流与鉴权示例:
from openjiuwen.core.runner import Runner
from openjiuwen.core.runner.callback import RateLimitFilter, AuthFilter
framework = Runner.callback_framework
framework.add_filter("api_call", RateLimitFilter(max_calls=100, time_window=60.0))
framework.add_filter("admin_action", AuthFilter(required_role="admin"))
@framework.on("admin_action")
async def do_admin(user_id: str, user_role: str):
return f"admin_ok_{user_id}"
await framework.trigger("admin_action", user_id="u1", user_role="admin")
熔断器 API
def add_circuit_breaker(
self,
event: str,
callback: Callable,
failure_threshold: int = 5,
timeout: float = 60.0
) -> None
为指定事件的某个回调添加熔断保护。参数:failure_threshold(打开熔断的失败次数,默认 5)、timeout(恢复尝试前的等待时间秒数,默认 60.0)。实现上,框架以 事件名:回调名 为 key 创建 CircuitBreakerFilter 并注册到事件过滤器列表(见 framework.py 的 add_circuit_breaker);框架在回调成功/失败时自动调用 record_success / record_failure。失败次数达到阈值后该回调会被跳过(SKIP),直到超过 timeout 后再次尝试。
生命周期钩子
def add_hook(self, event: str, hook_type: HookType, hook: Callable) -> None
为事件添加生命周期钩子,hook 可为同步或异步函数。钩子类型(enums.py 的 HookType):
HookType.BEFORE:事件下所有回调执行前;HookType.AFTER:所有回调执行完毕后(传入结果列表等);HookType.ERROR:某个回调抛错时(传入异常等);HookType.CLEANUP:在 finally 中执行,用于收尾(trigger_generator中保证执行)。
钩子执行由 _execute_hooks 完成:遍历对应事件与类型的钩子列表,异步函数 await 执行、同步函数直接调用,单个钩子失败只记录日志、不影响主流程(见 framework.py)。
framework.add_hook("user_login", HookType.BEFORE, on_login_before) # 同步或异步均可
framework.add_hook("user_login", HookType.AFTER, on_login_after)
指标、慢回调与性能监控
框架在 enable_metrics=True(默认开启)时,为每个回调收集 CallbackMetrics(models.py):call_count(调用次数)、total_time(累计耗时)、min_time / max_time、error_count(错误次数)、last_call_time(最近调用时间),派生 avg_time(平均耗时)与 error_rate(错误率)。
def get_metrics(
self,
event: Optional[str] = None,
callback: Optional[str] = None
) -> Dict[str, Dict[str, Any]]
返回 key 到指标字典的映射(key 格式为 事件名:回调名),可按事件或回调名筛选:
metrics = framework.get_metrics(event="user_login")
# {'user_login:handle_login': {'call_count': 3, 'avg_time': 0.002, ...}}
其他指标相关 API:
reset_metrics() -> None:清空所有性能指标;get_slow_callbacks(threshold: float = 1.0) -> List[Dict[str, Any]]:返回平均执行时间超过阈值的回调信息(含 callback、avg_time、max_time、call_count),按 avg_time 降序排列,便于性能排查。
建议在关键事件上开启 enable_metrics=True,并定期用 get_slow_callbacks 排查慢回调。另外,源码中定义了 SLOW_CALLBACK_SECONDS = 1.0 与 SLOW_CALLBACK_CHAIN_SECONDS = 0.05 两个内部阈值:单个回调超过 1 秒会以 INFO 单独上报,整条回调链合计超过 0.05 秒会输出 [RailChain] 逐回调耗时拆分日志,帮助定位是哪个 rail 钩子拖慢了事件链路。
事件历史与重放
def enable_event_history(self, enabled: bool = True) -> None
def get_event_history(
self,
event: Optional[str] = None,
since: Optional[datetime] = None
) -> List[Dict[str, Any]]
async def replay_events(self, since: Optional[datetime] = None) -> None
enable_event_history(True):开启事件历史记录。历史使用deque(maxlen=1000)存储,最多保留最近 1000 条记录,每条包含 event、args、kwargs、timestamp;get_event_history(event=None, since=None):获取已记录的事件历史,可按事件名与起始时间筛选;replay_events(since=None):按记录顺序重新触发事件(依次调用trigger),可用于故障复现、测试与补偿。has_subscribers在开启历史时恒返回 True,因此事件总会被记录。
framework.enable_event_history(True)
# ... 运行若干事件 ...
history = framework.get_event_history(event="user_login", since=datetime(2025, 1, 1))
await framework.replay_events(since=datetime(2025, 1, 1))
状态持久化与查询
save_state:保存框架元数据
def save_state(self, filepath: str) -> None
将框架状态写入文件(JSON 格式)。仅保存元数据(回调名、优先级、命名空间、标签、enabled 状态、指标、事件历史),不包含回调函数本身,因此无法直接跨进程恢复执行,但可用于诊断、审计与统计归档。
查询 API
def list_events(self, namespace: Optional[str] = None) -> List[str]
def list_callbacks(self, event: str) -> List[Dict[str, Any]]
def get_statistics(self) -> Dict[str, Any]
list_events(namespace=None):列出已注册的事件名;传入 namespace 时仅列出该命名空间下存在回调的事件;list_callbacks(event):列出某事件下所有回调的元信息(name、priority、enabled、namespace、tags、once、max_retries、timeout 等);get_statistics():获取框架整体统计——total_events(事件数)、total_callbacks(回调总数)、namespaces(命名空间集合)、total_filters(过滤器数)、total_chains(链数)、history_size(历史长度)、metrics_collected(指标数)。
Tool / LLM / Workflow 的 invoke/stream 全局拦截
Tool、BaseModelClient、Workflow 在实例化时自动将 invoke 和 stream 方法包装进对应的 transform_io 管道。注册相应事件的 transform 回调即可全局拦截所有实例的调用,无需修改各实例代码(详见高阶用法:异步回调框架)。
可用事件(定义于 events.py):
| 类 | 输入事件 | 输出事件 |
|---|---|---|
Tool.invoke |
ToolCallEvents.TOOL_INVOKE_INPUT |
ToolCallEvents.TOOL_INVOKE_OUTPUT |
Tool.stream |
ToolCallEvents.TOOL_STREAM_INPUT |
ToolCallEvents.TOOL_STREAM_OUTPUT |
BaseModelClient.invoke |
LLMCallEvents.LLM_INVOKE_INPUT |
LLMCallEvents.LLM_INVOKE_OUTPUT |
BaseModelClient.stream |
LLMCallEvents.LLM_STREAM_INPUT |
LLMCallEvents.LLM_STREAM_OUTPUT |
Workflow.invoke |
WorkflowEvents.WORKFLOW_INVOKE_INPUT |
WorkflowEvents.WORKFLOW_INVOKE_OUTPUT |
Workflow.stream |
WorkflowEvents.WORKFLOW_STREAM_INPUT |
WorkflowEvents.WORKFLOW_STREAM_OUTPUT |
输入回调接收 (*args, **kwargs) 并返回 (new_args, new_kwargs);输出回调接收 result=<value> 并返回新值;stream 的输出事件对每个 yield item 独立触发一次。示例:
from openjiuwen.core.runner import Runner
from openjiuwen.core.runner.callback.events import ToolCallEvents
fw = Runner.callback_framework
# 拦截所有 Tool.invoke 的入参
@fw.on_transform(ToolCallEvents.TOOL_INVOKE_INPUT)
async def preprocess(inputs, **kwargs):
# inputs 是 Tool.invoke 的第一个位置参数
return ((inputs,), kwargs)
# 拦截所有 Tool.invoke 的返回值
@fw.on_transform(ToolCallEvents.TOOL_INVOKE_OUTPUT)
async def postprocess(result):
return result # 原样透传,或修改后返回
该机制同样覆盖 Agent 生命周期(AgentEvents.AGENT_STARTED 等)、LLM 调用(LLM_CALL_STARTED、LLM_CALL_ERROR、LLM_RESPONSE_RECEIVED、LLM_STREAM_COMPLETED、LLM_ROUTE 等)、上下文管理、会话、记忆、检索与任务管理等多类预置事件,可作为全局可观测性与横切治理的统一入口。
与 Runner 的配合
Runner 在初始化时创建框架实例,启动后通过 Runner.callback_framework 暴露同一套框架实例(同时支持类属性访问与实例属性访问,见 runner.py)。可在 Agent / Workflow 执行前后注册事件(如 workflow_started、agent_finished),用于日志、指标、审计或扩展业务流程。Runner 的配置仍通过 Runner.set_config / Runner.get_config 管理,与回调框架解耦。
不依赖 Runner 实例时,还可以使用 utils.py 提供的单例访问工具:
get_callback_framework() -> AsyncCallbackFramework:返回 Runner 持有的框架单例;lazy_callback_framework:惰性代理对象,可在模块导入期安全使用emit_before、emit_after、transform_io等装饰器而不触发循环导入,属性访问在运行时才解析到真实框架;trigger(event, **kwargs):便捷触发函数,先通过has_subscribers判断是否存在订阅者,无订阅者时直接返回、避免无谓开销。
最佳实践
- 事件命名:使用有语义的点分形式(如
user.login、order.created),或直接复用events.py中的预置事件常量,避免泛用名; - 优先级:关键步骤(如鉴权、校验)设高 priority,辅助步骤(如通知、统计)设低 priority;
- I/O 与 CPU:I/O 密集用
trigger_parallel;CPU 密集或存在共享状态时用trigger; - 命名空间与标签:用
namespace、tags组织回调,便于unregister_namespace、unregister_by_tags批量管理; - 错误处理:对易失败的回调设置
error_handler,或在链中使用rollback_handler保证一致性; - 事务型流程:多步且需"全成功或全回滚"时使用
trigger_chain与rollback_handler; - 监控:定期用
get_slow_callbacks(threshold)排查慢回调,必要时为回调设置timeout;关注[RailChain]链路耗时日志定位瓶颈; - 全局横切:通过
transform_io事件统一拦截 Tool / LLM / Workflow 的入参出参,实现鉴权、脱敏、观测等横切关注点,避免逐实例改动。
常见问题
- 何时用 trigger 还是 trigger_parallel? 有顺序依赖或共享状态时用
trigger;回调相互独立且 I/O 密集时用trigger_parallel。 - 过滤器执行顺序? 全局过滤器 → 事件过滤器 → 回调专属过滤器;任一层可返回 STOP(停止整次触发)或 SKIP(跳过当前回调)。
- 链中数据如何传递? 下一个回调的第一个位置参数是上一个回调的返回值;此外可通过
kwargs["_chain_context"]的set_metadata/get_metadata、get_last_result()传递更多状态。 - 如何实现"仅当条件满足才执行"? 使用
ConditionalFilter,或使用trigger_until在找到第一个满足条件的结果后停止。 - 流式处理中单条失败会怎样? 单条失败不会中断流;错误会记入日志和指标,该条不产生输出,后续 item 继续处理。
- transform 回调为什么不执行? 普通
trigger会跳过callback_type="transform"的回调,需使用trigger_transform或transform_io事件模式(且需用@on_transform或on(callback_type="transform")注册)。 - unregister 时传什么? 可传原始回调函数,也可传
@on装饰器返回的包装函数,框架会按三种方式匹配后移除。
参考
- 模块索引与类清单:callback 模块 README
- 回调链类
CallbackChain:chain.md - 枚举
FilterAction/ChainAction/HookType:enums.md - 数据模型
CallbackMetrics/FilterResult/ChainContext/ChainResult/CallbackInfo:models.md - 过滤器体系:filters.md
- 完整开发指南与更多示例:高阶用法:异步回调框架
- 核心源码:framework.py、decorator.py、chain.py、filters.py、events.py
- 测试用例(覆盖注册、触发、过滤、链、钩子、指标、transform_io、生成器、事件作用域等):tests/unit_tests/core/runner/callback/