Langfuse 使用教程（结合 DeerFlow / ontology-harness）

1. 这门课学什么

学完你能回答：

• 开 / 关追踪、开 / 关远端提示词各改哪几个环境变量，二者是否互相牵连
• 为什么 setup_tracing() 必须早于进程里任何 Langfuse(...)，否则会拒绝启动
• 一次 Run 的开跑 / 续跑 / 重试 / 继续如何落进同一条 Langfuse trace
• 仓库 agent/prompts/*.md 怎样经 sync_prompts.py 进 Langfuse，运行时怎样回退

2. 环境变量怎么配

来源：仓库根 env.example（复制为 .env；真实值不入库）。与 Langfuse 相关的项如下（值留空或占位，勿粘贴真实密钥）：

3. 启动顺序铁律

Langfuse 客户端按 public_key 单例：第一次 Langfuse(...) 的参数（含 mask）生效，之后的构造都拿同一实例。

• agent/tracing.py 的 setup_tracing() 创建带 mask / mask_otel_spans / should_export_span 的客户端
• 若发现 client._mask is not mask，抛 RuntimeError("Langfuse 客户端在 setup_tracing() 之前已被初始化，mask 未生效") —— 拒绝启动
• main.py lifespan：在日志配置、读 config、池校验、记忆校验、upgrade_db() 之后立刻 setup_tracing()，再 setup_mcp() 与构造各 Service（含可能触发 DeerFlow 记忆抽取的路径）
• 进程退出时 lifespan 的 finally 调 shutdown_tracing() 冲刷缓冲

# main.py lifespan（节选，顺序以源码为准）
configure_logging()
app_config = get_app_config()
check_pool_size(app_config)
check_memory_config(app_config)
upgrade_db()
setup_tracing()   # 要早于进程里任何 Langfuse(...)
await setup_mcp()
# …再构造 AgentService / MemoryService 等

4. Trace 怎么串起来（DeerFlow 集成）

4.1 核心模块：agent/tracing.py

SECRET_KEYS 集合（小写匹配）：password、token、access_token、api_key、authorization、database_url、secret_key。

4.2 services/agent.py 的 _prepare

对话 / 续跑不走公开的 DeerFlowClient.stream，而是直接调 agent 的 stream，自行挂 callbacks，并调用 DeerFlow 的 deerflow.tracing.inject_langfuse_metadata 写入 metadata。字段映射（Run / 配置 → Langfuse）：

• 思考进 Langfuse：callback 在中间件之前看到模型原始响应（含 reasoning_content / thinking 块），原样上报便于排查；客户端侧仍丢掉模型层 reasoning 事件
• 模型侧：以 attach_tracing=False 创建，避免绕过图根 callback 另报一份

图 A · 追踪挂载时序（lifespan → 跑图 → 上报）。

sequenceDiagram
  autonumber
  participant Boot as lifespan
  participant TR as tracing.py
  participant AS as agent._prepare
  participant G as Agent图
  participant LF as Langfuse

  Boot->>TR: setup_tracing(mask…)
  Note over Boot,TR: 必须早于任何 Langfuse(...)
  AS->>TR: tracing_callbacks(run_id.hex)
  AS->>AS: inject_langfuse_metadata
  AS->>G: stream + CallbackHandler
  G-->>LF: spans（mask / 降噪后）
  Note over G,LF: 思考可见；凭据 [REDACTED]

5. 提示词怎么管

5.1 一 agent 一文件

• 仓库路径：agent/prompts/<agent_name>.md（文件名 = normalize_agent_name 后的名字）
• Langfuse 上同名 text prompt
• 五个 agent 启动时缺文件或空文件 → 拒绝启动

5.2 build_system_prompt（agent/prompt_assembly.py）

1. 先 read_prompt_file(agent_name) 读仓库（启动校验与失败回退都靠它）
2. 若 local_only 或 LANGFUSE_PROMPT_LOCAL 为真 → 直接返回仓库文本
3. 否则三项凭据齐全时 get_prompt(name, label=PROMPT_LABEL 或 production, type="text", …)
4. 拉不到 / 异常 / fallback → 仓库文件

5.3 scripts/sync_prompts.py

# 首次发布（远端不存在则 create，并标 production）
python scripts/sync_prompts.py

# 已有不同版本：默认跳过；要推仓库内容加 --update
python scripts/sync_prompts.py --update

# 本次新建版本升为 production
python scripts/sync_prompts.py --update --promote

• 需要 LANGFUSE_PUBLIC_KEY / SECRET_KEY / BASE_URL
• 脚本里 Langfuse(..., tracing_enabled=False)，只碰提示词 API
• 内容相同则跳过；已有不同版本且未 --update 则打印提示并跳过

5.4 运行时装配

SystemPromptMiddleware 每次调模型前重新装配：改本地文件后下一次模型调用即生效（无需为提示词重启；改技能白名单等另当别论）。

图 B · 提示词拉取与回退。

flowchart TD
  A["build_system_prompt(agent)"] --> B["读仓库 agent/prompts/name.md"]
  B --> C{"local_only 或 PROMPT_LOCAL?"}
  C -->|是| D["返回仓库文本"]
  C -->|否| E{"三项凭据齐全?"}
  E -->|否| D
  E -->|是| F["get_prompt label=production 等"]
  F -->|成功且非空| G["返回远端文本"]
  F -->|失败 / fallback / 空| D

6. 本地开发推荐流程

1. 默认本地提示词：保持 LANGFUSE_PROMPT_LOCAL=true，改 agent/prompts/*.md 即可验证文案
2. 需要 Trace 时：LANGFUSE_TRACING=true，填 PUBLIC_KEY / SECRET_KEY / BASE_URL（勿提交），确认 shell 无陈旧 export 盖住 .env
3. 不需要 Trace 时：保持 LANGFUSE_TRACING=false；提示词仍可只走本地
4. 要测远端提示词：PROMPT_LOCAL=false，凭据齐全；首次或缺版本时跑 sync_prompts.py，已有差异加 --update，升 production 加 --promote
5. 在 Langfuse UI 查 trace：用 Run 的 trace_id（即 run_id 的 UUID hex）搜索；也可按 session（thread_id）、user（user_id）、tag（含 ontology-wj、环境、模型）筛选
6. 关进程：依赖 lifespan 的 shutdown_tracing() 冲刷，避免尾部 span 丢在缓冲里

7. 和纯 DeerFlow 上游的关系

8. 怎么读代码 / 相关文件地图