Agent Trace

版本: 0.1.0
状态: RFC
日期: 2026年1月

摘要

Agent Trace 是一个用于追踪 AI 生成代码的开放规范。它提供了一种供应商中立的格式,用于在版本控制的代码库中记录 AI 贡献和人类作者身份。

目录

1. 动机
2. 目标
3. 非目标
4. 术语
5. 架构概述
6. 核心规范
7. 扩展性
8. 参考实现
9. 附录

1. 动机

随着 AI 代理编写越来越多的代码,理解哪些代码来自 AI、哪些来自人类变得非常重要。这种归属既包括使用的模型,也包括相关的代理对话。Agent Trace 定义了一个开放的、可互操作的标准,用于记录这些归属数据。

2. 目标

1. 互操作性: 任何符合规范的工具都可以读写归属数据。
2. 粒度: 支持文件级和行级的模型归属。
3. 可扩展性: 供应商可以添加自定义元数据而不破坏兼容性。
4. 人类和代理可读: 归属数据无需特殊工具即可阅读。

3. 非目标

1. 代码所有权: Agent Trace 不追踪法律所有权或版权。
2. 训练数据来源: 我们不追踪哪些训练数据影响了 AI 输出。
3. 质量评估: 我们不评估 AI 贡献的好坏。
4. 界面无关: Agent Trace 不要求任何特定的用户界面。

4. 术语

贡献者类型

5. 架构概述

Agent Trace 是一个数据规范,而非产品。它定义了如何记录归属数据。存储机制由具体实现定义。该规范对追踪数据的存储位置不做限定。

6. 核心规范

6.1 Trace Record Schema

Agent Trace 的基本单元是 Trace Record (追踪记录):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-trace.dev/schemas/v1/trace-record.json",
  "title": "Agent Trace Record",
  "type": "object",
  "required": ["version", "id", "timestamp", "files"],
  "properties": {
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "Agent Trace 规范版本(例如 '1.0.0')"
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "此追踪记录的唯一标识符"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "记录追踪时的 RFC 3339 时间戳"
    },
    "vcs": {
      "$ref": "#/$defs/vcs",
      "description": "此追踪的版本控制系统信息"
    },
    "tool": {
      "$ref": "#/$defs/tool",
      "description": "生成此追踪的工具"
    },
    "files": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/file"
      },
      "description": "包含归属范围的文件数组"
    },
    "metadata": {
      "type": "object",
      "description": "用于实现特定或供应商特定数据的附加元数据"
    }
  },
  "$defs": {
    "vcs": {
      "type": "object",
      "required": ["type", "revision"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["git", "jj", "hg", "svn"],
          "description": "版本控制系统类型"
        },
        "revision": {
          "type": "string",
          "description": "修订版本标识符(例如 git commit SHA、jj change ID)"
        }
      }
    },
    "tool": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "version": { "type": "string" }
      }
    },
    "file": {
      "type": "object",
      "required": ["path", "conversations"],
      "properties": {
        "path": {
          "type": "string",
          "description": "相对于仓库根目录的文件路径"
        },
        "conversations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/conversation"
          },
          "description": "对此文件做出贡献的对话数组"
        }
      }
    },
    "contributor": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["human", "ai", "mixed", "unknown"]
        },
        "model_id": {
          "type": "string",
          "maxLength": 250,
          "description": "遵循 models.dev 约定的模型唯一标识符(例如 'anthropic/claude-opus-4-5-20251101')"
        }
      }
    },
    "conversation": {
      "type": "object",
      "required": ["ranges"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "用于查找生成此代码的对话的 URL"
        },
        "contributor": {
          "$ref": "#/$defs/contributor",
          "description": "此对话中范围的贡献者(可在每个范围中覆盖)"
        },
        "ranges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/range"
          },
          "description": "此对话产生的行范围数组"
        },
        "related": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["type", "url"],
            "properties": {
              "type": { "type": "string" },
              "url": { "type": "string", "format": "uri" }
            }
          },
          "description": "其他相关资源"
        }
      }
    },
    "range": {
      "type": "object",
      "required": ["start_line", "end_line"],
      "properties": {
        "start_line": { "type": "integer", "minimum": 1 },
        "end_line": { "type": "integer", "minimum": 1 },
        "content_hash": {
          "type": "string",
          "description": "归属内容的哈希值,用于位置无关的追踪"
        },
        "contributor": {
          "$ref": "#/$defs/contributor",
          "description": "覆盖此特定范围的贡献者(例如用于代理交接)"
        }
      }
    }
  }
}

6.2 示例 Trace Record

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-23T14:30:00Z",
  "vcs": {
    "type": "git",
    "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  },
  "tool": {
    "name": "cursor",
    "version": "2.4.0"
  },
  "files": [
    {
      "path": "src/utils/parser.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [
            {
              "start_line": 42,
              "end_line": 67,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ],
          "related": [
            {
              "type": "session",
              "url": "https://api.cursor.com/v1/sessions/67890"
            }
          ]
        }
      ]
    },
    {
      "path": "src/utils/helpers.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "openai/gpt-4o"
          },
          "ranges": [
            {
              "start_line": 10,
              "end_line": 25
            }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "confidence": 0.95,
    "dev.cursor": {
      "workspace_id": "ws-abc123"
    }
  }
}

6.3 归属范围

范围按对话分组,贡献者元数据位于对话级别。当一个对话产生多个范围时,这可以减少基数。

行级归属:

{
  "files": [
    {
      "path": "src/utils.ts",
      "conversations": [
        {
          "url": "https://api.example.com/v1/conversations/abc",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-sonnet-4-20250514"
          },
          "ranges": [
            { "start_line": 10, "end_line": 25 },
            { "start_line": 30, "end_line": 45 },
            { "start_line": 80, "end_line": 95 }
          ]
        },
        {
          "url": "https://api.example.com/v1/conversations/def",
          "contributor": { "type": "ai", "model_id": "openai/gpt-4o" },
          "ranges": [{ "start_line": 50, "end_line": 52 }]
        }
      ]
    }
  ]
}

行号从 1 开始索引。范围引用记录修订版本时的位置。

6.4 版本控制系统

Agent Trace 通过 vcs 字段支持多种版本控制系统:

// Git
{ "vcs": { "type": "git", "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } }

// Jujutsu (使用 change ID 以在 rebase 时保持稳定)
{ "vcs": { "type": "jj", "revision": "kkmpptxz" } }

// Mercurial
{ "vcs": { "type": "hg", "revision": "a1b2c3d4e5f6" } }

revision 字段的格式取决于具体的 VCS:

• git: 40 字符的十六进制 commit SHA
• jj: Change ID(在 amend/rebase 操作中保持稳定)
• hg: Changeset 标识符

6.5 行追踪

追踪中的行号指的是记录修订版本时的位置,而非当前位置。要查询特定代码行的所有权:

1. 使用 VCS blame 查找最后修改第 N 行的修订版本
2. 查找该修订版本和文件的追踪记录
3. 找到包含第 N 行的范围

6.6 内容哈希

为了跨代码移动追踪归属,可以在范围级别使用内容哈希:

{
  "files": [
    {
      "path": "src/parser.ts",
      "conversations": [
        {
          "url": "https://api.example.com/v1/conversations/abc",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [
            {
              "start_line": 10,
              "end_line": 25,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ]
        }
      ]
    }
  ]
}

哈希应用于特定范围,即使代码在文件内或文件间移动也能进行追踪。

6.7 模型标识符

模型标识符遵循 models.dev 约定:

{
  "contributor": {
    "type": "ai",
    "model_id": "anthropic/claude-opus-4-5-20251101"
  }
}

格式: provider/model-name

6.8 关联资源

每个对话都有一个 url 字段和可选的 related 数组,用于链接到相关的子资源:

{
  "files": [
    {
      "path": "src/api.ts",
      "conversations": [
        {
          "url": "https://api.example.com/v1/conversations/abc123",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [{ "start_line": 10, "end_line": 50 }],
          "related": [
            {
              "type": "session",
              "url": "https://api.example.com/v1/sessions/xyz789"
            },
            {
              "type": "prompt",
              "url": "https://api.example.com/v1/prompts/def456"
            }
          ]
        }
      ]
    }
  ]
}

7. 扩展性

7.1 规范版本控制

• 主版本号: 必填字段的破坏性变更
• 次版本号: 增量变更(新的可选字段)

7.2 元数据

metadata 字段可以包含实现特定或供应商特定的数据:

{
  "metadata": {
    "confidence": 0.95,
    "post_processing_tools": ["prettier@3.0.0"],
    "dev.cursor": {
      "workspace_id": "ws-abc123"
    }
  }
}

供应商可以在 metadata 中使用反向域名表示法(例如 dev.cursor、com.github.copilot)以避免键冲突。

8. 参考实现

reference/ 目录中提供了一个参考实现,演示了如何将 Agent Trace 与编码代理集成。该实现包括:

• trace-store.ts: 用于读写追踪记录的存储层
• trace-hook.ts: 用于在文件更改时自动捕获追踪的 Hook 集成

该参考实现是针对 Cursor 或 Claude Code 的示例,但这些模式适用于任何 AI 编码代理。

附录

A. 最小有效 Trace Record

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-25T10:00:00Z",
  "files": [
    {
      "path": "src/app.ts",
      "conversations": [
        {
          "contributor": { "type": "ai" },
          "ranges": [{ "start_line": 1, "end_line": 50 }]
        }
      ]
    }
  ]
}

B. MIME 类型

C. 常见问题

我应该如何存储追踪记录?

本规范有意不定义追踪记录的存储方式。可以是本地文件、git notes、数据库或其他任何方式。

我应该如何处理 rebase 或合并提交?

我们期望在开源社区中看到不同的实现方式。这可能会在未来影响规范。我们欢迎反馈。

当代理创建脚本来编写代码时会发生什么?

这留给具体实现决定。以这种方式生成的代码仍应归属于代理。例如,您可以在脚本运行前后对文件进行快照,然后使用 git diff 来确定代理添加了什么。

许可证

本规范在 CC BY 4.0 下发布。

贡献

感谢以下合作伙伴帮助塑造 Agent Trace:

• Amp
• Amplitude
• Cline
• Cloudflare
• Cognition
• git-ai
• Jules
• OpenCode
• Tapes
• Vercel

本规范正在 GitHub 上接受建议。