AI编码助手实战：融合代码问答与任务执行的Agent设计

做 AI 編碼助手，最常見的誤區是把它做成一個「會說話的搜索引擎」。用戶問「這個報錯什麼意思」，它答得頭頭是道；用戶問「那你幫我改一下、跑一下、把任務排上」，它就啞火了。羲和（XiheAgent）這個項目的出發點很樸素：既然大模型已經能理解代碼、能操作工具，為什麼不把代碼問答和任務執行放進同一個助手裡，讓它既能當顧問，又能當幹活的工程師。這篇文章記錄我從零到一設計與實現 XiheAgent 的全過程，包括架構思路、核心代碼和真實踩坑記錄，適合正在做 AI 編碼助手、內部效能工具或 Agent 應用的同學參考。如果你是第一次接觸這個方向，文中會用大白話解釋必要概念，可以放心往下讀。

1. 設計起點：為什麼把問答和執行放進同一個助手

1.1 代碼問答的價值，不在「回答」本身

如果只是把大模型接到代碼庫上做問答，那它本質上還是個百科全書，只是換了檢索方式。真正讓問答產生價值的，是它能快速定位到用戶問題在倉庫裡的具體位置。舉個例子，新同事問「訂單超時之後狀態是怎麼流轉的」，人肉翻代碼可能要摸半天，而 XiheAgent 能把涉及的文件路徑、函數鏈路、狀態枚舉一次性列出來，讓人直接跳到需要看的地方。

所以在設計初期，我就把代碼問答定位成「入口」而不是「終點」。它能幫助用戶知道問題出在哪，但知道之後的修改、編譯、驗證、上線，仍然是一連串繁重的手工活。如果助手只停留在這一步，那它帶來的效率提升是有限的，頂多是把搜索的時間從半小時壓縮到三分鐘。真正要突破的，是讓它從「指路的人」變成「開車的人」，也就是任務執行能力。

1.2 任務執行，才是生產力真正爆發的地方

從「知道」到「做到」，中間隔著好幾個環節：修改代碼、運行測試、執行構建、觸發定時任務、收集結果。這些自動化工作傳統上由 CI 腳本和運維平臺完成，但它們的共同問題是：用戶需要知道具體的操作入口、參數格式、執行順序。DolphinScheduler 執行調度任務就是一個典型場景——以前我要在瀏覽器裡登錄控制檯，找到對應工作流，手動點啟動，再填一堆參數。現在 XiheAgent 可以直接把用戶一句「把訂單同步任務補跑一次」翻譯成 API 調用，並持續跟蹤執行狀態。

這就是 AI 編碼助手和傳統自動化工具的本質區別：傳統工具是人去適配系統，AI 助手是讓系統去理解人。用戶不需要記住任務代碼、不需要翻操作手冊，只需要把目標說清楚。當然，這件事的技術挑戰比單純問答高一個量級，因為它涉及意圖識別、參數抽取、權限控制、失敗處理，任何一個環節出問題，輕則任務沒跑起來，重則影響生產數據。我在動手之前反覆權衡過，最終還是決定做，因為這條路雖然難，但走通之後的門檻也高。

1.3 分層設計：兩層協作而不是一層混雜

XiheAgent 的整體結構是三明治式：上層是用戶交互，負責接收自然語言、返回最終結論；中層是 LLM 引擎，負責理解上下文、決策下一步動作；下層是工具層，把代碼檢索、命令執行、任務調度、告警推送這些能力封裝成可調用的函數。工具層又分成讀工具和寫工具：讀工具包括代碼檢索、文件讀取、狀態查詢；寫工具包括執行命令、觸發工作流、發送告警。

為什麼要嚴格分層？因為如果讓模型直接面對底層命令，很容易出現危險操作，比如把刪除命令的參數拼錯，或者帶著試探性的指令去動生產環境。工具層的作用是給所有動作加上「閘門」：統一鑑權、白名單校驗、審計日誌，模型只能看到工具的名字和描述，看不到也不允許直接執行任何裸命令。後續所有核心模塊都圍繞這個分層展開，先講代碼問答層怎麼把知識庫做紮實，再講任務執行層怎麼把動作做安全，最後講失敗告警怎麼閉環。

2. 代碼問答層：讓 AI 真正「讀懂」你的代碼庫

2.1 索引構建：從倉庫到檢索單元

代碼問答層的第一個核心步驟是離線構建索引。我沒有選擇把整個文件原樣塞進向量庫，因為文件粒度太大，檢索出來往往夾帶大量無關代碼。我的做法是先對每個文件做結構化解析，拆出函數、類、方法這些代碼單元，同時保留文件頭部註釋、函數簽名、關鍵變量名和調用關係，再對每個單元做向量化，存入向量數據庫。

單純向量檢索有個弱點：對專有名詞的命中率不高。比如用戶搜索「OrderStateMachine」，向量可能把它映射到語義相近但完全不同的概念去，而關鍵詞檢索能精確命中類名。反過來，用戶用自然語言描述「訂單超時怎麼處理」時，關鍵詞檢索就抓瞎了，向量檢索卻能找到語義相近的代碼。所以最終我采用混合檢索策略：向量召回 Top 50，BM25 關鍵詞召回 Top 50，再併集送入重排序模型，融合得分取 Top 10。實測下來，這個組合比單一方式準確率高不少，代價只是多一次重排計算，延遲增加幾十毫秒，完全可接受。

索引構建還有一個容易被忽略的問題：增量更新。代碼庫是持續變化的，如果每次全量重建，幾十萬文件的倉庫會耗時很久。我接了 Git 的合併請求回調，代碼合入後只對變更文件涉及的代碼單元做增量向量化和刪除，保證檢索結果不會停留在幾個月前的舊代碼上。沒有這個機制，用戶明明看到代碼已經重構了，問答助手還在引用舊接口，那信任感瞬間就沒了。

2.2 上下文注入：給模型看什麼，比模型本身更關鍵

檢索結果拿到之後，接下來最大的問題是：模型輸入窗口是有限的，不可能把整個代碼庫都塞進去。我的原則是「少而準」：只挑選與問題最相關的 3 到 5 個代碼單元，拼接成精簡上下文。拼接時必須保留關鍵信息，包括文件路徑、類名和函數名、註釋、就近的調用關係。文件路徑尤其重要，它讓模型知道自己看的是哪個文件，回答時才給得出真實出處。

這部分踩過兩個坑。第一個是「上下文過長導致注意力分散」：之前我把 Top 10 代碼單元全塞進去，結果模型容易被無關代碼干擾，生搬硬套不相關的實現邏輯。收斂到 Top 5 之後回答準確率反而提升了。第二個是「缺少文件路徑導致模型編造答案」：它看了一段代碼，不知道文件叫什麼，問到接口名時就開始「合理猜測」，看上去很專業，實際上是錯的。後來我在每個代碼塊前強制加上## File: 路徑/文件名的標記，並在 system prompt 裡明確要求「引用代碼時必須附帶真實文件路徑，不允許無來源推斷」，問題就解決了。

多輪對話的上下文管理也要單獨設計。用戶經常會說「這個函數剛才你提到的那個」，此時單純把歷史消息拼進 prompt 是不夠的，因為代碼檢索結果可能已經從上下文窗口裡滑出去了。我的做法是把每一輪檢索到的代碼單元緩存在 session 中以備追問時重用，同時只保留最近兩輪的完整檢索結果，更早的只保留對話摘要，這樣既控制了 token 消耗，又不丟失關鍵語境。

2.3 確保回答靠譜的幾個硬性規則

代碼問答裡最不能容忍的是模型一本正經地編造接口名。普通聊天裡偶爾胡說還有人能察覺，代碼場景裡用戶很可能直接複製去用，編譯報錯浪費半小時。所以我在代碼問答層設了三個硬性規則：

• 第一，凡涉及具體代碼的回答必須附帶來源文件路徑和函數名，查不到就只能說「倉庫中沒有找到相關實現」；
• 第二，不確定必須明確說「不確定」，不允許用含糊措辭掩蓋；
• 第三，對於「怎麼實現某功能」這類問題，只能基於倉庫現有代碼給出建議，不允許憑空推薦不存在的模塊或依賴。

規則通過 system prompt 和輸出校驗腳本雙重實現。校驗腳本會掃描回答中出現的所有代碼路徑，檢查是否真實存在，如果路徑不存在，直接把回答打回並附上錯誤信息，讓模型重新生成。這個機制會增加一些端到端延遲，但換來的是可信度。我個人認為，代碼問答階段寧願慢一點，也要把準確性做紮實，因為如果用戶在這裡發現幾次錯誤，後面你再告訴他「我能幫你執行任務」，他是不敢把控制權交給你的。

3. 任務執行層：從自然語言到可落地的動作

3.1 工具註冊：讓模型知道「你可以做什麼」

進入任務執行層之後，核心模塊變成工具註冊表。每個工具包含四個字段：名稱、描述、參數 JSON Schema、執行的 Python 函數。模型在對話過程中看到工具描述，如果判斷當前需要執行某個動作，就輸出結構化的工具調用指令，框架再根據指令路由到對應函數。這套機制本質上就是大模型的 function calling，但工程上最關鍵的不是調用本身，而是工具描述怎麼寫。

我把工具描述當作「給新同事的交接文檔」來寫，要包含使用場景、參數單位、邊界條件。舉個實際例子，trigger_dolphinscheduler這個工具的描述裡明確寫了：「用於觸發 DolphinScheduler 工作流執行調度任務。參數 task_name 是工作流名稱，必須存在於已註冊任務清單中；參數 run_date 是補跑日期，格式 YYYY-MM-DD；執行前會校驗任務權限，無權限時返回錯誤。」模型理解工具的能力比想象中強，但只要描述裡有模糊地帶，它就一定會踩。我見過模型把時間格式傳成MM-DD-YYYY，也見過它把task_name傳成用戶隨口說的簡稱。後來所有工具都補上了示例參數，模型照著示例做，出錯率大幅下降。

首批工具按照業務場景來定，不追求多，只追求閉環：get_code_context（查代碼）、search_code（搜符號）、run_shell_command（受限執行命令）、trigger_dolphinscheduler（觸發調度任務）、query_ds_task_status（查任務狀態）、send_wecom_alert（發送企微告警）。這些工具串起來，就覆蓋了「用戶提問 → 定位代碼 → 執行動作 → 跟蹤結果 → 異常通知」的完整鏈路。

3.2 安全執行：白名單、沙箱和審計，缺一不可

讓 AI 執行命令，相當於把終端交給一個「信心滿滿但有時候犯迷糊」的同事，安全機制必須前置到架構裡，不能事後補。我做了三層防護。

第一層是命令白名單。工具層只允許執行預先聲明的命令集合，比如python -m pytest、docker build、kubectl rollout status、bash scripts/xxx.sh，命令之外的參數要嚴格校驗，一切未在白名單裡的命令直接拒絕。起初有同事嫌麻煩，要求放開成「允許所有命令」，我堅決沒同意。後來有一次模型把git reset --hard的參數拼錯，白名單機制讓它直接失敗，沒有釀成事故，大家才認可這層防護的必要性。

第二層是容器沙箱。所有帶寫操作或可能影響宿主機的命令，都在臨時容器裡執行，容器一結束即銷毀，訪問不到宿主機文件系統。這樣即使模型產生意外行為，影響面也被限制在沙箱內部。第三層是審計日誌。每次工具調用都記錄用戶身份、原始意圖、模型生成的參數、執行結果、耗時，形成可以回溯的鏈路。後續排查任何「AI 為何這麼做」的問題，全靠這份日誌。

此外還有權限分層，容易被忽略但必須提前考慮。普通開發者通過 XiheAgent 只能操作測試環境的任務，申請生產環境調度權限需要負責人二次審批，實際執行前還會讓用戶再次確認命令參數。這不是技術難題，而是產品邊界的問題——如果 AI 助手的權限和用戶在後臺的權限完全一致，那它是殺器也是兇器。

3.3 對接 DolphinScheduler：執行調度任務的具體路徑

DolphinScheduler 是大數據場景裡很常見的分佈式工作流調度系統，用於編排定時任務、數據同步、ETL 等。XiheAgent 對接它時，我刻意避開了直連數據庫的方式，因為直接操作數據庫風險太高，而且繞過了 DS 自己的權限體制。最終方案是走官方 REST API，流程如下：

1. 登錄接口獲取 session token；
2. 用projects/process-instances接口創建流程實例，提交工作流定義碼、補跑時間、啟動參數；
3. 獲得實例 ID 後，用projects/process-instances/query接口輪詢狀態；
4. 狀態為失敗時，調用告警模塊發送企微通知。

這裡最關鍵的參數是工作流定義碼（processDefinitionCode），它是 DS 內部識別工作流主鍵。用戶口中的「訂單同步任務」不可能天然等於這個定義碼，所以我維護了一張任務名映射表，定期從 DS 後臺拉取工作流清單並同步名稱與定義碼的對應關係。映射表過期是常見問題，有了自動同步之後，新增工作流不需要人工維護，也就不會出現「任務明明建好了，AI 卻說找不到」的窘境。

同樣走 API 的還有狀態查詢與失敗判斷。我不會只查一次狀態就下結論，而是以固定間隔輪詢，直到工作流進入終態。需要注意的是「失敗」不一定反映在流程實例上——DolphinScheduler 有節點級失敗重試機制，如果某個節點在重試後最終成功，流程實例狀態仍然是成功。因此要判斷的是最終實例狀態，而非中間節點狀態，否則會產生大量誤報。

4. 失敗告警：任務執行失敗，第一時間用企微觸達負責人

4.1 告警規則不能一刀切

任務執行失敗企微進行告警，是整個閉環裡最容易被低估的一環。項目剛上線時，我只實現了「失敗就告警」，結果高峯期每天幾百條，值班群直接被刷屏，真正重要的告警反而被淹沒。後來我徹底重做了告警分級。

現在的分級方案是這樣的：P0 級別對應核心生產任務失敗，立即推送並且在企微消息裡 @ 值班負責人，要求馬上介入；P1 級別對應測試環境任務失敗，正常推送不 @；P2 級別對應自動重試最終仍失敗的任務，做聚合推送，把多次失敗合併成一條消息。任務屬於哪個級別，在創建工作流時由負責人指定，存到任務擴展屬性裡，XiheAgent 讀取後決定告警策略。

另外一定要區分失敗原因。用戶主動取消的任務、父流程被上層停止導致的失敗、系統停機維護期間的任務失敗，這些都不該觸發常規告警，否則值班的人會以為是在大規模故障，緊張半天才發現是維護窗口。我的做法是把取消、停止、維護中這幾類狀態單獨標記，只記錄到審計日誌，不進告警通道。

4.2 企業微信機器人的工程細節

企業微信告警最簡單的落地方案是群機器人。在目標企微群裡添加一個機器人，拿到 Webhook 地址，然後向這個地址 POST 一段 JSON。可用消息類型裡，我推薦用 markdown 類型而不是 text 類型，因為它支持標題、加粗、引用和換行，可讀性比純文本高很多。標準告警消息體我會寫清這幾項：

• 任務名稱和工作流定義碼；
• 執行實例 ID 和失敗節點；
• 錯誤摘要信息；
• 日誌鏈接（跳轉到 DolphinScheduler 或日誌平臺）；
• 任務開始時間、結束時間、總耗時。

構造消息時有個隱藏很深、很容易踩的坑：企業微信的 markdown 協議對特殊字符的處理和標準 Markdown 不一致。日誌原文裡經常有【、】、<、>、&這類字符，直接塞進消息會導致顯示錯亂甚至整個消息發送失敗。我的做法是先把正文做一次 HTML 轉義，再把長度截斷到 2048 字節以內，超過部分只保留日誌最後 500 字，因為報錯根因通常出現在尾部而不是開頭。

4.3 避免告警風暴和重複通知

任務失敗伴有重試是常態。假如一個任務失敗後自動重試三次，每次失敗都推一條，那就是三條重複告警；再疊加到底層數據源故障導致十幾個任務同時失敗，瞬間就是幾十條消息湧進來，值班的人直接崩潰。所以必須做告警收斂。

我的方案是「實例級去重 + 時間窗口聚合」。同一個工作流實例的多個失敗節點，只合併發一條告警，因為它們大概率是同一根因；同一錯誤信息在 10 分鐘內重複出現，不再單獨推送，而是等窗口結束後追加到下一條聚合消息裡；任務重試期間產生的中間失敗不推送，只推送最終狀態的失敗。這樣一來，一次底層故障最終表現為一到兩條告警，既保留了線索，又不至於轟炸羣組。

還有一個容易被忽略的問題：告警通道本身也會出故障。Webhook 可能被企微風控、可能因為頻繁調用被限流、也有可能因為配置錯誤一直調不對。所以我把告警發送也封裝成一個工具函數，在審計日誌裡記錄每次推送的 HTTP 狀態碼和響應體，並設置一個「告警末班車」：如果告警推送接口連續失敗三次，就轉為通過備用郵件通道通知管理員。這樣才能保證「任務失敗的告警」這件事本身不會悄悄失敗。

5. 核心代碼實現：可以直接抄作業的幾個模塊

5.1 統一工具封裝與模型調用骨架

工具調用的核心代碼並不複雜，關鍵是把工具 schema 和執行函數綁定在一起。下面是一個簡化的骨架，重點看註釋部分：

import json import requests from typing import Callable, Any # 全局工具註冊表，所有工具都掛在這裡 TOOL_REGISTRY = {} def register_tool(name: str, description: str, parameters_schema: dict): """裝飾器：把普通函數註冊成 Agent 可調用的工具""" def decorator(func: Callable): TOOL_REGISTRY[name] = { "name": name, "description": description, "parameters_schema": parameters_schema, "func": func, } return func return decorator @register_tool( "query_ds_task_status", "查詢 DolphinScheduler 工作流實例的狀態。參數 instance_id 是創建流程實例後返回的整型 ID。", { "type": "object", "properties": { "instance_id": {"type": "integer", "description": "流程實例 ID"} }, "required": ["instance_id"] } ) def query_ds_task_status(instance_id: int) -> str: # 實際調用 DS Open API，這裡省略真實請求 return json.dumps({"instance_id": instance_id, "state": "SUCCESS"})

模型端的使用邏輯是：把系統提示詞、對話歷史、以及所有工具的 name/description/parameters_schema 一起發給大模型。模型如果不是直接回答用戶，而是想調用工具，就會返回類似{"name": "query_ds_task_status", "arguments": {"instance_id": 123}}的結構。框架解析之後，在TOOL_REGISTRY裡找到對應函數執行，再把執行結果拼接成一段「工具回執」，發回給模型，讓它決定繼續調工具還是向用戶總結。這個「工具回執」最好加上一個清晰的前綴，比如[Tool Result: query_ds_task_status]，模型能明確區分哪些內容是工具返回的真實數據，哪些是它自己的推測。

5.2 用 API 觸發 DolphinScheduler 工作流

觸發調度任務的封裝重點在登錄和任務映射。DolphinScheduler 的 REST API 登錄後通常需要保持 session，或者把返回的 token 放在後續請求頭裡。下面是基於 requests 的簡化實現：

def ds_login(base_url: str, username: str, password: str) -> requests.Session: session = requests.Session() login_url = f"{base_url}/dolphinscheduler/login" resp = session.post(login_url, data={"userName": username, "userPassword": password}) resp.raise_for_status() return session def trigger_ds_process(session: requests.Session, base_url: str, project_code: str, process_definition_code: str, run_date: str) -> int: """創建一個流程實例並返回實例 ID""" url = f"{base_url}/dolphinscheduler/projects/{project_code}/executors/start-process-instance" params = { "processDefinitionCode": process_definition_code, "scheduleTime": run_date, "failureStrategy": "CONTINUE", "warningType": "FAIL", "warningGroupId": 1, "execType": "START_PROCESS", "runMode": "RUN_MODE_SERIAL", "processInstancePriority": "MEDIUM", } resp = session.post(url, params=params) resp.raise_for_status() # DS 返回的數據裡包含流程實例 ID，根據實際接口提取 return resp.json()["data"]["processInstance"]["id"]

這裡有一個實戰技巧：scheduleTime參數對應補跑日期。用戶說「補跑昨天」，我會提前把「昨天」換算成YYYY-MM-DD格式再傳入，而不是把「昨天」這個自然語言直接丟給 DS，因為調度系統只認具體時間，不認模糊概念。另外，不同版本的 DolphinScheduler，Open API 的路徑和參數名略有差異，接入前先查一下目標版本的 API 文檔，不要照抄網上舊代碼。

5.3 企業微信告警推送模塊

企微機器人告警的代碼非常直接，但要注意異常捕獲。我封裝成一個獨立函數，並加上簡單重試：

def send_wecom_alert(webhook_url: str, content: str): """發送企業微信 markdown 告警。content 已經轉義並截斷。""" payload = { "msgtype": "markdown", "markdown": {"content": content} } for attempt in range(3): try: resp = requests.post(webhook_url, json=payload, timeout=5) # 企微返回 code 為 0 表示成功，否則是業務錯誤 if resp.json().get("errcode") == 0: return True # 頻率限制等錯誤可以短暫等待後重試 time.sleep(attempt * 2) except requests.RequestException as e: # 記錄異常到日誌，供後續排查 log_error("wecom_alert_failed", e) return False

內容構造時，用 Python 的html.escape()對特殊字符做轉義，再截斷。一個常見的誤區是對整個 JSON 做轉義，其實只需要對content字段正文做轉義，其他部分保持 JSON 結構不變。還有就是企微機器人對每個 Webhook 有頻率限制，如果告警量極大，可以考慮把多條消息合併成一條發送，既符閤企業微信的使用規範，也減少對值班群的打擾。

6. 實戰排查記錄：那些讓我熬夜的故障

6.1 常見問題速查表

系統上線這段時間，我總結了一批高頻問題，整理成表格方便排查：

這裡每個問題背後都有實際案例，不是紙上談兵。比如「增量索引未觸發」那個問題，我排查了整整半天，最後發現是 Git 回調服務在重啟後沒有自動訂閱倉庫變更，導致所有合併請求都靜默丟失。教訓是：任何依賴事件回調的組件，都要在啟動時做一次全量對賬，把漏掉的事件補上再繼續監聽。

6.2 一次告警風暴的真實排查

印象最深的一次故障是某天晚上，值班群突然湧入上百條 P1 告警，全部指向不同的調度任務。第一反應是 DolphinScheduler 集群掛了，但登錄後臺看集群狀態完全正常。再對比告警時間，發現失敗集中在同一分鐘，而且是零星分佈在各個工作流裡。

後來查 DS 的任務日誌，發現所有失敗任務都掛在同一個 Worker 節點上。原來是運維在做晚上低峯期滾動升級，重啟 Worker 期間，正在該節點上執行的任務全部因連接中斷而失敗。這些任務明明有重試機制，但重試請求被調度到了其他節點，反而因為上游依賴事務沒提交，最終狀態還是失敗。這個故障帶給我兩個改變：第一，重啟或者維護窗口要在 XiheAgent 側設置「維護期間抑制告警」的開關，避免無意義的羣組轟炸；第二，告警聚合的邏輯裡要加入「失敗節點 IP」維度，一旦同一節點短時間內大量任務失敗，優先懷疑是節點問題，而不是逐個排查任務。

6.3 給後來者的幾點操作建議

如果你也在做類似的 AI Agent 項目，有幾個建議是基於真實教訓總結的，按按鈕級順序說：

第一，先做紮實的代碼問答，再加任務執行。用戶對 AI 的信任是慢慢累積的，如果一上來就讓它操作調度系統，一旦出錯，後面再想挽回信任就很難。我前兩週幾乎都在打磨問答層的準確性，後續執行層的開發反而是順水推舟。

第二，所有風險操作必須有確認機制。XiheAgent 現在對生產環境的任何寫操作，都會要求用戶在對話裡明確回覆「確認執行」，而不是讓模型直接動手。多一次確認，少一次事故，也讓操作者有掌控感。

第三，把審計日誌當作一等公民來設計。每條日誌要記錄事件時間、用戶 ID、工具名、輸入參數、輸出摘要、關聯的執行實例 ID。出了問題，能從用戶一句話一路追到具體 API 調用和日誌輸出，這在排查時價值無限。

第四，告警要收斂，不要製造告警。值班的人對告警的反應是：第一聲警報是緊張，第十聲警報是麻木。與其讓大家麻木，不如把告警控制在「有限但有意義」的範圍內。

第五，迭代工具描述比迭代模型參數更容易見效。很多時候模型用錯工具，不是模型不夠聰明，而是工具描述沒有寫清楚邊界。把描述改清楚，準確率能立刻提升一大截。

做這個項目最大的體會是：把 AI 編碼助手從「會說話」推向「會幹活」，真正的難點不在大模型本身，而在工程約束。問答層的檢索、執行層的權限、告警層的收斂，每一個環節都是靠踏踏實實的工程細節堆出來的，沒有任何一條捷徑。最後再分享一個小技巧：在審計日誌裡同時記錄工具調用前後的關鍵狀態，比如任務狀態從WAITING變成RUNNING，這種信息對排查 Agent 的「突發奇想」特別管用。我靠這條技巧定位過好幾次模型把參數傳錯的現場，省下了大量對着模型輸出猜來猜去的時間。