Harness 在 AI 編程領(lǐng)域的熱度主要來自一個很直接的痛點大模型生成代碼速度快但直接搬運到項目里并不讓人放心。模型寫出的代碼可能語法正確但語義錯誤可能調(diào)用了不存在的接口可能隨手修改了不應(yīng)該動的配置文件也可能在同一個編譯錯誤上反復(fù)打轉(zhuǎn)。所謂 harness就是圍繞編碼模型搭建的一層工程化約束和控制層讓代碼生成過程可觀察、可驗證、可干預(yù)。這篇文章以“生成可控代碼”為主線討論幾類能落地的 harness 實踐并用一個最小項目說明從模型輸出到驗證反饋的閉合流程。Harness 并不是什么神秘工具。它在測試領(lǐng)域早就存在叫“測試夾具”作用是給被測對象提供穩(wěn)定的運行環(huán)境。到了 AI 編程場景里它的角色變成給模型一個明確任務(wù)、一組受限工具、一套驗證規(guī)則和一條失敗后的反饋回路。社區(qū)里常見的做法是把 DeepSeek、Codex 這類編碼能力較強的模型接入本地工具鏈時不直接執(zhí)行模型輸出而是先套一層 harness讓模型在約束好的工作區(qū)里生成、修改、驗證代碼。這樣做的目的只有一個讓 AI 生成代碼的過程像人工開發(fā)一樣有任務(wù)單、有規(guī)范、有測試、有審查而不是把一段模糊輸出直接當成交付物。下面從概念、控制維度、可落地實踐、最小示例、參數(shù)調(diào)優(yōu)、效果評估、常見問題和生產(chǎn)建議幾個方向展開。1. 先搞清楚Harness 到底給編碼模型加了一層什么1.1 從“模型直接輸出”到“模型在框架內(nèi)行動”沒有 harness 時使用模型的典型流程是開發(fā)者把需求發(fā)給模型模型返回一段代碼開發(fā)者復(fù)制到項目里手動編譯、測試、修改。這個過程有兩個問題。第一模型只負責生成不負責驗證驗證責任全部落在人身上。第二如果生成的代碼有問題開發(fā)者需要手動把報錯信息重新喂給模型多輪往復(fù)效率低且容易遺漏上下文。有了 harness 之后流程變成開發(fā)者只定義任務(wù)和驗收條件harness 負責調(diào)用模型、接收輸出、執(zhí)行靜態(tài)檢查、運行測試、收集失敗信息并把失敗信息重新作為上下文發(fā)送給模型進行修復(fù)。整個過程被縮小到一個受控的執(zhí)行循環(huán)里。模型不再直接接觸真實項目目錄而是先在一個臨時工作區(qū)或受限目錄中完成任務(wù)只有通過全部驗證后diff 才會被提交到項目。這個轉(zhuǎn)變的本質(zhì)是“責任轉(zhuǎn)移”。代碼是否正確不再依賴模型一次性輸出得對不對而是依賴驗證器是否覆蓋了關(guān)鍵問題。模型可以犯錯但只要驗證器能發(fā)現(xiàn)錯誤并且錯誤信息能有效地回到模型側(cè)修復(fù)循環(huán)就可以收斂。Harness 解決的不是“模型能不能寫對代碼”而是“模型寫錯了能不能被及時攔住、及時修掉”。1.2 Harness 與 Agent 不是一回事很多人在實際項目里把 Harness 和 Agent 混在一起導(dǎo)致設(shè)計上出現(xiàn)偏差。Agent 強調(diào)的是自主決策模型可以根據(jù)目標自行規(guī)劃步驟、調(diào)用工具、觀察結(jié)果。Harness 強調(diào)的則是約束和管控它定義模型能做什么、不能做什么、做到什么程度算通過。兩者的關(guān)系可以這樣理解Harness 是 Agent 的“外殼 管理方”。一個 Agent 可以在 Harness 內(nèi)部運行但它的每一步行動都要經(jīng)過 Harness 的校驗。模型認為自己有權(quán)限修改某個文件不等于它真的能修改Harness 會在文件系統(tǒng)層面對路徑進行攔截。模型認為自己已經(jīng)完成任務(wù)也不等于任務(wù)真的完成Harness 會執(zhí)行測試套件來判斷。對比項HarnessAgent設(shè)計目標約束、驗證、可觀測自主規(guī)劃、執(zhí)行復(fù)雜任務(wù)控制方式白名單、規(guī)則、驗證器目標驅(qū)動、自我決策對錯誤的容忍錯誤必須被捕獲并反饋錯誤可能被吞掉或繼續(xù)執(zhí)行核心產(chǎn)物可驗證、可審計的交付物完成目標的過程和結(jié)果典型關(guān)系管理 Agent 的運行邊界在 Harness 內(nèi)完成任務(wù)設(shè)計 harness 時不要把“讓模型更自主”當成目標。模型越自主越需要更強的邊界。一個只知道“寫代碼”的模型如果被賦予了任意執(zhí)行命令、任意訪問網(wǎng)絡(luò)的權(quán)限它可能在幾秒內(nèi)做出超出預(yù)期的事?？煽氐膬?yōu)先級永遠高于智能。1.3 可控代碼要控制的其實是四個環(huán)節(jié)可控制代碼不是一個靜態(tài)概念它分布在生成鏈路的四個環(huán)節(jié)里。輸入環(huán)節(jié)要控制的是任務(wù)描述是否清晰、上下文是否完整、規(guī)則是否被模型看到。生成環(huán)節(jié)要控制的是模型參數(shù)的隨機性、輸出格式的合法性、生成結(jié)果是否被截斷。執(zhí)行環(huán)節(jié)要控制的是模型能否運行代碼、能訪問哪些路徑、能調(diào)用哪些外部命令。驗證環(huán)節(jié)要控制的是編譯是否通過、測試是否通過、代碼風格是否符合項目規(guī)范、是否存在明顯安全隱患。這四個環(huán)節(jié)缺一個都會出現(xiàn)“看起來能跑但一進項目就出事”的情況。很多團隊接了大模型寫代碼只做了生成環(huán)節(jié)的控制比如調(diào)低溫度、限制輸出長度卻忽略執(zhí)行環(huán)節(jié)和驗證環(huán)節(jié)結(jié)果模型生成的代碼破壞了本地環(huán)境或帶上了不安全依賴。一個完整的 harness 至少要把這四個環(huán)節(jié)串起來輸入有模板生成有格式約束執(zhí)行有沙箱驗證有測試。下面一節(jié)逐個展開。2. 生成可控代碼的五個控制維度2.1 輸入控制任務(wù)模板和上下文裁剪模型對輸入非常敏感。同一個需求用一句話描述和用結(jié)構(gòu)化的任務(wù)單描述輸出質(zhì)量差別很大。輸入控制的核心是兩件事一是把任務(wù)描述標準化二是把上下文裁剪到模型能有效處理的長度。任務(wù)模板的作用是固定輸入結(jié)構(gòu)。模板里至少應(yīng)該包含任務(wù)目標、輸入輸出約定、技術(shù)棧約束、禁止事項、驗收條件。模板不是限制開發(fā)者的表達而是讓模型每次都收到同樣完整的信息避免模型因為缺少關(guān)鍵約束而自由發(fā)揮。任務(wù)目標 用 Python 實現(xiàn)一個函數(shù)輸入為整數(shù) n返回第 n 個斐波那契數(shù)。 技術(shù)棧約束 - Python 3.10 - 只允許標準庫 - 禁止使用遞歸方式 輸出格式 必須輸出 JSON包含 code、explanation、tests 三個字段。 驗收條件 - 代碼通過 pylint 檢查 - 測試文件通過 pytest - 函數(shù)能正確處理 n0 和 n1上下文裁剪同樣重要。把整個倉庫的代碼都塞進 prompt模型往往記不住早期內(nèi)容還可能被無關(guān)文件干擾。常見做法是只把與任務(wù)相關(guān)的文件內(nèi)容、函數(shù)簽名、測試用例放進去。如果模型支持檢索增強可以按相似度召回相關(guān)代碼而不是無腦拼截上下文。2.2 工具控制白名單而不是自由發(fā)揮模型在生成代碼過程中如果需要修改文件、執(zhí)行命令、運行測試harness 必須明確告訴它可以用哪些工具。工具控制的基本原則是“默認拒絕白名單放行”。一個最小工具白名單配置可以這樣設(shè)計{ allowed_tools: [ read_file, write_file, list_dir, run_command ], allowed_read_paths: [ ./src, ./tests, ./requirements.txt ], allowed_write_paths: [ ./src, ./tests ], allowed_commands: [ python, pytest, pylint, pip install ] }這里的邏輯不是告訴模型“你可以做什么”而是告訴 harness“模型只能做這些”。模型在 prompt 里可能說要刪除某個目錄harness 在執(zhí)行層直接拒絕因為刪除操作不在白名單內(nèi)。把權(quán)限控制放在 harness 端而不是模型端這是很多失敗實踐的最重要分界線。永遠不要依賴模型自己判斷“這個文件該不該改”。2.3 執(zhí)行控制沙箱、超時和資源限制即使有了工具白名單也建議把代碼執(zhí)行放到沙箱里。原因是模型生成的代碼可能有難以預(yù)料的副作用占用大量內(nèi)存、開啟網(wǎng)絡(luò)連接、修改全局配置。如果直接在開發(fā)機上執(zhí)行清理成本非常高。常見的沙箱方案是 Docker 容器。把項目目錄掛載進容器限制網(wǎng)絡(luò)訪問設(shè)置 CPU 和內(nèi)存上限執(zhí)行完自動銷毀容器。這樣即使模型生成的代碼有問題影響范圍也被限制在容器內(nèi)。docker run --rm \ -v $(pwd)/workspace:/workspace \ -w /workspace \ --network none \ --memory 512m \ --cpus 1 \ --tmpfs /tmp:rw,noexec,nosuid,size128m \ python:3.11-slim \ bash -c pip install -r requirements.txt pytest tests/ -x這條命令里的關(guān)鍵參數(shù)每一個都有意義。--network none禁止容器訪問網(wǎng)絡(luò)防止模型生成的代碼下載惡意依賴或外發(fā)數(shù)據(jù)。--memory 512m限制內(nèi)存占用避免死循環(huán)代碼拖垮宿主機。--cpus 1限制 CPU 使用。--rm保證任務(wù)結(jié)束后容器自動刪除。--tmpfs把臨時目錄放到內(nèi)存且不允許執(zhí)行文件降低寫入入侵風險。學(xué)習環(huán)境為了簡單可以直接在本地執(zhí)行但至少要使用臨時目錄。生產(chǎn)環(huán)境如果接受不了容器方案也要用操作系統(tǒng)級別的用戶隔離和目錄權(quán)限來做執(zhí)行控制。2.4 驗證控制編譯、靜態(tài)檢查、測試三道關(guān)卡驗證器是 harness 的裁判。沒有驗證器模型說“寫完了”你無法判斷真假。驗證器應(yīng)該分層設(shè)計每一層解決一類問題。第一層是結(jié)構(gòu)驗證。檢查模型輸出是否符合約定的 JSON 格式、字段是否齊全、代碼是否能夠被解析。這一層可以過濾掉大量格式錯誤。第二層是靜態(tài)檢查。包括編譯、代碼風格檢查、靜態(tài)類型檢查。Python 項目可以用python -m compileall、pylint、mypyJavaScript 項目可以用tsc --noEmit、eslint。靜態(tài)檢查能發(fā)現(xiàn)語法錯誤、未使用變量、類型不匹配等問題執(zhí)行速度快非常適合作為第一道自動化關(guān)卡。第三層是測試執(zhí)行。運行項目的單元測試和集成測試驗證代碼行為是否符合預(yù)期。測試是判斷代碼是否“真的正確”的最可靠手段。如果項目測試覆蓋不足harness 的可靠程度也會下降。#!/usr/bin/env bash set -e echo 1. 結(jié)構(gòu)驗證 python validate_schema.py generated_output.json echo 2. 靜態(tài)檢查 cd workspace python -m compileall src/ pylint src/ --errors-only mypy src/ --ignore-missing-imports echo 3. 測試執(zhí)行 pytest tests/ -x --timeout30這三層驗證的執(zhí)行順序不能亂。先做結(jié)構(gòu)驗證再做靜態(tài)檢查最后才跑測試。如果結(jié)構(gòu)不對后面的檢查都沒有意義如果靜態(tài)檢查沒過測試大概率也過不了。每一層失敗后harness 都要收集失敗信息返回給模型進行下一輪修復(fù)。2.5 修復(fù)控制有限輪次的失敗反饋閉環(huán)模型第一次生成代碼很可能無法通過全部驗證這很正常。Harness 的價值在于把失敗反饋給模型讓模型有機會修正。但修復(fù)不能無限進行否則可能陷入死循環(huán)既浪費 token 又消耗時間。所以修復(fù)控制要有一個明確參數(shù)最大修復(fù)輪次。比如max_attempts 3意味著模型最多生成三次三次都失敗就停止交給人工處理。def run_harness(task, max_attempts3): for attempt in range(1, max_attempts 1): prompt build_prompt(task, previous_feedback) output call_model(prompt) result validate_and_test(output) if result.passed: return result previous_feedback result.feedback print(f第 {attempt} 次修復(fù)失敗原因{result.summary}) raise HarnessTimeout(超過最大修復(fù)輪次需要人工介入)這里的關(guān)鍵是previous_feedback。反饋信息必須簡潔、結(jié)構(gòu)化、可操作。直接把兩萬行 pytest 輸出全部塞給模型模型反而不知道問題在哪。推薦的做法是保留錯誤類型、出錯文件、出錯行號、錯誤摘要以及最近的失敗斷言上下文。反饋質(zhì)量直接決定修復(fù)能不能收斂。3. 五類可落地的 Harness 實踐3.1 最小命令行 Harness把模型調(diào)用封裝成校驗流程最簡單的一類 harness 適合個人開發(fā)者或?qū)W習場景用腳本封裝“調(diào)用模型 - 生成文件 - 執(zhí)行檢查”的流程。它不涉及復(fù)雜的工作區(qū)權(quán)限控制也不依賴容器重點是把驗證動作自動化。下面是一個最小 Python 示例的結(jié)構(gòu)。call_model函數(shù)在實際項目中可以替換為任何模型的接口調(diào)用比如 OpenAI 兼容接口或本地模型服務(wù)。import json import subprocess import sys def call_model(prompt): # 實際項目替換為具體模型接口 # response client.chat.completions.create(...) # return response.choices[0].message.content return {} def generate(task: str) - dict: prompt_template 任務(wù)目標 {task} 輸出格式 只輸出 JSON不要輸出解釋性文字。 JSON 必須包含 code、explanation、tests 三個字段。 raw call_model(prompt_template.format(tasktask)) return json.loads(raw) def run_checks(payload: dict): with open(workspace/solution.py, w) as f: f.write(payload[code]) result subprocess.run( [pytest, workspace/, -x, --timeout30], capture_outputTrue, textTrue ) return result.returncode 0, result.stdout[-2000:] if __name__ __main__: task sys.argv[1] payload generate(task) passed, feedback run_checks(payload) print(PASSED if passed else feedback)這段代碼的核心是“把驗證動作從人工命令變成程序行為”。以后要調(diào)整檢查項只需要改run_checks里的命令。要接入新的模型只需要替換call_model。最小 harness 的重點不是功能全面而是把生成到驗證的鏈路建立起來形成閉環(huán)。3.2 工作區(qū) Harness限制模型能改哪些文件第二個層級是工作區(qū)控制。當任務(wù)涉及多個文件模型需要讀寫項目代碼時僅靠 prompt 約束不夠。Harness 需要在文件系統(tǒng)層面強制執(zhí)行路徑白名單。一個可落地的思路是對所有文件操作做一層代理。模型不直接調(diào)用系統(tǒng) API而是統(tǒng)一調(diào)用 harness 提供的read_file、write_file接口。每個接口在真正執(zhí)行前都要檢查請求路徑是否在白名單內(nèi)。ALLOWED_WRITE_PATHS { /workspace/src, /workspace/tests, } ALLOWED_READ_PATHS ALLOWED_WRITE_PATHS | { /workspace/README.md, /workspace/requirements.txt, } def safe_write(path: str, content: str): normalized str(Path(path).resolve()) if not any(normalized.startswith(p) for p in ALLOWED_WRITE_PATHS): raise PermissionError(f禁止寫入路徑: {path}) with open(normalized, w, encodingutf-8) as f: f.write(content)這種設(shè)計的優(yōu)點是把權(quán)限判斷從“模型的自我約束”變成“harness 的執(zhí)行的強制約束”。即使模型在 prompt 里被誘導(dǎo)去修改config/app.conf只要路徑不在白名單內(nèi)操作就會拋錯。工作區(qū) harness 特別適合讓模型修改一個已有項目的多個文件同時保護敏感配置不被覆蓋。3.3 容器沙箱 Harness把依賴和副作用隔離起來當生成代碼需要安裝依賴、運行真實服務(wù)、連接數(shù)據(jù)庫時本地工作區(qū)已經(jīng)不夠安全。這時候需要把整個環(huán)境裝進容器做到“依賴隔離 副作用隔離”。容器沙箱 harness 的典型流程是生成代碼并寫入臨時目錄構(gòu)建一個包含項目依賴的鏡像啟動容器掛載臨時目錄執(zhí)行驗證命令結(jié)束后銷毀容器。這個流程適合集成到 CI 流水線中每次代碼生成都在干凈環(huán)境里驗證。#!/usr/bin/env bash set -e TARGET_DIR$(mktemp -d) # 生成代碼并寫入 TARGET_DIR python generate_and_write.py $TARGET_DIR # 使用項目 Dockerfile 構(gòu)建沙箱鏡像 docker build -t code-harness-sandbox . # 執(zhí)行驗證 docker run --rm \ -v $TARGET_DIR:/app \ -w /app \ --network none \ --memory 1g \ --cpus 2 \ code-harness-sandbox \ bash -c pytest tests/ -x pylint src/容器方案的權(quán)衡是構(gòu)建速度和隔離程度。每次構(gòu)建鏡像可能耗時較長所以一般把依賴安裝分成兩層基礎(chǔ)依賴放在鏡像構(gòu)建階段項目代碼用掛載卷注入。這樣代碼變化不需要重新構(gòu)建依賴層。生產(chǎn)環(huán)境可以在鏡像倉庫里緩存基礎(chǔ)鏡像把 build 時間控制在可接受范圍內(nèi)。3.4 測試驅(qū)動反饋 Harness讓失敗信息回到下一輪 prompt沒有反饋的驗證沒有意義。測試驅(qū)動反饋 harness 的核心是把 pytest、eslint 等工具的輸出轉(zhuǎn)換成模型能理解的修復(fù)指令。一個常見錯誤是直接把原始測試輸出全文喂給模型。原始輸出包含大量路徑、堆棧、無關(guān)警告模型很容易被干擾。正確做法是先結(jié)構(gòu)化摘要哪條測試失敗、失敗類型是什么、期望值是什么、實際值是什么、關(guān)鍵堆棧在哪幾行。上一輪結(jié)果 [1/3] test_fibonacci_value_0 - 失敗 原因: assert fib(0) 0 實際: fib(0) 拋出了 IndexError 關(guān)鍵信息: 函數(shù)在 n0 時訪問了 fib[-1] 請在不改變函數(shù)簽名的情況下修復(fù)確保測試通過。這段反饋里包含了失敗的測試名、斷言、實際表現(xiàn)和關(guān)鍵線索。模型看到之后可以快速定位到邊界條件處理缺失的問題。這樣的反饋比“你的代碼沒有通過測試”有效得多。修復(fù)循環(huán)是否收斂很大程度上取決于反饋的信息密度。3.5 多 Agent 評審 Harness生成和審查分離更高一層的可控性來自“讓另一個模型審查生成結(jié)果”。生成 agent 負責實現(xiàn)功能審查 agent 負責挑錯。兩者角色分離能減少生成 agent 自說自話的風險。多 agent 評審的流程并不復(fù)雜。先生成代碼并運行基礎(chǔ)測試再把代碼、任務(wù)描述、測試結(jié)果一起交給審查 agent。審查 agent 不直接修改代碼只輸出審查意見包括正確性問題、邊界條件、安全問題、可讀性問題。生成 agent 根據(jù)意見修改第二輪再交給審查 agent 復(fù)核。這種方案的代價是 token 消耗增加延遲變高所以不適合每個小任務(wù)都使用。比較適合高風險代碼例如數(shù)據(jù)庫遷移、權(quán)限相關(guān)邏輯、支付金額計算、外部系統(tǒng)接口對接。評審 agent 的 prompt 也要單獨設(shè)計不能簡單復(fù)用生成 agent 的模板。審查時更看重“找問題”而不是“寫代碼”。4. 從零搭建一個最小可運行的 Harness 示例4.1 項目結(jié)構(gòu)和運行環(huán)境下面用一個完整的 Python 小項目演示 harness 如何串起“生成 - 驗證 - 修復(fù)”的閉環(huán)。項目結(jié)構(gòu)如下harness-demo/ ├── runner.py ├── validator.py ├── prompt_builder.py ├── model_client.py └── workspace/ └── tests/ └── test_solution.py運行環(huán)境建議 Python 3.10 以上安裝pytest、pylint。如果本地沒有可用的模型接口可以把model_client.py里的模型調(diào)用替換成模擬函數(shù)先跑通整個 harness 流程再接入真實模型。pip install pytest pylint這里要說明一點真實項目里模型接口地址、API Key、模型名稱都應(yīng)通過環(huán)境變量注入而不是硬編碼在代碼里。學(xué)習環(huán)境為了減少配置成本可以先寫在配置文件中但進入生產(chǎn)環(huán)境前必須外置化。4.2 任務(wù)模板和輸出 JSON 約束prompt_builder.py負責把“任務(wù) 修復(fù)反饋”組裝成模型輸入。關(guān)鍵點是要求模型只能輸出 JSON方便后續(xù)程序解析。def build_prompt(task: str, feedback: str | None None) - str: feedback_section if feedback: feedback_section f 上一輪驗證失敗請根據(jù)以下反饋修復(fù)代碼 {feedback} return f 任務(wù)目標 {task} 約束 - 語言Python 3.10 - 只允許使用標準庫 - 不要修改測試文件 - 函數(shù)簽名必須保持為 fib(n) 輸出要求 只輸出一個 JSON 對象不要輸出任何解釋文字。 JSON 結(jié)構(gòu)如下 {{ code: 完整的 Python 代碼, tests: 針對該函數(shù)的 pytest 測試代碼, explanation: 一句話說明實現(xiàn)思路 }} {feedback_section} 這里要求模型把代碼和測試一起輸出是為了讓閉環(huán)更完整。測試代碼雖然會覆蓋預(yù)置的test_solution.py但模型給出的測試可以作為額外參考。實際項目中建議測試由人編寫而不是模型編寫否則模型的錯誤思路會滲透到測試里。模型自測通過不等于功能正確只有獨立的測試套件才可信。4.3 驗證器鏈從 JSON 解析到測試執(zhí)行validator.py負責執(zhí)行驗證。它的輸入是模型原始輸出輸出是一個驗證結(jié)果對象包含是否通過、失敗原因、完整反饋。import json import subprocess import tempfile from pathlib import Path class ValidationResult: def __init__(self, passed: bool, feedback: str): self.passed passed self.feedback feedback def validate(raw_output: str, workspace: Path) - ValidationResult: try: payload json.loads(raw_output) except json.JSONDecodeError as e: return ValidationResult(False, f模型輸出不是合法 JSON{e}) if not all(k in payload for k in (code, explanation)): return ValidationResult(False, JSON 缺少 code 或 explanation 字段) src_dir workspace / src src_dir.mkdir(exist_okTrue) (src_dir / solution.py).write_text(payload[code], encodingutf-8) compile_result subprocess.run( [python, -m, compileall, str(src_dir)], capture_outputTrue, textTrue ) if compile_result.returncode ! 0: return ValidationResult(False, f編譯失敗{compile_result.stderr[-1500:]}) pytest_result subprocess.run( [pytest, str(workspace / tests), -x, --timeout30], capture_outputTrue, textTrue ) if pytest_result.returncode ! 0: return ValidationResult(False, pytest_result.stderr[-2000:] or pytest_result.stdout[-2000:]) return ValidationResult(True, 所有驗證通過)注意驗證器里使用了compileall作為第一道檢查。它的執(zhí)行速度比 pytest 快很多能在測試前就發(fā)現(xiàn)語法錯誤。如果編譯失敗就沒有必要跑測試節(jié)省時間。這個順序體現(xiàn)在代碼里就是先編譯、后測試。tempfile在代碼里導(dǎo)入但未使用真實項目中應(yīng)使用臨時目錄管理輸出文件避免污染工作區(qū)。下面示例簡化了路徑管理實際生產(chǎn)代碼要清理臨時文件。4.4 修復(fù)循環(huán)把失敗反饋送回模型runner.py是整個 harness 的主入口。它定義最大修復(fù)輪次循環(huán)調(diào)用模型、驗證、反饋。import sys from pathlib import Path from model_client import call_model from prompt_builder import build_prompt from validator import validate def run(task: str, max_attempts: int 3): workspace Path(workspace).resolve() feedback None for attempt in range(1, max_attempts 1): print(f--- 第 {attempt} 輪 ---) prompt build_prompt(task, feedback) raw_output call_model(prompt) result validate(raw_output, workspace) if result.passed: print(驗證通過) return print(f驗證失敗{result.feedback[:200]}) feedback result.feedback print(f連續(xù) {max_attempts} 輪失敗自動停止請人工介入。) sys.exit(1) if __name__ __main__: run(實現(xiàn) fib(n)返回第 n 個斐波那契數(shù)n 為自然數(shù)要求處理 n0 和 n1 的邊界。)修復(fù)循環(huán)有一個容易忽略的細節(jié)失敗反饋不能無限累積。如果每一輪都把上一輪的完整輸出拼進去prompt 會越來越長模型反而抓不住重點。一般建議只保留最近一次失敗反饋或?qū)Χ噍喎答佔稣獕嚎s?？梢栽赽uild_prompt里只保留feedback字段也就是最近一輪的驗證結(jié)果。4.5 跑通流程后的預(yù)期結(jié)果如果接入了真實模型正常流程會看到類似這樣的輸出--- 第 1 輪 --- 驗證失敗test_fibonacci_value_0 失敗fib(0) 拋出了 IndexError --- 第 2 輪 --- 驗證失敗test_fibonacci_value_1 失敗fib(1) 返回 1期望 0 --- 第 3 輪 --- 驗證通過如果沒有接入模型可以先寫一個模擬的call_model讓它在第一輪返回固定 JSON用來測試 validator 和 runner 的邏輯是否正常。這也是一個很好的工程習慣在模型接入前先把 harness 自身鏈路驗證好。def call_model(prompt: str) - str: return json.dumps({ code: def fib(n):\n if n 0:\n return 0\n if n 1:\n return 1\n return fib(n - 1) fib(n - 2), tests: def test_fib():\n assert fib(0) 0\n assert fib(1) 1, explanation: 使用遞歸實現(xiàn)但實際生產(chǎn)需要處理性能問題 })模擬模型的目的不是驗證模型能力而是驗證 harness 的 JSON 解析、文件寫入、命令執(zhí)行、結(jié)果判斷是否正常。等 harness 鏈路穩(wěn)定后再替換成真實模型接口排查范圍會小很多。5. 關(guān)鍵參數(shù)怎么調(diào)調(diào)錯了會有什么表現(xiàn)5.1 模型側(cè)參數(shù)溫度、采樣和輸出長度模型側(cè)參數(shù)直接影響生成結(jié)果的可控性。下面是三個最常調(diào)整的參數(shù)。參數(shù)說明推薦值代碼生成場景調(diào)大影響調(diào)小影響temperature控制隨機性0 到 0.3更容易出現(xiàn)不常見寫法也更容易出錯輸出更穩(wěn)定、更保守top_p核采樣控制候選詞集合0.9 到 1.0多樣性增加確定性增加max_tokens控制最大輸出長度按任務(wù)預(yù)估留 20% 余量可能輸出無關(guān)內(nèi)容代碼容易被截斷代碼生成場景建議把 temperature 調(diào)到接近 0。原因不是溫度越低越聰明而是代碼對確定性要求高。同樣的需求模型如果每次輸出不同實現(xiàn)驗證成本會顯著增加。低溫度可以保證在同樣輸入下輸出基本穩(wěn)定便于復(fù)現(xiàn)和排除問題。max_tokens這個參數(shù)在 harness 里尤其重要。如果設(shè)置過小生成的代碼會被強行截斷validator 會報 JSON 解析錯誤。如果設(shè)置過大模型可能輸出大量無關(guān)解釋浪費 token。一個通用估算方法是按任務(wù)文件中可能出現(xiàn)的代碼行數(shù)乘以每行約 10 到 15 個 token再加上 500 token 余量。5.2 Harness 控制參數(shù)harness 自身的參數(shù)比模型參數(shù)更影響可控性。這些參數(shù)通常集中在配置文件里而不是散落在代碼中。參數(shù)默認值參考含義設(shè)置過大的表現(xiàn)設(shè)置過小的表現(xiàn)max_attempts3最大生成修復(fù)輪數(shù)長時間無效循環(huán)成本上升模型來不及修復(fù)可修復(fù)的錯誤timeout_seconds60單輪驗證超時卡在死循環(huán)或慢測試中正常測試被誤殺enabled_checkscompile, lint, test啟用的驗證器驗證過嚴影響通過率漏掉關(guān)鍵錯誤allowed_write_paths按項目配置允許寫入的目錄模型可能改到敏感配置模型無法完成多文件任務(wù)max_attempts是最容易調(diào)錯的一個參數(shù)。設(shè)成 1 等于不讓模型修復(fù)設(shè)成 10 又可能讓模型在錯誤方向上反復(fù)消耗。建議從 3 開始觀察平均修復(fù)成功輪次后再調(diào)整。如果大部分成功任務(wù)都在第 2 輪修復(fù)成功而第 3 輪幾乎不產(chǎn)生新進展就把最大值調(diào)回 3如果第 3 輪仍頻繁成功可以提高到 5。timeout_seconds也需要按驗證器的耗時單獨設(shè)置。編譯檢查通常幾秒內(nèi)完成pytest 時間取決于測試規(guī)模集成測試可能需要幾分鐘。不要讓一個統(tǒng)一超時同時約束所有驗證器。更合理的做法是每個驗證器都有單獨的超時配置。5.3 安全邊界和資源限制參數(shù)安全參數(shù)是生產(chǎn)環(huán)境不能省的。下面是一組必須顯式配置的安全約束。security: forbidden_commands: - rm -rf - shutdown - sudo - curl - wget forbidden_packages: - subprocess - os.system max_output_size: 204800 max_runtime_seconds: 300 enable_network: false enable_audit_log: true api_keys_in_prompt: false這里的forbidden_commands和forbidden_packages是針對模型生成內(nèi)容的靜態(tài)過濾不能替代沙箱隔離但可以作為前端過濾。api_keys_in_prompt控制的是組裝 prompt 時是否允許把 API Key、數(shù)據(jù)庫連接串等敏感信息傳給模型。默認應(yīng)該是 false。任何情況下都不應(yīng)該把生產(chǎn)密鑰放進模型上下文因為模型輸出可能被記錄到日志、發(fā)送到外部服務(wù)或在不經(jīng)意間被寫入代碼文件。6. 如何驗證 Harness 真的讓代碼變可控了6.1 用通過率、輪次、越權(quán)次數(shù)三個指標評估搭建完 harness 后需要用數(shù)據(jù)判斷它是否真的有效。三個核心指標值得長期記錄。指標含義怎么統(tǒng)計信號解讀首輪通過率不經(jīng)過修復(fù)第一次生成就通過驗證通過的樣本數(shù) / 總樣本數(shù)越高說明任務(wù)模板和上下文越有效平均修復(fù)輪次從首次失敗到最終通過的輪次數(shù)所有成功樣本的輪次均值平均值越低反饋信息越有效越權(quán)次數(shù)模型嘗試訪問白名單外路徑或命令的次數(shù)harness 攔截器日志計數(shù)數(shù)值高說明 prompt 約束或工具邊界需要加強建議準備一個 20 到 50 個任務(wù)的評測集任務(wù)從簡單到復(fù)雜分布。用相同的 harness 配置跑一遍記錄通過、失敗、越權(quán)和輪次。這個評測集的價值不只是驗證當前 harness 狀態(tài)它還能在更換模型版本、修改 prompt 模板時做回歸對比避免“某次改動讓整體效果變差”卻沒人發(fā)現(xiàn)。{ task_id: task_023, model: 模型標識, attempts: 2, passed: true, violation_count: 1, first_pass: false, duration_seconds: 45 }這類結(jié)構(gòu)化記錄可以累積成 CSV 或 JSONL后續(xù)用腳本統(tǒng)計。沒有數(shù)據(jù)的 harness 優(yōu)化都是憑感覺有了數(shù)據(jù)才知道該調(diào)參數(shù)還是該改 prompt。6.2 有 Harness 和無 Harness 的關(guān)鍵差異有 harness 和沒有 harness使用模型的方式完全不同?？梢杂靡粡埍碚f明差異。場景無 Harness 的典型行為有 Harness 的典型行為代碼錯誤人工復(fù)制代碼、手動運行、手動復(fù)制報錯自動執(zhí)行驗證器失敗信息結(jié)構(gòu)化回流文件修改模型建議人工確認容易遺漏路徑白名單強制執(zhí)行越權(quán)直接攔截測試運行依賴人工執(zhí)行時常跳過作為驗證關(guān)卡自動執(zhí)行失敗處理模型可能重復(fù)同樣的錯誤有限修復(fù)輪次內(nèi)自動修正超限則介入審計幾乎沒有記錄模型請求、工具調(diào)用、驗證結(jié)果全部留痕這些差異不需要等到生產(chǎn)環(huán)境才會體現(xiàn)。即使是個人項目把 harness 腳本固定下來之后每次讓模型生成代碼都走同一套驗證流程長期積累節(jié)省的時間非?？捎^。最明顯的收益是“模型生成錯誤代碼”時修復(fù)路徑從“人來復(fù)述問題”變成“harness 自動把問題上下文帶回給模型”。6.3 日志審計讓每次生成和修復(fù)都可回溯日志是 harness 的“黑匣子”。生產(chǎn)環(huán)境的模型調(diào)用必須可審計。每條日志至少應(yīng)該包含四個部分模型輸入的摘要、模型輸出的摘要、驗證器的執(zhí)行結(jié)果、harness 自身的決策。{ timestamp: 2026-08-22T10:15:33Z, task: 實現(xiàn) fib(n), prompt_hash: abc123, model_output_hash: def456, validator: { compile: pass, pytest: fail, summary: test_fibonacci_value_0 失敗 }, decision: feedback_to_model, token_count: 1234, duration_ms: 25400 }這里不建議把完整 prompt 和完整輸出都直接寫入日志因為可能包含敏感信息。更穩(wěn)妥的做法是記錄哈希值原始內(nèi)容存入獨立的、權(quán)限受限的存儲里只有排查問題時才讀取。日志的保留策略也要提前定義尤其是涉及代碼生成的項目審計數(shù)據(jù)可能需要保留較長周期。7. 常見問題排查從現(xiàn)象倒推根因7.1 模型不按約定輸出 JSON現(xiàn)象模型輸出里混入了 Markdown 代碼塊、解釋文字或多余字段導(dǎo)致 validator 在json.loads階段直接失敗?？赡茉蚰Ｐ陀?xùn)練數(shù)據(jù)里代碼類問題的回答習慣是包裹在 Markdown 代碼塊中。prompt 雖然要求“只輸出 JSON”但模型的輸出格式偏好可能覆蓋指令。檢查方式把模型原始輸出保存下來查看是否帶有json或“好的我將為你實現(xiàn)”這類前綴。解決方式在 validator 里先做一次凈化。如果原始輸出包含 Markdown 代碼塊提取其中的 JSON 內(nèi)容如果包含說明文字嘗試從第一個{截取到最后一個}。更根本的解決方法是把輸出格式約束放到 prompt 的開頭并且提供 in-context example。import re def extract_json(raw: str) - str: start raw.find({) end raw.rfind(}) if start -1 or end -1 or end start: raise ValueError(未找到 JSON 內(nèi)容) return raw[start:end 1]這種凈化方案不能作為偷懶的借口。它只是提高容錯性真正解決問題的仍然是要讓模型理解“輸出 JSON 是硬約束不是建議”。7.2 修復(fù)循環(huán)不收斂同一個錯誤反復(fù)出現(xiàn)現(xiàn)象模型在上一輪已經(jīng)看到fib(0)導(dǎo)致IndexError的反饋但新一輪代碼仍然沒有處理n0?？赡茉蛴腥齻€。第一反饋信息太弱模型沒有理解錯誤根因。第二prompt 中任務(wù)約束被后續(xù)文字覆蓋模型只記住了最新內(nèi)容。第三溫度設(shè)置過高模型每次都換一種實現(xiàn)方式?jīng)]有針對反饋做局部修復(fù)。檢查方式查看上一輪反饋文本是否在下一輪 prompt 中出現(xiàn)確認模型是否真的讀到了反饋。然后對比相鄰兩輪的輸出 diff看模型是“局部修改”還是“全量重寫”。解決方式把反饋信息壓縮成明確指令例如“請在函數(shù)開頭增加 if n 0 的邊界判斷”。如果模型仍在全量重寫調(diào)低 temperature并在 prompt 中明確要求“基于上一輪代碼做最小修改不要重寫整個函數(shù)”。另外要設(shè)置硬性最大輪次超過后停止并交給人工避免無效消耗。7.3 模型嘗試修改白名單外的文件或執(zhí)行危險命令現(xiàn)象harness 日志里出現(xiàn) PermissionError模型試圖寫入config/database.yaml或嘗試執(zhí)行rm -rf?？赡茉蛉蝿?wù)描述里沒有明確禁止這些操作或者模型為了實現(xiàn)目標選擇了破壞性方案。檢查方式查看工具調(diào)用日志統(tǒng)計越權(quán)訪問集中在哪些路徑和命令。如果越權(quán)次數(shù)明顯升高說明 prompt 中的約束信息不夠醒目。解決方式第一層是加強 prompt在任務(wù)模板中增加“禁止修改的文件”和“禁止執(zhí)行的命令”。第二層是執(zhí)行層強制攔截路徑不在白名單內(nèi)直接拒絕。第三層是沙箱兜底即使前兩層被繞過容器內(nèi)也沒有重要文件可破壞。預(yù)防建議不要把所有希望寄托在 prompt 上。模型可能因為上下文過長或?qū)馆斎攵雎约s束執(zhí)行層的強制攔截才是可控性的底線。7.4 測試環(huán)境不穩(wěn)定導(dǎo)致驗證誤判現(xiàn)象某輪生成的代碼實際正確但 pytest 因為超時、依賴缺失、隨機失敗報了錯harness 把反饋發(fā)給模型后模型在錯誤方向上反復(fù)修改?？赡茉驕y試環(huán)境每次運行依賴系統(tǒng)狀態(tài)。比如測試用了真實網(wǎng)絡(luò)請求但網(wǎng)絡(luò)不穩(wěn)定或者測試依賴某個未被凍結(jié)版本的第三方庫同一段代碼在不同時間運行結(jié)果不同。檢查方式在 validator 中重復(fù)執(zhí)行同一段代碼兩次對比結(jié)果是否一致。檢查requirements.txt或pyproject.toml是否鎖定了所有依賴版本。查看 pytest 輸出是否出現(xiàn) timeout、connection error 等環(huán)境相關(guān)錯誤。解決方式固定依賴版本把測試環(huán)境換成 Docker 容器對網(wǎng)絡(luò)測試使用 mock 或本地測試服務(wù)。同時區(qū)分 flaky 測試和真實失敗可以在測試命令里標記--durations10或為已知 flaky 的用例單獨配置重試規(guī)則。避免模型因為環(huán)境問題而修改正確代碼。7.5 上下文過長導(dǎo)致規(guī)則被忽略現(xiàn)象prompt 里明明寫了“只允許使用標準庫”模型還是導(dǎo)入了numpy?？赡茉蚰Ｐ涂梢蕴幚淼纳舷挛拈L度有限。任務(wù)描述、倉庫代碼、歷史反饋全部累積后早期約束被后續(xù)內(nèi)容掩蓋模型只關(guān)注最近的指令。檢查方式打印發(fā)送給模型的完整 prompt查看約束語句在文本中的位置。如果出現(xiàn)在很長上下文的中部它被忽略的概率會明顯增加。解決方式把最重要的約束放在 prompt 開頭和結(jié)尾兩個位置中間放背景材料。減小裁剪粒度只保留與當前任務(wù)直接相關(guān)的代碼。歷史反饋只保留最近一輪或使用摘要。更徹底的做法是啟用模型服務(wù)端的系統(tǒng)提示詞把硬性規(guī)則放在 system message 里而不是隨任務(wù)內(nèi)容一起傳入。7.6 多 Agent 評審意見產(chǎn)生沖突現(xiàn)象生成 agent 和評審 agent 對某個問題的判斷不一致。生成 agent 認為代碼正確評審 agent 堅持要求修改兩輪之后任務(wù)無法收斂?？赡茉蛟u審 agent 的判別標準不夠具體它的判斷依賴自身主觀理解。尤其在沒有測試用例覆蓋的領(lǐng)域評審 agent 容易提出風格化、非必要的修改意見。檢查方式記錄評審 agent 輸出的意見類型判斷多少條屬于正確性問題多少條屬于風格問題。如果大多數(shù)是風格意見說明評審 prompt 需要更嚴格地限定“只報告會導(dǎo)致錯誤或安全隱患的問題”。解決方式給評審 agent 一個明確的等級分類。建議按嚴重級別輸出阻斷級別、重要級別、建議級別。只有前兩級需要生成 agent 修復(fù)建議級別直接忽略。這樣能減少意見沖突導(dǎo)致的循環(huán)。8. 生產(chǎn)環(huán)境落地的檢查清單和擴展方向8.1 學(xué)習環(huán)境與生產(chǎn)環(huán)境的差異學(xué)習環(huán)境里跑通一個 harness 只需要幾分鐘但生產(chǎn)環(huán)境落地時要考慮的問題會多很多。下面這張表列出最常見的差異。維度學(xué)習環(huán)境生產(chǎn)環(huán)境配置硬編碼在代碼里配置外置化通過環(huán)境變量或配置中心注入模型 API本地模擬或測試賬號固定模型版本關(guān)注兼容性執(zhí)行環(huán)境本機目錄Docker 容器或獨立執(zhí)行機權(quán)限一個開發(fā)賬號獨立服務(wù)賬號最小權(quán)限日志打印到控制臺接入集中日志平臺設(shè)置保留周期監(jiān)控無通過率、失敗率、平均輪次、耗時指標回滾手動清理每個產(chǎn)物有唯一 ID記錄版本密鑰可能臨時寫在代碼里從環(huán)境變量讀取禁止進入 prompt 和日志學(xué)習環(huán)境的目的是快速看到效果可以容忍臨時配置。生產(chǎn)環(huán)境的目的是穩(wěn)定可維護必須從第一天就考慮可觀測性和權(quán)限控制。把一個學(xué)習用 harness 直接搬到生產(chǎn)環(huán)境最常見的后果是密鑰泄露、執(zhí)行片段污染宿主機、模型版本升級后結(jié)果波動卻無法定位原因。8.2 發(fā)布前檢查清單在把 harness 接入正式項目前可以按下面這份清單逐項確認。模型版本是否固定是否記錄了模型標識和 prompt 版本。max_attempts是否設(shè)置是否限制了總執(zhí)行時間和總 token 消耗。執(zhí)行環(huán)境是否隔離是否禁用了不必要的網(wǎng)絡(luò)權(quán)限。白名單路徑是否只覆蓋任務(wù)需要的目錄。敏感文件是否被排除在讀取白名單之外。測試套件是否獨立于模型生成內(nèi)容測試是否由可信人員維護。驗證器執(zhí)行是否有超時控制是否有序排列。失敗反饋是否結(jié)構(gòu)化是否只保留有效信息。日志是否記錄了任務(wù) ID、模型輸出哈希、驗證結(jié)果和最終決策。API Key 等敏感信息是否不進入 prompt、不寫入日志。是否有人工介入機制超限任務(wù)是否會被標記并推送。是否有評估集是否在修改 prompt 前后用同一套任務(wù)回歸。這份清單不需要一次性全部滿足。它可以作為從實驗到生產(chǎn)的驗收標準。每上線一個新場景先過一遍清單再開始引入模型生成流程能避免大量線上問題。8.3 可以繼續(xù)深入的方向Harness 實踐本身是一個可以持續(xù)擴展的方向。最直接的一個擴展是建立任務(wù)級評估集。把過去真實項目里的歷史問題整理成測試用例每次調(diào)整模型、prompt 或 harness 參數(shù)時都跑一遍評估集通過率變化一眼可見。第二個方向是將 harness 接入 CI/CD 流水線。當開發(fā)者提交一個“由模型修改的 PR”時流水線自動運行 harness 的全部驗證關(guān)卡包括編譯、靜態(tài)檢查、測試、安全掃描。這樣可以保證進入代碼評審階段的每個 PR 都已經(jīng)是經(jīng)過模型自驗和工具驗證的產(chǎn)物。第三個方向是讓反饋循環(huán)更智能。當前許多 harness 只是把測試失敗信息喂回給模型。更復(fù)雜的設(shè)計可以加入“問題定位器”先從堆棧中提取出錯文件、行號、符號名再結(jié)合語法樹分析給出更精確的修復(fù)建議。這種結(jié)構(gòu)化反饋能顯著減少模型盲目嘗試的次數(shù)。第四個方向是橫向?qū)Ρ炔煌Ｐ驮谕?harness 下的表現(xiàn)。同一個任務(wù)模板、同一套 validator、同一個評測集分別運行不同模型比較通過率、平均輪次、越權(quán)次數(shù)。這種對比可以為團隊選型提供量化依據(jù)而不是單純看演示效果。Harness 的核心價值不在于讓模型顯得更聰明而在于讓模型生成的代碼進入項目之前先經(jīng)過一條有約束、有驗證、有反饋、可回溯的生產(chǎn)線。把允許模型做什么、禁止模型做什么、怎樣算通過、怎樣算失敗、失敗后如何反饋寫成配置harness 才真正開始幫你控制代碼質(zhì)量而不是替你寫代碼。