SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场braintrust-tracing

braintrust-tracing

智能体与模型

查看项目

更新于 10-15 14:48

技能介绍

Braintrust Tracing for Claude Code 是一套面向 Claude Code 会话的 Braintrust 追踪方案，包含 Hook 架构、子智能体关联与调试方法。

用途 该方案用于将 Claude Code 的会话过程完整记录到 Braintrust 中，形成可查询、可分析的追踪数据，并尝试解决子智能体（sub-agent）追踪的关联问题。

主要能力

  1. 追踪层级：以 Session（task span，root_span_id = session_id）为根，下含多个 Turn（task span），每个 Turn 内包含 LLM span（如 claude-sonnet 模型调用）与 Tool span（如 Read、Edit、Task）。
  2. Hook 事件流：
  • SessionStart：会话开始，创建根 span，字段含 session_id、root_span_id。
  • UserPromptSubmit：用户发送提示，创建 Turn span，字段含 prompt、turn_number。
  • PreToolUse：工具运行前，修改 Task 提示（tool_input.prompt）。
  • PostToolUse：工具运行后，创建工具 span，字段含 tool_name、input、output。
  • Stop：轮次完成，创建 LLM span，字段含 model、tokens、tool_calls。
  • SubagentStop：子智能体结束，不创建 span，携带子智能体的 session_id。
  • SessionEnd：会话结束，最终化根 span，字段含 turn_count、tool_count。
  1. 状态管理：每个会话在 ~/.claude/state/braintrust_sessions/{session_id}.json 保存状态，包含 root_span_id、project_id、turn_count、tool_count、current_turn_span_id、current_turn_start、started、is_subagent 等字段；全局状态位于 ~/.claude/state/braintrust_global.json（缓存 project_id）与 ~/.claude/state/braintrust_hook.log（调试日志）。
  2. 调试与分析命令：可实时查看 Hook 日志、检查会话状态、验证环境变量；通过 scripts/braintrust_analyze.py 列出最近会话、分析上次会话、重放指定会话、查找子智能体追踪（孤立根）。

使用方式

  • 环境变量：TRACE_TO_BRAINTRUST 设为 "true" 启用（必需）；BRAINTRUST_API_KEY 为必需；BRAINTRUST_CC_PROJECT 默认 claude-code；BRAINTRUST_CC_DEBUG 默认 false；BRAINTRUST_API_URL 默认 https://api.braintrust.dev。
  • 关键文件：hooks/common.sh（共享工具、API、状态管理）、session_start.sh、user_prompt_submit.sh、pre_tool_use.sh、post_tool_use.sh、stop_hook.sh、session_end.sh，以及 scripts/braintrust_analyze.py。
  • 调试示例：tail -f ~/.claude/state/braintrust_hook.log；cat ~/.claude/state/braintrust_sessions/*.json | jq -s '.'；uv run python -m runtime.harness scripts/braintrust_analyze.py --sessions 5 / --last-session / --replay <session-id> / --agent-stats。
  • 手动测试 Hook：通过 echo 传入 JSON 并执行对应 .sh 脚本。

适用场景 适用于需要分析 Claude Code 会话、构建智能体运行数据集、排查追踪缺失或状态损坏问题的开发者与团队。

限制与已知问题

  • 子智能体追踪：通过 Task 工具生成的子智能体会创建孤立追踪（新的 root_span_id），与父会话之间没有内置链接。
  • 尝试过但无效的方案：通过 PreToolUse 向 Task 提示注入追踪上下文（SessionStart 只接收会话元数据，不接收提示，注入内容丢失）；SubagentStop 与 PostToolUse 之间的文件交接存在竞态条件；PreToolUse 关联文件方案不可靠。
  • 可行方案：事后匹配。父会话 Task span 含 agentId、totalTokens、totalToolUseCount、content、tool_input.prompt、tool_input.subagent_type 及起止时间戳；子智能体会话含 session_id（等于其孤立追踪的 root_span_id）及起止时间戳。可按时间（Task span 结束 ≈ 子智能体会话结束）、元数据（subagent_type）与 ID（SubagentStop 提供的 session_id）进行离线关联。
  • 架构边界：SessionStart 输入有意保持最小化，不含 prompt、tool_context、task_span_id、parent_span_id，因此无法在 Hook 阶段实时关联。
  • 推荐做法：会话内记录 SubagentStop 的 session_id；会话后导出父与子追踪；在脚本中离线按时间与元数据匹配；不要尝试实时链接。

故障排查要点

  • 无追踪：检查 .claude/settings.local.json 中 TRACE_TO_BRAINTRUST=true、验证 API key、查看日志。
  • 子智能体未链接：属预期行为，使用 --agent-stats 查找活动，按时间或 agentId 关联。
  • 缺失 span：检查 current_turn_span_id、确保 Stop hook 运行、查找日志中的 "Failed to create" 错误。
  • 状态损坏：删除会话状态文件与全局缓存。

其他事实（如具体收费、价格、平台支持范围）暂未提供。