1. 從“treg”這個標(biāo)題說起一個被低估的CLI工具鏈入口第一次看到“treg”這個詞很多人會以為是某個拼寫錯誤或者某個小眾庫的縮寫。但如果你最近在折騰 AI Agent 開發(fā)、CLI 工具鏈、MCP 協(xié)議這些東西大概率已經(jīng)在某個 GitHub issue、Discord 頻道或者技術(shù)群里見過它。treg 本質(zhì)上是一個圍繞 Agent 執(zhí)行鏈路做“注冊、追蹤、回放”的輕量級 CLI 工具它的定位不是替代 Codex CLI、Claude CLI 這類交互式終端而是補(bǔ)上它們?nèi)笔У哪且画h(huán)——把一次 Agent 執(zhí)行過程變成可復(fù)現(xiàn)、可審計、可對比的結(jié)構(gòu)化記錄。我最初接觸 treg 是因?yàn)橐粋€很具體的痛點(diǎn)用 Codex CLI 跑一個多步驟任務(wù)中間某一步工具調(diào)用失敗了終端里刷過去幾百行日志想回頭定位到底是哪個 MCP Server 返回了異常、當(dāng)時傳給模型的上下文是什么、重試了幾次幾乎不可能。Agent 執(zhí)行不像傳統(tǒng)程序它有隨機(jī)性、有外部工具依賴、有上下文窗口的裁剪出了問題光靠翻 scrollback 根本不夠。treg 解決的正是這個問題它在 Agent 和底層 CLI 之間插一層薄薄的記錄層把每次執(zhí)行的輸入、工具調(diào)用、返回、耗時、token 消耗落成結(jié)構(gòu)化文件之后你可以用treg replay回放、用treg diff對比兩次執(zhí)行的差異。這篇文章適合三類人看一是正在用 Codex CLI、Claude CLI 或者自研 Agent 框架做開發(fā)被調(diào)試和復(fù)現(xiàn)問題折磨的工程師二是想理解 MCP 協(xié)議在實(shí)際工具鏈里怎么落地、Agent 執(zhí)行鏈路到底長什么樣的進(jìn)階學(xué)習(xí)者三是需要給團(tuán)隊(duì)搭建 Agent 可觀測性方案的技術(shù)負(fù)責(zé)人。我會從設(shè)計思路、核心機(jī)制、實(shí)操步驟、踩坑經(jīng)驗(yàn)四個層面把 treg 講透所有命令和配置都是我實(shí)際跑過的你可以直接抄。2. treg 的整體設(shè)計與思路拆解2.1 為什么要在 CLI 和 Agent 之間加一層記錄要理解 treg 的價值先得理解現(xiàn)在 Agent 執(zhí)行鏈路的典型結(jié)構(gòu)。以 Codex CLI 為例一次任務(wù)大致是這樣流轉(zhuǎn)的用戶在終端輸入自然語言指令CLI 把指令和當(dāng)前工作目錄的上下文打包成 prompt 發(fā)給模型模型返回一個或多個工具調(diào)用請求比如讀文件、執(zhí)行 shell、調(diào)用 MCP ServerCLI 執(zhí)行這些調(diào)用把結(jié)果再喂回模型循環(huán)直到模型認(rèn)為任務(wù)完成。這個循環(huán)里每一次模型往返都是一個潛在的故障點(diǎn)而終端默認(rèn)只展示最終結(jié)果和部分中間輸出。問題在于Agent 的失敗往往不是“崩了”而是“悄悄跑偏了”。比如模型第三次調(diào)用某個 MCP 工具時傳錯了參數(shù)工具返回了一個空結(jié)果模型沒意識到異常繼續(xù)往下走最后產(chǎn)出一個看起來合理但實(shí)際錯誤的結(jié)論。這種問題在終端里幾乎看不出來因?yàn)槊恳徊蕉肌俺晒Α绷?。treg 的思路很直接把每一次模型往返和工具調(diào)用都當(dāng)成一條事件記錄下來形成一條完整的時間線。這條時間線不是給人看的日志而是結(jié)構(gòu)化的 JSON Lines可以被程序讀取、過濾、對比。這個設(shè)計選擇背后有一個關(guān)鍵判斷Agent 調(diào)試的核心不是“看日志”而是“復(fù)現(xiàn)現(xiàn)場”。傳統(tǒng)日志是線性的、易失的而 treg 記錄的是可重放的事件流。你可以把一次失敗的執(zhí)行導(dǎo)出在另一臺機(jī)器上重放甚至把兩次執(zhí)行的同一階段拿出來做 diff看是哪一步的輸入變了導(dǎo)致結(jié)果不同。這是純終端 scrollback 做不到的。2.2 與 OpenRouter、MCP 的關(guān)系定位熱詞里出現(xiàn)了 OpenRouter、MCP、agent、CLI 這些詞說明 treg 的使用場景和它們高度重疊。我實(shí)際用下來的理解是treg 不綁定任何特定的模型提供商或 Agent 框架。你可以用它記錄通過 OpenRouter 調(diào)用的模型請求也可以記錄本地直連的模型可以記錄 Codex CLI 的執(zhí)行也可以記錄你自己寫的 Agent 循環(huán)。它的接入方式是在你的 Agent 執(zhí)行入口處調(diào)用 treg 的 SDK 或者用treg wrap包裹一個 CLI 命令。和 MCP 的關(guān)系更微妙一些。MCP 協(xié)議定義的是模型和工具之間的通信標(biāo)準(zhǔn)它管的是“怎么調(diào)用工具”但不管“調(diào)用過程怎么記錄”。treg 恰好補(bǔ)上這一塊當(dāng)你的 Agent 通過 MCP 調(diào)用一個 Server 時treg 可以記錄下請求的 method、params、返回的 content、以及這次調(diào)用的耗時。如果你在調(diào)試一個自定義的 MCP Server這些記錄能直接告訴你模型傳了什么參數(shù)進(jìn)來、你的 Server 返回了什么、模型拿到之后做了什么決策。這比在 Server 里打 print 要系統(tǒng)得多。提示treg 的記錄層是旁路式的它不改變 Agent 的執(zhí)行邏輯只是觀察和落盤。這意味著你可以在生產(chǎn)環(huán)境低風(fēng)險地開啟它出問題時再分析記錄而不是一開始就侵入式地改造代碼。2.3 方案選型為什么是 CLI 而不是 GUI 或 SaaS市面上做 Agent 可觀測性的方案不少有 SaaS 平臺也有 IDE 插件。treg 選擇 CLI 形態(tài)我認(rèn)為有幾個務(wù)實(shí)的原因。第一Agent 開發(fā)者的工作流本來就在終端里Codex CLI、Claude CLI、各種 shell 腳本CLI 工具能無縫嵌入現(xiàn)有流程不需要切換窗口。第二記錄文件落在本地數(shù)據(jù)不出機(jī)器對于處理敏感代碼庫的場景更可控。第三CLI 天然適合腳本化和 CI 集成你可以在自動化測試?yán)锱躷reg replay來驗(yàn)證 Agent 行為是否回歸。這個選型也有代價CLI 的可視化能力弱看復(fù)雜時間線不如 GUI 直觀。treg 的應(yīng)對方式是提供treg view命令在終端里用 TUI 展示事件流同時支持導(dǎo)出成 HTML 報告。我個人的習(xí)慣是日常調(diào)試用treg view快速掃深度分析時導(dǎo)出 JSON 用 jq 或者寫腳本處理。這種“CLI 為主、導(dǎo)出為輔”的組合在靈活性和效率之間取得了不錯的平衡。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 安裝與環(huán)境準(zhǔn)備treg 的安裝方式取決于你的運(yùn)行環(huán)境。目前主流的是通過包管理器安裝macOS 上可以用 HomebrewLinux 上可以用官方提供的安裝腳本W(wǎng)indows 建議在 WSL2 里跑因?yàn)椴糠?Agent CLI 本身對 Windows 原生支持就不完整。我實(shí)測下來最穩(wěn)的方式是用 Node.js 生態(tài)的包管理器全局安裝因?yàn)?treg 的很多集成點(diǎn)比如 MCP 記錄依賴 Node 運(yùn)行時。# 通過 npm 全局安裝推薦版本更新最快 npm install -g treg-cli # 驗(yàn)證安裝 treg --version # 初始化配置目錄 treg inittreg init會在你的用戶目錄下創(chuàng)建~/.treg/配置目錄里面包含默認(rèn)的配置文件config.toml和記錄存儲目錄records/。配置文件里最關(guān)鍵的幾個參數(shù)是記錄存儲路徑、單次記錄的最大事件數(shù)、以及是否默認(rèn)開啟脫敏。脫敏這個功能值得單獨(dú)說Agent 執(zhí)行過程中可能會把 API Key、數(shù)據(jù)庫連接串、用戶隱私數(shù)據(jù)帶進(jìn)上下文treg 默認(rèn)會對常見敏感模式做正則替換但你不能完全依賴它涉及真實(shí)敏感數(shù)據(jù)時建議在隔離環(huán)境里跑。注意如果你用的是公司內(nèi)網(wǎng)環(huán)境npm 安裝可能走私有 registry需要提前確認(rèn) treg-cli 這個包在你們的鏡像源里可用。我遇到過私有源同步延遲導(dǎo)致裝到舊版本的情況用npm view treg-cli versions確認(rèn)一下最新版本號再裝。3.2 記錄格式與事件模型treg 的記錄文件是 JSON Lines 格式每行一個事件。這個選擇很務(wù)實(shí)JSON Lines 既能流式追加寫入又能被 jq、Python、Go 等各種工具直接處理不需要額外的解析庫。一個典型的事件長這樣{ event_id: evt_01HX..., trace_id: trc_01HX..., timestamp: 2025-01-15T10:23:45.123Z, type: tool_call, source: mcp, payload: { server: filesystem, method: read_file, params: {path: /src/main.py}, result: {content: ..., truncated: false}, duration_ms: 45 }, parent_event_id: evt_01HX... }事件類型主要有幾種model_request發(fā)給模型的請求、model_response模型返回、tool_call工具調(diào)用、tool_result工具返回、error異常。每個事件都有trace_id和parent_event_id這樣就能還原出完整的調(diào)用樹。我特別喜歡parent_event_id這個設(shè)計它讓你能精確知道某個工具調(diào)用是被哪次模型響應(yīng)觸發(fā)的排查“模型為什么調(diào)這個工具”時特別有用。記錄文件按 trace 分目錄存儲路徑是~/.treg/records/date/trace_id.jsonl。這個按日期分目錄的設(shè)計方便清理舊記錄你可以寫個 cron 任務(wù)定期刪掉 N 天前的記錄。我一般保留最近 7 天因?yàn)?Agent 調(diào)試通常集中在開發(fā)階段太久遠(yuǎn)的記錄參考價值不大。3.3 與 Codex CLI 的集成方式把 treg 和 Codex CLI 結(jié)合使用有兩種方式。第一種是treg wrap直接包裹 Codex CLI 的啟動命令treg wrap -- codex-cli run 重構(gòu) src/utils.py 里的日期處理函數(shù)這種方式最省事treg 會攔截 Codex CLI 的標(biāo)準(zhǔn)輸入輸出和子進(jìn)程調(diào)用自動記錄模型往返和工具調(diào)用。但它的局限是只能記錄到 CLI 層面的交互如果 Codex CLI 內(nèi)部有更細(xì)粒度的 MCP 調(diào)用wrap 方式可能抓不全。第二種方式是在 Codex CLI 的配置里顯式指定 treg 作為記錄后端這需要 Codex CLI 支持自定義 hook 或者插件機(jī)制。我實(shí)測下來wrap 方式對大多數(shù)調(diào)試場景夠用只有在深度分析 MCP 交互時才需要第二種方式。# 查看某次執(zhí)行的記錄 treg list --since 1h # 回放指定 trace treg replay trc_01HX... # 對比兩次執(zhí)行 treg diff trc_01HX... trc_01HY...treg diff是我用得最多的命令。比如我改了一版 prompt想確認(rèn)改動是否影響了 Agent 的工具調(diào)用序列直接 diff 兩次執(zhí)行的 trace就能看到哪些工具調(diào)用多了、哪些少了、參數(shù)有什么變化。這比人肉對比終端輸出高效太多。3.4 MCP Server 調(diào)用的記錄要點(diǎn)MCP 是當(dāng)前 Agent 工具調(diào)用的主流協(xié)議treg 對 MCP 的支持是它區(qū)別于普通日志工具的關(guān)鍵。當(dāng)你的 Agent 通過 MCP 調(diào)用一個 Server 時treg 記錄的不只是“調(diào)用了什么”還包括完整的請求和響應(yīng) payload。這對調(diào)試自定義 MCP Server 特別有價值你可以看到模型實(shí)際傳進(jìn)來的參數(shù)結(jié)構(gòu)而不是靠猜。配置 MCP 記錄需要在 treg 的 config.toml 里指定 MCP Server 的啟動命令[[mcp_servers]] name filesystem command npx args [-y, modelcontextprotocol/server-filesystem, /workspace] record_payload true max_payload_size 1048576record_payload true會記錄完整的請求和響應(yīng)內(nèi)容max_payload_size限制單條 payload 的最大字節(jié)數(shù)防止大文件讀取把記錄撐爆。我建議把這個值設(shè)在 1MB 左右超過的部分會被截斷并標(biāo)記truncated: true。如果你在調(diào)試一個返回大 JSON 的 MCP Server可以臨時調(diào)大這個值但記得調(diào)試完改回去否則記錄文件會膨脹得很快。提示MCP Server 的啟動命令如果依賴環(huán)境變量比如 API Keytreg 默認(rèn)會繼承當(dāng)前 shell 的環(huán)境變量。但如果你在 CI 里跑需要顯式在配置里聲明 env 字段否則 Server 可能啟動失敗而 treg 只會記錄一個啟動錯誤事件不會告訴你具體缺了哪個變量。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 從零搭建一個可記錄的 Agent 執(zhí)行環(huán)境我拿一個真實(shí)場景來演示用 Codex CLI 加一個自定義 MCP Server完成“讀取項(xiàng)目里的配置文件根據(jù)配置生成一份報告”的任務(wù)全程用 treg 記錄。這個場景覆蓋了模型調(diào)用、MCP 工具調(diào)用、文件讀寫三類事件比較有代表性。第一步準(zhǔn)備 MCP Server。我用一個簡單的 Python 腳本模擬它提供一個read_config工具讀取指定路徑的 YAML 文件并返回解析后的內(nèi)容。實(shí)際項(xiàng)目中你可能是連接數(shù)據(jù)庫、調(diào)用內(nèi)部 API 的 Server但記錄原理是一樣的。# mcp_server.py import yaml from mcp.server import Server from mcp.types import Tool, TextContent app Server(config-reader) app.list_tools() async def list_tools(): return [Tool( nameread_config, description讀取 YAML 配置文件, inputSchema{ type: object, properties: {path: {type: string}}, required: [path] } )] app.call_tool() async def call_tool(name, arguments): if name read_config: with open(arguments[path]) as f: data yaml.safe_load(f) return [TextContent(typetext, textstr(data))]第二步在 treg 配置里注冊這個 Server然后啟動 Codex CLI 并讓它使用這個 MCP Server。Codex CLI 的 MCP 配置通常在它的配置文件里你需要把 Server 的啟動命令加進(jìn)去。treg 這邊只需要在 config.toml 里聲明同一個 Server它就能在記錄時關(guān)聯(lián)上。第三步執(zhí)行任務(wù)并觀察記錄。跑完之后用treg list找到這次 trace再用treg view看事件流。你會看到類似這樣的序列model_request用戶指令→model_response模型決定調(diào)用 read_config→tool_callread_configpathconfig.yaml→tool_result返回配置內(nèi)容→model_response模型生成報告→ 結(jié)束。每一步的耗時、payload 大小都記錄在案。4.2 參數(shù)計算與記錄體積控制記錄體積是個容易被忽視的問題。一次復(fù)雜的 Agent 執(zhí)行可能產(chǎn)生幾百個事件如果每個事件的 payload 都完整記錄單個 trace 文件可能達(dá)到幾十 MB。我做過一個粗略的估算一次包含 50 次模型往返、每次往返上下文 8K token 的執(zhí)行如果完整記錄請求和響應(yīng)文本量大約是 50 × 8K × 2 800K token按每 token 約 4 字節(jié)算就是 3.2MB 左右。加上工具調(diào)用的 payload輕松超過 5MB。treg 提供了幾個控制手段。max_payload_size限制單條 payloadmax_events_per_trace限制單次 trace 的事件總數(shù)超過后新事件會被丟棄并記錄一個truncated標(biāo)記。我的經(jīng)驗(yàn)值是日常調(diào)試設(shè)max_payload_size 262144256KB、max_events_per_trace 500足夠覆蓋絕大多數(shù)場景深度調(diào)試時臨時調(diào)大但記得手動清理記錄目錄。[recording] max_payload_size 262144 max_events_per_trace 500 retention_days 7 compress_after_days 1compress_after_days 1會讓 treg 在記錄生成一天后自動 gzip 壓縮能省不少磁盤空間。我實(shí)測下來JSON Lines 的壓縮比通常在 8:1 到 12:1 之間5MB 的記錄壓完不到 500KB。4.3 用 replay 復(fù)現(xiàn)問題現(xiàn)場replay 是 treg 最有價值的功能之一但它的實(shí)現(xiàn)方式需要理解清楚。treg 的 replay 不是“重新執(zhí)行一遍 Agent”而是按記錄的事件流重新播放把當(dāng)時模型返回的內(nèi)容、工具返回的結(jié)果原樣重放出來。這意味著 replay 是確定性的不會因?yàn)槟Ｐ碗S機(jī)性產(chǎn)生不同結(jié)果。這對于復(fù)現(xiàn)“當(dāng)時到底發(fā)生了什么”非常關(guān)鍵。# 基礎(chǔ)回放按時間順序輸出事件 treg replay trc_01HX... # 只回放工具調(diào)用事件 treg replay trc_01HX... --filter typetool_call # 回放到指定事件為止 treg replay trc_01HX... --until evt_01HX...我常用的一個技巧是--until配合--filter當(dāng)我知道問題出在第 N 次工具調(diào)用時先 replay 到那一步仔細(xì)看當(dāng)時的輸入輸出再決定是改 prompt、改工具實(shí)現(xiàn)還是改 Agent 邏輯。這比從頭跑一遍快得多也不消耗模型 token。注意replay 依賴記錄文件的完整性。如果某次執(zhí)行因?yàn)檫M(jìn)程被 kill 導(dǎo)致記錄文件不完整最后一行 JSON 可能被截斷replay 會在截斷處報錯。treg 對這種情況的處理是跳過最后一行不完整的記錄并在輸出里警告。如果你發(fā)現(xiàn) replay 結(jié)果和記憶中的執(zhí)行不一致先檢查記錄文件最后幾行是否完整。4.4 在 CI 里做 Agent 行為回歸測試把 treg 集成到 CI 里可以做一件很有價值的事Agent 行為回歸測試。傳統(tǒng)單元測試驗(yàn)證的是確定性代碼而 Agent 的輸出有隨機(jī)性很難用斷言直接判斷對錯。但 Agent 的工具調(diào)用序列相對穩(wěn)定可以作為回歸的錨點(diǎn)。我的做法是在 CI 里跑一個固定的 Agent 任務(wù)用 treg 記錄然后把這次 trace 的工具調(diào)用序列和基線序列做 diff。如果序列發(fā)生了非預(yù)期的變化比如多了一次不該有的文件刪除調(diào)用就判定回歸失敗。這個方案不能覆蓋所有問題但能抓住“Agent 行為漂移”這類最危險的回歸。# 在 CI 腳本里 treg wrap --output /tmp/ci-trace.jsonl -- codex-cli run $TASK treg diff --baseline ./baselines/expected.jsonl /tmp/ci-trace.jsonl --fail-on-diff--fail-on-diff會讓 diff 發(fā)現(xiàn)差異時返回非零退出碼CI 就能據(jù)此判定失敗?；€文件需要人工審核后提交到倉庫每次 Agent 邏輯有意變更時更新基線。這個流程跑順之后我對 Agent 改動的信心提升了很多至少不會出現(xiàn)“改了一個 prompt結(jié)果 Agent 開始亂刪文件”這種事故。5. 常見問題與排查技巧實(shí)錄5.1 記錄為空或只有部分事件這是最常見的入門問題。原因通常有三類一是 treg 沒有正確攔截到 Agent 的執(zhí)行入口比如你用treg wrap包裹的命令本身是個 shell 腳本腳本里又 fork 了子進(jìn)程treg 可能只記錄到腳本層面二是 Agent 使用了獨(dú)立的網(wǎng)絡(luò)請求庫繞過了 treg 的攔截點(diǎn)三是記錄目錄權(quán)限問題treg 寫不進(jìn)去但沒報錯。排查順序建議這樣先treg doctor檢查環(huán)境它會驗(yàn)證記錄目錄可寫、依賴版本匹配、攔截點(diǎn)是否生效。然后手動跑一個最小任務(wù)用treg list --since 5m確認(rèn)有沒有生成 trace。如果 trace 存在但事件很少檢查 Agent 是否用了 treg 不認(rèn)識的 HTTP 客戶端。我遇到過用 Go 寫的 Agent 直接用net/http發(fā)請求treg 的 Node 層攔截不到這種情況需要在 Agent 代碼里顯式調(diào)用 treg 的 SDK?，F(xiàn)象可能原因排查方法完全沒有 trace攔截未生效treg doctor檢查trace 存在但事件少部分請求繞過攔截檢查 Agent 網(wǎng)絡(luò)庫記錄文件為空權(quán)限或磁盤滿檢查目錄權(quán)限和磁盤空間事件時間戳亂序多進(jìn)程并發(fā)寫入確認(rèn) trace_id 是否混用5.2 MCP Server 啟動失敗導(dǎo)致記錄中斷MCP Server 啟動失敗是另一個高頻問題。treg 記錄到的是一個error事件但錯誤信息往往只有“Server exited with code 1”具體原因需要看 Server 自己的 stderr。treg 會把 Server 的 stderr 也記錄到事件里但默認(rèn)只在record_payload true時記錄。如果你在調(diào)試 MCP Server建議臨時開啟這個選項(xiàng)。我踩過的一個坑是MCP Server 依賴的環(huán)境變量在 treg 啟動的子進(jìn)程里沒有繼承。比如 Server 需要DATABASE_URL我在 shell 里 export 了但 treg 的配置里沒聲明 env子進(jìn)程就啟動失敗。解決辦法是在 config.toml 的[[mcp_servers]]里顯式加env [DATABASE_URL]treg 會從當(dāng)前環(huán)境讀取并傳給子進(jìn)程。提示MCP Server 的啟動超時默認(rèn)是 10 秒如果你的 Server 啟動時需要加載大模型或者連接慢速數(shù)據(jù)庫可能超時?？梢栽谂渲美镎{(diào)大startup_timeout_ms但別設(shè)太大否則 Agent 會卡住等 Server。5.3 replay 結(jié)果與預(yù)期不符replay 是確定性的所以如果結(jié)果和預(yù)期不符通常是記錄本身有問題而不是 replay 邏輯有問題。常見情況有兩種一是記錄文件被手動修改過JSON 格式損壞二是記錄時 payload 被截斷超過max_payload_sizereplay 時只能看到截斷后的內(nèi)容。排查方法是用treg validate trace_file檢查記錄文件的完整性它會逐行解析 JSON 并報告格式錯誤。如果是截斷問題檢查事件里的truncated字段如果為 true說明當(dāng)時記錄就不完整需要調(diào)大max_payload_size重新跑一次。我建議在調(diào)試關(guān)鍵問題時臨時把max_payload_size設(shè)成 10MB確保記錄完整問題定位后再改回默認(rèn)值。5.4 記錄文件膨脹過快如果你頻繁跑 Agent 任務(wù)記錄目錄可能幾天就漲到幾個 GB。除了前面說的retention_days和compress_after_days還有一個技巧是按 trace 類型選擇性記錄。treg 支持在配置里定義過濾規(guī)則比如只記錄包含工具調(diào)用錯誤的 trace或者只記錄特定 MCP Server 的調(diào)用。[[filters]] name errors-only condition has_error true action keep [[filters]] name drop-healthcheck condition tool_name health_check action drop這個過濾機(jī)制在配置里是聲明式的treg 在寫入記錄前會先過一遍過濾器。我一般會加一條規(guī)則把心跳類、健康檢查類的工具調(diào)用直接丟掉這些調(diào)用量大但調(diào)試價值低。實(shí)測下來這條規(guī)則能減少 30% 到 40% 的記錄量。5.5 與 OpenRouter 等模型網(wǎng)關(guān)配合時的注意事項(xiàng)如果你的 Agent 通過 OpenRouter 這類模型網(wǎng)關(guān)調(diào)用模型treg 記錄的是網(wǎng)關(guān)層面的請求和響應(yīng)。這里有個細(xì)節(jié)網(wǎng)關(guān)可能會對請求做改寫比如注入系統(tǒng)提示、調(diào)整參數(shù)treg 記錄的是改寫后的版本還是改寫前的取決于你在哪一層接入。我建議在網(wǎng)關(guān)的客戶端側(cè)接入 treg這樣記錄的是你實(shí)際發(fā)出的請求便于對比網(wǎng)關(guān)行為。另外通過網(wǎng)關(guān)調(diào)用時響應(yīng)里通常包含網(wǎng)關(guān)自己的元數(shù)據(jù)如實(shí)際路由到的模型、計費(fèi)信息treg 會把這些一并記錄。這些信息在排查“為什么同一個請求兩次結(jié)果差異很大”時很有用因?yàn)榭赡苁蔷W(wǎng)關(guān)路由到了不同的后端模型。我遇到過這種情況同一個 prompt一次路由到 A 模型一次路由到 B 模型輸出風(fēng)格完全不同看 treg 記錄里的網(wǎng)關(guān)元數(shù)據(jù)才定位到原因。6. 我在實(shí)際使用中積累的幾個經(jīng)驗(yàn)treg 這類工具的價值很大程度上取決于你怎么用它。我用了幾個月有幾個體會比較深。第一記錄要趁早開。很多人是出了問題才想起來加記錄但 Agent 的問題往往需要對比“正常時”和“異常時”的記錄才能定位如果正常時沒記錄排查效率會大打折扣。我現(xiàn)在是默認(rèn)開著 treg只在確認(rèn)不影響性能的場景下才關(guān)。第二trace_id 要透傳到業(yè)務(wù)日志里。treg 的 trace_id 是它自己生成的但如果你能在 Agent 的業(yè)務(wù)日志里也打上這個 id兩邊就能關(guān)聯(lián)起來。比如 Agent 在處理某個用戶請求時打了一條業(yè)務(wù)日志你可以用 trace_id 找到對應(yīng)的 treg 記錄看到當(dāng)時模型和工具的完整交互。這個關(guān)聯(lián)在排查線上問題時特別有用。第三不要過度依賴自動記錄關(guān)鍵節(jié)點(diǎn)手動打點(diǎn)。treg 的自動攔截能覆蓋大部分場景但有些關(guān)鍵決策點(diǎn)比如 Agent 在多個方案里選了哪個、為什么選是模型內(nèi)部的自動記錄抓不到。我習(xí)慣在 Agent 代碼的關(guān)鍵分支里手動調(diào)用 treg 的annotate接口打一個自定義事件把決策依據(jù)記下來。這些手動打點(diǎn)的事件在 replay 時會和自動事件混在一起形成更完整的敘事。第四定期清理和歸檔。記錄文件是調(diào)試資產(chǎn)但不是永久資產(chǎn)。我現(xiàn)在的策略是最近 3 天的記錄保留完整3 到 7 天的壓縮保留7 天以上的只保留包含錯誤的 trace其余刪除。這個策略在磁盤占用和可追溯性之間取得了平衡。如果你在團(tuán)隊(duì)里用建議把歸檔策略寫進(jìn)文檔避免每個人都按自己的習(xí)慣清理導(dǎo)致需要時找不到記錄。最后分享一個我最近才用上的技巧treg 的記錄文件可以直接喂給一些分析工具做可視化。比如把 JSON Lines 轉(zhuǎn)成 CSV用 pandas 做耗時分布分析找出哪些工具調(diào)用是性能瓶頸。我用這個方法發(fā)現(xiàn)某個 MCP Server 的search工具平均耗時 2.3 秒占了整個任務(wù)耗時的 60%后來優(yōu)化了它的索引策略整體任務(wù)時間降了一半。這種基于記錄的量化分析是純靠感覺調(diào)試做不到的。