Docket：给 AI 编程 Agent 的每次提交留下可验证证据

AI 编程工具正在从"帮你补一行代码"走向"替你完成一次提交"，但代码生成速度的提升，反而把软件工程里一个老问题推到了台前：这次提交到底是怎么产生的，谁验证过，出了问题能不能复盘？

Docket 是一个面向 AI 编程 Agent 的开源证据记录工具，它把一次提交与生成该提交的完整工作过程关联起来，包括对话提示词、工具调用、文件变更和验证结果。项目的核心判断很直接：当代码越来越多由 Agent 写出时，Git 只记录最终结果已经不够了。

这不是又一个代码生成器，也不是给提交信息加上"AI 编写"标签的插件。Docket 试图补上的，是 AI 编程工作流中缺失的证据层：从哪个任务开始，到 Agent 看到了什么、执行了什么、改动了哪些文件，再到测试和检查是否通过，全部跟着提交一起保存。

先说结论：Docket 有用，但它解决的是信任问题，不是代码质量问题

Docket 最有价值的地方，是让一次 AI 生成的提交从"结果可见"变成"过程可审计"；但它不会自动证明代码正确，也不能替代代码审查、测试和安全扫描。

传统 Git 的提交记录回答的是三个问题：提交了什么、什么时候提交、提交的作者是谁。对于人工编程，这已经足够支撑大部分协作，因为开发者本人通常能解释修改背景，Pull Request 也会补充讨论上下文。

Agent 编程则不一样。一个 Agent 可能在几分钟内读取十几个文件，调用搜索、终端、测试和编辑工具，连续修改数百行代码，最后只留下一个看起来很普通的 commit。单看 diff，团队能够看到最终差异，却看不到 Agent 为什么选择某个实现，也不知道它是否执行过测试，或者是否因为上下文不足而漏掉了关键约束。

Docket 的价值就在这里：它把"代码产物"和"生成证据"放进同一条可追溯链路。对于个人开发者，这意味着几天后还能回忆某次改动的来龙去脉；对于团队，则意味着可以在 Review、回归测试和事故复盘时检查 Agent 的工作过程。

不过，证据不等于正确性。一个记录完整的错误决策，仍然是错误决策；一次通过了浅层测试的修改，也不代表没有边界漏洞。因此，Docket 更像 Git 之上的 provenance（来源追踪）层，而不是自动验收系统。

它具体记录什么：从聊天窗口进入版本控制

Docket 记录的是一次 Agent 会话与提交之间的关系，而不仅仅是最终的 commit message。根据项目介绍和相关讨论，它关注的主要信息可以拆成四类。

| 证据类型 | 记录内容 | 对团队的实际价值 | |---|---|---| | 任务与提示词 | 用户目标、约束条件、补充要求 | 判断 Agent 是否理解了原始需求 | | 工具调用 | 搜索、读文件、写文件、终端命令、测试命令 | 复盘 Agent 实际做过什么 | | 文件变更 | 修改、创建、删除的文件及对应提交 | 将行为与最终 diff 对齐 | | 验证结果 | 测试、构建、静态检查等执行结果 | 判断提交是否经过可重复验证 |

这里最关键的不是"保存聊天记录"，而是把聊天记录和版本控制事件绑定起来。单独保存对话，容易变成一堆无法定位的日志；单独保存 diff，又会丢掉决策上下文。只有当会话、动作和提交之间存在明确关联，证据才有工程价值。

可以把它理解成航空事故调查中的飞行数据记录器。Git diff 像飞机落地后的外观照片，能看到结果；Docket 试图补上飞行过程中发生过什么、哪些操作触发了变化、仪表是否报警等过程数据。它未必能阻止事故，但能显著降低调查成本。

为什么现在需要这层记录

AI Agent 的自主性越高，传统"看最终 diff"的审查方式就越容易失效。

早期的代码补全工具通常只生成一个函数或几行代码，开发者可以在编辑器里即时判断。现在的 Agent 会先分析仓库，再规划任务，随后连续调用工具，可能跨越多个模块完成重构。修改规模变大之后，人的注意力很难覆盖每一步，最终审查也更容易被"看起来合理"的代码带过。

参考资料中提到的一个现实问题是：有的 Agent 通过专用 Bot 账号提交，有的把 AI 身份藏在 commit message 里，有的只留下 CLAUDE.md、AGENTS.md 或编辑器配置文件，还有的依托 Pull Request 平台留下痕迹。这些方式都能说明"可能是 AI 写的"，却不能说明 Agent 做过哪些操作、使用了哪些上下文，更不能证明测试是否真实执行。

这就是身份标记和证据记录的区别。"AI-generated" 是标签，Docket 想提供的是可检查的工作履历。前者只能提醒审查者提高警惕，后者才能帮助审查者定位风险。

与 Git、Pull Request 和 Agent 日志是什么关系

Docket 不是 Git 的替代品，而是给 Git 提交增加过程上下文。

Git 擅长保存文件内容的历史、分支关系和提交差异；Pull Request 擅长承载团队讨论、审批和合并状态；Agent 自身的日志则通常最了解模型推理前后的工具调用。Docket 的意义在于把这些信息围绕一次提交组织起来，形成可追溯的证据单元。

| 机制 | 擅长记录什么 | 主要缺口 | |---|---|---| | Git | 文件快照、diff、提交关系 | 不知道代码为何被生成，也不知道执行过哪些 Agent 操作 | | Pull Request | Review 意见、审批、CI 状态 | 上下文可能分散，无法完整还原本地 Agent 会话 | | commit message 标签 | AI 身份或生成来源提示 | 信息量极少，不能证明过程和验证质量 | | Agent 原生日志 | 对话、工具调用、局部执行过程 | 常与版本库脱节，难以按提交定位 | | Docket | 会话、操作、变更、验证与提交的关联 | 仍需依赖测试和审查来判断正确性 |

这个定位很重要。如果团队已经有完善的 Agent 审计系统、CI 证据归档和可复现构建，Docket 的新增价值可能有限；但对正在把 Claude Code、Cursor、Codex 或自研 Agent 接入研发流程的团队，它提供了一个相对清晰的最小抽象：每个 Agent 提交都要带证据。

真正的难点不是记录，而是证据是否可信

Docket 面临的第一项挑战，是如何防止证据记录本身被篡改或选择性记录。

如果 Agent 可以修改代码，也可以自由删除日志、伪造测试结果，那么所谓审计轨迹就只是另一个由 Agent 生成的文本文件。要让证据具备可信度，至少需要考虑几个问题：日志是否与提交哈希绑定，记录是否包含命令退出状态，测试输出是否完整保存，时间顺序能否验证，以及开发者能否在本地重放关键步骤。

第二项挑战，是敏感信息泄露。提示词和工具调用可能包含源码片段、内部路径、环境变量名、数据库结构和业务规则。把完整会话放进仓库或远程平台，可能让原本只在本地存在的信息进入团队共享范围。因此，实际部署时应当区分公开证据、团队内部证据和受限审计材料，尤其要对访问令牌、密码、个人信息和客户数据做脱敏。

第三项挑战，是记录太多会降低可读性。完整保留每一次文件读取和终端输出，短期看很彻底，长期看可能产生海量噪声。好的证据系统不能只追求"什么都记"，还要提供按提交、文件、命令和风险级别筛选的能力。审查者需要的是一条能快速定位问题的路径，而不是再打开一个几百页的聊天记录。

验证闭环比事后追责更重要

AI 编程的关键流程，不应该是 Agent 写完代码后人类被动验收，而应该是把验证结果自动反馈给下一轮 Agent。

一个更可靠的闭环通常包括四步：第一，Agent 在明确任务和约束后生成修改；第二，系统自动执行单元测试、集成测试、类型检查和静态分析；第三，Docket 将命令、版本、退出状态与输出关联到本次提交；第四，失败信息作为下一轮上下文，让 Agent 修复后重新验证。

这与测试驱动开发中"先测再改"的思想相近，但重点从开发者个人习惯扩展到了 Agent 工作流。参考资料中提到，有些 Agent 先完成两百多行 Production Code，再补测试；也有些先取得有效的 Red，再开始实现。两种方式都可能最后显示绿灯，但过程证据和可还原范围完全不同。

如果系统只保存最后一次绿色结果，审查者可能误以为整个过程都经过约束；如果它保存了从失败测试到修复提交的链路，团队才能判断 Agent 是否真正解决了问题，还是通过修改测试、跳过检查等方式获得了绿灯。

因此，Docket 最值得关注的不是日志界面，而是它能否成为验证闭环的一部分：让每一次提交都带有"我做了什么、我检查了什么、检查结果是什么"这三类信息。

对个人开发者和团队分别有什么用

对个人开发者而言，Docket 主要解决的是记忆和复盘问题。Agent 生成的代码往往在当下看起来合理，但几天后再次修改时，开发者可能忘记最初的限制条件，也不记得某个兼容性判断是自己做的还是 Agent 推断的。有了提交级证据，后续维护可以直接回到原始上下文，而不是重新猜测。

对团队而言，价值更多体现在责任边界和协作效率。AI 参与开发后，"谁写的"这个问题正在失去一部分意义，团队更需要知道"谁定义了目标、谁批准了结果、哪些检查实际通过"。Docket 可以为代码审查提供额外依据，也能在线上故障后快速回答：这段逻辑由哪个任务产生，Agent 访问过哪些文件，最后一次测试覆盖了什么。

对高风险项目而言，这类记录尤其适合用于合规和安全审计，但不能简单把它当作合规认证。真正的合规还涉及权限控制、数据保留期限、访问审计、加密、人员审批和可复现构建。Docket 能提供其中的过程证据，却不能单独替代 SOC 2、ISO 27001 或行业监管要求。

目前它更像早期基础设施，而不是成熟平台

从产品判断看，Docket 的方向是对的，但项目的实际成熟度仍应以 GitHub 仓库中的代码、文档、发布记录和 Issue 状态为准，不能仅凭"可验证证据"这个概念就把它视为完整企业级解决方案。

它最适合的切入场景，是已经使用 Git、测试和 Agent 工具，却发现提交记录无法解释 Agent 工作过程的团队。与其一开始就追求复杂的智能审计，不如先建立几个可执行的最低要求：每个 Agent 提交必须关联任务；每次修改必须保存变更范围；测试命令必须记录退出状态；失败结果不能被绿色结果覆盖；敏感上下文不能未经处理进入共享日志。

如果 Docket 后续能够进一步提供不可抵赖的证据签名、细粒度脱敏、与 CI 平台的稳定集成，以及对不同 Agent 客户端的统一适配，它的价值会从"方便复盘"上升到"可以作为工程门禁的一部分"。反过来，如果它只是把聊天记录堆到 Git 旁边，缺乏提交绑定和验证语义，最终很可能变成另一套没人愿意看的日志。

OpenAI Hub 判断：AI 编程下一阶段，拼的是可解释的交付

Docket 抓住了 AI 编程从个人效率工具走向团队生产基础设施后的真实矛盾：模型可以更快地产出代码，但速度越快，组织越需要知道结果是否可追溯、过程是否可验证。

我们认为，"每次提交留下证据"会逐渐成为 Agent 编程的基础能力，就像今天的 Git 提交、CI 检查和代码 Review 一样。它不会让 Agent 自动变可靠，却能让不可靠的地方更容易被发现；它不会替开发者做决定，却能让开发者在做决定时拥有更多上下文。

对个人用户，Docket 值得尝试，但建议把它当作复盘工具，而不是质量背书。对团队用户，真正值得评估的是三点：证据能否与提交强绑定，日志能否防篡改和脱敏，验证结果能否进入下一轮 Agent 上下文。三点都做到，Agent 才不只是"会写代码"，而是开始具备可审计的交付能力。

这也是 Docket 这类工具的长期意义：未来的软件仓库里，最重要的记录可能不再只是代码和 diff，还包括代码为什么这样写、哪些假设被验证过，以及当时的 Agent 到底看到了什么。

参考来源

1. Docket – Per-commit evidence records for agent-written code：Docket 项目仓库，介绍其面向 Agent 生成代码的提交级证据记录思路。
2. AI 程序员真的开始提交代码了：讨论 AI Agent 在 Git 提交、Bot 身份和开发配置文件中的不同留痕方式。
3. 和先測再改有什麼差別？比較直接完成、TDD 與 TCR：比较先测再改、TDD 与 TCR，说明过程证据和最终绿色结果的差异。

本文基于截至 2026 年 9 月 13 日可获得的项目介绍与公开资料整理。Docket 的具体功能、兼容范围和安全能力应以其 GitHub 仓库的最新代码与文档为准。