1. 為什么我要做一個“會動手”的AI編碼代理我一直有個很煩的點大多數(shù)AI編碼代理都是“終端里的啞巴”你讓它改代碼、跑測試、查日志它干得確實不賴但一旦涉及圖形界面上的操作它基本就抓瞎了。我平時的工作流里有一大堆事情是繞不開GUI的比如打開一個桌面端的數(shù)據(jù)庫工具連上測試庫看數(shù)據(jù)、在Figma里按注釋調(diào)整標注、在瀏覽器的可視化頁面上點點菜單、在IDE里用鼠標調(diào)個斷點。這些事情你說它有多難真不難但讓編碼代理去做它只能干瞪眼。命令行工具確實覆蓋了很大一部分自動化場景但現(xiàn)實世界不全是終端。尤其我這種經(jīng)常要跟各種內(nèi)部系統(tǒng)、可視化工具打交道的場景最理想的狀態(tài)是我對AI說一句“去把那個接口測試一下把返回結(jié)果截圖給我看”然后它自己打開GUI、操作鼠標鍵盤、看屏幕反饋、分析結(jié)果全流程跑完。市面上的工具不是沒有類似的思路但大多要么閉源收費要么重度依賴云端環(huán)境要么要裝一大堆運行時和依賴折騰半天還沒跑起來。所以我花了一個周末的時間自己動手做了一個輕量級的AI編碼代理。它不是一個云端套殼服務(wù)也不是幾十個文件的項目工程就一個單文件免費的你拿到手就能跑。核心能力有兩塊一是能看屏幕、模擬鼠標鍵盤真正“操作”圖形界面二是支持MCP可以把外部工具統(tǒng)一接進來讓代理的能力不局限于我自己寫死的那幾個函數(shù)。我給它定的設(shè)計目標是這么幾條單文件運行不用依賴虛擬環(huán)境、不用安裝復雜的SDK包拿到手直接執(zhí)行就完事免費代碼開源模型調(diào)用部分你用自己的API Key甚至也可以用本地模型能操控GUI截屏、解析屏幕內(nèi)容、執(zhí)行點擊和輸入這條路必須跑通接入MCP不用自己重復造輪子能用統(tǒng)一的接口調(diào)用現(xiàn)成的MCP工具服務(wù)。這篇文章不是我做完之后的“展示型總結(jié)”而更接近一份把從需求到實現(xiàn)、再到踩坑的過程完整梳理的實戰(zhàn)記錄?？赐曛竽悴粌H能理解它的整體架構(gòu)也能直接用同樣的思路自己復刻一個。如果你正好需要一個能干活、能看屏幕的編碼代理這篇應(yīng)該幫得上忙。2. 單文件設(shè)計為什么不讓它散成一地依賴做這類工具的人第一反應(yīng)往往是建個工程目錄把視覺模塊、動作執(zhí)行模塊、模型調(diào)用模塊、MCP客戶端拆成一個個子目錄再配上依賴清單。但我的選擇恰恰相反整個項目就壓成一個文件。這個選擇不是偷懶而是有意為之。2.1 單文件的好處被低估了單文件最直接的價值是分發(fā)成本為零。我可以把文件傳到任何一臺機器上只要有Python環(huán)境和對應(yīng)的基礎(chǔ)依賴就能跑不用克隆倉庫、不用解決依賴沖突、不用關(guān)心包版本。對于這種“代理工具”來說能在一個環(huán)境里快速跑起來價值比代碼結(jié)構(gòu)上的優(yōu)雅重要得多。還有一點是可驗證性。一個文件讓使用者信任成本大幅降低——你不用逐個目錄審查代碼一個文件展開就能看完所有邏輯。很多工具做出來沒人敢用就是因為黑盒感太強。單文件至少意味著透明。從調(diào)試角度講單文件也更方便。出了問題你直接打開文件搜函數(shù)就能定位跨文件跳來跳去反而容易繞暈。我理想中的這個項目形態(tài)應(yīng)該像一個“瑞士軍刀”體積不大但功能都在壞了也好修。2.2 核心模塊是怎么塞進一個文件里的整個文件內(nèi)部雖然沒有物理拆分但邏輯上被我分成了清晰的幾層。按我的設(shè)計大概是這樣# agent_solo.py 核心結(jié)構(gòu)示意 # # 模塊一視覺層負責屏幕截圖與圖像預(yù)處理 # 模塊二模型層負責調(diào)用多模態(tài)大模型解析屏幕圖像并生成動作 # 模塊三執(zhí)行層負責把模型返回的動作指令映射為系統(tǒng)級鼠標鍵盤操作 # 模塊四MCP層負責與MCP工具服務(wù)器通信統(tǒng)一獲取外部能力 # 模塊五循環(huán)調(diào)度把上述模塊串成一個“感知-決策-執(zhí)行”的閉環(huán)你可能會覺得這不就是分層架構(gòu)的微型版嘛。對架構(gòu)思想沒有變只是實現(xiàn)上不做物理拆分。在這個文件里每一層大概對應(yīng)一個類或一組函數(shù)代碼量的分配大概是模型調(diào)用和Prompt拼裝占三成執(zhí)行層占兩成MCP通信占兩成視覺層占兩成剩下的是主循環(huán)和輔助工具函數(shù)。這種設(shè)計最關(guān)鍵的好處是當你需要改一個行為時你非常清楚它在這條主循環(huán)鏈路的哪個位置。比如模型老是點錯位置你會去看視覺層MCP工具返回超時你會去看MCP層的重試邏輯鼠標連點沒有響應(yīng)你會去查執(zhí)行層的動作間隔。2.3 依賴取舍的底線雖然我追求輕量但完全不依賴第三方庫是不現(xiàn)實的。我的原則是盡量把依賴控制在一個相對合理的范圍內(nèi)。模型調(diào)用大多數(shù)局域網(wǎng)內(nèi)能跑通的接口直接用HTTP請求就夠了不封裝SDK屏幕截圖如果用純標準庫我只能截取整個屏幕再手動轉(zhuǎn)格式很折騰這里我會用一個輕量的截圖庫GUI操作負責模擬鼠標和鍵盤的庫是必須的它是執(zhí)行層的物理基礎(chǔ)。實際上我把依賴數(shù)量控制在個位數(shù)而且都是常見、穩(wěn)定的基礎(chǔ)庫。這帶來的直接體驗就是拷過去的機器基本不用額外折騰環(huán)境跑不起來的情況極少。提示單文件不等于代碼質(zhì)量可以打折。反而因為所有代碼擠在一起更要重視函數(shù)邊界和命名清晰。不然改到第三周你自己打開文件都要做心理建設(shè)。3. GUI操控鏈路怎么讓模型真正“看見”并操作屏幕這一節(jié)是整個項目最核心的部分。編碼代理能“操控GUI”本質(zhì)上要做三件事看采集屏幕信息、想決定下一步動作、做把決策變成操作。聽起來簡單但每一步都有坑。3.1 視覺回路的搭建先說“看”。我的方案是周期性截屏把當前屏幕圖像發(fā)給多模態(tài)模型。這其實是目前比較通用的做法我選擇它不是因為它最優(yōu)雅而是它是適用范圍最廣的路徑。為什么不直接用可訪問性樹或者DOM解析因為GUI的世界太多樣了瀏覽器里的網(wǎng)頁有DOM原生桌面應(yīng)用有獨立的控件樹截圖里的普通軟件什么都沒有。想通吃所有GUI視覺方案是唯一能保障“萬物皆可操作”的路徑。你截個圖如果用的是多模態(tài)大模型它天然就能理解當前屏幕上是什么界面、有哪些按鈕、大概在什么位置。截屏這里有個細節(jié)值得說分辨率與縮放?，F(xiàn)代操作系統(tǒng)普遍有顯示縮放截出來的圖和真實邏輯坐標不一定一一對應(yīng)。我第一次測試時模型看截圖說“點擊右上角那個按鈕”返回的坐標在截圖里是對的但真正執(zhí)行鼠標點擊時卻偏了很遠。原因是Windows的長城縮放比如150%導致坐標映射錯位。后來我在執(zhí)行層里加了一步坐標換算把截圖坐標乘以縮放系數(shù)問題才徹底解決。下面是視覺回路的核心循環(huán)代碼可以簡化為def run_once(): # 1. 截取當前屏幕 screenshot capture_screen() # 2. 將截圖加上任務(wù)描述與歷史上下文一起發(fā)給多模態(tài)模型 response vision_model.chat( images[screenshot], promptbuild_action_prompt(current_task, last_action_result) ) # 3. 解析模型返回的動作描述 action parse_action(response) # 4. 執(zhí)行動作 execute_action(action) # 5. 等待片刻重新截屏以觀察界面變化 sleep(0.8)這個循環(huán)看起來簡單但真正重要的是第二步的Prompt設(shè)計。3.2 動作協(xié)議讓模型“說人話”還不夠得讓它說“結(jié)構(gòu)化的話”模型不能只回復“我點擊了確認按鈕”這種自然語言。我需要對它的輸出做嚴格約束讓它返回一個結(jié)構(gòu)化的動作指令方便程序直接執(zhí)行。我定義的動作協(xié)議大概長這樣{ reasoning: 當前彈窗提示確認保存點擊確定按鈕, action: click, x: 860, y: 345, parameter: }這個協(xié)議支持的動作類型包括click指定坐標左鍵單擊input在指定位置輸入文本parameter字段放文本內(nèi)容keypress模擬鍵盤按鍵比如CtrlSparameter放組合鍵描述scroll滾動鼠標滾輪方向和距離放在parameter里finish認為任務(wù)已完成終止循環(huán)。之所以用“坐標類型”模型是為了把理解交給模型、把執(zhí)行留給程序。模型從截圖里解讀語義定位到坐標程序只負責忠實地移動鼠標、執(zhí)行點擊輸入。兩者分工明確不越界。3.3 執(zhí)行與驗證一次點擊不代表任務(wù)完成真正讓這個代理“靠譜”起來的是執(zhí)行后的驗證機制。很多類似的工具容易犯的毛病是打一下沒看結(jié)果就認為這一步成功了結(jié)果后續(xù)全亂套。我的處理方式是每次執(zhí)行完動作后先截屏把模型的操作結(jié)果作為下一輪Prompt的一部分反饋給模型。模型看到界面變化后自己判斷“這個操作是否生效、是否已經(jīng)完成任務(wù)”。如果不生效它會嘗試換一種方式如果連續(xù)幾次都沒效果它會記錄失敗原因并選擇放棄或重試。我曾經(jīng)用這個代理做過一個測試任務(wù)“在瀏覽器里打開一個本地網(wǎng)頁填寫表單并提交”。第一次跑的時候模型正確輸入了表單內(nèi)容但提交后頁面沒刷新——原因是它點擊的提交按鈕上方有一個廣告遮罩層實際點擊被吃掉了。有意思的是模型在執(zhí)行完并重新截屏后自己發(fā)現(xiàn)頁面沒有變化隨后自動把鼠標稍微偏移了一下再次點擊這次頁面刷新成功了。這讓我意識到GUI代理的可能性不取決于它第一下點得多準而取決于它有沒有“看完結(jié)果再決定下一步”的閉環(huán)能力。只要驗證閉環(huán)在模型就有機會自我糾錯。4. MCP接入把外部工具統(tǒng)一成可調(diào)用的接口做編碼代理的都知道模型能力再強不能調(diào)外部工具就等于沒有手腳。而MCPModel Context Protocol恰恰是為了解決“讓模型能調(diào)工具”這個問題的通用協(xié)議。把它接進來之后我這個單文件代理就不再是孤島了。4.1 MCP到底解決的是什么問題用一個生活化的類比來理解MCP它就像USB-C接口。以前你給手機充電要帶好幾種線蘋果的、安卓的、Micro-B的MCP要做的就是給“AI調(diào)用工具”這一領(lǐng)域定一個統(tǒng)一標準。任何工具只要實現(xiàn)了MCP服務(wù)端任何AI應(yīng)用只要實現(xiàn)了MCP客戶端就能直接對接不需要針對每個工具單獨開發(fā)適配器。在MCP的世界里有兩方MCP服務(wù)器服務(wù)端負責連接一個具體的工具或功能比如文件系統(tǒng)、Git倉庫、網(wǎng)頁抓取、數(shù)據(jù)庫查詢等MCP客戶端客戶端也就是我的代理本身負責發(fā)現(xiàn)可用的工具、調(diào)用工具、獲取結(jié)果。所以我在代理里做的事情不是去實現(xiàn)某個私有接口而是實現(xiàn)一個標準的MCP客戶端然后它就自動能連上任何MCP服務(wù)器。4.2 手寫了一個極簡的MCP客戶端既然目標是單文件且依賴最少我決定不引入官方SDK而是直接用JSON-RPC格式與本地MCP服務(wù)器通信。整個通信邏輯簡化后其實就三個核心操作initialize建立會話協(xié)商協(xié)議版本tools/list拉取該服務(wù)器支持的工具列表tools/call調(diào)用指定工具。這三個操作走的就是標準JSON-RPC報文核心請求樣例如下def mcp_call(endpoint, method, paramsNone): payload { jsonrpc: 2.0, id: next_request_id(), method: method, params: params or {} } resp requests.post(endpoint, jsonpayload, timeout30) result resp.json() if error in result: raise RuntimeError(fMCP Error: {result[error]}) return result.get(result, {})然后我把tools/list返回的工具轉(zhuǎn)換成代理內(nèi)部的工具清單在Prompt里告訴模型“你現(xiàn)在可以調(diào)用哪些外部工具”。模型在決定行動時如果發(fā)現(xiàn)當前任務(wù)需要讀取一個文件或者查一段文檔就會觸發(fā)tools/call請求把結(jié)果作為下一輪推理的上下文。4.3 接入MCP之后代理的外延能力發(fā)生了什么變化只靠GUI操作代理能干的事其實偏向“點按鈕、填表、截圖看結(jié)果”接上MCP之后它相當于多了一整套工具庫。舉個例子我給它掛了兩個MCP服務(wù)器文件系統(tǒng)MCP服務(wù)器代理可以直接讀取工作目錄里的代碼文件了解項目結(jié)構(gòu)再根據(jù)看到的內(nèi)容去編輯器里操作GUI網(wǎng)頁抓取MCP服務(wù)器當任務(wù)涉及某個外部鏈接時代理可以先抓取頁面的結(jié)構(gòu)化內(nèi)容而不是純粹靠視覺猜測界面。這兩者結(jié)合之后的效果非常明顯。之前它打開一個IDE窗口寫代碼純靠視覺識別代碼內(nèi)容和報錯信息效率很低。而接入文件系統(tǒng)MCP后它可以直接讀取文件內(nèi)容來判斷代碼邏輯再回到IDE里精確點擊目標位置。視覺負責“定位和操作”MCP負責“讀取和理解”兩者互補整個代理的完成度立刻提升了一個量級。不過引入MCP也帶來一個新的復雜性工具選擇策略。當代理同時具備多個外部工具時它需要判斷什么時候該用GUI視覺什么時候該走MCP工具什么時候兩者結(jié)合。我目前的做法是把工具列表塞進Prompt讓模型自己權(quán)衡但實際操作中發(fā)現(xiàn)模型偶爾會做出“明明可以直接讀文件卻非要去GUI里打開文件再看一眼”這種低效決策。后續(xù)我打算加一個簡單的“成本偏好提示”讓模型優(yōu)先選擇它認為成本更低的路徑。5. 實測里被教育過的坑坐標偏移、誤觸、空轉(zhuǎn)與斷連正因為這個項目是真實的工具不是在演示環(huán)境里跑跑就好我花了不少時間處理各種“現(xiàn)實世界對理想模型的毒打”。這一節(jié)算是本篇文章里我覺得最值錢的部分全是我實際踩過、并且最終伸手解決了的問題。5.1 高分屏與縮放比例導致的坐標偏移這是我遇到的第一個攔路虎。在部分環(huán)境下代為截屏的分辨率是邏輯分辨率而鼠標事件用的坐標是物理分辨率中間隔著一個縮放系數(shù)。如果代理直接按截圖返回的坐標點擊往往會點偏。解決方式是在執(zhí)行層統(tǒng)一做坐標換算def convert_position(x, y): # 獲取當前顯示器的縮放比例 scale get_screen_scale_factor() return int(x * scale), int(y * scale)這個坑之所以值得單獨寫是因為它不做任何提示、也不報錯只會表現(xiàn)為“代理每次都點不中”看起來像是模型智障其實是坐標系錯亂。5.2 模型“誤觸”敏感彈窗的風險與安全兜底測試過程中有一次讓我冷汗直冒代理在執(zhí)行任務(wù)時屏幕上彈出了一個不知名的系統(tǒng)提示窗而模型沒能正確識別這個窗口的內(nèi)容直接點擊了提示窗上的某個按鈕。雖然沒造成什么實質(zhì)性后果但它讓我意識到一個能在桌面上亂點的代理必須要有明確的安全邊界。我加的第一道防線是動作白名單默認情況下代理只能對當前任務(wù)相關(guān)的窗口區(qū)域進行操作比如限定在特定的應(yīng)用窗口內(nèi)不能全屏亂點。第二道防線是關(guān)鍵操作需要二次確認如果動作涉及“刪除”“提交”“格式化”等高危操作我會要求代理停下來把即將執(zhí)行的指令反饋給用戶確認。提示這類GUI代理本質(zhì)上是“有手有腳”的程序權(quán)限給得越大出事的可能就越大。除非你很清楚自己在做什么否則務(wù)必給它設(shè)置操作邊界。不要貪全。5.3 空轉(zhuǎn)循環(huán)模型在同一步上反復橫跳還遇到過一種頗具喜感的場景代理在某個步驟失敗后開始瘋狂重復同一個錯誤動作。點擊同一個坐標、等待、截屏、發(fā)現(xiàn)沒變化、再次點擊同一個坐標無限循環(huán)。這背后其實是模型的“探索策略”出了問題——它只想到了當前這一種可能的解法又沒有足夠的隨機性去嘗試新方案。我的解決方式是給循環(huán)加了一道“重復動作檢測器”if same_action_count 3: action_policy change_strategy prompt 提示你連續(xù)執(zhí)行了多次類似動作都沒有效果請換一種策略或考慮放棄該步驟。 same_action_count 0加上這道檢測后模型空轉(zhuǎn)的現(xiàn)象少了很多。它會在提示的引導下重新審視屏幕或者嘗試不同的路徑來完成目標。5.4 MCP連接的不穩(wěn)定性MCP服務(wù)端如果崩潰或者網(wǎng)絡(luò)超時代理可能直接卡在等待結(jié)果的狀態(tài)。這里我的建議是MCP請求必須要有超時和重試而且重試要有上限。我設(shè)置的是超時30秒重試兩次仍失敗就把錯誤信息返回給模型讓模型決定是換工具還是將該步驟標記為失敗。這個機制在實際使用中幫我避免了很多掛死等待。5.5 模型“看錯”界面信息的場景視覺模型并非總能把屏幕上的文字識別準確尤其是較小字號、對比度較低的界面。這里我的經(jīng)驗是不要把關(guān)鍵任務(wù)的判斷完全壓在視覺上能通過MCP讀取結(jié)構(gòu)化數(shù)據(jù)的盡量走MCP。視覺方案是大而全的兜底但結(jié)構(gòu)化數(shù)據(jù)源永遠是更可靠的選項。6. 跑起來的方法與下一步真正想做的擴展說了這么多可能你最關(guān)心的是這東西到底怎么跑起來實際使用方式其實非常樸素python agent_solo.py --task 打開本地數(shù)據(jù)庫工具查詢users表中最近注冊的10個用戶將結(jié)果整理成JSON輸出 --model gpt-4o執(zhí)行之后代理會先截屏分析當前桌面環(huán)境是否有目標應(yīng)用如果沒有它會嘗試啟動該應(yīng)用接下來就是一路“截屏-決策-執(zhí)行-驗證”的循環(huán)。整個過程的日志會實時打印你能看到它每一步在想什么、要做什么也可以隨時中斷。我現(xiàn)在給它設(shè)定的典型使用場景大概是這幾個需要在多個系統(tǒng)之間切換操作時的“搬磚”任務(wù)對不提供API的舊系統(tǒng)做界面自動化結(jié)合MCP對項目代碼進行理解和改造后的GUI回歸快速演示、教學場景讓AI自己演示一段操作流程。至于不適合的場景說實話也有比如超高頻、超精準的操作它不如直接寫腳本穩(wěn)定色彩識別要求極高的場景它也會力不從心還有涉及敏感數(shù)據(jù)的高危操作不建議放給它自動執(zhí)行。認清工具的邊界比追求“什么都能干”更重要。下一步我自己想做的擴展大致有三條線第一條是讓動作反饋更細粒度不只依賴再次截屏而是結(jié)合窗口事件判斷操作是否成功減少等待時間第二條是強化跨應(yīng)用狀態(tài)管理讓代理記住自己當前打開了哪些窗口減少在多個界面間來回找目標的開銷第三條是工具調(diào)用偏好學習根據(jù)歷史經(jīng)驗自動調(diào)整是否優(yōu)先使用MCP還是GUI視覺。這三條線我都已經(jīng)摸到了一些可行的實現(xiàn)思路下面有空的時候會逐步落地。