用途：这是 langfuse-mcp 的智能体配套技能，用于在 Claude Code 或 Codex 中调试 AI 智能体与 LLM 应用，指导何时使用 Langfuse、优先调用哪个 MCP 工具，以及如何从宽泛的追踪发现推进到具体根因假设。触发场景包括 langfuse、traces、debug AI、find exceptions、set up langfuse、what went wrong、why is it slow、datasets、evaluation sets。
主要能力：提供连接 langfuse-mcp 的设置步骤；覆盖异常分诊、追踪检查、延迟分析、会话、提示词与数据集的操作手册；高价值 MCP 工具速查；指向完整设置与工具参考的链接。建议先用手册，从宽到窄：先定位相关 trace/session/observation，再深入具体失败或慢路径。
使用方式：步骤 1，从 https://cloud.langfuse.com 的 Settings → API Keys 获取凭据；自托管则用实例 URL 作为 LANGFUSE_HOST 并在那里创建密钥。步骤 2，安装 MCP（需 Python 3.10+，CI 验证 3.10 至 3.14）：Claude Code 用 claude mcp add 并配 --scope project 与 LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_HOST 环境变量，命令 uvx langfuse-mcp；Codex CLI 用 codex mcp add langfuse 加同样环境变量。可用 --python 3.14 固定解释器。步骤 3，重启 CLI，用 /mcp 或 codex mcp list 验证。步骤 4，测试 fetch_traces(age=60)。只读模式：langfuse-mcp --read-only 或 LANGFUSE_MCP_READ_ONLY=true，会禁用 create_text_prompt、create_chat_prompt、update_prompt_labels、create_dataset、create_dataset_item、delete_dataset_item。默认输出模式可用 langfuse-mcp --default-output-mode full_json_file 或 LANGFUSE_MCP_DEFAULT_OUTPUT_MODE=full_json_file。
手册示例：查错误用 find_exceptions(age=1440, group_by="file")、find_exceptions_in_file(filepath="src/ai/chat.py", age=1440)、get_exception_details(trace_id="...")；查看交互用 fetch_traces(age=60, user_id="...")、fetch_trace(trace_id="...", include_observations=true)、fetch_observation(observation_id="...")；慢因用 fetch_observations(age=60, type="GENERATION")；用户会话用 get_user_sessions(user_id="...", age=1440)、get_session_details(session_id="...")；数据集与提示词有对应 list/get/create 工具。age 为回溯分钟数，最大 10080（7 天）。
限制：需 Python 3.10+ 与有效凭据；写操作需读写密钥且非只读模式；连接失败先核对凭据、重启 CLI，或独立测试 fetch_traces 判断问题在 MCP。详细参数、过滤语义与响应模式见 references/tool-reference.md，手动设置与排障见 references/setup.md。