Agent Trace 中文版 - AI 编程追踪规范

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

摘要

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

1. 动机

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

2. 目标

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

3. 非目标

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

4. 术语

术语	定义
Contribution (贡献)	代码变更的单元(添加、修改或删除)
Contributor (贡献者)	产生贡献的实体(人类或 AI)
Trace Record (追踪记录)	描述贡献来源的元数据

贡献者类型

类型	代码	描述
Human (人类)	`human`	由人类开发者直接编写的代码
AI	`ai`	由 AI 生成的代码
Mixed (混合)	`mixed`	人类编辑的 AI 输出或 AI 编辑的人类代码
Unknown (未知)	`unknown`	无法确定来源

5. 架构概述

Agent Trace 架构

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 行追踪

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

使用 VCS blame 查找最后修改第 N 行的修订版本
查找该修订版本和文件的追踪记录
找到包含第 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 类型

类型	MIME 类型
Trace Record	`application/vnd.agent-trace.record+json`

C. 常见问题

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

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

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

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

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

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

许可证

本规范在 CC BY 4.0 下发布。

贡献

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

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