不管你是做传统软件开发还是已经在用AI辅助编程日常肯定绕不开一个场景看代码的时候发现一行改动很可疑想知道当初为什么这么写于是敲下git blame结果只看到一个提交hash、一个作者、一个“fix bug”之类的提交说明然后就没有然后了。Git blame能回答“谁改的、什么时候改的”但回答不了“他到底怎么想的、改之前看到了什么线索、改完有没有发现副作用”。我最近花了些业余时间捣鼓了一个小工具项目名叫ctx定位就是补上这块缺口让Git blame的每一行都可以直接返回到当时生成这行代码的AI agent的原始执行记录也就是agent transcript。今天就把它整体拆开聊聊从设计思路、核心实现到踩坑记录都过一遍。1. 这个东西到底在解决什么问题先说清楚context。现在用AI写代码已经不是“试试看”的玩法了很多团队已经让agent真正参与到日常开发里跑测试、改bug、做重构甚至在CI里自动修问题。Git提交历史里记录的提交人可能已经不是人而是某个agent的ID或者指定账号。这样的好处是效率高坏处也明显代码的可解释性断了。过去代码审查靠人聊天、靠设计文档、靠代码注释但agent写代码时不会主动把“我为什么选这个方案、我试过哪几种写法、我看到编译报错后做了哪些调整”写进commit message里。这些信息全部淹没在agent一条条的工具调用日志、键盘输入记录和中间决策里。一旦commit合入主线再有人回来看这段代码就只能面对一个干巴巴的diff。我做ctx的初衷就是把这些本来要被丢掉的上下文捡回来。工具本身用一个命令就能跑使用方式非常贴近前端开发者的心智模型ctx blame src/components/DataTable.tsx它做的事情和Git blame基本一样但返回的每一行除了有commit hash之外还额外附加了一个标记这行改动有没有对应的agent transcript可以查看。如果有直接跟着命令追进去看完整记录ctx show 3f2a7c9这里面的3f2a7c9就是commit hash的前缀ctx会顺着它找到当时agent的完整执行记录。对着这份记录你能看到agent在下这个修改决策前完整看到了哪些报错信息、尝试过哪些修复路径、最后为什么选择留下这一版代码。这比任何注释都来得实在因为它是当时真正发生的原始思考轨迹。而且这是个通用的概念不限语言、不限框架只要你的项目里产生过agent执行日志ctx就能挂上这条“代码行到思考现场”的索引链。哪怕你团队目前根本没用agent写代码只要提交历史里偶尔混入了自动化工具、脚本、批量改写工具的产出这套逻辑同样成立任何非人工的代码行为都应该能回溯到它原始的执行记录。2. 核心设计为什么锚定在 Git blame 而不是文件快照动手做ctx之前我其实纠结过另一个方案文件级别的快照对比。就是agent每跑一个阶段就存一份整个目录的快照最后想查某一行的历史时把快照之间做diff看到底是哪一步改动了这里。这个思路看上去更简单直接但实践里很快发现几个硬伤。第一是粒度问题。快照对比只能告诉你“这个文件被改建过、变动发生在这个时间点”却无法给出精确到行的映射。你想问的是“屏幕上第237行这个正则是谁在什么情境下引进来的”快照对比给你的是一个几十KB的diff靠眼睛在diff里找对应关系纯属浪费时间。第二是冗余问题。一个稍大的前端项目动辄几百个文件agent跑一个半小时的任务可能产生几十个快照全部存下来存储成本很高。即便压缩这个代价也是持续的。第三是心智负担问题。Git blame是每个用Git的人都已经掌握的标准工具它的输出格式稳定、语义清晰单纯用它的人不需要学习任何新概念。ctx只是把blame的结果映射到另一层数据上而不是发明一套新的代码追责体系。所以ctx的定位从一开始就明确了不重新发明轮子而是在Git自带的能力之上做映射。Git blame负责给出“哪一行在哪个commit里出现”ctx负责把“commit hash”翻译成“agent回顾日志”职责分离各干各的。其实这个设计的核心思路可以类比成可观测性领域常说的“trace”代码提交是spansagent transcript是完整的trace链路。git blame给你一个span IDctx把这个span ID串回整个trace让你看到它在整个事件流里的位置。3. 数据结构和存储如何组织agent transcript要实现“blame → transcript”的映射transcript本身得存储成可被检索的结构。我一开始想得很理想用SQLite存meta信息把transcript内容按段落分开存储支持全文检索。后来发现对多数项目来说这就是过度设计一个本地CLI工具牵着数据库跑没人会愿意为了看一行代码的历史去初始化数据库。现在的方案是非常朴素的文件目录索引文件。agent每完成一个任务会把执行记录导出为一个Markdown文件以commit hash作为文件名前缀比如3f2a7c92e1b4.md。放到项目的.ctx/transcripts/目录下。这个目录可以跟随项目仓库走也可以放到Git的common dir里作为本地索引看你的隐私需求。一个transcript文件内部的结构大概是这样的# Agent Session Transcript commit: 3f2a7c92e1b4 timestamp: 2025-01-04T14:22:3108:00 task: 修复白屏问题 ## Step 1: 分析报错 查看浏览器console发现Uncaught TypeError: Cannot read properties of undefined ## Step 2: 定位问题范围 追踪到DataTable组件中dataSource字段在初始化前被访问 ## Step 3: 尝试方案A 给dataSource设置默认值 []但控制台仍报错 ## Step 4: 尝试方案B 修改父组件传入时机确保先加载数据再渲染表格 ## Step 5: 验证 本地跑测试通过无控制台报错这个结构有几个关键设计考量。一是步骤带序号这样ctx在展示时可以按时间线真实还原不会把agent的思考过程凑成一段说明文。二是每个步骤都包含“尝试了什么方案结果是什么”这种Fail/Retry的循环是调试现场最珍贵的信息如果只记录最终成功路径等于丢掉了大量上下文。三是头部有明确的task描述这个描述往往能直接对应到一个用户issue或者一次code review的讨论上下文。存储层解决后接下来的关键就是建立commit和transcript文件的双向索引。ctx在首次运行时会扫描.ctx/transcripts/目录把文件名里的commit hash和文件内容里记录的commit字段都读取出来建立内存索引。后续运行时这个索引可以缓存到.ctx/index.json避免每次启动都重新解析所有markdown文件。4. 核心实现ctx的解析、关联、展示三阶段第一版ctx的实现比预想中复杂度高不少核心链路分三段解析blame输出、关联transcript、渲染结果。4.1 解析Git blame输出Git blame的输出格式本身不复杂每行大致长这个样子3f2a7c92 (agent-user 2024-12-30 11:23:45 0800 42) const data rows.map(item item.id);一个合格的解析器要把commit hash、作者、日期、原始行号、代码内容拆开。这些用正则就能搞定。但真正的问题来了Git blame输出里存在boundary commit的概念首次提交某些行前会带^前缀还有commit hash因为--abbrev参数长短不定日期格式在中文和英文环境下的locale差异也很大。实测下来最稳妥的方案是用git blame --line-porcelain它会输出机器可读的键值对格式字段顺序固定解析起来远比人读格式可靠。ctx在底层调用这个命令然后构造出类似这样的结构体type BlameLine struct { CommitHash string Author string Timestamp time.Time LineNumber int Content string }拿到完整文件的blame结果后我按commit hash做了聚合。这样同一批改动可以合并到同一次展示里而不是以单个行为单位散落在结果中。4.2 关联agent transcript第二步是把拿到的commit hash关联到transcript。这部分的匹配逻辑我刻意保持简单先按hash精确匹配如果找不到再走模糊匹配——允许git commit hash简写匹配到transcript里的完整hash。匹配成功后还需要解析transcript文件里的step节点按顺序挂到一个时间线上方便后面展示。这一步看起来简单实际坑不少。agent产生的commit hash并不总是和transcript里的commit完全一致。比如agent可能先commit一次后来amend了或者cherry-pick后hash历史变了。原hash对应的transcript还在但git历史里已经没有这个hash了。这种情况要在ctx里给用户明确提示这条transcript可能对应的是一个已漂移的commit信息只能作为参考。另一个情况是多个commit对应同一份transcript。一个长任务里agent可能会频繁commit多次每一份riginal的transcript却只有一个。此时ctx的展示就不该把transcript从头到尾吐一遍而是只展示该commit在transcript时间线里的那一段上下文前后各取几步做铺垫。4.3 交互展示与定位展示了这步花了我最多时间。因为单纯的“把整个markdown抛给终端”谈不上交互看得人眼睛疼。最后定下来的方案是分两层展示。第一层是小地图拿到transcript后首屏显示task描述、总步骤数、每个step的标题和关键操作类型。如果你只是在回顾某段代码的由来到这里基本就能找到答案。第二层才是细节展开指定某个step后ctx输出这个step下的详细内容包括粘贴的报错信息、执行的命令、改动的diff片段。实际终端里大概长这样ctx: 3f2a7c92 对应的Agent记录 task: 修复白屏问题 total steps: 5 [1] 分析报错 - 读取浏览器console - 发现 TypeError: Cannot read properties of undefined [2] 定位问题范围 - 追踪到 DataTable 组件 [3] 尝试方案A - 设置 dataSource 默认值 - 失败: 错误依旧 [4] 尝试方案B - 调整父组件传入时机 - 成功: 控制台干净 [5] 验证 - 跑相关单测通过 输入 step 编号查看详情, 输入 q 退出交互层还做了一个细节从blame模式进入show模式时ctx会自动定位到包含你在blame结果里看到的那一行代码的step而不是从step 1开始。这个体验提升很大相当于你问到痛点工具直接把诊断现场搬到你面前。5. 实操过程跑通一次完整的“代码考古”光说不练假把式。我把ctx用在一个实际改过的项目上场景是同事反馈DataTable组件在某些页面白屏。接到反馈后我先在数据加载相关逻辑上跑了ctx blamectx blame src/components/DataTable.tsx --filter dataSource终端输出的结果里除了常见的git blame字段外有一行高亮标注了3f2a7c92这个commit关联着agent transcript。接着深挖ctx show 3f2a7c92首屏快速扫过task描述确认这就是一次针对白屏问题的修复记录。前几步显示了agent观察控制台报错、检索组件内dataSource的引用随后尝试给它加默认空数组但改完运行测试仍然报错。这时候agent没有盲目继续加空值保护而是回去追踪了父组件的数据加载时机最后确定问题是父组件在异步请求返回前就渲染了子组件导致dataSource尚未初始化。修复方式是调整父组件让数据就绪后再渲染表格。看到这个transcript的瞬间我对整段代码的来龙去脉就完全清楚了。这也让我确信ctx这件事有价值如果没有transcript我只能看到一行“fix: 白屏问题”的提交说明不得不自己去读diff、翻父组件、跑测试复现循环大半天可能还在原地猜。有了transcript等于把“修复过程的思维体操”原封不动端到眼前直接省去大量无谓的考古时间。6. 常见问题与实战避坑6.1 agent没有产出transcript怎么办这是最现实的问题。agent跑完任务后不一定都配置了日志导出或者日志被CI环境清理掉了。ctrl能在blame结果里明确标记出“这条commit没有关联transcript”而不是偷摸地不显示任何信息。这能提醒用户此处是人工提交或者agent日志已丢失需要找其他途径确认改动来源。6.2 commit hash在历史中被重写怎么办团队使用rebase或者squash后原始的commit hash会变。blame结果里的hash在git历史里不存在了自然匹配不上transcript。我现在的处理方案是在git对象里查询该hash是否存在如果不存在会提示用户这可能是重写前的遗留记录并尝试用author和timestamp这两个维度做第二重匹配。这个方案不是百分百准确但实测能挽回一部分丢失的关联。6.3 transcript文件体积太大怎么展示agent一个长时间任务可能产生上百个step、几千行内容。如果一口气读进内存再展示终端直接卡死。解决办法是懒加载show命令先只解析头部信息和step标题生成小地图只有当用户选中某个step时才去读取对应段落渲染详情。这样即便transcript有10MB首屏响应也在毫秒级。6.4 代码后续被人改过blame结果不准如果一行代码在agent提交后被别人手动修改过blame看到的是更晚的commit hash自然关联不到agent的transcript。这个场景无法完全自动化解决只能靠用户审视blame结果时发现最近改动不是agent产生。ctx能做的只是在只读diff前标记一声这行代码的最近修改是人工改动若需查看agent版本的历史请用git log -L追踪更早的记录。7. 使用心得与扩展思路ctx目前在我的日常开发流程里已经变成了类似于“代码考古”的标配工具。每次review一段陌生代码或者修复一个历史bug都会习惯性先跑一遍ctx blame看能不能捞出当时的agent现场。这不光帮我自己省时间在帮团队其他成员解释一段代码“为什么会这样写”的时候也有了除了“我当时看文档觉得这么写没问题”之外的实打实佐证。顺着这个思路往后扩展ctx还有很多可以做的方向。一是把transcript和diff做双向映射显示某一行代码改动时可以自动关联到transcript里agent执行那次编辑操作的前后上下文。二是和code review流程打通提交PR时自动附上这次改动对应的agent执行摘要审阅者不用来回切工具就能看懂改动背景。三是引入文本相似度搜索hash可能漂移但agent日志里的某个报错文本可能和当前代码的运行时错误高度相似match上之后可以直接跳转。最后一句话总结我的真实感受git blame告诉你“谁动了这块代码”但只有ctx知道“TA到底经历了什么才把代码改成了这个样子”。后者才是理解一份代码的全部含义所在。如果你也经常和我一样面对agent代码一脸迷惑这套“blame transcript”的组合拳值得一试。