1. 這個(gè)項(xiàng)目到底解決什么問題先說說我為什么會(huì)做這個(gè)東西。用過 Cursor、Copilot 這類編碼工具的都知道AI 補(bǔ)全代碼已經(jīng)不算新鮮事了真正卡脖子的是“AI 只能改代碼不能替你操作電腦”。你在 IDE 里讓它改個(gè)文件沒問題可一旦涉及“打開某個(gè) GUI 程序、點(diǎn)幾個(gè)按鈕、截個(gè)圖看看界面長什么樣、把結(jié)果同步給另一個(gè)工具”傳統(tǒng) Agent 基本就啞火了。我當(dāng)時(shí)手頭正好有這樣一個(gè)需求幫一個(gè)不太熟悉命令行的人做一個(gè)小工具需要自動(dòng)打開桌面軟件、讀取界面內(nèi)容、再按規(guī)則點(diǎn)擊操作。這活兒交給大模型本身不難難的是怎么讓大模型“看見”和“操作”圖形界面。這個(gè)項(xiàng)目就是我自己寫的一個(gè)免費(fèi) AI 編碼代理AI Coding Agent核心賣點(diǎn)有三個(gè)支持操控 GUI、支持 MCP、單文件運(yùn)行。意思是它不需要復(fù)雜的安裝流程一個(gè)文件拉下來就能跑它能把大模型的判斷能力接到圖形界面的點(diǎn)擊、輸入、讀取上它還能通過 MCPModel Context Protocol模型上下文協(xié)議跟外部工具、數(shù)據(jù)源對(duì)接把 AI 的能力延伸到代碼編輯之外的場景。如果你正在研究 AI Agent、想給自己的插件或工具加“電腦操作”能力或者單純被各種 Agent 框架繞得頭疼、想要一個(gè)能看懂源碼的輕量方案這個(gè)東西應(yīng)該能給你一些啟發(fā)。我會(huì)把整個(gè)項(xiàng)目的設(shè)計(jì)思路、技術(shù)選型、踩坑過程全部拆開講爭取你看完能照著思路自己搭一個(gè)差不多的。2. 整體設(shè)計(jì)思路與方案選型2.1 為什么是“單文件”而不是一個(gè)完整項(xiàng)目現(xiàn)在市面上 Agent 框架多如牛毛比如 AutoGPT、MetaGPT、微調(diào)的 SWE-Agent隨便拉一個(gè)出來都是成千上萬行代碼依賴一堆庫環(huán)境配置就能勸退一半人。我做這個(gè)事兒的出發(fā)點(diǎn)很簡單我想讓用戶下載一個(gè)腳本運(yùn)行之后立刻能用不要裝 Python 環(huán)境、不要配 API Key、不要讀幾十頁文檔。所以“單文件”對(duì)我來說不是炫技而是核心使用場景倒逼出來的設(shè)計(jì)約束。我做的第一版其實(shí)是個(gè)完整項(xiàng)目結(jié)構(gòu)是 src/、config/、tests/ 那種標(biāo)準(zhǔn)布局跑起來要先 pip install、再設(shè)置環(huán)境變量、再初始化配置結(jié)果我自己在另一臺(tái)干凈機(jī)器上試用時(shí)都費(fèi)了半天勁更別說普通用戶了。后來我做了個(gè)很激進(jìn)的決定把全部代碼塞進(jìn)一個(gè)文件里。這個(gè)決定帶來的直接好處是分發(fā)成本趨近于零。用戶只需要做一件事python agent.py。而代價(jià)也很明顯——代碼組織和可維護(hù)性變差了但只要控制好文件內(nèi)部的分區(qū)結(jié)構(gòu)比如用大段注釋把“GUI 控制模塊”“MCP 對(duì)接模塊”“LLM 交互模塊”隔開這問題完全可控。經(jīng)驗(yàn)單文件項(xiàng)目最適合工具型、演示型、教學(xué)型的 Agent不適合需要長期多人維護(hù)的大型系統(tǒng)。如果你的 Agent 定位是后者別學(xué)我。2.2 GUI 操控我是怎么讓 AI “看見”屏幕的讓 AI 操控 GUI 最核心的難點(diǎn)是讓大模型理解圖形界面當(dāng)前的狀態(tài)然后把它的決策翻譯成鼠標(biāo)鍵盤動(dòng)作。這需要兩件事截圖給模型看、動(dòng)作交給系統(tǒng)執(zhí)行。我選擇的技術(shù)棧是截圖用 mss 這個(gè)庫跨平臺(tái)、速度快實(shí)測截一屏大約 30ms比 PIL 的 ImageGrab 快不少。速度很關(guān)鍵因?yàn)?GUI 操作是一個(gè)“截圖-思考-動(dòng)作”的循環(huán)截圖太慢會(huì)拖慢整個(gè)節(jié)奏。界面元素定位一開始我想用純視覺方案就是直接讓多模態(tài)模型看截圖判斷該點(diǎn)哪里后來發(fā)現(xiàn)可靠性不夠。比如一個(gè)小按鈕在截圖里只有十幾個(gè)像素模型經(jīng)常點(diǎn)歪。于是我加了一層OpenCV 模板匹配和屏幕坐標(biāo)歸一化。簡單說給模型兩種信息整個(gè)屏幕的截圖、以及一組可交互元素的坐標(biāo)標(biāo)簽。模型只需要說“我要點(diǎn)擊按鈕A”我這邊把“按鈕A”映射到具體坐標(biāo)。動(dòng)作執(zhí)行Windows 上用 pyautoguimacOS 上用 Quartz 事件Linux 上用 xdotool這個(gè)沒有跨平臺(tái)的完美方案所以我做了一層抽象接口按操作系統(tǒng)分發(fā)。這里有一個(gè)非常重要的經(jīng)驗(yàn)千萬別把“讓 AI 完全自由地控制鼠標(biāo)”當(dāng)成第一版目標(biāo)。我最初試過完全開放的方式讓模型愛點(diǎn)哪點(diǎn)哪結(jié)果它能把設(shè)置界面點(diǎn)得亂七八糟甚至差點(diǎn)把系統(tǒng)音量拉滿。后來我改成了白名單步驟確認(rèn)的機(jī)制模型只能在用戶給定的應(yīng)用窗口內(nèi)操作每個(gè)動(dòng)作執(zhí)行前會(huì)把意圖輸出到控制臺(tái)用戶按回車確認(rèn)才執(zhí)行。這樣既保留了自動(dòng)化能力又不會(huì)出大亂子。2.3 MCP為什么值得專門接一層協(xié)議MCP 是最近很熱的協(xié)議標(biāo)準(zhǔn)簡單理解就是給 AI 模型一個(gè)統(tǒng)一的方式去調(diào)用外部工具。以前每個(gè) Agent 接一個(gè)工具就要寫一套專用代碼有了 MCP 之后那個(gè)工具只要提供一個(gè) MCP ServerAgent 就能動(dòng)態(tài)發(fā)現(xiàn)它能干什么、按規(guī)范調(diào)用它。我支持 MCP 的動(dòng)機(jī)很直接我不想只為“操控 GUI”這一個(gè)功能寫死 API。GUI 操作只是這個(gè) Agent 的能力之一用戶可能還需要讓它查數(shù)據(jù)庫、讀文件、調(diào)瀏覽器、發(fā)請(qǐng)求。這些能力如果都靠我硬編碼那工作量沒上限而且每加一個(gè)功能就要重新發(fā)一版。MCP 把這個(gè)問題優(yōu)雅地解決了。實(shí)現(xiàn)的方案是把 MCP Server 的調(diào)用封裝成統(tǒng)一的工具接口Agent 在啟動(dòng)時(shí)加載一個(gè)配置文件里面可以聲明要連接哪些 MCP Server。每個(gè) Server 暴露的方法被自動(dòng)注冊(cè)為 Agent 的“可調(diào)工具”。比如有一個(gè) MCP Server 可以操作瀏覽器那 Agent 的消息循環(huán)里就多了一個(gè)“open_url”“click_element”這樣的工具。MCP 的語義特別像“USB-C 接口”——各種設(shè)備不管內(nèi)部怎么實(shí)現(xiàn)只要按統(tǒng)一規(guī)范接上就能用。這大大提高了我的 Agent 的擴(kuò)展性也讓它可以混用不同生態(tài)下的現(xiàn)成工具而不是重復(fù)造輪子。2.4 技術(shù)棧和核心依賴除了上面提到的截圖和 GUI 工具庫整個(gè)項(xiàng)目骨架是 Python。選 Python 不光是生態(tài)成熟還有一個(gè)重要原因這種 Agent 的核心邏輯是“循環(huán)調(diào)用 LLM-執(zhí)行工具-觀察結(jié)果-再調(diào) LLM”Python 寫這種膠水代碼最順手。核心依賴清單openai或兼容 OpenAI 接口的 SDK用來請(qǐng)求大模型接口支持本地模型如 Ollama、vLLM 等mss截圖pyautogui/Quartz/xdotool控制鼠標(biāo)鍵盤Pillow處理圖像opencv-python模板匹配和元素定位jsonsubprocessosplatformPython 自帶庫處理配置和系統(tǒng)交互整個(gè)文件大約 1200 行內(nèi)部結(jié)構(gòu)分四段配置區(qū)、GUI操作類、MCP客戶端封裝、Agent主循環(huán)。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 單文件里的模塊劃分我是怎么不把自己繞暈的如果你以為單文件就是把所有代碼從頭寫到尾那就錯(cuò)了很快就會(huì)陷入改一處壞三處的泥潭。我的做法是在文件里用非常清晰的分區(qū)注釋把它當(dāng)成一個(gè)“偽多文件”項(xiàng)目# # [Section 1] 全局配置解析 (僅供參考保留原始代碼的學(xué)生可照著分塊) # # [Section 2] GUI 自動(dòng)化操作類 # # [Section 3] MCP Client 封裝 # # [Section 4] Agent 主邏輯 # 每個(gè) Section 內(nèi)部保持內(nèi)聚Section 之間只通過少數(shù)幾個(gè)接口函數(shù)交互。這里的關(guān)鍵點(diǎn)是接口要盡量窄。比如 GUI 操作類對(duì)外只暴露三個(gè)方法capture_screen(),get_element_coordinates(description),perform_action(action)。MCP 模塊對(duì)外只暴露load_server(config)和call_tool(server_name, tool_name, args)。這樣即使整個(gè)文件有上千行實(shí)際牽一發(fā)而動(dòng)全身的鏈路非常短。3.2 大模型的工具調(diào)用循環(huán)怎么做Agent 主循環(huán)是整個(gè)文件的核心邏輯上跟 OpenAI Function Calling 的標(biāo)準(zhǔn)模式一致把系統(tǒng)提示詞、歷史消息、當(dāng)前工具定義一起發(fā)給大模型大模型返回兩種結(jié)果之一一段最終回答或者一個(gè)工具調(diào)用請(qǐng)求如果是工具調(diào)用我從本地函數(shù)映射表里找到對(duì)應(yīng)實(shí)現(xiàn)執(zhí)行把結(jié)果作為新消息追加回到第 1 步繼續(xù)直到模型給出最終回答理解這個(gè)循環(huán)是理解一切 Agent 的鑰匙。很多初學(xué)者第一次寫 Agent 容易犯一個(gè)錯(cuò)只發(fā)一次請(qǐng)求拿到結(jié)果就用完全沒想過“工具調(diào)用后還需要把觀察結(jié)果送回模型”這一步。沒有第二步的“行動(dòng)-觀察”循環(huán)模型就永遠(yuǎn)無法基于工具執(zhí)行結(jié)果做進(jìn)一步推理Agent 跟一個(gè)普通的 API 調(diào)用就沒區(qū)別了。舉個(gè)例子。我讓 Agent 幫我查一下當(dāng)前目錄有哪些 Python 文件然后對(duì)其中一個(gè)做語法檢查。正確流程是模型先調(diào)用工具list_files拿到目錄列表我把它作為工具結(jié)果傳回給模型模型看到test.py存在再調(diào)用run_compile_check拿到結(jié)果后模型才能給出最終判斷。如果只發(fā)一次請(qǐng)求模型會(huì)直接猜測文件名然后給出一個(gè)假結(jié)果這在 GUI 場景下就是災(zāi)難——它可能覺得自己已經(jīng)點(diǎn)了按鈕實(shí)際上什么都沒發(fā)生。3.3 GUI 元素定位從“看圖猜位置”到“邊界框標(biāo)注”需要操控 GUI 時(shí)我的 Agent 并不是直接把原生截圖丟給大模型而是先做一層預(yù)處理。具體流程是用 mss 截取當(dāng)前屏幕對(duì)窗口圖片做一次顏色分析和輪廓檢測并把檢測到的可能是按鈕、輸入框、圖標(biāo)的區(qū)域用紅色矩形框標(biāo)注把每個(gè)標(biāo)注框按順序編號(hào)同時(shí)輸出一份 JSON 描述“編號(hào) 1位置 (120, 300)大小 (80x30)顏色偏灰推測是按鈕”把標(biāo)注后的截圖和 JSON 一起發(fā)給模型這個(gè)方案比純視覺方案好在哪大模型不需要自己數(shù)像素坐標(biāo)了它只需要說“點(diǎn)編號(hào) 3”或者“在編號(hào) 5 的輸入框里填寫 xxx”。把坐標(biāo)空間折疊成語義標(biāo)簽是提升 GUI Agent 可靠性最有效的一招。實(shí)際使用中點(diǎn)擊準(zhǔn)確率從裸視覺方案的 60% 左右提升到了 90% 以上。但這里也有一個(gè)必須先解決的坑分辨率和縮放問題。Windows 上如果開啟了 125% 或 150% 顯示縮放pyautogui 拿到的坐標(biāo)和截圖里的像素坐標(biāo)對(duì)不上點(diǎn)擊會(huì)偏移。我的做法是在程序啟動(dòng)時(shí)調(diào)用ctypes.windll.shcore.GetScaleFactorForDevice(0)拿到縮放比然后把所有坐標(biāo)統(tǒng)一換算成物理像素?？s放比截圖邏輯坐標(biāo)pyautogui 物理坐標(biāo)最終換算100%1920x10801920x1080不處理125%1536x8641920x1080乘以 1.25150%1280x7201920x1080乘以 1.5這玩意兒看著簡單踩過一次才知道多疼——辛辛苦苦把點(diǎn)擊邏輯調(diào)通了換臺(tái)電腦又全歪排查半天發(fā)現(xiàn)是縮放設(shè)置換了。3.4 MCP 對(duì)接的配置約定MCP 部分我設(shè)計(jì)得很輕。配置文件是一個(gè) JSON里面列出要連接的 Server 名稱、啟動(dòng)命令和相關(guān)參數(shù){ mcp_servers: [ { name: browser_tool, command: npx, args: [-y, some/mcp-browser-server], env: {API_KEY: 12345} } ] }啟動(dòng)時(shí)依次拉起這些進(jìn)程通過標(biāo)準(zhǔn)輸入輸出 JSON-RPC 消息完成通信。這個(gè)方案需要的代碼量不大關(guān)鍵是消息分包——MCP 走的是 stdio多條 JSON-RPC 消息可能會(huì)粘包必須根據(jù) Content-Length 頭來分包。def read_message(stream): headers {} while True: line stream.readline() if line in (b\r\n, b\n, b): break key, _, value line.decode().partition(:) headers[key.strip().lower()] value.strip() length int(headers.get(content-length, 0)) body stream.read(length) if length else b return json.loads(body)這個(gè)細(xì)節(jié)很多人會(huì)忽略但它是 MCP 客戶端最容易出錯(cuò)的地方。如果你覺得這一段看得有點(diǎn)累可以先跳過用現(xiàn)成的mcpPython SDK但在單文件實(shí)現(xiàn)里我寧愿自己寫省得引入一個(gè)大依賴。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 從頭搭建一個(gè)最小可運(yùn)行的 Agent 骨架我不想空口講原理直接給一套最小實(shí)現(xiàn)。下面這個(gè)骨架大約 150 行跑通后你就擁有一個(gè)支持工具調(diào)用的 Agent 雛形然后再往上加 GUI 和 MCP 能力。import json import sys from openai import OpenAI client OpenAI(api_keyYOUR_KEY, base_urlYOUR_BASE_URL) tools [ { type: function, function: { name: run_shell, description: Run a shell command and return output, parameters: { type: object, properties: { cmd: {type: string, description: command to run} }, required: [cmd] } } } ] def run_shell(cmd): import subprocess result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue, timeout10) return result.stdout result.stderr def agent_loop(user_query): messages [{role: user, content: user_query}] while True: response client.chat.completions.create( modelgpt-4o, messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message if not msg.tool_calls: print(最終回答:, msg.content) break messages.append(msg) for call in msg.tool_calls: if call.function.name run_shell: args json.loads(call.function.arguments) result run_shell(args.get(cmd, )) messages.append({ role: tool, tool_call_id: call.id, content: result }) if __name__ __main__: agent_loop(sys.argv[1] if len(sys.argv) 1 else 請(qǐng)列出當(dāng)前目錄的文件)這段代碼跑通以后你就具備了一個(gè)最基礎(chǔ)的 Agent 循環(huán)。很多人在這個(gè)階段會(huì)犯一個(gè)致命錯(cuò)誤把工具執(zhí)行結(jié)果直接 print 出來給用戶看然后重新把結(jié)果拼到用戶輸入里再發(fā)一次請(qǐng)求。千萬不要這樣。正確做法是原封不動(dòng)的工具調(diào)用 ID、角色“tool”這樣模型才能正確對(duì)應(yīng)“哪個(gè)工具、返回了什么結(jié)果”。4.2 接入 GUI 截圖與點(diǎn)擊能力下一步是把 GUI 能力加進(jìn)這個(gè)循環(huán)。我要做的不是改變循環(huán)結(jié)構(gòu)而是新增兩個(gè)工具screenshot_now和click_on_screen。先做截圖工具。關(guān)鍵點(diǎn)是初始化時(shí)只創(chuàng)建一次 mss 實(shí)例不要每次截圖都重新初始化否則性能很差。import mss sct mss.mss() def screenshot_now(): monitor sct.monitors[1] img sct.grab(monitor) from PIL import Image img Image.frombytes(RGB, img.size, img.rgb) img.save(screen.png) return 已保存截圖到 screen.png下次對(duì)話將基于此圖分析截圖保存好后為了讓模型能“看見”圖我把圖片以 base64 形式作為一條 image 消息送入對(duì)話同時(shí)附上工具提示說 “請(qǐng)描述圖中你看到的界面內(nèi)容并告訴我如果要點(diǎn)擊某個(gè)按鈕它在哪個(gè)編號(hào)區(qū)域?！闭嬲暮皿w驗(yàn)來自結(jié)合前面的邊界框標(biāo)注。這里我給一個(gè)稍微完整一點(diǎn)的實(shí)現(xiàn)思路實(shí)際上就是四步截屏保存為screen.png用 OpenCV 找輪廓畫出所有可能區(qū)域的邊界框保存為screen_annotated.png讀取標(biāo)注框的坐標(biāo)和編號(hào)生成可發(fā)給模型的文本描述把screen_annotated.png和文本描述一起發(fā)給多模態(tài)模型import cv2 def annotate_screen(path): img cv2.imread(path) gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) edges cv2.Canny(gray, 50, 150) contours, _ cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) boxes [] for i, cnt in enumerate(contours[:20]): x, y, w, h cv2.boundingRect(cnt) # 過濾掉太小的噪聲區(qū)域 if w 20 or h 20: continue cv2.rectangle(img, (x, y), (xw, yh), (0, 0, 255), 2) cv2.putText(img, str(len(boxes)), (x, y-5), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 255), 2) boxes.append((x, y, w, h)) annotated screen_annotated.png cv2.imwrite(annotated, img) description [ {id: i, bbox: [x, y, w, h]} for i, (x, y, w, h) in enumerate(boxes) ] return annotated, description點(diǎn)擊動(dòng)作就簡單了import pyautogui def click_on_screen(x, y): pyautogui.click(x, y) return 已執(zhí)行點(diǎn)擊這里要提醒一下多模態(tài)模型對(duì)截圖的分析不是瞬時(shí)完成的如果截圖內(nèi)容比較復(fù)雜比如整個(gè)桌面模型的分析質(zhì)量會(huì)明顯下降。我在實(shí)際使用中的體會(huì)是讓它分析“某個(gè)特定窗口”比分析“整個(gè)屏幕”靠譜得多。所以后續(xù)版本里我加了一個(gè)窗口前置捕獲邏輯先通過win32gui.FindWindow找到目標(biāo)窗口句柄再只截取這個(gè)窗口區(qū)域效果好了不少。4.3 把 MCP Server 掛載為 Agent 工具等 GUI 能力穩(wěn)定了我再把 MCP 部分接進(jìn)來。這里不從頭實(shí)現(xiàn)協(xié)議細(xì)節(jié)了我直接用mcpPython SDK 把啟動(dòng)和調(diào)用封裝成一個(gè)工具類偽代碼如下from mcp.client.stdio import stdio_client class MCPToolWrapper: def __init__(self, config): self.server stdio_client(config[command], config[args]) def discover_tools(self): return self.server.list_tools() def call(self, tool_name, args): return self.server.call_tool(tool_name, args)在 Agent 主循環(huán)里我啟動(dòng)時(shí)遍歷配置文件里的所有 MCP Server把每個(gè) Server 暴露的工具都注冊(cè)到 tools 數(shù)組里。這樣模型在整個(gè)對(duì)話過程中就能自由選擇調(diào)用范圍不再局限于我預(yù)先寫死的幾個(gè)函數(shù)。這里有一個(gè)特別好的“化學(xué)反應(yīng)”MCP 和 GUI 能力疊加后Agent 才能完成真正意義上的“電腦操作閉環(huán)”。比如我可以讓 Agent 通過 MCP 調(diào)用瀏覽器工具去查某個(gè)網(wǎng)站的接口文檔然后根據(jù)文檔內(nèi)容用 GUI 工具在本地軟件里執(zhí)行對(duì)應(yīng)操作最后再把結(jié)果同步到另一個(gè) MCP 對(duì)接的數(shù)據(jù)系統(tǒng)里。這不是多個(gè)功能的簡單堆疊而是一個(gè)跨系統(tǒng)的自動(dòng)化流水線。4.4 實(shí)操現(xiàn)場記錄一個(gè)完整的任務(wù)演示為了讓你有更直觀的感受我把一次完整的實(shí)操過程記錄下來。假設(shè)目標(biāo)是自動(dòng)打開一個(gè)本地小工具讀取窗口上的三個(gè)數(shù)字然后求和將結(jié)果寫入一個(gè)文本文件。第一步啟動(dòng) Agent輸入任務(wù)描述。第二步Agent 調(diào)用 MCP 工具find_window定位目標(biāo)窗口得到窗口坐標(biāo)。第三步Agent 調(diào)用screenshot_now截取目標(biāo)窗口加上邊界框標(biāo)注后通過視覺模型識(shí)別出三個(gè)數(shù)字的位置輸出 JSON。{ok: true, numbers: [ {value: 12, bbox: [180, 220, 90, 40]}, {value: 23, bbox: [310, 220, 90, 40]}, {value: 45, bbox: [440, 220, 90, 40]} ]}第四步Agent 調(diào)用 Python 計(jì)算 12234580。第五步Agent 調(diào)用工具write_file把 80 寫入result.txt。整個(gè)過程沒有寫一行針對(duì)這個(gè)應(yīng)用的專用代碼這在我看來就是 Agent 的意義——它作為一個(gè)通用執(zhí)行框架通過工具的組合完成了一個(gè)原本需要定制腳本的任務(wù)。你可以把這個(gè)思路平移到任何你自己的場景里桌面應(yīng)用自動(dòng)化、瀏覽器輔助操作、Excel 數(shù)據(jù)整理、批量文件處理等。5. 常見問題與排查技巧實(shí)錄5.1 模型“假執(zhí)行”它說點(diǎn)過了實(shí)際沒點(diǎn)這是我在整個(gè)項(xiàng)目開發(fā)過程中遇到最多、也最坑的問題?，F(xiàn)象是模型在回復(fù)里自信地說“已點(diǎn)擊完成”但界面上什么事情都沒發(fā)生。原因很簡單——模型只是在生成文本并沒有真正觸發(fā)我的工具函數(shù)。這個(gè)問題的根源通常是兩種情況第一工具調(diào)用參數(shù)格式錯(cuò)誤比如模型的工具調(diào)用里把參數(shù)寫成嵌套 JSON 或者有空字段我的解析函數(shù)沒兜住直接跳過了執(zhí)行。排查辦法是把response.choices[0].message原始輸出 dump 出來看而不是只看最終回復(fù)。第二循環(huán)寫成了單輪。也就是說模型請(qǐng)求了工具調(diào)用但我的代碼沒有把工具結(jié)果追加回消息列表里繼續(xù)對(duì)話而是直接把模型那句“已點(diǎn)擊”當(dāng)成了最終輸出給出去了。這種錯(cuò)誤常見的表現(xiàn)就是LLM 自己編造一個(gè)工具調(diào)用的敘事實(shí)際函數(shù)從沒被調(diào)用。解決方法是嚴(yán)格檢查消息歷史里是否存在role: tool的記錄。5.2 坐標(biāo)偏移截圖坐標(biāo)和真實(shí)光標(biāo)位置不一致除了前面提到的顯示器縮放率問題還有一個(gè)容易被忽略的坑任務(wù)欄和窗口裝飾邊框。截圖工具截取的是整個(gè)虛擬屏幕區(qū)域而 pyautogui 的坐標(biāo)體系是從主顯示器左上角開始計(jì)算的。如果機(jī)器接了雙顯示器這個(gè)偏移會(huì)更復(fù)雜。我的排查技巧是在點(diǎn)擊之前先做一次“光標(biāo)回顯測試”。讓程序在目標(biāo)坐標(biāo)畫一個(gè)十字光標(biāo)或者移動(dòng)鼠標(biāo)過去然后截圖確認(rèn)這個(gè)位置和模型認(rèn)為的按鈕位置是否一致。如果差幾個(gè)像素多半是縮放問題如果差一個(gè)屏幕寬度多半是雙顯示器布局問題。5.3 MCP Server 啟動(dòng)失敗或通信超時(shí)這類問題最常見的表現(xiàn)是Agent 啟動(dòng)時(shí)卡住或者調(diào)用某個(gè) MCP 工具時(shí)報(bào) timeout。我排查的順序是手動(dòng)在終端執(zhí)行配置里的command和args看有沒有報(bào)錯(cuò)。很多 MCP Server 是 npx 啟動(dòng)第一次會(huì)下載依賴慢得很容易導(dǎo)致超時(shí)。檢查 MCP Server 的 SDK 版本和我的 SDK 版本是否兼容。尤其是 stdio 傳輸方式版本不匹配會(huì)出現(xiàn)握手失敗。加上日志輸出把 MCP 收到的原始消息打印到文件里。很多問題是消息格式不符合規(guī)范導(dǎo)致的看到原始消息就明白了。注意MCP 的 stdio 模式在 Windows 上有一個(gè)特殊問題就是換行符。Server 端如果用的是 LFWindows 下可能因?yàn)楣艿捞幚聿町悓?dǎo)致消息讀不到。我最后的解決辦法是不依賴 MCP SDK 的底層管道直接用 subprocess 的 PIPE手動(dòng)按\n分割兼容性好了很多。5.4 常見問題速查表問題可能原因解決辦法模型說已點(diǎn)擊但界面無反應(yīng)單輪循環(huán)、參數(shù)解析失敗檢查消息歷史確保 tool_calls 被正確回傳點(diǎn)擊位置偏移顯示器縮放比、雙屏坐標(biāo)啟動(dòng)時(shí)讀取縮放系數(shù)統(tǒng)一坐標(biāo)換算MCP 調(diào)用超時(shí)Server 首次啟動(dòng)慢或握手失敗手動(dòng)啟動(dòng) Server 驗(yàn)證調(diào)大超時(shí)時(shí)間圖片發(fā)不進(jìn)去多模態(tài)接口參數(shù)格式不對(duì)檢查圖片 base64 編碼和 content 字段格式截圖全黑目標(biāo)窗口最小化或被遮擋先恢復(fù)窗口再截取窗口區(qū)域Agent 答非所問工具描述不清晰重寫工具 description寫明參數(shù)含義和用途5.5 避坑技巧給工具命名和描述的藝術(shù)很多人寫 Agent 時(shí)忽略了一個(gè)關(guān)鍵點(diǎn)工具的name和description對(duì)模型的行為影響極大。模型是通過描述來理解“這個(gè)工具什么時(shí)候該用”的。如果描述寫得太含糊比如“用于執(zhí)行操作”模型就會(huì)在完全無關(guān)的場合也亂調(diào)用它。我現(xiàn)在的習(xí)慣是給每個(gè)工具寫一段“什么時(shí)候用、什么時(shí)候不用”的說明。舉個(gè)例子description: 截取當(dāng)前活動(dòng)窗口截圖返回圖片路徑。 當(dāng)用戶需要查看圖形界面內(nèi)容時(shí)使用。 如果沒有活動(dòng)窗口或需要獲取后臺(tái)數(shù)據(jù)不要使用此工具。這個(gè)改動(dòng)看起來不起眼但實(shí)實(shí)在在地提升了工具的調(diào)用準(zhǔn)確率。Agent 工具描述是給 LLM 看的文檔不是給程序員看的注釋要多寫意圖少寫實(shí)現(xiàn)細(xì)節(jié)。6. 從單文件項(xiàng)目到通用 Agent 的經(jīng)驗(yàn)沉淀這套東西做完之后我最大的感受是單文件 Agent 不是什么玩具而是一種很好的“最小可行產(chǎn)品”形態(tài)。它逼著你做減法把真正需要的邏輯留下來把花里胡哨的抽象剝離掉最后剩下的核心循環(huán)其實(shí)就是“解析模型意圖—調(diào)用工具—觀察結(jié)果—再喂回模型”這一個(gè)簡單模式。如果你也想做類似的事情我的建議是不要從框架開始從最簡單的while True tools循環(huán)開始跑通了再加功能。GUI 自動(dòng)化一定要做安全護(hù)欄白名單和人工確認(rèn)不是可選項(xiàng)是必須項(xiàng)。MCP 集成不用一步到位先用兩個(gè) Server 打通鏈路再擴(kuò)展。日志是最重要的調(diào)試工具尤其是在單文件項(xiàng)目里沒有日志的話出問題只能靠猜。最后分享一個(gè)小技巧給 Agent 加一個(gè)“自省”能力。在系統(tǒng)提示詞里明確告訴模型當(dāng)工具調(diào)用失敗時(shí)要主動(dòng)把失敗信息帶進(jìn)下一輪對(duì)話而不是假裝成功。這個(gè)簡單的指令能避免大量“假執(zhí)行”類的問題。我在自己的項(xiàng)目里加了這段話之后整體可靠性提升非常明顯。做完這個(gè)項(xiàng)目再回頭看命令行里的 AI 寫代碼只是冰山一角真正有價(jià)值的是把這些代碼世界和圖形世界、協(xié)議世界打通。單文件只是個(gè)分發(fā)形式但把“大模型—GUI—工具協(xié)議”串成一條線的思路才是這個(gè)項(xiàng)目讓我最興奮的地方。