Agent Trace 是为谁而设计的?

2026-01-30 · 1 min read

Cursor 发布了 Agent Trace,这是一个开放规范,用于追踪仓库中哪些代码是由 LLM 编写的。它记录模型、工具、对话和精确的行范围——所有内容都追加到项目中的 JSONL 文件中。

推介词:“随着代理编写更多代码,理解什么来自 AI 而非人类变得很重要。”

我花时间阅读了规范和参考实现。工程设计很扎实——清晰的架构、深思熟虑的可扩展性、良好的合作伙伴列表(Amp、Amplitude、Cloudflare、Cognition、Google、Vercel)。但我一直回到一个问题:你用这些数据做什么?

它捕获了什么

每次 LLM 编辑文件时,都会触发一个钩子并记录一条追踪:哪个模型、哪个工具、哪些行、哪个对话。参考实现处理来自 Cursor 和 Claude Code 的事件:

// 来自参考钩子——事件通过 stdin 流入
appendTrace(createTrace("ai", input.file_path!, {
  model: input.model,
  rangePositions,
  transcript: input.transcript_path,
  metadata: { conversation_id: input.conversation_id, generation_id: input.generation_id },
}));

规范定义了四种贡献者类型——human、ai、mixed、unknown——并支持行级归属,使用内容哈希来追踪移动的代码。它是供应商中立的、VCS 无关的,并且可以通过命名空间元数据进行扩展。

作为数据格式,它设计得很好。问题是它能实现什么。

归属挑战

规范将作者身份建模为一种分类。但 LLM 辅助编码是一场对话。你描述你想要什么。LLM 生成一些东西。你编辑其中一半,拒绝一个函数,要求修订,接受第二次尝试,然后手动修复边缘情况。后来,另一个 LLM 重构了整个块。

谁写了那段代码?人类和 LLM 作者身份之间的界限是模糊的,而且变得越来越模糊。大多数真实代码最终都会是 mixed,如果几乎所有东西都是 mixed,分类就没有告诉你太多信息。

行级归属也有保质期问题。追踪说"Claude 在提交 abc123 时写了第 10-50 行。“两次提交后,有人重新格式化了该块或从中提取了一个函数。规范的答案是通过 git blame 链接,内容哈希可以帮助追踪移动的代码。但在使用 rebase 和 squash-merge 的工作流中,链条会断裂。这些是困难的问题——早期 RFC 应该提出的那种问题。

缺失的行动

规范明确否认了明显的用途:不用于代码所有权,不用于质量评估,不用于训练数据来源。它说"透明度”。但透明度是手段,不是目的。

如果代码通过了审查和测试,因为 LLM 写的就有什么改变吗?如果它有 bug,无论如何你都会修复它。规范从未将归属与具体行动联系起来。数据进去了,但没有定义获取答案的方法。这就是差距——不是格式,而是用例。

有趣的地方

这是我认为 Agent Trace 实际指向的内容,即使规范还没有说出来。

每个 LLM 生成的函数背后都有推理令牌、错误的转向、重试、上下文切换和工具调用。代理不仅仅是产生代码——它经历一个过程才能到达那里。它读取文件、误解接口、回溯、尝试不同的方法、运行测试、修复失败,最后得出解决方案。该过程在最终差异中是不可见的。

钩子已经捕获了不仅仅是归属的内容。看看输入表面:

interface HookInput {
  hook_event_name: string;
  model?: string;
  transcript_path?: string | null;
  conversation_id?: string;
  generation_id?: string;
  session_id?: string;
  file_path?: string;
  edits?: FileEdit[];
  command?: string;
  duration?: number;
  is_background_agent?: boolean;
  composer_mode?: string;
  tool_name?: string;
  tool_input?: { file_path?: string; new_string?: string; old_string?: string; command?: string };
  tool_use_id?: string;
}

模型、会话、对话、工具、命令、持续时间、是否是后台代理、编辑器模式、每次工具调用及其输入。这不仅仅是归属数据。这是流程数据。而流程数据才是真正价值所在:

评估。 哪些模型在哪些模式上挣扎?一次尝试就完成的函数与需要十二次重试的函数不同——即使输出相同。不是"谁写的"而是"生产它有多难"。
代理原生代码库。 如果代理一直在某个模块上挣扎——许多错误的转向、高重试率、重复的上下文混淆——这是一个信号,表明代码的结构不适合代理的工作方式。你可以为清晰度、更好的接口、更明确的契约进行重构。追踪数据成为你的代码库对 LLM 协作不友好的地方的地图。
流程优化。 哪些工具配置产生更好的首次尝试代码?哪些提示模式减少回溯?你无法从行归属中回答这些问题。你需要旅程,而不是目的地。

正确的问题

Agent Trace 还处于早期阶段。这是一个 RFC,在归属建模、范围持久性和查询语义方面存在真正的挑战。但直觉是正确的——随着 LLM 编写更多代码,我们需要关于这如何发生的结构化数据。

这个规范最有用的版本可能不是"LLM 写了什么?“而是"LLM 是如何到达那里的?“行级分类账是一个起点。流程追踪——推理、迭代、达成解决方案的成本——才是团队实际使用 LLM 编写更好代码的地方。

这就是我想要构建的规范。