用途：指导将 Langfuse SDK 跨大版本升级，处理破坏性变更并在 API 变更间迁移。适用前提是已有 Langfuse 集成、有覆盖被追踪操作的测试套件，并准备升级用的 Git 分支。
版本路线：v3 为单一 langfuse 包、自定义 Langfuse 类，属旧版；v4 拆分为 @langfuse/client、@langfuse/tracing、@langfuse/otel，基于 OpenTelemetry，稳定；v5 沿用同一包结构并改进，为最新。
主要能力：检查当前与最新版本；v3 到 v4 的 TypeScript 迁移（安装新包、改用 LangfuseClient 与 NodeSDK 注册 LangfuseSpanProcessor、用 startActiveObservation/updateActiveObservation 替换 trace/span/generation、OpenAI 包装改为 @langfuse/openai、环境变量改为 LANGFUSE_BASE_URL、prompt.get 选项对象、sdk.shutdown 关闭）；Python v2 到 v3 迁移（改用 langfuse.decorators 的 observe 与 langfuse_context）；运行测试并验证 trace 导出；移除旧包并检查残留导入。
必要命令示例：npm install @langfuse/client @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node；npm uninstall langfuse；grep -rn "from ['"]langfuse['"]" src/。
常见错误：找不到 @langfuse/tracing 需安装对应包；langfuse.trace is not a function 说明用 v4 客户端做追踪，应改用 startActiveObservation；trace 扁平无嵌套说明未启动 OTel SDK；LANGFUSE_HOST 被忽略因 v5 弃用旧变量，需改为 LANGFUSE_BASE_URL。
输出要求：生成带版本的迁移记录，含起始与目标版本、变更的包与导入、配置变更、测试证据与回滚决策，并区分构建成功与在目标 Langfuse 项目中成功导出 trace。
限制：资料未提供具体收费、价格、平台支持范围与效果数据；实际迁移需结合自身测试与项目验证。