/Pydantic Logfire 利用编码智能体追踪来改进你的工作流 Duncan McKinnon avatar Duncan McKinnon 15 分钟 2026/11/13 以 Markdown 格式

自 Claude Code 首次发布以来,我们便不断迎来新模型、新能力和新 harness 的密集涌现,使 LLM 成为开发软件的主要手段。这些进步极大地拓展了此类工具的应用范围,以至于大多数团队每天都在使用它们。

harness 的巨大进步并未消除最大的挑战之一:整个过程依然不透明。当智能体失败或在无休止的探索中原地打转时,从外部很难看清究竟发生了什么。要充分利用你自己的 harness,你需要了解它在做什么,以及如何利用这些信息。

在日常工作中,我与一些团队合作,他们有意改进自己的编码 harness,却对追踪每一次交互的重要性持怀疑态度。我认为 harness 的改进与追踪本质上是相互关联的。从外部看,它可能只是简单的遥测数据,但它承载着丰富的信号,是许多监控、评估和改进流程所必需的。

本文将介绍编码 harness 追踪的一些最强大的用例,并展示如何通过让编码 harness 获取追踪数据来形成闭环,从而在模型、用户、团队和公司层面实现优化。

为什么编码 harness 需要可观测性

编码 harness 在广泛的场景中都能良好运作。只有当你建立起直觉后,差距才会变得清晰。你使用这些工具的时间越长,就越经常会产生这样的疑问:

  • 我的时间和 token 预算究竟花在哪里了?
  • 我如何从旧会话中提取有用的上下文?
  • 为什么我的智能体在执行任务时迷失了方向?
  • 这项任务我应该使用哪个 harness 和模型?
  • 我如何形成闭环,让智能体自己解决这些问题?

这些问题将是我们接下来的重点。我们将深入讨论如何系统地应对每一个问题。但归根结底,答案都需要可观测性。harness 所 提供的那些东西——会话日志的输入/输出——对于分析和改进的目的来说并不那么有用。

harness 隐藏了过程

The agent reads files, queries databases, runs tools, calls web APIs and edits code, while from outside the harness all you see is a terminal reading "working on it...".

智能体读取文件、查询数据库、运行工具、调用 Web API 并编辑代码,而从 harness 外部你看到的只是一个终端显示着“正在处理……”。

要获得真正的信号,你需要一个可观测性解决方案,它能够跨提供商工作,并记录从请求到响应的完整路径,而其中大部分都隐藏在 harness 内部。模型调用、工具调用、重试和死胡同都发生在视野之外,而且这些内容都没有被呈现和持久化以供长期反思。在你能回答这些问题之前,你需要一份智能体所做一切的记录。

追踪能为你带来什么

Logfire的 编码智能体追踪 可以根据你配置的捕获策略,为多种 harness 捕获模型调用、工具调用执行以及整个会话中的请求/响应配对。在每一个捕获的步骤中,它会记录元数据,例如耗时和用量(当 harness 和提供商提供时),缓存读取和写入也可能可用。对于受支持的提供商,Logfire 会根据记录的 token 和定价数据估算成本,因此你可以看到会话中受支持、已插桩调用的估算 API 成本。

这回答了第一个问题,其余问题都可以从同一份数据中得到解答。操作的顺序显示了智能体在哪里偏离了方向。每条追踪都记录了运行它的 harness 和模型,因此你可以比较不同的运行。会话被存储并可通过 SQL 搜索,因此旧的工作始终触手可及。而且通过 Logfire MCP server,智能体可以运行 SQL 查询并利用过往操作的上下文,这最终正是你形成闭环的方式。

形成闭环

形成闭环意味着让你启动的每一个编码 harness 都能充分利用丰富的历史会话上下文。在接下来的章节中,我们将使用这一模式来逐一解答前面的问题。我们将看到如何使用 Logfire MCP server 在你的 harness 内对追踪数据运行 SQL 操作,以监控、自动化和改进工作流。

这些示例并不全面,但它们代表了我所见过的对团队影响最大的用例。

为你关心的工作建立指标

编码 harness 追踪承载的不仅仅是延迟和 token 计数。它们记录了关于团队正在做什么、他们使用的模式以及低效之处所在的丰富信息。不同的组织、团队和用户会出于不同的原因关注这些信息。借助 Logfire MCP server,任何人都可以轻松地为自己想要追踪的内容开发指标和仪表盘。

无论指标是什么,模式都是一样的。在你偏好的 harness 中,只需让智能体使用 Logfire MCP 创建你想要看到的仪表盘和视图。由于 Logfire 中的大多数组件都定义为对追踪的 SQL 查询,智能体可以帮助构建和修改视图。

该流程概述如下,并用于后续所有示例。

The process used for the examples that follow: a plain-language request to the coding agent goes through the Logfire MCP server, which runs SQL over the trace data, creates the panel (here, average cycles per completed turn by agent) and replies with a link to it.

后续示例所使用的流程:向编码智能体发出一个自然语言请求,该请求经过 Logfire MCP server,后者对追踪数据运行 SQL,创建面板(此处为按智能体统计的每个已完成轮次的平均周期数)并回复一个指向该面板的链接。

在这个示例中,智能体收到了“按智能体统计完成一个轮次所需的平均周期数”的请求,查询了数据,找到了相关字段,创建了新面板,生成了按 harness 分组表示每轮平均操作的查询,并在完成后回复了一个指向该面板的链接。

追踪编码生产力

由于查询可以访问追踪的任何方面,而追踪代表编码工作,你可以开发面板来跟踪与生产力相关的特定操作,例如提交和拉取请求。下图显示了随时间变化的提交以及新增和删除的行数。这有助于立即发现智能体是否进行了大量删除,或者单个提交操作的大小是否异常小或大。

Lines added and deleted per commit, taken from agent traces.

每次提交的新增和删除行数,取自智能体追踪。

下图显示了从首次提交到创建 PR 所花费的时间,以及从首次编辑到提交所花费的时间。之所以能实现这类视图,是因为编码智能体使用 bash 工具运行 git 操作,而这些操作具有可通过 SQL 查询可靠拆分的结构。追踪中包含编码操作与最终 CI/CD 之间的时间信息和关联关系,因此我们可以直接从追踪中跟踪投入提交和 PR 的时间量。

Time from first commit to PR creation (top) and from first recorded edit to commit (bottom) across October, one point per PR or commit.

10 月期间从首次提交到创建 PR(上图)以及从首次记录的编辑到提交(下图)的时间,每个 PR 或提交为一个点。

跟踪成本与时间

如果你需要了解 token 和时间都花在了哪里,覆盖一段时间内支出和操作时长的图表是一个很好的起点。下面的可视化显示了 4 种不同智能体 harness 在 2 个月内的 token 成本。借助这类可视化,你可以开始评估低效之处和改进流程的机会。

Daily token cost in dollars from September through October for four harnesses: Claude Code, Codex, Cursor and Copilot.

9 月至 10 月期间四种 harness(Claude Code、Codex、Cursor 和 Copilot)的每日 token 成本(美元)。

对于 harness 和模型之间的一般比较,你可以细分性能的各个方面,以了解不同配置的效率。下面的图表比较了 harness 和模型在每轮平均工具调用次数和每次调用平均 token 数上的表现。监控这些特征可以及早发现某种配置比另一种更高效的信号,并促成有针对性的实验流程,我们将在后面讨论。

Average tool calls per turn (top) and average tokens per call (bottom), grouped by harness (left) and by model (right).

每轮平均工具调用次数(上图)和每次调用平均 token 数(下图),按 harness(左)和按模型(右)分组。

监控软件工厂

软件工厂使用一组协作的智能体将代码推进开发流水线。最近我一直在努力改进我的软件工厂配置,并添加了 harness 遥测来捕获会话。我特别感兴趣的是任务通过流水线需要多长时间,以及使用了多少 token。下图暴露了问题。

虽然实现和测试阶段通常比审查阶段更便宜,但流水线陷入了昂贵的审查和修复循环,导致审查和审查修复阶段的 token 使用量和成本很高。我们将在后面考察不同审查者配置的评估和实验时,再讨论如何解决这个问题。

Cost by phase of the software factory pipeline, in US dollars. The review-fix ($43.30) and review ($36.80) phases together account for about 60% of the roughly $132 total.

软件工厂流水线各阶段的成本(美元)。审查修复(43.30 美元)和审查(36.80 美元)两个阶段合计约占约 132 美元总额的 60%。

利用过去的工作

关闭会话通常意味着放弃上下文。如果你以后需要引用先前的工作,通常有 3 种选择:

  1. 以完整上下文打开同一会话,消耗大量 token
  2. 从头开始
  3. 设置某种文件系统模式,由智能体来管理

借助编码 harness 追踪和 Logfire MCP,你可以在新会话中检索先前的工作流,跨 harness 进行,并且只提取相关上下文,而不会使会话膨胀。

这种模式除了接续先前工作之外,还开辟了许多可能性。这里的图示展示了编码 harness 追踪所促成的三种模式。

Three patterns that coding harness tracing makes possible: splitting shared context across multiple harnesses, giving debugging and review sessions the full history, and branching any recorded turn into a new session for experiments.

编码 harness 追踪使之成为可能的三种模式:跨 harness 共享上下文、带完整历史的调试和审查,以及用于实验的分支轮次。

在多个 harness 之间拆分共享上下文

第一种模式在特定时间点获取先前的会话上下文,并将其分支到多个 harness 以协作完成工作,本质上是从共享知识开始,然后依靠各自的追踪作为沟通手段。当把在一个会话中规划好的工作拆分到多个不同 harness 中实施时,这很有用。它比创建规划文档更可靠,因为每个决策都已经编码在会话追踪中。

这在实验流程中同样有效,即在评估跨 harness 或模型的变体时需要保持完整上下文不变。后面在展示如何在一组代码审查任务上比较不同 harness 时会对此进行演示。

调试和审查会话

我们还可以在调试和审查方面更进一步。在进行代码审查时,智能体可以评估整个会话以确定结果的一致性。这比简单地检查代码是否有效并符合描述更能代表用户的意图。我发现,允许审查者使用 Logfire MCP 可以让审查者给出更好、更可操作的反馈,并减少事后后续修订。

能够访问先前的会话上下文,可以让你的智能体在如今调试由此产生的问题时评估自己过去的错误。在智能体构建的东西失败这种常见场景中,你既有失败的记录,也有关于它是如何实现的完整记录,以及最初的意图。这些额外的上下文可以大大加快改进速度,并形成长期记忆,避免下次再犯同样的错误。

用于实验的分支轮次

如今大多数 harness 都允许你针对某一轮次分支到新会话。借助编码 harness 追踪,你可以从任意 harness 和任意已记录的轮次分支到新会话。这非常适合实验流程,因为你需要用完全相同的上下文,在完全相同的任务上对不同 harness 进行对等比较。

在构建你自己的 harness 或软件工厂时,这是一种特别有用的模式。你可以收集场景,然后将既有智能体及其方法与你正在构建的 harness 进行比较,并按照对你重要的标准对它们进行评估。

将反复出现的困难转化为新技能

当智能体缺乏保持正轨所需的上下文时,重复性任务可能产生不一致的结果。这通常表现为冗长的发散式探索、不必要的确认询问以及未完成的任务。借助编码 harness 追踪,表现不佳的记录会成为关键信号,用于构建端到端梳理流程的技能。

人们最常迷失的地方,在于将相关信号转化为有用的技能。借助编码 harness 和 Logfire MCP server,你可以将该过程拆解为 4 个可重复的阶段。

首先,你从追踪记录中收集证据,供智能体在创建新技能时使用。为确保技能符合你的预期并消除歧义,你要与智能体协作,利用历史成功和失败中的证据梳理出一个可重复的流程。在证据和流程确立之后,你可以让智能体为该任务起草一项新技能。最后一步是验证该技能,确保它确实解决了问题,且不会引发新问题。为此,你可以利用第一步中收集的会话上下文,创建一个实验,在加载和不加载该技能的情况下比较同一个 harness。

完整流程如下所示:

The four stages of building a skill from traces: collect evidence, identify the happy path, create the skill, and verify the improvement by comparing runs with and without it.

从追踪记录构建技能的四个阶段:收集证据、识别顺利路径、创建技能,以及通过比较加载与不加载该技能的运行来验证改进。

为了演示这一流程并证明它确实有效,我将走查一个最近出现的场景。

收集证据

如果你在一个流程中不止一次遇到同一个问题,这通常表明智能体缺乏所需的上下文或方向。我经常使用 Logfire MCP server,通过对追踪记录执行查询来创建仪表盘面板。在创建新仪表盘时,通常会出现 1-2 个无效查询,以及少数需要修订和返工才能做对的面板。

为了解该问题的普遍程度,我使用 Logfire MCP 在编码智能体追踪记录中搜索无效查询和返工情况。这产生了如下所示的产物:

The evidence report the agent produced from the traces. Each case records a correction, such as a query that double-counted cached input tokens.

智能体从追踪记录中生成的证据报告。每个案例都记录了一次纠正,例如某个查询重复计算了缓存输入 token。

智能体还对错误进行了编目并逐一列出。这组证据是开发新的 logfire-dashboard-query 技能的完美起点。

识别顺利路径并创建技能

在没有证据或仅基于失败预期的情况下创建技能,通常会导致不必要的臃肿。有了问题及解决方案的证据,你就可以与智能体就技能的预期进行迭代。在本例中,我希望智能体验证查询、避免常见陷阱,并审查其创建的仪表盘是否对齐。

这些交互中还包含我的个人偏好和最佳实践的证据,因此我希望将这些普遍编码到将要创建的每个面板中。这一步有一些细微之处,但也是你可以开始塑造用于评估技能的标准的地方。

对于这项技能验证,标准基于查询的有效性、创建面板所需的步骤数,以及对不同类型变量的处理。

验证改进

要真正验证改进,你需要仔细设计实验结构。智能体运行应全部使用相同的 harness 配置、相同的会话和提示。只有技能的存在与否应能解释差异。幸运的是,你可以使用已通过 Logfire MCP server 收集的追踪记录作为测试集。这是为实验而分支轮次的一个示例,因为你需要获取先前的上下文和调用,而不包含任何暗示上一轮结果的线索。

对于这个实验,我选取了 12 个包含各种错误的仪表盘面板创建场景,并在加载和不加载该技能的情况下,在同一个 codex harness 上运行它们。结果显示在 Logfire 实验视图中。不加载技能时,12 次运行中有 9 次失败,并且还出现了若干格式错误。加载技能后,每个场景都成功且没有错误。

Logfire experiment view comparing the run without the skill (baseline) and with it (candidate). Cases passed went from 3/12 to 12/12 and assertions from 57/72 to 72/72. The largest gap was sql_executes, which went from 25% to 100%.

Logfire 实验视图比较了不加载技能(基线)和加载技能(候选)的运行。通过的案例从 3/12 提升到 12/12,断言从 57/72 提升到 72/72。差距最大的是 sql_executes,从 25% 提升到 100%。

评估和改进 harness

这里要展示的最后一种模式,结合了前面已经介绍的几种方法,目标是真正改进你的 harness 或优化你的工作流。当你使用编码智能体足够久之后,就会开始注意到在不同模型、harness 或指令下调用时行为上的细微差异。有些模型因过度工程而浪费更多 token,另一些在长任务中过早停止,而且总有可能陷入探索循环。

在修复智能体行为问题时,有几种可选方案。你可以尝试调整上文提到的任一杠杆。你可以尝试构建自己的 harness。你也可以忽略它,寄希望于它会自行改善。每种方案单独使用的问题在于,你缺乏数据来验证改动是否产生了预期效果,也无法确认它没有引入需要后续修复的新问题。

这正是智能体改进的实验流程发挥作用的地方。该方法遵循与开发新技能类似的步骤,如下图所示:

The evaluation workflow: select comparable traces for a task, build a dataset that keeps each trace's context along with the model and harness used, apply consistent criteria, then compare agents on group scores.

评估工作流:为某项任务挑选可比较的追踪记录,构建一个数据集,保留每条追踪记录的上下文以及所使用的模型和 harness,应用一致的评判标准,然后按分组得分比较各智能体。

查找追踪记录并构建数据集

第一步是收集你试图改进的场景的示例提示词。在这种情况下,你需要既能反映良好行为、也能反映不良行为的示例,这既是为了验证你的评判标准,也是为了防止出现回归。你不希望改动行为后导致其他方面出问题。

在这个案例中,我回到之前的可视化图表,注意到智能体修复实际上是我软件工厂中成本最高的操作。

Cost by phase of the software factory pipeline, repeated from above. Review-fix is the most expensive phase at $43.30, which is why the experiments target the reviewer and implementation agents.

软件工厂流水线各阶段的成本,重复自上图。审查-修复是成本最高的阶段,为 43.30 美元,这就是实验针对审查智能体和实现智能体的原因。

为了减少修复需求,我设计了一个两步实验序列:

  1. 优化审查智能体,使其不会因细微的风格选择而让过多审查失败,同时仍然遵循提示词中提供的指令和约定。
  2. 优化实现智能体,使代码不会通不过审查而需要修复循环。

在本例中,我们只聚焦第一阶段,即提升审查智能体的专注度和表现。首先,我回溯了不同 harness 下的追踪记录,寻找审查运行的示例。为了让实验保持可控,我收集了 5 个小型 PR 审查的示例。

The five matched code review cases, each from a real change, with the size of each diff: an agent alias refactor across six modules, derivation models, a template boundary, a web derived view and a prompt-sync web client.

五个匹配的代码审查案例,每个都来自真实改动,并附有各自 diff 的大小:一次跨六个模块的智能体别名重构、派生模型、一个模板边界、一个 Web 派生视图,以及一个 prompt-sync Web 客户端。

由于这些数据需要用于实验,必须将上下文添加到 Logfire 数据集中。数据集正是为这种场景而设:固定的示例案例,用于在不同智能体或 harness 配置下重新运行评估。由于原始审查的结果无关紧要,我只收集了输入到原始审查步骤的上下文,以便在实验中复用,并据此构建了数据集。

我选择在 3 种不同的编码 harness 上测试这 5 个审查案例,看看应该在我的软件工厂的审查阶段接入哪一个。我比较了使用 haiku-5.5 的 Claude Code、使用 gpt-6-luna 的 Codex,以及使用 composer-2.5 的 Cursor,看哪一个能给出最有效的 PR 审查。

评估标准

实验与改进流程中最关键的组成部分大概就是评估标准。你正是在这里将对齐要求编码进你所开发的系统中。重要的是要记住,大多数标准是在约束不良结果,而不是推向某个最小值或最大值。就审查而言,我开发了两个智能体评估,它们会使用审查智能体的输入和输出异步运行。

第一个评估测试审查者吹毛求疵的程度。该评估器会对那些引用格式或风格选择的过度敏感的审查失败进行扣分。为了平衡审查者过于宽松的风险,第二个评估器衡量智能体对指令中指定约定的遵循程度。对于我的软件工厂,每个智能体都会收到一组需要遵循的约定,基本上规定了使用哪些框架以及代码应如何组织。第二个评估器会对偏离既定编码期望的情况进行扣分。

实验与结果

一旦数据集和评估器创建完成,剩下要做的就是运行实验并解读结果。在此语境下,实验意味着用数据集中的提示词调用智能体,对结果运行评估,并跨案例汇总,以查看每项标准的整体表现。

在审查实验中,每个评估器按 1-4 分制对响应评分,审查中问题越严重得分越低。下表列出了每个 harness 和模型的实际评分。PR 结论不纳入智能体表现分析,但值得注意的是,某些 harness 被证明更严格或更宽松,这反映在评分中。

Score tables for the five review cases, in the order Agent alias, Web derived view, Derivation models, Template boundary, Web client. Each row lists the verdict, then the standards score and the avoids-nits score out of 4. Codex with gpt-6-luna: PASS 4 and 4, FAIL 4 and 3, PASS 4 and 4, PASS 4 and 4, FAIL 4 and 4. Claude with claude-haiku-5-5: PASS 3 and 1, FAIL 3 and 2, FAIL 2 and 1, FAIL 2 and 0, FAIL 3 and 2. Cursor with composer-2.5: PASS 3 and 3, PASS 3 and 1, PASS 3 and 1, PASS 3 and 1, PASS 3 and 1. The tables also show a truncated excerpt of each review and the rationale for each score.

Codex、Claude-Code 和 Cursor 各 5 个审查案例。表格显示了每个审查在用于评估表现的 2 项评估标准上的单独得分。

汇总结果清晰地说明了问题。使用 gpt-6-luna 的 Codex 在标准遵循度和避免吹毛求疵两方面都显著优于 Cursor composer-2.5 和 Claude haiku-5.5。事实上,两项标准上的排序相同,Claude 表现最差。此处显示的质量平均值是 2 项评估标准的平均值,而总体平均值还纳入了第三项指标,旨在确保审查以给出结论告终(所有运行都做到了)。

Reviewer scores out of 4 for the Claude Code, Cursor and Codex setups on the five cases. Codex scores highest on every panel (overall 3.93), Cursor is next (2.80) and Claude Code is lowest (2.60).

Claude Code、Cursor 和 Codex 三种配置在五个案例上的审查得分(满分 4 分)。Codex 在每个面板上得分最高(总体 3.93),Cursor 次之(2.80),Claude Code 最低(2.60)。

下一步方向

这里展示的模式在当今大多数编码智能体配置中都很实用,但它们远未穷尽像 Logfire 这样的可观测性框架所能实现的可能性。每天都有新功能推出,但所有这些功能都需要数据和实验来推动性能和效率的提升,就像本文所概述的那样。这些模式展示了追踪和实验如何帮助团队提升编码智能体的性能和效率。

在 Google 搜索中查看更多 Pydantic 内容

将 Pydantic 添加为首选来源,以便更轻松地找到我们的最新文章。

在 Google 上将 Pydantic 选为首选来源(在新标签页中打开)

准备好看看你的智能体实际在做什么了吗?

免费开始 免费开始 联系我们 联系我们

探索我们的开源软件包

Product shot