建Agent Harness：拆解Claude Code的AI編程助手)
1. 先把“AI 編程助手”拆成一塊塊看得見的零件最近不少人問我既然 Claude Code 已經(jīng)這么強(qiáng)為什么還要花時(shí)間去“從零構(gòu)建一個(gè) Agent Harness”我的回答是把一個(gè)黑盒拆開再重裝一遍你對(duì)它的掌控會(huì)完全不同。文章標(biāo)題寫著“Learn Claude Code”但我想說的比單純學(xué)命令用法更深一層把 AI 編程助手當(dāng)成一個(gè)由好幾塊零件拼起來的系統(tǒng)然后親手寫出一個(gè)最小可運(yùn)行的 harness。Claude Code 本質(zhì)上并不“神秘”。當(dāng)你坐在終端前敲下一句“幫我把這個(gè)模塊的重試邏輯修一下”它背后發(fā)生的其實(shí)是一連串非常工程化的步驟先收集倉庫上下文再把任務(wù)和上下文一起交給模型模型輸出一個(gè)行動(dòng)意圖外圍框架負(fù)責(zé)執(zhí)行這個(gè)行動(dòng)然后把執(zhí)行結(jié)果再喂回模型如此循環(huán)直到模型認(rèn)為任務(wù)完成。真正決定體驗(yàn)高下的不是模型本身有多聰明而是這一圈循環(huán)做得是否穩(wěn)定、收斂、安全。這篇文章適合兩類人一是已經(jīng)在用 Claude Code但想知道“它到底是怎么做到的”的開發(fā)者二是想自己搭一套內(nèi)部 AI 編程工具卻不太清楚該從哪里動(dòng)手的人。我會(huì)按我實(shí)際搭建玩具項(xiàng)目的順序來講先講最小閉環(huán)再逐步補(bǔ)上權(quán)限、反饋、上下文管理這些零件。讀完之后你能自己寫出一個(gè)能讀文件、改文件、跑測(cè)試、然后根據(jù)測(cè)試結(jié)果自我修復(fù)的 agent 循環(huán)。1.1 把 Claude Code 的使用體驗(yàn)拆成四個(gè)組件我自己的拆解習(xí)慣是把一個(gè) AI 編程助手分成四塊任務(wù)注入用戶指令加上倉庫結(jié)構(gòu)、相關(guān)文件內(nèi)容被組裝成一段上下文。決策循環(huán)模型根據(jù)上下文決定下一步動(dòng)作可能是讀文件、寫文件、跑命令也可能是直接給出最終結(jié)論。工具集合一系列可供模型調(diào)用的函數(shù)比如讀文件、搜索文件、執(zhí)行 shell 命令。安全與反饋執(zhí)行前做權(quán)限判斷執(zhí)行后把退出碼、標(biāo)準(zhǔn)輸出等結(jié)果返回給模型。這四塊里面最容易被忽視的是第四塊。很多人以為只要把模型接到終端上它自然就能“編程”了其實(shí)不是。模型只是一個(gè)“思考者”一個(gè)行動(dòng)要被真正執(zhí)行需要經(jīng)過工具層和權(quán)限層的翻譯與約束。Claude Code 之所以比普通聊天機(jī)器人更適合編程就在于它的第四個(gè)組件做得足夠細(xì)致它會(huì)自動(dòng)跑測(cè)試會(huì)把錯(cuò)誤日志截短后再喂給模型也會(huì)在模型要執(zhí)行危險(xiǎn)命令時(shí)停下來問用戶。1.2 Agent Harness 到底是個(gè)什么東西Harness 在中文里可以叫“套具”或“腳手架”但我更愿意叫它“夾層邏輯”。它夾在模型和操作系統(tǒng)之間負(fù)責(zé)把模型的文本輸出翻譯成可執(zhí)行動(dòng)作再將動(dòng)作結(jié)果序列化回上下文。舉個(gè)例子模型告訴你“我想讀取 config.yaml”但這只是它輸出的一句話。Harness 要做的事情是從這句話里解析出工具名“read_file”、參數(shù)“config.yaml”找到對(duì)應(yīng)的函數(shù)把文件內(nèi)容讀出來然后以標(biāo)準(zhǔn)格式寫回模型的歷史消息。如果工具調(diào)用格式不對(duì)harness 還得負(fù)責(zé)返回一個(gè)錯(cuò)誤讓模型看到之后重新生成。這就是為什么我說模型不是主角流程才是主角。模型的輸出千變?nèi)f化一個(gè)合格的 harness 要做的就是把這些千變?nèi)f化收斂成可執(zhí)行的、可控的步驟。你可以把 harness 想象成一位嚴(yán)謹(jǐn)?shù)能囬g主任模型是技術(shù)顧問。技術(shù)顧問可以提出各種方案但最后擰螺絲、通電、質(zhì)檢的步驟都必須經(jīng)過車間主任的流程和審批。車間主任可以沒有顧問那么懂技術(shù)但他必須保證每個(gè)動(dòng)作都留下記錄、不會(huì)越界、也不會(huì)在同一個(gè)錯(cuò)誤上反復(fù)折騰。1.3 為什么“從零構(gòu)建”比“讀文檔”更有學(xué)習(xí)價(jià)值直接讀 Claude Code 的文檔你只會(huì)知道它能做什么比如“可以編輯文件”“可以并行運(yùn)行多個(gè)任務(wù)”。但你自己動(dòng)手寫一個(gè)最少 200 行左右的 harness 之后才會(huì)理解它為什么那樣設(shè)計(jì)。舉個(gè)我在搭玩具項(xiàng)目時(shí)反復(fù)遇到的例子模型偶爾會(huì)不按約定輸出結(jié)構(gòu)化的工具調(diào)用而是直接說一段話比如“我先讀取一下文件再?zèng)Q定怎么改”。如果 harness 不處理這種情況整個(gè)循環(huán)就斷了。好的做法是把自然語言和結(jié)構(gòu)化調(diào)用都解析一遍先嘗試嚴(yán)格解析失敗就退回模糊提取再失敗就把“當(dāng)前輸出無法理解”明確告訴模型。類似這樣的細(xì)節(jié)不親手寫一遍代碼是體會(huì)不到的。所以我后面幾個(gè)章節(jié)的內(nèi)容都是從一個(gè)能跑的玩具 harness 出發(fā)一步一步加零件。每一步我都會(huì)解釋“為什么需要這個(gè)部件”因?yàn)檫@才是從零構(gòu)建的真正價(jià)值不只是知道怎么拼而是知道為什么這么拼。2. 最小版 Harness 的核心一個(gè)能自己跑命令的循環(huán)先別急著加權(quán)限、加測(cè)試、加上下文壓縮。一個(gè) agent 的最小形態(tài)只需要一件事一個(gè)能反復(fù)“想、動(dòng)、看”的循環(huán)。第一版我建議把目標(biāo)定得極小——給模型一個(gè)任務(wù)讓它能讀取當(dāng)前目錄里的文件列表最多循環(huán) 6 輪然后就停止。能跑通這個(gè)再談其他。2.1 先約定一個(gè)可替換的模型后端入口為了不把注意力浪費(fèi)在具體廠商 API 上我在代碼里統(tǒng)一用一個(gè)call_backend()函數(shù)作為模型入口。后面無論是接 Claude 系列還是其他模型都只需要替換這一個(gè)函數(shù)。這個(gè)函數(shù)接收歷史消息和工具定義返回一個(gè)結(jié)構(gòu)化結(jié)果要么是“最終回答”要么是“工具調(diào)用請(qǐng)求”。SYSTEM_PROMPT 你是一個(gè)運(yùn)行在終端里的 AI 編程助手。 你可以調(diào)用下列工具來完成任務(wù) - read_file(path): 讀取文件內(nèi)容 - list_files(path): 列出目錄下的文件 - run_command(command): 在項(xiàng)目目錄下執(zhí)行命令 當(dāng)任務(wù)完成時(shí)直接輸出最終結(jié)論不要附帶任何工具調(diào)用。 TOOLS_DEFINITION [ { name: read_file, description: 讀取指定文本文件的內(nèi)容, parameters: {path: string}, }, { name: list_files, description: 列出指定目錄下的條目, parameters: {path: string}, }, { name: run_command, description: 執(zhí)行一條 shell 命令, parameters: {command: string}, }, ] def call_backend(messages, tools): # 真實(shí)實(shí)現(xiàn)中這里會(huì)調(diào)用你選擇的模型接口。 # 返回值示例 # {type: tool_call, tool_name: list_files, tool_args: {path: .}} # {type: final, content: 我已經(jīng)完成了任務(wù)。} raise NotImplementedError我把call_backend留成未實(shí)現(xiàn)原因很簡(jiǎn)單不同讀者手上的模型入口不一樣。有人用一個(gè)幾十行的本地模型有人用廠商 API還有人想用命令行封裝。把模型調(diào)用單獨(dú)隔離出來之后整條 agent 循環(huán)的邏輯就可以完全復(fù)用。2.2 最小循環(huán)解析動(dòng)作、執(zhí)行、回填下面是整個(gè) harness 的核心我認(rèn)為 8 行就能講清楚import json def run_agent(task: str, max_steps: int 6): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: task}, ] for step in range(max_steps): response call_backend(messages, TOOLS_DEFINITION) if response[type] final: print(f[agent] {response[content]}) return response[content] action parse_action(response) result dispatch(action) messages.append({ role: tool, tool_name: action[tool_name], content: json.dumps(result), })這個(gè)循環(huán)里最關(guān)鍵的兩個(gè)函數(shù)是parse_action和dispatch。parse_action負(fù)責(zé)把模型的響應(yīng)解析成一個(gè)標(biāo)準(zhǔn)動(dòng)作結(jié)構(gòu)比如{tool_name: read_file, tool_args: {path: config.yaml}}。dispatch根據(jù)動(dòng)作名找到對(duì)應(yīng)的工具函數(shù)并執(zhí)行同時(shí)負(fù)責(zé)捕獲異常、記錄執(zhí)行時(shí)間、把執(zhí)行結(jié)果封裝成字符串。這里有一個(gè)初學(xué)者很容易漏掉的點(diǎn)工具執(zhí)行的結(jié)果一定要以“工具消息”的形式繼續(xù)追加到messages里而不是單獨(dú)存放在一個(gè)變量里。因?yàn)橄乱惠喣Ｐ驼{(diào)用時(shí)它必須能同時(shí)看到自己剛才做了什么以及得到了什么結(jié)果才能決定下一步動(dòng)作。如果你只是把結(jié)果存在內(nèi)存里下一輪請(qǐng)求就會(huì)缺一段關(guān)鍵歷史模型就會(huì)“失憶”。2.3 第一版跑通后我遇到的問題第一次跑通這個(gè)循環(huán)我挺興奮的但緊接著就撞上兩個(gè)問題。第一個(gè)問題是解析容錯(cuò)。模型經(jīng)常不老老實(shí)實(shí)返回結(jié)構(gòu)化字段而是輸出類似“讓我先看看當(dāng)前目錄下有什么”這樣的自然語言。如果直接把這段扔給dispatch必然報(bào)錯(cuò)。我的解決辦法是讓parse_action做三層嘗試先按嚴(yán)格 JSON 解析失敗則嘗試從文本里用正則提取工具名和參數(shù)再失敗就把整段文本作為一條“模型消息”返回給模型請(qǐng)它重新組織輸出。這么做的理由是很多本地模型的輸出格式穩(wěn)定性確實(shí)不如大廠 API但 harness 可以把這點(diǎn)差異消化掉。第二個(gè)問題是工作目錄混亂。我一開始讓run_command在進(jìn)程默認(rèn)目錄下運(yùn)行結(jié)果發(fā)現(xiàn)同一個(gè)命令在不同時(shí)間執(zhí)行跑的位置不一樣模型拿到的結(jié)果自然也不一致。統(tǒng)一做法是給所有工具函數(shù)傳入一個(gè)固定的workspace路徑常量所有相對(duì)路徑都基于這個(gè)常量解析。這在后面接入真實(shí)項(xiàng)目時(shí)特別重要一個(gè) agent 如果連“我在哪個(gè)目錄里”都不能保證那它讀到的文件和執(zhí)行測(cè)試的結(jié)果都會(huì)很不可靠。3. 給 Harness 補(bǔ)上工具注冊(cè)表與權(quán)限邊界最小循環(huán)跑通之后下一步不是繼續(xù)加功能而是把工具層做規(guī)范。因?yàn)楫?dāng)模型能調(diào)用工具之后你就把一部分系統(tǒng)控制權(quán)交給了模型輸出這必須有“圍欄”。3.1 用注冊(cè)表而不是一堆 if-else 管理工具早期版本里dispatch函數(shù)用一長(zhǎng)串 if-else 來分發(fā)動(dòng)作每加一個(gè)工具就要改一次函數(shù)。后來我發(fā)現(xiàn)用注冊(cè)表設(shè)計(jì)能省掉大量重復(fù)代碼也給后續(xù)的權(quán)限校驗(yàn)、參數(shù)校驗(yàn)留出了統(tǒng)一入口。TOOL_REGISTRY { read_file: { fn: read_file, validate: lambda args: isinstance(args.get(path), str), permission: read, }, list_files: { fn: list_files, validate: lambda args: isinstance(args.get(path), str), permission: read, }, run_command: { fn: run_command, validate: lambda args: isinstance(args.get(command), str), permission: write, }, } def dispatch(action): try: tool TOOL_REGISTRY[action[tool_name]] except KeyError: return {ok: False, error: f未知工具: {action[tool_name]}} args action.get(tool_args, {}) if not tool[validate](args): return {ok: False, error: f參數(shù)類型錯(cuò)誤: {args}} try: result tool[fn](**args) return {ok: True, data: result} except Exception as e: return {ok: False, error: f{type(e).__name__}: {e}}注冊(cè)表的好處是新增工具時(shí)只需要往字典里加一個(gè)條目同時(shí)因?yàn)樗泄ぞ叨冀?jīng)過dispatch統(tǒng)一處理異常、校驗(yàn)、權(quán)限檢查都可以在這一層集中做。模型調(diào)用工具時(shí)萬一拿到一個(gè)錯(cuò)誤結(jié)果也不會(huì)讓整個(gè) harness 崩潰而是把錯(cuò)誤作為下一輪輸入的一部分讓它自己想辦法修正。這在 agent 場(chǎng)景里非常有用。3.2 別急著給模型一把無限權(quán)力的 shell很多第一次寫 harness 的人會(huì)直接給模型一個(gè)run_command允許它執(zhí)行任意 shell 命令。我也這么干過結(jié)果不是模型跑飛而是我自己嚇出一身冷汗——它竟然嘗試去刪除一個(gè)看似無關(guān)的緩存目錄。我后來把工具集合收得很緊第一版只有三個(gè)工具read_file、list_files、run_tests。其中run_tests只允許執(zhí)行固定的測(cè)試命令不接受任意參數(shù)。想跑 grep 之類的搜索再加一個(gè)只讀的search_files。這樣雖然沒有給模型最大的自由度但保證了它在這個(gè)階段能完成絕大多數(shù)任務(wù)。只有當(dāng)它明確遇到現(xiàn)有工具覆蓋不了的情況我才會(huì)考慮放開一個(gè)更通用的命令工具而且一定要配上下面的權(quán)限檢查。3.3 用 allowlist 和用戶確認(rèn)把危險(xiǎn)操作攔下來如果要提供一個(gè)通用run_command就必須有權(quán)限策略。我的做法是分層防錯(cuò)詞法層檢查命令頭部策略層攔截危險(xiǎn)模式。import shlex ALLOWED_COMMAND_HEADS { python, pytest, ls, cat, find, grep, sed, awk, diff, wc } BLOCKED_PATTERNS [ rm -rf, mkfs, dd if, :(){, curl.*|sh, /dev/sd, chmod -R 777 ] def approve_command(raw_command: str) - bool: parts shlex.split(raw_command) if not parts: return False if parts[0] not in ALLOWED_COMMAND_HEADS: return False return not any(pattern in raw_command for pattern in BLOCKED_PATTERNS)這段代碼不是絕對(duì)安全但它足夠作為第一道防線。真正執(zhí)行前我還會(huì)再加一道“人工確認(rèn)”的關(guān)卡當(dāng)模型要執(zhí)行命令時(shí)harness 先把命令打印出來等待用戶按y后才執(zhí)行。Claude Code 在實(shí)際使用中也有類似交互——在關(guān)鍵操作前停下來要用戶確認(rèn)。這道關(guān)卡尤其在模型要執(zhí)行寫操作、刪除操作或者管道命令時(shí)不能省。4. 還要定義“任務(wù)成功”測(cè)試、反饋與有限循環(huán)一個(gè)人工智能編程助手和一個(gè)聊天機(jī)器人的最大區(qū)別是它有“客觀反饋”。模型改完代碼后憑什么說它改對(duì)了憑測(cè)試結(jié)果。沒有測(cè)試作為判據(jù)模型就會(huì)在一輪輪自我感覺良好中瞎改。所以這一章要給 harness 裝上“眼睛”和“剎車”。4.1 用測(cè)試退出碼作為模型的“好消息”和“壞消息”我的系統(tǒng)提示里專門有一段話當(dāng)你修改完代碼之后立刻調(diào)用run_tests工具如果測(cè)試失敗仔細(xì)閱讀最后 30 行錯(cuò)誤輸出定位原因后繼續(xù)修改最多嘗試三輪如果三輪后仍然失敗停止修改并給出你的判斷。代碼層面run_tests工具會(huì)返回三個(gè)關(guān)鍵信息退出碼、標(biāo)準(zhǔn)輸出的最后若干行、標(biāo)準(zhǔn)錯(cuò)誤的最后若干行。這三個(gè)信息會(huì)以 JSON 字符串的形式進(jìn)入下一輪上下文。退出碼是 0模型就知道任務(wù)完成了退出碼非 0模型就知道還得繼續(xù)干活。關(guān)鍵是錯(cuò)誤信息必須截短否則一次失敗的測(cè)試可能有幾百行輸出直接把上下文撐爆。我后面會(huì)專門講上下文管理這里先記住“只回傳 tail 而非全量”這個(gè)原則。4.2 防呆設(shè)計(jì)識(shí)別“重復(fù)動(dòng)作”和“循環(huán)卡死”就算有了測(cè)試反饋模型也可能陷入一個(gè)經(jīng)典陷阱它在同一個(gè)錯(cuò)誤上反復(fù)嘗試同樣的修改只是每次說法略有不同。這種循環(huán)在真實(shí)項(xiàng)目中太常見了尤其是模型在上下文較長(zhǎng)、不能完全記得前一輪動(dòng)作的時(shí)候。我在 harness 里加了一個(gè)“最近動(dòng)作去重”機(jī)制from collections import deque def detect_repetition(recent_actions: deque, threshold: int 3) - bool: if len(recent_actions) threshold: return False return len(set(recent_actions)) 1 recent deque(maxlen3) # 每輪循環(huán)中 if detect_repetition(recent): messages.append({ role: tool, name: system_note, content: 檢測(cè)到連續(xù)重復(fù)動(dòng)作請(qǐng)換一種策略。 }) recent.clear()這個(gè)機(jī)制的作用不是阻止模型嘗試而是強(qiáng)制它跳出慣性。重復(fù)三次同樣的動(dòng)作基本可以判定當(dāng)前策略無效與其讓它繼續(xù)浪費(fèi) token不如直接把“換個(gè)思路”作為明確指令注入到上下文里。類似機(jī)制還可以擴(kuò)展成“同一條命令連續(xù)失敗兩次后暫時(shí)凍結(jié)”比如 pytest 連續(xù)兩次失敗就先把pytest從 allowlist 里臨時(shí)移除一輪逼模型先檢查代碼而不是再次盲跑測(cè)試。4.3 詞法黑名單與系統(tǒng)提示雙保險(xiǎn)很多人會(huì)問既然我已經(jīng)在系統(tǒng)提示里寫了“不要?jiǎng)h除文件、不要訪問生產(chǎn)環(huán)境”是不是就夠了不夠。模型偶爾會(huì)忽略指令或者被后續(xù)較長(zhǎng)的上下文干擾忘記最初的安全約定。所以系統(tǒng)提示是策略層allowlist 是執(zhí)行層兩層必須同時(shí)存在。我在系統(tǒng)提示里會(huì)寫你只能操作當(dāng)前項(xiàng)目工作區(qū)內(nèi)的文件。禁止刪除未說明的文件禁止修改.env、密鑰文件、數(shù)據(jù)庫文件。在執(zhí)行任何可能造成不可逆影響的命令前必須先用describe_plan輸出執(zhí)行計(jì)劃。而在執(zhí)行層即使模型真的請(qǐng)求了類似rm -rf的命令approve_command也會(huì)直接拒絕。對(duì) agent 來說安全永遠(yuǎn)不能只依賴模型的“自覺”而是必須由 harness 兜底。這是我的一個(gè)比較堅(jiān)定的經(jīng)驗(yàn)寧可讓模型因?yàn)楣ぞ呤芟薅鄦枎拙湟膊荒茏屗鼡碛性竭^圍欄的能力。5. 從玩具到能用的編碼助手上下文管理與增量編輯到這一步你的 toy harness 已經(jīng)能完成“讀代碼、改文件、跑測(cè)試、反復(fù)修復(fù)”的閉環(huán)了。但一旦放到真實(shí)項(xiàng)目中很快會(huì)遇到一個(gè)成長(zhǎng)瓶頸上下文不夠用。真實(shí)倉庫的文件數(shù)量和測(cè)試輸出會(huì)讓模型在幾輪之后就“忘掉前面在做什么”。這章講我實(shí)際動(dòng)手時(shí)踩坑最多的地方。5.1 先給工具輸出上一層“止血帶”有一次我讓 harness 跑一個(gè)稍微大一點(diǎn)的測(cè)試套件結(jié)果單輪工具輸出就帶回了 4000 多行內(nèi)容。下一輪請(qǐng)求直接報(bào)上下文超限。從那以后我給自己定了一條硬規(guī)矩任何工具返回內(nèi)容寫入上下文之前必須經(jīng)過裁剪器。def clamp_text(text: str, max_lines: int 200, max_chars: int 6000) - str: lines text.splitlines() if len(lines) max_lines: lines lines[-max_lines:] return \n.join(lines) f\n[已截?cái)鄡H顯示末尾 {max_lines} 行] if len(text) max_chars: return text[-max_chars:] f\n[已截?cái)喑^ {max_chars} 字符] return text這個(gè)裁剪器很簡(jiǎn)單但它改變了整個(gè) harness 的可靠性。對(duì)成功的測(cè)試模型其實(shí)只需要看“PASS”“退出碼 0”這幾個(gè)字對(duì)失敗的測(cè)試它需要的是末尾的錯(cuò)誤摘要和 traceback 尾部。開頭幾百行通常是無用的環(huán)境信息全部保留只會(huì)稀釋模型的注意力。5.2 大文件修改用 apply_patch 而不是整個(gè)文件重寫早期我讓模型改代碼用的是write_file工具直接把整個(gè)新文件內(nèi)容寫給 harness。文件小的時(shí)候還好文件一旦超過一千行問題就來了模型很可能會(huì)在重寫過程中丟掉函數(shù)或者不小心把某段注釋改動(dòng)掉。而且整文件重寫也極度浪費(fèi) token——目標(biāo)只是改一行字段名卻要把整個(gè) 800 行的文件重新發(fā)一遍。更好的方案是引入apply_patch工具讓模型輸出一個(gè) unified diff由 harness 在本地應(yīng)用這個(gè) diff。這樣模型只需要給出改動(dòng)區(qū)域上下文消耗可能降到原來的十分之一。即便 diff 格式有問題沖突信息也可以轉(zhuǎn)換成錯(cuò)誤返回給模型讓模型重新生成更小的補(bǔ)丁。我在系統(tǒng)提示里放了一個(gè)簡(jiǎn)短示例告訴模型“下面是一個(gè)非常常見的 diff 格式請(qǐng)嚴(yán)格按照這個(gè)格式輸出”。Claude Code 內(nèi)部其實(shí)也采用了類似的編輯策略盡量做增量編輯而不是整文件覆蓋既省 token 又降低出錯(cuò)概率。5.3 歷史壓縮當(dāng) agent 開始“忘事”的時(shí)候即使做了工具輸出裁剪多輪之后的歷史仍然可能膨脹。我碰到的典型情況是前兩輪模型讀了三個(gè)文件第三輪跑測(cè)試第四輪改代碼第五輪又跑測(cè)試。到第六輪時(shí)前面讀過的文件內(nèi)容其實(shí)已經(jīng)被后續(xù)動(dòng)作替換了但一直留在歷史里。此時(shí)如果不做處理token 預(yù)算很快就爆。我后來加了一個(gè)簡(jiǎn)單的“壓縮策略”每完成一個(gè)明確的階段性動(dòng)作比如改完一個(gè)文件、跑完一輪測(cè)試就把最舊的一輪工具結(jié)果壓縮成一行摘要用類似[步驟 1-2] 讀取了 config.py發(fā)現(xiàn) retry 相關(guān)代碼在 45-60 行的句子替換原始內(nèi)容。這個(gè)壓縮動(dòng)作發(fā)生在 harness 層模型完全感知不到但它看到的歷史變得更緊湊。還有更激進(jìn)的辦法當(dāng)歷史長(zhǎng)度超過預(yù)設(shè)閾值直接讓模型自己寫一段“到目前為止完成情況和下一步計(jì)劃”然后用這段摘要替換掉先前全部對(duì)話。6. 復(fù)盤與進(jìn)階拿 Claude Code 當(dāng)尺子衡量我的 Harness把 toy harness 搭到這一步它在功能上已經(jīng)很接近一個(gè)小型 AI 編程助手了。但真正讓這套東西變得有價(jià)值的是自我對(duì)照。我會(huì)拿 Claude Code 的實(shí)際表現(xiàn)當(dāng)尺子一條一條對(duì)照看哪些我做對(duì)了哪些我可以直接模仿哪些未來值得繼續(xù)做深。6.1 功能差距對(duì)照表以下是我在某個(gè)階段做的對(duì)照表。注意這不是為了“追平”而是為了看清楚每個(gè)功能模塊組合出來的體驗(yàn)差異。維度我的 toy harnessClaude Code 的成熟表現(xiàn)我的結(jié)論循環(huán)控制單線程、固定上限支持多線程任務(wù)、長(zhǎng)時(shí)間運(yùn)行、可中斷核心循環(huán)思路一致但并發(fā)和控制信號(hào)做得更深工具數(shù)量4 到 5 個(gè)讀、寫、編輯、搜索、終端、代碼查詢等數(shù)量不是關(guān)鍵覆蓋場(chǎng)景才是權(quán)限模型allowlist 用戶確認(rèn)會(huì)話級(jí)權(quán)限、項(xiàng)目級(jí)白名單、可配置策略我的機(jī)制可用但粒度不夠細(xì)上下文管理裁剪器 歷史壓縮自動(dòng)壓縮、子對(duì)話隔離、分步任務(wù)記憶方向正確工程化程度差很多可觀測(cè)性JSONL 日志內(nèi)部有 trace 可視化我的日志方案更進(jìn)一步成為調(diào)試核心這張表不是給產(chǎn)品做 benchmark而是用來指導(dǎo)下一步開發(fā)。比如我發(fā)現(xiàn)“子對(duì)話隔離”這個(gè)能力很重要的時(shí)候就去查 Claude Code 在這一塊的設(shè)計(jì)思路然后回到自己的 harness 里實(shí)現(xiàn)一個(gè)粗版本把不同子任務(wù)的歷史分開存放。這個(gè)過程非常爽因?yàn)槟悴皇窃诔鸢付窃诶斫鉃槭裁葱枰@個(gè)答案。6.2 日志回放是我調(diào)試 Agent 循環(huán)的救命稻草單獨(dú)說一下可觀測(cè)性。沒有日志你根本沒法判斷一個(gè) agent 為什么行為異常。我記得有一次模型總是不執(zhí)行工具而是光說“我準(zhǔn)備做這件事”排查了很久最后發(fā)現(xiàn)是系統(tǒng)提示里“工具調(diào)用格式”的示例寫得不夠強(qiáng)讓模型產(chǎn)生了誤解。如果不是把每一輪的完整請(qǐng)求和響應(yīng)都記錄成 JSONL這個(gè)問題很可能會(huì)被我歸因到模型能力上而不是 harness 的提示設(shè)計(jì)上。我采用的日志格式很簡(jiǎn)單每個(gè)事件一行 JSON包含時(shí)間戳、步驟序號(hào)、消息角色、工具名、參數(shù)摘要、執(zhí)行結(jié)果 exit code、耗時(shí)、消耗 token 數(shù)。排查時(shí)用grep過濾某個(gè) step再按時(shí)間順序一口氣回放就能還原模型當(dāng)時(shí)看到的一切。調(diào)試 agent 時(shí)最重要的認(rèn)知就是把模型當(dāng)作一個(gè)需要完整上下文才能運(yùn)轉(zhuǎn)的系統(tǒng)你能看到多少上下文你就能定位多少問題。6.3 再往前走多 Agent、沙箱與流式輸出玩具項(xiàng)目到這里已經(jīng)可以收尾了但如果你想把這條路繼續(xù)走下去有幾個(gè)方向我認(rèn)為特別值得探索。多 Agent 是最自然的一個(gè)擴(kuò)展。把“規(guī)劃”和“執(zhí)行”分開一個(gè) Agent 只負(fù)責(zé)分析任務(wù)、拆解步驟、生成方案另一個(gè) Agent 只負(fù)責(zé)做具體文件修改和命令執(zhí)行。這樣做的好處是規(guī)劃 Agent 的上下文不會(huì)被工具輸出污染執(zhí)行 Agent 也不需要讀過所有說明文檔。子代理之間的通信接口需要固定我用的是 JSON 格式的“任務(wù)單結(jié)果單”本質(zhì)上又成了一層小 harness。沙箱是第二個(gè)方向。讓模型在容器或臨時(shí)目錄里執(zhí)行命令可以極大減少誤操作帶來的風(fēng)險(xiǎn)。雖然做容器封裝會(huì)有額外性能開銷但如果你準(zhǔn)備把這個(gè) harness 用在不可完全信任的輸入場(chǎng)景沙箱不是可選項(xiàng)而是必選項(xiàng)。流式輸出則是體驗(yàn)層面的提升把模型的思考過程和工具調(diào)用結(jié)果實(shí)時(shí)推到終端而不是等整個(gè)任務(wù)跑完才一次性顯示。真正常用的 AI 編程助手都會(huì)這么做因?yàn)樗屇愀杏X自己在“看著別人干活”而不是在黑盒等待。實(shí)現(xiàn)思路也不復(fù)雜只需要把call_backend換成支持流式回調(diào)的版本把事件分發(fā)到終端渲染層。說句實(shí)在話我第一次跑通這個(gè)玩具 harness 的時(shí)候最大的收獲不是“我會(huì)寫 agent 了”而是我終于能解釋清楚很多現(xiàn)象——為什么模型會(huì)反復(fù)改同一個(gè)錯(cuò)誤為什么強(qiáng)行塞進(jìn)太多上下文會(huì)讓它變笨為什么權(quán)限機(jī)制必須放在工具層而不是提示詞層。拆過一次再裝回去再看 Claude Code 就覺得它不再是黑盒而是一套我深刻理解工作原理、能預(yù)測(cè)它行為邊界的工具箱。如果你也在學(xué)習(xí)這類 AI 編程助手我的建議很簡(jiǎn)單不必一開始就追求完整功能先寫一個(gè)能跑通一個(gè)真實(shí)小任務(wù)的循環(huán)然后慢慢地往里面加測(cè)試反饋、權(quán)限確認(rèn)和上下文壓縮。每一步都值得。 從零構(gòu)建Agent Harness：拆解Claude Code的AI編程助手
1. 先把“AI 編程助手”拆成一塊塊看得見的零件最近不少人問我既然 Claude Code 已經(jīng)這么強(qiáng)為什么還要花時(shí)間去“從零構(gòu)建一個(gè) Agent Harness”我的回答是把一個(gè)黑盒拆開再重裝一遍你對(duì)它的掌控會(huì)完全不同。文章標(biāo)題寫著“Learn Claude Code”但我想說的比單純學(xué)命令用法更深一層把 AI 編程助手當(dāng)成一個(gè)由好幾塊零件拼起來的系統(tǒng)然后親手寫出一個(gè)最小可運(yùn)行的 harness。Claude Code 本質(zhì)上并不“神秘”。當(dāng)你坐在終端前敲下一句“幫我把這個(gè)模塊的重試邏輯修一下”它背后發(fā)生的其實(shí)是一連串非常工程化的步驟先收集倉庫上下文再把任務(wù)和上下文一起交給模型模型輸出一個(gè)行動(dòng)意圖外圍框架負(fù)責(zé)執(zhí)行這個(gè)行動(dòng)然后把執(zhí)行結(jié)果再喂回模型如此循環(huán)直到模型認(rèn)為任務(wù)完成。真正決定體驗(yàn)高下的不是模型本身有多聰明而是這一圈循環(huán)做得是否穩(wěn)定、收斂、安全。這篇文章適合兩類人一是已經(jīng)在用 Claude Code但想知道“它到底是怎么做到的”的開發(fā)者二是想自己搭一套內(nèi)部 AI 編程工具卻不太清楚該從哪里動(dòng)手的人。我會(huì)按我實(shí)際搭建玩具項(xiàng)目的順序來講先講最小閉環(huán)再逐步補(bǔ)上權(quán)限、反饋、上下文管理這些零件。讀完之后你能自己寫出一個(gè)能讀文件、改文件、跑測(cè)試、然后根據(jù)測(cè)試結(jié)果自我修復(fù)的 agent 循環(huán)。1.1 把 Claude Code 的使用體驗(yàn)拆成四個(gè)組件我自己的拆解習(xí)慣是把一個(gè) AI 編程助手分成四塊任務(wù)注入用戶指令加上倉庫結(jié)構(gòu)、相關(guān)文件內(nèi)容被組裝成一段上下文。決策循環(huán)模型根據(jù)上下文決定下一步動(dòng)作可能是讀文件、寫文件、跑命令也可能是直接給出最終結(jié)論。工具集合一系列可供模型調(diào)用的函數(shù)比如讀文件、搜索文件、執(zhí)行 shell 命令。安全與反饋執(zhí)行前做權(quán)限判斷執(zhí)行后把退出碼、標(biāo)準(zhǔn)輸出等結(jié)果返回給模型。這四塊里面最容易被忽視的是第四塊。很多人以為只要把模型接到終端上它自然就能“編程”了其實(shí)不是。模型只是一個(gè)“思考者”一個(gè)行動(dòng)要被真正執(zhí)行需要經(jīng)過工具層和權(quán)限層的翻譯與約束。Claude Code 之所以比普通聊天機(jī)器人更適合編程就在于它的第四個(gè)組件做得足夠細(xì)致它會(huì)自動(dòng)跑測(cè)試會(huì)把錯(cuò)誤日志截短后再喂給模型也會(huì)在模型要執(zhí)行危險(xiǎn)命令時(shí)停下來問用戶。1.2 Agent Harness 到底是個(gè)什么東西Harness 在中文里可以叫“套具”或“腳手架”但我更愿意叫它“夾層邏輯”。它夾在模型和操作系統(tǒng)之間負(fù)責(zé)把模型的文本輸出翻譯成可執(zhí)行動(dòng)作再將動(dòng)作結(jié)果序列化回上下文。舉個(gè)例子模型告訴你“我想讀取 config.yaml”但這只是它輸出的一句話。Harness 要做的事情是從這句話里解析出工具名“read_file”、參數(shù)“config.yaml”找到對(duì)應(yīng)的函數(shù)把文件內(nèi)容讀出來然后以標(biāo)準(zhǔn)格式寫回模型的歷史消息。如果工具調(diào)用格式不對(duì)harness 還得負(fù)責(zé)返回一個(gè)錯(cuò)誤讓模型看到之后重新生成。這就是為什么我說模型不是主角流程才是主角。模型的輸出千變?nèi)f化一個(gè)合格的 harness 要做的就是把這些千變?nèi)f化收斂成可執(zhí)行的、可控的步驟。你可以把 harness 想象成一位嚴(yán)謹(jǐn)?shù)能囬g主任模型是技術(shù)顧問。技術(shù)顧問可以提出各種方案但最后擰螺絲、通電、質(zhì)檢的步驟都必須經(jīng)過車間主任的流程和審批。車間主任可以沒有顧問那么懂技術(shù)但他必須保證每個(gè)動(dòng)作都留下記錄、不會(huì)越界、也不會(huì)在同一個(gè)錯(cuò)誤上反復(fù)折騰。1.3 為什么“從零構(gòu)建”比“讀文檔”更有學(xué)習(xí)價(jià)值直接讀 Claude Code 的文檔你只會(huì)知道它能做什么比如“可以編輯文件”“可以并行運(yùn)行多個(gè)任務(wù)”。但你自己動(dòng)手寫一個(gè)最少 200 行左右的 harness 之后才會(huì)理解它為什么那樣設(shè)計(jì)。舉個(gè)我在搭玩具項(xiàng)目時(shí)反復(fù)遇到的例子模型偶爾會(huì)不按約定輸出結(jié)構(gòu)化的工具調(diào)用而是直接說一段話比如“我先讀取一下文件再?zèng)Q定怎么改”。如果 harness 不處理這種情況整個(gè)循環(huán)就斷了。好的做法是把自然語言和結(jié)構(gòu)化調(diào)用都解析一遍先嘗試嚴(yán)格解析失敗就退回模糊提取再失敗就把“當(dāng)前輸出無法理解”明確告訴模型。類似這樣的細(xì)節(jié)不親手寫一遍代碼是體會(huì)不到的。所以我后面幾個(gè)章節(jié)的內(nèi)容都是從一個(gè)能跑的玩具 harness 出發(fā)一步一步加零件。每一步我都會(huì)解釋“為什么需要這個(gè)部件”因?yàn)檫@才是從零構(gòu)建的真正價(jià)值不只是知道怎么拼而是知道為什么這么拼。2. 最小版 Harness 的核心一個(gè)能自己跑命令的循環(huán)先別急著加權(quán)限、加測(cè)試、加上下文壓縮。一個(gè) agent 的最小形態(tài)只需要一件事一個(gè)能反復(fù)“想、動(dòng)、看”的循環(huán)。第一版我建議把目標(biāo)定得極小——給模型一個(gè)任務(wù)讓它能讀取當(dāng)前目錄里的文件列表最多循環(huán) 6 輪然后就停止。能跑通這個(gè)再談其他。2.1 先約定一個(gè)可替換的模型后端入口為了不把注意力浪費(fèi)在具體廠商 API 上我在代碼里統(tǒng)一用一個(gè)call_backend()函數(shù)作為模型入口。后面無論是接 Claude 系列還是其他模型都只需要替換這一個(gè)函數(shù)。這個(gè)函數(shù)接收歷史消息和工具定義返回一個(gè)結(jié)構(gòu)化結(jié)果要么是“最終回答”要么是“工具調(diào)用請(qǐng)求”。SYSTEM_PROMPT 你是一個(gè)運(yùn)行在終端里的 AI 編程助手。 你可以調(diào)用下列工具來完成任務(wù) - read_file(path): 讀取文件內(nèi)容 - list_files(path): 列出目錄下的文件 - run_command(command): 在項(xiàng)目目錄下執(zhí)行命令 當(dāng)任務(wù)完成時(shí)直接輸出最終結(jié)論不要附帶任何工具調(diào)用。 TOOLS_DEFINITION [ { name: read_file, description: 讀取指定文本文件的內(nèi)容, parameters: {path: string}, }, { name: list_files, description: 列出指定目錄下的條目, parameters: {path: string}, }, { name: run_command, description: 執(zhí)行一條 shell 命令, parameters: {command: string}, }, ] def call_backend(messages, tools): # 真實(shí)實(shí)現(xiàn)中這里會(huì)調(diào)用你選擇的模型接口。 # 返回值示例 # {type: tool_call, tool_name: list_files, tool_args: {path: .}} # {type: final, content: 我已經(jīng)完成了任務(wù)。} raise NotImplementedError我把call_backend留成未實(shí)現(xiàn)原因很簡(jiǎn)單不同讀者手上的模型入口不一樣。有人用一個(gè)幾十行的本地模型有人用廠商 API還有人想用命令行封裝。把模型調(diào)用單獨(dú)隔離出來之后整條 agent 循環(huán)的邏輯就可以完全復(fù)用。2.2 最小循環(huán)解析動(dòng)作、執(zhí)行、回填下面是整個(gè) harness 的核心我認(rèn)為 8 行就能講清楚import json def run_agent(task: str, max_steps: int 6): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: task}, ] for step in range(max_steps): response call_backend(messages, TOOLS_DEFINITION) if response[type] final: print(f[agent] {response[content]}) return response[content] action parse_action(response) result dispatch(action) messages.append({ role: tool, tool_name: action[tool_name], content: json.dumps(result), })這個(gè)循環(huán)里最關(guān)鍵的兩個(gè)函數(shù)是parse_action和dispatch。parse_action負(fù)責(zé)把模型的響應(yīng)解析成一個(gè)標(biāo)準(zhǔn)動(dòng)作結(jié)構(gòu)比如{tool_name: read_file, tool_args: {path: config.yaml}}。dispatch根據(jù)動(dòng)作名找到對(duì)應(yīng)的工具函數(shù)并執(zhí)行同時(shí)負(fù)責(zé)捕獲異常、記錄執(zhí)行時(shí)間、把執(zhí)行結(jié)果封裝成字符串。這里有一個(gè)初學(xué)者很容易漏掉的點(diǎn)工具執(zhí)行的結(jié)果一定要以“工具消息”的形式繼續(xù)追加到messages里而不是單獨(dú)存放在一個(gè)變量里。因?yàn)橄乱惠喣Ｐ驼{(diào)用時(shí)它必須能同時(shí)看到自己剛才做了什么以及得到了什么結(jié)果才能決定下一步動(dòng)作。如果你只是把結(jié)果存在內(nèi)存里下一輪請(qǐng)求就會(huì)缺一段關(guān)鍵歷史模型就會(huì)“失憶”。2.3 第一版跑通后我遇到的問題第一次跑通這個(gè)循環(huán)我挺興奮的但緊接著就撞上兩個(gè)問題。第一個(gè)問題是解析容錯(cuò)。模型經(jīng)常不老老實(shí)實(shí)返回結(jié)構(gòu)化字段而是輸出類似“讓我先看看當(dāng)前目錄下有什么”這樣的自然語言。如果直接把這段扔給dispatch必然報(bào)錯(cuò)。我的解決辦法是讓parse_action做三層嘗試先按嚴(yán)格 JSON 解析失敗則嘗試從文本里用正則提取工具名和參數(shù)再失敗就把整段文本作為一條“模型消息”返回給模型請(qǐng)它重新組織輸出。這么做的理由是很多本地模型的輸出格式穩(wěn)定性確實(shí)不如大廠 API但 harness 可以把這點(diǎn)差異消化掉。第二個(gè)問題是工作目錄混亂。我一開始讓run_command在進(jìn)程默認(rèn)目錄下運(yùn)行結(jié)果發(fā)現(xiàn)同一個(gè)命令在不同時(shí)間執(zhí)行跑的位置不一樣模型拿到的結(jié)果自然也不一致。統(tǒng)一做法是給所有工具函數(shù)傳入一個(gè)固定的workspace路徑常量所有相對(duì)路徑都基于這個(gè)常量解析。這在后面接入真實(shí)項(xiàng)目時(shí)特別重要一個(gè) agent 如果連“我在哪個(gè)目錄里”都不能保證那它讀到的文件和執(zhí)行測(cè)試的結(jié)果都會(huì)很不可靠。3. 給 Harness 補(bǔ)上工具注冊(cè)表與權(quán)限邊界最小循環(huán)跑通之后下一步不是繼續(xù)加功能而是把工具層做規(guī)范。因?yàn)楫?dāng)模型能調(diào)用工具之后你就把一部分系統(tǒng)控制權(quán)交給了模型輸出這必須有“圍欄”。3.1 用注冊(cè)表而不是一堆 if-else 管理工具早期版本里dispatch函數(shù)用一長(zhǎng)串 if-else 來分發(fā)動(dòng)作每加一個(gè)工具就要改一次函數(shù)。后來我發(fā)現(xiàn)用注冊(cè)表設(shè)計(jì)能省掉大量重復(fù)代碼也給后續(xù)的權(quán)限校驗(yàn)、參數(shù)校驗(yàn)留出了統(tǒng)一入口。TOOL_REGISTRY { read_file: { fn: read_file, validate: lambda args: isinstance(args.get(path), str), permission: read, }, list_files: { fn: list_files, validate: lambda args: isinstance(args.get(path), str), permission: read, }, run_command: { fn: run_command, validate: lambda args: isinstance(args.get(command), str), permission: write, }, } def dispatch(action): try: tool TOOL_REGISTRY[action[tool_name]] except KeyError: return {ok: False, error: f未知工具: {action[tool_name]}} args action.get(tool_args, {}) if not tool[validate](args): return {ok: False, error: f參數(shù)類型錯(cuò)誤: {args}} try: result tool[fn](**args) return {ok: True, data: result} except Exception as e: return {ok: False, error: f{type(e).__name__}: {e}}注冊(cè)表的好處是新增工具時(shí)只需要往字典里加一個(gè)條目同時(shí)因?yàn)樗泄ぞ叨冀?jīng)過dispatch統(tǒng)一處理異常、校驗(yàn)、權(quán)限檢查都可以在這一層集中做。模型調(diào)用工具時(shí)萬一拿到一個(gè)錯(cuò)誤結(jié)果也不會(huì)讓整個(gè) harness 崩潰而是把錯(cuò)誤作為下一輪輸入的一部分讓它自己想辦法修正。這在 agent 場(chǎng)景里非常有用。3.2 別急著給模型一把無限權(quán)力的 shell很多第一次寫 harness 的人會(huì)直接給模型一個(gè)run_command允許它執(zhí)行任意 shell 命令。我也這么干過結(jié)果不是模型跑飛而是我自己嚇出一身冷汗——它竟然嘗試去刪除一個(gè)看似無關(guān)的緩存目錄。我后來把工具集合收得很緊第一版只有三個(gè)工具read_file、list_files、run_tests。其中run_tests只允許執(zhí)行固定的測(cè)試命令不接受任意參數(shù)。想跑 grep 之類的搜索再加一個(gè)只讀的search_files。這樣雖然沒有給模型最大的自由度但保證了它在這個(gè)階段能完成絕大多數(shù)任務(wù)。只有當(dāng)它明確遇到現(xiàn)有工具覆蓋不了的情況我才會(huì)考慮放開一個(gè)更通用的命令工具而且一定要配上下面的權(quán)限檢查。3.3 用 allowlist 和用戶確認(rèn)把危險(xiǎn)操作攔下來如果要提供一個(gè)通用run_command就必須有權(quán)限策略。我的做法是分層防錯(cuò)詞法層檢查命令頭部策略層攔截危險(xiǎn)模式。import shlex ALLOWED_COMMAND_HEADS { python, pytest, ls, cat, find, grep, sed, awk, diff, wc } BLOCKED_PATTERNS [ rm -rf, mkfs, dd if, :(){, curl.*|sh, /dev/sd, chmod -R 777 ] def approve_command(raw_command: str) - bool: parts shlex.split(raw_command) if not parts: return False if parts[0] not in ALLOWED_COMMAND_HEADS: return False return not any(pattern in raw_command for pattern in BLOCKED_PATTERNS)這段代碼不是絕對(duì)安全但它足夠作為第一道防線。真正執(zhí)行前我還會(huì)再加一道“人工確認(rèn)”的關(guān)卡當(dāng)模型要執(zhí)行命令時(shí)harness 先把命令打印出來等待用戶按y后才執(zhí)行。Claude Code 在實(shí)際使用中也有類似交互——在關(guān)鍵操作前停下來要用戶確認(rèn)。這道關(guān)卡尤其在模型要執(zhí)行寫操作、刪除操作或者管道命令時(shí)不能省。4. 還要定義“任務(wù)成功”測(cè)試、反饋與有限循環(huán)一個(gè)人工智能編程助手和一個(gè)聊天機(jī)器人的最大區(qū)別是它有“客觀反饋”。模型改完代碼后憑什么說它改對(duì)了憑測(cè)試結(jié)果。沒有測(cè)試作為判據(jù)模型就會(huì)在一輪輪自我感覺良好中瞎改。所以這一章要給 harness 裝上“眼睛”和“剎車”。4.1 用測(cè)試退出碼作為模型的“好消息”和“壞消息”我的系統(tǒng)提示里專門有一段話當(dāng)你修改完代碼之后立刻調(diào)用run_tests工具如果測(cè)試失敗仔細(xì)閱讀最后 30 行錯(cuò)誤輸出定位原因后繼續(xù)修改最多嘗試三輪如果三輪后仍然失敗停止修改并給出你的判斷。代碼層面run_tests工具會(huì)返回三個(gè)關(guān)鍵信息退出碼、標(biāo)準(zhǔn)輸出的最后若干行、標(biāo)準(zhǔn)錯(cuò)誤的最后若干行。這三個(gè)信息會(huì)以 JSON 字符串的形式進(jìn)入下一輪上下文。退出碼是 0模型就知道任務(wù)完成了退出碼非 0模型就知道還得繼續(xù)干活。關(guān)鍵是錯(cuò)誤信息必須截短否則一次失敗的測(cè)試可能有幾百行輸出直接把上下文撐爆。我后面會(huì)專門講上下文管理這里先記住“只回傳 tail 而非全量”這個(gè)原則。4.2 防呆設(shè)計(jì)識(shí)別“重復(fù)動(dòng)作”和“循環(huán)卡死”就算有了測(cè)試反饋模型也可能陷入一個(gè)經(jīng)典陷阱它在同一個(gè)錯(cuò)誤上反復(fù)嘗試同樣的修改只是每次說法略有不同。這種循環(huán)在真實(shí)項(xiàng)目中太常見了尤其是模型在上下文較長(zhǎng)、不能完全記得前一輪動(dòng)作的時(shí)候。我在 harness 里加了一個(gè)“最近動(dòng)作去重”機(jī)制from collections import deque def detect_repetition(recent_actions: deque, threshold: int 3) - bool: if len(recent_actions) threshold: return False return len(set(recent_actions)) 1 recent deque(maxlen3) # 每輪循環(huán)中 if detect_repetition(recent): messages.append({ role: tool, name: system_note, content: 檢測(cè)到連續(xù)重復(fù)動(dòng)作請(qǐng)換一種策略。 }) recent.clear()這個(gè)機(jī)制的作用不是阻止模型嘗試而是強(qiáng)制它跳出慣性。重復(fù)三次同樣的動(dòng)作基本可以判定當(dāng)前策略無效與其讓它繼續(xù)浪費(fèi) token不如直接把“換個(gè)思路”作為明確指令注入到上下文里。類似機(jī)制還可以擴(kuò)展成“同一條命令連續(xù)失敗兩次后暫時(shí)凍結(jié)”比如 pytest 連續(xù)兩次失敗就先把pytest從 allowlist 里臨時(shí)移除一輪逼模型先檢查代碼而不是再次盲跑測(cè)試。4.3 詞法黑名單與系統(tǒng)提示雙保險(xiǎn)很多人會(huì)問既然我已經(jīng)在系統(tǒng)提示里寫了“不要?jiǎng)h除文件、不要訪問生產(chǎn)環(huán)境”是不是就夠了不夠。模型偶爾會(huì)忽略指令或者被后續(xù)較長(zhǎng)的上下文干擾忘記最初的安全約定。所以系統(tǒng)提示是策略層allowlist 是執(zhí)行層兩層必須同時(shí)存在。我在系統(tǒng)提示里會(huì)寫你只能操作當(dāng)前項(xiàng)目工作區(qū)內(nèi)的文件。禁止刪除未說明的文件禁止修改.env、密鑰文件、數(shù)據(jù)庫文件。在執(zhí)行任何可能造成不可逆影響的命令前必須先用describe_plan輸出執(zhí)行計(jì)劃。而在執(zhí)行層即使模型真的請(qǐng)求了類似rm -rf的命令approve_command也會(huì)直接拒絕。對(duì) agent 來說安全永遠(yuǎn)不能只依賴模型的“自覺”而是必須由 harness 兜底。這是我的一個(gè)比較堅(jiān)定的經(jīng)驗(yàn)寧可讓模型因?yàn)楣ぞ呤芟薅鄦枎拙湟膊荒茏屗鼡碛性竭^圍欄的能力。5. 從玩具到能用的編碼助手上下文管理與增量編輯到這一步你的 toy harness 已經(jīng)能完成“讀代碼、改文件、跑測(cè)試、反復(fù)修復(fù)”的閉環(huán)了。但一旦放到真實(shí)項(xiàng)目中很快會(huì)遇到一個(gè)成長(zhǎng)瓶頸上下文不夠用。真實(shí)倉庫的文件數(shù)量和測(cè)試輸出會(huì)讓模型在幾輪之后就“忘掉前面在做什么”。這章講我實(shí)際動(dòng)手時(shí)踩坑最多的地方。5.1 先給工具輸出上一層“止血帶”有一次我讓 harness 跑一個(gè)稍微大一點(diǎn)的測(cè)試套件結(jié)果單輪工具輸出就帶回了 4000 多行內(nèi)容。下一輪請(qǐng)求直接報(bào)上下文超限。從那以后我給自己定了一條硬規(guī)矩任何工具返回內(nèi)容寫入上下文之前必須經(jīng)過裁剪器。def clamp_text(text: str, max_lines: int 200, max_chars: int 6000) - str: lines text.splitlines() if len(lines) max_lines: lines lines[-max_lines:] return \n.join(lines) f\n[已截?cái)鄡H顯示末尾 {max_lines} 行] if len(text) max_chars: return text[-max_chars:] f\n[已截?cái)喑^ {max_chars} 字符] return text這個(gè)裁剪器很簡(jiǎn)單但它改變了整個(gè) harness 的可靠性。對(duì)成功的測(cè)試模型其實(shí)只需要看“PASS”“退出碼 0”這幾個(gè)字對(duì)失敗的測(cè)試它需要的是末尾的錯(cuò)誤摘要和 traceback 尾部。開頭幾百行通常是無用的環(huán)境信息全部保留只會(huì)稀釋模型的注意力。5.2 大文件修改用 apply_patch 而不是整個(gè)文件重寫早期我讓模型改代碼用的是write_file工具直接把整個(gè)新文件內(nèi)容寫給 harness。文件小的時(shí)候還好文件一旦超過一千行問題就來了模型很可能會(huì)在重寫過程中丟掉函數(shù)或者不小心把某段注釋改動(dòng)掉。而且整文件重寫也極度浪費(fèi) token——目標(biāo)只是改一行字段名卻要把整個(gè) 800 行的文件重新發(fā)一遍。更好的方案是引入apply_patch工具讓模型輸出一個(gè) unified diff由 harness 在本地應(yīng)用這個(gè) diff。這樣模型只需要給出改動(dòng)區(qū)域上下文消耗可能降到原來的十分之一。即便 diff 格式有問題沖突信息也可以轉(zhuǎn)換成錯(cuò)誤返回給模型讓模型重新生成更小的補(bǔ)丁。我在系統(tǒng)提示里放了一個(gè)簡(jiǎn)短示例告訴模型“下面是一個(gè)非常常見的 diff 格式請(qǐng)嚴(yán)格按照這個(gè)格式輸出”。Claude Code 內(nèi)部其實(shí)也采用了類似的編輯策略盡量做增量編輯而不是整文件覆蓋既省 token 又降低出錯(cuò)概率。5.3 歷史壓縮當(dāng) agent 開始“忘事”的時(shí)候即使做了工具輸出裁剪多輪之后的歷史仍然可能膨脹。我碰到的典型情況是前兩輪模型讀了三個(gè)文件第三輪跑測(cè)試第四輪改代碼第五輪又跑測(cè)試。到第六輪時(shí)前面讀過的文件內(nèi)容其實(shí)已經(jīng)被后續(xù)動(dòng)作替換了但一直留在歷史里。此時(shí)如果不做處理token 預(yù)算很快就爆。我后來加了一個(gè)簡(jiǎn)單的“壓縮策略”每完成一個(gè)明確的階段性動(dòng)作比如改完一個(gè)文件、跑完一輪測(cè)試就把最舊的一輪工具結(jié)果壓縮成一行摘要用類似[步驟 1-2] 讀取了 config.py發(fā)現(xiàn) retry 相關(guān)代碼在 45-60 行的句子替換原始內(nèi)容。這個(gè)壓縮動(dòng)作發(fā)生在 harness 層模型完全感知不到但它看到的歷史變得更緊湊。還有更激進(jìn)的辦法當(dāng)歷史長(zhǎng)度超過預(yù)設(shè)閾值直接讓模型自己寫一段“到目前為止完成情況和下一步計(jì)劃”然后用這段摘要替換掉先前全部對(duì)話。6. 復(fù)盤與進(jìn)階拿 Claude Code 當(dāng)尺子衡量我的 Harness把 toy harness 搭到這一步它在功能上已經(jīng)很接近一個(gè)小型 AI 編程助手了。但真正讓這套東西變得有價(jià)值的是自我對(duì)照。我會(huì)拿 Claude Code 的實(shí)際表現(xiàn)當(dāng)尺子一條一條對(duì)照看哪些我做對(duì)了哪些我可以直接模仿哪些未來值得繼續(xù)做深。6.1 功能差距對(duì)照表以下是我在某個(gè)階段做的對(duì)照表。注意這不是為了“追平”而是為了看清楚每個(gè)功能模塊組合出來的體驗(yàn)差異。維度我的 toy harnessClaude Code 的成熟表現(xiàn)我的結(jié)論循環(huán)控制單線程、固定上限支持多線程任務(wù)、長(zhǎng)時(shí)間運(yùn)行、可中斷核心循環(huán)思路一致但并發(fā)和控制信號(hào)做得更深工具數(shù)量4 到 5 個(gè)讀、寫、編輯、搜索、終端、代碼查詢等數(shù)量不是關(guān)鍵覆蓋場(chǎng)景才是權(quán)限模型allowlist 用戶確認(rèn)會(huì)話級(jí)權(quán)限、項(xiàng)目級(jí)白名單、可配置策略我的機(jī)制可用但粒度不夠細(xì)上下文管理裁剪器 歷史壓縮自動(dòng)壓縮、子對(duì)話隔離、分步任務(wù)記憶方向正確工程化程度差很多可觀測(cè)性JSONL 日志內(nèi)部有 trace 可視化我的日志方案更進(jìn)一步成為調(diào)試核心這張表不是給產(chǎn)品做 benchmark而是用來指導(dǎo)下一步開發(fā)。比如我發(fā)現(xiàn)“子對(duì)話隔離”這個(gè)能力很重要的時(shí)候就去查 Claude Code 在這一塊的設(shè)計(jì)思路然后回到自己的 harness 里實(shí)現(xiàn)一個(gè)粗版本把不同子任務(wù)的歷史分開存放。這個(gè)過程非常爽因?yàn)槟悴皇窃诔鸢付窃诶斫鉃槭裁葱枰@個(gè)答案。6.2 日志回放是我調(diào)試 Agent 循環(huán)的救命稻草單獨(dú)說一下可觀測(cè)性。沒有日志你根本沒法判斷一個(gè) agent 為什么行為異常。我記得有一次模型總是不執(zhí)行工具而是光說“我準(zhǔn)備做這件事”排查了很久最后發(fā)現(xiàn)是系統(tǒng)提示里“工具調(diào)用格式”的示例寫得不夠強(qiáng)讓模型產(chǎn)生了誤解。如果不是把每一輪的完整請(qǐng)求和響應(yīng)都記錄成 JSONL這個(gè)問題很可能會(huì)被我歸因到模型能力上而不是 harness 的提示設(shè)計(jì)上。我采用的日志格式很簡(jiǎn)單每個(gè)事件一行 JSON包含時(shí)間戳、步驟序號(hào)、消息角色、工具名、參數(shù)摘要、執(zhí)行結(jié)果 exit code、耗時(shí)、消耗 token 數(shù)。排查時(shí)用grep過濾某個(gè) step再按時(shí)間順序一口氣回放就能還原模型當(dāng)時(shí)看到的一切。調(diào)試 agent 時(shí)最重要的認(rèn)知就是把模型當(dāng)作一個(gè)需要完整上下文才能運(yùn)轉(zhuǎn)的系統(tǒng)你能看到多少上下文你就能定位多少問題。6.3 再往前走多 Agent、沙箱與流式輸出玩具項(xiàng)目到這里已經(jīng)可以收尾了但如果你想把這條路繼續(xù)走下去有幾個(gè)方向我認(rèn)為特別值得探索。多 Agent 是最自然的一個(gè)擴(kuò)展。把“規(guī)劃”和“執(zhí)行”分開一個(gè) Agent 只負(fù)責(zé)分析任務(wù)、拆解步驟、生成方案另一個(gè) Agent 只負(fù)責(zé)做具體文件修改和命令執(zhí)行。這樣做的好處是規(guī)劃 Agent 的上下文不會(huì)被工具輸出污染執(zhí)行 Agent 也不需要讀過所有說明文檔。子代理之間的通信接口需要固定我用的是 JSON 格式的“任務(wù)單結(jié)果單”本質(zhì)上又成了一層小 harness。沙箱是第二個(gè)方向。讓模型在容器或臨時(shí)目錄里執(zhí)行命令可以極大減少誤操作帶來的風(fēng)險(xiǎn)。雖然做容器封裝會(huì)有額外性能開銷但如果你準(zhǔn)備把這個(gè) harness 用在不可完全信任的輸入場(chǎng)景沙箱不是可選項(xiàng)而是必選項(xiàng)。流式輸出則是體驗(yàn)層面的提升把模型的思考過程和工具調(diào)用結(jié)果實(shí)時(shí)推到終端而不是等整個(gè)任務(wù)跑完才一次性顯示。真正常用的 AI 編程助手都會(huì)這么做因?yàn)樗屇愀杏X自己在“看著別人干活”而不是在黑盒等待。實(shí)現(xiàn)思路也不復(fù)雜只需要把call_backend換成支持流式回調(diào)的版本把事件分發(fā)到終端渲染層。說句實(shí)在話我第一次跑通這個(gè)玩具 harness 的時(shí)候最大的收獲不是“我會(huì)寫 agent 了”而是我終于能解釋清楚很多現(xiàn)象——為什么模型會(huì)反復(fù)改同一個(gè)錯(cuò)誤為什么強(qiáng)行塞進(jìn)太多上下文會(huì)讓它變笨為什么權(quán)限機(jī)制必須放在工具層而不是提示詞層。拆過一次再裝回去再看 Claude Code 就覺得它不再是黑盒而是一套我深刻理解工作原理、能預(yù)測(cè)它行為邊界的工具箱。如果你也在學(xué)習(xí)這類 AI 編程助手我的建議很簡(jiǎn)單不必一開始就追求完整功能先寫一個(gè)能跑通一個(gè)真實(shí)小任務(wù)的循環(huán)然后慢慢地往里面加測(cè)試反饋、權(quán)限確認(rèn)和上下文壓縮。每一步都值得。