1. 從 JAZ 這個(gè)標(biāo)題說(shuō)起Harness 為什么值得被當(dāng)成一門(mén)語(yǔ)言來(lái)對(duì)待第一次看到“Harness as a Language”這個(gè)說(shuō)法我的反應(yīng)是終于有人把這件事挑明了。過(guò)去兩年大家聊 Agent、聊 LLM 應(yīng)用注意力幾乎都?jí)涸谀Ｐ捅旧怼獏?shù)多大、上下文多長(zhǎng)、榜單排第幾。但真正在一線把 Agent 跑起來(lái)的人心里都清楚模型只是發(fā)動(dòng)機(jī)決定這臺(tái)車(chē)能不能上路、能不能跑長(zhǎng)途的是外面那層殼工具怎么掛、狀態(tài)怎么存、失敗怎么重試、權(quán)限怎么收口。這層殼英文里常被叫做 Harness。JAZ 這個(gè)研究最抓人的地方不是又提出了一個(gè) Agent 框架而是換了個(gè)視角把 Harness 從“一堆膠水代碼”提升到“一門(mén)語(yǔ)言”的高度來(lái)設(shè)計(jì)。這個(gè)視角的轉(zhuǎn)變直接決定了后面所有的工程取舍。你把它當(dāng)膠水它就是一堆 if-else 和 try-catch你把它當(dāng)語(yǔ)言它就得有語(yǔ)法、有語(yǔ)義、有作用域、有組合規(guī)則、有錯(cuò)誤模型。這兩種心態(tài)寫(xiě)出來(lái)的東西維護(hù)成本差著一個(gè)數(shù)量級(jí)。我先把結(jié)論擺在前面方便你對(duì)號(hào)入座如果你只是想讓模型調(diào)一兩個(gè) API 做個(gè) demo那 Harness 是不是語(yǔ)言無(wú)所謂怎么寫(xiě)都能跑。但只要你開(kāi)始面對(duì)多工具、多輪次、多 Agent 協(xié)作、需要回退和審計(jì)的真實(shí)場(chǎng)景Harness 的設(shè)計(jì)質(zhì)量就會(huì)變成整個(gè)系統(tǒng)的天花板。JAZ 想解決的正是這個(gè)天花板問(wèn)題。這篇文章我會(huì)按一線落地的順序來(lái)拆先講清楚 Harness 和 Agent 到底怎么分工再講 JAZ 把 Harness 語(yǔ)言化背后的設(shè)計(jì)邏輯然后是核心機(jī)制怎么落地、實(shí)操里怎么搭、踩坑怎么排。全程按“能抄作業(yè)”的標(biāo)準(zhǔn)寫(xiě)參數(shù)和步驟我都會(huì)給到能直接用的程度。1.1 先把概念釘死Harness、Agent、LLM 三者到底誰(shuí)管什么很多人一上來(lái)就混著用這三個(gè)詞結(jié)果架構(gòu)圖畫(huà)出來(lái)自己都說(shuō)不清邊界。我用一個(gè)生活化的類(lèi)比把它釘死LLM 是那個(gè)腦子很好使但只會(huì)動(dòng)嘴的顧問(wèn)Agent 是帶著這個(gè)顧問(wèn)去干活的項(xiàng)目經(jīng)理Harness 是項(xiàng)目經(jīng)理手里的那套流程手冊(cè)加工具箱。具體到職責(zé)LLM負(fù)責(zé)理解和生成。你給它一段上下文它吐出下一步該干嘛的意圖。它本身沒(méi)有記憶、沒(méi)有手腳、不能真的去調(diào)接口。它的輸出是“文本形式的決策”。Agent負(fù)責(zé)把 LLM 的文本決策翻譯成真實(shí)動(dòng)作并維護(hù)“我是誰(shuí)、我在找什么、我能提供什么”這套狀態(tài)。它決定什么時(shí)候該問(wèn) LLM、什么時(shí)候該直接執(zhí)行、什么時(shí)候該停。Harness負(fù)責(zé)提供 Agent 執(zhí)行動(dòng)作所需的一切基礎(chǔ)設(shè)施——工具的注冊(cè)與調(diào)用、參數(shù)的校驗(yàn)、執(zhí)行結(jié)果的規(guī)范化、錯(cuò)誤的分類(lèi)與重試、上下文的拼裝與裁剪、權(quán)限與沙盒的邊界。熱詞里有個(gè)說(shuō)法特別形象LLM 的 token 三個(gè)點(diǎn)是 key“我是誰(shuí)”、query“我在找什么”、value“我能提供什么”。這其實(shí)是在說(shuō)注意力機(jī)制但借到 Agent 語(yǔ)境里也成立——Agent 每一輪都在回答這三個(gè)問(wèn)題而 Harness 就是保證這三個(gè)問(wèn)題能被穩(wěn)定、可復(fù)現(xiàn)地回答的那層機(jī)制。注意把 Harness 和 Agent 混為一談是新手最容易犯的架構(gòu)錯(cuò)誤。Agent 是決策者Harness 是執(zhí)行環(huán)境。決策邏輯可以換模型、換 prompt但 Harness 一旦定下來(lái)整個(gè)系統(tǒng)的行為邊界就定了。1.2 為什么“語(yǔ)言化”不是玩概念而是被逼出來(lái)的我踩過(guò)的坑很典型早期做 Agent工具調(diào)用就是手寫(xiě)函數(shù)模型返回個(gè) JSON我json.loads一下然后if tool_name search: ...。三個(gè)工具的時(shí)候還行十個(gè)工具就開(kāi)始亂三十個(gè)工具的時(shí)候光參數(shù)校驗(yàn)和錯(cuò)誤處理就能寫(xiě)出一千行而且每加一個(gè)工具都要?jiǎng)雍诵倪壿嫓y(cè)試根本覆蓋不過(guò)來(lái)。這就是“膠水心態(tài)”的必然結(jié)局耦合度隨工具數(shù)量線性上升維護(hù)成本指數(shù)上升。JAZ 提出 Harness as a Language本質(zhì)是要把這層耦合切斷。語(yǔ)言化的核心收益有三個(gè)第一聲明與執(zhí)行分離。工具用聲明式的方式注冊(cè)長(zhǎng)什么樣、要什么參數(shù)、返回什么結(jié)構(gòu)全部描述清楚執(zhí)行引擎統(tǒng)一處理調(diào)用、校驗(yàn)、重試。加工具不再動(dòng)核心代碼。第二組合有語(yǔ)法。多個(gè)工具、多個(gè)步驟之間怎么串用一套明確的組合規(guī)則表達(dá)而不是靠散落各處的回調(diào)。這讓“先查再算再寫(xiě)”這種流程可以被靜態(tài)分析、被復(fù)用、被測(cè)試。第三錯(cuò)誤有語(yǔ)義。語(yǔ)言化之后錯(cuò)誤不再是隨便拋的異常而是有類(lèi)型、有層級(jí)、有恢復(fù)策略的一等公民。哪些錯(cuò)該重試、哪些該回退、哪些該直接終止全部可以在 Harness 層統(tǒng)一決策。這三條加起來(lái)才是“語(yǔ)言”這個(gè)詞真正的分量。它不是讓你寫(xiě)起來(lái)更花哨而是讓系統(tǒng)在規(guī)模上去之后還能被理解、被測(cè)試、被演進(jìn)。2. JAZ 的核心設(shè)計(jì)邏輯把 Harness 拆成語(yǔ)法、語(yǔ)義和運(yùn)行時(shí)理解了動(dòng)機(jī)接下來(lái)拆 JAZ 的設(shè)計(jì)。我把它歸納成三層語(yǔ)法層管“能寫(xiě)什么”語(yǔ)義層管“寫(xiě)了是什么意思”運(yùn)行時(shí)層管“跑起來(lái)怎么執(zhí)行”。這三層對(duì)應(yīng)到工程上就是接口定義、類(lèi)型系統(tǒng)和執(zhí)行引擎。2.1 語(yǔ)法層工具與流程的聲明式描述語(yǔ)法層要解決的是“怎么把一個(gè)工具講清楚”。一個(gè)工具至少要說(shuō)清四件事名字、輸入、輸出、副作用。JAZ 的思路是用結(jié)構(gòu)化描述替代散落的函數(shù)簽名讓工具本身成為可被引擎讀取的數(shù)據(jù)而不是只能被程序員讀懂的代碼。我實(shí)際落地時(shí)用的描述結(jié)構(gòu)大概是這樣你可以直接參考{ name: search_docs, description: 在內(nèi)部文檔庫(kù)中檢索相關(guān)片段, input_schema: { type: object, properties: { query: { type: string, minLength: 1 }, top_k: { type: integer, default: 5, minimum: 1, maximum: 20 } }, required: [query] }, output_schema: { type: object, properties: { items: { type: array } } }, side_effect: read_only, timeout_ms: 8000 }這份描述里input_schema和output_schema是關(guān)鍵。它們讓引擎可以在調(diào)用前校驗(yàn)參數(shù)、在返回后校驗(yàn)結(jié)構(gòu)把大量“模型瞎編參數(shù)”的問(wèn)題擋在執(zhí)行之前。side_effect字段則決定了這個(gè)工具能不能在沙盒里跑、要不要額外授權(quán)。timeout_ms是硬性保護(hù)防止某個(gè)工具卡死拖垮整個(gè)流程。提示side_effect這個(gè)字段看著不起眼但它是后面做權(quán)限收口和審計(jì)的基礎(chǔ)。讀操作和寫(xiě)操作必須分開(kāi)標(biāo)記否則你沒(méi)法在 Harness 層做“寫(xiě)操作二次確認(rèn)”這種策略。2.2 語(yǔ)義層類(lèi)型、作用域與組合規(guī)則語(yǔ)法層只是讓工具“可讀”語(yǔ)義層才讓它“可推理”。JAZ 在語(yǔ)義層做了兩件我認(rèn)為最關(guān)鍵的事類(lèi)型約束和組合規(guī)則。類(lèi)型約束的意思是工具之間的數(shù)據(jù)流是有類(lèi)型的。A 工具輸出的結(jié)構(gòu)能不能直接喂給 B 工具引擎要能判斷。這聽(tīng)起來(lái)像類(lèi)型系統(tǒng)實(shí)際落地時(shí)不需要做到那么嚴(yán)格但至少要能識(shí)別“結(jié)構(gòu)不匹配”這種低級(jí)錯(cuò)誤。我見(jiàn)過(guò)太多線上事故根源就是上游返回的字段名變了下游還在按老字段取結(jié)果靜默失敗。組合規(guī)則是語(yǔ)義層的重頭戲。多個(gè)工具怎么串JAZ 用一套顯式的組合表達(dá)而不是靠 Agent 自由發(fā)揮。舉個(gè)實(shí)際例子一個(gè)“先檢索、再總結(jié)、再落庫(kù)”的流程用組合規(guī)則寫(xiě)出來(lái)大概是這樣pipeline summarize_and_store: step retrieve search_docs(queryuser_input, top_k8) step summary llm_summarize(itemsretrieve.items) step persist write_record(contentsummary.text, tagauto) on_error retrieve - fallback: return_empty on_error persist - retry(3, backoffexponential)這段偽代碼里on_error是語(yǔ)義層的核心。它把“出錯(cuò)怎么辦”從散落的 try-catch 提升成了流程定義的一部分。retrieve失敗就返回空persist失敗就重試三次指數(shù)退避。這種策略一旦寫(xiě)進(jìn)流程就可以被復(fù)用、被審計(jì)、被統(tǒng)一修改。2.3 運(yùn)行時(shí)層執(zhí)行引擎、狀態(tài)機(jī)與沙盒運(yùn)行時(shí)層是真正干活的地方。它要維護(hù)一個(gè)狀態(tài)機(jī)記錄當(dāng)前流程走到哪一步、每步的輸入輸出是什么、有沒(méi)有失敗、失敗了幾次。這個(gè)狀態(tài)機(jī)是 Harness 的心臟也是“代碼回退”能力的基礎(chǔ)。熱詞里有人問(wèn)“deepseek harness 代碼回退”怎么搞答案就在這一層?；赝瞬皇呛?jiǎn)單地重新跑一遍而是基于狀態(tài)機(jī)里記錄的快照把系統(tǒng)恢復(fù)到某個(gè)已知良好的狀態(tài)。這就要求運(yùn)行時(shí)在每一步都保存足夠的上下文輸入、輸出、時(shí)間戳、工具版本。沒(méi)有這些回退就是空談。沙盒是運(yùn)行時(shí)層的另一塊。Agent 執(zhí)行工具時(shí)尤其是執(zhí)行代碼類(lèi)工具必須在隔離環(huán)境里跑。JAZ 的設(shè)計(jì)里沙盒的邊界由工具的side_effect和權(quán)限策略共同決定。只讀工具可以在輕量沙盒里跑寫(xiě)操作必須走更嚴(yán)格的授權(quán)鏈路。注意沙盒不是萬(wàn)能的。我見(jiàn)過(guò)有人以為套了沙盒就安全了結(jié)果工具本身有網(wǎng)絡(luò)訪問(wèn)權(quán)限照樣能捅婁子。沙盒要和權(quán)限策略配合用單靠一層防護(hù)是不夠的。3. 核心機(jī)制落地從工具注冊(cè)到并發(fā)扛壓的完整鏈路設(shè)計(jì)講完了接下來(lái)是最實(shí)在的部分怎么把這套東西搭起來(lái)。我按實(shí)際搭建順序走一遍每一步都給到能直接用的配置和參數(shù)。3.1 工具注冊(cè)與參數(shù)校驗(yàn)的實(shí)操細(xì)節(jié)工具注冊(cè)是第一步。我的做法是建一個(gè)注冊(cè)中心所有工具通過(guò)聲明文件注冊(cè)引擎啟動(dòng)時(shí)統(tǒng)一加載。這樣加工具只需要加一個(gè)聲明文件不用動(dòng)核心代碼。參數(shù)校驗(yàn)我強(qiáng)烈建議用 JSON Schema因?yàn)槟Ｐ头祷氐膮?shù)本質(zhì)就是 JSON用同一套 schema 校驗(yàn)最自然。校驗(yàn)分兩道第一道在調(diào)用前檢查必填項(xiàng)、類(lèi)型、范圍第二道在返回后檢查輸出結(jié)構(gòu)是否符合預(yù)期。兩道校驗(yàn)都失敗時(shí)不要直接把原始錯(cuò)誤拋給模型而是轉(zhuǎn)成模型能理解的提示讓它重新生成參數(shù)。這里有個(gè)實(shí)操心得top_k這類(lèi)數(shù)值參數(shù)一定要設(shè)上下限。我吃過(guò)虧模型有時(shí)候會(huì)返回top_k: 1000直接把檢索服務(wù)打爆。加上maximum: 20之后這類(lèi)問(wèn)題基本絕跡。同理字符串參數(shù)要設(shè)maxLength防止模型生成超長(zhǎng)輸入。3.2 上下文拼裝與 token 預(yù)算的分配策略上下文拼裝是 Harness 里最容易被低估的環(huán)節(jié)。Agent 每一輪都要把歷史、工具描述、當(dāng)前任務(wù)拼成 prompt 喂給 LLM拼得好不好直接決定效果和成本。我的分配策略是這樣的先給系統(tǒng)提示和工具描述留固定預(yù)算再給當(dāng)前任務(wù)留一塊剩下的才分給歷史。歷史部分用滑動(dòng)窗口加摘要最近幾輪保留原文更早的壓縮成摘要。具體比例我一般按 2:3:5 來(lái)分——系統(tǒng)提示占兩成當(dāng)前任務(wù)占三成歷史占五成。這個(gè)比例不是死的任務(wù)越復(fù)雜當(dāng)前任務(wù)那塊要越大。token 預(yù)算一定要顯式管理。我見(jiàn)過(guò)太多項(xiàng)目上下文無(wú)限增長(zhǎng)跑到十幾輪之后要么超限報(bào)錯(cuò)要么成本失控。顯式預(yù)算的意思是每次拼裝前先算一下還剩多少額度超了就主動(dòng)裁剪而不是等模型報(bào)錯(cuò)。3.3 并發(fā)場(chǎng)景下 Agent 怎么扛住壓力熱詞里“ai agent 怎么扛并發(fā)”是個(gè)高頻問(wèn)題我單獨(dú)拎出來(lái)講。Agent 扛并發(fā)和普通服務(wù)扛并發(fā)不一樣因?yàn)槊總€(gè)請(qǐng)求背后可能掛著多次 LLM 調(diào)用和工具調(diào)用鏈路長(zhǎng)、耗時(shí)不可控。我的做法分三層。第一層是請(qǐng)求級(jí)限流用令牌桶控制入口 QPS防止瞬間打滿。第二層是 LLM 調(diào)用級(jí)并發(fā)控制因?yàn)?LLM 接口通常有并發(fā)上限超了會(huì)被拒。第三層是工具調(diào)用級(jí)的隔離不同工具用不同的線程池或連接池防止一個(gè)慢工具拖垮所有請(qǐng)求。具體參數(shù)上LLM 調(diào)用并發(fā)我一般設(shè)成接口上限的 80%留 20% 余量應(yīng)對(duì)突發(fā)。工具調(diào)用超時(shí)統(tǒng)一設(shè) 8 到 10 秒超過(guò)就降級(jí)。降級(jí)策略要提前定義好比如檢索失敗就返回空結(jié)果而不是讓整個(gè)流程掛掉。提示并發(fā)問(wèn)題里最隱蔽的是“重試風(fēng)暴”。一個(gè)工具超時(shí)如果所有請(qǐng)求同時(shí)重試會(huì)把下游瞬間打爆。重試一定要加抖動(dòng)比如backoff base * 2^n random(0, base)避免重試同步。3.4 錯(cuò)誤分類(lèi)與恢復(fù)策略的對(duì)照表錯(cuò)誤處理是 Harness 語(yǔ)言化之后收益最明顯的地方。我把常見(jiàn)錯(cuò)誤整理成一張表直接對(duì)應(yīng)恢復(fù)策略錯(cuò)誤類(lèi)型典型場(chǎng)景恢復(fù)策略是否重試參數(shù)校驗(yàn)失敗模型生成非法參數(shù)回傳提示讓模型重生成是最多 2 次工具超時(shí)下游服務(wù)慢降級(jí)或換備用工具是指數(shù)退避權(quán)限拒絕越權(quán)訪問(wèn)直接終止并記錄否輸出結(jié)構(gòu)不符上游字段變更記錄并告警否需人工介入LLM 接口拒絕schema 不匹配修正 payload 后重試是最多 1 次沙盒異常隔離環(huán)境故障切換沙盒實(shí)例是最多 1 次這張表的價(jià)值在于它把“出錯(cuò)怎么辦”從個(gè)人經(jīng)驗(yàn)變成了團(tuán)隊(duì)共識(shí)。新人接手時(shí)不用猜照著表來(lái)就行。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄這一節(jié)是我踩坑踩出來(lái)的都是文檔里不會(huì)寫(xiě)的。4.1 模型返回的 JSON 解析失敗怎么辦這是最高頻的問(wèn)題。模型有時(shí)候會(huì)在 JSON 外面包一層解釋文字或者用單引號(hào)或者少個(gè)括號(hào)。我的處理是三步先嘗試直接解析失敗就用正則提取第一個(gè)完整 JSON 塊再失敗就回傳錯(cuò)誤讓模型重新生成。但更根本的解法是在 prompt 里明確要求“只輸出 JSON不要任何解釋”并且用 schema 約束輸出。如果模型支持結(jié)構(gòu)化輸出一定要開(kāi)。開(kāi)了之后解析失敗率能從百分之幾降到千分之幾。4.2 工具調(diào)用陷入死循環(huán)怎么破Agent 有時(shí)候會(huì)反復(fù)調(diào)同一個(gè)工具因?yàn)槟Ｐ陀X(jué)得上次結(jié)果不滿意。我的做法是給每個(gè)工具設(shè)調(diào)用次數(shù)上限比如同一個(gè)工具在同一任務(wù)里最多調(diào) 5 次超了就強(qiáng)制進(jìn)入下一步或終止。另一個(gè)技巧是在上下文里顯式記錄“你已經(jīng)調(diào)過(guò)這個(gè)工具了結(jié)果是……”讓模型看到歷史減少重復(fù)調(diào)用。這個(gè)改動(dòng)很小但效果很明顯。4.3 上下文超限的排查思路上下文超限通常不是突然發(fā)生的而是慢慢漲上來(lái)的。我的排查順序是先看歷史是不是沒(méi)裁剪再看工具返回是不是太大最后看是不是有工具把整個(gè)文檔塞進(jìn)了上下文。工具返回一定要做截?cái)唷z索類(lèi)工具返回的片段單條不要超過(guò) 500 字總數(shù)不要超過(guò) 3000 字。超出的部分要么丟棄要么摘要。這一步不做上下文遲早爆。4.4 沙盒里工具跑不通的常見(jiàn)原因沙盒環(huán)境干凈很多依賴沒(méi)有。常見(jiàn)原因有三個(gè)缺依賴庫(kù)、缺環(huán)境變量、網(wǎng)絡(luò)不通。排查時(shí)先在沙盒里跑一個(gè)最小復(fù)現(xiàn)腳本確認(rèn)基礎(chǔ)環(huán)境沒(méi)問(wèn)題再逐步加依賴。環(huán)境變量要顯式注入不要指望沙盒繼承宿主環(huán)境。網(wǎng)絡(luò)訪問(wèn)要按需開(kāi)放只讀工具通常不需要網(wǎng)絡(luò)寫(xiě)工具才需要而且要走白名單。5. 我對(duì) Harness 工程化的一點(diǎn)個(gè)人體會(huì)搭了幾套 Agent 系統(tǒng)之后我最大的體會(huì)是Harness 的質(zhì)量不取決于你用了多花哨的框架而取決于你有沒(méi)有把它當(dāng)成一門(mén)需要設(shè)計(jì)的語(yǔ)言來(lái)對(duì)待。語(yǔ)法清晰、語(yǔ)義明確、運(yùn)行時(shí)可靠這三條做到了用什么框架都能跑得穩(wěn)做不到換再多框架也是換個(gè)地方踩坑。JAZ 把 Harness 語(yǔ)言化這個(gè)提法真正的價(jià)值是給了我們一個(gè)判斷標(biāo)準(zhǔn)當(dāng)你加一個(gè)新工具、改一個(gè)新流程時(shí)需不需要?jiǎng)雍诵拇a如果需要說(shuō)明你的 Harness 還沒(méi)語(yǔ)言化到位。這個(gè)標(biāo)準(zhǔn)很樸素但特別管用。最后分享一個(gè)小技巧把每次工具調(diào)用的輸入輸出都落盤(pán)按任務(wù) ID 歸檔。出問(wèn)題時(shí)這份日志比任何調(diào)試工具都好使。我靠這個(gè)習(xí)慣定位過(guò)好幾次“模型看起來(lái)在胡說(shuō)”的問(wèn)題最后發(fā)現(xiàn)都是上游工具返回了臟數(shù)據(jù)。日志不騙人模型會(huì)。