Claude Code → Langfuse 数据上报实现说明

基于源码：langfuse_trace/common/langfuse_transcript.py + langfuse_trace/watcher/claude_langfuse_watcher.py
目标读者：想理解「Claude Code 如何把对话变成 Langfuse Trace」的开发者

---

文档索引

章节	文件	内容
0	0_overview.md	方案总览、核心思路、生活类比
1	1_data_source.md	Claude Code jsonl 数据来源与格式
2	2_parse_pipeline.md	增量读取、Turn 切分、子代理发现
3	3_langfuse_emit.md	映射到 Langfuse Trace/Generation/Span
4	4_hook_scheme.md	Hook 方案（langfuse_transcript.py）
5	5_watcher_scheme.md	Watcher 方案（claude_langfuse_watcher.py）
6	6_streaming_mode.md	流式上报机制
7	7_setup_guide.md	环境配置与快速上手
8	8_troubleshooting.md	故障排查

---

一句话总结

Claude Code 把会话过程写成本地 jsonl 文件；本方案旁路读取这些文件，解析为 Turn（用户轮次），再通过 Langfuse SDK v2 上报为 Trace → Generation / Span 树，不修改 Claude Code 本体。

---

两种上报入口

                    ┌─────────────────────────────────┐
                    │   Claude Code 写 session jsonl   │
                    └───────────────┬─────────────────┘
                                    │
              ┌─────────────────────┴─────────────────────┐
              ▼                                           ▼
    ┌─────────────────────┐                   ┌─────────────────────┐
    │ 方案 A: Hook         │                   │ 方案 B: Watcher      │
    │ langfuse_transcript  │                   │ claude_langfuse_watcher│
    │ Stop 事件触发        │                   │ 独立进程轮询 jsonl    │
    └──────────┬──────────┘                   └──────────┬──────────┘
               │                                         │
               └─────────────────┬───────────────────────┘
                                 ▼
                    ┌────────────────────────┐
                    │  共享核心逻辑（同构实现）  │
                    │  解析 + 上报 + 状态管理    │
                    └────────────┬───────────────┘
                                 ▼
                         Langfuse Server

⚠️ 两种方案勿同时启用，否则会重复上报同一 Turn。

---

源码位置

langfuse_trace/
├── common/
│   ├── langfuse_transcript.py      # 核心：解析 + 上报（Hook 入口也用这份）
│   └── langfuse_hook_all_agents.py # 薄封装，re-export langfuse_transcript
├── hook/
│   └── langfuse_hook_all_agents.py # Hook 入口脚本
└── watcher/
    ├── claude_langfuse_watcher.py   # Watcher 入口（逻辑自包含，与 common 同构）
    └── run_watcher.sh              # 常驻启动脚本

langfuse_transcript.py 与 claude_langfuse_watcher.py 的解析/上报函数高度同构；Watcher 在顶部自包含了一份副本，并额外增加了 JsonlWatcher 轮询框架。

---

建议阅读顺序

1. 0_overview.md — 建立全局图景
2. 1_data_source.md + 2_parse_pipeline.md — 理解输入
3. 3_langfuse_emit.md — 理解输出
4. 按你使用的方案读 4 或 5
5. 7_setup_guide.md — 动手配置