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