Agent Trace

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

抽象

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

目录

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

---

1. 动机

随着代理编写更多代码，了解哪些内容来自 AI、哪些来自人类变得尤为重要。这种归因涉及使用的模型以及相关的代理对话。Agent Trace 定义了一个开放、可互操作的标准，用于记录这种归因数据。

---

2. 目标

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

---

3. 非目标

1. 代码所有权：Agent Trace 不追踪法律所有权或版权。
2. 训练数据溯源：我们不追踪影响 AI 输出的训练数据。
3. 质量评估：我们不评估 AI 贡献是否优质。
4. 界面无关：Agent Trace 不需要特定界面。

---

4. 术语

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

贡献者类型

类型	代码	描述
人类	human	由人类开发者直接编写的代码
AI	ai	由 AI 生成的代码
混合	mixed	人类编辑的 AI 输出或 AI 编辑的人类代码
未知	unknown	原因无法确定

---

5. 架构概述

Agent Trace 是一个数据规范，而非产品。它定义了如何记录归因数据。存储机制由实现定义。规范对追踪数据的存储位置持中立态度。

---

6. 核心规范

6.1 跟踪记录模式

Agent 跟踪的基本单位是 跟踪记录：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-trace.dev/schemas/v1/trace-record.json",
  "title": "Agent 跟踪记录",
  "type": "object",
  "required": ["version", "id", "timestamp", "files"],
  "properties": {
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "Agent 跟踪规范版本（例如：'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 提交 SHA，jj 变更 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  convention 的模型唯一标识符（例如：'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 示例跟踪记录

{
  "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 位十六进制提交 SHA
• jj: Change ID（在 amend/rebase 操作中保持稳定）
• hg: 变更集标识符

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：用于文件更改时自动捕获追踪的钩子集成

该参考实现适用于 Cursor 或 Claude Code，但模式可应用于任何 AI 编码代理。

---

附录

A. 最小有效追踪记录

{
  "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 类型
追踪记录	application/vnd.agent-trace.record+json

C. 常见问题

如何存储追踪记录？

本规范有意未定义追踪的存储方式。这可以是本地文件、git 注释、数据库或任何其他方式。

如何处理 rebase 或合并提交？

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

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

由实现决定。通过这种方式生成的代码仍应归因于代理。例如，您可以在脚本运行前后快照文件，然后使用 git diff 确定代理添加了哪些内容。

---

许可证

本规范在 CC BY 4.0 下发布。

贡献

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

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

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

agent-trace 快速上手指南

环境准备

• 系统要求：Python 3.8+
• 前置依赖：
  • jsonschema（用于验证数据格式）
  • git（用于版本控制相关操作）

安装步骤

pip install agent-trace --index-url https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

创建简单 trace 记录

from agent_trace import create_trace

trace_data = {
    "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"
                        }
                    ]
                }
            ]
        }
    ]
}

create_trace(trace_data, "trace_record.json")