AI编码代理实操：让大模型操控GUI并支持MCP，打包单文件

最近我做了个免费的AI编码代理它不只会改代码还能直接操控GUI软件同时原生支持MCP协议整个程序最后能打包成单文件运行。说白了就是让大模型长出“眼睛”和“手”能自己去开软件、点按钮、填表单而不是只会坐在终端里敲代码。适合谁参考如果你平时要做桌面软件自动化、想把大模型接到本机工具链里、又不想被重型RPA平台绑架这篇就是给你看的实操笔记。这个项目起源于我处理一堆内网报表。数据要从三个老系统里导出来每个系统都是Windows桌面程序没有API没有命令行只能靠鼠标点。最初我用Python脚本硬编码坐标换台电脑就废。后来我把脚本逻辑交给大模型调度再统一包一个GUI操控和MCP工具协议这个代理才真正“通用”起来。整个项目分两个阶段走先让代理能“看见”屏幕、能“点鼠标”再通过MCP把所有常用工具接口挂进去最后解决打包分发的问题。每一步都踩了不少坑我把过程完整拆开写一遍希望能帮你少绕点弯。1. 为什么我要做这个“能动手”的AI代理1.1 从编码助手到“会点鼠标”的差距常见的AI编码助手主要在终端里工作你给它一个自然语言指令它生成代码、执行命令、读文件、改文件。这套流程对开发者很友好但换到普通桌面软件就完全不管用。比如用Photoshop改个图层名用某仿真软件设置参数或者操作一个只能鼠标点击的ERP客户端终端命令全都不适用。我一开始也觉得这是老系统的问题后来发现桌面GUI自动化本身就是个长期被忽视的刚需。很多企业内部系统没有现代化接口又不能随便换唯一能做的是模拟人工操作。市面上的RPA工具能解决一部分但它们通常有三个问题一是贵按机器人数量收费二是学习成本高流程设计器那一套不是每个人都能快速上手三是流程写死后界面稍微改个按钮位置就全崩。我想要的是一个更灵活的东西大模型能看图理解界面动态决定下一步鼠标怎么动而不是靠死板脚本。这就是“AI编码代理”和传统RPA最大的区别——它不按固定流程跑而是根据当前屏幕内容自行判断。1.2 GUI操控与MCP到底补上了什么只说“操控GUI”其实还不够。一个真正能干活的代理还需要读写文件、调用数据库、执行命令行、搜索网络、操作浏览器等等。如果每个能力都单独给大模型写一套私有调用方法你会发现工具越多代码越乱最后变成一通乱麻。MCPModel Context Protocol模型上下文协议就是干这个的把外部能力统一封装成一个“工具集市”代理只需要按同一个协议去调用就行。我理解MCP最好的类比是USB-C接口。以前每个设备都要专用充电头现在大家统一成一个标准接口换设备不用换线。MCP做的事情类似——大模型、GUI自动化模块、文件系统、数据库插件都能通过这个标准协议互相连接。这样一来我做的代理不需要在每个新工具上都改主程序只要写一个符合MCP规范的适配器就能动态挂载新能力。标题里“支持操控GUI和MCP”这句话其实描述的是两个互补的东西GUI让代理能碰桌面软件MCP让代理能碰所有外部工具。两者合在一起才勉强算一个“能用”的助手。2. 整体架构与关键技术选型2.1 核心模块划分大脑、手、眼睛和工具箱整个代理分四块调度核心负责把用户指令拆解成步骤然后循环执行“观察-思考-行动-确认结果”GUI控制模块负责鼠标键盘操作和窗口截图MCP客户端负责与各个工具服务通信技能注册表负责存储可用的动作和工具描述。调度核心是最麻烦的部分我最初想用一个大模型去搞定所有事后来发现不行。大模型做规划和决策很强但执行细节必须靠本地规则约束否则它会一本正经地乱点。举个例子用户说“帮我把这个文件夹里的图片全部压缩到800像素宽”调度核心应该先列出文件夹检查图片数量然后启动一个批量处理动作。它不应该自己想象“点一下右键菜单里的压缩”这种不存在的功能。所以我的设计是大模型只负责生成高层的任务序列底层每一步动作都映射到具体函数或者是MCP工具调用。这样既保留灵活性又不会失控。2.2 GUI操控路线为什么选用“图像识别OCR”混合方案选GUI自动化技术时我对比过几条路线。Windows的UI AutomationUIA能读取控件树定位很精准但很多老软件控件不是标准实现经常只能拿到一个空壳pywinauto对标准Win32窗口效果好遇到自定义绘制的界面就经常失灵。pyautogui按屏幕坐标操作简单直接但坐标跟窗口位置、分辨率强绑定换环境就废。最后我选择混合路线以图像模板匹配找视觉元素以OCR读屏幕文字再配合坐标偏移修正。这个选型逻辑很朴素既然人眼是靠看按钮、看文字来操作软件的那就让代理也尽量“看”。OpenCV做模板匹配效率高但放大缩小或主题换色会失效OCR可以应对动态变化的文本比如窗口标题、菜单项但识别速度略慢。两者结合后覆盖率明显提升典型界面元素基本都能定位到。遇到视频播放器、游戏这种特殊窗口我也能兜底用图像识别。这个方案的代价是会比UIA方案多耗一点CPU但换来的是跨软件通用性我觉得很值。2.3 MCP协议如何把“工具”变成“可插拔积木”MCP的工作方式并不复杂。代理作为客户端连接一个MCP服务端服务端先上报自己能提供哪些工具每个工具都有一段名称、描述和参数Schema代理根据用户请求匹配工具然后发起调用请求服务端执行完返回结果。整个过程基于JSON-RPC 2.0。好处是“工具描述”本身就是给大模型看的说明书模型能自己判断用什么工具、传什么参数。我这边做了两个MCP服务一个是文件系统服务负责读写、移动、搜索文件另一个是系统操作服务负责执行命令、打开软件、管理窗口。GUI模块则是作为另一条本地能力线存在没有完全塞进MCP。因为GUI操作需要频繁截图和反馈走MCP会引入额外的串行通信开销而文件、命令这类操作没有强实时性走MCP非常合适。这样设计之后以后想加一个“浏览器控制”工具只要新增一个MCP服务即可主程序一行不用改。2.4 单文件运行的打包策略与取舍“单文件运行”是我给自己定的硬性要求。原因很简单要让同事用起来不装环境、不查依赖双击一个exe就能跑。Python项目要打包成单文件绕不开PyInstaller的--onefile模式。它会把所有依赖和资源压进一个可执行文件运行时再释放到临时目录。代价是启动速度变慢第一次运行可能等两三秒而且容易被杀毒软件误报。权衡之下我在开发阶段用--onedir模式加快迭代确认稳定后再切--onefile发布。资源文件处理也是一个坑。比如OCR语言包、模板图片、图标文件不能直接丢在exe旁边因为单文件运行时工作目录并不是exe所在目录。PyInstaller会把这些文件放在sys._MEIPASS临时目录里程序必须通过这个路径来定位。我封装了一个资源路径函数启动时判断是开发环境还是打包环境分别返回正确路径。这块踩了好几次坑才彻底理顺后面第4部分会给出具体代码。3. 核心细节与实操要点3.1 GUI元素定位坐标、模板与OCR三者怎么协作我不建议只依赖单一方式。先说坐标法它适合那种窗口固定、程序固定、屏幕分辨率固定的内部环境只定位一次就能用速度最快。模板匹配用来找按钮图标、Logo这类静态图案比如“保存”图标、“导出”按钮。OCR则用来读动态文字例如窗口标题、对话框提示、列表项。实际动作的定位优先级是先尝试UIA控件树如果软件支持其次OCR文字匹配再次图标模板匹配最后才用坐标偏移。这套组合需要写一个“定位器”统一返回目标元素的中心坐标。定位器接收一个描述比如“带有‘确认’文字的按钮”它会先在截图上执行OCR找出所有包含“确认”的区域再按面积大小排序选出最可能的一个。如果OCR结果有多个候选还可以把每个候选区域和预设模板做相似度对比。整个过程大约消耗几百毫秒对于GUI自动化可以接受。定位到坐标之后我会再做一次“安全确认”对按钮类型做一个粗略判断如果是“删除”“格式化”“清空”这类危险操作就强制暂停把截图发给用户确认绝不自动点击。3.2 MCP工具服务端的注册与调用约定MCP工具服务端最重要的是把“工具描述”写清楚。大模型能正确调用工具一半靠模型能力一半靠描述质量。描述里必须说明工具用途、参数含义、边界条件。比如文件写入工具不能只写“write_file”要写清楚“创建或覆盖指定路径的文本文件encoding支持utf-8目录不存在时自动创建”这样模型才知道何时调用它、传什么参数。调用约定上我倾向于“返回精简结果”。如果一个工具返回大量内容比如文件列表几千行会占满模型的上下文窗口后面的推理和动作都会变慢。所以MCP服务端要做“裁剪和摘要”返回列表时只给前50条带总数提示文件内容超过200行就只返回头部和尾部各50行中间用省略号替代。这个设计对长文档处理特别重要。我一开始没做限制让工具返回完整日志文件结果直接把模型上下文撑爆过程变得非常卡。另外工具调用尽量设计成“幂等”。同样的参数调用两次结果要么一致要么不会造成破坏。比如“创建目录”工具目录存在就返回成功而不是报错移动文件时不覆盖已有文件而是自动改名。这样即使模型重复执行一个动作后果也可控。3.3 单文件运行环境下的资源释放与权限处理单文件模式有个隐藏问题程序运行时要解压完整依赖包到系统临时目录退出时再清理。如果代理在运行中生成了临时文件例如OCR缓存、截图文件、日志默认都写到临时目录退出会被清掉不方便排查。我后来把日志和截图目录单独指向exe所在目录下的logs和screenshots文件夹每次运行自动创建同时按日期归档这样即使程序崩溃也能找出问题。权限处理同样重要。GUI自动化操作大多数情况下不需要管理员权限但如果目标软件是以管理员身份启动的普通权限的代理无法操作它的窗口截图和鼠标消息都会失效。我遇到过一次代理开了一个提权后的安装程序然后找不到任何窗口。解决办法很简单如果发现目标窗口句柄获取失败就在界面提示“请用管理员身份重新运行代理”或者将整个代理设置为“管理员权限启动”。后者有个副作用每次启动会弹UAC但是对我这个使用场景来说收益大于成本。3.4 提示词编排把自然语言翻译成可执行动作链提示词在AI代理里的作用比在普通聊天里更关键。它不是简单地把用户问题发给模型而是要把“当前屏幕状态”“可用工具列表”“历史操作记录”拼成一份结构化上下文。例如用户说“打开任务管理器看哪个进程占用CPU最高”代理会先执行“截屏”再把截屏信息和MCP工具列表一起交给模型模型输出“下一步操作点击性能标签”。如果没有屏幕状态信息模型就只能瞎猜生成的步骤根本无法执行。我使用的提示词模板大致分成四层角色约束、上下文、工具说明、输出格式。角色约束强调“你是桌面自动化代理只操作计算机不讨论无关话题”上下文包含当前截图、窗口标题、用户请求、最近几步动作工具说明列出可调用函数或MCP工具输出格式强制要求模型输出JSON例如{action: click, target: CPU, confidence: 0.87}。这个JSON会被本地逻辑解析再转成具体鼠标动作。这套方法跑通后代理的容错率明显提升即使模型偶尔给出不合理的action本地校验层也能拦截。4. 从零跑通实操过程与关键代码4.1 环境准备与依赖清单我建议在Python 3.10或3.11环境下操作依赖版本尽量锁定避免后来升级破坏兼容性。核心依赖包括pyautogui负责鼠标键盘控制opencv-python做图像模板匹配pytesseract接OCR识别Pillow处理截图mcp如果使用官方SDK负责MCP通信pyinstaller最后打包。如果只用我这种简化方案也可以不引入官方MCP SDK自己用websockets或者requests实现JSON-RPC但我建议新手直接用SDK省得协议细节出错。安装命令就是常规的pip install pyautogui opencv-python pillow pytesseract pyinstaller。需要注意pytesseract只是客户端库真正执行OCR的Tesseract二进制还得单独装。Windows上可以用exe安装包装完把pytesseract.pytesseract.tesseract_cmd指向安装路径。语言包默认只有英文需要中文界面识别的话到Tesseract的官方语言包仓库下载chi_sim.traineddata放到tessdata目录。这一步很多人漏掉导致识别中文全是乱码。4.2 编写第一个GUI自动化任务我拿“打开记事本并输入一段文字”作为第一个任务它足够简单又包含完整链路。先导入库用pyautogui.hotkey(win, r)打开运行对话框再输入notepad回车。这里不能直接敲一次回车就完事因为Windows启动程序有延迟必须等待窗口出现。等待窗口的方式我推荐用循环轮询而不是固定sleep。import pyautogui import time import pygetwindow as gw def wait_for_window(title, timeout10): start time.time() while time.time() - start timeout: windows gw.getWindowsWithTitle(title) if windows: return windows[0] time.sleep(0.3) return None pyautogui.hotkey(win, r) time.sleep(0.5) pyautogui.write(notepad, interval0.05) pyautogui.press(enter) win wait_for_window(记事本, timeout10) if win: win.activate() pyautogui.write(Hello from AI Agent, interval0.02) else: print(未找到记事本窗口)这个例子看着简单但已经包含了三个关键点快速唤起、显式等待窗口、激活目标窗口。win.activate()经常被忽略如果桌面上有多个窗口直接输入文字可能落在别的窗口上。我还习惯在输入前加一次截屏确认焦点位置避免误操作。4.3 接入一个MCP文件读写工具MCP服务端的核心是向客户端暴露工具列表和处理调用请求。这里用简化的JSON-RPC伪代码来说明结构避免陷入SDK版本差异。def tools_list(): return [ { name: read_text_file, description: 读取指定文本文件内容支持utf-8编码返回前200行摘要。, inputSchema: { type: object, properties: { path: {type: string, description: 要读取的文件的绝对路径} }, required: [path] } }, { name: write_text_file, description: 写入文本文件目录不存在时自动创建已存在时覆盖。, inputSchema: { type: object, properties: { path: {type: string}, content: {type: string, description: 要写入的完整内容} }, required: [path, content] } } ] def tools_call(name, arguments): if name read_text_file: path arguments[path] with open(path, r, encodingutf-8) as f: lines f.readlines() return { total_lines: len(lines), head: lines[:50], tail: lines[-50:] if len(lines) 100 else None } elif name write_text_file: path arguments[path] content arguments[content] import os os.makedirs(os.path.dirname(path), exist_okTrue) with open(path, w, encodingutf-8) as f: f.write(content) return {success: True, path: path}我特意在read_text_file里做了摘要逻辑避免返回整个大文件。客户端收到响应后会先判断是否符合预期再决定继续调用还是修正参数。模型如果传了相对路径我会在工具内部强制要求绝对路径否则在不同操作系统上很容易出错。4.4 用PyInstaller打成单文件并验证开发完成后打包命令很简单pyinstaller -F -w --add-data assets;assets --hidden-import cv2 --name ai-coding-agent main.py-w表示不显示控制台窗口--add-data把资源目录打入包内Windows下用分号分隔源目录和目标目录。如果你在开发时依赖了某些动态隐藏导入例如pyautogui的子模块可能需要增加--hidden-import。我建议打包完先运行一次测试版看是否报缺少模块报什么补什么。验证过程不能只验证“能启动”还要验证“打包后的单文件在另一台电脑上能跑”。把exe复制到一台没有Python环境的干净虚拟机里运行一个最简单的GUI自动化任务比如“打开计算器点击数字5”。如果模板匹配或OCR资源没打进去会在这一步暴露。我还比较推荐在打包后的程序里把资源文件路径打印出来虽然用户看不到控制台但能写入日志文件方便排查。4.5 关键参数选择与性能观察我的GUI定位器有几个核心参数都是实测调出来的模板匹配阈值confidence设为0.8低于0.8就不点击防止误触OCR结果按包含关键词的模式匹配如果匹配到多个则会做位置优先级一般优先选择屏幕中央区域的候选鼠标移动间隔设为0.1秒太快会导致软件反应不过来太慢则任务耗时翻倍。重试次数设3次每次重试间隔1秒。如果一个动作重试3次仍失败就暂停并输出截图让用户决定下一步。性能上单文件模式启动时间比目录模式慢约2秒运行中截图和模板匹配单次约0.2秒OCR单次约0.5秒。对于不需要OCR的任务整体速度还能接受。真正的性能瓶颈在大模型调用上尤其是第一次请求时模型响应可能长达几秒。我做了异步预取在截图完成后立即发送给模型同时让本地鼠标先执行上一步动作的“确认检查”两者并行能省不少时间。5. 常见问题与排查技巧实录5.1 GUI程序偶发找不到窗口或控件这个问题最常见的原因是启动延迟和显示器坐标映射。我遇到过很多次程序已经启动了但窗口没完全渲染又或者窗口出现了但按钮要到两秒后才可用。解决办法就是“不要固定sleep”用轮询配合窗口标题和控件特征查找。另外有些软件的窗口标题会动态变化比如“文档1 - 记事本”“文档1”会变。这时候要用标题包含匹配而不是精确匹配。如果轮询超时还没找到多半是程序启动失败比如依赖的组件没装、文件路径错误。我会把最后一次截图存到日志目录然后提示用户查看。不要硬重试太多次浪费时间。还可以在GUI库初始化时设置程序DPI感知能有效减少高DPI环境下找不到窗口的问题这个用法在第5.4节展开。5.2 MCP连接超时或调用失败MCP连接超时通常是服务端和客户端的通信方式没配对。我在项目里同时支持stdio和HTTP两种模式stdio模式适合两个进程在同一台机器上代理启动子进程并管道通信HTTP模式适合远程服务比如同一局域网内的另一个工具主机。如果工具服务迟迟没响应先看服务端日志不要一上来就怀疑协议不对。工具调用失败还可能是因为返回了超大结果导致客户端内存暴涨或解析超时。我的规避策略如前文所述服务端统一裁剪结果并把错误信息用英文短句描述例如“Permission denied: /path”。大模型看到短错误信息后更容易形成下一步修复动作。如果是参数缺失则返回“missing required argument: path”并附带示例。这样模型能自我纠正不完全依赖用户干预。5.3 单文件运行被杀毒软件误报PyInstaller单文件exe在很多杀毒软件下都可能被误报尤其是用了UPX压缩之后。我测试过程中的经验是不用UPX压缩报毒概率会下降不少再在发布前用证书签名即便自签名也会降低一部分拦截概率。不要通过关闭杀毒软件来解决问题这是对用户的不负责。最好是把程序行为做成可预期的不打乱杀毒判断的敏感动作例如不模拟键盘钩子、不注入其他进程、不自动安装驱动。如果误报依然存在我建议在项目文档里写清楚开发过程和文件校验并把源代码公开展示接受安全审查。免费工具更怕被当恶意软件开源和透明度是最好的信任凭据。5.4 高DPI、多显示器下的坐标偏移Windows的DPI缩放是GUI自动化最容易踩的坑。系统默认对高分屏做缩放显示比如150%、200%而pyautogui拿到的是物理像素坐标两者不匹配导致点击位置偏到按钮外面。解决办法是在程序初始化时调用系统API关闭DPI缩放import ctypes ctypes.windll.shcore.SetProcessDpiAwareness(1)SetProcessDpiAwareness(1)代表系统DPI感知应用按真实像素绘制这样坐标就和截图对上了。多显示器场景则是另一个坑当显示器上主屏和副屏分辨率不同Windows虚拟屏幕会存在负坐标区域。pyautogui的鼠标操作是基于虚拟屏幕的但截图保存的图像坐标是从0开始的两者如果不做偏移换算就会点击到错误位置。我封装了一个坐标系转换函数把“图像相对坐标”转成“虚拟屏幕绝对坐标”测试了两个显示器不同缩放比例的混合环境目前都能命中。5.5 日志与回放式排查技巧GUI自动化最怕“看起来什么都没发生但程序没报错”。解决这个问题的唯一办法就是“留痕”我一共记录三样东西操作日志、执行前截图、执行后截图。操作日志用JSONL格式每行记录time, action, target, result方便后期写脚本分析。前后截图用时间戳命名如果任务失败能很直观地看出代理在哪个步骤偏了。日志文件不要写到临时目录因为单文件模式退出后会清空。我自己会创建一个screenshots目录保留最近500张截图配合一个简单的查看界面按时间回放。这样做虽然占用一点磁盘空间但排查效率提升非常明显。我甚至写了一个小脚本把前后截图叠加成GIF动图任务出错时一眼就能看出是“窗口没弹出来”还是“坐标偏了”还是“OCR认错字”。6. 后续扩展方向与踩坑心得6.1 可以继续叠加的实用能力这个架构留了很好的扩展点。MCP服务端可以继续加“浏览器控制”“数据库查询”“邮件发送”等工具GUI模块可以横向扩展到Linux的X11/Wayland或macOS的辅助功能接口调度核心可以加入多模型切换比如高难度任务调大模型简单重复动作走本地小模型。甚至可以把截图识别这部分扔给一个视觉能力更强的模型提升中文老软件的识别准确率。我自己目前最想加的是“流程录制器”让用户在界面上手动操作一遍代理录制鼠标键盘事件并生成结构化步骤之后自动回放。这样能结合人的经验判断和AI的灵活性很多一看就会的简单工作流就不需要再写规则了。这套思路完全可以复用到办公自动化、测试脚本生成、教学演示录制等场景。6.2 一些避坑经验总结做这个项目我最大的体会是先解决“看得见”再解决“能动”最后才谈“聪明”。如果屏幕截图都拿不到模型再强也做不出正确动作。所以第一步一定是把截屏、OCR、模板匹配这些基础能力调稳这些底子打好了后面所有的事都顺了。第二任何危险操作都要加确认或限制。AI在执行时不怕慢就怕快一旦快速地把鼠标点进“删除确认”对话框里后果很难挽回。我后来给代理加了一个“危险操作名单”凡是动作描述里包含删除、清空、格式化、覆盖之类的关键词一律先给用户看截图。宁可让用户多等一秒也不要让代理捅娄子。第三单文件运行是发布要求但开发时不要用单文件模式。--onedir模式启动快、报错定位容易开发效率高得多到接近发布时再试--onefile专门处理资源路径、杀毒误报这些问题。我这个顺序一开始搞反了导致一个简单问题修了半天非常划不来。现在整个项目稳定下来我也打算把GUI操控、MCP服务、单文件打包这三块分别拆成独立模块后续更新时可以单独替换不用每次重新打包全套。做个人项目虽然自由但模块边界越清晰后面写起来越省心。