用途:面向 LangChain / LangGraph 事故的排障技能,产出一个自包含的 tar.gz 诊断包(通常 1-10 MB),让第二位工程师无需现场终端即可复现失败。
主要能力:
- 环境清单:记录 Python、平台、CPU 数,以及 langchain-core、langgraph、langsmith 等关键包版本;只记录环境变量名,不记录值。
- 事件捕获:用白名单过滤 astream_events(version="v2"),丢弃 on_chain_* 生命周期噪声,保留 on_chat_model_、on_tool_、on_retriever_*、on_custom_event 及任何 *_error 事件,并对 on_chat_model_stream 做 1/10 采样,把每次调用 2000+ 事件降到 50-200 条。
- 回调传播:通过 invoke 时的 config["callbacks"] 挂载 DebugCallbackHandler,而非 Runnable.with_config(callbacks=[...]),以捕获子图与内层 create_react_agent 循环中的事件。
- 追踪链接:用 get_current_run_tree() 取 RunTree.get_url(),写入 langsmith.url。
- 脱敏:打包前对每个文件跑正则替换,覆盖 OpenAI、Anthropic、Google、LangSmith 密钥、Bearer、数据库 URI、私钥等。
- 打包:写 MANIFEST.yaml 索引与脱敏统计,再 tar.gz。
必要用法:需 Python 3.10+、langchain-core >=1.0,<2.0、langgraph >=1.0,<2.0、langsmith >=0.1.40,并启用 LANGSMITH_TRACING=true、LANGSMITH_API_KEY、LANGSMITH_PROJECT(1.0 规范变量名,非旧版 LANGCHAIN_TRACING_V2),且对仓库外暂存目录有写权限。
限制:不使用已软弃用的 astream_log();token_usage 需从 on_chat_model_stream 分块聚合,on_llm_end 读取会滞后;LangSmith URL 需对方有项目权限,公开分享应使用 RunTree.share();自定义对象需扩展 _json_safe 才能序列化。