{
  "canonical_name": "langfuse/langfuse",
  "compilation_id": "pack_5f65fcb27355452f951d29ff981019bd",
  "created_at": "2026-05-14T10:27:59.352062+00:00",
  "created_by": "project-pack-compiler",
  "feedback": {
    "carrier_selection_notes": [
      "viable_asset_types=prompt, recipe, host_instruction, eval, preflight",
      "recommended_asset_types=prompt, recipe, host_instruction, eval, preflight"
    ],
    "evidence_delta": {
      "confirmed_claims": [
        "identity_anchor_present",
        "capability_and_host_targets_present",
        "install_path_declared_or_better"
      ],
      "missing_required_fields": [],
      "must_verify_forwarded": [
        "Run or inspect `pip install langfuse` in an isolated environment.",
        "Confirm the project exposes the claimed capability to at least one target host."
      ],
      "quickstart_execution_scope": "allowlisted_sandbox_smoke",
      "sandbox_command": "pip install langfuse",
      "sandbox_container_image": "python:3.12-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "llm_execute_isolated_install",
      "sandbox_validation_id": "sbx_323e8edd11144797b2cc30117b5d2ff8"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_d76c8776b862d70bf43436637f1148d6",
    "canonical_name": "langfuse/langfuse",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/langfuse/langfuse",
    "slug": "langfuse",
    "source_packet_id": "phit_b8e94b0121e64dec86f1a587db839bc6",
    "source_validation_id": "dval_8c486efe87fd4ad990dc77cbf338b160"
  },
  "merchandising": {
    "best_for": "需要软件开发与交付能力，并使用 chatgpt的用户",
    "github_forks": 2760,
    "github_stars": 27170,
    "one_liner_en": "🪢 Open source LLM engineering platform: LLM Observability, metrics, evals, prompt management, playground, datasets. Integrates with OpenTelemetry, Langchain, OpenAI SDK, LiteLLM, and more. 🍊YC W23",
    "one_liner_zh": "🪢 Open source LLM engineering platform: LLM Observability, metrics, evals, prompt management, playground, datasets. Integrates with OpenTelemetry, Langchain, OpenAI SDK, LiteLLM, and more. 🍊YC W23",
    "primary_category": {
      "category_id": "software-development",
      "confidence": "medium",
      "name_en": "Software Development",
      "name_zh": "软件开发与交付",
      "reason": "matched_keywords:git, sdk"
    },
    "target_user": "使用 chatgpt 等宿主 AI 的用户",
    "title_en": "langfuse",
    "title_zh": "langfuse 能力包",
    "visible_tags": [
      {
        "label_en": "Browser Agents",
        "label_zh": "浏览器 Agent",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-browser-agents",
        "type": "product_domain"
      },
      {
        "label_en": "Web Task Automation",
        "label_zh": "网页任务自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "user_job-web-task-automation",
        "type": "user_job"
      },
      {
        "label_en": "Browser Automation",
        "label_zh": "浏览器自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-browser-automation",
        "type": "core_capability"
      },
      {
        "label_en": "Checkpoint Resume",
        "label_zh": "断点恢复流程",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "workflow_pattern-checkpoint-resume",
        "type": "workflow_pattern"
      },
      {
        "label_en": "Evaluation Suite",
        "label_zh": "评测体系",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-evaluation-suite",
        "type": "selection_signal"
      }
    ]
  },
  "packet_id": "phit_b8e94b0121e64dec86f1a587db839bc6",
  "page_model": {
    "artifacts": {
      "artifact_slug": "langfuse",
      "files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json",
        "REPO_INSPECTION.md",
        "CAPABILITY_CONTRACT.json",
        "EVIDENCE_INDEX.json",
        "CLAIM_GRAPH.json"
      ],
      "required_files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json"
      ]
    },
    "detail": {
      "capability_source": "Project Hit Packet + DownstreamValidationResult",
      "commands": [
        {
          "command": "pip install langfuse",
          "label": "Python / pip · 官方安装入口",
          "source": "https://github.com/langfuse/langfuse#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "断点恢复流程",
        "评测体系"
      ],
      "eyebrow": "软件开发与交付",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要软件开发与交付能力，并使用 chatgpt的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "🪢 Open source LLM engineering platform: LLM Observability, metrics, evals, prompt management, playground, datasets. Integrates with OpenTelemetry, Langchain, OpenAI SDK, LiteLLM, and more. 🍊YC W23"
        },
        {
          "body": "未完成验证前保持审慎。",
          "label": "继续前",
          "value": "publish to Doramagic.ai project surfaces"
        }
      ],
      "guardrail_source": "Boundary & Risk Card",
      "guardrails": [
        {
          "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
          "label": "Check 1",
          "value": "不要把试用当真实运行"
        },
        {
          "body": "chatgpt",
          "label": "Check 2",
          "value": "确认宿主兼容"
        },
        {
          "body": "publish to Doramagic.ai project surfaces",
          "label": "Check 3",
          "value": "先隔离验证"
        }
      ],
      "mode": "prompt, recipe, host_instruction, eval, preflight",
      "pitfall_log": {
        "items": [
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Using client with context manager breaks the scoring",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_5afee24537ba47369cc4621f7fb18122 | https://github.com/langfuse/langfuse/issues/8138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
            ],
            "severity": "high",
            "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
            "title": "来源证据：bug: Using client with context manager breaks the scoring",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: unnamed trace name in Langfuse UI",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_a219c99fe99c4b7dab002e2b3a6296c2 | https://github.com/langfuse/langfuse/issues/13416 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "high",
            "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
            "title": "来源证据：bug: unnamed trace name in Langfuse UI",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_8657d86702904e90b9d448770e618256 | https://github.com/langfuse/langfuse/issues/8173 | 来源类型 github_issue 暴露的待验证使用条件。"
            ],
            "severity": "high",
            "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
            "title": "来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: Worker shutdown takes ~1 hour in self hosted kubernetes",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_cff1b1d1a1ca4eb892563c33d3aa62e9 | https://github.com/langfuse/langfuse/issues/8156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
            ],
            "severity": "high",
            "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
            "title": "来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_49a69075a1c346789a28db93c9ec6f3f | https://github.com/langfuse/langfuse/issues/13601 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.169.0",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_864f213fd7694eba9a4d2fe2bb9267ab | https://github.com/langfuse/langfuse/releases/tag/v3.169.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v3.169.0",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.172.0",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_14588986ba9945eeb40cbc0508e3fed0 | https://github.com/langfuse/langfuse/releases/tag/v3.172.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v3.172.0",
            "user_impact": "可能影响升级、迁移或版本选择。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.173.0",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_7560a954846b4f35aedb74de1291c9a4 | https://github.com/langfuse/langfuse/releases/tag/v3.173.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v3.173.0",
            "user_impact": "可能影响升级、迁移或版本选择。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | github_repo:642497346 | https://github.com/langfuse/langfuse | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | last_activity_observed missing"
            ],
            "severity": "medium",
            "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
            "title": "维护活跃度未知",
            "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "downstream_validation.risk_items | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.168.0",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_202b4e8c2c1f4b3790315098d1530297 | https://github.com/langfuse/langfuse/releases/tag/v3.168.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v3.168.0",
            "user_impact": "可能影响升级、迁移或版本选择。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.170.0",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_9ed6f994e1424878aa4559a73d72fc52 | https://github.com/langfuse/langfuse/releases/tag/v3.170.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v3.170.0",
            "user_impact": "可能阻塞安装或首次运行。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.174.0",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_f9cb7b7232ff4cce96f0c020fe48c7f4 | https://github.com/langfuse/langfuse/releases/tag/v3.174.0 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v3.174.0",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | issue_or_pr_quality=unknown"
            ],
            "severity": "low",
            "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
            "title": "issue/PR 响应质量未知",
            "user_impact": "用户无法判断遇到问题后是否有人维护。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 17 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：bug: Using client with context manager breaks the scoring。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 156,
        "forks": 2760,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 27170
      },
      "source_url": "https://github.com/langfuse/langfuse",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "🪢 Open source LLM engineering platform: LLM Observability, metrics, evals, prompt management, playground, datasets. Integrates with OpenTelemetry, Langchain, OpenAI SDK, LiteLLM, and more. 🍊YC W23",
      "title": "langfuse 能力包",
      "trial_prompt": "# langfuse - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langfuse 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. p-structure：仓库结构。围绕“仓库结构”模拟一次用户任务，不展示安装或运行结果。\n3. p-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. p-database：数据库设计。围绕“数据库设计”模拟一次用户任务，不展示安装或运行结果。\n5. p-tracing：追踪系统。围绕“追踪系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p-structure\n输入：用户提供的“仓库结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p-database\n输入：用户提供的“数据库设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p-tracing\n输入：用户提供的“追踪系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / p-structure：Step 2 必须围绕“仓库结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / p-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / p-database：Step 4 必须围绕“数据库设计”形成一个小中间产物，并等待用户确认。\n- Step 5 / p-tracing：Step 5 必须围绕“追踪系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langfuse/langfuse\n- https://github.com/langfuse/langfuse#readme\n- .agents/skills/add-model-price/SKILL.md\n- .agents/skills/agent-setup-maintenance/SKILL.md\n- .agents/skills/analyze-cloud-costs/SKILL.md\n- .agents/skills/backend-dev-guidelines/SKILL.md\n- .agents/skills/changelog-writing/SKILL.md\n- .agents/skills/clickhouse-best-practices/SKILL.md\n- .agents/skills/code-review/SKILL.md\n- .agents/skills/datadog-query-recipes/SKILL.md\n- .agents/skills/debug-issue-with-datadog/SKILL.md\n- .agents/skills/detect-prod-regressions/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langfuse 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "voices": [
        {
          "body": "来源平台：github。github/github_issue: bug: unnamed trace name in Langfuse UI（https://github.com/langfuse/langfuse/issues/13416）；github/github_issue: bug: Socket timeout. Expecting data, but didn't receive any in 30000ms o（https://github.com/langfuse/langfuse/issues/13601）；github/github_issue: bug: Using client with context manager breaks the scoring（https://github.com/langfuse/langfuse/issues/8138）；github/github_issue: bug: Worker shutdown takes ~1 hour in self hosted kubernetes（https://github.com/langfuse/langfuse/issues/8156）；github/github_issue: bug: AsyncStream' object has no attribute 'usage' when integrated with S（https://github.com/langfuse/langfuse/issues/8173）；github/github_release: v3.174.0（https://github.com/langfuse/langfuse/releases/tag/v3.174.0）；github/github_release: v3.173.0（https://github.com/langfuse/langfuse/releases/tag/v3.173.0）；github/github_release: v3.172.1（https://github.com/langfuse/langfuse/releases/tag/v3.172.1）；github/github_release: v3.172.0（https://github.com/langfuse/langfuse/releases/tag/v3.172.0）；github/github_release: v3.171.0（https://github.com/langfuse/langfuse/releases/tag/v3.171.0）；github/github_release: v3.170.0（https://github.com/langfuse/langfuse/releases/tag/v3.170.0）；github/github_release: v3.169.0（https://github.com/langfuse/langfuse/releases/tag/v3.169.0）。这些是项目级外部声音，不作为单独质量证明。",
          "items": [
            {
              "kind": "github_issue",
              "source": "github",
              "title": "bug: unnamed trace name in Langfuse UI",
              "url": "https://github.com/langfuse/langfuse/issues/13416"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "bug: Socket timeout. Expecting data, but didn't receive any in 30000ms o",
              "url": "https://github.com/langfuse/langfuse/issues/13601"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "bug: Using client with context manager breaks the scoring",
              "url": "https://github.com/langfuse/langfuse/issues/8138"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "bug: Worker shutdown takes ~1 hour in self hosted kubernetes",
              "url": "https://github.com/langfuse/langfuse/issues/8156"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "bug: AsyncStream' object has no attribute 'usage' when integrated with S",
              "url": "https://github.com/langfuse/langfuse/issues/8173"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v3.174.0",
              "url": "https://github.com/langfuse/langfuse/releases/tag/v3.174.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v3.173.0",
              "url": "https://github.com/langfuse/langfuse/releases/tag/v3.173.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v3.172.1",
              "url": "https://github.com/langfuse/langfuse/releases/tag/v3.172.1"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v3.172.0",
              "url": "https://github.com/langfuse/langfuse/releases/tag/v3.172.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v3.171.0",
              "url": "https://github.com/langfuse/langfuse/releases/tag/v3.171.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v3.170.0",
              "url": "https://github.com/langfuse/langfuse/releases/tag/v3.170.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v3.169.0",
              "url": "https://github.com/langfuse/langfuse/releases/tag/v3.169.0"
            }
          ],
          "status": "已收录 12 条来源",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "软件开发与交付",
      "desc": "🪢 Open source LLM engineering platform: LLM Observability, metrics, evals, prompt management, playground, datasets. Integrates with OpenTelemetry, Langchain, OpenAI SDK, LiteLLM, and more. 🍊YC W23",
      "effort": "安装已验证",
      "forks": 2760,
      "icon": "code",
      "name": "langfuse 能力包",
      "risk": "可发布",
      "slug": "langfuse",
      "stars": 27170,
      "tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "断点恢复流程",
        "评测体系"
      ],
      "thumb": "gray",
      "type": "Prompt Preview"
    },
    "manual": {
      "markdown": "# https://github.com/langfuse/langfuse 项目说明书\n\n生成时间：2026-05-14 08:22:55 UTC\n\n## 目录\n\n- [项目介绍](#p-intro)\n- [仓库结构](#p-structure)\n- [系统架构](#p-architecture)\n- [数据库设计](#p-database)\n- [追踪系统](#p-tracing)\n- [提示词管理](#p-prompts)\n- [评估系统](#p-evaluations)\n- [数据集管理](#p-datasets)\n- [队列系统](#p-queues)\n- [API 系统](#p-api)\n\n<a id='p-intro'></a>\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[仓库结构](#p-structure), [系统架构](#p-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n- [web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n- [web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n- [web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)\n- [web/src/features/feature-flags/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/feature-flags/README.md)\n- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n- [web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n</details>\n\n# 项目介绍\n\nLangfuse 是一个开源的 LLM（大型语言模型）可观测性和评估平台，专注于帮助开发团队追踪、监控和优化其 AI 应用的性能与质量。本文档将从项目架构、核心功能模块和技术实现等方面对 Langfuse 进行全面介绍。\n\n## 项目概述\n\nLangfuse 项目采用 **Monorepo**（单体仓库）架构，使用 pnpm 作为包管理器进行多包管理。项目的核心依赖和配置信息集中在根目录的 `package.json` 中定义，通过 pnpm workspace 机制管理多个子项目。资料来源：[package.json:1-50]()\n\n### 技术栈概览\n\nLangfuse 的技术栈涵盖前后端多个层面：\n\n| 层级 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | Next.js / React | Web 应用核心框架 |\n| 包管理器 | pnpm 10.33.0 | 项目依赖管理 |\n| 编程语言 | TypeScript | 全栈 TypeScript 开发 |\n| 后端服务 | Python/Worker | 数据处理和队列管理 |\n| 数据存储 | PostgreSQL, ClickHouse, Redis, S3 | 多样化数据存储方案 |\n| 状态管理 | React Context + Hooks | 前端状态管理 |\n| UI 组件 | Tailwind CSS + CVA | 样式和组件变体 |\n\n```mermaid\ngraph TD\n    A[Langfuse Monorepo] --> B[web/ - 前端应用]\n    A --> C[worker/ - 后端 Worker]\n    A --> D[packages/shared/ - 共享包]\n    B --> E[React Components]\n    B --> F[Feature Modules]\n    C --> G[Queue Processors]\n    C --> H[Data Ingestion]\n    D --> I[Shared Types]\n    D --> J[Validation Schemas]\n```\n\n## 架构设计\n\n### Monorepo 结构\n\nLangfuse 采用 pnpm workspace 实现的 Monorepo 架构，主要包含以下几个核心包：\n\n- **web**: 前端 Next.js 应用，包含 UI 组件系统和业务功能模块\n- **worker**: 后端 Worker 服务，处理数据摄取、队列管理和事件处理\n- **packages/shared**: 前后端共享的类型定义、验证模式和业务接口\n\n资料来源：[package.json:20-40]()\n\n### 前端架构分层\n\n前端代码遵循清晰的分层设计原则：\n\n```mermaid\ngraph TB\n    subgraph web/src/components\n        A[layouts/ - 页面布局组件]\n        B[design-system/ - 基础设计系统]\n        C[ui/ - 通用 UI 组件]\n        D[table/ - 表格组件]\n    end\n    \n    subgraph web/src/features\n        E[entitlements/ - 权限系统]\n        F[feature-flags/ - 功能开关]\n        G[mcp/ - MCP 服务器]\n        H[score-analytics/ - 分数分析]\n        I[filters/ - 过滤器系统]\n        J[comments/ - 评论功能]\n    end\n    \n    A --> B\n    B --> C\n    D --> C\n    E --> F\n```\n\n#### 布局系统 (layouts)\n\n`Page` 组件是所有页面的标准包装器，确保应用具有一致的布局、粘性头部和适当的滚动行为。所有页面必须包装在 `<Page>` 组件内，不能直接使用 `<main>` 元素。\n\n关键特性：\n- 封装的粘性头部 - 防止布局不一致\n- 滚动管理 - 支持 \"content-scroll\" 和 \"page-scroll\" 两种模式\n- 标准化的内边距和布局\n- 面包屑导航支持\n- 自定义头部操作区域\n\n资料来源：[web/src/components/layouts/README.md:1-30]()\n\n#### 设计系统 (design-system)\n\n设计系统文件夹包含**可复用的、原始的、展示性质的 UI 组件**。设计原则如下：\n\n| 原则 | 说明 |\n|------|------|\n| 纯展示性 | 不包含业务逻辑 |\n| 显式类型 | 使用严格的 TypeScript 类型定义 |\n| 一致性优先 | 优先考虑一致性而非灵活性 |\n| Props 优先 | 使用 Props 而非 React Context |\n\n**组件规范**：\n- 一个组件一个文件\n- 使用 CVA (Class Variance Authority) 管理变体\n- 使用显式枚举定义尺寸和变体类型\n- 布尔属性使用 `is`/`should` 前缀命名\n\n资料来源：[web/src/components/design-system/README.md:1-50]()\n\n## 核心功能模块\n\n### 权限系统 (entitlements)\n\nEntitlements 系统用于控制功能的可用性，基于组织 (organization) 级别进行管理。\n\n核心概念：\n- **Plan（套餐）**: 功能层级的划分，如 `oss`、`cloud:pro`、`self-hosted:enterprise`\n- **Entitlement（权限）**: 用户可用的功能特性，如 `playground`\n- **EntitlementLimit（权限限制）**: 资源数量限制，如 `annotation-queue-count`\n\n权限使用方式：\n| 使用场景 | 实现方式 |\n|----------|----------|\n| 客户端 | React Hooks (`hooks.ts`) |\n| 服务端 | `hasEntitlement.ts` / `hasOrganizationEntitlement` |\n\n资料来源：[web/src/features/entitlements/README.md:1-35]()\n\n### 功能开关 (feature-flags)\n\nFeature Flags 允许在运行时动态控制功能启用状态。\n\n功能开关启用条件（满足任一即可）：\n1. 用户在 `user.feature_flags` 中包含该标志\n2. 环境变量 `LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES` 被设置\n3. 用户具有管理员权限 (`user.admin === true`)\n\n```typescript\nconst isFeatureEnabled = useIsFeatureEnabled(\"feature-flag-name\");\n```\n\n资料来源：[web/src/features/feature-flags/README.md:1-15]()\n\n### MCP 服务器 (mcp)\n\nLangfuse MCP 服务器提供了 6 个 Prompt 管理工具，采用**无状态按请求架构**：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `getPrompt` | 获取完全解析的 Prompt（包含依赖替换） |\n| `getPromptUnresolved` | 获取原始 Prompt（保留依赖标签） |\n| `listPrompts` | 列出项目中所有 Prompt |\n| `createTextPrompt` | 创建新的文本 Prompt 版本 |\n| `createChatPrompt` | 创建新的聊天 Prompt 版本 |\n| `updatePromptLabels` | 更新 Prompt 标签 |\n\n**架构特点**：\n- 每个 MCP 请求创建新的服务器实例\n- 认证上下文通过闭包捕获\n- 请求完成后服务器被丢弃\n- 请求间无状态共享\n\n```mermaid\ngraph LR\n    A[MCP Client] -->|Request| B[New Server Instance]\n    B --> C[Handler with Auth Closure]\n    C --> D[Process Request]\n    D --> E[Return Response]\n    E --> F[Discard Server]\n```\n\n资料来源：[web/src/features/mcp/README.md:1-80]()\n\n### 分数分析 (score-analytics)\n\n分数分析模块提供数据分析和可视化功能。\n\n#### 关键组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `ScoreAnalyticsProvider` | ScoreAnalyticsProvider.tsx | 上下文提供者，管理数据状态 |\n| `useScoreAnalyticsQuery` | useScoreAnalyticsQuery.ts | 数据获取和转换 |\n\n#### 数据转换管道\n\n```\nAPI Response → Extract Categories → Fill Distribution Bins → \nGenerate Bin Labels → Transform Heatmap → Calculate Mode Metrics →\nFill Time Series Gaps → Namespace Categorical → Final Output\n```\n\n#### 统计分析工具\n\n`s statistics-utils.ts` 提供了多种统计分析函数：\n\n| 函数 | 功能 | 输出 |\n|------|------|------|\n| `interpretAgreement` | 解释一致性指标 | Strength + Color + Description |\n| `interpretMAE` | 解释平均绝对误差 | 相对误差分析 |\n\n资料来源：[web/src/features/score-analytics/README.md:1-60]()\n\n### 分数接口系统 (scores/interfaces)\n\n分数接口定义了完整的类型系统，支持多版本 API。\n\n#### API 版本支持\n\n| API 版本 | traceId 要求 | 支持范围 |\n|----------|-------------|----------|\n| v1 | 必需 | 仅 Trace 级别分数 |\n| v2 | 可选 | Trace + Session |\n\n#### 接口目录结构\n\n```\ninterfaces/\n├── api/\n│   ├── v1/        # 遗留 API 类型\n│   ├── v2/        # 当前 API 类型\n│   └── shared.ts  # 共享模式\n├── application/   # 应用层验证\n├── ingestion/     # 摄取类型\n└── ui/            # UI 专用类型\n```\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md:1-40]()\n\n### 过滤器系统 (filters)\n\n过滤器系统提供灵活的查询条件编码和解码功能。\n\n**支持的过滤类型**：\n\n| 类型 | 编码方式 | 说明 |\n|------|----------|------|\n| `datetime` | Date 对象 | 时间范围过滤 |\n| `number` | Number | 数值比较 |\n| `stringOptions` | 管道分隔数组 | 字符串选项 |\n| `arrayOptions` | 数组 | 数组匹配 |\n| `boolean` | true/false | 布尔过滤 |\n| `categoryOptions` | 分类选项 | 分类过滤 |\n| `positionInTrace` | 位置索引 | Trace 内位置 |\n\n资料来源：[web/src/features/filters/lib/filter-query-encoding.ts:1-50]()\n\n### 表格 peek 功能 (table/peek)\n\nPeekTable 系统允许在侧边栏中预览和查看表格数据，与主表格保持状态同步。\n\n**关键 Hook**：\n\n| Hook | 用途 |\n|------|------|\n| `usePeekTableState` | 管理 peek 上下文状态 |\n| `useSidebarFilterState` | 过滤器状态管理 |\n| `useOrderByState` | 排序状态管理 |\n\n**状态位置优先级**：\n1. Peek Context（peek 上下文）\n2. URL & Session Storage（URL 和会话存储）\n\n资料来源：[web/src/components/table/peek/README.md:1-50]()\n\n### 高级 JSON 查看器 (ui/AdvancedJsonViewer)\n\n用于可视化大型 JSON 数据的组件，具备以下能力：\n\n| 特性 | 说明 |\n|------|------|\n| 虚拟化渲染 | 使用 TanStack Virtual 处理大数据集 |\n| 迭代遍历 | 使用显式栈避免递归栈溢出 |\n| 客户端搜索 | 内存内匹配计算 |\n| 调试模式 | 通过 localStorage 启用详细日志 |\n\n**算法特点**：\n- 所有树操作使用**显式基于栈的迭代**而非递归\n- 支持深度 1000+ 的树结构安全遍历\n- 二进制搜索优化 `getNodeByIndex` 性能\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md:1-80]()\n\n### 评论提及功能 (comments/mentionParser)\n\n支持用户提及功能的解析和处理。\n\n**提及格式**：`@[DisplayName](user:userId)`\n\n**核心函数**：\n\n| 函数 | 作用 |\n|------|------|\n| `extractUniqueMentionedUserIds` | 从文本中提取所有被提及的用户 ID |\n| `sanitizeMentions` | 清理和验证提及内容 |\n| `MENTION_USER_PREFIX` | 常量 `\"user:\"` |\n\n资料来源：[web/src/features/comments/lib/mentionParser.clienttest.ts:1-30]()\n\n## 后端 Worker 系统\n\n### 事件重放脚本 (replayIngestionEventsV2)\n\n用于将历史事件重新摄取到系统的工具脚本。\n\n**主要功能**：\n- 从 S3 读取历史事件\n- 通过 HTTP POST 发送到 Langfuse Host\n- 支持检查点恢复\n- 内置速率限制和重试机制\n\n**事件键格式**：\n\n| 类型 | 格式 | 目标队列 |\n|------|------|----------|\n| 标准键 | `{projectId}/{type}/{eventBodyId}/{eventId}.json` | IngestionSecondaryQueue |\n| OTEL 键 | `otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json` | OtelIngestionQueue |\n\n**状态码处理**：\n\n| 状态码 | 含义 | 处理方式 |\n|--------|------|----------|\n| 200 | 批次接受 | 检查 skipped/errors |\n| 401 | 认证失败 | 停止处理 |\n| 400 | 请求格式错误 | 跳过并记录 |\n| 429 | 速率限制 | 指数退避重试 |\n\n**v1 vs v2 差异**：\n\n| 特性 | v1 | v2 |\n|------|----|----|\n| 基础设施访问 | Redis, ClickHouse, PostgreSQL, S3 | 仅 Langfuse Host URL |\n| 事件传递 | 直接 BullMQ addBulk | HTTP POST 到 Admin API |\n| 恢复支持 | 手动分割文件 | 内置检查点/恢复 |\n| 速率限制 | 无 | 客户端+服务端双重限制 |\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md:1-120]()\n\n### 队列填充脚本 (refillQueueEvent)\n\n用于从本地机器回填队列事件的实用工具脚本。\n\n**使用流程**：\n1. 创建 `./worker/events.jsonl` 文件\n2. 配置 `.env` 环境变量\n3. 确保 Redis 连接可达\n4. 执行 `pnpm run --filter=worker refill-queue-event`\n\n**环境变量要求**：\n```bash\nREDIS_CONNECTION_STRING=redis://:myredissecret@127.0.0.1:6379\nLANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse\nCLICKHOUSE_URL=http://localhost:8123\nCLICKHOUSE_USER=clickhouse\nCLICKHOUSE_PASSWORD=clickhouse\n```\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md:1-50]()\n\n## 依赖管理\n\n### pnpm Overrides\n\n项目使用 pnpm overrides 强制管理依赖版本：\n\n| 依赖包 | 锁定版本 | 备注 |\n|--------|----------|------|\n| zod | 4.3.6 | 数据验证库 |\n| nanoid | ^3.3.8 | ID 生成 |\n| katex | ^0.16.21 | 数学渲染 |\n| rollup | ^4.22.4 | 打包工具 |\n| @types/react-dom | 19.2.3 | React 类型 |\n| qs | 6.14.1 | 查询字符串解析 |\n| glob | ^10.5.0 | 文件匹配 |\n\n资料来源：[package.json:55-75]()\n\n## 总结\n\nLangfuse 是一个功能完备的 LLM 可观测性平台，其架构设计体现了以下特点：\n\n1. **Monorepo 组织**：通过 pnpm workspace 高效管理多个相关包\n2. **清晰的分层**：前端组件与业务逻辑分离，设计系统独立维护\n3. **多版本 API 支持**：v1/v2 API 并存，保证向后兼容\n4. **灵活的扩展机制**：Feature Flags 和 Entitlements 支持动态功能控制\n5. **完善的工具链**：事件重放、队列填充等运维工具完备\n\n该平台适用于需要追踪 AI 应用行为、评估模型性能、管理 Prompt 版本的开发团队。\n\n---\n\n<a id='p-structure'></a>\n\n## 仓库结构\n\n### 相关页面\n\n相关主题：[项目介绍](#p-intro), [系统架构](#p-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n- [web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)\n- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n- [worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n- [package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n- [web/src/components/table/peek/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/table/peek/README.md)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n- [web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)\n- [web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n- [web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n</details>\n\n# 仓库结构\n\n## 概述\n\nLangfuse 是一个开源的 LLMOps 平台，采用 Monorepo（单体仓库）架构进行项目管理。整个仓库包含多个子项目，通过 pnpm workspace 进行统一管理和协调。资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n该架构的核心设计目标是：\n\n- **代码共享**：在多个包之间共享类型定义、工具函数和业务逻辑\n- **统一版本管理**：所有子项目保持一致的依赖版本\n- **简化开发流程**：一次安装即可配置好所有开发环境\n\nLangfuse 的主要子系统包括：\n\n| 子系统 | 描述 |\n|--------|------|\n| **web** | Next.js 前端应用，提供用户界面 |\n| **worker** | 后台任务处理器，处理数据摄入和异步任务 |\n| **packages/shared** | 共享包，包含类型定义和跨模块复用代码 |\n\n资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n---\n\n## 项目架构总览\n\nLangfuse 采用分层架构，各层之间职责清晰、边界明确：\n\n```mermaid\ngraph TD\n    A[用户界面层<br/>web/src] --> B[业务功能层<br/>web/src/features]\n    B --> C[共享组件层<br/>web/src/components]\n    C --> D[设计系统层<br/>design-system]\n    A --> E[packages/shared]\n    F[后台处理层<br/>worker/src] --> E\n    G[脚本工具层<br/>worker/src/scripts] --> F\n```\n\n资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n\n---\n\n## Web 前端模块\n\nWeb 模块是 Langfuse 的用户界面层，基于 Next.js 框架构建。它采用模块化组织，将功能代码按领域进行划分。\n\n### 目录结构概览\n\n```\nweb/src/\n├── components/          # UI 组件库\n│   ├── layouts/        # 页面布局组件\n│   ├── ui/             # 基础 UI 组件\n│   ├── table/          # 表格相关组件\n│   └── design-system/  # 设计系统\n├── features/           # 功能模块\n└── ...\n```\n\n资料来源：[web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n\n### 页面布局组件\n\n`Page` 组件是所有页面的标准包装器，确保应用具有一致的布局、粘性头部和正确的滚动行为。\n\n```tsx\nimport Page from \"@/src/components/layouts/Page\";\n\nexport default function MyPage() {\n  return (\n    <Page\n      title=\"My Page\"\n      scrollable\n      headerProps={{\n        breadcrumb: [{ name: \"Home\", href: \"/\" }, { name: \"My Page\" }],\n        actionButtons: <button className=\"btn-primary\">Save</button>,\n      }}\n    >\n      <div>My page content here...</div>\n    </Page>\n  );\n}\n```\n\n资料来源：[web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n\n**重要约束**：\n\n- ⚠️ 每个页面都必须包装在 `<Page>` 内，切勿直接使用 `<main>`\n- 当内容无法良好适应页面宽度时，应使用 `ContainerPage` 组件\n\n### 设计系统\n\n设计系统位于 `web/src/components/design-system/`，包含可复用的基础 UI 组件。\n\n#### 组件设计原则\n\n| 原则 | 说明 |\n|------|------|\n| 仅展示性质 | 不包含业务逻辑 |\n| 显式类型 API | 使用严格的 TypeScript 类型定义 |\n| 一致性优先 | 优先考虑一致性而非灵活性 |\n| Props 优于 Context | 避免使用 React Context |\n\n资料来源：[web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n\n#### 目录结构\n\n```\ndesign-system/\n  Button/\n    Button.tsx\n    Button.stories.tsx\n```\n\n#### 样式与变体规范\n\n- ❌ 禁止使用 `className` 或 `style` props\n- ❌ 禁止使用任意值（如 `#fff`、`12px`）\n- ✅ 使用显式枚举\n\n```ts\nsize: \"sm\" | \"md\" | \"lg\";\nvariant: \"primary\" | \"secondary\";\n```\n\n#### Props 命名约定\n\n| 类型 | 命名方式 |\n|------|----------|\n| 布尔属性 | `isLoading`、`shouldTruncate` |\n| 互斥属性 | 使用正向命名：`suffix={null}` |\n\n资料来源：[web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n\n### 高级 JSON 查看器\n\n位于 `web/src/components/ui/AdvancedJsonViewer/`，提供虚拟化的大 JSON 数据展示能力。\n\n#### 已知限制\n\n| 限制 | 说明 |\n|------|------|\n| 无水平虚拟化 | 换行模式下会完全渲染所有宽行 |\n| 仅客户端搜索 | 所有匹配在内存中计算 |\n| 内存约束 | 100万+ 节点可能导致问题 |\n| 只读查看器 | 不支持内联编辑 |\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)\n\n#### 算法设计\n\n所有树操作使用显式基于栈的迭代而非递归：\n\n```typescript\n// ❌ 递归（深度 1000+ 可能栈溢出）\nfunction traverse(node: TreeNode) {\n  process(node);\n  node.children.forEach((child) => traverse(child));\n}\n\n// ✅ 迭代（任意深度都安全）\nfunction traverse(rootNode: TreeNode) {\n  const stack = [rootNode];\n  while (stack.length > 0) {\n    const node = stack.pop()!;\n    process(node);\n    node.children.forEach((child) => stack.push(child));\n  }\n}\n```\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)\n\n### 表格 Peek 功能\n\n`peek` 模块位于 `web/src/components/table/peek/`，支持在侧边栏中预览表格数据。\n\n#### Peek 感知状态管理\n\n| Hook | 用途 |\n|------|------|\n| `useTextSearch` | 文本搜索 |\n| `useSidebarFilterState` | 过滤器状态 |\n| `useOrderByState` | 排序状态 |\n\n资料来源：[web/src/components/table/peek/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/table/peek/README.md)\n\n---\n\n## 功能模块（Features）\n\n`web/src/features/` 目录包含各业务领域的功能实现。\n\n### Public API 模块\n\nPublic API 提供了外部访问 Langfuse 功能的接口。\n\n#### 新增 API 路由的流程\n\n| 步骤 | 操作 |\n|------|------|\n| 1 | 使用 `withMiddleware` 包装 |\n| 2 | 使用 `createAuthedAPIRoute` 创建类型安全的路由 |\n| 3 | 在 `/features/public-api/types` 添加 Zod 类型 |\n| 4 | 使用 `strict()` 定义响应对象 |\n| 5 | 抛出 `shared/src/errors` 中定义的错误 |\n| 6 | 使用 `makeZodVerifiedAPICall` 进行测试 |\n\n资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n\n### MCP 服务器模块\n\nMCP（Model Context Protocol）服务器位于 `web/src/features/mcp/`，提供提示词管理功能。\n\n#### 架构特点\n\n| 特点 | 说明 |\n|------|------|\n| 无状态设计 | 每个请求创建新的服务器实例 |\n| 闭包捕获上下文 | 认证上下文在处理函数闭包中捕获 |\n| 无会话存储 | 请求完成后服务器被丢弃 |\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n#### 可用工具\n\n| 工具 | 功能 |\n|------|------|\n| `getPrompt` | 获取已解析的提示词（含依赖替换） |\n| `getPromptUnresolved` | 获取未解析的提示词（保留原始标签） |\n| `listPrompts` | 列出所有提示词（支持过滤和分页） |\n| `createTextPrompt` | 创建文本提示词版本 |\n| `createChatPrompt` | 创建聊天提示词版本 |\n| `updatePromptLabels` | 更新提示词标签 |\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n#### 提示词解析示例\n\n```\n输入: \"You are helpful. @@@langfusePrompt:name=base-rules|label=production@@@\"\n输出: \"You are helpful. Always be kind and respectful.\"\n```\n\n### Entitlements 模块\n\n位于 `web/src/features/entitlements/`，用于控制功能可用性。\n\n#### 核心概念\n\n| 概念 | 说明 |\n|------|------|\n| **Plan** | 功能层级，如 `oss`、`cloud:pro`、`self-hosted:enterprise` |\n| **Entitlement** | 可用功能，如 `playground` |\n| **EntitlementLimit** | 资源限制，如 `annotation-queue-count` |\n\n资料来源：[web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)\n\n#### Plan 的管理方式\n\n| 环境 | 管理方式 |\n|------|----------|\n| Cloud | 通过 NextAuth 添加到 JWT 的 organization 对象 |\n| Self-hosted | 通过 NextAuth 添加到 JWT 的 `environment.selfHostedInstancePlan` |\n\n---\n\n## 共享包（packages/shared）\n\n`packages/shared` 包含跨模块复用的类型定义和工具函数。\n\n### Score 接口\n\n位于 `packages/shared/src/features/scores/interfaces/`，定义分数相关的类型和验证逻辑。\n\n#### 目录结构\n\n```\ninterfaces/\n├── api/              # API 相关类型\n│   ├── v1/           # 遗留 API 类型（仅 trace）\n│   ├── v2/           # 当前 API 类型（支持 trace、session）\n│   └── shared.ts     # 通用类型\n├── application/      # 应用层验证\n├── ingestion/        # 数据摄入类型\n└── ui/               # UI 组件类型\n```\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n#### API 版本差异\n\n| 操作 | V1 API | V2 API |\n|------|--------|--------|\n| GET | 需要 `traceId`，仅支持 trace 级分数 | `traceId` 可选，支持 `sessionId` |\n| POST/DELETE | 支持所有类型 | 支持所有类型 |\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## Worker 后台处理模块\n\n`worker` 模块负责处理后台任务，包括数据摄入和异步任务执行。\n\n### 脚本工具\n\n位于 `worker/src/scripts/`，提供数据处理和队列管理工具。\n\n#### Replay Ingestion Events V2\n\n用于重放 S3 中的摄入事件到 Langfuse。\n\n**事件转换规则**：\n\n| 事件类型 | 键格式 | 目标队列 |\n|----------|--------|----------|\n| 标准事件 | `{projectId}/{type}/{eventBodyId}/{eventId}.json` | IngestionSecondaryQueue |\n| OTEL 事件 | `otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json` | OtelIngestionQueue |\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n#### Refill Queue Event\n\n用于从本地机器回填队列事件。\n\n**环境要求**：\n\n| 变量 | 说明 |\n|------|------|\n| `REDIS_CONNECTION_STRING` | Redis 连接字符串 |\n| `CLICKHOUSE_URL` | ClickHouse 服务器地址 |\n| `LANGFUSE_S3_EVENT_UPLOAD_BUCKET` | S3 存储桶名称 |\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n\n---\n\n## 依赖管理\n\n### pnpm Workspace 配置\n\nLangfuse 使用 pnpm workspace 管理多包项目，通过 `package.json` 中的 `pnpm` 配置进行全局依赖覆盖。\n\n```json\n{\n  \"pnpm\": {\n    \"overrides\": {\n      \"zod\": \"4.3.6\",\n      \"nanoid\": \"^3.3.8\",\n      \"katex\": \"^0.16.21\",\n      \"tar-fs\": \"^2.1.2\",\n      \"rollup@^4.0.0\": \"^4.22.4\"\n    }\n  }\n}\n```\n\n资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n### 包管理器版本\n\nLangfuse 使用 `pnpm@10.33.0` 作为包管理器。\n\n资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n---\n\n## 技术栈总结\n\n```mermaid\ngraph LR\n    subgraph \"前端层\"\n        A[Next.js]\n        B[React]\n        C[Tailwind CSS]\n    end\n    \n    subgraph \"后端层\"\n        D[Worker]\n        E[BullMQ]\n        F[Redis]\n    end\n    \n    subgraph \"数据层\"\n        G[ClickHouse]\n        H[S3 Storage]\n        I[PostgreSQL]\n    end\n    \n    A --> G\n    A --> I\n    D --> E\n    E --> F\n    D --> G\n    D --> H\n```\n\n---\n\n## 开发指南\n\n### 添加新功能模块\n\n1. 在 `web/src/features/` 下创建新模块目录\n2. 在 `web/src/components/design-system/` 中添设计系统组件\n3. 在 `packages/shared` 中添加共享类型定义\n4. 更新 API 路由时使用标准流程\n\n资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n\n### 运行测试\n\n```bash\n# 运行前端测试\npnpm --filter=web run test-client --testPathPattern=\"AdvancedJsonViewer\"\n\n# 运行工作线程脚本\npnpm run --filter=worker refill-queue-event\n```\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)、[worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n\n---\n\n<a id='p-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[数据库设计](#p-database), [队列系统](#p-queues), [仓库结构](#p-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/server/redis/redis.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/redis.ts)\n- [packages/shared/src/server/clickhouse/client.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/clickhouse/client.ts)\n- [packages/shared/src/db.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/db.ts)\n- [worker/src/app.ts](https://github.com/langfuse/langfuse/blob/main/worker/src/app.ts)\n- [web/next.config.mjs](https://github.com/langfuse/langfuse/blob/main/web/next.config.mjs)\n</details>\n\n# 系统架构\n\n## 概述\n\nLangfuse 是一个开源的 LLM 工程平台，采用分布式微服务架构设计。系统由多个核心组件构成，包括 Web 前端服务、Worker 后台处理服务、数据存储层和缓存层。这种架构设计实现了前端展示与后端处理的分离，保证了系统的高可用性和可扩展性。\n\nLangfuse 的技术栈涵盖了现代 Web 开发的多个层面：使用 Next.js 构建前端应用、使用 BullMQ 与 Redis 实现异步任务队列、使用 PostgreSQL 存储核心业务数据、使用 ClickHouse 处理分析查询、使用 S3 兼容存储管理事件文件。\n\n## 核心架构组件\n\n### 整体架构图\n\n```mermaid\ngraph TB\n    subgraph Client[\"客户端层\"]\n        Web[Web 前端<br/>Next.js]\n    end\n\n    subgraph API[\"API 层\"]\n        TRPC[tRPC API]\n    end\n\n    subgraph Worker[\"Worker 层\"]\n        Queue[BullMQ 队列]\n        Worker[Worker 进程]\n    end\n\n    subgraph Storage[\"存储层\"]\n        Redis[(Redis<br/>队列/缓存)]\n        Postgres[(PostgreSQL<br/>核心数据)]\n        ClickHouse[(ClickHouse<br/>分析数据)]\n        S3[(S3 存储<br/>事件文件)]\n    end\n\n    Web --> TRPC\n    TRPC --> Postgres\n    TRPC --> Redis\n    TRPC --> ClickHouse\n    TRPC --> S3\n    Queue --> Redis\n    Worker --> Queue\n    Worker --> Postgres\n    Worker --> ClickHouse\n    Worker --> Redis\n    Worker --> S3\n```\n\n### 技术栈概览\n\n| 组件 | 技术选型 | 用途 |\n|------|----------|------|\n| 前端框架 | Next.js | 用户界面和服务端渲染 |\n| API 层 | tRPC | 类型安全的 API 调用 |\n| 后台任务 | BullMQ + Worker | 异步任务处理 |\n| 主数据库 | PostgreSQL | 业务数据持久化 |\n| 分析数据库 | ClickHouse | OLAP 查询和分析 |\n| 缓存/队列 | Redis | 缓存、限流、队列 |\n| 对象存储 | S3 兼容 | 事件文件存储 |\n\n## Web 前端服务\n\n### Next.js 应用架构\n\nWeb 前端基于 Next.js 框架构建，采用 App Router 架构进行路由管理。前端服务负责用户交互界面、数据展示和 API 调用。\n\nWeb 前端的源码位于 `web/` 目录，其核心配置文件包括 Next.js 配置和应用程序入口点。\n\n```mermaid\ngraph LR\n    subgraph Web[\"Web 服务\"]\n        Next[Next.js App]\n        Config[next.config.mjs]\n        Components[React 组件]\n        Features[Feature 模块]\n    end\n\n    subgraph API[\"后端通信\"]\n        TRPC[tRPC Client]\n        HTTP[REST API]\n    end\n\n    Next --> Components\n    Next --> Features\n    Components --> TRPC\n    Features --> TRPC\n    TRPC --> HTTP\n```\n\n前端采用模块化设计，将功能划分为独立的 Feature 目录，例如：\n\n- `features/prompts` - 提示词管理\n- `features/score-analytics` - 评分分析\n- `features/filters` - 过滤功能\n- `features/mcp` - MCP 服务器集成\n- `features/comments` - 评论功能\n- `features/entitlements` - 权限控制\n\n## Worker 后台服务\n\n### Worker 应用架构\n\nWorker 服务是 Langfuse 的后台任务处理核心，负责处理异步任务，包括数据摄入、队列管理和事件处理。\n\nWorker 的主入口文件位于 `worker/src/app.ts`，该文件初始化 Worker 应用并注册各种处理器。\n\n```mermaid\ngraph TB\n    subgraph WorkerApp[\"Worker 应用\"]\n        Init[应用初始化]\n        QueueProcessors[队列处理器]\n        Schedulers[定时任务]\n    end\n\n    subgraph Queues[\"队列系统\"]\n        IngestionQueue[摄入队列]\n        OtelQueue[OTEL 队列]\n        SecondaryQueue[二级处理队列]\n    end\n\n    Init --> QueueProcessors\n    QueueProcessors --> IngestionQueue\n    QueueProcessors --> OtelQueue\n    QueueProcessors --> SecondaryQueue\n```\n\n### 队列系统\n\nLangfuse 使用 BullMQ 实现任务队列，支持多种队列类型：\n\n| 队列名称 | 用途 | 数据来源 |\n|----------|------|----------|\n| IngestionQueue | 事件摄入处理 | S3 文件 |\n| OtelIngestionQueue | OpenTelemetry 数据摄入 | OTEL 格式文件 |\n| IngestionSecondaryQueue | 二次处理队列 | 内部触发 |\n| ScoreCalculationQueue | 评分计算 | 异步计算任务 |\n\n### Worker 数据处理流程\n\n```mermaid\ngraph TD\n    A[接收 HTTP 请求] --> B[验证请求参数]\n    B --> C{请求类型}\n    C -->|admin API| D[写入队列]\n    C -->|普通请求| E[直接处理]\n    D --> F[Worker 获取任务]\n    F --> G[读取 S3 文件]\n    G --> H[解析事件数据]\n    H --> I[数据转换]\n    I --> J[写入 PostgreSQL]\n    J --> K[写入 ClickHouse]\n    K --> L[任务完成]\n    E --> L\n```\n\nWorker 服务实现了无状态架构设计：每个 MCP 请求创建新的服务器实例，认证上下文通过闭包捕获，请求完成后服务器被丢弃，任务处理器之间无共享状态。\n\n## 数据存储层\n\n### PostgreSQL 数据库\n\nPostgreSQL 作为 Langfuse 的主数据库，存储所有核心业务数据，包括用户信息、项目配置、提示词版本、追踪记录等。\n\n数据库连接通过 `packages/shared/src/db.ts` 中的 Prisma Client 实现，该模块提供统一的数据库访问接口。\n\n```mermaid\ngraph TB\n    subgraph Postgres[(PostgreSQL)]\n        Users[用户表]\n        Projects[项目表]\n        Prompts[提示词表]\n        Traces[追踪表]\n        Scores[评分表]\n    end\n\n    subgraph Tables[\"核心数据表\"]\n        Organizations[组织表]\n        Members[成员表]\n        Datasets[数据集表]\n    end\n```\n\n### ClickHouse 分析数据库\n\nClickHouse 是 Langfuse 的分析查询引擎，专门用于处理大规模追踪数据的 OLAP 查询。分析功能包括评分趋势分析、热力图生成、时间序列聚合等。\n\nClickHouse 客户端配置位于 `packages/shared/src/server/clickhouse/client.ts`，该模块初始化 ClickHouse 连接并提供查询接口。\n\n| 功能模块 | 数据表 | 用途 |\n|----------|--------|------|\n| score-analytics | 评分数据表 | 评分统计和分析 |\n| traces | 追踪事件表 | 追踪数据分析 |\n| observations | 观察数据表 | LLM 调用分析 |\n\n### Redis 缓存与队列\n\nRedis 在 Langfuse 架构中承担多重职责：作为任务队列的后端存储、实现 API 限流、提供数据缓存加速查询。\n\nRedis 客户端配置位于 `packages/shared/src/server/redis/redis.ts`，该模块封装了 Redis 连接管理和常用操作。\n\n```mermaid\ngraph LR\n    subgraph Redis[(Redis)]\n        Queues[BullMQ 队列]\n        Cache[数据缓存]\n        RateLimit[限流控制]\n        Locks[分布式锁]\n    end\n\n    subgraph CacheKeys[\"缓存键结构\"]\n        PromptCache[prompt:{projectId}:{name}:{version}]\n        SessionCache[session:{sessionId}]\n    end\n\n    Redis --> Queues\n    Redis --> Cache\n    Redis --> RateLimit\n    Redis --> Locks\n```\n\n### S3 对象存储\n\nS3 存储用于保存原始事件文件，包括追踪事件、OTEL 数据和大型 JSON 对象。Worker 服务从 S3 读取事件文件进行处理，处理后的结构化数据存入 PostgreSQL 和 ClickHouse。\n\n事件文件存储路径遵循特定格式：`{projectId}/{type}/{eventBodyId}/{eventId}.json`，便于快速定位和检索。\n\n## 服务间通信\n\n### tRPC API 调用\n\nWeb 前端与后端服务通过 tRPC 进行类型安全的 API 通信。tRPC 提供了端到端的类型推断，减少了前后端接口不匹配的问题。\n\nAPI 路由定义采用模块化结构，每个 Feature 拥有独立的 Router 文件，例如：\n\n- `scoreAnalyticsRouter` - 评分分析 API\n- `promptRouter` - 提示词管理 API\n- `traceRouter` - 追踪数据 API\n\n### 缓存策略\n\nLangfuse 实现了多级缓存策略以提升系统性能：\n\n1. **Redis 缓存层**：提示词内容缓存，避免重复查询数据库\n2. **TTK 重置机制**：缓存条目被访问时自动重置 TTL\n3. **写时失效**：数据更新时清除相关缓存条目\n\n缓存键结构示例：`prompt:<project-id>:<prompt-name>:<version-or-label>`\n\n```mermaid\ngraph TD\n    A[读取请求] --> B{检查 Redis 锁}\n    B -->|有锁| C[等待或降级]\n    B -->|无锁| D{检查缓存}\n    D -->|命中| E[返回缓存数据]\n    D -->|未命中| F[查询 PostgreSQL]\n    F --> G[写入 Redis]\n    G --> H[返回数据]\n    E --> I[重置 TTL]\n```\n\n## 权限与认证\n\n### 组织级权限模型\n\nLangfuse 采用组织级权限管理模型，权限通过 Plan 和 Entitlement 两层机制控制。\n\n| 概念 | 定义 | 管理位置 |\n|------|------|----------|\n| Plan | 功能等级，如 oss、cloud:pro、self-hosted:enterprise | plans.ts |\n| Entitlement | 具体功能，如 playground、annotation-queue-count | entitlements.ts |\n| EntitlementLimit | 资源数量限制 | entitlements.ts |\n\nPlan 信息通过以下方式获取：\n\n- Cloud 版本：通过 NextAuth JWT 获取\n- Self-hosted：通过环境变量或许可证密钥获取\n\n### 权限检查流程\n\n```mermaid\ngraph TB\n    A[请求进入] --> B{获取 Organization}\n    B --> C{检查 JWT 中的 Plan}\n    C -->|Cloud| D[使用 cloudConfig]\n    C -->|Self-hosted| E[检查许可证]\n    D --> F[加载 Entitlements]\n    E --> F\n    F --> G{验证功能权限}\n    G -->|通过| H[处理请求]\n    G -->|拒绝| I[返回 403]\n```\n\n## 部署架构\n\n### 服务组件关系\n\n```mermaid\ngraph TB\n    subgraph Deployment[\"部署拓扑\"]\n        Web[Web 服务<br/>Next.js]\n        API[API 服务]\n        Worker1[Worker 实例 1]\n        Worker2[Worker 实例 2]\n        WorkerN[Worker 实例 N]\n    end\n\n    subgraph Shared[\"共享服务\"]\n        Redis[(Redis Cluster)]\n        Postgres[(PostgreSQL)]\n        ClickHouse[(ClickHouse)]\n        S3[(S3 兼容存储)]\n    end\n\n    Web --> API\n    API --> Redis\n    API --> Postgres\n    API --> ClickHouse\n    API --> S3\n    Worker1 --> Redis\n    Worker2 --> Redis\n    WorkerN --> Redis\n    Worker1 --> Postgres\n    Worker2 --> Postgres\n    WorkerN --> Postgres\n    Worker1 --> ClickHouse\n    Worker2 --> ClickHouse\n    Worker1 --> S3\n    Worker2 --> S3\n```\n\n### 环境配置\n\n主要环境变量配置项：\n\n| 变量名 | 用途 | 示例值 |\n|--------|------|--------|\n| DATABASE_URL | PostgreSQL 连接 | postgresql://user:pass@host:5432/db |\n| REDIS_CONNECTION_STRING | Redis 连接 | redis://:secret@host:6379 |\n| CLICKHOUSE_URL | ClickHouse 连接 | http://localhost:8123 |\n| LANGFUSE_S3_EVENT_UPLOAD_BUCKET | S3 存储桶 | langfuse-events |\n\n## 源码文件引用\n\n本文档基于以下核心源码文件编写：\n\n- `packages/shared/src/server/redis/redis.ts` - Redis 客户端封装\n- `packages/shared/src/server/clickhouse/client.ts` - ClickHouse 连接配置\n- `packages/shared/src/db.ts` - Prisma 数据库客户端\n- `worker/src/app.ts` - Worker 应用入口\n- `web/next.config.mjs` - Next.js 应用配置\n\n---\n\n<a id='p-database'></a>\n\n## 数据库设计\n\n### 相关页面\n\n相关主题：[系统架构](#p-architecture), [追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/prisma/schema.prisma](https://github.com/langfuse/langfuse/blob/main/packages/shared/prisma/schema.prisma)\n- [packages/shared/clickhouse/migrations/clustered](https://github.com/langfuse/langfuse/blob/main/packages/shared/clickhouse/migrations/clustered)\n- [packages/shared/src/server/repositories](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories)\n- [packages/shared/src/tableDefinitions](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions)\n- [worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n</details>\n\n# 数据库设计\n\n## 概述\n\nLangfuse 采用多数据库架构，针对不同的数据访问模式选择最适合的存储方案。系统主要使用三种数据存储技术：**PostgreSQL** 作为主关系型数据库，**ClickHouse** 用于事件分析和时序数据，**Redis** 用于缓存和消息队列。这种混合架构平衡了事务一致性、查询性能和实时处理能力。\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n## 架构概览\n\n```mermaid\ngraph TB\n    subgraph 客户端层\n        A[Langfuse SDK] --> B[Ingestion API]\n        C[Web UI] --> D[Management API]\n    end\n    \n    subgraph 数据处理层\n        B --> E[BullMQ Queue]\n        E --> F[Worker Process]\n    end\n    \n    subgraph 存储层\n        F --> G[(PostgreSQL)]\n        F --> H[(ClickHouse)]\n        F --> I[(Redis)]\n        D --> G\n        D --> H\n    end\n    \n    subgraph 查询层\n        G --> J[Repository Pattern]\n        H --> K[ClickHouse Queries]\n        I --> L[Cache Layer]\n    end\n```\n\nLangfuse 的数据流向遵循以下原则：所有写入操作通过消息队列异步处理，确保高并发场景下的稳定性；读取操作根据数据类型选择最优存储引擎。`Observation` 和 `Trace` 等核心实体同时存在于 PostgreSQL 和 ClickHouse 中，前者保证关系完整性，后者支持复杂分析查询。\n\n资料来源：[packages/shared/src/server/repositories]()\n\n## PostgreSQL 核心表设计\n\n### 实体关系模型\n\nPostgreSQL 使用 Prisma ORM 进行模式管理，所有表设计遵循标准关系型数据库规范。核心实体包括组织、项目、用户、追踪、观察、提示词和数据集。\n\n```mermaid\nerDiagram\n    Organization ||--o{ Project : contains\n    Project ||--o{ ApiKey : has\n    Project ||--o{ Trace : contains\n    Project ||--o{ Dataset : contains\n    Project ||--o{ Prompt : contains\n    Trace ||--o{ Observation : contains\n    Trace ||--o{ Score : has\n    Observation ||--o{ Score : has\n    Dataset ||--o{ DatasetItem : contains\n    Dataset ||--o{ DatasetRun : has\n    User ||--o{ Membership : belongs_to\n    Organization ||--o{ Membership : has\n```\n\n### 主要数据表\n\n| 表名 | 描述 | 关联 |\n|------|------|------|\n| `Organization` | 组织租户 | 顶层实体 |\n| `Project` | 项目空间 | 属于组织 |\n| `User` | 用户账户 | 通过Membership关联 |\n| `Membership` | 组织成员关系 | User-Organization多对多 |\n| `ApiKey` | API密钥 | 属于项目 |\n| `Trace` | 追踪记录 | 属于项目 |\n| `Observation` | 观察单元 | 属于追踪 |\n| `Score` | 评分数据 | 可关联追踪或观察 |\n| `Prompt` | 提示词模板 | 属于项目 |\n| `Dataset` | 数据集 | 属于项目 |\n| `DatasetItem` | 数据集项 | 属于数据集 |\n| `DatasetRun` | 数据集运行 | 属于数据集 |\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n### Trace 表结构\n\n`Trace` 表是 Langfuse 数据模型的核心，用于记录完整的 LLM 调用会话：\n\n```prisma\nmodel Trace {\n  id            String       @id @default(cuid())\n  name          String?\n  userId        String?\n  projectId     String\n  metadata      Json?\n  release       String?\n  version       String?\n  createdAt     DateTime     @default(now())\n  updatedAt     DateTime     @updatedAt\n  \n  observations  Observation[]\n  scores        Score[]\n  sessions      Session[]\n}\n```\n\n关键字段说明：\n- `id`: 全局唯一标识符，使用 CUID 算法生成\n- `name`: 可选的追踪名称，便于识别\n- `userId`: 终端用户标识，用于多用户场景\n- `metadata`: 灵活 JSON 字段存储附加信息\n- `release`: 发布版本标签\n- `version`: 追踪数据版本\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n### Observation 表结构\n\n`Observation` 表存储追踪内的具体调用单元，支持多种事件类型：\n\n```prisma\nmodel Observation {\n  id            String       @id @default(cuid())\n  traceId       String\n  type          ObservationType\n  name          String?\n  startTime     DateTime\n  endTime       DateTime?\n  metadata      Json?\n  \n  // 嵌套调用\n  parentObservationId String?\n  parentObservation   Observation? @relation(...)\n  childObservations   Observation[]\n  \n  // 嵌入内容\n  input      String?\n  output     String?\n  usage      Json?\n  parameters Json?\n  \n  // 成本追踪\n  promptTokens        Int?\n  completionTokens    Int?\n  totalTokens         Int?\n  unitDollarPrice     Float?\n  totalDollarPrice   Float?\n  \n  scores      Score[]\n}\n```\n\n`ObservationType` 枚举定义事件类型：\n- `CHAT Spike`: 聊天消息\n- `COMPLETION`: 文本补全\n- `CHUNK`: 流式数据块\n- `GENERATION`: 生成事件\n- `EVENT`: 通用事件\n- `SPAN`: 跨度（包含子事件）\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n### Score 评分设计\n\n评分系统支持多维度评估，采用灵活的 JSON 结构：\n\n```prisma\nmodel Score {\n  id            String       @id @default(cuid())\n  name          String\n  value         Float\n  dataType      ScoreDataType\n  \n  // 评分来源\n  source        ScoreSource\n  \n  // 关联对象\n  traceId       String?\n  observationId String?\n  \n  // 评分者信息\n  authorId      String?\n  comment       String?\n  \n  createdAt     DateTime     @default(now())\n}\n```\n\n评分数据类型：\n- `NUMERIC`: 数值型评分\n- `CATEGORICAL`: 分类型评分\n- `BOOLEAN`: 布尔型评分\n\n评分来源包括 `API`、`INGESTION`、`EVALUATION`、`USER`、`BENCHMARK` 等。\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n资料来源：[packages/shared/src/features/scores/interfaces/README.md]()\n\n## ClickHouse 事件存储\n\n### 事件存储架构\n\nClickHouse 作为列式存储数据库，专门用于高吞吐量的事件数据和分析查询。所有通过 Ingestion API 摄入的事件都会写入 ClickHouse，形成持久化的事件流。\n\n```mermaid\ngraph LR\n    A[SDK Events] --> B[Ingestion API]\n    B --> C[Event Validation]\n    C --> D[Queue Event]\n    D --> E[Worker Processing]\n    E --> F[(ClickHouse)]\n    E --> G[(PostgreSQL)]\n    \n    F --> H[Analytics Queries]\n    G --> I[Relational Queries]\n```\n\n事件数据按时间分区存储，支持高效的时间范围查询。数据采用分层设计：原始事件存储在 ClickHouse，经过处理的关系数据同步到 PostgreSQL。\n\n资料来源：[packages/shared/clickhouse/migrations/clustered]()\n资料来源：[worker/src/scripts/refillQueueEvent/README.md]()\n\n### ClickHouse 表结构\n\nClickHouse 采用物化视图和合并树引擎优化查询性能：\n\n```sql\nCREATE TABLE events (\n    id UUID,\n    project_id String,\n    trace_id String,\n    type String,\n    body String,\n    event_timestamp DateTime,\n    created_at DateTime\n) ENGINE = MergeTree()\nORDER BY (project_id, event_timestamp, id)\nPARTITION BY toYYYYMM(event_timestamp);\n```\n\n关键设计决策：\n- 使用 `project_id` 作为排序键首位，支持项目级高效过滤\n- 按月份分区，便于历史数据管理\n- 事件体存储为字符串，支持灵活的反序列化\n\n资料来源：[packages/shared/clickhouse/migrations/clustered]()\n\n### OTEL 事件格式\n\nOpenTelemetry 兼容事件使用特定路径格式存储：\n\n```\notel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json\n```\n\n这种层次化路径设计允许 S3 兼容存储和 ClickHouse 联合查询，实现边缘缓存和计算分离。\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n## Redis 缓存与队列\n\n### 队列架构\n\nLangfuse 使用 BullMQ（基于 Redis）实现异步任务处理：\n\n```mermaid\ngraph TB\n    subgraph 队列系统\n        A[OtelIngestionQueue] --> B[Ingestion Worker]\n        C[IngestionSecondaryQueue] --> D[Secondary Worker]\n        E[PromptCacheQueue] --> F[Cache Worker]\n    end\n    \n    subgraph 数据流\n        B --> G[(ClickHouse)]\n        D --> H[(PostgreSQL)]\n        F --> I[(Cache)]\n    end\n```\n\n主要队列类型：\n\n| 队列名称 | 用途 | 数据目标 |\n|----------|------|----------|\n| `OtelIngestionQueue` | OTEL 格式事件处理 | ClickHouse |\n| `IngestionSecondaryQueue` | 标准事件处理 | PostgreSQL + ClickHouse |\n| `PromptCacheQueue` | 提示词缓存更新 | Redis Cache |\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md]()\n\n### 缓存策略\n\n提示词模板使用 Redis 缓存加速访问：\n\n```typescript\ninterface PromptCacheEntry {\n  promptId: string;\n  content: string;\n  version: number;\n  expiresAt: number;\n}\n```\n\n缓存失效采用主动更新模式：当提示词更新时，通过队列触发缓存刷新，确保多实例部署的一致性。\n\n资料来源：[web/src/features/mcp/README.md]()\n\n## 数据流与同步\n\n### 事件摄取流程\n\n```mermaid\nsequenceDiagram\n    participant SDK\n    participant API as Ingestion API\n    participant Queue as BullMQ\n    participant Worker\n    participant CH as ClickHouse\n    participant PG as PostgreSQL\n\n    SDK->>API: POST /ingestion\n    API->>API: Validate & Transform\n    API->>Queue: Enqueue Event\n    API-->>SDK: 200 OK\n    \n    Queue->>Worker: Dequeue Job\n    Worker->>CH: Insert Event\n    Worker->>PG: Upsert Entity\n    Worker->>Worker: Index & Compute\n```\n\n事件摄取遵循写入放大模式：单次 API 调用触发多次数据写入，通过队列解耦确保响应延迟最小化。\n\n资料来源：[packages/shared/src/server/repositories]()\n\n### 批量处理与检查点\n\n摄取脚本支持断点续传机制：\n\n```typescript\ninterface BatchProgress {\n  totalRows: number;\n  processedRows: number;\n  queuedCount: number;\n  skippedCount: number;\n  errorCount: number;\n}\n```\n\n检查点文件保存当前处理位置，失败后可从上次成功位置恢复，保证大规模数据导入的可靠性。\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n## 查询优化\n\n### 索引策略\n\nPostgreSQL 表设计包含多层索引优化：\n\n```sql\n-- 复合索引支持项目级快速查询\nCREATE INDEX idx_traces_project_created \nON traces(project_id, created_at DESC);\n\n-- 文本搜索索引\nCREATE INDEX idx_traces_name_gin \nON traces USING gin(name gin_trgm_ops);\n\n-- 关系索引维护查询性能\nCREATE INDEX idx_observations_trace \nON observations(trace_id, start_time DESC);\n```\n\n### ClickHouse 查询模式\n\n分析查询使用物化视图聚合：\n\n```sql\nCREATE MATERIALIZED VIEW score_stats_mv\nENGINE = SummingMergeTree()\nORDER BY (project_id, score_name, period)\nAS SELECT\n    project_id,\n    score_name,\n    toDate(timestamp) as period,\n    count() as count,\n    avg(value) as avg_value,\n    quantile(0.5)(value) as p50\nFROM raw_events\nWHERE type = 'score'\nGROUP BY project_id, score_name, period;\n```\n\n资料来源：[packages/shared/src/tableDefinitions]()\n\n## 安全与隔离\n\n### 组织级数据隔离\n\n所有查询必须通过项目作用域验证：\n\n```typescript\ninterface AuthCheck {\n  validKey: boolean;\n  scope: {\n    projectId: string;\n    accessLevel: \"project\" | \"org\";\n  };\n}\n```\n\nAPI 密钥与项目绑定，跨项目访问通过组织成员关系控制。\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n### 敏感数据处理\n\n用户上传的 `metadata` 字段支持服务端过滤：\n\n```typescript\ninterface FilterConfig {\n  fieldPath: string;\n  action: \"REDACT\" | \"REMOVE\" | \"ALLOW\";\n}\n```\n\n配置化的数据过滤规则确保敏感信息不会出现在日志或分析结果中。\n\n## 总结\n\nLangfuse 的数据库设计体现了现代 SaaS 应用的多存储策略：\n- **PostgreSQL** 提供强一致性的关系数据存储\n- **ClickHouse** 处理高吞吐量分析工作负载\n- **Redis** 实现异步处理和高速缓存\n\n三层架构通过事件驱动模式松耦合，支持水平扩展同时保持数据完整性。Repository 模式封装数据访问逻辑，隐藏底层存储细节，便于未来架构演进。\n\n资料来源：[packages/shared/src/server/repositories]()\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n---\n\n<a id='p-tracing'></a>\n\n## 追踪系统\n\n### 相关页面\n\n相关主题：[数据库设计](#p-database)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/traces.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/traces.ts)\n- [packages/shared/src/domain/observations.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/observations.ts)\n- [packages/shared/src/server/ingestion](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/ingestion)\n- [packages/shared/src/server/otel](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/otel)\n- [packages/shared/src/server/repositories/traces.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories/traces.ts)\n- [packages/shared/src/server/repositories/observations.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories/observations.ts)\n</details>\n\n# 追踪系统\n\n## 概述\n\n追踪系统（Tracing System）是 Langfuse 的核心功能模块，负责收集、存储和展示 LLM 应用执行过程中的完整调用链路。该系统基于 OpenTelemetry 标准构建，支持多种观察类型，能够帮助开发者监控、分析和优化 AI 应用的行为。\n\n追踪系统的主要职责包括：\n\n- **链路追踪**：记录完整的请求调用链路，包括输入、输出和中间过程\n- **观察类型支持**：支持 SPAN（跨度）、GENERATION（生成）、EVENT（事件）等多种观察类型\n- **层级结构**：通过父子关系构建树形结构，展现调用嵌套关系\n- **元数据管理**：附加和解析丰富的上下文元数据\n- **评分集成**：与评分系统集成，支持评估执行效果的追踪\n\n资料来源：[packages/shared/src/domain/traces.ts]()\n\n---\n\n## 核心数据模型\n\n### Trace（追踪）\n\nTrace 是整个追踪系统的顶层容器，代表一次完整的请求或会话。每个 Trace 包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 追踪的唯一标识符 |\n| name | string | 追踪名称，用于快速识别 |\n| projectId | string | 所属项目 ID |\n| userId | string | 用户标识 |\n| sessionId | string | 会话标识 |\n| metadata | JSON | 附加的元数据 |\n| release | string | 发布版本 |\n| version | string | 追踪版本 |\n| tags | string[] | 标签数组 |\n| environment | string | 环境（default 等） |\n| bookmarked | boolean | 是否收藏 |\n| input | JSON | 输入数据 |\n| output | JSON | 输出数据 |\n| latency | number | 总延迟（秒） |\n| createdAt | DateTime | 创建时间 |\n\n资料来源：[packages/shared/src/domain/traces.ts:1-20]()\n\n### Observation（观察）\n\nObservation 是 Trace 的子节点，代表追踪中的一个具体操作或事件。支持四种类型：\n\n| 类型 | 说明 | 使用场景 |\n|------|------|----------|\n| TRACE | 追踪容器根节点 | 包装整个追踪结构 |\n| SPAN | 跨度 | 标记一段代码执行区间 |\n| GENERATION | 生成 | 记录 LLM 生成操作 |\n| EVENT | 事件 | 记录离散的时间点事件 |\n\n每个 Observation 包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 观察的唯一标识符 |\n| traceId | string | 所属追踪 ID |\n| parentObservationId | string | 父观察 ID（用于构建层级） |\n| type | ObservationType | 观察类型 |\n| name | string | 观察名称 |\n| startTime | DateTime | 开始时间 |\n| endTime | DateTime | 结束时间 |\n| metadata | JSON | 元数据 |\n| input | JSON | 输入内容 |\n| output | JSON | 输出内容 |\n| model | string | 使用的模型（如适用） |\n| modelParameters | JSON | 模型参数 |\n| usage | Usage | Token 使用量 |\n| level | string | 日志级别 |\n| statusMessage | string | 状态消息 |\n\n资料来源：[packages/shared/src/domain/observations.ts]()\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n    subgraph 客户端层\n        SDK[SDK / OpenTelemetry SDK]\n        MCP[MCP Server]\n    end\n\n    subgraph 摄取层\n        IngestionAPI[摄取 API]\n        OTELEndpoint[OTEL Endpoint]\n    end\n\n    subgraph 处理层\n        Validation[数据验证]\n        Transform[数据转换]\n        Queue[消息队列]\n    end\n\n    subgraph 存储层\n        PostgreSQL[(PostgreSQL)]\n        ClickHouse[(ClickHouse)]\n        Redis[(Redis)]\n    end\n\n    subgraph 查询层\n        TracesRepo[Traces Repository]\n        ObservationsRepo[Observations Repository]\n        ScoreRepo[Score Repository]\n    end\n\n    subgraph 展示层\n        TraceTree[追踪树构建]\n        JsonViewer[JSON 查看器]\n        Analytics[分析面板]\n    end\n\n    SDK --> IngestionAPI\n    MCP --> IngestionAPI\n    SDK --> OTELEndpoint\n\n    IngestionAPI --> Validation\n    OTELEndpoint --> Validation\n\n    Validation --> Transform\n    Transform --> Queue\n\n    Queue --> PostgreSQL\n    Queue --> ClickHouse\n\n    TracesRepo --> PostgreSQL\n    ObservationsRepo --> ClickHouse\n    ScoreRepo --> PostgreSQL\n\n    TraceTree --> ObservationsRepo\n    JsonViewer --> TracesRepo\n    Analytics --> ScoreRepo\n```\n\n### 数据流向\n\n```mermaid\ngraph LR\n    A[事件创建] --> B[事件摄取]\n    B --> C{验证}\n    C -->|通过| D[写入队列]\n    C -->|失败| E[错误日志]\n    D --> F[异步处理]\n    F --> G[ClickHouse]\n    F --> H[PostgreSQL]\n    G --> I[UI 展示]\n    H --> I\n```\n\n---\n\n## 摄取系统\n\n### 标准摄取流程\n\nLangfuse 支持两种事件摄取方式：标准摄取和 OpenTelemetry（OTEL）摄取。\n\n#### 标准摄取端点\n\n标准摄取使用以下格式的 S3 键路径：\n\n```\n{projectId}/{type}/{eventBodyId}/{eventId}.json\n```\n\n摄取请求体结构：\n\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\" }\n  },\n  \"data\": {\n    \"eventBodyId\": \"<eventBodyId>\",\n    \"fileKey\": \"<eventId>\",\n    \"type\": \"<type>-create\"\n  }\n}\n```\n\n事件经过验证后被加入 `IngestionSecondaryQueue` 队列处理。\n\n资料来源：[packages/shared/src/server/ingestion]()\n\n#### OTEL 摄取端点\n\nOTEL 格式使用更详细的路径结构，支持标准化的遥测数据格式：\n\n```\notel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json\n```\n\nOTEL 请求体结构：\n\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\", \"accessLevel\": \"project\" }\n  },\n  \"data\": {\n    \"fileKey\": \"otel/<projectId>/<yyyy>/<mm>/<dd>/<hh>/<mm>/<eventId>.json\"\n  }\n}\n```\n\nOTEL 事件被加入 `OtelIngestionQueue` 队列处理。\n\n资料来源：[packages/shared/src/server/otel]()\n\n### 验证与转换\n\n摄取流程包含严格的数据验证步骤：\n\n1. **身份验证检查**：验证 API Key 和项目权限\n2. **Schema 验证**：使用 Zod 进行类型验证\n3. **数据转换**：将原始事件转换为内部数据模型\n4. **队列分发**：根据事件类型分发到对应队列\n\n---\n\n## 存储层\n\n### 多存储架构\n\nLangfuse 采用混合存储策略，根据数据特性选择最优存储：\n\n| 数据类型 | 存储引擎 | 说明 |\n|----------|----------|------|\n| Trace 元数据 | PostgreSQL | 结构化查询，事务支持 |\n| Observation 数据 | ClickHouse | 时序数据，分析查询优化 |\n| 缓存数据 | Redis | 热点数据加速访问 |\n| 大型 JSON | S3 | 存储 input/output 等大字段 |\n\n### Traces 仓库\n\n`TracesRepository` 负责 Trace 的 CRUD 操作：\n\n- 创建新追踪记录\n- 更新追踪元数据\n- 查询追踪列表（支持分页、过滤、排序）\n- 获取单个追踪详情\n\n资料来源：[packages/shared/src/server/repositories/traces.ts]()\n\n### Observations 仓库\n\n`ObservationsRepository` 负责 Observation 的管理：\n\n- 创建观察记录\n- 更新观察数据\n- 构建树形结构查询\n- 批量查询追踪下的所有观察\n\n资料来源：[packages/shared/src/server/repositories/observations.ts]()\n\n---\n\n## UI 展示系统\n\n### 追踪树构建\n\n追踪数据在 UI 中以树形结构展示。核心构建逻辑位于 `buildTraceUiData` 函数：\n\n```typescript\n// 传统追踪：单一 TRACE 根节点 + 子观察节点\nconst result = buildTraceUiData(trace, observations);\n\n// 结果结构\n{\n  roots: [\n    {\n      id: \"trace-{traceId}\",\n      type: \"TRACE\",\n      name: \"{traceName}\",\n      children: [\n        { id: \"{obsId}\", type: \"SPAN|GENERATION|EVENT\", ... }\n      ]\n    }\n  ]\n}\n```\n\n树构建使用**显式栈迭代**而非递归，以避免深度嵌套导致的栈溢出问题：\n\n```typescript\n// ❌ 递归方式（深度 1000+ 可能栈溢出）\nfunction traverse(node: TreeNode) {\n  process(node);\n  node.children.forEach((child) => traverse(child));\n}\n\n// ✅ 迭代方式（安全处理任意深度）\nfunction traverse(rootNode: TreeNode) {\n  const stack = [rootNode];\n  while (stack.length > 0) {\n    const node = stack.pop()!;\n    process(node);\n    node.children.forEach((child) => stack.push(child));\n  }\n}\n```\n\n资料来源：[web/src/components/trace/lib/tree-building.clienttest.ts]()\n\n### 追踪页面组件\n\n追踪详情页面使用 `Page` 组件包装，确保一致的布局体验：\n\n```tsx\n<Page\n  title=\"{traceName}: {traceId}\"\n  scrollable\n  headerProps={{\n    breadcrumb: [\n      { name: \"Traces\", href: \"/traces\" },\n      { name: \"{traceName}\" }\n    ]\n  }}\n>\n  <TraceDetail />\n</Page>\n```\n\n### JSON 查看器\n\n追踪详情使用 `AdvancedJsonViewer` 组件展示，支持：\n\n- 树形结构展开/折叠\n- 关键字搜索（客户端内存搜索）\n- 虚拟化渲染（支持大数据集）\n- 自定义主题\n\n---\n\n## 元数据系统\n\n### 元数据解析\n\n追踪系统支持从元数据中提取特定字段：\n\n```typescript\nexport const resolveEvalExecutionMetadata = (\n  parsedMetadata: unknown\n): string | null => {\n  try {\n    if (typeof parsedMetadata !== \"object\" || parsedMetadata === null)\n      return null;\n    return (parsedMetadata as Record<string, unknown>)[\n      \"target_trace_id\"\n    ] as string;\n  } catch {\n    return null;\n  }\n};\n```\n\n此函数用于关联评估执行与目标追踪，实现评估结果的溯源。\n\n资料来源：[web/src/components/trace/lib/resolve-metadata.ts]()\n\n### 过滤器与查询编码\n\n追踪支持丰富的过滤条件，使用 URL 编码存储：\n\n```typescript\n// 支持的过滤类型\nconst filterTypes = {\n  datetime: Date,        // 日期时间过滤\n  number: Number,         // 数值过滤\n  numberObject: Number,  // 对象内数值过滤\n  stringOptions: string[],  // 字符串选项\n  arrayOptions: string[],   // 数组选项\n  categoryOptions: string[], // 分类选项\n  boolean: boolean        // 布尔过滤\n};\n```\n\n资料来源：[web/src/features/filters/lib/filter-query-encoding.ts]()\n\n---\n\n## 评分集成\n\n### 评分接口\n\n追踪系统与评分系统深度集成，支持在追踪级别附加评分：\n\n| API 版本 | GET 要求 | 新增字段 |\n|----------|----------|----------|\n| V1 | 必须提供 `traceId` | 仅支持追踪级评分 |\n| V2 | `traceId` 可选 | 支持 `sessionId` |\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md]()\n\n### 评分解析\n\n评分分析模块提供统计计算和可视化：\n\n```typescript\n// 评分一致性解读\nfunction interpretAgreement(agreement: number): InterpretationResult {\n  if (agreement >= 0.9) {\n    return { strength: \"Excellent\", color: \"green\" };\n  }\n  if (agreement >= 0.8) {\n    return { strength: \"Good\", color: \"blue\" };\n  }\n  // ...\n}\n\n// MAE 解读（支持相对误差计算）\nfunction interpretMAE(\n  mae: number | null,\n  scale?: { min: number; max: number }\n): InterpretationResult\n```\n\n资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts]()\n\n---\n\n## 开发工具\n\n### 追踪回放脚本\n\n`replayIngestionEventsV2` 脚本支持从 CSV 文件回放摄取事件：\n\n```bash\npnpm run --filter=worker replay-ingestion-events-v2 \\\n  --input=events.csv \\\n  --url=http://localhost:3000 \\\n  --rate-limit=100\n```\n\n特性：\n\n- **断点续传**：自动保存检查点，失败后可恢复\n- **速率限制**：客户端与服务端双重限流\n- **重试机制**：临时错误自动重试（最多 3 次）\n- **错误日志**：失败事件记录到 `errors.csv`\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n### 队列填充脚本\n\n`refillQueueEvent` 脚本用于本地回填队列：\n\n```bash\n# 1. 创建事件文件 worker/events.jsonl\n{\"projectId\": \"project-123\", \"orgId\": \"org-456\"}\n\n# 2. 配置环境变量\nREDIS_CONNECTION_STRING=redis://:secret@127.0.0.1:6379\n\n# 3. 运行脚本\npnpm run --filter=worker refill-queue-event\n```\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md]()\n\n---\n\n## 最佳实践\n\n### 追踪命名规范\n\n追踪名称建议遵循格式：`{操作}: {唯一标识}`，例如：\n\n- `chat-completion: msg-abc123`\n- `agent-execution: run-xyz789`\n\n### 嵌套层级控制\n\n为保证 UI 性能和可读性：\n\n- 建议单个追踪的观察节点不超过 1000 个\n- 深度嵌套建议拆分为多个子追踪\n- 使用 EVENT 类型记录关键时间点，而非创建大量小 SPAN\n\n### 元数据组织\n\n元数据应包含：\n\n- **上下文信息**：请求来源、用户特征\n- **性能指标**：各阶段耗时、Token 使用量\n- **调试信息**：内部标识符、版本号\n\n---\n\n## 相关文档\n\n| 模块 | 路径 | 说明 |\n|------|------|------|\n| 领域模型 | `packages/shared/src/domain/` | Trace 和 Observation 的核心定义 |\n| 摄取服务 | `packages/shared/src/server/ingestion/` | 数据摄取 API |\n| OTEL 支持 | `packages/shared/src/server/otel/` | OpenTelemetry 集成 |\n| 仓库层 | `packages/shared/src/server/repositories/` | 数据库操作封装 |\n| UI 组件 | `web/src/components/trace/` | 追踪展示组件 |\n| 评分系统 | `web/src/features/score-analytics/` | 评分分析与可视化 |\n\n---\n\n<a id='p-prompts'></a>\n\n## 提示词管理\n\n### 相关页面\n\n相关主题：[数据库设计](#p-database)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/prompts.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/prompts.ts)\n- [packages/shared/src/features/prompts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/prompts)\n- [packages/shared/src/server/services/PromptService](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/services/PromptService)\n- [web/src/features/prompts](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)\n- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n- [packages/shared/src/tableDefinitions/promptsTable.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions/promptsTable.ts)\n</details>\n\n# 提示词管理\n\n提示词管理（Prompt Management）是 Langfuse 平台的核心功能之一，它提供了对提示词（Prompts）的创建、版本控制、组合、缓存和分发的完整生命周期管理。通过 Langfuse 的提示词管理系统，用户可以集中管理所有项目的提示词，支持版本标签、依赖引用、API 调用以及 MCP（Model Context Protocol）集成。\n\n## 核心概念\n\n### 提示词实体\n\nLangfuse 中的提示词是一个包含名称、版本、内容和元数据的实体。每个提示词具有以下核心属性：\n\n| 属性 | 说明 |\n|------|------|\n| `name` | 提示词的唯一标识名称 |\n| `version` | 自动递增的版本号 |\n| `type` | 提示词类型（text 或 chat） |\n| `config` | 提示词配置（温度、最大 token 等） |\n| `labels` | 版本标签数组（如 production、development） |\n| `prompt` | 提示词内容或消息数组 |\n| `createdAt` | 创建时间戳 |\n\n资料来源：[packages/shared/src/domain/prompts.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/prompts.ts)\n\n### 提示词类型\n\nLangfuse 支持两种提示词类型：\n\n**文本提示词（Text Prompt）**\n- 用于简单的文本补全任务\n- `prompt` 字段存储纯文本内容\n\n**聊天提示词（Chat Prompt）**\n- 用于 OpenAI 风格的聊天接口\n- `prompt` 字段存储消息数组，每条消息包含 `role` 和 `content`\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n## 系统架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n    subgraph 客户端层\n        MCP[ MCP Server ]\n        API[ REST API ]\n        WebUI[ Web 前端 ]\n    end\n    \n    subgraph 服务层\n        PromptService[ PromptService ]\n        PromptCache[ Redis Cache ]\n        PromptDB[( PostgreSQL )]\n    end\n    \n    MCP -->|getPrompt/createPrompt| PromptService\n    API -->|CRUD 操作| PromptService\n    WebUI -->|管理界面| PromptService\n    \n    PromptService -->|缓存读写| PromptCache\n    PromptService -->|持久化| PromptDB\n```\n\n### 数据存储\n\nLangfuse 使用 PostgreSQL 作为提示词的持久化存储，并通过 Redis 实现缓存层以提升读取性能。\n\n```mermaid\ngraph LR\n    A[读请求] --> B{检查 Redis}\n    B -->|缓存命中| C[返回缓存数据]\n    B -->|缓存未命中| D[查询 PostgreSQL]\n    D --> E[写入 Redis]\n    E --> C\n```\n\n资料来源：[web/src/features/prompts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)\n\n## 缓存策略\n\n### 缓存结构\n\n提示词的缓存使用 Redis 管理，缓存键格式如下：\n\n```\nprompt:<project-id>:<prompt-name>:<prompt-version ?? label>\n```\n\n这意味着：\n- 同一提示词名称可能对应多个缓存键\n- 具有多个标签的提示词会在缓存中多次出现\n\n### 缓存操作流程\n\n```mermaid\nsequenceDiagram\n    participant Client as 客户端\n    participant Cache as Redis Cache\n    participant Lock as Redis Lock\n    participant DB as PostgreSQL\n\n    Client->>Cache: 读取提示词\n    Cache->>Cache: 检查缓存键\n    alt 缓存命中\n        Cache-->>Client: 返回缓存数据\n        Cache->>Cache: 重置 TTL\n    else 缓存未命中 或 锁存在\n        Cache-->>DB: 查询数据库\n        DB-->>Cache: 返回提示词数据\n        Cache-->>Client: 返回数据并缓存\n    end\n\n    Note over Lock,DB: 更新提示词时\n    Lock->>Lock: 获取分布式锁\n    Lock->>Cache: 清除所有相关缓存键\n    Lock->>DB: 执行数据库更新\n    Lock->>Lock: 释放锁\n```\n\n### 关键设计原则\n\n1. **从不更新缓存**：当提示词更新时，系统会删除所有相关的缓存条目，而不是修改它们\n2. **分布式锁保护**：使用 Redis 锁确保并发更新的安全性\n3. **操作顺序**：先获取锁 → 失效缓存 → 执行数据库操作 → 释放锁\n\n资料来源：[web/src/features/prompts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)\n\n## MCP 集成\n\nLangfuse 提供了 MCP（Model Context Protocol）服务器集成，允许外部工具和客户端程序访问提示词管理功能。\n\n### MCP 工具列表\n\n| 工具名称 | 功能 | 类型 |\n|----------|------|------|\n| `getPrompt` | 获取完全解析的提示词（包含依赖） | 只读 |\n| `getPromptUnresolved` | 获取原始提示词（保留依赖标签） | 只读 |\n| `listPrompts` | 列出所有提示词（支持过滤和分页） | 只读 |\n| `createTextPrompt` | 创建新的文本提示词版本 | 写入 |\n| `createChatPrompt` | 创建新的聊天提示词版本 | 写入 |\n| `updatePromptLabels` | 更新提示词标签 | 写入 |\n\n### 提示词解析模式\n\nMCP 服务提供两种提示词获取模式：\n\n**完全解析模式（getPrompt）**\n- 用于获取可直接发送给 LLM 的最终提示词\n- 递归解析所有依赖标签\n- 返回包含完整内容的提示词\n\n**原始模式（getPromptUnresolved）**\n- 用于分析提示词组合结构\n- 保留 `@@@langfusePrompt:name=xxx|label=yyy@@@` 依赖标签\n- 有助于调试和理解提示词依赖关系\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n## 提示词组合\n\n### 依赖标签语法\n\nLangfuse 支持提示词组合功能，允许一个提示词引用其他提示词。依赖标签语法如下：\n\n```\n@@@langfusePrompt:name=<prompt-name>|label=<label-name>@@@\n```\n\n### 组合示例\n\n```\n输入: \"You are helpful. @@@langfusePrompt:name=base-rules|label=production@@@\"\n输出: \"You are helpful. Always be kind and respectful.\"\n```\n\n### 使用场景\n\n- **提示词堆叠**：将基础规则与具体任务提示词组合\n- **依赖链分析**：使用 `getPromptUnresolved` 调试依赖关系\n- **构建工具**：开发管理提示词组合的自动化工具\n\n```mermaid\ngraph TD\n    A[主提示词] -->|依赖| B[基础规则提示词]\n    A -->|依赖| C[角色定义提示词]\n    B -->|依赖| D[通用指令提示词]\n    \n    style A fill:#e1f5fe\n    style B fill:#fff3e0\n    style C fill:#fff3e0\n    style D fill:#f3e5f5\n```\n\n## API 接口\n\n### 创建提示词\n\n**文本提示词**\n\n```typescript\ncreateTextPrompt(params: {\n  projectId: string;\n  promptName: string;\n  prompt: string;\n  config?: PromptConfig;\n  labels?: string[];\n})\n```\n\n**聊天提示词**\n\n```typescript\ncreateChatPrompt(params: {\n  projectId: string;\n  promptName: string;\n  messages: ChatMessage[];\n  config?: PromptConfig;\n  labels?: string[];\n})\n```\n\n### 查询提示词\n\n```typescript\nlistPrompts(params: {\n  projectId: string;\n  name?: string;      // 可选：按名称过滤\n  label?: string;     // 可选：按标签过滤\n  tag?: string;       // 可选：按标签过滤\n  updatedAtStart?: Date;\n  updatedAtEnd?: Date;\n  page?: number;\n  limit?: number;\n})\n```\n\n## 版本控制与标签\n\n### 版本管理\n\n每个提示词版本具有自动递增的版本号。创建新版本时：\n\n1. 版本号自动加一\n2. 可选择性地添加标签（如 `production`、`dev`）\n3. 版本记录创建时间戳\n\n### 标签系统\n\n标签用于标识提示词的用途或环境：\n\n| 标签示例 | 用途 |\n|----------|------|\n| `production` | 生产环境使用的版本 |\n| `staging` | 测试环境使用的版本 |\n| `experiment` | 实验性版本 |\n| `archived` | 已归档的旧版本 |\n\n### 标签更新操作\n\n`updatePromptLabels` 工具允许：\n- 添加新标签到现有版本\n- 将标签从一个版本移动到另一个版本\n- 删除不需要的标签\n\n## 数据库模型\n\n提示词表结构定义：\n\n```typescript\ninterface PromptTable {\n  id: string;              // UUID 主键\n  project_id: string;      // 项目 ID\n  name: string;           // 提示词名称\n  version: number;         // 版本号\n  type: \"text\" | \"chat\";   // 提示词类型\n  prompt: string;          // 提示词内容\n  config: object;          // 配置（JSON）\n  labels: string[];        // 标签数组\n  created_at: Date;        // 创建时间\n  updated_at: Date;        // 更新时间\n}\n```\n\n资料来源：[packages/shared/src/tableDefinitions/promptsTable.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions/promptsTable.ts)\n\n## 审计日志\n\n所有写入操作（创建、更新标签）会自动创建审计日志条目，包含：\n\n- 操作前状态快照\n- 操作后状态快照\n- 操作时间戳\n- 操作者信息\n\n## 安全与权限\n\n### 访问控制\n\nMCP 集成使用 BasicAuth 认证：\n\n```bash\n# 生成 Basic Auth Token\necho -n \"pk-lf-your-public-key:sk-lf-your-secret-key\" | base64\n```\n\n### 权限级别\n\n| 权限级别 | 说明 |\n|----------|------|\n| `project` | 项目级访问权限 |\n| `org` | 组织级访问权限 |\n| `admin` | 管理员权限 |\n\n### 工具注解\n\nMCP 工具包含安全提示注解：\n\n- `readOnly: true`：安全操作，无需确认（如 `getPrompt`、`listPrompts`）\n- `destructive: true`：修改数据的操作（如 `createTextPrompt`、`createChatPrompt`）\n\n客户端程序可以根据这些注解自动批准只读操作，或在执行破坏性操作时要求用户确认。\n\n## 最佳实践\n\n### 命名规范\n\n- 使用描述性名称：`customer-support-greeting` 而非 `prompt-1`\n- 统一命名风格：建议使用 kebab-case 或 camelCase\n- 包含版本或环境信息：`prompt-name:production`\n\n### 标签使用策略\n\n1. 生产环境使用 `production` 标签\n2. 开发和测试使用 `dev` 或 `staging` 标签\n3. 避免在标签中包含敏感信息\n4. 定期清理不再使用的标签\n\n### 缓存优化\n\n1. 避免频繁更新提示词，以减少缓存失效开销\n2. 使用标签而非版本号来引用提示词（标签更稳定）\n3. 监控缓存命中率，及时调整缓存策略\n\n## 总结\n\nLangfuse 的提示词管理系统提供了企业级的提示词管理能力，包括：\n\n- **版本控制**：自动版本管理和标签系统\n- **组合能力**：支持提示词依赖和复用\n- **高性能**：Redis 缓存和锁机制确保并发安全\n- **标准化接口**：REST API 和 MCP 集成支持多种客户端\n- **审计追踪**：完整的操作日志记录\n\n---\n\n<a id='p-evaluations'></a>\n\n## 评估系统\n\n### 相关页面\n\n相关主题：[数据集管理](#p-datasets), [追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/score-configs.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/score-configs.ts)\n- [packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n- [web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n- [web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)\n</details>\n\n# 评估系统\n\n## 概述\n\nLangfuse 的评估系统（Evaluation System）是用于衡量和分析 LLM 应用输出的核心模块。该系统提供了一套完整的评分（Score）管理机制，包括评分的定义、存储、分析和可视化功能。评估系统帮助开发者量化 LLM 生成内容的质量，支持自定义评分规则，并通过统计分析提供对模型性能的洞察。\n\nLangfuse 采用双轨 API 设计，支持 v1（遗留版本，仅支持 trace 级别评分）和 v2（当前版本，支持 trace、session 和数据集运行级别的评分）。资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 核心数据模型\n\n### 评分（Score）\n\n评分是评估系统的基本单元，用于记录对 trace、session 或数据集运行项的评估结果。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 评分唯一标识符 |\n| `name` | string | 评分名称（如 \"accuracy\", \"relevance\"） |\n| `value` | number \\| string \\| boolean | 评分的实际值 |\n| `dataType` | \"NUMERIC\" \\| \"CATEGORICAL\" \\| \"BOOLEAN\" | 数据类型 |\n| `traceId` | string | 关联的 trace ID（v1 API 必需） |\n| `sessionId` | string | 关联的 session ID（v2 API 支持） |\n| `observationId` | string | 关联的 observation ID |\n| `source` | \"API\" \\| \"APP\" \\| \"EVALUATION\" \\| \"LLM\" | 评分来源 |\n| `comment` | string | 可选的评分备注 |\n| `metadata` | object | 附加元数据 |\n| `createdAt` | DateTime | 创建时间 |\n| `updatedAt` | DateTime | 更新时间 |\n\n资料来源：[packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)\n\n### 评分配置（ScoreConfig）\n\n评分配置定义了项目中的评分规则和元数据，确保评分的一致性和可解释性。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 配置唯一标识符 |\n| `projectId` | string | 所属项目 ID |\n| `name` | string | 评分名称（项目内唯一） |\n| `dataType` | \"NUMERIC\" \\| \"CATEGORICAL\" \\| \"BOOLEAN\" | 期望的数据类型 |\n| `categories` | string[] | 枚举值列表（categorical 类型必需） |\n| `description` | string | 评分说明文档 |\n| `valueRange` | { min?, max? } | 数值范围约束（numeric 类型） |\n| `createdAt` | DateTime | 创建时间 |\n| `updatedAt` | DateTime | 更新时间 |\n\n资料来源：[packages/shared/src/domain/score-configs.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/score-configs.ts)\n\n---\n\n## 系统架构\n\n```mermaid\ngraph TD\n    subgraph 前端层\n        A[Web UI] --> B[Score Analytics 组件]\n        A --> C[评分配置管理]\n    end\n    \n    subgraph API 层\n        D[v1 API] --> E[Scores Endpoints]\n        F[v2 API] --> E\n        E --> G[Score Router]\n    end\n    \n    subgraph 服务层\n        G --> H[Score Service]\n        G --> I[Score Analytics Service]\n    end\n    \n    subgraph 数据层\n        H --> J[(PostgreSQL)]\n        I --> K[(ClickHouse)]\n    end\n    \n    subgraph Worker 层\n        L[Evaluation Worker] --> M[评分计算任务]\n        M --> I\n    end\n```\n\n---\n\n## 评分类型\n\nLangfuse 支持三种评分数据类型，适用于不同的评估场景：\n\n### 数值型（NUMERIC）\n\n用于连续数值的评分，如准确率得分（0-1）、延迟（毫秒）、成本（美元）等。\n\n```typescript\n{\n  name: \"accuracy\",\n  value: 0.95,\n  dataType: \"NUMERIC\",\n  dataType: {\n    min: 0,\n    max: 1\n  }\n}\n```\n\n### 类别型（CATEGORICAL）\n\n用于离散的分类标签，如评级（A/B/C）、质量等级（优秀/良好/一般）等。\n\n```typescript\n{\n  name: \"quality\",\n  value: \"excellent\",\n  dataType: \"CATEGORICAL\",\n  categories: [\"excellent\", \"good\", \"fair\", \"poor\"]\n}\n```\n\n### 布尔型（BOOLEAN）\n\n用于二元判断，如是否通过、是否合规、是否有毒等。\n\n```typescript\n{\n  name: \"is_valid\",\n  value: true,\n  dataType: \"BOOLEAN\"\n}\n```\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 评分来源\n\n| 来源标识 | 说明 | 典型使用场景 |\n|----------|------|-------------|\n| `API` | 通过 API 直接提交 | 外部评估系统集成 |\n| `APP` | 通过 Langfuse UI 手动创建 | 人工审核评分 |\n| `EVALUATION` | 通过评估任务自动生成 | 自动化测试套件 |\n| `LLM` | 由 LLM 作为评判者生成 | LLM-as-Judge 评估 |\n\n资料来源：[packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)\n\n---\n\n## 评分分析功能\n\n### Score Analytics Provider\n\n`ScoreAnalyticsProvider` 是前端核心组件，用于包装评分分析数据并向子组件提供上下文。\n\n```tsx\n<ScoreAnalyticsProvider\n  projectId=\"proj_xxx\"\n  score1={{\n    id: \"score_1\",\n    name: \"accuracy\",\n    source: \"API\",\n    dataType: \"NUMERIC\"\n  }}\n  score2={{ /* 可选：第二个评分用于对比 */ }}\n  objectType=\"TRACE\"\n  startDate={new Date(\"2024-01-01\")}\n  endDate={new Date(\"2024-12-31\")}\n  interval={{ count: 1, unit: \"day\" }}\n>\n  <ScoreAnalyticsDashboard />\n</ScoreAnalyticsProvider>\n```\n\n### Hooks 层\n\n| Hook | 职责 |\n|------|------|\n| `useScoreAnalyticsQuery` | 从 API 获取数据并执行一次转换 |\n| `useScoreAnalytics` | 从 Provider 上下文获取分析数据 |\n\n资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n\n### 数据转换管道\n\n评分数据从 API 返回后需经过多层转换处理：\n\n```mermaid\ngraph LR\n    A[API Raw Data] --> B[Extract Categories]\n    B --> C[Fill Distribution Bins]\n    C --> D[Generate Bin Labels]\n    D --> E[Transform Heatmap]\n    E --> F[Calculate Mode Metrics]\n    F --> G[Fill Time Series Gaps]\n    G --> H[Namespace Categorical]\n    H --> I[ScoreAnalyticsData]\n```\n\n所有转换逻辑均位于 `useScoreAnalyticsQuery` Hook 中，使用 `useMemo` 进行记忆化，确保数据仅转换一次。\n\n资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n\n---\n\n## 统计分析工具\n\n### 一致性解释（interpretAgreement）\n\n用于评估两个评分之间的一致性程度：\n\n| 一致性范围 | 强度等级 | 颜色标识 |\n|-----------|----------|----------|\n| ≥ 0.9 | Excellent | green |\n| ≥ 0.8 | Good | blue |\n| ≥ 0.6 | Fair | yellow |\n| ≥ 0.4 | Poor | orange |\n| < 0.4 | Very Poor | red |\n\n```typescript\nexport function interpretAgreement(\n  agreement: number | null\n): InterpretationResult {\n  if (agreement >= 0.9) {\n    return {\n      strength: \"Excellent\",\n      color: \"green\",\n      description: `${percentage}% of predictions match`,\n    };\n  }\n  // ... 其他阈值\n}\n```\n\n资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)\n\n### MAE 解释（interpretMAE）\n\nMean Absolute Error 的上下文相关解释：\n\n```typescript\nexport function interpretMAE(\n  mae: number | null,\n  scale?: { min: number; max: number }\n): InterpretationResult\n```\n\n当提供 `scale` 参数时，系统会计算相对误差以提供更有意义的解释。\n\n资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)\n\n---\n\n## API 版本差异\n\n| 特性 | v1 API | v2 API |\n|------|--------|--------|\n| `traceId` | **必需** | 可选 |\n| `sessionId` | 不支持 | 支持 |\n| 适用范围 | 仅 trace 级别评分 | trace、session、数据集运行 |\n| 生命周期 | 遗留版本 | 当前推荐版本 |\n\n> **注意**：POST 和 DELETE API 在 v1 和 v2 中保持一致，继续支持所有评分类型。\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 文件结构\n\n```\npackages/shared/src/\n├── domain/\n│   ├── score-configs.ts      # 评分配置领域模型\n│   └── scores.ts             # 评分领域模型\n└── features/scores/\n    └── interfaces/           # 接口定义\n        ├── api/\n        │   ├── v1/           # 遗留 API 类型\n        │   ├── v2/           # 当前 API 类型\n        │   └── shared.ts     # 共享类型\n        ├── application/      # 应用层验证\n        ├── ingestion/        # 摄取层类型\n        └── ui/               # UI 简化类型\n\nweb/src/features/\n└── score-analytics/\n    ├── components/           # 评分分析组件\n    │   └── ScoreAnalyticsProvider.tsx\n    ├── hooks/\n    │   └── useScoreAnalyticsQuery.ts\n    ├── lib/\n    │   ├── analytics-url-state.ts\n    │   ├── clickhouse-time-utils.ts\n    │   ├── color-scales.ts\n    │   ├── heatmap-utils.ts\n    │   ├── score-formatter.ts\n    │   ├── scoreAnalyticsTransformers.ts\n    │   └── statistics-utils.ts\n    └── server/\n        └── scoreAnalyticsRouter.ts\n\nworker/src/features/\n└── evaluation/              # 评估任务执行\n```\n\n资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n\n---\n\n## 使用指南\n\n### 创建评分配置\n\n在项目中定义评分规则，确保数据一致性：\n\n```typescript\nconst scoreConfig = {\n  projectId: \"proj_xxx\",\n  name: \"relevance_score\",\n  dataType: \"NUMERIC\",\n  description: \"衡量生成内容与查询的相关程度\",\n  valueRange: { min: 0, max: 1 }\n};\n```\n\n### 使用评分分析组件\n\n```tsx\nimport { ScoreAnalyticsProvider } from \"@/features/score-analytics\";\nimport { ScoreAnalyticsDashboard } from \"./ScoreAnalyticsDashboard\";\n\nfunction ScoresPage({ projectId }) {\n  return (\n    <ScoreAnalyticsProvider\n      projectId={projectId}\n      score1={{ id: \"score_accuracy\", name: \"accuracy\", source: \"API\", dataType: \"NUMERIC\" }}\n      objectType=\"TRACE\"\n      startDate={startDate}\n      endDate={endDate}\n      interval={{ count: 1, unit: \"day\" }}\n    >\n      <ScoreAnalyticsDashboard />\n    </ScoreAnalyticsProvider>\n  );\n}\n```\n\n---\n\n## 性能注意事项\n\n| 优化项 | 说明 |\n|--------|------|\n| **单次转换** | 所有数据转换在 Hook 中执行一次，避免重复计算 |\n| **记忆化** | 所有转换函数使用 `useMemo` 进行依赖跟踪 |\n| **上下文隔离** | 数据和状态通过 React Context 传递，避免 prop drilling |\n| **ClickHouse 查询** | 大规模分析数据通过 ClickHouse 进行聚合计算 |\n\n---\n\n<a id='p-datasets'></a>\n\n## 数据集管理\n\n### 相关页面\n\n相关主题：[评估系统](#p-evaluations), [追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/dataset-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-items.ts)\n- [packages/shared/src/domain/dataset-run-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-run-items.ts)\n- [packages/shared/src/server/services/DatasetService](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/services/DatasetService)\n- [web/src/features/datasets](https://github.com/langfuse/langfuse/blob/main/web/src/features/datasets)\n- [worker/src/features/experiments](https://github.com/langfuse/langfuse/blob/main/worker/src/features/experiments)\n- [packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n</details>\n\n# 数据集管理\n\n## 概述\n\n数据集管理（Datasets）是 Langfuse 平台的核心功能之一，用于管理和组织用于评估和测试 LLM 应用的数据集合。数据集由多个数据项组成，每个数据项包含输入、期望输出以及其他元数据，支持在实验和评估流程中被引用和执行。\n\n数据集管理功能覆盖了从数据项的创建、编辑，到运行时与 trace 的关联，再到实验执行和结果评估的完整生命周期。\n\n## 核心数据模型\n\n### DatasetItem（数据集项）\n\n`DatasetItem` 是数据集的基本组成单元，代表数据集中的单个测试样本。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 数据项唯一标识符 |\n| `datasetId` | string | 所属数据集 ID |\n| `input` | JSON | 输入数据，支持任意结构 |\n| `expectedOutput` | JSON (可选) | 期望输出，用于评估 |\n| `metadata` | JSON (可选) | 附加元数据信息 |\n| `sourceTraceId` | string (可选) | 来源 trace ID |\n| `sourceObservationId` | string (可选) | 来源 observation ID |\n| `createdAt` | DateTime | 创建时间 |\n| `updatedAt` | DateTime | 更新时间 |\n\n资料来源：[packages/shared/src/domain/dataset-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-items.ts)\n\n### DatasetRunItem（数据集运行项）\n\n`DatasetRunItem` 记录数据集在特定实验运行中的执行结果，将数据集项与实际执行产生的 trace 关联起来。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 运行项唯一标识符 |\n| `datasetRunId` | string | 所属实验运行 ID |\n| `datasetItemId` | string | 关联的数据集项 ID |\n| `traceId` | string | 关联的执行 trace ID |\n| `observationId` | string (可选) | 关联的 observation ID |\n| `status` | enum | 执行状态：`success` / `error` / `skipped` |\n| `error` | string (可选) | 错误信息 |\n| `startTime` | DateTime | 开始时间 |\n| `endTime` | DateTime (可选) | 结束时间 |\n| `createdAt` | DateTime | 创建时间 |\n\n资料来源：[packages/shared/src/domain/dataset-run-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-run-items.ts)\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n    subgraph 前端层[\"前端层 (web/src/features/datasets)\"]\n        UI[数据集管理界面]\n        Hooks[React Hooks]\n    end\n\n    subgraph 服务层[\"服务层 (packages/shared)\"]\n        DS[DatasetService]\n        DRS[DatasetRunService]\n    end\n\n    subgraph 数据层[\"数据层\"]\n        PG[(PostgreSQL)]\n        CH[(ClickHouse)]\n    end\n\n    subgraph 实验执行层[\"实验执行层 (worker/src/features/experiments)\"]\n        Executor[实验执行器]\n        Evaluator[评估器]\n    end\n\n    UI --> Hooks\n    Hooks --> DS\n    DS --> DRS\n    DRS --> PG\n    DRS --> CH\n    Executor --> DRS\n    Executor --> Evaluator\n    Evaluator --> CH\n```\n\n### 服务层职责\n\n**DatasetService** 负责数据集的核心业务逻辑：\n\n- 创建和管理数据集\n- 数据集项的 CRUD 操作\n- 数据集与项目（Project）的关联管理\n\n**DatasetRunService** 负责实验运行的生命周期：\n\n- 管理实验运行的创建和状态\n- 关联数据集项与执行 trace\n- 记录执行结果和评估数据\n\n## 实验与评估\n\n### 实验系统概述\n\nLangfuse 的实验系统（Experiments）与数据集管理紧密集成，支持以下核心功能：\n\n1. **数据集选择**：从现有数据集中选择运行的数据项\n2. **变量注入**：将数据集项的输入注入到 prompt 模板中\n3. **批量执行**：对数据集中的所有项执行推理\n4. **结果收集**：收集执行产生的 trace 和 observation\n5. **评估计算**：基于预设的评分标准计算评估分数\n\n资料来源：[worker/src/features/experiments](https://github.com/langfuse/langfuse/blob/main/worker/src/features/experiments)\n\n### 实验运行流程\n\n```mermaid\ngraph LR\n    A[启动实验] --> B[加载数据集项]\n    B --> C{遍历数据项}\n    C -->|存在未处理项| D[注入变量到 Prompt]\n    D --> E[执行 LLM 调用]\n    E --> F[创建 Trace]\n    F --> G[记录 DatasetRunItem]\n    G --> H{评估分数}\n    H --> I[计算评分]\n    I --> C\n    C -->|处理完成| J[生成实验报告]\n```\n\n### 评估数据存储\n\n评估相关的分数数据存储在 ClickHouse 中，支持高效的查询和分析：\n\n- 实验运行的分数数据通过 `SeederOrchestrator` 批量插入\n- 支持环境（environment）过滤：`production`、`development`、`staging`\n- 支持按数据集和实验运行进行聚合查询\n\n资料来源：[packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)\n\n## API 接口\n\n### 评分接口版本\n\nLangfuse 为评分（Scores）功能提供了 v1 和 v2 两个 API 版本：\n\n| 特性 | v1 API | v2 API |\n|------|--------|--------|\n| traceId | 必需 | 可选 |\n| sessionId | 不支持 | 支持 |\n| 数据集运行评分 | 支持 | 支持 |\n| 适用对象 | 仅 trace 级别 | trace、session、数据集运行 |\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n### 核心 API 端点\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/api/v2/datasets` | POST | 创建数据集 |\n| `/api/v2/datasets/:id/items` | POST | 添加数据集项 |\n| `/api/v2/datasets/:id/items` | GET | 获取数据集项列表 |\n| `/api/v2/datasets/:id/run` | POST | 创建实验运行 |\n| `/api/v2/datasets/:id/run/:runId/results` | GET | 获取实验运行结果 |\n\n## 前端组件\n\n前端数据集管理功能位于 `web/src/features/datasets` 目录，提供以下核心功能：\n\n- 数据集列表展示和搜索\n- 数据集项的添加、编辑、删除\n- 实验运行的历史记录查看\n- 实验结果的可视化展示\n\n### 数据集列表页面\n\n数据集列表页面提供以下功能：\n\n- 按名称、环境过滤数据集\n- 查看数据集项数量\n- 快速操作入口（运行实验、导出数据）\n\n### 数据集详情页面\n\n数据集详情页面展示：\n\n- 数据集基本信息（名称、描述、创建时间）\n- 数据集项列表（支持分页）\n- 实验运行历史\n- 评估分数统计\n\n## 数据流转\n\n```mermaid\ngraph TD\n    subgraph 数据录入\n        UserInput[用户录入]\n        Import[批量导入]\n    end\n\n    subgraph 数据存储\n        PG[(PostgreSQL<br/>数据集元数据)]\n        CH[(ClickHouse<br/>运行时数据)]\n    end\n\n    subgraph 评估执行\n        Experiment[实验]\n        LLM[LLM 调用]\n    end\n\n    subgraph 结果分析\n        ScoreUI[分数展示]\n        TraceView[Trace 详情]\n    end\n\n    UserInput --> PG\n    Import --> PG\n    Experiment --> LLM\n    LLM --> PG\n    LLM --> CH\n    Experiment --> CH\n    CH --> ScoreUI\n    PG --> TraceView\n```\n\n## 环境与隔离\n\n### 多环境支持\n\n数据集支持环境隔离，确保不同环境（生产、开发、测试）的数据相互独立：\n\n- `production`：生产环境数据\n- `development`：开发环境数据\n- `staging`：预发布环境数据\n\n### 数据隔离策略\n\n| 环境 | 数据来源 | 访问权限 |\n|------|----------|----------|\n| production | 正式 LLM 调用 | 仅生产用户 |\n| development | 测试 LLM 调用 | 开发团队 |\n| staging | 预发布测试 | 测试团队 |\n\n资料来源：[packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)\n\n## 最佳实践\n\n### 数据集组织\n\n1. **按用途分类**：将用于不同目的的数据集分开管理\n2. **版本控制**：对重要数据集进行版本标记\n3. **元数据丰富**：为数据项添加充分的元数据，便于筛选和分析\n\n### 实验设计\n\n1. **小规模测试**：先在小数据集上验证实验逻辑\n2. **变量控制**：确保对比实验仅改变目标变量\n3. **结果复现**：记录实验参数，便于复现结果\n\n### 评估配置\n\n1. **选择合适的评分标准**：根据业务需求选择或自定义评分函数\n2. **设置合理的阈值**：避免过于宽松或严格的评估标准\n3. **定期校准**：随着 LLM 版本更新，重新校准评估标准\n\n## 相关模块\n\n| 模块 | 位置 | 说明 |\n|------|------|------|\n| 数据集服务 | `packages/shared/src/server/services/DatasetService` | 后端数据集业务逻辑 |\n| 数据集项领域模型 | `packages/shared/src/domain/dataset-items.ts` | 数据集项数据模型 |\n| 运行项领域模型 | `packages/shared/src/domain/dataset-run-items.ts` | 实验运行项数据模型 |\n| 前端功能 | `web/src/features/datasets` | 前端数据集管理界面 |\n| 实验执行 | `worker/src/features/experiments` | 实验执行引擎 |\n\n---\n\n<a id='p-queues'></a>\n\n## 队列系统\n\n### 相关页面\n\n相关主题：[系统架构](#p-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/server/redis/ingestionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/ingestionQueue.ts)\n- [packages/shared/src/server/redis/evalExecutionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/evalExecutionQueue.ts)\n- [packages/shared/src/server/redis/batchActionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/batchActionQueue.ts)\n- [packages/shared/src/server/queues.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/queues.ts)\n- [worker/src/queues](https://github.com/langfuse/langfuse/blob/main/worker/src/queues)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n</details>\n\n# 队列系统\n\n## 概述\n\nLangfuse 的队列系统是基于 Redis 和 BullMQ 构建的消息队列基础设施，负责处理异步任务、事件摄取、评估执行和批量操作。该系统采用生产者和消费者模式，通过队列解耦服务间的通信，提高系统的可扩展性和可靠性。\n\n队列系统在 Langfuse 架构中扮演核心角色，主要承担以下职责：\n\n- **事件摄取**：处理来自 SDK 和 OTEL 协议的事件数据\n- **评估执行**：管理评估任务的异步执行\n- **批量操作**：处理需要批量处理的后台任务\n- **事件重放**：支持从 S3 重新导入历史事件\n\n## 架构设计\n\nLangfuse 采用多队列架构，不同类型的任务使用独立的队列，每个队列由专门的消费者处理器处理。\n\n```mermaid\ngraph TD\n    subgraph \"生产者\"\n        SDK[Langfuse SDK]\n        OTEL[OTEL Protocol]\n        API[API Server]\n    end\n\n    subgraph \"队列层\"\n        IQ[IngestionQueue<br/>摄取队列]\n        OIQ[OtelIngestionQueue<br/>OTEL摄取队列]\n        ISQ[IngestionSecondaryQueue<br/>摄取次级队列]\n        EEQ[EvalExecutionQueue<br/>评估执行队列]\n        BAQ[BatchActionQueue<br/>批量操作队列]\n    end\n\n    subgraph \"消费者\"\n        Worker[Worker Service]\n    end\n\n    SDK --> IQ\n    OTEL --> OIQ\n    API --> EEQ\n    API --> BAQ\n    \n    IQ --> Worker\n    OIQ --> Worker\n    ISQ --> Worker\n    EEQ --> Worker\n    BAQ --> Worker\n\n    Worker --> Redis[(Redis)]\n```\n\n## 队列类型\n\n### 摄取队列 (IngestionQueue)\n\n摄取队列是 Langfuse 最核心的队列，负责处理来自客户端 SDK 的事件数据。事件类型包括 traces、generations、scores、evals 等。\n\n| 属性 | 说明 |\n|------|------|\n| 队列名称 | `ingestion` |\n| 优先级 | 高 |\n| 并发处理 | 支持多worker并发消费 |\n| 重试机制 | 支持指数退避重试 |\n| 数据存储 | Redis |\n\n**事件格式示例**：\n\n```json\n{\n  \"projectId\": \"project-123\",\n  \"orgId\": \"org-456\",\n  \"eventType\": \"trace-create\",\n  \"body\": { /* 事件数据 */ }\n}\n```\n\n资料来源：[packages/shared/src/server/redis/ingestionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/ingestionQueue.ts)\n\n### OTEL 摄取队列 (OtelIngestionQueue)\n\n专门处理 OpenTelemetry 协议格式的事件，采用特定的文件存储路径格式。\n\n**S3 文件路径格式**：\n\n```\notel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json\n```\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n### 摄取次级队列 (IngestionSecondaryQueue)\n\n作为摄取队列的补充队列，用于处理需要二次处理的事件或分流部分摄取负载。\n\n### 评估执行队列 (EvalExecutionQueue)\n\n负责调度和管理评估任务的执行。当用户触发评估操作时，评估任务被加入此队列，由专门的评估工作器异步处理。\n\n| 属性 | 说明 |\n|------|------|\n| 队列名称 | `eval-execution` |\n| 优先级 | 中 |\n| 任务类型 | 异步评估计算 |\n| 超时处理 | 支持任务超时配置 |\n\n资料来源：[packages/shared/src/server/redis/evalExecutionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/evalExecutionQueue.ts)\n\n### 批量操作队列 (BatchActionQueue)\n\n处理需要批量执行的系统操作，如批量更新、批量删除等后台任务。\n\n| 属性 | 说明 |\n|------|------|\n| 队列名称 | `batch-action` |\n| 优先级 | 低 |\n| 批处理大小 | 可配置 |\n| 事务支持 | 支持批量事务 |\n\n资料来源：[packages/shared/src/server/redis/batchActionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/batchActionQueue.ts)\n\n## 队列配置\n\nLangfuse 在中央配置文件 `queues.ts` 中定义所有队列的默认配置和行为。\n\n```typescript\n// packages/shared/src/server/queues.ts 中的典型配置结构\ninterface QueueConfig {\n  name: string;\n  concurrency: number;\n  maxRetries: number;\n  backoff: {\n    type: 'exponential' | 'fixed';\n    delay: number;\n  };\n  removeOnComplete: boolean | number;\n  removeOnFail: boolean | number;\n}\n```\n\n资料来源：[packages/shared/src/server/queues.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/queues.ts)\n\n## 消费者与工作器\n\n### Worker 服务架构\n\nWorker 服务运行在独立的进程中，通过 Redis 连接队列并消费消息。每个队列类型对应专门的处理逻辑。\n\n```mermaid\ngraph LR\n    subgraph \"Worker 进程\"\n        subgraph \"处理器\"\n            IQH[IngestionHandler]\n            OIQH[OtelHandler]\n            EEQH[EvalHandler]\n            BAH[BatchHandler]\n        end\n        \n        subgraph \"队列连接\"\n            R[Redis BullMQ]\n        end\n    end\n\n    IQH --> R\n    OIQH --> R\n    EEQH --> R\n    BAH --> R\n```\n\n### 处理器职责\n\n| 处理器 | 队列 | 主要功能 |\n|--------|------|----------|\n| IngestionHandler | IngestionQueue | 解析事件、存储ClickHouse、触发后续处理 |\n| OtelHandler | OtelIngestionQueue | 处理OTEL格式事件、文件下载与解析 |\n| EvalHandler | EvalExecutionQueue | 执行评估计算、存储评估结果 |\n| BatchHandler | BatchActionQueue | 执行批量数据库操作 |\n\n资料来源：[worker/src/queues](https://github.com/langfuse/langfuse/blob/main/worker/src/queues)\n\n## 事件重放系统\n\nLangfuse 提供了事件重放脚本，允许从 S3 重新导入历史事件到队列系统。\n\n### replayIngestionEventsV2\n\n最新版本的事件重放工具，提供完整的事件重放功能。\n\n**主要特性**：\n\n- 支持从 S3 读取历史事件\n- 支持增量重放和断点续传\n- 内置速率限制和重试机制\n- 支持批量并发请求\n\n**命令行参数**：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--input` | - | CSV文件路径 |\n| `--batch-size` | 500 | 每次API请求的key数量 |\n| `--concurrency` | 4 | 最大并发API请求数 |\n| `--rate-limit` | 50 | 每秒最大请求数 |\n| `--dry-run` | false | 仅解析验证，不发送请求 |\n| `--resume` | false | 从上次断点继续 |\n\n**环境变量**：\n\n| 变量 | 说明 |\n|------|------|\n| `LANGFUSE_HOST` | 目标Langfuse实例URL |\n| `ADMIN_API_KEY` | 管理员API认证密钥 |\n\n**进度追踪与错误处理**：\n\n- **进度日志**：每批次处理后记录进度（如 `[1200/45000] 2.7% — 498 queued, 2 skipped`）\n- **检查点**：每批成功处理后写入检查点文件到CSV同目录，使用 `--resume` 可从断点继续\n- **速率限制**：尊重本地 `--rate-limit` 配置，对429响应使用指数退避\n- **重试机制**：临时错误（429、5xx）最多重试3次，永久错误（其他4xx）记录并跳过\n- **错误日志**：失败记录追加到输入文件同目录的 `errors.csv`\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n### v1 与 v2 版本对比\n\n| 特性 | v1 | v2 |\n|------|----|----|\n| 基础设施访问 | Redis、ClickHouse、PostgreSQL、S3 | 仅需Langfuse Host URL |\n| 配置复杂度 | 需完整repo克隆和环境配置 | 只需 tsx 运行 + 环境变量 |\n| 事件投递 | 直接BullMQ addBulk到Redis | HTTP POST到管理API |\n| 断点续传 | 手动（分割文件、重跑） | 内置检查点/续传 |\n| 速率限制 | 无（可能压垮Redis） | 客户端+服务端双重限速 |\n\n## 事件转换\n\n重放脚本支持两种 S3 key 格式的转换：\n\n### 标准格式\n\n路径：`{projectId}/{type}/{eventBodyId}/{eventId}.json`\n\n转换结果：\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\" }\n  },\n  \"data\": {\n    \"eventBodyId\": \"<eventBodyId>\",\n    \"fileKey\": \"<eventId>\",\n    \"type\": \"<type>-create\"\n  }\n}\n```\n\n投递到 `IngestionSecondaryQueue`。\n\n### OTEL 格式\n\n路径：`otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json`\n\n转换结果：\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\", \"accessLevel\": \"project\" }\n  },\n  \"data\": {\n    \"fileKey\": \"otel/<projectId>/<yyyy>/<mm>/<dd>/<hh>/<mm>/<eventId>.json\"\n  }\n}\n```\n\n投递到 `OtelIngestionQueue`。\n\n## 管理员 API 端点\n\n### POST /api/admin/ingestion-replay\n\n接受批量 S3 key 并将其排队等待重新处理。\n\n**认证方式**：`Authorization: Bearer {ADMIN_API_KEY}` 头，由 `AdminApiAuthService` 验证。\n\n**请求格式**：\n```json\n{\n  \"keys\": [\n    \"projectId/trace/eventBodyId/eventId.json\",\n    \"otel/projectId/2025/07/09/14/30/some-uuid.json\"\n  ]\n}\n```\n\n**响应格式**：\n```json\n{\n  \"queued\": 498,\n  \"skipped\": 2,\n  \"errors\": []\n}\n```\n\n**状态码说明**：\n\n| 状态码 | 含义 |\n|--------|------|\n| 200 | 批次已接受（检查 `skipped`/`errors` 了解部分失败） |\n| 401 | 缺少或无效的 `ADMIN_API_KEY` |\n| 400 | 请求体格式错误 |\n| 429 | 速率限制，等待退避后重试 |\n\n## 性能优化\n\n队列系统采用多种策略确保高性能：\n\n### 并发处理\n\n- 不同队列可独立配置并发数\n- Worker 支持水平扩展，多实例并行消费\n- 基于 Redis 的队列提供低延迟的消息传递\n\n### 重试机制\n\n```mermaid\ngraph TD\n    A[消息处理失败] --> B{错误类型}\n    B -->|临时错误 429/5xx| C[指数退避重试]\n    B -->|永久错误 4xx| D[记录并跳过]\n    C --> E[重试次数 < 3?]\n    E -->|是| A\n    E -->|否| D\n```\n\n### 资源管理\n\n- 完成或失败的消息自动清理（可配置保留策略）\n- 死信队列处理长时间失败的消息\n- 内存敏感操作使用流式处理\n\n## 监控与调试\n\n### 本地调试工具\n\n事件重放脚本提供进度追踪功能：\n\n```bash\n# 运行脚本会输出类似：\n[1200/45000] 2.7% — 498 queued, 2 skipped\n```\n\n### 检查点文件\n\n脚本在每次批量处理成功后保存检查点：\n\n```\n./worker/events.csv\n./worker/events.csv.checkpoint  # 存储当前行偏移量\n```\n\n### 错误日志\n\n处理失败的事件记录到 `errors.csv`：\n\n```csv\ns3_key,error_message,timestamp\nprojectId/trace/xxx.json,Rate limited,2025-07-09T10:30:00Z\n```\n\n## 最佳实践\n\n### 生产环境部署\n\n1. **队列隔离**：不同环境的队列使用不同的 Redis 实例或键前缀\n2. **监控告警**：配置队列深度、处理延迟、失败率的监控\n3. **优雅关闭**：Worker 支持优雅关闭，确保处理中的任务完成\n\n### 故障恢复\n\n1. **启用检查点**：长时间运行的批量任务使用断点续传\n2. **死信处理**：定期检查死信队列，分析失败原因\n3. **数据校验**：重放前验证事件格式，避免格式错误导致处理失败\n\n### 容量规划\n\n- 根据峰值吞吐量配置 Worker 并发数\n- 监控队列积压情况，动态扩展 Worker\n- 评估 Redis 内存使用，预留足够空间\n\n## 相关文档\n\n- [Worker 服务文档](../worker/README.md)\n- [事件摄取系统](./ingestion.md)\n- [评估执行系统](./evaluation.md)\n- [ClickHouse 存储](./clickhouse.md)\n\n---\n\n<a id='p-api'></a>\n\n## API 系统\n\n### 相关页面\n\n相关主题：[追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [fern/apis/server/definition](https://github.com/langfuse/langfuse/blob/main/fern/apis/server/definition)\n- [fern/apis/client/definition](https://github.com/langfuse/langfuse/blob/main/fern/apis/client/definition)\n- [packages/shared/src/server/ingestion](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/ingestion)\n- [web/src/features/public-api](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api)\n- [packages/shared/src/features/scores/interfaces](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n</details>\n\n# API 系统\n\n## 概述\n\nLangfuse 的 API 系统是一个多层架构，支持数据摄取、公共 API 接口、客户端 SDK 以及服务端内部调用。该系统采用 Fern 进行 API 定义和类型生成，实现了服务端和客户端的双向代码生成，确保 API 的一致性和类型安全。\n\nAPI 系统主要包含以下几个核心组成部分：\n\n- **摄取 API (Ingestion API)**：接收来自 SDK 和集成工具的事件数据\n- **公共 API (Public API)**：面向外部开发者的高层 REST 接口\n- **客户端 SDK API**：Python 和 JavaScript/TypeScript SDK 使用的接口\n- **服务端定义 API**：内部服务端使用的 API 定义\n\n资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)\n\n---\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TD\n    subgraph 外部客户端\n        A[Python SDK]\n        B[JS/TS SDK]\n        C[直接 HTTP 请求]\n    end\n    \n    subgraph API 层\n        D[摄取 API]\n        E[公共 API]\n        F[Admin API]\n    end\n    \n    subgraph 服务端组件\n        G[Next.js API Routes]\n        H[BullMQ Queues]\n        I[Prisma ORM]\n    end\n    \n    subgraph 数据存储\n        J[(PostgreSQL)]\n        K[(ClickHouse)]\n        L[(Redis)]\n    end\n    \n    A --> D\n    B --> D\n    C --> D\n    C --> E\n    D --> H\n    H --> I\n    I --> J\n    I --> K\n    I --> L\n    E --> G\n    G --> I\n```\n\n### API 版本策略\n\nLangfuse 采用双版本 API 策略，同时维护 v1 和 v2 两个版本的 API：\n\n| 版本 | 状态 | 说明 |\n|------|------|------|\n| v1 | 继续支持 | 遗留 API，聚焦于 trace 级别 |\n| v2 | 当前版本 | 支持 traces、sessions 及更多功能 |\n\n**关键差异**：在 GET API 中，v1 需要 `traceId` 参数且仅支持 trace 级别分数；v2 将 `traceId` 设为可选，并新增 `sessionId` 支持。\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 摄取 API (Ingestion API)\n\n### 功能概述\n\n摄取 API 是 Langfuse 数据入口点，负责接收来自各类 SDK 和集成工具的事件数据，包括 traces、generations、spans、events 等。\n\n### 支持的事件类型\n\n摄取 API 支持多种事件类型的批量摄取：\n\n```typescript\n// 标准事件结构\ninterface IngestionEvent {\n  eventBodyId: string;      // 事件体 ID\n  type: EventType;          // 事件类型\n  timestamp: Date;         // 事件时间戳\n  metadata?: Record<string, unknown>;\n}\n```\n\n### S3 事件回放\n\n对于大规模事件重放场景，Langfuse 提供了基于 S3 的事件回放功能：\n\n```mermaid\ngraph LR\n    A[S3 Access Logs] --> B[CSV 文件]\n    B --> C[replayIngestionEventsV2]\n    C --> D{批量处理}\n    D -->|500 条/批| E[POST /api/admin/ingestion-replay]\n    E --> F[摄取队列]\n    F --> G[ClickHouse/PostgreSQL]\n```\n\n### 回放脚本参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--csv` | 必需 | CSV 文件路径 |\n| `--batch-size` | 500 | 每批 API 请求的键数量 |\n| `--concurrency` | 4 | 最大并行 API 请求数 |\n| `--rate-limit` | 50 | 最大每秒请求数 |\n| `--dry-run` | false | 仅解析验证不发送 |\n| `--resume` | false | 从上次检查点继续 |\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n---\n\n## 公共 API (Public API)\n\n### 路由创建规范\n\nLangfuse 的公共 API 路由遵循严格的实现规范：\n\n```typescript\n// 标准 API 路由结构\nimport { withMiddleware } from \"@/src/apiMiddleware\";\nimport { createAuthedAPIRoute } from \"@/src/lib/createAuthedAPIRoute\";\n\n// 使用 withMiddleware 包装\nexport default withMiddleware(\n  createAuthedAPIRoute({\n    // Zod 类型定义\n    request: z.object({...}),\n    response: z.object({...}),\n    // 业务逻辑\n    handler: async (req, res) => {\n      // 实现代码\n    }\n  })\n);\n```\n\n### 类型定义位置\n\n所有公共 API 的类型定义位于 `packages/shared/src/features/public-api/types/` 目录：\n\n- 使用 `coerce` 处理日期等原始类型转换\n- 对不应返回额外属性的对象使用 `strict()` 模式\n- 使用 `validateZodSchema` 在 API 路由中验证响应类型\n\n### API 响应验证\n\n```typescript\nimport { validateZodSchema } from \"@/src/lib/validateZodSchema\";\n\n// 在 API 路由中验证响应\nconst validatedResponse = validateZodSchema(response, ResponseSchema);\n```\n\n### 错误处理\n\n公共 API 使用 `shared/src/errors` 中定义的错误类，这些错误会自动转换为相应的 HTTP 状态码：\n\n```typescript\nimport { ValidationError, NotFoundError } from \"@/src/errors\";\n\n// 抛出错误会被自动转换\nthrow new ValidationError(\"Invalid input\");\nthrow new NotFoundError(\"Resource not found\");\n```\n\n资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)\n\n---\n\n## Fern API 定义\n\n### 概述\n\nLangfuse 使用 Fern 进行 API 定义，实现服务端和客户端的代码生成。\n\n### 目录结构\n\n```\nfern/\n├── apis/\n│   ├── server/\n│   │   └── definition/     # 服务端 API 定义\n│   └── client/\n│       └── definition/      # 客户端 SDK API 定义\n```\n\n### 代码生成流程\n\n```mermaid\ngraph TD\n    A[Fern 定义文件] --> B[fern generate --api server]\n    A --> C[fern generate --api client]\n    B --> D[服务端类型]\n    C --> E[Python SDK 类型]\n    C --> F[JS/TS SDK 类型]\n```\n\n### 生成命令\n\n```bash\n# 生成服务端 API\nfern generate --api server\n\n# 生成客户端 API\nfern generate --api client\n\n# 提交生成的变更\ngit commit -m \"chore: update api reference\"\n```\n\n### API Reference 文档\n\n生成的 API Reference 会被添加到 Fern 文档中，包含 `docs` 属性用于描述接口用途和参数说明。\n\n资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)\n\n---\n\n## 分数接口 (Score Interfaces)\n\n### 目录结构\n\n```\npackages/shared/src/features/scores/interfaces/\n├── api/\n│   ├── v1/                  # v1 API 类型\n│   │   ├── endpoints.ts\n│   │   ├── schemas.ts\n│   │   └── validation.ts\n│   ├── v2/                  # v2 API 类型\n│   │   ├── endpoints.ts\n│   │   ├── schemas.ts\n│   │   └── validation.ts\n│   └── shared.ts            # 通用类型\n├── application/             # 应用层验证\n│   └── validation.ts\n├── ingestion/               # 摄取端点类型\n│   └── validation.ts\n└── ui/                      # UI 组件类型\n    └── types.ts\n```\n\n### API 版本对比\n\n| 特性 | v1 API | v2 API |\n|------|--------|--------|\n| traceId 参数 | 必需 | 可选 |\n| sessionId 支持 | ❌ | ✅ |\n| 支持的分数类型 | trace 级别 | trace、session、dataset run |\n\n### 验证层次\n\n分数接口采用多层验证架构：\n\n1. **API 层验证** (`api/v1/validation.ts`, `api/v2/validation.ts`)：处理请求参数验证\n2. **应用层验证** (`application/validation.ts`)：业务逻辑验证\n3. **摄取层验证** (`ingestion/validation.ts`)：数据摄取时的验证\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## Admin API\n\n### 认证机制\n\nAdmin API 使用 `Authorization: Bearer {ADMIN_API_KEY}` 头部进行认证：\n\n```bash\ncurl -X POST https://your-langfuse.com/api/admin/ingestion-replay \\\n  -H \"Authorization: Bearer $ADMIN_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"keys\": [\"projectId/trace/eventBodyId/eventId.json\"]}'\n```\n\n### 端点：摄取回放\n\n**端点**：`POST /api/admin/ingestion-replay`\n\n**请求格式**：\n\n```json\n{\n  \"keys\": [\n    \"projectId/trace/eventBodyId/eventId.json\",\n    \"otel/projectId/2025/07/09/14/30/some-uuid.json\"\n  ]\n}\n```\n\n**响应格式**：\n\n```json\n{\n  \"queued\": 498,\n  \"skipped\": 2,\n  \"errors\": []\n}\n```\n\n### 响应状态码\n\n| 状态码 | 含义 |\n|--------|------|\n| 200 | 批量已接受（检查 `skipped`/`errors` 获取部分失败信息） |\n| 401 | 缺少或无效的 `ADMIN_API_KEY` |\n| 400 | 请求体格式错误 |\n| 429 | 速率限制，请稍后重试 |\n\n### 事件转换\n\n**标准键格式**：`{projectId}/{type}/{eventBodyId}/{eventId}.json`\n\n转换后的队列负载：\n\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\" }\n  },\n  \"data\": {\n    \"eventBodyId\": \"<eventBodyId>\",\n    \"fileKey\": \"<eventId>\",\n    \"type\": \"<type>-create\"\n  }\n}\n```\n\n**OTEL 键格式**：`otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json`\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n---\n\n## SDK API\n\n### Python SDK\n\nPython SDK 使用从 Fern 生成的类型和接口，提供与 Langfuse 服务器交互的便捷方法：\n\n```python\nfrom langfuse import Langfuse\n\nclient = Langfuse(\n    public_key=\"pk-lf-xxx\",\n    secret_key=\"sk-lf-xxx\",\n    host=\"https://cloud.langfuse.com\"\n)\n\n# 创建 trace\ntrace = client.trace.create(\n    name=\"my-trace\",\n    metadata={\"user_id\": \"123\"}\n)\n```\n\n### JavaScript/TypeScript SDK\n\nJS/TS SDK 采用相同的 Fern 定义，确保与 Python SDK 行为一致：\n\n```typescript\nimport { Langfuse } from \"langfuse-js\";\n\nconst langfuse = new Langfuse({\n  publicKey: \"pk-lf-xxx\",\n  secretKey: \"sk-lf-xxx\",\n  baseUrl: \"https://cloud.langfuse.com\"\n});\n\n// 创建 trace\nconst trace = await langfuse.trace.create({\n  name: \"my-trace\",\n  metadata: { userId: \"123\" }\n});\n```\n\n---\n\n## 认证与授权\n\n### 认证方式\n\nLangfuse API 支持多种认证方式：\n\n| 认证方式 | 适用场景 | 说明 |\n|----------|----------|------|\n| API Keys | SDK 和直接调用 | public_key + secret_key |\n| Basic Auth | MCP Server | base64(publicKey:secretKey) |\n| Bearer Token | Admin API | ADMIN_API_KEY |\n\n### Basic Auth 编码\n\n```bash\n# 生成 Basic Auth Token\necho -n \"pk-lf-your-public-key:sk-lf-your-secret-key\" | base64\n```\n\n### MCP Server 认证\n\nMCP Server 使用 Basic Auth 认证：\n\n```typescript\n{\n  auth: {\n    authType: \"BasicAuth\",\n    accessLevel: \"project\",\n    publicKey: \"pk-lf-...\"\n  }\n}\n```\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n---\n\n## 测试策略\n\n### API 响应验证测试\n\n使用 `makeZodVerifiedAPICall` 测试工具验证 API 响应：\n\n```typescript\nimport { makeZodVerifiedAPICall } from \"@/test/server\";\n\nit(\"should return correct response structure\", async () => {\n  const response = await makeZodVerifiedAPICall(\n    \"GET\",\n    \"/api/public-api/endpoint\",\n    {},\n    ResponseSchema\n  );\n  \n  expect(response.data).toBeDefined();\n});\n```\n\n### 测试覆盖要求\n\n- 所有标准用例必须有测试覆盖\n- 使用 `strict()` 模式的对象响应，测试工具会在额外属性时抛出错误\n- 生产环境会记录响应包含额外属性的错误\n\n---\n\n## 最佳实践\n\n### API 路由开发流程\n\n1. 在 `features/public-api/types/` 中添加 Zod 类型定义\n2. 使用 `coerce` 处理日期等需要转换的类型\n3. 在 API 路由中使用 `validateZodSchema` 验证响应\n4. 添加完整的测试用例\n5. 运行 `fern generate` 更新 SDK 类型\n6. 提交所有变更\n\n### 错误处理规范\n\n- 优先使用 `shared/src/errors` 中预定义的错误类\n- 避免直接返回原始错误信息给客户端\n- 在生产环境记录详细的错误日志\n\n### 性能考虑\n\n- 批量摄取事件以减少网络开销\n- 使用检查点机制支持长时间运行的批处理任务\n- 实施客户端和服务器端速率限制\n\n---\n\n## 相关链接\n\n- [Fern 文档](https://buildwithfern.com/)\n- [Zod 验证库](https://zod.dev/)\n- [Langfuse SDK 文档](https://langfuse.com/docs/sdk)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langfuse/langfuse\n\n摘要：发现 17 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：bug: Using client with context manager breaks the scoring。\n\n## 1. 安装坑 · 来源证据：bug: Using client with context manager breaks the scoring\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Using client with context manager breaks the scoring\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5afee24537ba47369cc4621f7fb18122 | https://github.com/langfuse/langfuse/issues/8138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：bug: unnamed trace name in Langfuse UI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: unnamed trace name in Langfuse UI\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a219c99fe99c4b7dab002e2b3a6296c2 | https://github.com/langfuse/langfuse/issues/13416 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8657d86702904e90b9d448770e618256 | https://github.com/langfuse/langfuse/issues/8173 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cff1b1d1a1ca4eb892563c33d3aa62e9 | https://github.com/langfuse/langfuse/issues/8156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49a69075a1c346789a28db93c9ec6f3f | https://github.com/langfuse/langfuse/issues/13601 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v3.169.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.169.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_864f213fd7694eba9a4d2fe2bb9267ab | https://github.com/langfuse/langfuse/releases/tag/v3.169.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v3.172.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.172.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14588986ba9945eeb40cbc0508e3fed0 | https://github.com/langfuse/langfuse/releases/tag/v3.172.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v3.173.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.173.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7560a954846b4f35aedb74de1291c9a4 | https://github.com/langfuse/langfuse/releases/tag/v3.173.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:642497346 | https://github.com/langfuse/langfuse | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：v3.168.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.168.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_202b4e8c2c1f4b3790315098d1530297 | https://github.com/langfuse/langfuse/releases/tag/v3.168.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：v3.170.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.170.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ed6f994e1424878aa4559a73d72fc52 | https://github.com/langfuse/langfuse/releases/tag/v3.170.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v3.174.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.174.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9cb7b7232ff4cce96f0c020fe48c7f4 | https://github.com/langfuse/langfuse/releases/tag/v3.174.0 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | release_recency=unknown\n\n<!-- canonical_name: langfuse/langfuse; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "langfuse",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:642497346",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/langfuse/langfuse"
        },
        {
          "evidence_id": "art_4db510b3782b4191a485788845d3047b",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/langfuse/langfuse#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "langfuse 说明书",
      "toc": [
        "https://github.com/langfuse/langfuse 项目说明书",
        "目录",
        "项目介绍",
        "项目概述",
        "架构设计",
        "核心功能模块",
        "后端 Worker 系统",
        "依赖管理",
        "Doramagic 踩坑日志"
      ]
    }
  },
  "quality_gate": {
    "blocking_gaps": [],
    "category_confidence": "medium",
    "compile_status": "ready_for_review",
    "five_assets_present": true,
    "install_sandbox_verified": true,
    "missing_evidence": [],
    "next_action": "publish to Doramagic.ai project surfaces",
    "prompt_preview_boundary_ok": true,
    "publish_status": "publishable",
    "quick_start_verified": true,
    "repo_clone_verified": true,
    "repo_commit": "da8a4f54c92bc5f16415f1a039ca5530aa62298b",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "pnpm-lock.yaml",
      "package.json",
      "README.md",
      "docker-compose.yml",
      "packages/eslint-plugin/vitest.config.ts",
      "packages/eslint-plugin/vitest.setup.ts",
      "packages/eslint-plugin/package.json",
      "packages/eslint-plugin/tsconfig.json",
      "packages/shared/AGENTS.md",
      "packages/shared/package.json",
      "packages/shared/tsconfig.json",
      "packages/config-typescript/package.json",
      "packages/config-typescript/nextjs.json",
      "packages/config-typescript/base.json",
      "packages/config-eslint/base.js",
      "packages/config-eslint/index.js",
      "packages/config-eslint/index.d.ts",
      "packages/config-eslint/package.json",
      "packages/config-eslint/next.d.ts",
      "packages/config-eslint/base.d.ts",
      "packages/config-eslint/next.js",
      "packages/eslint-plugin/src/util.ts",
      "packages/eslint-plugin/src/index.ts",
      "packages/eslint-plugin/src/rules/no-tailwind-overflow-scroll.test.ts",
      "packages/eslint-plugin/src/rules/no-in-source-vitest.test.ts",
      "packages/eslint-plugin/src/rules/no-in-source-vitest.ts",
      "packages/eslint-plugin/src/rules/no-tailwind-overflow-scroll.ts",
      "packages/shared/src/eventsTable.ts",
      "packages/shared/src/db.ts",
      "packages/shared/src/constants.ts",
      "packages/shared/src/index.ts",
      "packages/shared/src/env.ts",
      "packages/shared/src/types.ts",
      "packages/shared/src/observationsTable.ts",
      "packages/shared/src/server/logger.ts",
      "packages/shared/src/server/deletionGuard.ts",
      "packages/shared/src/server/orderByToPrisma.ts",
      "packages/shared/src/server/traceDeletionProcessor.ts",
      "packages/shared/src/server/index.ts",
      "packages/shared/src/server/queues.ts"
    ],
    "repo_inspection_verified": true,
    "review_reasons": [],
    "tag_count_ok": true,
    "unsupported_claims": []
  },
  "schema_version": "0.1",
  "user_assets": {
    "ai_context_pack": {
      "asset_id": "ai_context_pack",
      "filename": "AI_CONTEXT_PACK.md",
      "markdown": "# langfuse - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 langfuse 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/add-model-price/SKILL.md`, `.agents/skills/agent-setup-maintenance/SKILL.md`, `.agents/skills/analyze-cloud-costs/SKILL.md`, `.agents/skills/backend-dev-guidelines/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/add-model-price/SKILL.md`, `.agents/skills/agent-setup-maintenance/SKILL.md`, `.agents/skills/analyze-cloud-costs/SKILL.md`, `.agents/skills/backend-dev-guidelines/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `git clone https://github.com/langfuse/langfuse.git` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install langfuse openai` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/add-model-price/SKILL.md`, `.agents/skills/agent-setup-maintenance/SKILL.md`, `.agents/skills/analyze-cloud-costs/SKILL.md`, `.agents/skills/backend-dev-guidelines/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/add-model-price/SKILL.md`, `.agents/skills/agent-setup-maintenance/SKILL.md`, `.agents/skills/analyze-cloud-costs/SKILL.md`, `.agents/skills/backend-dev-guidelines/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/add-model-price/SKILL.md`, `.agents/skills/agent-setup-maintenance/SKILL.md`, `.agents/skills/analyze-cloud-costs/SKILL.md`, `.agents/skills/backend-dev-guidelines/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/add-model-price/SKILL.md`, `.agents/skills/agent-setup-maintenance/SKILL.md`, `.agents/skills/analyze-cloud-costs/SKILL.md`, `.agents/skills/backend-dev-guidelines/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.agents/skills/add-model-price/SKILL.md`, `.agents/skills/agent-setup-maintenance/SKILL.md`, `.agents/skills/analyze-cloud-costs/SKILL.md`, `.agents/skills/backend-dev-guidelines/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：3224\n- 重要文件覆盖：40/3224\n- 证据索引条目：80\n- 角色 / Skill 条目：16\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 langfuse 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 langfuse 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 langfuse 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 16 个角色 / Skill / 项目文档条目。\n\n- **add-model-price**（skill）：Use when editing worker/src/constants/default-model-prices.json, packages/shared/src/server/llm/types.ts, pricing tiers, tokenizer IDs, or matchPattern regexes for OpenAI, Anthropic, Bedrock, Vertex, Azure, or Gemini model pricing. 激活提示：当用户任务与“add-model-price”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/add-model-price/SKILL.md`\n- **agent-setup-maintenance**（skill）： 激活提示：当用户任务与“agent-setup-maintenance”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/agent-setup-maintenance/SKILL.md`\n- **analyze-cloud-costs**（skill）： 激活提示：当用户任务与“analyze-cloud-costs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/analyze-cloud-costs/SKILL.md`\n- **backend-dev-guidelines**（skill）：Shared backend guide for Langfuse's Next.js, tRPC, BullMQ, and TypeScript monorepo. Use when creating or reviewing tRPC routers, public REST endpoints, BullMQ queue processors, backend services, middleware, Prisma or ClickHouse data access, OpenTelemetry instrumentation, Zod validation, env configuration, or backend tests across web, worker, or packages/shared. 激活提示：当用户任务与“backend-dev-guidelines”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/backend-dev-guidelines/SKILL.md`\n- **changelog-writing**（skill）： 激活提示：当用户任务与“changelog-writing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/changelog-writing/SKILL.md`\n- **clickhouse-best-practices**（skill）：MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 28 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses. 激活提示：当用户任务与“clickhouse-best-practices”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/clickhouse-best-practices/SKILL.md`\n- **code-review**（skill）： 激活提示：当用户任务与“code-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/code-review/SKILL.md`\n- **datadog-query-recipes**（skill）： 激活提示：当用户任务与“datadog-query-recipes”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/datadog-query-recipes/SKILL.md`\n- **debug-issue-with-datadog**（skill）： 激活提示：当用户任务与“debug-issue-with-datadog”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/debug-issue-with-datadog/SKILL.md`\n- **detect-prod-regressions**（skill）： 激活提示：当用户任务与“detect-prod-regressions”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/detect-prod-regressions/SKILL.md`\n- **frontend-browser-review**（skill）： 激活提示：当用户任务与“frontend-browser-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/frontend-browser-review/SKILL.md`\n- **linear-bug-triage**（skill）： 激活提示：当用户任务与“linear-bug-triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/linear-bug-triage/SKILL.md`\n- **pnpm-upgrade-package**（skill）：Use when upgrading a dependency in this pnpm workspace, including requests to bump a package to a specific version, compare the registry latest version with the latest version installable under the current minimum-release-age window, or decide whether minimumReleaseAgeExclude in pnpm-workspace.yaml must change. Ask the user for the package name or target version when either is missing. 激活提示：当用户任务与“pnpm-upgrade-package”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/pnpm-upgrade-package/SKILL.md`\n- **turborepo**（skill）： 激活提示：当用户任务与“turborepo”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/turborepo/SKILL.md`\n- **vercel-composition-patterns**（skill）：Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale. 激活提示：当用户任务与“vercel-composition-patterns”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`web/.agents/skills/vercel-composition-patterns/SKILL.md`\n- **vercel-react-best-practices**（skill）：React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. 激活提示：当用户任务与“vercel-react-best-practices”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`web/.agents/skills/vercel-react-best-practices/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Agent Guidelines for Langfuse**（documentation）：This is the canonical root agent guide for the repo. The root AGENTS.md should remain only as a discovery symlink so tools that require that filename continue to work while .agents/ stays the source of truth. 证据：`.agents/AGENTS.md`\n- **Shared Agent Setup**（documentation）：This directory is the neutral, repo-owned source of truth for agent behavior in Langfuse. 证据：`.agents/README.md`\n- **✨ Core Features**（documentation）：Langfuse Is Doubling Down On Open Source Langfuse Cloud · Self Host · Demo 证据：`README.md`\n- **Codex Guidelines for ee**（documentation）：This file covers package-local guidance for this package. Use root AGENTS.md ../AGENTS.md for monorepo-level rules. 证据：`ee/AGENTS.md`\n- **Enterprise Edition**（documentation）：This folder includes features that are only available in the Enterprise Edition of Langfuse and on Langfuse Cloud. 证据：`ee/README.md`\n- **Codex Guidelines for web**（documentation）：This file covers package-local guidance for this package. Use root AGENTS.md ../AGENTS.md for monorepo-level rules. 证据：`web/AGENTS.md`\n- **CLAUDE.md**（documentation）：Claude Code should treat this file as the package entrypoint for web/ . 证据：`web/CLAUDE.md`\n- **Codex Guidelines for worker**（documentation）：This file covers package-local guidance for this package. Use root AGENTS.md ../AGENTS.md for monorepo-level rules. 证据：`worker/AGENTS.md`\n- **Shared Skills**（documentation）：Shared repo skills for any coding agent working in Langfuse. 证据：`.agents/skills/README.md`\n- **Add Model Price**（documentation）：Guide for adding or updating model pricing entries in Langfuse. Use this when editing worker/src/constants/default-model-prices.json , packages/shared/src/server/llm/types.ts , model matchPattern values, tokenizer IDs, or pricing tiers. 证据：`.agents/skills/add-model-price/AGENTS.md`\n- **Backend Development Guidelines**（documentation）：Establish consistency and best practices across Langfuse's backend packages web , worker , packages/shared using Next.js, tRPC, BullMQ, and TypeScript patterns. Check package manifests such as web/package.json for current framework versions before version-sensitive work. Keep this file as an entrypoint; open reference files only when the task needs their details. 证据：`.agents/skills/backend-dev-guidelines/AGENTS.md`\n- **ClickHouse Best Practices**（documentation）：Start with SKILL.md for the ClickHouse review workflow, rule-selection process, and response format. This file exists as a concise compatibility entrypoint for agents that open AGENTS.md directly. 证据：`.agents/skills/clickhouse-best-practices/AGENTS.md`\n- **ClickHouse Best Practices**（documentation）：Agent skill providing comprehensive ClickHouse guidance for schema design, query optimization, and data ingestion. 证据：`.agents/skills/clickhouse-best-practices/README.md`\n- **PNPM Upgrade Package**（documentation）：Use this workflow when a user wants to upgrade a dependency in the Langfuse pnpm workspace. 证据：`.agents/skills/pnpm-upgrade-package/AGENTS.md`\n- **Codex Guidelines for @langfuse/shared**（documentation）：Codex Guidelines for @langfuse/shared 证据：`packages/shared/AGENTS.md`\n- **Langfuse Seeder System**（documentation）：System for generating test data in ClickHouse and PostgreSQL for Langfuse development and testing. 证据：`packages/shared/scripts/seeder/utils/README.md`\n- **Framework Traces**（documentation）：This folder contains real traces produced through framework instrumentation. Most of them stem from here: https://langfuse.com/integrations/frameworks/agno-agents and so on. 证据：`packages/shared/scripts/seeder/utils/framework-traces/README.md`\n- **Score Interfaces**（documentation）：This directory contains all type definitions, schemas, and validation logic for Langfuse scores. 证据：`packages/shared/src/features/scores/interfaces/README.md`\n- **Instrumentation at Langfuse**（documentation）：Throughout our applications we want to use as much Otel as possible. This helps us to be flexible choosing our observability backend, and we will benefit from features and packages built by the Otel community. 证据：`packages/shared/src/server/instrumentation/README.md`\n- **Repository docs**（documentation）：Guarantees for relating data within Langfuse 证据：`packages/shared/src/server/repositories/README.md`\n- **React Composition Patterns**（documentation）：Version 1.0.0 Engineering January 2026 证据：`web/.agents/skills/vercel-composition-patterns/AGENTS.md`\n- **React Best Practices**（documentation）：Version 1.0.0 Vercel Engineering January 2026 证据：`web/.agents/skills/vercel-react-best-practices/AGENTS.md`\n- **Design System**（documentation）：This folder contains reusable, primitive, presentational UI components . 证据：`web/src/components/design-system/README.md`\n- **📦 Langfuse Layout Components**（documentation）：📌 Overview: Page - Standard Page Wrapper 证据：`web/src/components/layouts/README.md`\n- **Peek View Table State Management**（documentation）：This document describes how table state filters, sorting, pagination, search is managed and persisted in peek views when navigating between items using K/J keyboard shortcuts. 证据：`web/src/components/table/peek/README.md`\n- **Table View Presets**（documentation）：This module provides a flexible and robust way to manage and persist table states across sessions. Users can save, load, and share specific table configurations including column visibility, ordering, filters, and search queries. 证据：`web/src/components/table/table-view-presets/README.md`\n- **AdvancedJsonViewer**（documentation）：A high-performance JSON viewer component built for rendering large datasets 10K+ nodes with virtualization, search, and near-instant expand/collapse operations. 证据：`web/src/components/ui/AdvancedJsonViewer/README.md`\n- **Enterprise Edition**（documentation）：This folder includes features that are only available in the Enterprise Edition of Langfuse and on Langfuse Cloud. 证据：`web/src/ee/README.md`\n- **Billing**（documentation）：Stripe Billing powers subscriptions and usage-based pricing for organizations. We primarily use the new flexible billing model plan + usage and still handle legacy, single-item metered subscriptions during migration. 证据：`web/src/ee/features/billing/README.md`\n- **Public API**（documentation）：- Wrap with withMiddleware - Type-safe and authed API Route with createAuthedAPIRoute - Add zod types to /features/public-api/types folder. 证据：`web/src/features/README.md`\n- **Batch Exports**（documentation）：- Find types in shared - Actual export logic in worker 证据：`web/src/features/batch-exports/README.md`\n- **Dataset Mutations**（documentation）：Always use functions in this directory. Never use direct Prisma calls. 证据：`web/src/features/datasets/server/actions/README.md`\n- **Entitlements**（documentation）：This feature allows to control for availability of features. Entitlements are managed on the organization level. 证据：`web/src/features/entitlements/README.md`\n- **Feature Flags**（documentation）：Configure feature flags in the available-flags.ts file. 证据：`web/src/features/feature-flags/README.md`\n- **Langfuse MCP Server**（documentation）：Model Context Protocol MCP server for Langfuse, enabling AI assistants to interact with your Langfuse prompts programmatically. 证据：`web/src/features/mcp/README.md`\n- **Caching Strategy of Prompts**（documentation）：The caching strategy for prompts is implemented in the PromptService class and is utilized in the createPrompt function. Here is an overview of how the caching mechanism works: 证据：`web/src/features/prompts/README.md`\n- **Prompt Mutations**（documentation）：Always use functions in this directory. Never use direct Prisma calls. 证据：`web/src/features/prompts/server/actions/README.md`\n- **Caching Strategy of API Keys**（documentation）：The cache for API keys is managed using Redis. The cache key looks like the following: api-key: : . The hash is the fastHashedSecretKey from postgres. Hence, we can easily find the key in Redis. 证据：`web/src/features/public-api/README.md`\n- **Score Analytics - Architecture Guide**（documentation）：Score Analytics - Architecture Guide 证据：`web/src/features/score-analytics/README.md`\n- **Slack Integration Setup Guide**（documentation）：This guide walks you through setting up and testing the Langfuse Slack integration for local development. 证据：`web/src/features/slack/README.md`\n- **Telemetry service for Docker deployments**（documentation）：Telemetry service for Docker deployments 证据：`web/src/features/telemetry/README.md`\n- **Readme**（documentation）：These APIs are implemented via the NextJS App router in src/app/api/billing. 证据：`web/src/pages/api/billing/README.md`\n- **otlp-proto**（documentation）：This directory contains compiled opentelemetry protobuf files. Those should correspond to the definitions in https://github.com/open-telemetry/opentelemetry-proto/tree/v1.5.0 and are copied from the generated contents of https://www.npmjs.com/package/@opentelemetry/otlp-transformer. The file was converted from .js to .ts and the export statements were modified to make them Next.js compatible. 证据：`web/src/pages/api/public/otel/otlp-proto/README.md`\n- **ChatML Normalization System**（documentation）：Normalizes LLM provider/framework data traces, observations to ChatML format for display and, partly, playground. In general, provider adapters preprocess data → ChatMlSchema validates → UI renders 证据：`web/src/utils/chatml/README.md`\n- **Readme**（documentation）：Those traces are used to test the chatML adapters. They comes for the various framework intragration examples in Langfuse's doc for example https://langfuse.com/integrations/frameworks/agno-agents . Use download traces.js to generate the files. 证据：`worker/src/__tests__/chatml/framework-traces/README.md`\n- **Background Migrations**（documentation）：Background migrations are longer running jobs that must not be complete before a new application version can be served correctly. They are used to fill new optional columns, migrate data between tables or systems, or perform other actions that would take too long to run in a standard migration. A good threshold is something that takes more than 5 minutes to run or is not an atomic operation. 证据：`worker/src/backgroundMigrations/README.md`\n- **Refill Queue Event**（documentation）：This is a utility script to backfill any queue with events from local machines. It validates events against the queue's schema and processes them in batches for efficient ingestion. 证据：`worker/src/scripts/refillQueueEvent/README.md`\n- **Replay Ingestion Events from S3 v2**（documentation）：Replays failed ingestion events by reading S3 keys from a CSV and submitting them to Langfuse via an admin API endpoint. This replaces the v1 script ../replayIngestionEvents/README.md , which required direct Redis, ClickHouse, and PostgreSQL access plus a full repo clone. 证据：`worker/src/scripts/replayIngestionEventsV2/README.md`\n- **Verify Clickhouse Records**（documentation）：This script is used to compare Clickhouse records to our Postgres records. Per default, it draws a sample of observations, traces, and scores from the Postgres tables and executes single queries on Clickhouse to compare the individual fields. It is possible to overwrite the selection process using the overwriteIds per type. 证据：`worker/src/scripts/verifyClickhouseRecords/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@langfuse/ee\", \"version\": \"1.0.0\", \"private\": true, \"main\": \"./dist/src/index.js\", \"types\": \"./dist/src/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/src/index.js\", \"require\": \"./dist/src/index.js\" }, \"./sso\": { \"import\": \"./dist/src/sso/index.js\", \"require\": \"./dist/src/sso/index.js\" } }, \"engines\": { \"node\": \"24\" }, \"scripts\": { \"build\": \"tsc\", \"build:check\": \"tsc\", \"typecheck\": \"dotenv -e ../../.env -- tsgo --noEmit --skipLibCheck --incremental --tsBuildInfoFile .tsbuildinfo\", \"dev\": \"tsc --watch\", \"lint\": \"eslint . --cache --cache-location dist/.eslintcache --max-warnings 0\", \"lint:fix\": \"eslint . --cache --cache-location dist/.eslintcache --fix\" }, \"dependencies\": { \"@l… 证据：`ee/package.json`\n- **Package**（package_manifest）：{ \"name\": \"langfuse\", \"version\": \"3.174.1\", \"author\": \"engineering@langfuse.com\", \"license\": \"MIT\", \"private\": true, \"engines\": { \"node\": \"24\" }, \"scripts\": { \"agents:check\": \"node scripts/agents/sync-agent-shims.mjs --check\", \"agents:sync\": \"node scripts/agents/sync-agent-shims.mjs\", \"postinstall\": \"node -e \\\"const fs = require 'node:fs' ; const cp = require 'node:child process' ; if !fs.existsSync 'scripts/postinstall.sh' { console.log 'Skipping repo postinstall helper: scripts/postinstall.sh is not present in this install context.' ; process.exit 0 ; } cp.execSync 'bash scripts/postinstall.sh', { stdio: 'inherit' } ;\\\"\", \"preinstall\": \"npx only-allow pnpm\", \"infra:dev:up\": \"docker compos… 证据：`package.json`\n- **Package**（package_manifest）：{ \"name\": \"web\", \"version\": \"3.174.1\", \"private\": true, \"license\": \"MIT\", \"engines\": { \"node\": \"24\" }, \"scripts\": { \"build\": \"INLINE RUNTIME CHUNK=false dotenv -e ../.env -- next build\", \"build:check\": \"NEXT DIST DIR=.next-check INLINE RUNTIME CHUNK=false dotenv -e ../.env -- next build\", \"typecheck\": \"dotenv -e ../.env -- tsgo -p tsconfig.build.json --noEmit --skipLibCheck --incremental --tsBuildInfoFile .tsbuildinfo\", \"dev\": \"dotenv -e ../.env -- next dev\", \"dev:http\": \"dotenv -e ../.env -- next dev --experimental-https --experimental-https-key ./localhost+1-key.pem --experimental-https-cert ./localhost+1.pem\", \"lint\": \"dotenv -e ../.env -- eslint . --cache --cache-location .next/cache/es… 证据：`web/package.json`\n- **Package**（package_manifest）：{ \"name\": \"worker\", \"version\": \"3.174.1\", \"description\": \"\", \"license\": \"MIT\", \"private\": true, \"files\": \"dist/ \", \"entrypoint.sh\" , \"engines\": { \"node\": \"24\" }, \"scripts\": { \"test\": \"vitest run\", \"test:exclude-llm-connections\": \"vitest run --exclude ' /llmConnections.test.ts'\", \"test:llm-connections-only\": \"vitest run llmConnections.test.ts\", \"coverage\": \"vitest run --coverage\", \"start\": \"dotenv -e ../.env -- node dist/index.js\", \"build\": \"tsc\", \"build:check\": \"tsc\", \"typecheck\": \"dotenv -e ../.env -- tsgo --noEmit --skipLibCheck --incremental --tsBuildInfoFile .tsbuildinfo\", \"dev\": \"dotenv -e ../.env -- tsx watch --clear-screen=false --include '../packages/shared/dist/ ' src/index.ts\", \"l… 证据：`worker/package.json`\n- **Contributing to Langfuse**（documentation）：! Langfuse GitHub Banner https://github.com/langfuse/langfuse/assets/121163007/6035f0f3-d691-4963-b5d0-10cf506e9d42 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@repo/eslint-config\", \"version\": \"0.0.0\", \"license\": \"MIT\", \"private\": true, \"type\": \"module\", \"exports\": { \".\": \"./index.js\", \"./base\": \"./base.js\", \"./next\": \"./next.js\" }, \"files\": \"index.js\", \"base.js\", \"next.js\" , \"dependencies\": { \"@eslint/js\": \"^9.39.2\", \"@repo/eslint-plugin\": \"workspace: \", \"eslint-config-next\": \"16.2.6\", \"eslint-config-prettier\": \"^10.1.8\", \"eslint-config-turbo\": \"2.9.12\", \"eslint-plugin-only-warn\": \"^1.1.0\", \"eslint-plugin-prettier\": \"^5.5.4\", \"globals\": \"^16.0.0\", \"typescript-eslint\": \"^8.57.1\" }, \"peerDependencies\": { \"eslint\": \"^9.39.0\", \"typescript\": \" =5.0.0\" } } 证据：`packages/config-eslint/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@repo/typescript-config\", \"license\": \"MIT\", \"version\": \"0.0.0\", \"private\": true, \"publishConfig\": { \"access\": \"public\" } } 证据：`packages/config-typescript/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@repo/eslint-plugin\", \"version\": \"0.0.0\", \"license\": \"MIT\", \"private\": true, \"type\": \"module\", \"main\": \"dist/index.js\", \"scripts\": { \"test\": \"vitest run\", \"build\": \"tsc\" }, \"devDependencies\": { \"@repo/typescript-config\": \"workspace: \", \"@types/node\": \"^24.3.0\", \"@typescript-eslint/parser\": \"^8.59.0\", \"@typescript-eslint/rule-tester\": \"^8.59.0\", \"@typescript-eslint/utils\": \"^8.59.0\", \"typescript\": \"^5.9.2\", \"vitest\": \"^4.1.4\" } } 证据：`packages/eslint-plugin/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@langfuse/shared\", \"version\": \"1.0.0\", \"license\": \"MIT\", \"private\": true, \"files\": \"dist/ \", \"prisma/ \", \"clickhouse/ \", \"scripts/cleanup.sql\" , \"main\": \"./dist/src/index.js\", \"types\": \"./dist/src/index.d.ts\", \"engines\": { \"node\": \"24\" }, \"exports\": { \".\": { \"import\": \"./dist/src/index.js\", \"require\": \"./dist/src/index.js\" }, \"./src/db\": { \"import\": \"./dist/src/db.js\", \"require\": \"./dist/src/db.js\" }, \"./src/env\": { \"import\": \"./dist/src/env.js\", \"require\": \"./dist/src/env.js\" }, \"./src/server\": { \"import\": \"./dist/src/server/index.js\", \"require\": \"./dist/src/server/index.js\" }, \"./src/server/auth/apiKeys\": { \"import\": \"./dist/src/server/auth/apiKeys.js\", \"require\": \"./dist/src/s… 证据：`packages/shared/package.json`\n- **Add Model Price**（skill_instruction）：Use this skill for model pricing changes in worker/ and shared LLM type updates in packages/shared/ . 证据：`.agents/skills/add-model-price/SKILL.md`\n- **Agent Setup Maintenance**（skill_instruction）：Use this skill when changing the shared agent setup for the repository. 证据：`.agents/skills/agent-setup-maintenance/SKILL.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.agents/AGENTS.md`, `.agents/README.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.agents/AGENTS.md`, `.agents/README.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n  - source_paths: README.md, package.json, pnpm-workspace.yaml\n- **仓库结构**：importance `high`\n  - source_paths: turbo.json, docker-compose.yml, pnpm-workspace.yaml\n- **系统架构**：importance `high`\n  - source_paths: packages/shared/src/server/redis/redis.ts, packages/shared/src/server/clickhouse/client.ts, packages/shared/src/db.ts, worker/src/app.ts, web/next.config.mjs\n- **数据库设计**：importance `high`\n  - source_paths: packages/shared/prisma/schema.prisma, packages/shared/clickhouse/migrations/clustered, packages/shared/src/server/repositories, packages/shared/src/tableDefinitions\n- **追踪系统**：importance `high`\n  - source_paths: packages/shared/src/domain/traces.ts, packages/shared/src/domain/observations.ts, packages/shared/src/server/ingestion, packages/shared/src/server/otel, packages/shared/src/server/repositories/traces.ts\n- **提示词管理**：importance `high`\n  - source_paths: packages/shared/src/domain/prompts.ts, packages/shared/src/features/prompts, packages/shared/src/server/services/PromptService, web/src/features/prompts, packages/shared/src/tableDefinitions/promptsTable.ts\n- **评估系统**：importance `high`\n  - source_paths: packages/shared/src/domain/score-configs.ts, packages/shared/src/domain/scores.ts, worker/src/features/evaluation, packages/shared/src/features/scores\n- **数据集管理**：importance `high`\n  - source_paths: packages/shared/src/domain/dataset-items.ts, packages/shared/src/domain/dataset-run-items.ts, packages/shared/src/server/services/DatasetService, web/src/features/datasets, worker/src/features/experiments\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `da8a4f54c92bc5f16415f1a039ca5530aa62298b`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docker-compose.yml`, `packages/eslint-plugin/vitest.config.ts`, `packages/eslint-plugin/vitest.setup.ts`, `packages/eslint-plugin/package.json`, `packages/eslint-plugin/tsconfig.json`, `packages/shared/AGENTS.md`, `packages/shared/package.json`, `packages/shared/tsconfig.json`, `packages/config-typescript/package.json`, `packages/config-typescript/nextjs.json`, `packages/config-typescript/base.json`, `packages/config-eslint/base.js`, `packages/config-eslint/index.js`, `packages/config-eslint/index.d.ts`, `packages/config-eslint/package.json`, `packages/config-eslint/next.d.ts`, `packages/config-eslint/base.d.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：bug: Using client with context manager breaks the scoring\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Using client with context manager breaks the scoring\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5afee24537ba47369cc4621f7fb18122 | https://github.com/langfuse/langfuse/issues/8138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：bug: unnamed trace name in Langfuse UI\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: unnamed trace name in Langfuse UI\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a219c99fe99c4b7dab002e2b3a6296c2 | https://github.com/langfuse/langfuse/issues/13416 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_8657d86702904e90b9d448770e618256 | https://github.com/langfuse/langfuse/issues/8173 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_cff1b1d1a1ca4eb892563c33d3aa62e9 | https://github.com/langfuse/langfuse/issues/8156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_49a69075a1c346789a28db93c9ec6f3f | https://github.com/langfuse/langfuse/issues/13601 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v3.169.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.169.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_864f213fd7694eba9a4d2fe2bb9267ab | https://github.com/langfuse/langfuse/releases/tag/v3.169.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v3.172.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.172.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_14588986ba9945eeb40cbc0508e3fed0 | https://github.com/langfuse/langfuse/releases/tag/v3.172.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v3.173.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.173.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_7560a954846b4f35aedb74de1291c9a4 | https://github.com/langfuse/langfuse/releases/tag/v3.173.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:642497346 | https://github.com/langfuse/langfuse | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
      "summary": "给宿主 AI 的上下文和工作边界。",
      "title": "AI Context Pack / 带给我的 AI"
    },
    "boundary_risk_card": {
      "asset_id": "boundary_risk_card",
      "filename": "BOUNDARY_RISK_CARD.md",
      "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：langfuse/langfuse\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：bug: Using client with context manager breaks the scoring（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：bug: unnamed trace name in Langfuse UI（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/langfuse/langfuse 项目说明书\n\n生成时间：2026-05-14 08:22:55 UTC\n\n## 目录\n\n- [项目介绍](#p-intro)\n- [仓库结构](#p-structure)\n- [系统架构](#p-architecture)\n- [数据库设计](#p-database)\n- [追踪系统](#p-tracing)\n- [提示词管理](#p-prompts)\n- [评估系统](#p-evaluations)\n- [数据集管理](#p-datasets)\n- [队列系统](#p-queues)\n- [API 系统](#p-api)\n\n<a id='p-intro'></a>\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[仓库结构](#p-structure), [系统架构](#p-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n- [web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n- [web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n- [web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)\n- [web/src/features/feature-flags/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/feature-flags/README.md)\n- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n- [web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n</details>\n\n# 项目介绍\n\nLangfuse 是一个开源的 LLM（大型语言模型）可观测性和评估平台，专注于帮助开发团队追踪、监控和优化其 AI 应用的性能与质量。本文档将从项目架构、核心功能模块和技术实现等方面对 Langfuse 进行全面介绍。\n\n## 项目概述\n\nLangfuse 项目采用 **Monorepo**（单体仓库）架构，使用 pnpm 作为包管理器进行多包管理。项目的核心依赖和配置信息集中在根目录的 `package.json` 中定义，通过 pnpm workspace 机制管理多个子项目。资料来源：[package.json:1-50]()\n\n### 技术栈概览\n\nLangfuse 的技术栈涵盖前后端多个层面：\n\n| 层级 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | Next.js / React | Web 应用核心框架 |\n| 包管理器 | pnpm 10.33.0 | 项目依赖管理 |\n| 编程语言 | TypeScript | 全栈 TypeScript 开发 |\n| 后端服务 | Python/Worker | 数据处理和队列管理 |\n| 数据存储 | PostgreSQL, ClickHouse, Redis, S3 | 多样化数据存储方案 |\n| 状态管理 | React Context + Hooks | 前端状态管理 |\n| UI 组件 | Tailwind CSS + CVA | 样式和组件变体 |\n\n```mermaid\ngraph TD\n    A[Langfuse Monorepo] --> B[web/ - 前端应用]\n    A --> C[worker/ - 后端 Worker]\n    A --> D[packages/shared/ - 共享包]\n    B --> E[React Components]\n    B --> F[Feature Modules]\n    C --> G[Queue Processors]\n    C --> H[Data Ingestion]\n    D --> I[Shared Types]\n    D --> J[Validation Schemas]\n```\n\n## 架构设计\n\n### Monorepo 结构\n\nLangfuse 采用 pnpm workspace 实现的 Monorepo 架构，主要包含以下几个核心包：\n\n- **web**: 前端 Next.js 应用，包含 UI 组件系统和业务功能模块\n- **worker**: 后端 Worker 服务，处理数据摄取、队列管理和事件处理\n- **packages/shared**: 前后端共享的类型定义、验证模式和业务接口\n\n资料来源：[package.json:20-40]()\n\n### 前端架构分层\n\n前端代码遵循清晰的分层设计原则：\n\n```mermaid\ngraph TB\n    subgraph web/src/components\n        A[layouts/ - 页面布局组件]\n        B[design-system/ - 基础设计系统]\n        C[ui/ - 通用 UI 组件]\n        D[table/ - 表格组件]\n    end\n    \n    subgraph web/src/features\n        E[entitlements/ - 权限系统]\n        F[feature-flags/ - 功能开关]\n        G[mcp/ - MCP 服务器]\n        H[score-analytics/ - 分数分析]\n        I[filters/ - 过滤器系统]\n        J[comments/ - 评论功能]\n    end\n    \n    A --> B\n    B --> C\n    D --> C\n    E --> F\n```\n\n#### 布局系统 (layouts)\n\n`Page` 组件是所有页面的标准包装器，确保应用具有一致的布局、粘性头部和适当的滚动行为。所有页面必须包装在 `<Page>` 组件内，不能直接使用 `<main>` 元素。\n\n关键特性：\n- 封装的粘性头部 - 防止布局不一致\n- 滚动管理 - 支持 \"content-scroll\" 和 \"page-scroll\" 两种模式\n- 标准化的内边距和布局\n- 面包屑导航支持\n- 自定义头部操作区域\n\n资料来源：[web/src/components/layouts/README.md:1-30]()\n\n#### 设计系统 (design-system)\n\n设计系统文件夹包含**可复用的、原始的、展示性质的 UI 组件**。设计原则如下：\n\n| 原则 | 说明 |\n|------|------|\n| 纯展示性 | 不包含业务逻辑 |\n| 显式类型 | 使用严格的 TypeScript 类型定义 |\n| 一致性优先 | 优先考虑一致性而非灵活性 |\n| Props 优先 | 使用 Props 而非 React Context |\n\n**组件规范**：\n- 一个组件一个文件\n- 使用 CVA (Class Variance Authority) 管理变体\n- 使用显式枚举定义尺寸和变体类型\n- 布尔属性使用 `is`/`should` 前缀命名\n\n资料来源：[web/src/components/design-system/README.md:1-50]()\n\n## 核心功能模块\n\n### 权限系统 (entitlements)\n\nEntitlements 系统用于控制功能的可用性，基于组织 (organization) 级别进行管理。\n\n核心概念：\n- **Plan（套餐）**: 功能层级的划分，如 `oss`、`cloud:pro`、`self-hosted:enterprise`\n- **Entitlement（权限）**: 用户可用的功能特性，如 `playground`\n- **EntitlementLimit（权限限制）**: 资源数量限制，如 `annotation-queue-count`\n\n权限使用方式：\n| 使用场景 | 实现方式 |\n|----------|----------|\n| 客户端 | React Hooks (`hooks.ts`) |\n| 服务端 | `hasEntitlement.ts` / `hasOrganizationEntitlement` |\n\n资料来源：[web/src/features/entitlements/README.md:1-35]()\n\n### 功能开关 (feature-flags)\n\nFeature Flags 允许在运行时动态控制功能启用状态。\n\n功能开关启用条件（满足任一即可）：\n1. 用户在 `user.feature_flags` 中包含该标志\n2. 环境变量 `LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES` 被设置\n3. 用户具有管理员权限 (`user.admin === true`)\n\n```typescript\nconst isFeatureEnabled = useIsFeatureEnabled(\"feature-flag-name\");\n```\n\n资料来源：[web/src/features/feature-flags/README.md:1-15]()\n\n### MCP 服务器 (mcp)\n\nLangfuse MCP 服务器提供了 6 个 Prompt 管理工具，采用**无状态按请求架构**：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `getPrompt` | 获取完全解析的 Prompt（包含依赖替换） |\n| `getPromptUnresolved` | 获取原始 Prompt（保留依赖标签） |\n| `listPrompts` | 列出项目中所有 Prompt |\n| `createTextPrompt` | 创建新的文本 Prompt 版本 |\n| `createChatPrompt` | 创建新的聊天 Prompt 版本 |\n| `updatePromptLabels` | 更新 Prompt 标签 |\n\n**架构特点**：\n- 每个 MCP 请求创建新的服务器实例\n- 认证上下文通过闭包捕获\n- 请求完成后服务器被丢弃\n- 请求间无状态共享\n\n```mermaid\ngraph LR\n    A[MCP Client] -->|Request| B[New Server Instance]\n    B --> C[Handler with Auth Closure]\n    C --> D[Process Request]\n    D --> E[Return Response]\n    E --> F[Discard Server]\n```\n\n资料来源：[web/src/features/mcp/README.md:1-80]()\n\n### 分数分析 (score-analytics)\n\n分数分析模块提供数据分析和可视化功能。\n\n#### 关键组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `ScoreAnalyticsProvider` | ScoreAnalyticsProvider.tsx | 上下文提供者，管理数据状态 |\n| `useScoreAnalyticsQuery` | useScoreAnalyticsQuery.ts | 数据获取和转换 |\n\n#### 数据转换管道\n\n```\nAPI Response → Extract Categories → Fill Distribution Bins → \nGenerate Bin Labels → Transform Heatmap → Calculate Mode Metrics →\nFill Time Series Gaps → Namespace Categorical → Final Output\n```\n\n#### 统计分析工具\n\n`s statistics-utils.ts` 提供了多种统计分析函数：\n\n| 函数 | 功能 | 输出 |\n|------|------|------|\n| `interpretAgreement` | 解释一致性指标 | Strength + Color + Description |\n| `interpretMAE` | 解释平均绝对误差 | 相对误差分析 |\n\n资料来源：[web/src/features/score-analytics/README.md:1-60]()\n\n### 分数接口系统 (scores/interfaces)\n\n分数接口定义了完整的类型系统，支持多版本 API。\n\n#### API 版本支持\n\n| API 版本 | traceId 要求 | 支持范围 |\n|----------|-------------|----------|\n| v1 | 必需 | 仅 Trace 级别分数 |\n| v2 | 可选 | Trace + Session |\n\n#### 接口目录结构\n\n```\ninterfaces/\n├── api/\n│   ├── v1/        # 遗留 API 类型\n│   ├── v2/        # 当前 API 类型\n│   └── shared.ts  # 共享模式\n├── application/   # 应用层验证\n├── ingestion/     # 摄取类型\n└── ui/            # UI 专用类型\n```\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md:1-40]()\n\n### 过滤器系统 (filters)\n\n过滤器系统提供灵活的查询条件编码和解码功能。\n\n**支持的过滤类型**：\n\n| 类型 | 编码方式 | 说明 |\n|------|----------|------|\n| `datetime` | Date 对象 | 时间范围过滤 |\n| `number` | Number | 数值比较 |\n| `stringOptions` | 管道分隔数组 | 字符串选项 |\n| `arrayOptions` | 数组 | 数组匹配 |\n| `boolean` | true/false | 布尔过滤 |\n| `categoryOptions` | 分类选项 | 分类过滤 |\n| `positionInTrace` | 位置索引 | Trace 内位置 |\n\n资料来源：[web/src/features/filters/lib/filter-query-encoding.ts:1-50]()\n\n### 表格 peek 功能 (table/peek)\n\nPeekTable 系统允许在侧边栏中预览和查看表格数据，与主表格保持状态同步。\n\n**关键 Hook**：\n\n| Hook | 用途 |\n|------|------|\n| `usePeekTableState` | 管理 peek 上下文状态 |\n| `useSidebarFilterState` | 过滤器状态管理 |\n| `useOrderByState` | 排序状态管理 |\n\n**状态位置优先级**：\n1. Peek Context（peek 上下文）\n2. URL & Session Storage（URL 和会话存储）\n\n资料来源：[web/src/components/table/peek/README.md:1-50]()\n\n### 高级 JSON 查看器 (ui/AdvancedJsonViewer)\n\n用于可视化大型 JSON 数据的组件，具备以下能力：\n\n| 特性 | 说明 |\n|------|------|\n| 虚拟化渲染 | 使用 TanStack Virtual 处理大数据集 |\n| 迭代遍历 | 使用显式栈避免递归栈溢出 |\n| 客户端搜索 | 内存内匹配计算 |\n| 调试模式 | 通过 localStorage 启用详细日志 |\n\n**算法特点**：\n- 所有树操作使用**显式基于栈的迭代**而非递归\n- 支持深度 1000+ 的树结构安全遍历\n- 二进制搜索优化 `getNodeByIndex` 性能\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md:1-80]()\n\n### 评论提及功能 (comments/mentionParser)\n\n支持用户提及功能的解析和处理。\n\n**提及格式**：`@[DisplayName](user:userId)`\n\n**核心函数**：\n\n| 函数 | 作用 |\n|------|------|\n| `extractUniqueMentionedUserIds` | 从文本中提取所有被提及的用户 ID |\n| `sanitizeMentions` | 清理和验证提及内容 |\n| `MENTION_USER_PREFIX` | 常量 `\"user:\"` |\n\n资料来源：[web/src/features/comments/lib/mentionParser.clienttest.ts:1-30]()\n\n## 后端 Worker 系统\n\n### 事件重放脚本 (replayIngestionEventsV2)\n\n用于将历史事件重新摄取到系统的工具脚本。\n\n**主要功能**：\n- 从 S3 读取历史事件\n- 通过 HTTP POST 发送到 Langfuse Host\n- 支持检查点恢复\n- 内置速率限制和重试机制\n\n**事件键格式**：\n\n| 类型 | 格式 | 目标队列 |\n|------|------|----------|\n| 标准键 | `{projectId}/{type}/{eventBodyId}/{eventId}.json` | IngestionSecondaryQueue |\n| OTEL 键 | `otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json` | OtelIngestionQueue |\n\n**状态码处理**：\n\n| 状态码 | 含义 | 处理方式 |\n|--------|------|----------|\n| 200 | 批次接受 | 检查 skipped/errors |\n| 401 | 认证失败 | 停止处理 |\n| 400 | 请求格式错误 | 跳过并记录 |\n| 429 | 速率限制 | 指数退避重试 |\n\n**v1 vs v2 差异**：\n\n| 特性 | v1 | v2 |\n|------|----|----|\n| 基础设施访问 | Redis, ClickHouse, PostgreSQL, S3 | 仅 Langfuse Host URL |\n| 事件传递 | 直接 BullMQ addBulk | HTTP POST 到 Admin API |\n| 恢复支持 | 手动分割文件 | 内置检查点/恢复 |\n| 速率限制 | 无 | 客户端+服务端双重限制 |\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md:1-120]()\n\n### 队列填充脚本 (refillQueueEvent)\n\n用于从本地机器回填队列事件的实用工具脚本。\n\n**使用流程**：\n1. 创建 `./worker/events.jsonl` 文件\n2. 配置 `.env` 环境变量\n3. 确保 Redis 连接可达\n4. 执行 `pnpm run --filter=worker refill-queue-event`\n\n**环境变量要求**：\n```bash\nREDIS_CONNECTION_STRING=redis://:myredissecret@127.0.0.1:6379\nLANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse\nCLICKHOUSE_URL=http://localhost:8123\nCLICKHOUSE_USER=clickhouse\nCLICKHOUSE_PASSWORD=clickhouse\n```\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md:1-50]()\n\n## 依赖管理\n\n### pnpm Overrides\n\n项目使用 pnpm overrides 强制管理依赖版本：\n\n| 依赖包 | 锁定版本 | 备注 |\n|--------|----------|------|\n| zod | 4.3.6 | 数据验证库 |\n| nanoid | ^3.3.8 | ID 生成 |\n| katex | ^0.16.21 | 数学渲染 |\n| rollup | ^4.22.4 | 打包工具 |\n| @types/react-dom | 19.2.3 | React 类型 |\n| qs | 6.14.1 | 查询字符串解析 |\n| glob | ^10.5.0 | 文件匹配 |\n\n资料来源：[package.json:55-75]()\n\n## 总结\n\nLangfuse 是一个功能完备的 LLM 可观测性平台，其架构设计体现了以下特点：\n\n1. **Monorepo 组织**：通过 pnpm workspace 高效管理多个相关包\n2. **清晰的分层**：前端组件与业务逻辑分离，设计系统独立维护\n3. **多版本 API 支持**：v1/v2 API 并存，保证向后兼容\n4. **灵活的扩展机制**：Feature Flags 和 Entitlements 支持动态功能控制\n5. **完善的工具链**：事件重放、队列填充等运维工具完备\n\n该平台适用于需要追踪 AI 应用行为、评估模型性能、管理 Prompt 版本的开发团队。\n\n---\n\n<a id='p-structure'></a>\n\n## 仓库结构\n\n### 相关页面\n\n相关主题：[项目介绍](#p-intro), [系统架构](#p-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n- [web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)\n- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n- [worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n- [package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n- [web/src/components/table/peek/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/table/peek/README.md)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n- [web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)\n- [web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n- [web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n</details>\n\n# 仓库结构\n\n## 概述\n\nLangfuse 是一个开源的 LLMOps 平台，采用 Monorepo（单体仓库）架构进行项目管理。整个仓库包含多个子项目，通过 pnpm workspace 进行统一管理和协调。资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n该架构的核心设计目标是：\n\n- **代码共享**：在多个包之间共享类型定义、工具函数和业务逻辑\n- **统一版本管理**：所有子项目保持一致的依赖版本\n- **简化开发流程**：一次安装即可配置好所有开发环境\n\nLangfuse 的主要子系统包括：\n\n| 子系统 | 描述 |\n|--------|------|\n| **web** | Next.js 前端应用，提供用户界面 |\n| **worker** | 后台任务处理器，处理数据摄入和异步任务 |\n| **packages/shared** | 共享包，包含类型定义和跨模块复用代码 |\n\n资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n---\n\n## 项目架构总览\n\nLangfuse 采用分层架构，各层之间职责清晰、边界明确：\n\n```mermaid\ngraph TD\n    A[用户界面层<br/>web/src] --> B[业务功能层<br/>web/src/features]\n    B --> C[共享组件层<br/>web/src/components]\n    C --> D[设计系统层<br/>design-system]\n    A --> E[packages/shared]\n    F[后台处理层<br/>worker/src] --> E\n    G[脚本工具层<br/>worker/src/scripts] --> F\n```\n\n资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n\n---\n\n## Web 前端模块\n\nWeb 模块是 Langfuse 的用户界面层，基于 Next.js 框架构建。它采用模块化组织，将功能代码按领域进行划分。\n\n### 目录结构概览\n\n```\nweb/src/\n├── components/          # UI 组件库\n│   ├── layouts/        # 页面布局组件\n│   ├── ui/             # 基础 UI 组件\n│   ├── table/          # 表格相关组件\n│   └── design-system/  # 设计系统\n├── features/           # 功能模块\n└── ...\n```\n\n资料来源：[web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n\n### 页面布局组件\n\n`Page` 组件是所有页面的标准包装器，确保应用具有一致的布局、粘性头部和正确的滚动行为。\n\n```tsx\nimport Page from \"@/src/components/layouts/Page\";\n\nexport default function MyPage() {\n  return (\n    <Page\n      title=\"My Page\"\n      scrollable\n      headerProps={{\n        breadcrumb: [{ name: \"Home\", href: \"/\" }, { name: \"My Page\" }],\n        actionButtons: <button className=\"btn-primary\">Save</button>,\n      }}\n    >\n      <div>My page content here...</div>\n    </Page>\n  );\n}\n```\n\n资料来源：[web/src/components/layouts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/layouts/README.md)\n\n**重要约束**：\n\n- ⚠️ 每个页面都必须包装在 `<Page>` 内，切勿直接使用 `<main>`\n- 当内容无法良好适应页面宽度时，应使用 `ContainerPage` 组件\n\n### 设计系统\n\n设计系统位于 `web/src/components/design-system/`，包含可复用的基础 UI 组件。\n\n#### 组件设计原则\n\n| 原则 | 说明 |\n|------|------|\n| 仅展示性质 | 不包含业务逻辑 |\n| 显式类型 API | 使用严格的 TypeScript 类型定义 |\n| 一致性优先 | 优先考虑一致性而非灵活性 |\n| Props 优于 Context | 避免使用 React Context |\n\n资料来源：[web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n\n#### 目录结构\n\n```\ndesign-system/\n  Button/\n    Button.tsx\n    Button.stories.tsx\n```\n\n#### 样式与变体规范\n\n- ❌ 禁止使用 `className` 或 `style` props\n- ❌ 禁止使用任意值（如 `#fff`、`12px`）\n- ✅ 使用显式枚举\n\n```ts\nsize: \"sm\" | \"md\" | \"lg\";\nvariant: \"primary\" | \"secondary\";\n```\n\n#### Props 命名约定\n\n| 类型 | 命名方式 |\n|------|----------|\n| 布尔属性 | `isLoading`、`shouldTruncate` |\n| 互斥属性 | 使用正向命名：`suffix={null}` |\n\n资料来源：[web/src/components/design-system/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/design-system/README.md)\n\n### 高级 JSON 查看器\n\n位于 `web/src/components/ui/AdvancedJsonViewer/`，提供虚拟化的大 JSON 数据展示能力。\n\n#### 已知限制\n\n| 限制 | 说明 |\n|------|------|\n| 无水平虚拟化 | 换行模式下会完全渲染所有宽行 |\n| 仅客户端搜索 | 所有匹配在内存中计算 |\n| 内存约束 | 100万+ 节点可能导致问题 |\n| 只读查看器 | 不支持内联编辑 |\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)\n\n#### 算法设计\n\n所有树操作使用显式基于栈的迭代而非递归：\n\n```typescript\n// ❌ 递归（深度 1000+ 可能栈溢出）\nfunction traverse(node: TreeNode) {\n  process(node);\n  node.children.forEach((child) => traverse(child));\n}\n\n// ✅ 迭代（任意深度都安全）\nfunction traverse(rootNode: TreeNode) {\n  const stack = [rootNode];\n  while (stack.length > 0) {\n    const node = stack.pop()!;\n    process(node);\n    node.children.forEach((child) => stack.push(child));\n  }\n}\n```\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)\n\n### 表格 Peek 功能\n\n`peek` 模块位于 `web/src/components/table/peek/`，支持在侧边栏中预览表格数据。\n\n#### Peek 感知状态管理\n\n| Hook | 用途 |\n|------|------|\n| `useTextSearch` | 文本搜索 |\n| `useSidebarFilterState` | 过滤器状态 |\n| `useOrderByState` | 排序状态 |\n\n资料来源：[web/src/components/table/peek/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/table/peek/README.md)\n\n---\n\n## 功能模块（Features）\n\n`web/src/features/` 目录包含各业务领域的功能实现。\n\n### Public API 模块\n\nPublic API 提供了外部访问 Langfuse 功能的接口。\n\n#### 新增 API 路由的流程\n\n| 步骤 | 操作 |\n|------|------|\n| 1 | 使用 `withMiddleware` 包装 |\n| 2 | 使用 `createAuthedAPIRoute` 创建类型安全的路由 |\n| 3 | 在 `/features/public-api/types` 添加 Zod 类型 |\n| 4 | 使用 `strict()` 定义响应对象 |\n| 5 | 抛出 `shared/src/errors` 中定义的错误 |\n| 6 | 使用 `makeZodVerifiedAPICall` 进行测试 |\n\n资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n\n### MCP 服务器模块\n\nMCP（Model Context Protocol）服务器位于 `web/src/features/mcp/`，提供提示词管理功能。\n\n#### 架构特点\n\n| 特点 | 说明 |\n|------|------|\n| 无状态设计 | 每个请求创建新的服务器实例 |\n| 闭包捕获上下文 | 认证上下文在处理函数闭包中捕获 |\n| 无会话存储 | 请求完成后服务器被丢弃 |\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n#### 可用工具\n\n| 工具 | 功能 |\n|------|------|\n| `getPrompt` | 获取已解析的提示词（含依赖替换） |\n| `getPromptUnresolved` | 获取未解析的提示词（保留原始标签） |\n| `listPrompts` | 列出所有提示词（支持过滤和分页） |\n| `createTextPrompt` | 创建文本提示词版本 |\n| `createChatPrompt` | 创建聊天提示词版本 |\n| `updatePromptLabels` | 更新提示词标签 |\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n#### 提示词解析示例\n\n```\n输入: \"You are helpful. @@@langfusePrompt:name=base-rules|label=production@@@\"\n输出: \"You are helpful. Always be kind and respectful.\"\n```\n\n### Entitlements 模块\n\n位于 `web/src/features/entitlements/`，用于控制功能可用性。\n\n#### 核心概念\n\n| 概念 | 说明 |\n|------|------|\n| **Plan** | 功能层级，如 `oss`、`cloud:pro`、`self-hosted:enterprise` |\n| **Entitlement** | 可用功能，如 `playground` |\n| **EntitlementLimit** | 资源限制，如 `annotation-queue-count` |\n\n资料来源：[web/src/features/entitlements/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/entitlements/README.md)\n\n#### Plan 的管理方式\n\n| 环境 | 管理方式 |\n|------|----------|\n| Cloud | 通过 NextAuth 添加到 JWT 的 organization 对象 |\n| Self-hosted | 通过 NextAuth 添加到 JWT 的 `environment.selfHostedInstancePlan` |\n\n---\n\n## 共享包（packages/shared）\n\n`packages/shared` 包含跨模块复用的类型定义和工具函数。\n\n### Score 接口\n\n位于 `packages/shared/src/features/scores/interfaces/`，定义分数相关的类型和验证逻辑。\n\n#### 目录结构\n\n```\ninterfaces/\n├── api/              # API 相关类型\n│   ├── v1/           # 遗留 API 类型（仅 trace）\n│   ├── v2/           # 当前 API 类型（支持 trace、session）\n│   └── shared.ts     # 通用类型\n├── application/      # 应用层验证\n├── ingestion/        # 数据摄入类型\n└── ui/               # UI 组件类型\n```\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n#### API 版本差异\n\n| 操作 | V1 API | V2 API |\n|------|--------|--------|\n| GET | 需要 `traceId`，仅支持 trace 级分数 | `traceId` 可选，支持 `sessionId` |\n| POST/DELETE | 支持所有类型 | 支持所有类型 |\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## Worker 后台处理模块\n\n`worker` 模块负责处理后台任务，包括数据摄入和异步任务执行。\n\n### 脚本工具\n\n位于 `worker/src/scripts/`，提供数据处理和队列管理工具。\n\n#### Replay Ingestion Events V2\n\n用于重放 S3 中的摄入事件到 Langfuse。\n\n**事件转换规则**：\n\n| 事件类型 | 键格式 | 目标队列 |\n|----------|--------|----------|\n| 标准事件 | `{projectId}/{type}/{eventBodyId}/{eventId}.json` | IngestionSecondaryQueue |\n| OTEL 事件 | `otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json` | OtelIngestionQueue |\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n#### Refill Queue Event\n\n用于从本地机器回填队列事件。\n\n**环境要求**：\n\n| 变量 | 说明 |\n|------|------|\n| `REDIS_CONNECTION_STRING` | Redis 连接字符串 |\n| `CLICKHOUSE_URL` | ClickHouse 服务器地址 |\n| `LANGFUSE_S3_EVENT_UPLOAD_BUCKET` | S3 存储桶名称 |\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n\n---\n\n## 依赖管理\n\n### pnpm Workspace 配置\n\nLangfuse 使用 pnpm workspace 管理多包项目，通过 `package.json` 中的 `pnpm` 配置进行全局依赖覆盖。\n\n```json\n{\n  \"pnpm\": {\n    \"overrides\": {\n      \"zod\": \"4.3.6\",\n      \"nanoid\": \"^3.3.8\",\n      \"katex\": \"^0.16.21\",\n      \"tar-fs\": \"^2.1.2\",\n      \"rollup@^4.0.0\": \"^4.22.4\"\n    }\n  }\n}\n```\n\n资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n### 包管理器版本\n\nLangfuse 使用 `pnpm@10.33.0` 作为包管理器。\n\n资料来源：[package.json](https://github.com/langfuse/langfuse/blob/main/package.json)\n\n---\n\n## 技术栈总结\n\n```mermaid\ngraph LR\n    subgraph \"前端层\"\n        A[Next.js]\n        B[React]\n        C[Tailwind CSS]\n    end\n    \n    subgraph \"后端层\"\n        D[Worker]\n        E[BullMQ]\n        F[Redis]\n    end\n    \n    subgraph \"数据层\"\n        G[ClickHouse]\n        H[S3 Storage]\n        I[PostgreSQL]\n    end\n    \n    A --> G\n    A --> I\n    D --> E\n    E --> F\n    D --> G\n    D --> H\n```\n\n---\n\n## 开发指南\n\n### 添加新功能模块\n\n1. 在 `web/src/features/` 下创建新模块目录\n2. 在 `web/src/components/design-system/` 中添设计系统组件\n3. 在 `packages/shared` 中添加共享类型定义\n4. 更新 API 路由时使用标准流程\n\n资料来源：[web/src/features/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/README.md)\n\n### 运行测试\n\n```bash\n# 运行前端测试\npnpm --filter=web run test-client --testPathPattern=\"AdvancedJsonViewer\"\n\n# 运行工作线程脚本\npnpm run --filter=worker refill-queue-event\n```\n\n资料来源：[web/src/components/ui/AdvancedJsonViewer/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/components/ui/AdvancedJsonViewer/README.md)、[worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n\n---\n\n<a id='p-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[数据库设计](#p-database), [队列系统](#p-queues), [仓库结构](#p-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/server/redis/redis.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/redis.ts)\n- [packages/shared/src/server/clickhouse/client.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/clickhouse/client.ts)\n- [packages/shared/src/db.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/db.ts)\n- [worker/src/app.ts](https://github.com/langfuse/langfuse/blob/main/worker/src/app.ts)\n- [web/next.config.mjs](https://github.com/langfuse/langfuse/blob/main/web/next.config.mjs)\n</details>\n\n# 系统架构\n\n## 概述\n\nLangfuse 是一个开源的 LLM 工程平台，采用分布式微服务架构设计。系统由多个核心组件构成，包括 Web 前端服务、Worker 后台处理服务、数据存储层和缓存层。这种架构设计实现了前端展示与后端处理的分离，保证了系统的高可用性和可扩展性。\n\nLangfuse 的技术栈涵盖了现代 Web 开发的多个层面：使用 Next.js 构建前端应用、使用 BullMQ 与 Redis 实现异步任务队列、使用 PostgreSQL 存储核心业务数据、使用 ClickHouse 处理分析查询、使用 S3 兼容存储管理事件文件。\n\n## 核心架构组件\n\n### 整体架构图\n\n```mermaid\ngraph TB\n    subgraph Client[\"客户端层\"]\n        Web[Web 前端<br/>Next.js]\n    end\n\n    subgraph API[\"API 层\"]\n        TRPC[tRPC API]\n    end\n\n    subgraph Worker[\"Worker 层\"]\n        Queue[BullMQ 队列]\n        Worker[Worker 进程]\n    end\n\n    subgraph Storage[\"存储层\"]\n        Redis[(Redis<br/>队列/缓存)]\n        Postgres[(PostgreSQL<br/>核心数据)]\n        ClickHouse[(ClickHouse<br/>分析数据)]\n        S3[(S3 存储<br/>事件文件)]\n    end\n\n    Web --> TRPC\n    TRPC --> Postgres\n    TRPC --> Redis\n    TRPC --> ClickHouse\n    TRPC --> S3\n    Queue --> Redis\n    Worker --> Queue\n    Worker --> Postgres\n    Worker --> ClickHouse\n    Worker --> Redis\n    Worker --> S3\n```\n\n### 技术栈概览\n\n| 组件 | 技术选型 | 用途 |\n|------|----------|------|\n| 前端框架 | Next.js | 用户界面和服务端渲染 |\n| API 层 | tRPC | 类型安全的 API 调用 |\n| 后台任务 | BullMQ + Worker | 异步任务处理 |\n| 主数据库 | PostgreSQL | 业务数据持久化 |\n| 分析数据库 | ClickHouse | OLAP 查询和分析 |\n| 缓存/队列 | Redis | 缓存、限流、队列 |\n| 对象存储 | S3 兼容 | 事件文件存储 |\n\n## Web 前端服务\n\n### Next.js 应用架构\n\nWeb 前端基于 Next.js 框架构建，采用 App Router 架构进行路由管理。前端服务负责用户交互界面、数据展示和 API 调用。\n\nWeb 前端的源码位于 `web/` 目录，其核心配置文件包括 Next.js 配置和应用程序入口点。\n\n```mermaid\ngraph LR\n    subgraph Web[\"Web 服务\"]\n        Next[Next.js App]\n        Config[next.config.mjs]\n        Components[React 组件]\n        Features[Feature 模块]\n    end\n\n    subgraph API[\"后端通信\"]\n        TRPC[tRPC Client]\n        HTTP[REST API]\n    end\n\n    Next --> Components\n    Next --> Features\n    Components --> TRPC\n    Features --> TRPC\n    TRPC --> HTTP\n```\n\n前端采用模块化设计，将功能划分为独立的 Feature 目录，例如：\n\n- `features/prompts` - 提示词管理\n- `features/score-analytics` - 评分分析\n- `features/filters` - 过滤功能\n- `features/mcp` - MCP 服务器集成\n- `features/comments` - 评论功能\n- `features/entitlements` - 权限控制\n\n## Worker 后台服务\n\n### Worker 应用架构\n\nWorker 服务是 Langfuse 的后台任务处理核心，负责处理异步任务，包括数据摄入、队列管理和事件处理。\n\nWorker 的主入口文件位于 `worker/src/app.ts`，该文件初始化 Worker 应用并注册各种处理器。\n\n```mermaid\ngraph TB\n    subgraph WorkerApp[\"Worker 应用\"]\n        Init[应用初始化]\n        QueueProcessors[队列处理器]\n        Schedulers[定时任务]\n    end\n\n    subgraph Queues[\"队列系统\"]\n        IngestionQueue[摄入队列]\n        OtelQueue[OTEL 队列]\n        SecondaryQueue[二级处理队列]\n    end\n\n    Init --> QueueProcessors\n    QueueProcessors --> IngestionQueue\n    QueueProcessors --> OtelQueue\n    QueueProcessors --> SecondaryQueue\n```\n\n### 队列系统\n\nLangfuse 使用 BullMQ 实现任务队列，支持多种队列类型：\n\n| 队列名称 | 用途 | 数据来源 |\n|----------|------|----------|\n| IngestionQueue | 事件摄入处理 | S3 文件 |\n| OtelIngestionQueue | OpenTelemetry 数据摄入 | OTEL 格式文件 |\n| IngestionSecondaryQueue | 二次处理队列 | 内部触发 |\n| ScoreCalculationQueue | 评分计算 | 异步计算任务 |\n\n### Worker 数据处理流程\n\n```mermaid\ngraph TD\n    A[接收 HTTP 请求] --> B[验证请求参数]\n    B --> C{请求类型}\n    C -->|admin API| D[写入队列]\n    C -->|普通请求| E[直接处理]\n    D --> F[Worker 获取任务]\n    F --> G[读取 S3 文件]\n    G --> H[解析事件数据]\n    H --> I[数据转换]\n    I --> J[写入 PostgreSQL]\n    J --> K[写入 ClickHouse]\n    K --> L[任务完成]\n    E --> L\n```\n\nWorker 服务实现了无状态架构设计：每个 MCP 请求创建新的服务器实例，认证上下文通过闭包捕获，请求完成后服务器被丢弃，任务处理器之间无共享状态。\n\n## 数据存储层\n\n### PostgreSQL 数据库\n\nPostgreSQL 作为 Langfuse 的主数据库，存储所有核心业务数据，包括用户信息、项目配置、提示词版本、追踪记录等。\n\n数据库连接通过 `packages/shared/src/db.ts` 中的 Prisma Client 实现，该模块提供统一的数据库访问接口。\n\n```mermaid\ngraph TB\n    subgraph Postgres[(PostgreSQL)]\n        Users[用户表]\n        Projects[项目表]\n        Prompts[提示词表]\n        Traces[追踪表]\n        Scores[评分表]\n    end\n\n    subgraph Tables[\"核心数据表\"]\n        Organizations[组织表]\n        Members[成员表]\n        Datasets[数据集表]\n    end\n```\n\n### ClickHouse 分析数据库\n\nClickHouse 是 Langfuse 的分析查询引擎，专门用于处理大规模追踪数据的 OLAP 查询。分析功能包括评分趋势分析、热力图生成、时间序列聚合等。\n\nClickHouse 客户端配置位于 `packages/shared/src/server/clickhouse/client.ts`，该模块初始化 ClickHouse 连接并提供查询接口。\n\n| 功能模块 | 数据表 | 用途 |\n|----------|--------|------|\n| score-analytics | 评分数据表 | 评分统计和分析 |\n| traces | 追踪事件表 | 追踪数据分析 |\n| observations | 观察数据表 | LLM 调用分析 |\n\n### Redis 缓存与队列\n\nRedis 在 Langfuse 架构中承担多重职责：作为任务队列的后端存储、实现 API 限流、提供数据缓存加速查询。\n\nRedis 客户端配置位于 `packages/shared/src/server/redis/redis.ts`，该模块封装了 Redis 连接管理和常用操作。\n\n```mermaid\ngraph LR\n    subgraph Redis[(Redis)]\n        Queues[BullMQ 队列]\n        Cache[数据缓存]\n        RateLimit[限流控制]\n        Locks[分布式锁]\n    end\n\n    subgraph CacheKeys[\"缓存键结构\"]\n        PromptCache[prompt:{projectId}:{name}:{version}]\n        SessionCache[session:{sessionId}]\n    end\n\n    Redis --> Queues\n    Redis --> Cache\n    Redis --> RateLimit\n    Redis --> Locks\n```\n\n### S3 对象存储\n\nS3 存储用于保存原始事件文件，包括追踪事件、OTEL 数据和大型 JSON 对象。Worker 服务从 S3 读取事件文件进行处理，处理后的结构化数据存入 PostgreSQL 和 ClickHouse。\n\n事件文件存储路径遵循特定格式：`{projectId}/{type}/{eventBodyId}/{eventId}.json`，便于快速定位和检索。\n\n## 服务间通信\n\n### tRPC API 调用\n\nWeb 前端与后端服务通过 tRPC 进行类型安全的 API 通信。tRPC 提供了端到端的类型推断，减少了前后端接口不匹配的问题。\n\nAPI 路由定义采用模块化结构，每个 Feature 拥有独立的 Router 文件，例如：\n\n- `scoreAnalyticsRouter` - 评分分析 API\n- `promptRouter` - 提示词管理 API\n- `traceRouter` - 追踪数据 API\n\n### 缓存策略\n\nLangfuse 实现了多级缓存策略以提升系统性能：\n\n1. **Redis 缓存层**：提示词内容缓存，避免重复查询数据库\n2. **TTK 重置机制**：缓存条目被访问时自动重置 TTL\n3. **写时失效**：数据更新时清除相关缓存条目\n\n缓存键结构示例：`prompt:<project-id>:<prompt-name>:<version-or-label>`\n\n```mermaid\ngraph TD\n    A[读取请求] --> B{检查 Redis 锁}\n    B -->|有锁| C[等待或降级]\n    B -->|无锁| D{检查缓存}\n    D -->|命中| E[返回缓存数据]\n    D -->|未命中| F[查询 PostgreSQL]\n    F --> G[写入 Redis]\n    G --> H[返回数据]\n    E --> I[重置 TTL]\n```\n\n## 权限与认证\n\n### 组织级权限模型\n\nLangfuse 采用组织级权限管理模型，权限通过 Plan 和 Entitlement 两层机制控制。\n\n| 概念 | 定义 | 管理位置 |\n|------|------|----------|\n| Plan | 功能等级，如 oss、cloud:pro、self-hosted:enterprise | plans.ts |\n| Entitlement | 具体功能，如 playground、annotation-queue-count | entitlements.ts |\n| EntitlementLimit | 资源数量限制 | entitlements.ts |\n\nPlan 信息通过以下方式获取：\n\n- Cloud 版本：通过 NextAuth JWT 获取\n- Self-hosted：通过环境变量或许可证密钥获取\n\n### 权限检查流程\n\n```mermaid\ngraph TB\n    A[请求进入] --> B{获取 Organization}\n    B --> C{检查 JWT 中的 Plan}\n    C -->|Cloud| D[使用 cloudConfig]\n    C -->|Self-hosted| E[检查许可证]\n    D --> F[加载 Entitlements]\n    E --> F\n    F --> G{验证功能权限}\n    G -->|通过| H[处理请求]\n    G -->|拒绝| I[返回 403]\n```\n\n## 部署架构\n\n### 服务组件关系\n\n```mermaid\ngraph TB\n    subgraph Deployment[\"部署拓扑\"]\n        Web[Web 服务<br/>Next.js]\n        API[API 服务]\n        Worker1[Worker 实例 1]\n        Worker2[Worker 实例 2]\n        WorkerN[Worker 实例 N]\n    end\n\n    subgraph Shared[\"共享服务\"]\n        Redis[(Redis Cluster)]\n        Postgres[(PostgreSQL)]\n        ClickHouse[(ClickHouse)]\n        S3[(S3 兼容存储)]\n    end\n\n    Web --> API\n    API --> Redis\n    API --> Postgres\n    API --> ClickHouse\n    API --> S3\n    Worker1 --> Redis\n    Worker2 --> Redis\n    WorkerN --> Redis\n    Worker1 --> Postgres\n    Worker2 --> Postgres\n    WorkerN --> Postgres\n    Worker1 --> ClickHouse\n    Worker2 --> ClickHouse\n    Worker1 --> S3\n    Worker2 --> S3\n```\n\n### 环境配置\n\n主要环境变量配置项：\n\n| 变量名 | 用途 | 示例值 |\n|--------|------|--------|\n| DATABASE_URL | PostgreSQL 连接 | postgresql://user:pass@host:5432/db |\n| REDIS_CONNECTION_STRING | Redis 连接 | redis://:secret@host:6379 |\n| CLICKHOUSE_URL | ClickHouse 连接 | http://localhost:8123 |\n| LANGFUSE_S3_EVENT_UPLOAD_BUCKET | S3 存储桶 | langfuse-events |\n\n## 源码文件引用\n\n本文档基于以下核心源码文件编写：\n\n- `packages/shared/src/server/redis/redis.ts` - Redis 客户端封装\n- `packages/shared/src/server/clickhouse/client.ts` - ClickHouse 连接配置\n- `packages/shared/src/db.ts` - Prisma 数据库客户端\n- `worker/src/app.ts` - Worker 应用入口\n- `web/next.config.mjs` - Next.js 应用配置\n\n---\n\n<a id='p-database'></a>\n\n## 数据库设计\n\n### 相关页面\n\n相关主题：[系统架构](#p-architecture), [追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/prisma/schema.prisma](https://github.com/langfuse/langfuse/blob/main/packages/shared/prisma/schema.prisma)\n- [packages/shared/clickhouse/migrations/clustered](https://github.com/langfuse/langfuse/blob/main/packages/shared/clickhouse/migrations/clustered)\n- [packages/shared/src/server/repositories](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories)\n- [packages/shared/src/tableDefinitions](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions)\n- [worker/src/scripts/refillQueueEvent/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/refillQueueEvent/README.md)\n</details>\n\n# 数据库设计\n\n## 概述\n\nLangfuse 采用多数据库架构，针对不同的数据访问模式选择最适合的存储方案。系统主要使用三种数据存储技术：**PostgreSQL** 作为主关系型数据库，**ClickHouse** 用于事件分析和时序数据，**Redis** 用于缓存和消息队列。这种混合架构平衡了事务一致性、查询性能和实时处理能力。\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n## 架构概览\n\n```mermaid\ngraph TB\n    subgraph 客户端层\n        A[Langfuse SDK] --> B[Ingestion API]\n        C[Web UI] --> D[Management API]\n    end\n    \n    subgraph 数据处理层\n        B --> E[BullMQ Queue]\n        E --> F[Worker Process]\n    end\n    \n    subgraph 存储层\n        F --> G[(PostgreSQL)]\n        F --> H[(ClickHouse)]\n        F --> I[(Redis)]\n        D --> G\n        D --> H\n    end\n    \n    subgraph 查询层\n        G --> J[Repository Pattern]\n        H --> K[ClickHouse Queries]\n        I --> L[Cache Layer]\n    end\n```\n\nLangfuse 的数据流向遵循以下原则：所有写入操作通过消息队列异步处理，确保高并发场景下的稳定性；读取操作根据数据类型选择最优存储引擎。`Observation` 和 `Trace` 等核心实体同时存在于 PostgreSQL 和 ClickHouse 中，前者保证关系完整性，后者支持复杂分析查询。\n\n资料来源：[packages/shared/src/server/repositories]()\n\n## PostgreSQL 核心表设计\n\n### 实体关系模型\n\nPostgreSQL 使用 Prisma ORM 进行模式管理，所有表设计遵循标准关系型数据库规范。核心实体包括组织、项目、用户、追踪、观察、提示词和数据集。\n\n```mermaid\nerDiagram\n    Organization ||--o{ Project : contains\n    Project ||--o{ ApiKey : has\n    Project ||--o{ Trace : contains\n    Project ||--o{ Dataset : contains\n    Project ||--o{ Prompt : contains\n    Trace ||--o{ Observation : contains\n    Trace ||--o{ Score : has\n    Observation ||--o{ Score : has\n    Dataset ||--o{ DatasetItem : contains\n    Dataset ||--o{ DatasetRun : has\n    User ||--o{ Membership : belongs_to\n    Organization ||--o{ Membership : has\n```\n\n### 主要数据表\n\n| 表名 | 描述 | 关联 |\n|------|------|------|\n| `Organization` | 组织租户 | 顶层实体 |\n| `Project` | 项目空间 | 属于组织 |\n| `User` | 用户账户 | 通过Membership关联 |\n| `Membership` | 组织成员关系 | User-Organization多对多 |\n| `ApiKey` | API密钥 | 属于项目 |\n| `Trace` | 追踪记录 | 属于项目 |\n| `Observation` | 观察单元 | 属于追踪 |\n| `Score` | 评分数据 | 可关联追踪或观察 |\n| `Prompt` | 提示词模板 | 属于项目 |\n| `Dataset` | 数据集 | 属于项目 |\n| `DatasetItem` | 数据集项 | 属于数据集 |\n| `DatasetRun` | 数据集运行 | 属于数据集 |\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n### Trace 表结构\n\n`Trace` 表是 Langfuse 数据模型的核心，用于记录完整的 LLM 调用会话：\n\n```prisma\nmodel Trace {\n  id            String       @id @default(cuid())\n  name          String?\n  userId        String?\n  projectId     String\n  metadata      Json?\n  release       String?\n  version       String?\n  createdAt     DateTime     @default(now())\n  updatedAt     DateTime     @updatedAt\n  \n  observations  Observation[]\n  scores        Score[]\n  sessions      Session[]\n}\n```\n\n关键字段说明：\n- `id`: 全局唯一标识符，使用 CUID 算法生成\n- `name`: 可选的追踪名称，便于识别\n- `userId`: 终端用户标识，用于多用户场景\n- `metadata`: 灵活 JSON 字段存储附加信息\n- `release`: 发布版本标签\n- `version`: 追踪数据版本\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n### Observation 表结构\n\n`Observation` 表存储追踪内的具体调用单元，支持多种事件类型：\n\n```prisma\nmodel Observation {\n  id            String       @id @default(cuid())\n  traceId       String\n  type          ObservationType\n  name          String?\n  startTime     DateTime\n  endTime       DateTime?\n  metadata      Json?\n  \n  // 嵌套调用\n  parentObservationId String?\n  parentObservation   Observation? @relation(...)\n  childObservations   Observation[]\n  \n  // 嵌入内容\n  input      String?\n  output     String?\n  usage      Json?\n  parameters Json?\n  \n  // 成本追踪\n  promptTokens        Int?\n  completionTokens    Int?\n  totalTokens         Int?\n  unitDollarPrice     Float?\n  totalDollarPrice   Float?\n  \n  scores      Score[]\n}\n```\n\n`ObservationType` 枚举定义事件类型：\n- `CHAT Spike`: 聊天消息\n- `COMPLETION`: 文本补全\n- `CHUNK`: 流式数据块\n- `GENERATION`: 生成事件\n- `EVENT`: 通用事件\n- `SPAN`: 跨度（包含子事件）\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n### Score 评分设计\n\n评分系统支持多维度评估，采用灵活的 JSON 结构：\n\n```prisma\nmodel Score {\n  id            String       @id @default(cuid())\n  name          String\n  value         Float\n  dataType      ScoreDataType\n  \n  // 评分来源\n  source        ScoreSource\n  \n  // 关联对象\n  traceId       String?\n  observationId String?\n  \n  // 评分者信息\n  authorId      String?\n  comment       String?\n  \n  createdAt     DateTime     @default(now())\n}\n```\n\n评分数据类型：\n- `NUMERIC`: 数值型评分\n- `CATEGORICAL`: 分类型评分\n- `BOOLEAN`: 布尔型评分\n\n评分来源包括 `API`、`INGESTION`、`EVALUATION`、`USER`、`BENCHMARK` 等。\n\n资料来源：[packages/shared/prisma/schema.prisma]()\n资料来源：[packages/shared/src/features/scores/interfaces/README.md]()\n\n## ClickHouse 事件存储\n\n### 事件存储架构\n\nClickHouse 作为列式存储数据库，专门用于高吞吐量的事件数据和分析查询。所有通过 Ingestion API 摄入的事件都会写入 ClickHouse，形成持久化的事件流。\n\n```mermaid\ngraph LR\n    A[SDK Events] --> B[Ingestion API]\n    B --> C[Event Validation]\n    C --> D[Queue Event]\n    D --> E[Worker Processing]\n    E --> F[(ClickHouse)]\n    E --> G[(PostgreSQL)]\n    \n    F --> H[Analytics Queries]\n    G --> I[Relational Queries]\n```\n\n事件数据按时间分区存储，支持高效的时间范围查询。数据采用分层设计：原始事件存储在 ClickHouse，经过处理的关系数据同步到 PostgreSQL。\n\n资料来源：[packages/shared/clickhouse/migrations/clustered]()\n资料来源：[worker/src/scripts/refillQueueEvent/README.md]()\n\n### ClickHouse 表结构\n\nClickHouse 采用物化视图和合并树引擎优化查询性能：\n\n```sql\nCREATE TABLE events (\n    id UUID,\n    project_id String,\n    trace_id String,\n    type String,\n    body String,\n    event_timestamp DateTime,\n    created_at DateTime\n) ENGINE = MergeTree()\nORDER BY (project_id, event_timestamp, id)\nPARTITION BY toYYYYMM(event_timestamp);\n```\n\n关键设计决策：\n- 使用 `project_id` 作为排序键首位，支持项目级高效过滤\n- 按月份分区，便于历史数据管理\n- 事件体存储为字符串，支持灵活的反序列化\n\n资料来源：[packages/shared/clickhouse/migrations/clustered]()\n\n### OTEL 事件格式\n\nOpenTelemetry 兼容事件使用特定路径格式存储：\n\n```\notel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json\n```\n\n这种层次化路径设计允许 S3 兼容存储和 ClickHouse 联合查询，实现边缘缓存和计算分离。\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n## Redis 缓存与队列\n\n### 队列架构\n\nLangfuse 使用 BullMQ（基于 Redis）实现异步任务处理：\n\n```mermaid\ngraph TB\n    subgraph 队列系统\n        A[OtelIngestionQueue] --> B[Ingestion Worker]\n        C[IngestionSecondaryQueue] --> D[Secondary Worker]\n        E[PromptCacheQueue] --> F[Cache Worker]\n    end\n    \n    subgraph 数据流\n        B --> G[(ClickHouse)]\n        D --> H[(PostgreSQL)]\n        F --> I[(Cache)]\n    end\n```\n\n主要队列类型：\n\n| 队列名称 | 用途 | 数据目标 |\n|----------|------|----------|\n| `OtelIngestionQueue` | OTEL 格式事件处理 | ClickHouse |\n| `IngestionSecondaryQueue` | 标准事件处理 | PostgreSQL + ClickHouse |\n| `PromptCacheQueue` | 提示词缓存更新 | Redis Cache |\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md]()\n\n### 缓存策略\n\n提示词模板使用 Redis 缓存加速访问：\n\n```typescript\ninterface PromptCacheEntry {\n  promptId: string;\n  content: string;\n  version: number;\n  expiresAt: number;\n}\n```\n\n缓存失效采用主动更新模式：当提示词更新时，通过队列触发缓存刷新，确保多实例部署的一致性。\n\n资料来源：[web/src/features/mcp/README.md]()\n\n## 数据流与同步\n\n### 事件摄取流程\n\n```mermaid\nsequenceDiagram\n    participant SDK\n    participant API as Ingestion API\n    participant Queue as BullMQ\n    participant Worker\n    participant CH as ClickHouse\n    participant PG as PostgreSQL\n\n    SDK->>API: POST /ingestion\n    API->>API: Validate & Transform\n    API->>Queue: Enqueue Event\n    API-->>SDK: 200 OK\n    \n    Queue->>Worker: Dequeue Job\n    Worker->>CH: Insert Event\n    Worker->>PG: Upsert Entity\n    Worker->>Worker: Index & Compute\n```\n\n事件摄取遵循写入放大模式：单次 API 调用触发多次数据写入，通过队列解耦确保响应延迟最小化。\n\n资料来源：[packages/shared/src/server/repositories]()\n\n### 批量处理与检查点\n\n摄取脚本支持断点续传机制：\n\n```typescript\ninterface BatchProgress {\n  totalRows: number;\n  processedRows: number;\n  queuedCount: number;\n  skippedCount: number;\n  errorCount: number;\n}\n```\n\n检查点文件保存当前处理位置，失败后可从上次成功位置恢复，保证大规模数据导入的可靠性。\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n## 查询优化\n\n### 索引策略\n\nPostgreSQL 表设计包含多层索引优化：\n\n```sql\n-- 复合索引支持项目级快速查询\nCREATE INDEX idx_traces_project_created \nON traces(project_id, created_at DESC);\n\n-- 文本搜索索引\nCREATE INDEX idx_traces_name_gin \nON traces USING gin(name gin_trgm_ops);\n\n-- 关系索引维护查询性能\nCREATE INDEX idx_observations_trace \nON observations(trace_id, start_time DESC);\n```\n\n### ClickHouse 查询模式\n\n分析查询使用物化视图聚合：\n\n```sql\nCREATE MATERIALIZED VIEW score_stats_mv\nENGINE = SummingMergeTree()\nORDER BY (project_id, score_name, period)\nAS SELECT\n    project_id,\n    score_name,\n    toDate(timestamp) as period,\n    count() as count,\n    avg(value) as avg_value,\n    quantile(0.5)(value) as p50\nFROM raw_events\nWHERE type = 'score'\nGROUP BY project_id, score_name, period;\n```\n\n资料来源：[packages/shared/src/tableDefinitions]()\n\n## 安全与隔离\n\n### 组织级数据隔离\n\n所有查询必须通过项目作用域验证：\n\n```typescript\ninterface AuthCheck {\n  validKey: boolean;\n  scope: {\n    projectId: string;\n    accessLevel: \"project\" | \"org\";\n  };\n}\n```\n\nAPI 密钥与项目绑定，跨项目访问通过组织成员关系控制。\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n### 敏感数据处理\n\n用户上传的 `metadata` 字段支持服务端过滤：\n\n```typescript\ninterface FilterConfig {\n  fieldPath: string;\n  action: \"REDACT\" | \"REMOVE\" | \"ALLOW\";\n}\n```\n\n配置化的数据过滤规则确保敏感信息不会出现在日志或分析结果中。\n\n## 总结\n\nLangfuse 的数据库设计体现了现代 SaaS 应用的多存储策略：\n- **PostgreSQL** 提供强一致性的关系数据存储\n- **ClickHouse** 处理高吞吐量分析工作负载\n- **Redis** 实现异步处理和高速缓存\n\n三层架构通过事件驱动模式松耦合，支持水平扩展同时保持数据完整性。Repository 模式封装数据访问逻辑，隐藏底层存储细节，便于未来架构演进。\n\n资料来源：[packages/shared/src/server/repositories]()\n资料来源：[packages/shared/prisma/schema.prisma]()\n\n---\n\n<a id='p-tracing'></a>\n\n## 追踪系统\n\n### 相关页面\n\n相关主题：[数据库设计](#p-database)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/traces.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/traces.ts)\n- [packages/shared/src/domain/observations.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/observations.ts)\n- [packages/shared/src/server/ingestion](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/ingestion)\n- [packages/shared/src/server/otel](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/otel)\n- [packages/shared/src/server/repositories/traces.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories/traces.ts)\n- [packages/shared/src/server/repositories/observations.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/repositories/observations.ts)\n</details>\n\n# 追踪系统\n\n## 概述\n\n追踪系统（Tracing System）是 Langfuse 的核心功能模块，负责收集、存储和展示 LLM 应用执行过程中的完整调用链路。该系统基于 OpenTelemetry 标准构建，支持多种观察类型，能够帮助开发者监控、分析和优化 AI 应用的行为。\n\n追踪系统的主要职责包括：\n\n- **链路追踪**：记录完整的请求调用链路，包括输入、输出和中间过程\n- **观察类型支持**：支持 SPAN（跨度）、GENERATION（生成）、EVENT（事件）等多种观察类型\n- **层级结构**：通过父子关系构建树形结构，展现调用嵌套关系\n- **元数据管理**：附加和解析丰富的上下文元数据\n- **评分集成**：与评分系统集成，支持评估执行效果的追踪\n\n资料来源：[packages/shared/src/domain/traces.ts]()\n\n---\n\n## 核心数据模型\n\n### Trace（追踪）\n\nTrace 是整个追踪系统的顶层容器，代表一次完整的请求或会话。每个 Trace 包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 追踪的唯一标识符 |\n| name | string | 追踪名称，用于快速识别 |\n| projectId | string | 所属项目 ID |\n| userId | string | 用户标识 |\n| sessionId | string | 会话标识 |\n| metadata | JSON | 附加的元数据 |\n| release | string | 发布版本 |\n| version | string | 追踪版本 |\n| tags | string[] | 标签数组 |\n| environment | string | 环境（default 等） |\n| bookmarked | boolean | 是否收藏 |\n| input | JSON | 输入数据 |\n| output | JSON | 输出数据 |\n| latency | number | 总延迟（秒） |\n| createdAt | DateTime | 创建时间 |\n\n资料来源：[packages/shared/src/domain/traces.ts:1-20]()\n\n### Observation（观察）\n\nObservation 是 Trace 的子节点，代表追踪中的一个具体操作或事件。支持四种类型：\n\n| 类型 | 说明 | 使用场景 |\n|------|------|----------|\n| TRACE | 追踪容器根节点 | 包装整个追踪结构 |\n| SPAN | 跨度 | 标记一段代码执行区间 |\n| GENERATION | 生成 | 记录 LLM 生成操作 |\n| EVENT | 事件 | 记录离散的时间点事件 |\n\n每个 Observation 包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 观察的唯一标识符 |\n| traceId | string | 所属追踪 ID |\n| parentObservationId | string | 父观察 ID（用于构建层级） |\n| type | ObservationType | 观察类型 |\n| name | string | 观察名称 |\n| startTime | DateTime | 开始时间 |\n| endTime | DateTime | 结束时间 |\n| metadata | JSON | 元数据 |\n| input | JSON | 输入内容 |\n| output | JSON | 输出内容 |\n| model | string | 使用的模型（如适用） |\n| modelParameters | JSON | 模型参数 |\n| usage | Usage | Token 使用量 |\n| level | string | 日志级别 |\n| statusMessage | string | 状态消息 |\n\n资料来源：[packages/shared/src/domain/observations.ts]()\n\n---\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n    subgraph 客户端层\n        SDK[SDK / OpenTelemetry SDK]\n        MCP[MCP Server]\n    end\n\n    subgraph 摄取层\n        IngestionAPI[摄取 API]\n        OTELEndpoint[OTEL Endpoint]\n    end\n\n    subgraph 处理层\n        Validation[数据验证]\n        Transform[数据转换]\n        Queue[消息队列]\n    end\n\n    subgraph 存储层\n        PostgreSQL[(PostgreSQL)]\n        ClickHouse[(ClickHouse)]\n        Redis[(Redis)]\n    end\n\n    subgraph 查询层\n        TracesRepo[Traces Repository]\n        ObservationsRepo[Observations Repository]\n        ScoreRepo[Score Repository]\n    end\n\n    subgraph 展示层\n        TraceTree[追踪树构建]\n        JsonViewer[JSON 查看器]\n        Analytics[分析面板]\n    end\n\n    SDK --> IngestionAPI\n    MCP --> IngestionAPI\n    SDK --> OTELEndpoint\n\n    IngestionAPI --> Validation\n    OTELEndpoint --> Validation\n\n    Validation --> Transform\n    Transform --> Queue\n\n    Queue --> PostgreSQL\n    Queue --> ClickHouse\n\n    TracesRepo --> PostgreSQL\n    ObservationsRepo --> ClickHouse\n    ScoreRepo --> PostgreSQL\n\n    TraceTree --> ObservationsRepo\n    JsonViewer --> TracesRepo\n    Analytics --> ScoreRepo\n```\n\n### 数据流向\n\n```mermaid\ngraph LR\n    A[事件创建] --> B[事件摄取]\n    B --> C{验证}\n    C -->|通过| D[写入队列]\n    C -->|失败| E[错误日志]\n    D --> F[异步处理]\n    F --> G[ClickHouse]\n    F --> H[PostgreSQL]\n    G --> I[UI 展示]\n    H --> I\n```\n\n---\n\n## 摄取系统\n\n### 标准摄取流程\n\nLangfuse 支持两种事件摄取方式：标准摄取和 OpenTelemetry（OTEL）摄取。\n\n#### 标准摄取端点\n\n标准摄取使用以下格式的 S3 键路径：\n\n```\n{projectId}/{type}/{eventBodyId}/{eventId}.json\n```\n\n摄取请求体结构：\n\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\" }\n  },\n  \"data\": {\n    \"eventBodyId\": \"<eventBodyId>\",\n    \"fileKey\": \"<eventId>\",\n    \"type\": \"<type>-create\"\n  }\n}\n```\n\n事件经过验证后被加入 `IngestionSecondaryQueue` 队列处理。\n\n资料来源：[packages/shared/src/server/ingestion]()\n\n#### OTEL 摄取端点\n\nOTEL 格式使用更详细的路径结构，支持标准化的遥测数据格式：\n\n```\notel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json\n```\n\nOTEL 请求体结构：\n\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\", \"accessLevel\": \"project\" }\n  },\n  \"data\": {\n    \"fileKey\": \"otel/<projectId>/<yyyy>/<mm>/<dd>/<hh>/<mm>/<eventId>.json\"\n  }\n}\n```\n\nOTEL 事件被加入 `OtelIngestionQueue` 队列处理。\n\n资料来源：[packages/shared/src/server/otel]()\n\n### 验证与转换\n\n摄取流程包含严格的数据验证步骤：\n\n1. **身份验证检查**：验证 API Key 和项目权限\n2. **Schema 验证**：使用 Zod 进行类型验证\n3. **数据转换**：将原始事件转换为内部数据模型\n4. **队列分发**：根据事件类型分发到对应队列\n\n---\n\n## 存储层\n\n### 多存储架构\n\nLangfuse 采用混合存储策略，根据数据特性选择最优存储：\n\n| 数据类型 | 存储引擎 | 说明 |\n|----------|----------|------|\n| Trace 元数据 | PostgreSQL | 结构化查询，事务支持 |\n| Observation 数据 | ClickHouse | 时序数据，分析查询优化 |\n| 缓存数据 | Redis | 热点数据加速访问 |\n| 大型 JSON | S3 | 存储 input/output 等大字段 |\n\n### Traces 仓库\n\n`TracesRepository` 负责 Trace 的 CRUD 操作：\n\n- 创建新追踪记录\n- 更新追踪元数据\n- 查询追踪列表（支持分页、过滤、排序）\n- 获取单个追踪详情\n\n资料来源：[packages/shared/src/server/repositories/traces.ts]()\n\n### Observations 仓库\n\n`ObservationsRepository` 负责 Observation 的管理：\n\n- 创建观察记录\n- 更新观察数据\n- 构建树形结构查询\n- 批量查询追踪下的所有观察\n\n资料来源：[packages/shared/src/server/repositories/observations.ts]()\n\n---\n\n## UI 展示系统\n\n### 追踪树构建\n\n追踪数据在 UI 中以树形结构展示。核心构建逻辑位于 `buildTraceUiData` 函数：\n\n```typescript\n// 传统追踪：单一 TRACE 根节点 + 子观察节点\nconst result = buildTraceUiData(trace, observations);\n\n// 结果结构\n{\n  roots: [\n    {\n      id: \"trace-{traceId}\",\n      type: \"TRACE\",\n      name: \"{traceName}\",\n      children: [\n        { id: \"{obsId}\", type: \"SPAN|GENERATION|EVENT\", ... }\n      ]\n    }\n  ]\n}\n```\n\n树构建使用**显式栈迭代**而非递归，以避免深度嵌套导致的栈溢出问题：\n\n```typescript\n// ❌ 递归方式（深度 1000+ 可能栈溢出）\nfunction traverse(node: TreeNode) {\n  process(node);\n  node.children.forEach((child) => traverse(child));\n}\n\n// ✅ 迭代方式（安全处理任意深度）\nfunction traverse(rootNode: TreeNode) {\n  const stack = [rootNode];\n  while (stack.length > 0) {\n    const node = stack.pop()!;\n    process(node);\n    node.children.forEach((child) => stack.push(child));\n  }\n}\n```\n\n资料来源：[web/src/components/trace/lib/tree-building.clienttest.ts]()\n\n### 追踪页面组件\n\n追踪详情页面使用 `Page` 组件包装，确保一致的布局体验：\n\n```tsx\n<Page\n  title=\"{traceName}: {traceId}\"\n  scrollable\n  headerProps={{\n    breadcrumb: [\n      { name: \"Traces\", href: \"/traces\" },\n      { name: \"{traceName}\" }\n    ]\n  }}\n>\n  <TraceDetail />\n</Page>\n```\n\n### JSON 查看器\n\n追踪详情使用 `AdvancedJsonViewer` 组件展示，支持：\n\n- 树形结构展开/折叠\n- 关键字搜索（客户端内存搜索）\n- 虚拟化渲染（支持大数据集）\n- 自定义主题\n\n---\n\n## 元数据系统\n\n### 元数据解析\n\n追踪系统支持从元数据中提取特定字段：\n\n```typescript\nexport const resolveEvalExecutionMetadata = (\n  parsedMetadata: unknown\n): string | null => {\n  try {\n    if (typeof parsedMetadata !== \"object\" || parsedMetadata === null)\n      return null;\n    return (parsedMetadata as Record<string, unknown>)[\n      \"target_trace_id\"\n    ] as string;\n  } catch {\n    return null;\n  }\n};\n```\n\n此函数用于关联评估执行与目标追踪，实现评估结果的溯源。\n\n资料来源：[web/src/components/trace/lib/resolve-metadata.ts]()\n\n### 过滤器与查询编码\n\n追踪支持丰富的过滤条件，使用 URL 编码存储：\n\n```typescript\n// 支持的过滤类型\nconst filterTypes = {\n  datetime: Date,        // 日期时间过滤\n  number: Number,         // 数值过滤\n  numberObject: Number,  // 对象内数值过滤\n  stringOptions: string[],  // 字符串选项\n  arrayOptions: string[],   // 数组选项\n  categoryOptions: string[], // 分类选项\n  boolean: boolean        // 布尔过滤\n};\n```\n\n资料来源：[web/src/features/filters/lib/filter-query-encoding.ts]()\n\n---\n\n## 评分集成\n\n### 评分接口\n\n追踪系统与评分系统深度集成，支持在追踪级别附加评分：\n\n| API 版本 | GET 要求 | 新增字段 |\n|----------|----------|----------|\n| V1 | 必须提供 `traceId` | 仅支持追踪级评分 |\n| V2 | `traceId` 可选 | 支持 `sessionId` |\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md]()\n\n### 评分解析\n\n评分分析模块提供统计计算和可视化：\n\n```typescript\n// 评分一致性解读\nfunction interpretAgreement(agreement: number): InterpretationResult {\n  if (agreement >= 0.9) {\n    return { strength: \"Excellent\", color: \"green\" };\n  }\n  if (agreement >= 0.8) {\n    return { strength: \"Good\", color: \"blue\" };\n  }\n  // ...\n}\n\n// MAE 解读（支持相对误差计算）\nfunction interpretMAE(\n  mae: number | null,\n  scale?: { min: number; max: number }\n): InterpretationResult\n```\n\n资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts]()\n\n---\n\n## 开发工具\n\n### 追踪回放脚本\n\n`replayIngestionEventsV2` 脚本支持从 CSV 文件回放摄取事件：\n\n```bash\npnpm run --filter=worker replay-ingestion-events-v2 \\\n  --input=events.csv \\\n  --url=http://localhost:3000 \\\n  --rate-limit=100\n```\n\n特性：\n\n- **断点续传**：自动保存检查点，失败后可恢复\n- **速率限制**：客户端与服务端双重限流\n- **重试机制**：临时错误自动重试（最多 3 次）\n- **错误日志**：失败事件记录到 `errors.csv`\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md]()\n\n### 队列填充脚本\n\n`refillQueueEvent` 脚本用于本地回填队列：\n\n```bash\n# 1. 创建事件文件 worker/events.jsonl\n{\"projectId\": \"project-123\", \"orgId\": \"org-456\"}\n\n# 2. 配置环境变量\nREDIS_CONNECTION_STRING=redis://:secret@127.0.0.1:6379\n\n# 3. 运行脚本\npnpm run --filter=worker refill-queue-event\n```\n\n资料来源：[worker/src/scripts/refillQueueEvent/README.md]()\n\n---\n\n## 最佳实践\n\n### 追踪命名规范\n\n追踪名称建议遵循格式：`{操作}: {唯一标识}`，例如：\n\n- `chat-completion: msg-abc123`\n- `agent-execution: run-xyz789`\n\n### 嵌套层级控制\n\n为保证 UI 性能和可读性：\n\n- 建议单个追踪的观察节点不超过 1000 个\n- 深度嵌套建议拆分为多个子追踪\n- 使用 EVENT 类型记录关键时间点，而非创建大量小 SPAN\n\n### 元数据组织\n\n元数据应包含：\n\n- **上下文信息**：请求来源、用户特征\n- **性能指标**：各阶段耗时、Token 使用量\n- **调试信息**：内部标识符、版本号\n\n---\n\n## 相关文档\n\n| 模块 | 路径 | 说明 |\n|------|------|------|\n| 领域模型 | `packages/shared/src/domain/` | Trace 和 Observation 的核心定义 |\n| 摄取服务 | `packages/shared/src/server/ingestion/` | 数据摄取 API |\n| OTEL 支持 | `packages/shared/src/server/otel/` | OpenTelemetry 集成 |\n| 仓库层 | `packages/shared/src/server/repositories/` | 数据库操作封装 |\n| UI 组件 | `web/src/components/trace/` | 追踪展示组件 |\n| 评分系统 | `web/src/features/score-analytics/` | 评分分析与可视化 |\n\n---\n\n<a id='p-prompts'></a>\n\n## 提示词管理\n\n### 相关页面\n\n相关主题：[数据库设计](#p-database)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/prompts.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/prompts.ts)\n- [packages/shared/src/features/prompts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/prompts)\n- [packages/shared/src/server/services/PromptService](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/services/PromptService)\n- [web/src/features/prompts](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)\n- [web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n- [packages/shared/src/tableDefinitions/promptsTable.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions/promptsTable.ts)\n</details>\n\n# 提示词管理\n\n提示词管理（Prompt Management）是 Langfuse 平台的核心功能之一，它提供了对提示词（Prompts）的创建、版本控制、组合、缓存和分发的完整生命周期管理。通过 Langfuse 的提示词管理系统，用户可以集中管理所有项目的提示词，支持版本标签、依赖引用、API 调用以及 MCP（Model Context Protocol）集成。\n\n## 核心概念\n\n### 提示词实体\n\nLangfuse 中的提示词是一个包含名称、版本、内容和元数据的实体。每个提示词具有以下核心属性：\n\n| 属性 | 说明 |\n|------|------|\n| `name` | 提示词的唯一标识名称 |\n| `version` | 自动递增的版本号 |\n| `type` | 提示词类型（text 或 chat） |\n| `config` | 提示词配置（温度、最大 token 等） |\n| `labels` | 版本标签数组（如 production、development） |\n| `prompt` | 提示词内容或消息数组 |\n| `createdAt` | 创建时间戳 |\n\n资料来源：[packages/shared/src/domain/prompts.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/prompts.ts)\n\n### 提示词类型\n\nLangfuse 支持两种提示词类型：\n\n**文本提示词（Text Prompt）**\n- 用于简单的文本补全任务\n- `prompt` 字段存储纯文本内容\n\n**聊天提示词（Chat Prompt）**\n- 用于 OpenAI 风格的聊天接口\n- `prompt` 字段存储消息数组，每条消息包含 `role` 和 `content`\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n## 系统架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n    subgraph 客户端层\n        MCP[ MCP Server ]\n        API[ REST API ]\n        WebUI[ Web 前端 ]\n    end\n    \n    subgraph 服务层\n        PromptService[ PromptService ]\n        PromptCache[ Redis Cache ]\n        PromptDB[( PostgreSQL )]\n    end\n    \n    MCP -->|getPrompt/createPrompt| PromptService\n    API -->|CRUD 操作| PromptService\n    WebUI -->|管理界面| PromptService\n    \n    PromptService -->|缓存读写| PromptCache\n    PromptService -->|持久化| PromptDB\n```\n\n### 数据存储\n\nLangfuse 使用 PostgreSQL 作为提示词的持久化存储，并通过 Redis 实现缓存层以提升读取性能。\n\n```mermaid\ngraph LR\n    A[读请求] --> B{检查 Redis}\n    B -->|缓存命中| C[返回缓存数据]\n    B -->|缓存未命中| D[查询 PostgreSQL]\n    D --> E[写入 Redis]\n    E --> C\n```\n\n资料来源：[web/src/features/prompts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)\n\n## 缓存策略\n\n### 缓存结构\n\n提示词的缓存使用 Redis 管理，缓存键格式如下：\n\n```\nprompt:<project-id>:<prompt-name>:<prompt-version ?? label>\n```\n\n这意味着：\n- 同一提示词名称可能对应多个缓存键\n- 具有多个标签的提示词会在缓存中多次出现\n\n### 缓存操作流程\n\n```mermaid\nsequenceDiagram\n    participant Client as 客户端\n    participant Cache as Redis Cache\n    participant Lock as Redis Lock\n    participant DB as PostgreSQL\n\n    Client->>Cache: 读取提示词\n    Cache->>Cache: 检查缓存键\n    alt 缓存命中\n        Cache-->>Client: 返回缓存数据\n        Cache->>Cache: 重置 TTL\n    else 缓存未命中 或 锁存在\n        Cache-->>DB: 查询数据库\n        DB-->>Cache: 返回提示词数据\n        Cache-->>Client: 返回数据并缓存\n    end\n\n    Note over Lock,DB: 更新提示词时\n    Lock->>Lock: 获取分布式锁\n    Lock->>Cache: 清除所有相关缓存键\n    Lock->>DB: 执行数据库更新\n    Lock->>Lock: 释放锁\n```\n\n### 关键设计原则\n\n1. **从不更新缓存**：当提示词更新时，系统会删除所有相关的缓存条目，而不是修改它们\n2. **分布式锁保护**：使用 Redis 锁确保并发更新的安全性\n3. **操作顺序**：先获取锁 → 失效缓存 → 执行数据库操作 → 释放锁\n\n资料来源：[web/src/features/prompts/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/prompts)\n\n## MCP 集成\n\nLangfuse 提供了 MCP（Model Context Protocol）服务器集成，允许外部工具和客户端程序访问提示词管理功能。\n\n### MCP 工具列表\n\n| 工具名称 | 功能 | 类型 |\n|----------|------|------|\n| `getPrompt` | 获取完全解析的提示词（包含依赖） | 只读 |\n| `getPromptUnresolved` | 获取原始提示词（保留依赖标签） | 只读 |\n| `listPrompts` | 列出所有提示词（支持过滤和分页） | 只读 |\n| `createTextPrompt` | 创建新的文本提示词版本 | 写入 |\n| `createChatPrompt` | 创建新的聊天提示词版本 | 写入 |\n| `updatePromptLabels` | 更新提示词标签 | 写入 |\n\n### 提示词解析模式\n\nMCP 服务提供两种提示词获取模式：\n\n**完全解析模式（getPrompt）**\n- 用于获取可直接发送给 LLM 的最终提示词\n- 递归解析所有依赖标签\n- 返回包含完整内容的提示词\n\n**原始模式（getPromptUnresolved）**\n- 用于分析提示词组合结构\n- 保留 `@@@langfusePrompt:name=xxx|label=yyy@@@` 依赖标签\n- 有助于调试和理解提示词依赖关系\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n## 提示词组合\n\n### 依赖标签语法\n\nLangfuse 支持提示词组合功能，允许一个提示词引用其他提示词。依赖标签语法如下：\n\n```\n@@@langfusePrompt:name=<prompt-name>|label=<label-name>@@@\n```\n\n### 组合示例\n\n```\n输入: \"You are helpful. @@@langfusePrompt:name=base-rules|label=production@@@\"\n输出: \"You are helpful. Always be kind and respectful.\"\n```\n\n### 使用场景\n\n- **提示词堆叠**：将基础规则与具体任务提示词组合\n- **依赖链分析**：使用 `getPromptUnresolved` 调试依赖关系\n- **构建工具**：开发管理提示词组合的自动化工具\n\n```mermaid\ngraph TD\n    A[主提示词] -->|依赖| B[基础规则提示词]\n    A -->|依赖| C[角色定义提示词]\n    B -->|依赖| D[通用指令提示词]\n    \n    style A fill:#e1f5fe\n    style B fill:#fff3e0\n    style C fill:#fff3e0\n    style D fill:#f3e5f5\n```\n\n## API 接口\n\n### 创建提示词\n\n**文本提示词**\n\n```typescript\ncreateTextPrompt(params: {\n  projectId: string;\n  promptName: string;\n  prompt: string;\n  config?: PromptConfig;\n  labels?: string[];\n})\n```\n\n**聊天提示词**\n\n```typescript\ncreateChatPrompt(params: {\n  projectId: string;\n  promptName: string;\n  messages: ChatMessage[];\n  config?: PromptConfig;\n  labels?: string[];\n})\n```\n\n### 查询提示词\n\n```typescript\nlistPrompts(params: {\n  projectId: string;\n  name?: string;      // 可选：按名称过滤\n  label?: string;     // 可选：按标签过滤\n  tag?: string;       // 可选：按标签过滤\n  updatedAtStart?: Date;\n  updatedAtEnd?: Date;\n  page?: number;\n  limit?: number;\n})\n```\n\n## 版本控制与标签\n\n### 版本管理\n\n每个提示词版本具有自动递增的版本号。创建新版本时：\n\n1. 版本号自动加一\n2. 可选择性地添加标签（如 `production`、`dev`）\n3. 版本记录创建时间戳\n\n### 标签系统\n\n标签用于标识提示词的用途或环境：\n\n| 标签示例 | 用途 |\n|----------|------|\n| `production` | 生产环境使用的版本 |\n| `staging` | 测试环境使用的版本 |\n| `experiment` | 实验性版本 |\n| `archived` | 已归档的旧版本 |\n\n### 标签更新操作\n\n`updatePromptLabels` 工具允许：\n- 添加新标签到现有版本\n- 将标签从一个版本移动到另一个版本\n- 删除不需要的标签\n\n## 数据库模型\n\n提示词表结构定义：\n\n```typescript\ninterface PromptTable {\n  id: string;              // UUID 主键\n  project_id: string;      // 项目 ID\n  name: string;           // 提示词名称\n  version: number;         // 版本号\n  type: \"text\" | \"chat\";   // 提示词类型\n  prompt: string;          // 提示词内容\n  config: object;          // 配置（JSON）\n  labels: string[];        // 标签数组\n  created_at: Date;        // 创建时间\n  updated_at: Date;        // 更新时间\n}\n```\n\n资料来源：[packages/shared/src/tableDefinitions/promptsTable.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/tableDefinitions/promptsTable.ts)\n\n## 审计日志\n\n所有写入操作（创建、更新标签）会自动创建审计日志条目，包含：\n\n- 操作前状态快照\n- 操作后状态快照\n- 操作时间戳\n- 操作者信息\n\n## 安全与权限\n\n### 访问控制\n\nMCP 集成使用 BasicAuth 认证：\n\n```bash\n# 生成 Basic Auth Token\necho -n \"pk-lf-your-public-key:sk-lf-your-secret-key\" | base64\n```\n\n### 权限级别\n\n| 权限级别 | 说明 |\n|----------|------|\n| `project` | 项目级访问权限 |\n| `org` | 组织级访问权限 |\n| `admin` | 管理员权限 |\n\n### 工具注解\n\nMCP 工具包含安全提示注解：\n\n- `readOnly: true`：安全操作，无需确认（如 `getPrompt`、`listPrompts`）\n- `destructive: true`：修改数据的操作（如 `createTextPrompt`、`createChatPrompt`）\n\n客户端程序可以根据这些注解自动批准只读操作，或在执行破坏性操作时要求用户确认。\n\n## 最佳实践\n\n### 命名规范\n\n- 使用描述性名称：`customer-support-greeting` 而非 `prompt-1`\n- 统一命名风格：建议使用 kebab-case 或 camelCase\n- 包含版本或环境信息：`prompt-name:production`\n\n### 标签使用策略\n\n1. 生产环境使用 `production` 标签\n2. 开发和测试使用 `dev` 或 `staging` 标签\n3. 避免在标签中包含敏感信息\n4. 定期清理不再使用的标签\n\n### 缓存优化\n\n1. 避免频繁更新提示词，以减少缓存失效开销\n2. 使用标签而非版本号来引用提示词（标签更稳定）\n3. 监控缓存命中率，及时调整缓存策略\n\n## 总结\n\nLangfuse 的提示词管理系统提供了企业级的提示词管理能力，包括：\n\n- **版本控制**：自动版本管理和标签系统\n- **组合能力**：支持提示词依赖和复用\n- **高性能**：Redis 缓存和锁机制确保并发安全\n- **标准化接口**：REST API 和 MCP 集成支持多种客户端\n- **审计追踪**：完整的操作日志记录\n\n---\n\n<a id='p-evaluations'></a>\n\n## 评估系统\n\n### 相关页面\n\n相关主题：[数据集管理](#p-datasets), [追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/score-configs.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/score-configs.ts)\n- [packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n- [web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n- [web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)\n</details>\n\n# 评估系统\n\n## 概述\n\nLangfuse 的评估系统（Evaluation System）是用于衡量和分析 LLM 应用输出的核心模块。该系统提供了一套完整的评分（Score）管理机制，包括评分的定义、存储、分析和可视化功能。评估系统帮助开发者量化 LLM 生成内容的质量，支持自定义评分规则，并通过统计分析提供对模型性能的洞察。\n\nLangfuse 采用双轨 API 设计，支持 v1（遗留版本，仅支持 trace 级别评分）和 v2（当前版本，支持 trace、session 和数据集运行级别的评分）。资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 核心数据模型\n\n### 评分（Score）\n\n评分是评估系统的基本单元，用于记录对 trace、session 或数据集运行项的评估结果。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 评分唯一标识符 |\n| `name` | string | 评分名称（如 \"accuracy\", \"relevance\"） |\n| `value` | number \\| string \\| boolean | 评分的实际值 |\n| `dataType` | \"NUMERIC\" \\| \"CATEGORICAL\" \\| \"BOOLEAN\" | 数据类型 |\n| `traceId` | string | 关联的 trace ID（v1 API 必需） |\n| `sessionId` | string | 关联的 session ID（v2 API 支持） |\n| `observationId` | string | 关联的 observation ID |\n| `source` | \"API\" \\| \"APP\" \\| \"EVALUATION\" \\| \"LLM\" | 评分来源 |\n| `comment` | string | 可选的评分备注 |\n| `metadata` | object | 附加元数据 |\n| `createdAt` | DateTime | 创建时间 |\n| `updatedAt` | DateTime | 更新时间 |\n\n资料来源：[packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)\n\n### 评分配置（ScoreConfig）\n\n评分配置定义了项目中的评分规则和元数据，确保评分的一致性和可解释性。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 配置唯一标识符 |\n| `projectId` | string | 所属项目 ID |\n| `name` | string | 评分名称（项目内唯一） |\n| `dataType` | \"NUMERIC\" \\| \"CATEGORICAL\" \\| \"BOOLEAN\" | 期望的数据类型 |\n| `categories` | string[] | 枚举值列表（categorical 类型必需） |\n| `description` | string | 评分说明文档 |\n| `valueRange` | { min?, max? } | 数值范围约束（numeric 类型） |\n| `createdAt` | DateTime | 创建时间 |\n| `updatedAt` | DateTime | 更新时间 |\n\n资料来源：[packages/shared/src/domain/score-configs.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/score-configs.ts)\n\n---\n\n## 系统架构\n\n```mermaid\ngraph TD\n    subgraph 前端层\n        A[Web UI] --> B[Score Analytics 组件]\n        A --> C[评分配置管理]\n    end\n    \n    subgraph API 层\n        D[v1 API] --> E[Scores Endpoints]\n        F[v2 API] --> E\n        E --> G[Score Router]\n    end\n    \n    subgraph 服务层\n        G --> H[Score Service]\n        G --> I[Score Analytics Service]\n    end\n    \n    subgraph 数据层\n        H --> J[(PostgreSQL)]\n        I --> K[(ClickHouse)]\n    end\n    \n    subgraph Worker 层\n        L[Evaluation Worker] --> M[评分计算任务]\n        M --> I\n    end\n```\n\n---\n\n## 评分类型\n\nLangfuse 支持三种评分数据类型，适用于不同的评估场景：\n\n### 数值型（NUMERIC）\n\n用于连续数值的评分，如准确率得分（0-1）、延迟（毫秒）、成本（美元）等。\n\n```typescript\n{\n  name: \"accuracy\",\n  value: 0.95,\n  dataType: \"NUMERIC\",\n  dataType: {\n    min: 0,\n    max: 1\n  }\n}\n```\n\n### 类别型（CATEGORICAL）\n\n用于离散的分类标签，如评级（A/B/C）、质量等级（优秀/良好/一般）等。\n\n```typescript\n{\n  name: \"quality\",\n  value: \"excellent\",\n  dataType: \"CATEGORICAL\",\n  categories: [\"excellent\", \"good\", \"fair\", \"poor\"]\n}\n```\n\n### 布尔型（BOOLEAN）\n\n用于二元判断，如是否通过、是否合规、是否有毒等。\n\n```typescript\n{\n  name: \"is_valid\",\n  value: true,\n  dataType: \"BOOLEAN\"\n}\n```\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 评分来源\n\n| 来源标识 | 说明 | 典型使用场景 |\n|----------|------|-------------|\n| `API` | 通过 API 直接提交 | 外部评估系统集成 |\n| `APP` | 通过 Langfuse UI 手动创建 | 人工审核评分 |\n| `EVALUATION` | 通过评估任务自动生成 | 自动化测试套件 |\n| `LLM` | 由 LLM 作为评判者生成 | LLM-as-Judge 评估 |\n\n资料来源：[packages/shared/src/domain/scores.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/scores.ts)\n\n---\n\n## 评分分析功能\n\n### Score Analytics Provider\n\n`ScoreAnalyticsProvider` 是前端核心组件，用于包装评分分析数据并向子组件提供上下文。\n\n```tsx\n<ScoreAnalyticsProvider\n  projectId=\"proj_xxx\"\n  score1={{\n    id: \"score_1\",\n    name: \"accuracy\",\n    source: \"API\",\n    dataType: \"NUMERIC\"\n  }}\n  score2={{ /* 可选：第二个评分用于对比 */ }}\n  objectType=\"TRACE\"\n  startDate={new Date(\"2024-01-01\")}\n  endDate={new Date(\"2024-12-31\")}\n  interval={{ count: 1, unit: \"day\" }}\n>\n  <ScoreAnalyticsDashboard />\n</ScoreAnalyticsProvider>\n```\n\n### Hooks 层\n\n| Hook | 职责 |\n|------|------|\n| `useScoreAnalyticsQuery` | 从 API 获取数据并执行一次转换 |\n| `useScoreAnalytics` | 从 Provider 上下文获取分析数据 |\n\n资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n\n### 数据转换管道\n\n评分数据从 API 返回后需经过多层转换处理：\n\n```mermaid\ngraph LR\n    A[API Raw Data] --> B[Extract Categories]\n    B --> C[Fill Distribution Bins]\n    C --> D[Generate Bin Labels]\n    D --> E[Transform Heatmap]\n    E --> F[Calculate Mode Metrics]\n    F --> G[Fill Time Series Gaps]\n    G --> H[Namespace Categorical]\n    H --> I[ScoreAnalyticsData]\n```\n\n所有转换逻辑均位于 `useScoreAnalyticsQuery` Hook 中，使用 `useMemo` 进行记忆化，确保数据仅转换一次。\n\n资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n\n---\n\n## 统计分析工具\n\n### 一致性解释（interpretAgreement）\n\n用于评估两个评分之间的一致性程度：\n\n| 一致性范围 | 强度等级 | 颜色标识 |\n|-----------|----------|----------|\n| ≥ 0.9 | Excellent | green |\n| ≥ 0.8 | Good | blue |\n| ≥ 0.6 | Fair | yellow |\n| ≥ 0.4 | Poor | orange |\n| < 0.4 | Very Poor | red |\n\n```typescript\nexport function interpretAgreement(\n  agreement: number | null\n): InterpretationResult {\n  if (agreement >= 0.9) {\n    return {\n      strength: \"Excellent\",\n      color: \"green\",\n      description: `${percentage}% of predictions match`,\n    };\n  }\n  // ... 其他阈值\n}\n```\n\n资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)\n\n### MAE 解释（interpretMAE）\n\nMean Absolute Error 的上下文相关解释：\n\n```typescript\nexport function interpretMAE(\n  mae: number | null,\n  scale?: { min: number; max: number }\n): InterpretationResult\n```\n\n当提供 `scale` 参数时，系统会计算相对误差以提供更有意义的解释。\n\n资料来源：[web/src/features/score-analytics/lib/statistics-utils.ts](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/lib/statistics-utils.ts)\n\n---\n\n## API 版本差异\n\n| 特性 | v1 API | v2 API |\n|------|--------|--------|\n| `traceId` | **必需** | 可选 |\n| `sessionId` | 不支持 | 支持 |\n| 适用范围 | 仅 trace 级别评分 | trace、session、数据集运行 |\n| 生命周期 | 遗留版本 | 当前推荐版本 |\n\n> **注意**：POST 和 DELETE API 在 v1 和 v2 中保持一致，继续支持所有评分类型。\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 文件结构\n\n```\npackages/shared/src/\n├── domain/\n│   ├── score-configs.ts      # 评分配置领域模型\n│   └── scores.ts             # 评分领域模型\n└── features/scores/\n    └── interfaces/           # 接口定义\n        ├── api/\n        │   ├── v1/           # 遗留 API 类型\n        │   ├── v2/           # 当前 API 类型\n        │   └── shared.ts     # 共享类型\n        ├── application/      # 应用层验证\n        ├── ingestion/        # 摄取层类型\n        └── ui/               # UI 简化类型\n\nweb/src/features/\n└── score-analytics/\n    ├── components/           # 评分分析组件\n    │   └── ScoreAnalyticsProvider.tsx\n    ├── hooks/\n    │   └── useScoreAnalyticsQuery.ts\n    ├── lib/\n    │   ├── analytics-url-state.ts\n    │   ├── clickhouse-time-utils.ts\n    │   ├── color-scales.ts\n    │   ├── heatmap-utils.ts\n    │   ├── score-formatter.ts\n    │   ├── scoreAnalyticsTransformers.ts\n    │   └── statistics-utils.ts\n    └── server/\n        └── scoreAnalyticsRouter.ts\n\nworker/src/features/\n└── evaluation/              # 评估任务执行\n```\n\n资料来源：[web/src/features/score-analytics/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/score-analytics/README.md)\n\n---\n\n## 使用指南\n\n### 创建评分配置\n\n在项目中定义评分规则，确保数据一致性：\n\n```typescript\nconst scoreConfig = {\n  projectId: \"proj_xxx\",\n  name: \"relevance_score\",\n  dataType: \"NUMERIC\",\n  description: \"衡量生成内容与查询的相关程度\",\n  valueRange: { min: 0, max: 1 }\n};\n```\n\n### 使用评分分析组件\n\n```tsx\nimport { ScoreAnalyticsProvider } from \"@/features/score-analytics\";\nimport { ScoreAnalyticsDashboard } from \"./ScoreAnalyticsDashboard\";\n\nfunction ScoresPage({ projectId }) {\n  return (\n    <ScoreAnalyticsProvider\n      projectId={projectId}\n      score1={{ id: \"score_accuracy\", name: \"accuracy\", source: \"API\", dataType: \"NUMERIC\" }}\n      objectType=\"TRACE\"\n      startDate={startDate}\n      endDate={endDate}\n      interval={{ count: 1, unit: \"day\" }}\n    >\n      <ScoreAnalyticsDashboard />\n    </ScoreAnalyticsProvider>\n  );\n}\n```\n\n---\n\n## 性能注意事项\n\n| 优化项 | 说明 |\n|--------|------|\n| **单次转换** | 所有数据转换在 Hook 中执行一次，避免重复计算 |\n| **记忆化** | 所有转换函数使用 `useMemo` 进行依赖跟踪 |\n| **上下文隔离** | 数据和状态通过 React Context 传递，避免 prop drilling |\n| **ClickHouse 查询** | 大规模分析数据通过 ClickHouse 进行聚合计算 |\n\n---\n\n<a id='p-datasets'></a>\n\n## 数据集管理\n\n### 相关页面\n\n相关主题：[评估系统](#p-evaluations), [追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/domain/dataset-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-items.ts)\n- [packages/shared/src/domain/dataset-run-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-run-items.ts)\n- [packages/shared/src/server/services/DatasetService](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/services/DatasetService)\n- [web/src/features/datasets](https://github.com/langfuse/langfuse/blob/main/web/src/features/datasets)\n- [worker/src/features/experiments](https://github.com/langfuse/langfuse/blob/main/worker/src/features/experiments)\n- [packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)\n- [packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n</details>\n\n# 数据集管理\n\n## 概述\n\n数据集管理（Datasets）是 Langfuse 平台的核心功能之一，用于管理和组织用于评估和测试 LLM 应用的数据集合。数据集由多个数据项组成，每个数据项包含输入、期望输出以及其他元数据，支持在实验和评估流程中被引用和执行。\n\n数据集管理功能覆盖了从数据项的创建、编辑，到运行时与 trace 的关联，再到实验执行和结果评估的完整生命周期。\n\n## 核心数据模型\n\n### DatasetItem（数据集项）\n\n`DatasetItem` 是数据集的基本组成单元，代表数据集中的单个测试样本。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 数据项唯一标识符 |\n| `datasetId` | string | 所属数据集 ID |\n| `input` | JSON | 输入数据，支持任意结构 |\n| `expectedOutput` | JSON (可选) | 期望输出，用于评估 |\n| `metadata` | JSON (可选) | 附加元数据信息 |\n| `sourceTraceId` | string (可选) | 来源 trace ID |\n| `sourceObservationId` | string (可选) | 来源 observation ID |\n| `createdAt` | DateTime | 创建时间 |\n| `updatedAt` | DateTime | 更新时间 |\n\n资料来源：[packages/shared/src/domain/dataset-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-items.ts)\n\n### DatasetRunItem（数据集运行项）\n\n`DatasetRunItem` 记录数据集在特定实验运行中的执行结果，将数据集项与实际执行产生的 trace 关联起来。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 运行项唯一标识符 |\n| `datasetRunId` | string | 所属实验运行 ID |\n| `datasetItemId` | string | 关联的数据集项 ID |\n| `traceId` | string | 关联的执行 trace ID |\n| `observationId` | string (可选) | 关联的 observation ID |\n| `status` | enum | 执行状态：`success` / `error` / `skipped` |\n| `error` | string (可选) | 错误信息 |\n| `startTime` | DateTime | 开始时间 |\n| `endTime` | DateTime (可选) | 结束时间 |\n| `createdAt` | DateTime | 创建时间 |\n\n资料来源：[packages/shared/src/domain/dataset-run-items.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/domain/dataset-run-items.ts)\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n    subgraph 前端层[\"前端层 (web/src/features/datasets)\"]\n        UI[数据集管理界面]\n        Hooks[React Hooks]\n    end\n\n    subgraph 服务层[\"服务层 (packages/shared)\"]\n        DS[DatasetService]\n        DRS[DatasetRunService]\n    end\n\n    subgraph 数据层[\"数据层\"]\n        PG[(PostgreSQL)]\n        CH[(ClickHouse)]\n    end\n\n    subgraph 实验执行层[\"实验执行层 (worker/src/features/experiments)\"]\n        Executor[实验执行器]\n        Evaluator[评估器]\n    end\n\n    UI --> Hooks\n    Hooks --> DS\n    DS --> DRS\n    DRS --> PG\n    DRS --> CH\n    Executor --> DRS\n    Executor --> Evaluator\n    Evaluator --> CH\n```\n\n### 服务层职责\n\n**DatasetService** 负责数据集的核心业务逻辑：\n\n- 创建和管理数据集\n- 数据集项的 CRUD 操作\n- 数据集与项目（Project）的关联管理\n\n**DatasetRunService** 负责实验运行的生命周期：\n\n- 管理实验运行的创建和状态\n- 关联数据集项与执行 trace\n- 记录执行结果和评估数据\n\n## 实验与评估\n\n### 实验系统概述\n\nLangfuse 的实验系统（Experiments）与数据集管理紧密集成，支持以下核心功能：\n\n1. **数据集选择**：从现有数据集中选择运行的数据项\n2. **变量注入**：将数据集项的输入注入到 prompt 模板中\n3. **批量执行**：对数据集中的所有项执行推理\n4. **结果收集**：收集执行产生的 trace 和 observation\n5. **评估计算**：基于预设的评分标准计算评估分数\n\n资料来源：[worker/src/features/experiments](https://github.com/langfuse/langfuse/blob/main/worker/src/features/experiments)\n\n### 实验运行流程\n\n```mermaid\ngraph LR\n    A[启动实验] --> B[加载数据集项]\n    B --> C{遍历数据项}\n    C -->|存在未处理项| D[注入变量到 Prompt]\n    D --> E[执行 LLM 调用]\n    E --> F[创建 Trace]\n    F --> G[记录 DatasetRunItem]\n    G --> H{评估分数}\n    H --> I[计算评分]\n    I --> C\n    C -->|处理完成| J[生成实验报告]\n```\n\n### 评估数据存储\n\n评估相关的分数数据存储在 ClickHouse 中，支持高效的查询和分析：\n\n- 实验运行的分数数据通过 `SeederOrchestrator` 批量插入\n- 支持环境（environment）过滤：`production`、`development`、`staging`\n- 支持按数据集和实验运行进行聚合查询\n\n资料来源：[packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)\n\n## API 接口\n\n### 评分接口版本\n\nLangfuse 为评分（Scores）功能提供了 v1 和 v2 两个 API 版本：\n\n| 特性 | v1 API | v2 API |\n|------|--------|--------|\n| traceId | 必需 | 可选 |\n| sessionId | 不支持 | 支持 |\n| 数据集运行评分 | 支持 | 支持 |\n| 适用对象 | 仅 trace 级别 | trace、session、数据集运行 |\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n### 核心 API 端点\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/api/v2/datasets` | POST | 创建数据集 |\n| `/api/v2/datasets/:id/items` | POST | 添加数据集项 |\n| `/api/v2/datasets/:id/items` | GET | 获取数据集项列表 |\n| `/api/v2/datasets/:id/run` | POST | 创建实验运行 |\n| `/api/v2/datasets/:id/run/:runId/results` | GET | 获取实验运行结果 |\n\n## 前端组件\n\n前端数据集管理功能位于 `web/src/features/datasets` 目录，提供以下核心功能：\n\n- 数据集列表展示和搜索\n- 数据集项的添加、编辑、删除\n- 实验运行的历史记录查看\n- 实验结果的可视化展示\n\n### 数据集列表页面\n\n数据集列表页面提供以下功能：\n\n- 按名称、环境过滤数据集\n- 查看数据集项数量\n- 快速操作入口（运行实验、导出数据）\n\n### 数据集详情页面\n\n数据集详情页面展示：\n\n- 数据集基本信息（名称、描述、创建时间）\n- 数据集项列表（支持分页）\n- 实验运行历史\n- 评估分数统计\n\n## 数据流转\n\n```mermaid\ngraph TD\n    subgraph 数据录入\n        UserInput[用户录入]\n        Import[批量导入]\n    end\n\n    subgraph 数据存储\n        PG[(PostgreSQL<br/>数据集元数据)]\n        CH[(ClickHouse<br/>运行时数据)]\n    end\n\n    subgraph 评估执行\n        Experiment[实验]\n        LLM[LLM 调用]\n    end\n\n    subgraph 结果分析\n        ScoreUI[分数展示]\n        TraceView[Trace 详情]\n    end\n\n    UserInput --> PG\n    Import --> PG\n    Experiment --> LLM\n    LLM --> PG\n    LLM --> CH\n    Experiment --> CH\n    CH --> ScoreUI\n    PG --> TraceView\n```\n\n## 环境与隔离\n\n### 多环境支持\n\n数据集支持环境隔离，确保不同环境（生产、开发、测试）的数据相互独立：\n\n- `production`：生产环境数据\n- `development`：开发环境数据\n- `staging`：预发布环境数据\n\n### 数据隔离策略\n\n| 环境 | 数据来源 | 访问权限 |\n|------|----------|----------|\n| production | 正式 LLM 调用 | 仅生产用户 |\n| development | 测试 LLM 调用 | 开发团队 |\n| staging | 预发布测试 | 测试团队 |\n\n资料来源：[packages/shared/scripts/seeder/utils/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/scripts/seeder/utils/README.md)\n\n## 最佳实践\n\n### 数据集组织\n\n1. **按用途分类**：将用于不同目的的数据集分开管理\n2. **版本控制**：对重要数据集进行版本标记\n3. **元数据丰富**：为数据项添加充分的元数据，便于筛选和分析\n\n### 实验设计\n\n1. **小规模测试**：先在小数据集上验证实验逻辑\n2. **变量控制**：确保对比实验仅改变目标变量\n3. **结果复现**：记录实验参数，便于复现结果\n\n### 评估配置\n\n1. **选择合适的评分标准**：根据业务需求选择或自定义评分函数\n2. **设置合理的阈值**：避免过于宽松或严格的评估标准\n3. **定期校准**：随着 LLM 版本更新，重新校准评估标准\n\n## 相关模块\n\n| 模块 | 位置 | 说明 |\n|------|------|------|\n| 数据集服务 | `packages/shared/src/server/services/DatasetService` | 后端数据集业务逻辑 |\n| 数据集项领域模型 | `packages/shared/src/domain/dataset-items.ts` | 数据集项数据模型 |\n| 运行项领域模型 | `packages/shared/src/domain/dataset-run-items.ts` | 实验运行项数据模型 |\n| 前端功能 | `web/src/features/datasets` | 前端数据集管理界面 |\n| 实验执行 | `worker/src/features/experiments` | 实验执行引擎 |\n\n---\n\n<a id='p-queues'></a>\n\n## 队列系统\n\n### 相关页面\n\n相关主题：[系统架构](#p-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/shared/src/server/redis/ingestionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/ingestionQueue.ts)\n- [packages/shared/src/server/redis/evalExecutionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/evalExecutionQueue.ts)\n- [packages/shared/src/server/redis/batchActionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/batchActionQueue.ts)\n- [packages/shared/src/server/queues.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/queues.ts)\n- [worker/src/queues](https://github.com/langfuse/langfuse/blob/main/worker/src/queues)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n</details>\n\n# 队列系统\n\n## 概述\n\nLangfuse 的队列系统是基于 Redis 和 BullMQ 构建的消息队列基础设施，负责处理异步任务、事件摄取、评估执行和批量操作。该系统采用生产者和消费者模式，通过队列解耦服务间的通信，提高系统的可扩展性和可靠性。\n\n队列系统在 Langfuse 架构中扮演核心角色，主要承担以下职责：\n\n- **事件摄取**：处理来自 SDK 和 OTEL 协议的事件数据\n- **评估执行**：管理评估任务的异步执行\n- **批量操作**：处理需要批量处理的后台任务\n- **事件重放**：支持从 S3 重新导入历史事件\n\n## 架构设计\n\nLangfuse 采用多队列架构，不同类型的任务使用独立的队列，每个队列由专门的消费者处理器处理。\n\n```mermaid\ngraph TD\n    subgraph \"生产者\"\n        SDK[Langfuse SDK]\n        OTEL[OTEL Protocol]\n        API[API Server]\n    end\n\n    subgraph \"队列层\"\n        IQ[IngestionQueue<br/>摄取队列]\n        OIQ[OtelIngestionQueue<br/>OTEL摄取队列]\n        ISQ[IngestionSecondaryQueue<br/>摄取次级队列]\n        EEQ[EvalExecutionQueue<br/>评估执行队列]\n        BAQ[BatchActionQueue<br/>批量操作队列]\n    end\n\n    subgraph \"消费者\"\n        Worker[Worker Service]\n    end\n\n    SDK --> IQ\n    OTEL --> OIQ\n    API --> EEQ\n    API --> BAQ\n    \n    IQ --> Worker\n    OIQ --> Worker\n    ISQ --> Worker\n    EEQ --> Worker\n    BAQ --> Worker\n\n    Worker --> Redis[(Redis)]\n```\n\n## 队列类型\n\n### 摄取队列 (IngestionQueue)\n\n摄取队列是 Langfuse 最核心的队列，负责处理来自客户端 SDK 的事件数据。事件类型包括 traces、generations、scores、evals 等。\n\n| 属性 | 说明 |\n|------|------|\n| 队列名称 | `ingestion` |\n| 优先级 | 高 |\n| 并发处理 | 支持多worker并发消费 |\n| 重试机制 | 支持指数退避重试 |\n| 数据存储 | Redis |\n\n**事件格式示例**：\n\n```json\n{\n  \"projectId\": \"project-123\",\n  \"orgId\": \"org-456\",\n  \"eventType\": \"trace-create\",\n  \"body\": { /* 事件数据 */ }\n}\n```\n\n资料来源：[packages/shared/src/server/redis/ingestionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/ingestionQueue.ts)\n\n### OTEL 摄取队列 (OtelIngestionQueue)\n\n专门处理 OpenTelemetry 协议格式的事件，采用特定的文件存储路径格式。\n\n**S3 文件路径格式**：\n\n```\notel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json\n```\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n### 摄取次级队列 (IngestionSecondaryQueue)\n\n作为摄取队列的补充队列，用于处理需要二次处理的事件或分流部分摄取负载。\n\n### 评估执行队列 (EvalExecutionQueue)\n\n负责调度和管理评估任务的执行。当用户触发评估操作时，评估任务被加入此队列，由专门的评估工作器异步处理。\n\n| 属性 | 说明 |\n|------|------|\n| 队列名称 | `eval-execution` |\n| 优先级 | 中 |\n| 任务类型 | 异步评估计算 |\n| 超时处理 | 支持任务超时配置 |\n\n资料来源：[packages/shared/src/server/redis/evalExecutionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/evalExecutionQueue.ts)\n\n### 批量操作队列 (BatchActionQueue)\n\n处理需要批量执行的系统操作，如批量更新、批量删除等后台任务。\n\n| 属性 | 说明 |\n|------|------|\n| 队列名称 | `batch-action` |\n| 优先级 | 低 |\n| 批处理大小 | 可配置 |\n| 事务支持 | 支持批量事务 |\n\n资料来源：[packages/shared/src/server/redis/batchActionQueue.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/redis/batchActionQueue.ts)\n\n## 队列配置\n\nLangfuse 在中央配置文件 `queues.ts` 中定义所有队列的默认配置和行为。\n\n```typescript\n// packages/shared/src/server/queues.ts 中的典型配置结构\ninterface QueueConfig {\n  name: string;\n  concurrency: number;\n  maxRetries: number;\n  backoff: {\n    type: 'exponential' | 'fixed';\n    delay: number;\n  };\n  removeOnComplete: boolean | number;\n  removeOnFail: boolean | number;\n}\n```\n\n资料来源：[packages/shared/src/server/queues.ts](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/queues.ts)\n\n## 消费者与工作器\n\n### Worker 服务架构\n\nWorker 服务运行在独立的进程中，通过 Redis 连接队列并消费消息。每个队列类型对应专门的处理逻辑。\n\n```mermaid\ngraph LR\n    subgraph \"Worker 进程\"\n        subgraph \"处理器\"\n            IQH[IngestionHandler]\n            OIQH[OtelHandler]\n            EEQH[EvalHandler]\n            BAH[BatchHandler]\n        end\n        \n        subgraph \"队列连接\"\n            R[Redis BullMQ]\n        end\n    end\n\n    IQH --> R\n    OIQH --> R\n    EEQH --> R\n    BAH --> R\n```\n\n### 处理器职责\n\n| 处理器 | 队列 | 主要功能 |\n|--------|------|----------|\n| IngestionHandler | IngestionQueue | 解析事件、存储ClickHouse、触发后续处理 |\n| OtelHandler | OtelIngestionQueue | 处理OTEL格式事件、文件下载与解析 |\n| EvalHandler | EvalExecutionQueue | 执行评估计算、存储评估结果 |\n| BatchHandler | BatchActionQueue | 执行批量数据库操作 |\n\n资料来源：[worker/src/queues](https://github.com/langfuse/langfuse/blob/main/worker/src/queues)\n\n## 事件重放系统\n\nLangfuse 提供了事件重放脚本，允许从 S3 重新导入历史事件到队列系统。\n\n### replayIngestionEventsV2\n\n最新版本的事件重放工具，提供完整的事件重放功能。\n\n**主要特性**：\n\n- 支持从 S3 读取历史事件\n- 支持增量重放和断点续传\n- 内置速率限制和重试机制\n- 支持批量并发请求\n\n**命令行参数**：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--input` | - | CSV文件路径 |\n| `--batch-size` | 500 | 每次API请求的key数量 |\n| `--concurrency` | 4 | 最大并发API请求数 |\n| `--rate-limit` | 50 | 每秒最大请求数 |\n| `--dry-run` | false | 仅解析验证，不发送请求 |\n| `--resume` | false | 从上次断点继续 |\n\n**环境变量**：\n\n| 变量 | 说明 |\n|------|------|\n| `LANGFUSE_HOST` | 目标Langfuse实例URL |\n| `ADMIN_API_KEY` | 管理员API认证密钥 |\n\n**进度追踪与错误处理**：\n\n- **进度日志**：每批次处理后记录进度（如 `[1200/45000] 2.7% — 498 queued, 2 skipped`）\n- **检查点**：每批成功处理后写入检查点文件到CSV同目录，使用 `--resume` 可从断点继续\n- **速率限制**：尊重本地 `--rate-limit` 配置，对429响应使用指数退避\n- **重试机制**：临时错误（429、5xx）最多重试3次，永久错误（其他4xx）记录并跳过\n- **错误日志**：失败记录追加到输入文件同目录的 `errors.csv`\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n### v1 与 v2 版本对比\n\n| 特性 | v1 | v2 |\n|------|----|----|\n| 基础设施访问 | Redis、ClickHouse、PostgreSQL、S3 | 仅需Langfuse Host URL |\n| 配置复杂度 | 需完整repo克隆和环境配置 | 只需 tsx 运行 + 环境变量 |\n| 事件投递 | 直接BullMQ addBulk到Redis | HTTP POST到管理API |\n| 断点续传 | 手动（分割文件、重跑） | 内置检查点/续传 |\n| 速率限制 | 无（可能压垮Redis） | 客户端+服务端双重限速 |\n\n## 事件转换\n\n重放脚本支持两种 S3 key 格式的转换：\n\n### 标准格式\n\n路径：`{projectId}/{type}/{eventBodyId}/{eventId}.json`\n\n转换结果：\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\" }\n  },\n  \"data\": {\n    \"eventBodyId\": \"<eventBodyId>\",\n    \"fileKey\": \"<eventId>\",\n    \"type\": \"<type>-create\"\n  }\n}\n```\n\n投递到 `IngestionSecondaryQueue`。\n\n### OTEL 格式\n\n路径：`otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json`\n\n转换结果：\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\", \"accessLevel\": \"project\" }\n  },\n  \"data\": {\n    \"fileKey\": \"otel/<projectId>/<yyyy>/<mm>/<dd>/<hh>/<mm>/<eventId>.json\"\n  }\n}\n```\n\n投递到 `OtelIngestionQueue`。\n\n## 管理员 API 端点\n\n### POST /api/admin/ingestion-replay\n\n接受批量 S3 key 并将其排队等待重新处理。\n\n**认证方式**：`Authorization: Bearer {ADMIN_API_KEY}` 头，由 `AdminApiAuthService` 验证。\n\n**请求格式**：\n```json\n{\n  \"keys\": [\n    \"projectId/trace/eventBodyId/eventId.json\",\n    \"otel/projectId/2025/07/09/14/30/some-uuid.json\"\n  ]\n}\n```\n\n**响应格式**：\n```json\n{\n  \"queued\": 498,\n  \"skipped\": 2,\n  \"errors\": []\n}\n```\n\n**状态码说明**：\n\n| 状态码 | 含义 |\n|--------|------|\n| 200 | 批次已接受（检查 `skipped`/`errors` 了解部分失败） |\n| 401 | 缺少或无效的 `ADMIN_API_KEY` |\n| 400 | 请求体格式错误 |\n| 429 | 速率限制，等待退避后重试 |\n\n## 性能优化\n\n队列系统采用多种策略确保高性能：\n\n### 并发处理\n\n- 不同队列可独立配置并发数\n- Worker 支持水平扩展，多实例并行消费\n- 基于 Redis 的队列提供低延迟的消息传递\n\n### 重试机制\n\n```mermaid\ngraph TD\n    A[消息处理失败] --> B{错误类型}\n    B -->|临时错误 429/5xx| C[指数退避重试]\n    B -->|永久错误 4xx| D[记录并跳过]\n    C --> E[重试次数 < 3?]\n    E -->|是| A\n    E -->|否| D\n```\n\n### 资源管理\n\n- 完成或失败的消息自动清理（可配置保留策略）\n- 死信队列处理长时间失败的消息\n- 内存敏感操作使用流式处理\n\n## 监控与调试\n\n### 本地调试工具\n\n事件重放脚本提供进度追踪功能：\n\n```bash\n# 运行脚本会输出类似：\n[1200/45000] 2.7% — 498 queued, 2 skipped\n```\n\n### 检查点文件\n\n脚本在每次批量处理成功后保存检查点：\n\n```\n./worker/events.csv\n./worker/events.csv.checkpoint  # 存储当前行偏移量\n```\n\n### 错误日志\n\n处理失败的事件记录到 `errors.csv`：\n\n```csv\ns3_key,error_message,timestamp\nprojectId/trace/xxx.json,Rate limited,2025-07-09T10:30:00Z\n```\n\n## 最佳实践\n\n### 生产环境部署\n\n1. **队列隔离**：不同环境的队列使用不同的 Redis 实例或键前缀\n2. **监控告警**：配置队列深度、处理延迟、失败率的监控\n3. **优雅关闭**：Worker 支持优雅关闭，确保处理中的任务完成\n\n### 故障恢复\n\n1. **启用检查点**：长时间运行的批量任务使用断点续传\n2. **死信处理**：定期检查死信队列，分析失败原因\n3. **数据校验**：重放前验证事件格式，避免格式错误导致处理失败\n\n### 容量规划\n\n- 根据峰值吞吐量配置 Worker 并发数\n- 监控队列积压情况，动态扩展 Worker\n- 评估 Redis 内存使用，预留足够空间\n\n## 相关文档\n\n- [Worker 服务文档](../worker/README.md)\n- [事件摄取系统](./ingestion.md)\n- [评估执行系统](./evaluation.md)\n- [ClickHouse 存储](./clickhouse.md)\n\n---\n\n<a id='p-api'></a>\n\n## API 系统\n\n### 相关页面\n\n相关主题：[追踪系统](#p-tracing)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [fern/apis/server/definition](https://github.com/langfuse/langfuse/blob/main/fern/apis/server/definition)\n- [fern/apis/client/definition](https://github.com/langfuse/langfuse/blob/main/fern/apis/client/definition)\n- [packages/shared/src/server/ingestion](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/server/ingestion)\n- [web/src/features/public-api](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api)\n- [packages/shared/src/features/scores/interfaces](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces)\n- [worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n</details>\n\n# API 系统\n\n## 概述\n\nLangfuse 的 API 系统是一个多层架构，支持数据摄取、公共 API 接口、客户端 SDK 以及服务端内部调用。该系统采用 Fern 进行 API 定义和类型生成，实现了服务端和客户端的双向代码生成，确保 API 的一致性和类型安全。\n\nAPI 系统主要包含以下几个核心组成部分：\n\n- **摄取 API (Ingestion API)**：接收来自 SDK 和集成工具的事件数据\n- **公共 API (Public API)**：面向外部开发者的高层 REST 接口\n- **客户端 SDK API**：Python 和 JavaScript/TypeScript SDK 使用的接口\n- **服务端定义 API**：内部服务端使用的 API 定义\n\n资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)\n\n---\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TD\n    subgraph 外部客户端\n        A[Python SDK]\n        B[JS/TS SDK]\n        C[直接 HTTP 请求]\n    end\n    \n    subgraph API 层\n        D[摄取 API]\n        E[公共 API]\n        F[Admin API]\n    end\n    \n    subgraph 服务端组件\n        G[Next.js API Routes]\n        H[BullMQ Queues]\n        I[Prisma ORM]\n    end\n    \n    subgraph 数据存储\n        J[(PostgreSQL)]\n        K[(ClickHouse)]\n        L[(Redis)]\n    end\n    \n    A --> D\n    B --> D\n    C --> D\n    C --> E\n    D --> H\n    H --> I\n    I --> J\n    I --> K\n    I --> L\n    E --> G\n    G --> I\n```\n\n### API 版本策略\n\nLangfuse 采用双版本 API 策略，同时维护 v1 和 v2 两个版本的 API：\n\n| 版本 | 状态 | 说明 |\n|------|------|------|\n| v1 | 继续支持 | 遗留 API，聚焦于 trace 级别 |\n| v2 | 当前版本 | 支持 traces、sessions 及更多功能 |\n\n**关键差异**：在 GET API 中，v1 需要 `traceId` 参数且仅支持 trace 级别分数；v2 将 `traceId` 设为可选，并新增 `sessionId` 支持。\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## 摄取 API (Ingestion API)\n\n### 功能概述\n\n摄取 API 是 Langfuse 数据入口点，负责接收来自各类 SDK 和集成工具的事件数据，包括 traces、generations、spans、events 等。\n\n### 支持的事件类型\n\n摄取 API 支持多种事件类型的批量摄取：\n\n```typescript\n// 标准事件结构\ninterface IngestionEvent {\n  eventBodyId: string;      // 事件体 ID\n  type: EventType;          // 事件类型\n  timestamp: Date;         // 事件时间戳\n  metadata?: Record<string, unknown>;\n}\n```\n\n### S3 事件回放\n\n对于大规模事件重放场景，Langfuse 提供了基于 S3 的事件回放功能：\n\n```mermaid\ngraph LR\n    A[S3 Access Logs] --> B[CSV 文件]\n    B --> C[replayIngestionEventsV2]\n    C --> D{批量处理}\n    D -->|500 条/批| E[POST /api/admin/ingestion-replay]\n    E --> F[摄取队列]\n    F --> G[ClickHouse/PostgreSQL]\n```\n\n### 回放脚本参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--csv` | 必需 | CSV 文件路径 |\n| `--batch-size` | 500 | 每批 API 请求的键数量 |\n| `--concurrency` | 4 | 最大并行 API 请求数 |\n| `--rate-limit` | 50 | 最大每秒请求数 |\n| `--dry-run` | false | 仅解析验证不发送 |\n| `--resume` | false | 从上次检查点继续 |\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n---\n\n## 公共 API (Public API)\n\n### 路由创建规范\n\nLangfuse 的公共 API 路由遵循严格的实现规范：\n\n```typescript\n// 标准 API 路由结构\nimport { withMiddleware } from \"@/src/apiMiddleware\";\nimport { createAuthedAPIRoute } from \"@/src/lib/createAuthedAPIRoute\";\n\n// 使用 withMiddleware 包装\nexport default withMiddleware(\n  createAuthedAPIRoute({\n    // Zod 类型定义\n    request: z.object({...}),\n    response: z.object({...}),\n    // 业务逻辑\n    handler: async (req, res) => {\n      // 实现代码\n    }\n  })\n);\n```\n\n### 类型定义位置\n\n所有公共 API 的类型定义位于 `packages/shared/src/features/public-api/types/` 目录：\n\n- 使用 `coerce` 处理日期等原始类型转换\n- 对不应返回额外属性的对象使用 `strict()` 模式\n- 使用 `validateZodSchema` 在 API 路由中验证响应类型\n\n### API 响应验证\n\n```typescript\nimport { validateZodSchema } from \"@/src/lib/validateZodSchema\";\n\n// 在 API 路由中验证响应\nconst validatedResponse = validateZodSchema(response, ResponseSchema);\n```\n\n### 错误处理\n\n公共 API 使用 `shared/src/errors` 中定义的错误类，这些错误会自动转换为相应的 HTTP 状态码：\n\n```typescript\nimport { ValidationError, NotFoundError } from \"@/src/errors\";\n\n// 抛出错误会被自动转换\nthrow new ValidationError(\"Invalid input\");\nthrow new NotFoundError(\"Resource not found\");\n```\n\n资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)\n\n---\n\n## Fern API 定义\n\n### 概述\n\nLangfuse 使用 Fern 进行 API 定义，实现服务端和客户端的代码生成。\n\n### 目录结构\n\n```\nfern/\n├── apis/\n│   ├── server/\n│   │   └── definition/     # 服务端 API 定义\n│   └── client/\n│       └── definition/      # 客户端 SDK API 定义\n```\n\n### 代码生成流程\n\n```mermaid\ngraph TD\n    A[Fern 定义文件] --> B[fern generate --api server]\n    A --> C[fern generate --api client]\n    B --> D[服务端类型]\n    C --> E[Python SDK 类型]\n    C --> F[JS/TS SDK 类型]\n```\n\n### 生成命令\n\n```bash\n# 生成服务端 API\nfern generate --api server\n\n# 生成客户端 API\nfern generate --api client\n\n# 提交生成的变更\ngit commit -m \"chore: update api reference\"\n```\n\n### API Reference 文档\n\n生成的 API Reference 会被添加到 Fern 文档中，包含 `docs` 属性用于描述接口用途和参数说明。\n\n资料来源：[web/src/features/public-api/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/public-api/README.md)\n\n---\n\n## 分数接口 (Score Interfaces)\n\n### 目录结构\n\n```\npackages/shared/src/features/scores/interfaces/\n├── api/\n│   ├── v1/                  # v1 API 类型\n│   │   ├── endpoints.ts\n│   │   ├── schemas.ts\n│   │   └── validation.ts\n│   ├── v2/                  # v2 API 类型\n│   │   ├── endpoints.ts\n│   │   ├── schemas.ts\n│   │   └── validation.ts\n│   └── shared.ts            # 通用类型\n├── application/             # 应用层验证\n│   └── validation.ts\n├── ingestion/               # 摄取端点类型\n│   └── validation.ts\n└── ui/                      # UI 组件类型\n    └── types.ts\n```\n\n### API 版本对比\n\n| 特性 | v1 API | v2 API |\n|------|--------|--------|\n| traceId 参数 | 必需 | 可选 |\n| sessionId 支持 | ❌ | ✅ |\n| 支持的分数类型 | trace 级别 | trace、session、dataset run |\n\n### 验证层次\n\n分数接口采用多层验证架构：\n\n1. **API 层验证** (`api/v1/validation.ts`, `api/v2/validation.ts`)：处理请求参数验证\n2. **应用层验证** (`application/validation.ts`)：业务逻辑验证\n3. **摄取层验证** (`ingestion/validation.ts`)：数据摄取时的验证\n\n资料来源：[packages/shared/src/features/scores/interfaces/README.md](https://github.com/langfuse/langfuse/blob/main/packages/shared/src/features/scores/interfaces/README.md)\n\n---\n\n## Admin API\n\n### 认证机制\n\nAdmin API 使用 `Authorization: Bearer {ADMIN_API_KEY}` 头部进行认证：\n\n```bash\ncurl -X POST https://your-langfuse.com/api/admin/ingestion-replay \\\n  -H \"Authorization: Bearer $ADMIN_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"keys\": [\"projectId/trace/eventBodyId/eventId.json\"]}'\n```\n\n### 端点：摄取回放\n\n**端点**：`POST /api/admin/ingestion-replay`\n\n**请求格式**：\n\n```json\n{\n  \"keys\": [\n    \"projectId/trace/eventBodyId/eventId.json\",\n    \"otel/projectId/2025/07/09/14/30/some-uuid.json\"\n  ]\n}\n```\n\n**响应格式**：\n\n```json\n{\n  \"queued\": 498,\n  \"skipped\": 2,\n  \"errors\": []\n}\n```\n\n### 响应状态码\n\n| 状态码 | 含义 |\n|--------|------|\n| 200 | 批量已接受（检查 `skipped`/`errors` 获取部分失败信息） |\n| 401 | 缺少或无效的 `ADMIN_API_KEY` |\n| 400 | 请求体格式错误 |\n| 429 | 速率限制，请稍后重试 |\n\n### 事件转换\n\n**标准键格式**：`{projectId}/{type}/{eventBodyId}/{eventId}.json`\n\n转换后的队列负载：\n\n```json\n{\n  \"authCheck\": {\n    \"validKey\": true,\n    \"scope\": { \"projectId\": \"<projectId>\" }\n  },\n  \"data\": {\n    \"eventBodyId\": \"<eventBodyId>\",\n    \"fileKey\": \"<eventId>\",\n    \"type\": \"<type>-create\"\n  }\n}\n```\n\n**OTEL 键格式**：`otel/{projectId}/{yyyy}/{mm}/{dd}/{hh}/{mm}/{eventId}.json`\n\n资料来源：[worker/src/scripts/replayIngestionEventsV2/README.md](https://github.com/langfuse/langfuse/blob/main/worker/src/scripts/replayIngestionEventsV2/README.md)\n\n---\n\n## SDK API\n\n### Python SDK\n\nPython SDK 使用从 Fern 生成的类型和接口，提供与 Langfuse 服务器交互的便捷方法：\n\n```python\nfrom langfuse import Langfuse\n\nclient = Langfuse(\n    public_key=\"pk-lf-xxx\",\n    secret_key=\"sk-lf-xxx\",\n    host=\"https://cloud.langfuse.com\"\n)\n\n# 创建 trace\ntrace = client.trace.create(\n    name=\"my-trace\",\n    metadata={\"user_id\": \"123\"}\n)\n```\n\n### JavaScript/TypeScript SDK\n\nJS/TS SDK 采用相同的 Fern 定义，确保与 Python SDK 行为一致：\n\n```typescript\nimport { Langfuse } from \"langfuse-js\";\n\nconst langfuse = new Langfuse({\n  publicKey: \"pk-lf-xxx\",\n  secretKey: \"sk-lf-xxx\",\n  baseUrl: \"https://cloud.langfuse.com\"\n});\n\n// 创建 trace\nconst trace = await langfuse.trace.create({\n  name: \"my-trace\",\n  metadata: { userId: \"123\" }\n});\n```\n\n---\n\n## 认证与授权\n\n### 认证方式\n\nLangfuse API 支持多种认证方式：\n\n| 认证方式 | 适用场景 | 说明 |\n|----------|----------|------|\n| API Keys | SDK 和直接调用 | public_key + secret_key |\n| Basic Auth | MCP Server | base64(publicKey:secretKey) |\n| Bearer Token | Admin API | ADMIN_API_KEY |\n\n### Basic Auth 编码\n\n```bash\n# 生成 Basic Auth Token\necho -n \"pk-lf-your-public-key:sk-lf-your-secret-key\" | base64\n```\n\n### MCP Server 认证\n\nMCP Server 使用 Basic Auth 认证：\n\n```typescript\n{\n  auth: {\n    authType: \"BasicAuth\",\n    accessLevel: \"project\",\n    publicKey: \"pk-lf-...\"\n  }\n}\n```\n\n资料来源：[web/src/features/mcp/README.md](https://github.com/langfuse/langfuse/blob/main/web/src/features/mcp/README.md)\n\n---\n\n## 测试策略\n\n### API 响应验证测试\n\n使用 `makeZodVerifiedAPICall` 测试工具验证 API 响应：\n\n```typescript\nimport { makeZodVerifiedAPICall } from \"@/test/server\";\n\nit(\"should return correct response structure\", async () => {\n  const response = await makeZodVerifiedAPICall(\n    \"GET\",\n    \"/api/public-api/endpoint\",\n    {},\n    ResponseSchema\n  );\n  \n  expect(response.data).toBeDefined();\n});\n```\n\n### 测试覆盖要求\n\n- 所有标准用例必须有测试覆盖\n- 使用 `strict()` 模式的对象响应，测试工具会在额外属性时抛出错误\n- 生产环境会记录响应包含额外属性的错误\n\n---\n\n## 最佳实践\n\n### API 路由开发流程\n\n1. 在 `features/public-api/types/` 中添加 Zod 类型定义\n2. 使用 `coerce` 处理日期等需要转换的类型\n3. 在 API 路由中使用 `validateZodSchema` 验证响应\n4. 添加完整的测试用例\n5. 运行 `fern generate` 更新 SDK 类型\n6. 提交所有变更\n\n### 错误处理规范\n\n- 优先使用 `shared/src/errors` 中预定义的错误类\n- 避免直接返回原始错误信息给客户端\n- 在生产环境记录详细的错误日志\n\n### 性能考虑\n\n- 批量摄取事件以减少网络开销\n- 使用检查点机制支持长时间运行的批处理任务\n- 实施客户端和服务器端速率限制\n\n---\n\n## 相关链接\n\n- [Fern 文档](https://buildwithfern.com/)\n- [Zod 验证库](https://zod.dev/)\n- [Langfuse SDK 文档](https://langfuse.com/docs/sdk)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langfuse/langfuse\n\n摘要：发现 17 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：bug: Using client with context manager breaks the scoring。\n\n## 1. 安装坑 · 来源证据：bug: Using client with context manager breaks the scoring\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Using client with context manager breaks the scoring\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5afee24537ba47369cc4621f7fb18122 | https://github.com/langfuse/langfuse/issues/8138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：bug: unnamed trace name in Langfuse UI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: unnamed trace name in Langfuse UI\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a219c99fe99c4b7dab002e2b3a6296c2 | https://github.com/langfuse/langfuse/issues/13416 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8657d86702904e90b9d448770e618256 | https://github.com/langfuse/langfuse/issues/8173 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cff1b1d1a1ca4eb892563c33d3aa62e9 | https://github.com/langfuse/langfuse/issues/8156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49a69075a1c346789a28db93c9ec6f3f | https://github.com/langfuse/langfuse/issues/13601 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v3.169.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.169.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_864f213fd7694eba9a4d2fe2bb9267ab | https://github.com/langfuse/langfuse/releases/tag/v3.169.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v3.172.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.172.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14588986ba9945eeb40cbc0508e3fed0 | https://github.com/langfuse/langfuse/releases/tag/v3.172.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v3.173.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.173.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7560a954846b4f35aedb74de1291c9a4 | https://github.com/langfuse/langfuse/releases/tag/v3.173.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:642497346 | https://github.com/langfuse/langfuse | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：v3.168.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.168.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_202b4e8c2c1f4b3790315098d1530297 | https://github.com/langfuse/langfuse/releases/tag/v3.168.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：v3.170.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.170.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ed6f994e1424878aa4559a73d72fc52 | https://github.com/langfuse/langfuse/releases/tag/v3.170.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v3.174.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.174.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9cb7b7232ff4cce96f0c020fe48c7f4 | https://github.com/langfuse/langfuse/releases/tag/v3.174.0 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | release_recency=unknown\n\n<!-- canonical_name: langfuse/langfuse; human_manual_source: deepwiki_human_wiki -->\n",
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "Human Manual / 人类版说明书"
    },
    "pitfall_log": {
      "asset_id": "pitfall_log",
      "filename": "PITFALL_LOG.md",
      "markdown": "# Pitfall Log / 踩坑日志\n\n项目：langfuse/langfuse\n\n摘要：发现 17 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：bug: Using client with context manager breaks the scoring。\n\n## 1. 安装坑 · 来源证据：bug: Using client with context manager breaks the scoring\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Using client with context manager breaks the scoring\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5afee24537ba47369cc4621f7fb18122 | https://github.com/langfuse/langfuse/issues/8138 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：bug: unnamed trace name in Langfuse UI\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: unnamed trace name in Langfuse UI\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a219c99fe99c4b7dab002e2b3a6296c2 | https://github.com/langfuse/langfuse/issues/13416 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: AsyncStream' object has no attribute 'usage' when integrated with Semantic Kernel and Openlit\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8657d86702904e90b9d448770e618256 | https://github.com/langfuse/langfuse/issues/8173 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: Worker shutdown takes ~1 hour in self hosted kubernetes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cff1b1d1a1ca4eb892563c33d3aa62e9 | https://github.com/langfuse/langfuse/issues/8156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Socket timeout. Expecting data, but didn't receive any in 30000ms on idle BullMQ queues\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49a69075a1c346789a28db93c9ec6f3f | https://github.com/langfuse/langfuse/issues/13601 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v3.169.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.169.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_864f213fd7694eba9a4d2fe2bb9267ab | https://github.com/langfuse/langfuse/releases/tag/v3.169.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v3.172.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.172.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14588986ba9945eeb40cbc0508e3fed0 | https://github.com/langfuse/langfuse/releases/tag/v3.172.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v3.173.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v3.173.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7560a954846b4f35aedb74de1291c9a4 | https://github.com/langfuse/langfuse/releases/tag/v3.173.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:642497346 | https://github.com/langfuse/langfuse | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:642497346 | https://github.com/langfuse/langfuse | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：v3.168.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.168.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_202b4e8c2c1f4b3790315098d1530297 | https://github.com/langfuse/langfuse/releases/tag/v3.168.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：v3.170.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.170.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ed6f994e1424878aa4559a73d72fc52 | https://github.com/langfuse/langfuse/releases/tag/v3.170.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：v3.174.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.174.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9cb7b7232ff4cce96f0c020fe48c7f4 | https://github.com/langfuse/langfuse/releases/tag/v3.174.0 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:642497346 | https://github.com/langfuse/langfuse | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# langfuse - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langfuse 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p-intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. p-structure：仓库结构。围绕“仓库结构”模拟一次用户任务，不展示安装或运行结果。\n3. p-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. p-database：数据库设计。围绕“数据库设计”模拟一次用户任务，不展示安装或运行结果。\n5. p-tracing：追踪系统。围绕“追踪系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p-intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p-structure\n输入：用户提供的“仓库结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p-database\n输入：用户提供的“数据库设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p-tracing\n输入：用户提供的“追踪系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p-intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / p-structure：Step 2 必须围绕“仓库结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / p-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / p-database：Step 4 必须围绕“数据库设计”形成一个小中间产物，并等待用户确认。\n- Step 5 / p-tracing：Step 5 必须围绕“追踪系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langfuse/langfuse\n- https://github.com/langfuse/langfuse#readme\n- .agents/skills/add-model-price/SKILL.md\n- .agents/skills/agent-setup-maintenance/SKILL.md\n- .agents/skills/analyze-cloud-costs/SKILL.md\n- .agents/skills/backend-dev-guidelines/SKILL.md\n- .agents/skills/changelog-writing/SKILL.md\n- .agents/skills/clickhouse-best-practices/SKILL.md\n- .agents/skills/code-review/SKILL.md\n- .agents/skills/datadog-query-recipes/SKILL.md\n- .agents/skills/debug-issue-with-datadog/SKILL.md\n- .agents/skills/detect-prod-regressions/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langfuse 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
      "title": "Prompt Preview / 安装前试用 Prompt"
    },
    "quick_start": {
      "asset_id": "quick_start",
      "filename": "QUICK_START.md",
      "markdown": "# Quick Start / 官方入口\n\n项目：langfuse/langfuse\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install langfuse\n```\n\n来源：https://github.com/langfuse/langfuse#readme\n\n## 来源\n\n- repo: https://github.com/langfuse/langfuse\n- docs: https://github.com/langfuse/langfuse#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_8c486efe87fd4ad990dc77cbf338b160"
}