会话即提交信息

一位开发者接手了一个代码库。git blame显示47个文件在一次提交中被修改。提交信息写着：”refactor auth module。”提交者显示为一位人类开发者。但实际作者是一个运行了90分钟的编码智能体，它读取了200个文件，评估了三种替代方案，因具体原因否决了其中两种，并产生了涉及每个身份验证端点的变更集。那90分钟的设计决策、被否决的替代方案和讨论过的边缘情况全部消失了。Git保留了什么变了。但没有任何东西保留为什么。

我的认知债务文章将智能体输出速度与开发者理解速度之间的差距命名为”认知债务”——一种随着每次未审查的提交而不断累积的负债。¹ Memento项目获得了100个HN积分和124条评论，它提出了下一个问题：如果会话包含了推理过程，那么会话是否应该成为提交的一部分？²

摘要

Git记录了什么变了。智能体会话记录了为什么。当智能体编写代码时，会话记录才是真正的设计文档，而每个丢弃记录的工作流都丢弃了溯源信息。Memento（一个开源Git扩展）将AI会话记录作为git notes附加到提交上，创建从提交到推理的溯源链。Claude Code的新LSP集成增加了结构化代码理解能力，使会话记录更加精确：跳转到定义取代了grep，类型签名取代了猜测。以下内容涵盖：溯源缺口、会话元数据的四个层次、Memento的构建方式、LSP如何改变会话数据的质量，以及您今天就能实施的最低溯源实践。

溯源缺口

Git对每次变更追踪五项信息：谁做的、什么时候、哪些文件改了、差异内容，以及提交信息。对于人类编写的代码，提交信息弥合了差异与意图之间的鸿沟。一条好的提交信息解释了变更存在的原因。一条糟糕的信息（”fix stuff”）则让审查者不得不从代码中重建意图。

智能体编写的代码具有不同的溯源结构。意图并不存在于开发者的脑海中。意图存在于会话中：启动任务的提示词、智能体读取的文件、它评估的替代方案、它调用的工具，以及它在报告完成时引用的证据。用一行话总结90分钟智能体推理的提交信息，丢弃了99.9%的决策上下文。

这种损失并非理论上的。我的编排系统生成会话状态文件（jiro.state.json、jiro.progress.json），记录每个故事的完成情况、审查者的裁定和证据关卡的结果。³当审查者问”为什么智能体使用了指数退避而不是断路器？”时，会话状态文件包含着答案：智能体评估了两种模式，发现上游服务返回带有Retry-After头的可重试503响应，因此选择了指数退避以遵循头部值。提交信息写着”refactor: standardize retry patterns。”而会话状态记录了原因。

没有会话溯源，对智能体编写的变更进行代码审查就变成了考古学。审查者阅读差异，逆向工程推理过程，然后形成关于变更存在原因的理论。这个理论可能是错的。智能体的实际推理是可获得的，记录在会话记录中。行业标准工作流（提交、推送、审查差异）把推理过程丢弃了。

当智能体组合使用时，问题成倍增加。我的编排系统为代码审查生成专门的子智能体：正确性审查者、安全审查者、规范审查者。⁵每个子智能体运行自己的会话，读取自己的文件，形成自己的结论。父智能体汇总裁定结果。最终的提交信息写着”3 reviewers: approve。”三个独立的审查会话——每个都包含具体发现、边缘情况分析和批准理由——存在于提交从未引用的单独记录中。每一层智能体委托都增加了一层不可见的推理。

溯源问题与三种已知的失败模式相关联。虚构防火墙指出当不存在输出关卡时，智能体会如何发布未经验证的声明。⁶会话溯源本可以更早发现虚构：会话记录显示智能体编造了一种没有人类审查过的token计数方法。不可见的智能体记录了如何在没有显式检测的情况下智能体行为不受监控。⁷会话溯源就是可见性栈生成的审计追踪。NIST公开评论建议对智能体行为进行标准化审计日志记录。⁹将会话记录存储为git notes是该建议的一种实现方式。

我的质量体系中的证据关卡要求智能体为每个质量标准引用具体证明：命名模式、解释替代方案、列出边缘情况、粘贴测试输出。¹⁰证据关卡迫使智能体生成推理层和验证层的数据，否则这些数据将不会存在。没有关卡时，智能体报告”完成”，会话中只包含过程数据（工具调用）。有关卡时，会话包含审查者可以对照代码验证的显式理由。

仅靠Git无法区分一个代表90分钟仔细推理的47文件提交和一个代表智能体在无审查状态下不受约束运行90分钟的47文件提交。Git文档将notes描述为”可以附加到对象上而不改变对象本身的额外信息。”⁸会话记录完全符合这一定义：关于提交溯源的额外信息，不改变提交哈希、差异或历史记录。

Memento之问

Memento项目用一个Git扩展回答了溯源缺口的问题。²该工具捕获AI编码会话记录，并将其作为git notes附加到提交上，存储在refs/notes/commits和refs/notes/memento-full-audit中。

工作流程：git memento init配置仓库。git memento commit <session-id>替代git commit，自动从配置的AI提供商（Codex或Claude Code）检索会话记录，并将其作为结构化元数据存储在提交上。

124条HN评论讨论呈现了四种立场：

立场一：会话是必要的上下文。智能体会话包含提交信息无法承载的推理。将会话附加到提交上保留了溯源链。审查者可以将任何一行代码追溯到提交、会话和原始提示词。

立场二：会话是噪声。一个90分钟的会话记录是数千行对话。其中大部分与最终变更集无关。附加完整记录将信号淹没在噪声中，使审查变得更难而非更容易。

立场三：要摘要，不要记录。会话应该被提炼为结构化摘要：任务描述、考虑的替代方案、决策理由、引用的证据。摘要保留溯源而不产生噪声。Memento生成标记了用户和助手轮次的markdown摘要。

立场四：隐私和安全顾虑。会话记录可能包含API密钥、内部URL、来自其他文件的专有代码，或开发者不希望出现在永久Git记录中的对话内容。会话在附加前需要脱敏处理。

四种立场都有道理。会话的溯源价值是不可否认的。噪声问题是真实存在的。隐私顾虑是结构性的。Memento解决了立场一和立场三（记录存储与markdown转换）以及立场四（将记录视为不可信数据进行摘要生成）。立场二仍是一个开放的设计问题：多少会话上下文才足够？

溯源的四个层次

智能体会话元数据组织为四个层次，每个层次回答关于变更的不同问题。

每个层次都有成本。存储完整的意图层（原始提示词）很廉价：一个文本字段。存储90分钟会话的完整过程层（每次工具调用）会生成数兆字节的JSON。存储推理层需要智能体显式叙述其决策过程，而大多数智能体默认不会这样做。存储验证层需要与测试运行器和审查系统集成。

我的编排系统通过不同机制捕获所有四个层次。³使捕获成为可能的钩子基础设施横跨15种事件类型的84个钩子。⁵意图：UserPromptSubmit钩子记录原始提示词。过程：PostToolUse钩子记录每次工具调用和结果。推理：证据关卡要求智能体为每个质量标准引用具体理由。验证：jiro.state.json文件记录测试输出和审查者裁定。

钩子还追踪智能体调用了哪些技能以及调用顺序。¹¹由/review技能后跟/test技能产生的提交与单次非结构化会话产生的提交具有不同的溯源特征。技能序列揭示了工作流模式：先审查后测试，还是先测试后审查？顺序对理解质量保障覆盖度很重要。数据分布在多个状态文件中。问题在于没有任何数据附加到git提交上。

LSP作为溯源桥梁

Claude Code的新LSP（语言服务器协议）集成改变了会话溯源数据的质量。⁴

在LSP之前，Claude Code通过grep和文件读取来导航代码库。当智能体需要查找函数定义时，它在所有文件中搜索函数名。搜索返回模糊结果：多个匹配项、部分匹配、包含函数名注释的测试文件。智能体选择最可能的匹配项。会话记录记载：”搜索了authenticate_user，在auth.py、test_auth.py和middleware.py中找到。”溯源数据包含搜索过程、歧义性和智能体的最佳猜测。

有了LSP，智能体调用goToDefinition并在约50毫秒内收到确切的文件和行号。⁴会话记录记载：”authenticate_user定义在auth.py:47。”溯源数据精确、无歧义且可机器验证。审查会话的审查者可以确信智能体找到了正确的定义，而不是另一个模块中名称相似的函数。

这种改进在整个会话中不断累积。使用grep读取200个文件的智能体生成的会话数据充满了”搜索了X，找到潜在匹配项A、B、C，选择了A。”使用LSP读取200个文件的智能体生成的会话数据则表述为”X定义在file:line，引用在file:line、file:line、file:line。”基于LSP的会话是智能体代码理解的精确地图。基于grep的会话是一个模糊近似。

LSP增加了六项提升溯源质量的能力：

溯源的意义在于：来自LSP赋能智能体的会话记录作为设计文档更有价值，因为每一步代码导航都是可验证的。审查者可以确认智能体对代码库的理解是正确的，而不仅仅是看似合理的。

会话元数据的实际样貌

来自我的编排系统的真实示例。故事：”为身份验证端点添加速率限制。”

意图层（来自UserPromptSubmit钩子）：

Prompt: "Implement rate limiting on POST /auth/login.
  Use sliding window, 5 attempts per minute per IP.
  Return 429 with Retry-After header."

过程层（来自PostToolUse钩子）：

Files read: 14 (auth/, middleware/, tests/)
Files written: 3 (rate_limiter.py, auth.py, test_rate_limit.py)
Bash commands: 7 (pytest x3, pip install x1, curl x3)
Duration: 23 minutes
Token usage: 87K input, 24K output

推理层（来自证据关卡）：

Pattern: Sliding window (token bucket rejected
  because per-IP granularity requires separate
  counters, sliding window handles this natively)
Edge cases: IPv6 normalization, proxy headers
  (X-Forwarded-For validated against trusted proxy list)

验证层（来自jiro.state.json）：

Tests: 12 passed, 0 failed, 0 skipped
Reviewers: correctness (approve), security (approve),
  conventions (approve with note: add docstring to
  rate_limiter.py:RateLimiter class)
Evidence gate: 6/6 criteria met

同一变更的提交信息：”feat: add rate limiting to auth endpoint。”十四个单词。会话元数据包含2300个单词的结构化溯源信息。提交信息与会话上下文之间的差距是两个数量级。

溯源的代价

会话溯源并非免费。三项成本制约着采用。

存储。一个90分钟的智能体会话生成500KB至2MB的原始记录。按每天10次提交计算，完整记录每天为Git仓库增加5至20MB。Git notes将数据存储在主历史之外（默认不影响git clone大小），但refs/notes/memento-full-audit中的审计追踪会不断累积。Memento的markdown转换将原始大小减少约60%。²

隐私。会话记录包含智能体看到的一切：文件内容、环境变量、API响应、带有堆栈追踪的错误信息。附加到公开仓库的记录会暴露内部实现细节。Memento将记录视为不可信数据，并指示摘要模型忽略嵌入的指令，但完整审计追踪中的原始记录需要访问控制。²

信噪比。一个90分钟的会话中，智能体读取200个文件却只修改12个，其中包含188个文件的无关过程数据。挑战在于区分导航（噪声）和决策点（信号）。四层模型有所帮助：意图和推理是高信号，过程是混合的，验证是高信号。一个默认存储意图和推理、按需存储过程的溯源系统可以在不丢失关键决策上下文的前提下减少噪声。

您今天就能实施的措施

四种最低溯源实践，无需任何新工具：

1. 结构化提交信息。将”refactor auth module”替换为结构化格式：

feat: add rate limiting to auth endpoint

Task: sliding window rate limiter, 5/min per IP
Alternatives: token bucket (rejected: per-IP overhead)
Evidence: 12 tests pass, 3 reviewers approve
Session: 23 min, 87K tokens, 14 files read

该格式是四个溯源层次的手动版本。信息在四行中回答了意图（任务）、推理（替代方案）和验证（证据）。无需任何工具。

2. 将会话记录与提交一起保存。在智能体会话结束后，将记录导出为仓库中的文件（例如.sessions/2026-03-02-auth-rate-limit.md）。对于公开仓库将文件添加到.gitignore，对于内部仓库则提交它。记录无需git notes基础设施即可供审查使用。

3. 标记智能体编写的提交。使用git trailer标记智能体产生的提交：

Agent: Claude Code (Opus)
Session-Duration: 23m
Files-Read: 14
Files-Written: 3

trailer创建了智能体参与的机器可解析记录。git log --grep="Agent: Claude Code"列出所有智能体编写的提交。元数据使未来的工具能够在无需追溯注释的情况下重建溯源链。

4. 要求智能体提交时通过证据关卡。在智能体提交前，要求它回答六个问题：代码遵循什么模式？存在哪些更简单的替代方案？处理了哪些边缘情况？测试是否通过？您检查了哪些文件的回归？变更是否解决了实际问题？¹⁰答案构成推理层和验证层。没有关卡时，智能体报告”完成”，会话中只包含过程数据。有关卡时，每次提交都会作为质量保障的副产品生成结构化溯源信息。

证据关卡实践与更广泛的溯源论证相关联。一个必须在提交前为其决策提供理由的智能体，比一个不受约束运行的智能体生成更高质量的会话元数据。关卡将溯源从被动副产品（记录发生了什么）转变为主动质量信号（要求智能体解释发生了什么以及为什么）。

核心要点

致工程管理者：每个只有一行信息的智能体编写提交都在丢弃设计文档。会话记录包含推理过程。请决定这些推理对您团队的代码审查、入职培训和事件响应工作流是否有价值。如果答案是肯定的，至少实施结构化提交信息。

致开发者：当您接手智能体编写的代码时，提交信息告诉您什么变了。会话记录（如果保留的话）告诉您为什么。在团队的智能体工作流中推动会话溯源。Memento项目提供了一种Git原生方式。结构化提交信息提供了零基础设施的起点。

致工具开发者：LSP集成通过用精确、可验证的代码引用替代模糊的基于grep的导航，使会话记录更有价值。对智能体代码理解的每一次改进都提升了会话生成的溯源数据的质量。请构建保留四个溯源层次的导出格式。

常见问题

什么是会话溯源？ 会话溯源是AI智能体在编码会话期间推理过程的记录：原始任务、读取的文件、评估的替代方案、做出的决策和产生的证据。会话记录捕获了提交信息和差异无法承载的”为什么”。

什么是Memento？ Memento是一个开源Git扩展，捕获AI编码会话记录并将其作为git notes附加到提交上。该工具支持Codex和Claude Code，生成markdown摘要，并提供GitHub Action用于PR集成。²

LSP如何改善智能体会话？ 语言服务器协议为智能体提供结构化代码理解：精确的定义、带类型的引用、调用层次和实时诊断。来自LSP赋能智能体的会话记录包含精确、可验证的代码导航数据，而非模糊的grep结果。⁴

会话记录应该提交到Git吗？ 答案取决于仓库的隐私要求。对于内部仓库，提交记录保留了溯源信息。对于公开仓库，git notes（默认在clone时不会传输）或带有提交引用的独立存储是更安全的方式。²

会话溯源需要多少存储空间？ 一个典型的30分钟智能体会话生成200KB至800KB的原始记录。Git notes将数据存储在主对象数据库之外，默认保持git clone大小不变。Memento的markdown转换将原始大小减少约60%。对于每天运行10至20个智能体会话的团队，预计每天产生2至10MB的溯源数据，相当于每个会话一张中等分辨率截图。²

智能体可观测性与会话溯源之间有什么关系？ 智能体可观测性实时监控智能体的行为：资源消耗、策略合规性、运行时行为。⁷会话溯源则在事后记录智能体做了什么决策以及为什么。可观测性回答”智能体现在的行为是否正确？”溯源回答”上周二智能体为什么做出了这个选择？”两个系统相辅相成：可观测性实时捕获问题，溯源在事后解释问题。

参考来源