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