文章目录

  • PentestGPT V2 gitee镜像仓库地址
  • Langfuse 是一个专为由大型语言模型（LLM）驱动的应用而设计的开源的可观测性和分析平台。它提供了一系列功能，如跟踪、评估、测试、调试和集成，帮助开发人员和组织构建并改进 LLM 应用程序。

一 全局变量

订阅事件

«Module Level Variables»

LangfuseGlobals

_langfuse_client: Any

_current_span: Any

_user_id: str | None

_session_target: str | None

_pending_session: dict[str, Any] | None

_tool_executed: bool

«External»

EventBus

get()

subscribe()
  • 变量详细说明表
变量名 类型 说明 生命周期
_langfuse_client Any Langfuse SDK v3 客户端实例 初始化后 → shutdown
_current_span Any 顶层 span（相当于 trace） 首次工具执行时创建 → session 结束时结束
_user_id str | None 持久化用户 ID（~/.excalibur/user_id） 初始化后永久存在
_session_target str | None 当前会话目标（IP/URL） 每次 session 期间有效
_pending_session dict[str, Any] | None 等待首次工具执行的会话数据 running → 首次工具执行时创建 span
_tool_executed bool 跟踪当前会话是否已执行任何工具 每次 session 期间有效

二 函数调用关系图

清理阶段

Span 创建流程

事件处理流程

初始化阶段

延迟创建

session 结束

span 已创建

init_langfuse

_silence_langfuse_loggers

_get_or_create_user_id

_subscribe_to_events

bus.subscribe STATE_CHANGED _handle_state

bus.subscribe MESSAGE _handle_message

bus.subscribe TOOL _handle_tool

bus.subscribe FLAG_FOUND _handle_flag

_handle_state: running

_handle_state: completed/error

_handle_message

_handle_tool

_handle_flag

首次工具执行时创建 session span

创建 agent-message nested span

创建 tool-name nested span

创建 flag-found nested span

shutdown_langfuse

_current_span.end

_langfuse_client.flush

三 函数详细说明表

3.1 初始化函数

Yes

No

LANGFUSE_ENABLED=false

true

init_langfuse

disabled?

return False

env var check

_silence_langfuse_loggers

设置环境变量 PK/SK/HOST

from langfuse import get_client

_langfuse_client = get_client

_user_id = _get_or_create_user_id

_subscribe_to_events

return True

3.2 事件处理函数（4 个 Handler）

3.2.1 _handle_state(event: Event) -> None

Yes

No: completed/error

Yes

No, _pending_session exists

_handle_state

state == 'running'?

设置 _session_target

_tool_executed = False

生成 session_id

_pending_session = ...

return

_current_span exists?

_current_span.update

_current_span.end

_langfuse_client.flush

return

静默丢弃 session

重置所有状态变量

return

3.2.2 _handle_message(event: Event) -> None

No

Yes

_handle_message

client & span exist?

return

获取 text, msg_type

_current_span.start_span

name='agent-message'

msg_span.end

return

3.2.3 _handle_tool(event: Event) -> None

No

Yes

Yes - 首次工具

No - 后续工具

Yes

_handle_tool

status == 'start'?

return

_pending_session & no current_span?

创建 session span

name='excalibur:target'

_current_span.update_trace

_langfuse_client.flush

_pending_session = None

_tool_executed = True

创建 tool-name nested span

current_span exists?

3.2.4 _handle_flag(event: Event) -> None

No

Yes

_handle_flag

client & span exist?

return

获取 flag, context

_current_span.start_span

name='flag-found'

flag_span.end

return

3.3 辅助函数

3.3.1 _silence_langfuse_loggers()

_silence_langfuse_loggers

定义 noisy_loggers 列表

遍历每个 logger

setLevel CRITICAL+1

propagate = False

return

3.3.2 _get_or_create_user_id() -> str

Yes

No

_get_or_create_user_id

读取 ./.excalibur/user_id

文件存在且有值?

返回存储的 ID

生成新 UUID

确保目录存在

写入 user_id 文件

返回新 ID

3.3.3 _subscribe_to_events() -> None

_subscribe_to_events

bus = EventBus.get

bus.subscribe STATE_CHANGED _handle_state

bus.subscribe MESSAGE _handle_message

bus.subscribe TOOL _handle_tool

bus.subscribe FLAG_FOUND _handle_flag

3.3.4 shutdown_langfuse() -> None

No

Yes

shutdown_langfuse

_langfuse_client exists?

重置所有变量

_current_span.end

_langfuse_client.flush

重置所有变量

四 完整执行流程时序图

Langfuse Client EventBus Langfuse Module Application Langfuse Client EventBus Langfuse Module Application 初始化阶段 Session 开始 首次工具执行 工具执行中... loop [每个工具调用] Session 结束 Shutdown init_langfuse() _silence_langfuse_loggers() _get_or_create_user_id() subscribe all handlers get_client() emit STATE_CHANGED(running) store _pending_session emit TOOL(start) create session span (deferred) create tool-{name} nested span flush() emit TOOL(start/complete) create tool-{name} nested span emit STATE_COMPLETED _current_span.end() flush() shutdown_langfuse() reset all variables

五 Span 层次结构图

消息嵌套

工具嵌套

Session Span
excalibur:target

Tool Span
tool-name

Message Span
agent-message

Flag Span
flag-found

Sub-tool Span

Sub-message Span
  • Span 属性说明
Span 类型 name 格式 input output metadata
Session excalibur:{target} {target, task, status} {final_state, target} {target, task, version, user_id, session_id}
Tool tool-{name} {args} - {tool_name}
Message agent-message {message_type} {text} -
Flag flag-found {context} {flag} {flag, context}

六 关键设计模式总结

6.1 延迟Span创建（Deferred Span Creation）

  • 问题: 避免记录空会话（用户启动但未执行工具就退出）
  • 方案: running 状态只存储 _pending_session，首次工具执行时才创建 session span
  • 代码位置: _handle_state():167 + _handle_tool():255

6.2 静默失败（Silent Failure）

  • 问题: 遥测错误不应影响主输出
  • 方案: 所有关键操作使用 contextlib.suppress(Exception)
  • 代码位置: 所有 handler 函数中

6.3 单例模式（Singleton Pattern）

  • 问题: 确保全局只有一个 EventBus 实例
  • 方案: _instance + _lock 双重检查锁定
  • 代码位置: EventBus.get():72

6.4 观察者模式（Observer Pattern）

  • 问题: 解耦事件发布者和订阅者
  • 方案: EventBus 作为中心枢纽，handler 函数作为观察者
  • 代码位置: _subscribe_to_events():151
Logo
腾讯云开发者社区

腾讯云面向开发者汇聚海量精品云计算使用和开发经验，营造开放的云计算技术生态圈。

更多推荐

终极指南：Flink SQL连接器版本管理从混乱到有序的升级之路

Apache Flink作为流处理领域的佼佼者，其SQL连接器的版本管理一直是开发者面临的核心挑战。本文将系统讲解Flink SQL连接器版本管理的最佳实践，帮助你轻松应对版本兼容性问题，实现从混乱到有序的升级之旅。## 连接器版本管理的常见痛点 😫在Flink应用开发中，连接器版本管理常常让开发者头疼不已。不同版本的连接器可能导致各种兼容性问题，例如API变更、功能差异甚至运行时错误。

avatar 腾讯云开发者社区

Elasticsearch复杂数据类型终极指南：从入门到精通

Elasticsearch作为功能强大的搜索引擎，支持多种复杂数据类型，让开发者能够灵活处理各种结构化和非结构化数据。本文将带你全面了解Elasticsearch中的复杂数据类型，从基础概念到实际应用，助你轻松掌握数据建模的核心技巧。## 内部对象：构建层级化数据结构在Elasticsearch中，对象类型（Object）是最基础的复杂数据类型之一，用于表示具有嵌套关系的数据。例如，我们可

avatar 腾讯云开发者社区

如何快速搭建Neon无服务器PostgreSQL：面向初学者的完整指南

Neon是一款革命性的无服务器PostgreSQL解决方案，它通过分离存储和计算层，实现了自动扩缩容、类代码式数据库分支以及零级扩展能力。本指南将帮助你从零开始搭建Neon开发环境，体验这款创新数据库的强大功能。## 准备工作：环境要求与依赖项在开始搭建Neon环境前，请确保你的系统满足以下要求：- Linux操作系统（推荐Ubuntu 20.04+或Debian 11+）- Git

avatar 腾讯云开发者社区