讓 AI Agent 寫代碼真正的瓶頸往往不在生成的那一下而在生成之后的審查、維護和責任追溯。你打開一個 PR里面有一行代碼寫得很精煉你想知道 Agent 當時依據(jù)什么信息拍板你在線上日志里看到一個奇怪分支懷疑是上周那次批量重構(gòu)引入的而那次重構(gòu)由 Agent 在一小時內(nèi)完成。git blame 只能告訴你提交人和提交時間給不出當時給 Agent 的原始指令、Agent 調(diào)用過哪些工具、中間報過什么錯、最后為什么選了這種寫法。這里討論的工具思路就是補上這一環(huán)給定倉庫里任意一行代碼立刻拿到生成這行代碼的那段 Agent 會話 transcript本質(zhì)上是在把 git blame 擴展成“Agent 會話回溯”。這篇博客會先講清楚為什么 Agent 生成的代碼比傳統(tǒng)代碼更需要 traceability再拆解 transcript 的數(shù)據(jù)形態(tài)然后帶你寫一個最小可用的查詢工具。最后會討論行號漂移、索引更新、隱私邊界等實際問題。文章里的代碼和命令用于說明實現(xiàn)思路落地時請根據(jù)自己使用的 Agent 工具、日志格式和項目結(jié)構(gòu)調(diào)整。1. 為什么需要給 Agent 寫的代碼做溯源1.1 git blame 能回答誰寫的回答不了為什么這樣寫傳統(tǒng)項目里一行代碼的來源通常靠兩條信息確定git blame 顯示的提交信息以及提交信息里的 commit message。如果提交規(guī)范做得好你還能看到關(guān)聯(lián)的 issue 號或需求單號。這套機制假設(shè)一個前提提交作者能清楚解釋代碼意圖而且代碼是經(jīng)過人類思考后寫出來的。Agent 寫代碼時這個鏈條斷了。一個 Agent 會話可能連續(xù)修改十幾個文件每個文件里包含大量邏輯。最終提交時commit message 一般只寫“用 Agent 完成某個需求”不會記錄 Agent 在中間嘗試過哪幾種方案、為什么放棄另一種寫法、用戶在某一步補充了什么約束。于是當你站在一串詭異的條件判斷面前能獲取的信息只剩“誰提交的”和“什么時候提交的”。這不是說 commit message 沒用而是說它的信息密度不夠。要還原 Agent 寫這行代碼時的完整上下文必須回到生成它的那段會話記錄里去看。1.2 transcript 能補充哪些關(guān)鍵上下文transcript 直譯是“會話記錄”在 Agent 場景里它就是一次完整交互過程的落盤數(shù)據(jù)。拿到一段 transcript 后你能看到三類普通版本管理工具給不出的信息用戶原始指令是什么。比如“把訂單列表接口改成支持分頁”這句話決定了 Agent 后續(xù)所有動作的方向。Agent 調(diào)用過哪些工具結(jié)果如何。比如它先搜索了某個函數(shù)的用法又執(zhí)行了一條測試命令最后才修改某個文件。中間過程的錯誤和修正。比如第一次改動后測試報錯Agent 又修改了參數(shù)類型最后才通過。這些信息對代碼評審和問題排查價值很高。評審時你能確認“這段邏輯確實來自用戶指令而不是 Agent 自由發(fā)揮”排查 Bug 時你能看到“Agent 當時讀取了哪份數(shù)據(jù)文件”避免重復試錯。1.3 適合這類工具的場景和不適合的場景適合的場景包括團隊里大量使用 Agent 生成代碼需要建立可審計的變更記錄線上出現(xiàn)難排查的問題需要快速定位 Agent 當時的推理過程新成員接手舊模塊想理解某段代碼為什么長這樣。不適合的場景也要說清楚。如果一個項目只是偶爾用 Agent 補幾行樣板代碼為每行代碼建立索引的維護成本大于收益。另外如果你的 Agent 工具默認不保存本地會話或者改用了云端會話存儲從“本地文件反查”這條路徑就走不通必須換用官方 API 或?qū)С鼋涌?。這類工具解決的是“日志已經(jīng)在手邊怎么快速查到對應行”的問題而不是“沒有日志也要造日志”的問題。2. 先看懂 Agent 會話 transcript 的數(shù)據(jù)結(jié)構(gòu)2.1 一次會話由用戶消息、工具調(diào)用和結(jié)果組成目前常見的 CLI 型 Agent 工具比如 Claude Code、Codex、OpenCode 等一般會把一次會話保存成本地 JSONL 文件。JSONL 每行一個 JSON 對象行與行之間按時間順序追加。字段名在不同工具里不完全一致但整體結(jié)構(gòu)高度相似通常包含四種類型user用戶發(fā)給 Agent 的消息。assistantAgent 的文本回復或發(fā)起工具調(diào)用的請求。tool_useAgent 調(diào)用某個工具參數(shù)里包含文件名、修改內(nèi)容等。tool_result工具執(zhí)行結(jié)果比如“編輯成功”“命令退出碼為 1”。下面是一個經(jīng)過簡化的會話片段用來展示這種結(jié)構(gòu){type:user,timestamp:2025-05-10T14:22:31Z,message:修復 OrderService 中可能出現(xiàn)的空指針} {type:assistant,timestamp:2025-05-10T14:22:33Z,content:我先看 OrderService 里的 getItems 調(diào)用。} {type:tool_use,timestamp:2025-05-10T14:22:35Z,name:Edit,input:{file_path:src/order/OrderService.java,old_string:return order.getItems();,new_string:if (order.getItems() null) {\n return Collections.emptyList();\n}\nreturn order.getItems();}} {type:tool_result,timestamp:2025-05-10T14:22:36Z,content:The file has been edited successfully.}實際工具的字段名可能不同但“用戶指令 → 工具調(diào)用 → 工具結(jié)果 → 回復”的鏈條是通用的。解析日志的目標就是從這條鏈條里提取出“哪個文件被改過、改動了什么、對應哪條用戶指令”。2.2 編輯事件里藏著文件路徑和行號線索對代碼溯源來說最關(guān)鍵的事件類型是 Edit。Edit 事件的入?yún)⒁话惆齻€字段file_path被修改的文件在項目中的相對路徑。old_string被替換的舊內(nèi)容。new_string寫入的新內(nèi)容。這三者決定了你能不能用代碼定位它。一個常見的誤解是“JSONL 里會直接記錄絕對行號”。實際上大多數(shù) Agent 工具不會在日志里寫“我改的是第 42 行”它記錄的是“把 A 字符串替換成 B 字符串”。行號是事后推算出來的需要把 old_string 放回當時的文件內(nèi)容里做匹配。這帶來兩個重要推論如果文件后來又被修改old_string 可能已經(jīng)不存在行號就無法直接推算。如果 old_string 在文件里出現(xiàn)多次匹配時還要考慮出現(xiàn)順序否則容易定位到錯誤位置。2.3 從一行代碼到整體映射關(guān)系把“一行代碼”映射到“一段 transcript”本質(zhì)是建立三層索引第一層文件路徑到編輯事件列表。給定src/order/OrderService.java能拿到所有改過它的 Edit 事件。第二層編輯事件到會話位置。每個 Edit 事件關(guān)聯(lián)自己的 JSONL 文件路徑、時間戳以及它前面最近的那條用戶指令。第三層代碼內(nèi)容到編輯事件。為了應對行號漂移還需要把 new_string 的片段或哈希存進索引這樣即使文件結(jié)構(gòu)變了也能用代碼片段本身找到它最初的來源。三層索引對應一次查詢過程輸入文件路徑和行號找到 Edit 事件再找到會話記錄最后把會話里相關(guān)的上下文打印出來。這就是整個工具的核心鏈路。3. 準備 transcript 數(shù)據(jù)和運行環(huán)境3.1 你需要哪些前置條件在動手實現(xiàn)前先確認環(huán)境滿足以下條件檢查項最低要求說明Agent 工具已使用 CLI 型 Agent 完成過代碼修改需要本地有可讀取的會話日志會話日志本地存在 JSONL 或其他文本日志云端僅存儲時需先使用官方導出能力項目代碼與會話日志對應的項目目錄可訪問用于把 old_string 定位到行號Python3.9 及以上本文示例使用 Python 實現(xiàn)數(shù)據(jù)庫SQLitePython 內(nèi)置不需要單獨安裝如果原始項目中使用的 Agent 工具把會話存在云端需要先搞清楚有沒有本地緩存或?qū)С鼋涌凇]有本地日志后面的所有步驟都無法開展。3.2 找到本地 transcript 的存放位置不同工具的存放目錄差別很大。以一些 CLI 形態(tài)的 Agent 工具為例會話日志通常放在用戶目錄下的隱藏文件夾里再按項目目錄名或項目路徑編碼分目錄保存。常見路徑形如~/.claude/projects/項目編碼/session-id.jsonl具體以你安裝的工具版本為準?？梢杂孟旅婷羁焖俣ㄎ豢赡艿娜罩灸夸沴s -la ~/.claude find ~/.claude -name *.jsonl | head -20 find ~ -maxdepth 3 -name *.jsonl 2/dev/null | grep -i -E claude|codex|agent | head -20定位到目錄后再看目錄下的文件數(shù)量和大小find ~/.claude -name *.jsonl | wc -l du -sh ~/.claude這一步的目的不是找到某一個文件而是確認整個日志目錄的結(jié)構(gòu)。后面的索引程序會遞歸掃描這個目錄。3.3 用一條命令驗證日志能被正常解析寫完整工具之前先手動讀一個 JSONL 文件確認格式和字段名符合預期。用 jq 或 Python 都能快速驗證head -5 ~/.claude/projects/xxx/session-abc123.jsonl | jq .python3 -c import json, sys with open(sys.argv[1], encodingutf-8) as f: for i, line in enumerate(f): try: obj json.loads(line) print(i, obj.get(type), list(obj.keys())) except json.JSONDecodeError as e: print(parse error at line, i, e) if i 10: break ~/.claude/projects/xxx/session-abc123.jsonl如果能看到 type、timestamp、input 等字段說明日志結(jié)構(gòu)清晰可以進入下一步。如果整行報 JSONDecodeError可能是文件編碼問題或行內(nèi)容被截斷需要先處理數(shù)據(jù)完整性問題。注意會話日志里可能包含你輸入給 Agent 的完整指令以及項目中的文件路徑和代碼片段。不要把日志目錄直接提交到公開倉庫也不要把它打包發(fā)給無關(guān)人員。4. 用 Python 實現(xiàn)最小版“代碼行反查 transcript”工具4.1 整體流程解析、建索引、查詢最小工具分為三條命令index 負責掃描日志并建索引query 負責按文件和行號查詢最終把匹配到的會話上下文打印出來。完整流程是項目目錄 transcript 目錄 | v 解析 JSONL提取 Edit 事件 | v 用 old_string 在項目文件里定位行號 | v 寫入 SQLite 索引表 | v 命令行輸入 file_path line | v 反查 Edit 事件和用戶指令這里的實現(xiàn)做了簡化索引時直接在項目當前文件里搜索 old_string。它的優(yōu)點是代碼量小缺點是文件后續(xù)被改后匹配會失敗。更可靠的“回放編輯歷史”方案會在第 5 節(jié)討論。4.2 解析 JSONL 并建立線級索引下面是完整的解析和建索引代碼。它遞歸掃描 transcript 目錄下的所有 JSONL 文件提取 Edit 事件然后用 old_string 在項目文件中定位絕對行號#!/usr/bin/env python3 import argparse import json import sqlite3 from pathlib import Path def locate_string_in_file(project_root: Path, rel_path: str, content: str): 在項目當前文件中定位 old_string返回起始行號和結(jié)束行號。 full_path (project_root / rel_path).resolve() if not full_path.exists(): return None, None try: file_text full_path.read_text(encodingutf-8) except (UnicodeDecodeError, OSError): return None, None index file_text.find(content) if index -1: return None, None start_line file_text.count(\n, 0, index) 1 end_line start_line content.count(\n) return start_line, end_line def build_index(transcript_dir: Path, project_root: Path, db_path: Path) - None: conn sqlite3.connect(db_path) conn.execute(DROP TABLE IF EXISTS edits) conn.execute( CREATE TABLE edits ( file_path TEXT, start_line INTEGER, end_line INTEGER, session_file TEXT, timestamp TEXT, user_message TEXT, snippet TEXT ) ) for log_file in sorted(transcript_dir.rglob(*.jsonl)): last_user_message with log_file.open(r, encodingutf-8, errorsreplace) as fh: for raw_line in fh: try: entry json.loads(raw_line) except json.JSONDecodeError: continue if entry.get(type) user and entry.get(message): last_user_message entry[message] if entry.get(type) ! tool_use: continue tool_input entry.get(input, {}) file_path tool_input.get(file_path) old_string tool_input.get(old_string, ) new_string tool_input.get(new_string, ) if not file_path or not old_string or not new_string: continue start_line, end_line locate_string_in_file( project_root, file_path, old_string ) if start_line is None: print(fskip {file_path}: old_string not found in current file) continue conn.execute( INSERT INTO edits VALUES (?,?,?,?,?,?,?), ( str(file_path), start_line, end_line, str(log_file), entry.get(timestamp, ), last_user_message, new_string[:200], ), ) conn.commit() conn.close() print(findex built at {db_path})這段代碼有幾個值得注意的設(shè)計點用errorsreplace容忍非 UTF-8 字符避免單個日志文件導致整個索引中斷。遇到解析失敗的 JSON 行直接跳過不讓臟數(shù)據(jù)阻斷索引。只索引同時包含 old_string 和 new_string 的 Edit因為空 old_string 的插入類編輯無法用當前文件定位行號。4.3 實現(xiàn) file:line 查詢?nèi)肟诓樵兒瘮?shù)讀取 SQLite按文件路徑和行號查匹配的編輯事件。為了讓結(jié)果可讀它會輸出時間、會話文件、用戶指令和代碼片段def query_index(db_path: Path, file_path: str, line: int) - None: conn sqlite3.connect(db_path) rows conn.execute( SELECT timestamp, session_file, user_message, snippet FROM edits WHERE file_path ? AND ? BETWEEN start_line AND end_line ORDER BY timestamp DESC , (file_path, line), ).fetchall() conn.close() if not rows: print(沒有找到對應的 Agent 會話記錄。) return for row in rows: print(f時間: {row[0]}) print(f會話文件: {row[1]}) print(f用戶指令: {row[2]}) print(相關(guān)代碼片段:) print(row[3]) print(- * 60) def main() - None: parser argparse.ArgumentParser(descriptionagent blame tool) sub parser.add_subparsers(destcommand, requiredTrue) index_p sub.add_parser(index) index_p.add_argument(--transcript-dir, requiredTrue, typePath) index_p.add_argument(--project-root, requiredTrue, typePath) index_p.add_argument(--db, defaultPath(agent_index.db), typePath) query_p sub.add_parser(query) query_p.add_argument(--db, defaultPath(agent_index.db), typePath) query_p.add_argument(file_path, typestr) query_p.add_argument(line, typeint) args parser.parse_args() if args.command index: build_index(args.transcript_dir, args.project_root, args.db) elif args.command query: query_index(args.db, args.file_path, args.line) if __name__ __main__: main()查詢的核心 SQL 是一個區(qū)間判斷l(xiāng)ine BETWEEN start_line AND end_line。它假設(shè)索引時記錄的行號范圍和當前查詢的行號一致。這個假設(shè)在文件長期未改動時成立一旦文件被后續(xù)提交改動就會出現(xiàn)匹配不上的情況。4.4 運行驗證和預期輸出先建索引再查詢python agent_blame.py index \ --transcript-dir ~/.claude/projects \ --project-root ./my-project \ --db ./agent_index.db python agent_blame.py query \ --db ./agent_index.db \ src/order/OrderService.java 42如果第 42 行恰好落在某次 Edit 寫入的范圍內(nèi)預期輸出類似時間: 2025-05-10T14:22:35Z 會話文件: /home/user/.claude/projects/xxx/session-abc123.jsonl 用戶指令: 修復 OrderService 中可能出現(xiàn)的空指針 相關(guān)代碼片段: if (order.getItems() null) { return Collections.emptyList(); } return order.getItems(); ------------------------------------------------------------這個輸出說明已經(jīng)走通了“行號 → 編輯事件 → 用戶指令 → 會話文件”的鏈路。再往前一步你可以打開會話文件查看那次 Edit 前后幾條 tool_result看 Agent 是否在執(zhí)行測試后補充過修改。5. 匹配策略、索引更新與存儲選型5.1 精確行號匹配的局限第 4 節(jié)的實現(xiàn)有兩個明顯限制。第一個是 old_string 在當前文件里可能已經(jīng)不存在因為后續(xù)提交改動了這段代碼。第二個是 old_string 可能匹配到文件里另一個相同片段導致行號錯誤。更可靠的方案是回放編輯歷史。從項目在會話開始時的狀態(tài)出發(fā)按時間順序依次應用每個 Edit 事件里的 old_string 到 new_string。每次應用時都能準確知道 old_string 在“當時文件內(nèi)容”里的位置也就拿到了絕對行號?；胤乓蕾囈粋€前提你保留著會話開始時的項目快照或能通過 git 恢復到那個時點。會話開始時文件內(nèi)容 ↓ 應用 Edit1 中間狀態(tài) A ↓ 應用 Edit2 中間狀態(tài) B ↓ 應用 Edit3 得到每個事件的行號這個方案能同時解決行號漂移和多個 Edit 連續(xù)修改同一文件的問題代價是實現(xiàn)復雜度明顯上升。對于最小工具可以先用 4.3 的簡化方案確認鏈路通了再升級。5.2 內(nèi)容哈希匹配解決行號漂移行號會漂移但代碼片段本身不容易憑空消失。一種工程上常用的思路是建立“代碼片段 → 會話”的倒排索引把 new_string 切分成若干固定長度的連續(xù)代碼塊對每個代碼塊計算哈希索引表里存“哈希 → 會話文件 編輯事件”。查詢時先取當前文件目標行附近的一段內(nèi)容做同樣的哈希計算再去倒排索引里查。只要這段代碼沒有被大改就能命中原始會話。這種策略不依賴行號天然抗漂移?？梢越Y(jié)合兩種匹配方式匹配方式原理優(yōu)點局限適用場景行號范圍匹配用編輯前后內(nèi)容推算行號準確實時文件改動后容易失效短會話、小型項目old_string 當前文件搜索在項目里搜索替換前內(nèi)容實現(xiàn)簡單多處匹配時定位易錯演示和驗證編輯歷史回放按時間順序重放所有 Edit最準確依賴會話開始時的快照嚴肅生產(chǎn)場景內(nèi)容哈希倒排對代碼塊建哈希索引抗行號漂移同片段多處出現(xiàn)時需排序長期維護多個模塊5.3 索引增量更新與數(shù)據(jù)保留策略JSONL 是追加寫入的新的會話會持續(xù)產(chǎn)生新行。每次全量重建索引在日志量小時沒問題日志量大了以后耗時和 IO 都會成為負擔。增量更新思路是按文件記錄已解析的字節(jié)偏移量下次只從偏移量處往后讀。注意 JSONL 文件末尾可能寫入了一半讀取時遇到最后一行不完整 JSON 應當跳過等到下一次再解析。數(shù)據(jù)保留策略也要提前定。會話日志里包含原始用戶指令長期保留會增加泄露風險。常見做法是保留最近 30 到 90 天的會話記錄更早的自動清理。索引表只存必要字段不存完整日志內(nèi)容。查詢結(jié)果默認只顯示 snippet 和用戶指令摘要完整 session 文件需要二次確認才能打開。6. 常見問題排查清單6.1 查不到任何會話記錄現(xiàn)象是運行 query 后輸出“沒有找到對應的 Agent 會話記錄”。按以下順序排查檢查項操作可能結(jié)果transcript 目錄是否正確用 find 列出所有 jsonl目錄為空或路徑指向錯誤Agent 工具是否產(chǎn)出本地日志打開最新 jsonl 看內(nèi)容日志只有云端鏈接沒有落盤目標文件是否真的被 Agent 改過在日志里 grep 文件名該文件由人工編寫無對應記錄項目的相對路徑是否一致檢查 file_path 字段的實際值A(chǔ)gent 記錄的是絕對路徑需要做路徑歸一化最常見的原因是路徑不一致。Agent 工具記錄的 file_path 有些是相對路徑有些是絕對路徑還有些帶./前綴。建索引前先統(tǒng)計一下 file_path 字段的特征統(tǒng)一格式后再寫入數(shù)據(jù)庫。6.2 返回的 transcript 是過期上下文現(xiàn)象是查到了記錄但展示的代碼和當前文件里的代碼對不上。原因基本可以歸結(jié)為后續(xù)提交改動了這段代碼行號或內(nèi)容都發(fā)生了變化。兩個處理方向查詢時用內(nèi)容片段而不是行號。如果當前行附近的內(nèi)容能在索引 snippet 里匹配上說明這段代碼雖被移動但內(nèi)容保持一致可以繼續(xù)使用舊會話記錄。查詢時結(jié)合 git 歷史。先用 git log 定位這行代碼最近一次被修改的提交再在會話日志里找那次提交之前的 agent 活動縮小范圍。注意不要因為一次匹配失敗就立刻認定“Agent 沒寫過這段代碼”。先確認目標行是否是 Agent 生成內(nèi)容的后代版本比如被人類復制粘貼或重命名后留下的代碼。6.3 日志解析亂碼或缺少字段現(xiàn)象是索引過程大量輸出 skip或 JSON 解析報錯。可能是以下原因單個 JSONL 文件體積過大讀取時被程序中斷末尾行不完整。處理方式是跳過不完整行而不是終止整個索引。不同版本的 Agent 工具字段名不同比如file_path被寫成pathnew_string被寫成replacement。處理方式是在解析層做字段映射而不是修改所有歷史日志。文件編碼不是 UTF-8。代碼里已用errorsreplace兜底但最好在索引前先做一次文件編碼檢查。排查時可以先取單個文件用 jq 打印每層 JSON 的字段名確認字段映射關(guān)系。不要在不知道字段名的情況下盲目改正則或字符串截取那樣會把解析邏輯寫得很脆弱。6.4 安全與隱私邊界會話 transcript 的價值和風險都來自“完整”。它記錄了你的業(yè)務需求、代碼結(jié)構(gòu)、可能還有數(shù)據(jù)庫地址或第三方密鑰。這幾條邊界必須守住不要把 transcript 目錄加入 git 倉庫。必要時在.gitignore里顯式排除~/.claude這類目錄。不要直接把 transcript 發(fā)到聊天群或外部文檔。需要分享時先做脫敏把密鑰、地址、人員姓名替換掉。使用從網(wǎng)上下載的 Agent 工具或腳本前先讀一遍源碼和隱私說明。和“不要往控制臺粘貼看不懂的代碼”是同一個原則運行你自己理解的東西不理解就先別跑。7. 從個人腳本走向團隊實踐的落地建議7.1 學習環(huán)境快速驗證與生產(chǎn)環(huán)境要求對比本地驗證時臨時目錄、Python 腳本、SQLite 已經(jīng)足夠了。但如果這個工具要在團隊里長期使用要求會顯著提高維度本地驗證階段團隊生產(chǎn)階段數(shù)據(jù)存儲SQLite 單文件集中式日志存儲支持多項目隔離索引方式全量重建增量更新 定期全量校驗權(quán)限控制本機文件權(quán)限按項目、按角色控制查詢權(quán)限保密策略手動清理自動脫敏、過期刪除、訪問審計查詢?nèi)肟贑LICLI 編輯器插件 CI 集成故障恢復無要求索引表可重建日志源不丟如果團隊里多個成員使用不同 Agent 工具還需要在解析層做統(tǒng)一抽象。不同工具的 JSONL 字段不同但核心的“file_path old_string new_string timestamp”幾乎都會出現(xiàn)以這四個字段作為統(tǒng)一模型可以屏蔽大部分差異。7.2 把 transcript 關(guān)聯(lián)信息寫進提交和評審流程“代碼反查會話記錄”是被動查詢。更主動的做法是在 Agent 生成代碼時就把來源信息寫進提交。提交信息里增加一行agent-session: session-id評審系統(tǒng)里通過這個 ID 直接跳轉(zhuǎn)到對應會話。這樣評審人不需要先查工具直接在 PR 詳情里就能看到 Agent 的推理過程。另一種做法是 PR 模板里增加“Agent 參與說明”哪些文件由 Agent 生成、哪些由人工修改、生成過程中是否執(zhí)行過會影響代碼邏輯的命令。寫清楚這幾個問題比事后反查更省力。7.3 落地前檢查清單把一個“代碼行反查 transcript”工具從原型推進到可運維狀態(tài)建議對照檢查能自動、穩(wěn)定地拿到所有 Agent 會話日志不依賴人工導出。日志目錄有明確的保留期和清理任務。索引構(gòu)建支持增量更新部分日志損壞不影響整體索引。統(tǒng)一了不同 Agent 工具的 file_path 路徑格式。查詢結(jié)果能把文件路徑、行號、用戶指令、會話文件四類信息同時展示。不把 transcript 和索引文件提交到代碼倉庫。團隊成員清楚哪些文件可以查詢、哪些需要權(quán)限審批。有明確的回退方案索引丟失時能通過重新解析 JSONL 完全恢復。把這套鏈路搭建起來之后你會明顯感覺到 Agent 生成代碼不再是“黑盒”。評審時能追指令排查時能看上下文交接時能查設(shè)計意圖。下一步可以考慮把它做成 VS Code 擴展在鼠標懸停某一行代碼時直接彈出對應的 Agent 會話摘要。對想動手的讀者建議先把自己最近一周用 Agent 改過的代碼拿出來跑通上面的最小腳本再根據(jù)自己的項目結(jié)構(gòu)逐步補強匹配策略。