1. 從“工具”這個詞說起opencode 的定位到底特殊在哪聊 opencode 的工具系統(tǒng)之前得先把一個容易混淆的概念掰扯清楚。很多人第一次接觸 opencode看到“工具”兩個字腦子里第一反應(yīng)是插件市場里那種裝完就多一個按鈕的東西。但 opencode 的“工具”不是這個意思它更接近“智能體可以調(diào)用的能力單元”——你可以把它理解成給一個坐在電腦前的助手遞過去的一整套家伙什螺絲刀、扳手、萬用表、示波器每一樣都對應(yīng)一類具體操作。這個定位決定了后面所有討論的走向。opencode 本身是一個智能體框架它的核心循環(huán)是“理解意圖 → 選擇工具 → 執(zhí)行 → 觀察結(jié)果 → 繼續(xù)推理”。工具就是它和外部世界之間的那層接口。沒有工具它只能跟你聊天有了工具它能讀文件、跑命令、查數(shù)據(jù)庫、調(diào)接口、改代碼。這個差別是質(zhì)變不是量變。我見過不少人把 opencode 當(dāng)成一個“更聰明的命令行補全”來用結(jié)果用了一周覺得也就那樣。問題不在工具本身在于沒理解工具系統(tǒng)的設(shè)計意圖。opencode 的工具不是讓你少打幾個字而是讓智能體能夠自主完成一個多步驟任務(wù)鏈。比如你說“幫我把這個項目的測試覆蓋率提上去”它會自己去讀測試報告、定位未覆蓋的分支、生成測試用例、跑一遍驗證、再根據(jù)失敗結(jié)果調(diào)整。這一整套動作背后是多個工具在協(xié)同而不是一個工具在干活。所以下篇要聊的“工具、服務(wù)面、外殼與實戰(zhàn)集成”本質(zhì)上是在回答三個問題opencode 提供了哪些能力單元、這些能力怎么被組織和暴露出來、以及怎么把它塞進(jìn)你現(xiàn)有的工作流里而不是另起爐灶。這三個問題分別對應(yīng)工具系統(tǒng)、服務(wù)面設(shè)計和外殼集成最后落到實戰(zhàn)場景上。適合讀這篇的人我大致分三類。第一類是已經(jīng)裝好 opencode、能跑起來基本對話但不知道怎么讓它真正干活的第二類是想把 opencode 接入自己團隊現(xiàn)有工具鏈的比如你們已經(jīng)在用某套 CI、某個數(shù)據(jù)庫客戶端、某個遠(yuǎn)程運維方案第三類是對智能體框架本身感興趣想看看一個生產(chǎn)可用的工具系統(tǒng)是怎么設(shè)計的。三類人關(guān)注點不同但底層邏輯是通的。2. opencode 工具系統(tǒng)的整體設(shè)計思路2.1 為什么是“工具”而不是“插件”插件和工具的區(qū)別往深了說是一個架構(gòu)哲學(xué)問題。插件通常是“我提供一個擴展點你來填”擴展點的形狀是框架定死的你只能在這個形狀里做文章。工具則是“我提供一個調(diào)用協(xié)議你按協(xié)議實現(xiàn)能力”協(xié)議是穩(wěn)定的能力是開放的。opencode 選工具路線我推測有幾個考量。第一是智能體的推理過程需要工具的描述信息來支撐決策工具的名稱、參數(shù)、返回值類型這些元數(shù)據(jù)必須能被模型理解插件那種黑盒式擴展做不到這一點。第二是工具需要支持組合一個任務(wù)可能同時用到文件讀寫、命令執(zhí)行、網(wǎng)絡(luò)請求三類工具它們之間要能傳遞數(shù)據(jù)插件模型下這種組合會很別扭。第三是工具的執(zhí)行結(jié)果需要被結(jié)構(gòu)化地反饋回推理循環(huán)插件通常只返回一個 UI 狀態(tài)信息量不夠。這個選擇帶來的直接好處是你可以給 opencode 加一個“查內(nèi)部工單系統(tǒng)”的工具它就能在排查問題時自己去查相關(guān)工單而不是你復(fù)制粘貼給它。壞處是工具的開發(fā)門檻比插件高一點你得理解它的調(diào)用協(xié)議。2.2 工具的三層結(jié)構(gòu)聲明、實現(xiàn)、注冊opencode 的工具系統(tǒng)我拆成三層來看。最上面是聲明層描述這個工具叫什么、干什么、需要什么參數(shù)、返回什么。這一層是給模型看的措辭很關(guān)鍵寫得好模型就知道什么時候該用寫得差模型就瞎調(diào)。中間是實現(xiàn)層真正干活的代碼可能是調(diào)一個 API、跑一段 shell、讀一個文件。最下面是注冊層把工具掛到 opencode 的運行時里讓它能被發(fā)現(xiàn)和調(diào)用。這三層分離的好處是你可以先寫聲明讓模型認(rèn)識這個工具實現(xiàn)慢慢補也可以換實現(xiàn)而不動聲明模型那邊的行為不變。我實際用下來聲明層的措辭是最容易踩坑的地方。比如你寫“查詢數(shù)據(jù)庫”模型可能在任何跟數(shù)據(jù)沾邊的時候都去調(diào)它你寫“根據(jù) SQL 語句查詢只讀數(shù)據(jù)庫并返回結(jié)果集”模型的調(diào)用就精準(zhǔn)很多。2.3 內(nèi)置工具和自定義工具的邊界opencode 自帶一批內(nèi)置工具覆蓋文件操作、命令執(zhí)行、網(wǎng)絡(luò)請求這些高頻場景。自定義工具則是你根據(jù)自己環(huán)境加的。邊界在哪我的經(jīng)驗是凡是“通用且無狀態(tài)”的能力內(nèi)置就夠了凡是“跟你的環(huán)境強相關(guān)”或者“需要維護(hù)狀態(tài)”的就該自定義。舉個例子讀文件是通用的內(nèi)置沒問題。但“讀我們公司內(nèi)部文檔系統(tǒng)里的文件”就強相關(guān)了得自定義。再比如跑 shell 命令是通用的但“在我們這套受限環(huán)境里跑命令并做權(quán)限校驗”就強相關(guān)了。這個邊界不是絕對的但按這個原則走工具集不會太臃腫也不會太單薄。3. 核心工具類型逐個拆解與實操要點3.1 文件與代碼操作類工具這類工具是使用頻率最高的。讀文件、寫文件、列目錄、搜索內(nèi)容看起來簡單但細(xì)節(jié)很多。讀文件工具通常要處理編碼問題、大文件截斷、二進(jìn)制文件識別。寫文件工具要處理覆蓋還是追加、目錄不存在時是否自動創(chuàng)建、寫入失敗的回滾。我踩過的一個坑是行尾符。在跨平臺場景下同一個文件在不同系統(tǒng)上可能用不同的行尾符如果工具不做歸一化處理模型看到的和實際寫的可能不一致導(dǎo)致它基于錯誤的前提做判斷。后來我在自定義的文件工具里加了一層行尾符檢測和轉(zhuǎn)換問題就沒了。另一個坑是大文件。有些實現(xiàn)會一次性把整個文件讀進(jìn)上下文幾萬行的文件直接把上下文撐爆。合理的做法是分塊讀或者先返回文件的行數(shù)和結(jié)構(gòu)摘要讓模型決定讀哪一段。opencode 的內(nèi)置讀文件工具在這方面做得還行但如果你自己實現(xiàn)這塊一定要考慮。實操上我建議給文件工具加一個“dry run”模式就是只返回將要執(zhí)行的操作而不真正執(zhí)行。這在批量修改場景下特別有用模型可以先 dry run 一遍讓你確認(rèn)確認(rèn)了再真跑。這個模式不是內(nèi)置的但自己加不復(fù)雜。3.2 命令執(zhí)行類工具的安全邊界命令執(zhí)行是威力最大也最危險的工具。opencode 在這塊的默認(rèn)策略我觀察下來是偏保守的會要求確認(rèn)或者限制在某些目錄下執(zhí)行。這個保守是對的因為一個失控的命令執(zhí)行工具能造成的破壞是災(zāi)難性的。安全邊界我建議從幾個維度設(shè)。第一是命令白名單只允許特定前綴的命令比如 git、npm、pytest 這些。第二是目錄限制命令的工作目錄必須在項目根目錄下。第三是超時控制任何命令超過一定時間就強制終止防止卡死。第四是輸出截斷命令輸出可能非常大要限制返回給模型的行數(shù)。注意不要因為圖方便就把命令執(zhí)行工具的限制全關(guān)掉。我見過有人為了讓它能跑系統(tǒng)級命令把沙箱整個拆了結(jié)果模型誤執(zhí)行了一條刪除命令損失不小。限制帶來的那點不便跟事故成本比起來不值一提。超時控制這塊有個細(xì)節(jié)不同命令的合理超時差別很大。跑個 lint 可能幾秒跑個完整測試套件可能幾分鐘。一刀切設(shè)一個值要么誤殺要么形同虛設(shè)。我的做法是給工具加一個超時參數(shù)模型可以根據(jù)命令類型自己指定同時設(shè)一個硬上限兜底。3.3 網(wǎng)絡(luò)與 API 調(diào)用類工具這類工具讓 opencode 能跟外部服務(wù)交互。實現(xiàn)上要注意的是認(rèn)證信息的處理。API key 這類東西絕對不能出現(xiàn)在工具的聲明里也不能出現(xiàn)在返回給模型的內(nèi)容里。正確的做法是工具實現(xiàn)層從環(huán)境變量或者密鑰管理服務(wù)里取模型只看到“調(diào)用成功”和業(yè)務(wù)數(shù)據(jù)。重試和限流也是必須考慮的。外部服務(wù)不穩(wěn)定是常態(tài)工具要能區(qū)分“可重試的錯誤”和“不可重試的錯誤”。網(wǎng)絡(luò)超時、5xx 錯誤可以重試4xx 里的認(rèn)證失敗、參數(shù)錯誤重試也沒用。重試要有退避策略不能死循環(huán)猛打。返回值的結(jié)構(gòu)化程度直接影響模型的使用效果。如果 API 返回一大坨 JSON模型可能抓不住重點。好的做法是在工具實現(xiàn)里做一層提取只返回模型真正需要的字段或者返回一個摘要加原始數(shù)據(jù)的引用。這個“摘要加引用”的模式我在多個項目里用過效果很好既省上下文又不丟信息。3.4 數(shù)據(jù)查詢類工具的只讀約束數(shù)據(jù)庫查詢工具是很多團隊最想要的一類。opencode 接數(shù)據(jù)庫核心約束是只讀。寫操作應(yīng)該走另一條路徑不能跟查詢混在一起。只讀約束的實現(xiàn)方式有幾種最簡單的是在 SQL 層面攔截只允許 SELECT 開頭的語句。但這種方式不嚴(yán)謹(jǐn)有些數(shù)據(jù)庫的 SELECT 也能觸發(fā)副作用比如某些函數(shù)調(diào)用。更穩(wěn)妥的是在數(shù)據(jù)庫連接層面用只讀賬號。給 opencode 配一個只有 SELECT 權(quán)限的數(shù)據(jù)庫用戶從根上杜絕寫操作。這個做法我在生產(chǎn)環(huán)境用過很穩(wěn)。代價是要多維護(hù)一個賬號但安全收益值得。查詢結(jié)果的返回也要控制。一個大表全查出來可能幾十萬行必須加分頁或者 LIMIT。我通常會在工具里強制加一個默認(rèn) LIMIT模型可以顯式指定更大的值但要有上限。另外查詢超時也要設(shè)慢查詢不能讓它一直掛著。4. 服務(wù)面設(shè)計工具怎么被組織和暴露4.1 服務(wù)面的概念和它解決的問題“服務(wù)面”這個詞聽起來抽象其實說的是一件很具體的事opencode 的工具不是散裝的一堆函數(shù)而是按某種結(jié)構(gòu)組織起來、通過一個統(tǒng)一的接口暴露出去的。這個統(tǒng)一接口就是服務(wù)面。為什么需要服務(wù)面因為工具多了之后直接暴露會亂。模型面對幾十個工具選擇困難調(diào)用錯誤率上升。服務(wù)面做的事情是分層把相關(guān)的工具歸到一個服務(wù)下模型先選服務(wù)再選工具決策空間小了準(zhǔn)確率就上去了。我自己的項目里工具數(shù)量超過十五個之后不加服務(wù)面分層模型的調(diào)用準(zhǔn)確率明顯下降。加了分層之后同樣的工具集準(zhǔn)確率回升到可接受水平。這個經(jīng)驗不一定普適但方向是對的工具的組織方式影響模型的使用效果。4.2 服務(wù)面的劃分原則劃分服務(wù)面沒有標(biāo)準(zhǔn)答案但有幾個原則可以參考。按領(lǐng)域劃分是最自然的文件服務(wù)、命令服務(wù)、數(shù)據(jù)服務(wù)、網(wǎng)絡(luò)服務(wù)各管一攤。按權(quán)限劃分也常見只讀服務(wù)和可寫服務(wù)分開敏感操作單獨一個面。按使用頻率劃分也有道理高頻工具放一個面低頻的放另一個減少干擾。我傾向按領(lǐng)域為主、權(quán)限為輔。領(lǐng)域劃分符合模型的語義理解習(xí)慣權(quán)限劃分作為補充處理那些需要額外管控的工具。比如數(shù)據(jù)服務(wù)下面查詢工具和寫入工具分屬兩個子面模型知道查詢是安全的寫入要謹(jǐn)慎。服務(wù)面的粒度也要注意。太粗了等于沒分太細(xì)了模型記不住。我的經(jīng)驗是每個服務(wù)面下五到十個工具比較合適超過十五個就該考慮再分。4.3 服務(wù)面的版本管理和兼容性工具是會變的服務(wù)面也會變。加工具、改參數(shù)、換實現(xiàn)這些都會影響使用方的兼容性。版本管理這塊我的做法是服務(wù)面整體打版本號工具級別的變更通過服務(wù)面版本體現(xiàn)。模型調(diào)用時指定服務(wù)面版本這樣舊版本的調(diào)用行為不會因為新工具加入而改變。兼容性策略上破壞性變更要謹(jǐn)慎。改工具名、改必填參數(shù)、改返回結(jié)構(gòu)這些都是破壞性的。能通過加可選參數(shù)解決的就不要改必填參數(shù)。能通過新增工具解決的就不要改現(xiàn)有工具。這個原則跟 API 設(shè)計是一樣的只是使用方從人變成了模型。5. 外殼集成把 opencode 塞進(jìn)現(xiàn)有工作流5.1 外殼是什么為什么需要它“外殼”這個詞我用它來指代 opencode 跟外部環(huán)境的接口層。opencode 本身是個內(nèi)核它需要被包在一個外殼里才能在你的具體環(huán)境里跑起來。這個外殼可能是一個 CLI、一個編輯器插件、一個 CI 步驟、一個聊天機器人形式不限。為什么需要外殼因為內(nèi)核提供的是通用能力而你的工作流是具體的。你不可能讓 opencode 直接理解你團隊的代碼規(guī)范、部署流程、審批鏈路這些都得通過外殼來適配。外殼做的事情是接收你的輸入、轉(zhuǎn)成 opencode 能理解的格式、調(diào)用內(nèi)核、把結(jié)果轉(zhuǎn)回你習(xí)慣的形式。5.2 編輯器集成以 VS Code 為例編輯器集成是最常見的場景。VS Code 里跑 opencode核心要解決的是上下文傳遞問題。編輯器知道當(dāng)前打開的文件、光標(biāo)位置、選中的代碼這些信息對 opencode 很有價值但需要通過外殼傳進(jìn)去。我實際配下來關(guān)鍵點有幾個。第一是工作目錄要對opencode 的文件工具是相對于工作目錄的工作目錄錯了它讀的文件就錯了。第二是環(huán)境變量要傳尤其是認(rèn)證相關(guān)的。第三是輸出要能回顯到編輯器里不能只在終端里刷。VS Code 的集成方式有幾種官方擴展、任務(wù)配置、終端里直接跑。官方擴展體驗最好但靈活性差任務(wù)配置靈活但要自己寫終端里跑最靈活但上下文傳遞要手動。我一般推薦先用官方擴展跑通有特殊需求再考慮自己寫外殼。5.3 CI/CD 流水線里的 opencode把 opencode 放進(jìn) CI 流水線用途主要是代碼審查、測試生成、變更分析這幾類。這個場景跟交互式使用差別很大核心是無人值守所以安全邊界要更嚴(yán)。我的做法是給 CI 里的 opencode 配一套獨立的工具集只開放只讀工具和有限的寫工具。寫工具限制在特定目錄比如只允許寫測試文件不允許改業(yè)務(wù)代碼。命令執(zhí)行工具限制在測試和 lint 命令不允許跑部署腳本。輸出處理也不一樣。交互式場景下輸出給人看CI 場景下輸出要能被流水線解析。我通常讓 opencode 輸出結(jié)構(gòu)化的結(jié)果比如 JSON 格式的審查意見然后流水線根據(jù)這個結(jié)果決定是阻斷還是放行。5.4 遠(yuǎn)程運維場景的集成要點遠(yuǎn)程運維是另一個高頻場景。opencode 通過 SSH 工具連到遠(yuǎn)程機器上執(zhí)行操作這個場景的坑主要在連接管理和狀態(tài)保持上。SSH 連接是有狀態(tài)的但 opencode 的工具調(diào)用是無狀態(tài)的這中間的適配要做好。我的做法是把 SSH 連接封裝成一個有狀態(tài)的服務(wù)工具調(diào)用時通過連接 ID 找到對應(yīng)的連接。連接池要管理好空閑連接及時釋放避免占滿遠(yuǎn)程機器的連接數(shù)。命令執(zhí)行的超時和輸出截斷在這個場景下尤其重要遠(yuǎn)程命令卡住或者輸出爆炸都是常見問題。提示遠(yuǎn)程運維場景下建議給 opencode 配一個專用的跳板賬號權(quán)限按最小必要原則給。不要用你的個人賬號出了問題不好追溯也不好限制。6. 實戰(zhàn)集成幾個能直接抄的場景6.1 場景一自動化代碼審查這個場景的目標(biāo)是讓 opencode 在每次提交時自動審查代碼給出結(jié)構(gòu)化的意見。實現(xiàn)路徑是CI 觸發(fā) → 拉取變更 → 調(diào)用 opencode → 解析輸出 → 回寫 PR。工具集配置上需要文件讀取工具讀變更文件、代碼搜索工具找相關(guān)上下文、靜態(tài)分析工具跑 lint。不需要寫工具審查是只讀的。命令執(zhí)行工具限制在 lint 和測試命令。提示詞是關(guān)鍵。我用的提示詞大致是你是一個代碼審查助手請審查以下變更關(guān)注邏輯正確性、邊界條件、錯誤處理、性能問題輸出 JSON 格式的意見列表每條包含文件、行號、嚴(yán)重程度、描述。這個提示詞我迭代了好幾版早期版本輸出太啰嗦后來加了格式約束才好。6.2 場景二測試用例生成與驗證這個場景比審查復(fù)雜因為它涉及寫操作和驗證循環(huán)。流程是讀目標(biāo)代碼 → 生成測試用例 → 寫入測試文件 → 跑測試 → 根據(jù)結(jié)果調(diào)整 → 重復(fù)直到通過或達(dá)到上限。工具集需要文件讀寫、命令執(zhí)行、測試結(jié)果解析。寫操作限制在測試目錄下。循環(huán)次數(shù)要設(shè)上限防止無限重試。我一般設(shè)三輪三輪還不過就放棄并報告。這個場景的坑在于測試環(huán)境的準(zhǔn)備。如果測試依賴數(shù)據(jù)庫或者外部服務(wù)opencode 跑測試時這些依賴得就緒。我的做法是在外殼層做環(huán)境檢查依賴沒就緒就直接返回錯誤不讓 opencode 白跑。6.3 場景三數(shù)據(jù)庫變更影響分析這個場景是只讀的但價值很高。給定一個數(shù)據(jù)庫變更比如加字段、改索引讓 opencode 分析影響范圍。流程是讀變更腳本 → 查數(shù)據(jù)庫元數(shù)據(jù) → 搜索代碼里的相關(guān)引用 → 生成影響報告。工具集需要數(shù)據(jù)庫查詢工具只讀、代碼搜索工具、文件讀取工具。數(shù)據(jù)庫查詢工具要能查 information_schema 這類元數(shù)據(jù)表。代碼搜索要能搜 SQL 字符串、ORM 映射、數(shù)據(jù)模型定義。這個場景的輸出我要求包含三部分直接影響的表和字段、間接影響的代碼模塊、建議的驗證步驟。第三部分特別有用它把分析結(jié)果轉(zhuǎn)化成了可執(zhí)行的驗證清單。6.4 場景四運維故障排查輔助故障排查場景下opencode 的角色是輔助而不是替代。它能做的是快速收集信息、關(guān)聯(lián)分析、給出排查方向最終判斷還是人來做。工具集需要日志查詢、指標(biāo)查詢、配置讀取、命令執(zhí)行只讀命令。這個場景對工具的響應(yīng)速度要求高因為故障排查是爭分奪秒的。工具實現(xiàn)要優(yōu)化能并行的并行能緩存的緩存。我實際用下來這個場景最大的價值是減少信息收集的時間。以前排查一個故障要登好幾臺機器、查好幾個系統(tǒng)現(xiàn)在一句話讓 opencode 把相關(guān)信息都拉過來我直接看匯總結(jié)果。省下來的時間可以用來思考。7. 常見問題與排查技巧實錄7.1 工具調(diào)用失敗怎么排查工具調(diào)用失敗的原因很多排查要有章法。我的排查順序是先看工具聲明有沒有問題再看參數(shù)對不對再看實現(xiàn)有沒有報錯最后看環(huán)境依賴。聲明問題最常見的是描述不清導(dǎo)致模型傳錯參數(shù)。排查方法是把工具的聲明單獨拿出來看假設(shè)你是一個不了解這個工具的人能不能根據(jù)聲明正確調(diào)用。如果不能聲明就要改。參數(shù)問題看模型的調(diào)用記錄它傳了什么、期望什么。類型不匹配、必填項缺失、格式錯誤這些都能從記錄里看出來。實現(xiàn)問題看日志工具內(nèi)部的異常要打出來。環(huán)境問題看依賴網(wǎng)絡(luò)通不通、認(rèn)證過沒過、權(quán)限夠不夠。7.2 模型不調(diào)用工具或者亂調(diào)用工具這個問題的根源通常在工具的聲明和提示詞上。模型不調(diào)用可能是聲明寫得太模糊模型不知道什么時候該用也可能是提示詞沒引導(dǎo)它用工具。亂調(diào)用可能是聲明寫得太寬泛什么場景都匹配。解決辦法是收緊聲明。把工具的適用場景寫具體把不適用的場景也寫出來。比如“當(dāng)需要查詢數(shù)據(jù)庫時使用”改成“當(dāng)需要根據(jù) SQL 語句查詢只讀數(shù)據(jù)庫并獲取結(jié)果集時使用不適用于數(shù)據(jù)寫入場景”。這個改動看起來小效果很明顯。提示詞里也可以加引導(dǎo)。明確告訴模型在什么情況下應(yīng)該用工具而不是憑記憶回答。這個引導(dǎo)要具體不能泛泛說“多用工具”。7.3 上下文被工具輸出撐爆工具輸出太大是常見問題。解決辦法有幾個層次。最直接的是截斷超過一定長度就截掉但截斷可能丟關(guān)鍵信息。好一點的是摘要讓工具實現(xiàn)返回摘要而不是原始數(shù)據(jù)。更好的是分頁模型需要更多再取。我通常組合使用。默認(rèn)返回摘要加前 N 行模型覺得不夠可以請求更多。這個“按需獲取”的模式比一次性給全更省上下文也更符合模型的推理節(jié)奏。7.4 工具執(zhí)行的安全事故預(yù)防安全事故預(yù)防的核心是假設(shè)模型會犯錯?；谶@個假設(shè)所有工具都要有兜底。寫操作要有備份或者回滾命令執(zhí)行要有沙箱或者白名單網(wǎng)絡(luò)請求要有域名限制數(shù)據(jù)查詢要有只讀約束。我還會加一層人工確認(rèn)。高風(fēng)險操作在執(zhí)行前彈確認(rèn)確認(rèn)了才跑。這個確認(rèn)可以配置低風(fēng)險操作不確認(rèn)高風(fēng)險操作必須確認(rèn)。確認(rèn)的內(nèi)容要清楚讓操作者知道將要發(fā)生什么。7.5 常見問題速查表問題現(xiàn)象可能原因排查方向解決建議工具不被調(diào)用聲明模糊、提示詞未引導(dǎo)檢查工具描述和系統(tǒng)提示收緊聲明加調(diào)用引導(dǎo)工具被亂調(diào)用聲明過寬、場景重疊檢查工具適用場景描述明確不適用場景拆分工具調(diào)用參數(shù)錯誤參數(shù)描述不清、類型不明檢查參數(shù)定義和調(diào)用記錄補充參數(shù)說明和示例執(zhí)行超時命令耗時、網(wǎng)絡(luò)慢檢查超時設(shè)置和實際耗時調(diào)整超時加異步處理輸出撐爆上下文返回數(shù)據(jù)過大檢查返回內(nèi)容大小加截斷、摘要或分頁認(rèn)證失敗密鑰過期、權(quán)限不足檢查認(rèn)證配置和權(quán)限更新密鑰調(diào)整權(quán)限結(jié)果不符合預(yù)期實現(xiàn)邏輯錯誤檢查工具實現(xiàn)代碼修實現(xiàn)加測試并發(fā)沖突共享狀態(tài)未隔離檢查狀態(tài)管理加鎖或隔離狀態(tài)8. 工具集維護(hù)與迭代的一些經(jīng)驗工具集不是一次配好就完事的它需要持續(xù)維護(hù)。我自己的做法是定期回顧工具的使用情況看哪些工具高頻、哪些低頻、哪些從沒被調(diào)用過。低頻和零調(diào)用的工具考慮下線減少模型的決策負(fù)擔(dān)。工具的聲明也要定期審視。隨著模型能力的提升有些以前需要詳細(xì)說明的地方現(xiàn)在可以簡化隨著使用場景的變化有些以前沒考慮到的場景需要補充說明。這個審視我一般一個月做一次花不了多少時間但收益明顯。版本管理上我建議工具集整體打版本跟 opencode 內(nèi)核版本解耦。內(nèi)核升級不一定需要工具集升級工具集升級也不一定需要內(nèi)核升級。這個解耦讓升級更靈活風(fēng)險也更可控。最后說一個我踩過的坑。早期我追求工具數(shù)量覺得工具越多能力越強。后來發(fā)現(xiàn)工具多了之后模型的調(diào)用準(zhǔn)確率反而下降因為選擇太多?，F(xiàn)在我傾向于精簡能用組合工具解決的就不新增單一工具能合并的就合并。工具集的質(zhì)量比數(shù)量重要得多。這個內(nèi)容后續(xù)還可以往幾個方向擴展。一是工具的性能優(yōu)化尤其是高頻工具的響應(yīng)速度二是工具的可觀測性怎么監(jiān)控工具的使用情況和效果三是多智能體場景下的工具共享和隔離。這幾個方向我還在摸索有心得再分享。