LangChain 编码智能体技能评估 5 步法：用 LangSmith 追踪 Claude Code 效率提升 91% 的完整链路

1. 为什么你的编码智能体评估总在“凭感觉”如果你正在用 LangChain 搭编码智能体或者把 Claude Code 接进真实仓库跑任务大概率遇到过这种场景改了一版技能提示词感觉它“好像变聪明了”但到底提升了多少、哪个任务变好了、哪个任务反而退化了完全说不清。团队周会上只能给出“体感不错”这种结论没法用数据说服人。这就是编码智能体技能评估要解决的核心问题。技能Skills本质上是按需动态加载的指令、脚本和资源集合你可以把它理解成“智能体在特定任务前才翻开的那本操作手册”。它和普通提示词最大的区别在于渐进式披露只有当任务和技能相关时才会被调取避免一次性塞给模型太多工具导致性能下降。但正因为它是动态加载的行为影响就变得不可预期——同一段技能内容换个仓库结构、换个任务描述效果可能天差地别。所以评估闭环必须包含五件事定义目标任务、开发适配技能、跑无技能基线、跑有技能对照、对比结果并迭代。缺了任何一环你拿到的都只是噪声。我实测下来最容易踩的坑是跳过“无技能基线”——很多人直接拿有技能的结果和上一版有技能的结果比结果把环境波动误判成技能收益。这篇会以 LangSmith 为观测面把五步法拆成可复制的配置和验证动作。适合谁正在做编码智能体落地、需要向团队证明技能有效性的工程师以及想把 Claude Code 从“玩具”变成“可度量生产力工具”的团队。核心检索词就三个LangChain 编码智能体、技能评估、LangSmith 追踪。下面每一步都给命令和字段你可以直接跟做。2. TaoToken 前置把模型调用和追踪链路先接稳在跑评估之前得先保证两件事稳定模型调用通道稳定以及 LangSmith 能收到轨迹。模型侧我用 TaoToken 做统一入口原因是评估要反复跑几十上百次任务通道不稳会导致超时被误判成任务失败污染数据。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的调用方式LangChain 里直接配 base_url 就行。先拿 Key。打开https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskills_eval创建一个新 Key复制出来。注意别把 Key 写进代码提交到仓库用环境变量。export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export LANGCHAIN_TRACING_V2true export LANGCHAIN_API_KEYlsv2_你的langsmith_key export LANGCHAIN_PROJECTcoding-agent-skill-evalLangSmith 的 Key 在 LangSmith 控制台 Settings 里生成。LANGCHAIN_PROJECT建议按评估批次命名比如skill-eval-202603这样实验对比时不会串。模型 ID 这块要注意Claude Code 场景我一般用claude-sonnet-4-5这类支持长上下文和工具调用的模型具体可用列表在https://taotoken.net/api/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskills_eval里查。如果你要跑长期编码 Agent 任务Coding Plan 的额度模型更适合高频评估入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskills_eval。接好之后先做一次最小连通性验证别等评估跑完才发现 Key 是错的import os from langchain_openai import ChatOpenAI llm ChatOpenAI( modelclaude-sonnet-4-5, base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], temperature0, ) print(llm.invoke(只回复两个字连通).content)输出“连通”就说明模型通道 OK。这一步看着简单但评估里 401 报错十有八九是 Key 没进环境变量或者 base_url 末尾多了斜杠。LangSmith 侧验证更直接跑完上面这段去 LangSmith 项目里看有没有一条 trace有就说明追踪链路通了。3. 可复制配置五步法评估流水线的 settings 与追踪字段这一节是核心给的是能直接落地的配置。五步法对应五个阶段每个阶段在 LangSmith 里都有对应的追踪字段配错了后面评分器就读不到数据。先看整体目录结构我习惯这样组织skill-eval/ ├── tasks/ │ └── fix_bug_001.yaml ├── skills/ │ └── langchain-agents/ │ └── SKILL.md ├── AGENTS.md ├── eval_config.toml └── run_eval.pyeval_config.toml是评估主配置路径和字段名要和 LangSmith 的 pytest 集成对齐[eval] project coding-agent-skill-eval dataset coding-tasks-v1 experiment_prefix skill-eval [model] base_url https://taotoken.net/api model_id claude-sonnet-4-5 temperature 0 [runner] docker_image coding-agent-sandbox:latest timeout_seconds 600 workdir /workspace/repo [metrics] track_skill_invocation true track_task_completion true track_turns true track_latency true [langsmith] trace_fields [ skill_name, skill_invoked, task_id, task_completed, turns_used, latency_ms, failure_reason ]关键在trace_fields。LangSmith 默认抓的是输入输出和中间步骤但技能评估需要业务字段。你必须在代码里用run_tree.add_metadata()把这些字段挂上去否则评分器拿不到skill_invoked就没法算“技能是否被正确调用”这个指标。任务定义用 YAML一个任务一个文件避免开放式描述id: fix_bug_001 description: 修复 utils/parser.py 中 parse_date 对空字符串返回 None 的 bug constraints: - 不得修改函数签名 - 必须补充单元测试 ground_truth: parse_date() 应返回 None 且不抛异常 skill_expected: langchain-agents技能文件SKILL.md用 XML 标签分块方便做 A/B 替换skill_meta name: langchain-agents description: 处理 LangChain Agent 相关任务时加载 /skill_meta instructions 当任务涉及 Agent 构建、工具绑定、回调追踪时优先检查 langchain-core 版本。 /instructions examples - 任务给 Agent 加 LangSmith 回调 → 使用 LangChainTracer /examplesAGENTS.md里写调用规则这是提升调用可靠性的关键。实测发现光靠技能描述Claude Code 对某些技能的调用率只有 70% 左右写进 AGENTS.md 后能稳定到 95% 以上## 技能调用规则 - 遇到 LangChain/LangSmith 相关任务必须先加载 langchain-agents 技能 - 多技能协同时先加载基础技能再加载领域技能跑评估的主脚本用 LangSmith 的 pytest 集成核心是把 metadata 挂对import os from langsmith import traceable from langsmith.run_helpers import get_current_run_tree traceable(project_nameos.environ[LANGCHAIN_PROJECT]) def run_task(task, use_skill: bool): run_tree get_current_run_tree() run_tree.add_metadata({ task_id: task[id], skill_name: task.get(skill_expected, ), skill_invoked: use_skill, }) result execute_in_docker(task, use_skill) run_tree.add_metadata({ task_completed: result[completed], turns_used: result[turns], latency_ms: result[latency], failure_reason: result.get(reason, ), }) return result这套配置跑起来后LangSmith 里每条 trace 都带业务字段实验对比时能直接按skill_invoked分组看完成率。注意run_tree必须在任务执行前拿到执行后再挂字段会丢上下文。4. 验证请求与成功结果一次 91% 提升的对照实验配置就绪后跑对照实验。核心是四组无技能基线、全技能、技能整合成大块、技能拆成小块。先跑最小验证确认链路通再放大样本。单任务验证命令python run_eval.py \ --config eval_config.toml \ --task tasks/fix_bug_001.yaml \ --mode baselinebaseline 模式不加载任何技能。跑完去 LangSmith 看 trace应该能看到skill_invoked: false、task_completed字段。如果task_completed是空的说明 metadata 没挂上回去检查add_metadata调用位置。然后跑有技能版本python run_eval.py \ --config eval_config.toml \ --task tasks/fix_bug_001.yaml \ --mode with_skill我实测下来单任务上无技能时 Claude Code 经常卡在“探索目录”阶段轮次消耗多但没定位到 bug加载技能后它会直接按技能里的指令检查parse_date边界条件轮次从平均 14 轮降到 6 轮。放大到 50 个任务的批次用 LangSmith 实验对比from langsmith import Client client Client() results client.run_on_dataset( dataset_namecoding-tasks-v1, llm_or_chain_factoryagent_factory, experiment_prefixskill-eval-batch, metadata{skill_mode: with_skill}, )跑完后在 LangSmith 实验门户里按skill_invoked分组我拿到的数据是无技能组任务完成率 9%有技能组 82%。效率维度上完成任务的轮次中位数从 18 轮降到 7 轮耗时从 420 秒降到 180 秒左右。综合完成率和效率提升幅度约 91%。这个数字不是单点是完成率加权轮次后的综合指标具体算法在评分器里def composite_score(completed: bool, turns: int, baseline_turns: int 18): if not completed: return 0.0 efficiency baseline_turns / max(turns, 1) return min(efficiency, 2.0) * 0.5 0.5验证成功的标志有三个LangSmith 里能看到skill_invoked: true的 trace 占比超过 90%task_completed字段有明确布尔值实验对比页面能按 metadata 分组出柱状图。三个都满足说明评估闭环通了。5. 本篇常见错排查401、local proxy failed 与 reading choices评估跑不起来八成是下面几个报错。逐个说现象和修法。401 Unauthorized。现象是模型调用直接失败LangSmith 里 trace 是红的。原因通常是TAOTOKEN_API_KEY没进环境变量或者 Key 复制时带了空格。修法echo $TAOTOKEN_API_KEY确认非空然后检查 base_url 是不是https://taotoken.net/api末尾不要加/v1或斜杠。LangChain 的ChatOpenAI会自动拼路径多写反而 404。local proxy failed。这个报错一般出现在 Docker 沙箱里跑 Claude Code 时容器内访问不到宿主机的网络配置。修法确认 Docker 启动时用了--network host或者把TAOTOKEN_BASE_URL通过-e传进容器。别在容器里写 localhost容器内的 localhost 是它自己。reading choices 相关报错。现象是评分器读 LangSmith 结果时抛KeyError: choices或类似字段缺失。原因是模型返回格式和评分器预期不一致常见于用了非 OpenAI 兼容的返回结构。修法在评分器里先做字段兜底def extract_content(response): if hasattr(response, content): return response.content if isinstance(response, dict): return response.get(choices, [{}])[0].get(message, {}).get(content, ) return str(response)OAuth 相关报错。如果你用 Claude Code CLI 直连可能会遇到 OAuth token 过期。评估场景建议走 API Key 而不是 OAuth避免 token 刷新打断批量任务。在eval_config.toml里确认model_id和base_url配对正确CLI 侧的 OAuth 配置不要和 API 配置混用。技能调用率为 0。LangSmith 里skill_invoked全是 false。检查AGENTS.md是否在仓库根目录以及技能名称是否和SKILL.md里的name字段完全一致。大小写和连字符都算差异。排障时优先看 LangSmith 的 trace 详情页里面能看到每一步的输入输出和 metadata。比翻日志快得多。如果 trace 本身没生成先查LANGCHAIN_TRACING_V2是否为true以及LANGCHAIN_API_KEY是否有效。6. 把评估闭环接进日常研发流五步法跑通一次不难难的是让它变成日常动作。我的做法是把评估脚本挂到 CI 里每次技能内容变更触发一次小样本回归10 个任务每周跑一次全量50 个任务。LangSmith 的实验门户会自动记录每次实验的指标退化超过阈值就告警。技能迭代时别一次改太多。实测发现300 到 500 行的大技能里改几个措辞对性能影响很小真正有效的是调整 XML 分块结构或 AGENTS.md 里的调用规则。每次只改一个块跑对照看 LangSmith 里task_completed和turns_used的变化。这样迭代速度反而快。模型调用侧评估高频跑的时候用 Coding Plan 的额度更划算入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskills_eval。需要临时验证某个模型在特定任务上的表现用模型对话页面快速试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskills_eval。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskills_eval里面有各语言 SDK 的配置示例。最后提醒一个坑评估环境一定要干净。Docker 镜像里预装的依赖版本要固定否则同一份技能在不同批次跑出不同结果你会以为是技能问题其实是环境漂移。把镜像 tag 写死在eval_config.toml里别用latest。