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