做AI编码代理这事我一开始是有点不服气的。市面上的代理工具很多但它们大多被锁在IDE和终端里让模型写代码、跑命令、改文件再往上看一眼截图就结束了。可真正干活的时候我们要面对的明明是桌面上的各种软件是要打开某个GUI程序点几下要连上内部的数据工具查点东西。这种“只会在黑框里写代码”的代理离“帮我搞定一件事”还很远。所以我花了些时间做了个免费的单文件AI编码代理它可以直接操控GUI界面也支持MCP协议去接外部工具整个项目就一个脚本文件拷到哪里都能跑。这篇文章就是整个项目的思路复盘和实操记录包括技术选型、核心实现、真实踩坑和排查经验给也想做类似东西的人一个参考。1. 首先得把事情说清楚这个代理到底解决什么问题1.1 现有AI编码工具的边界在哪现在大家常用的编码代理基本都能做到“听懂需求 → 改代码 → 跑测试”这条链路。它们依赖的基础设施是终端和文件系统模型通过工具调用去执行Shell命令、读取代码文件、运行测试用例。这套流程在纯开发场景里确实够用我也很依赖它。但一旦任务需要跨出代码库问题就来了。我举个具体例子你想让代理帮你在某个桌面软件的配置界面里把某个开关打开顺便把另一处设置项改成指定值。传统的编码代理做不到因为桌面GUI没有现成的API它看到的只是屏幕上的像素又比如你想让代理连上公司或社区里的数据服务比如某个数据库查询工具、某个浏览器控制插件或者某个专门的开发辅助服务这些服务彼此协议不统一每个都去单独适配一轮工作量直接失控。这时候最自然的需求就是两件事一个是让代理能“看到屏幕、操作鼠标键盘”也就是GUI操控能力另一个是让代理能通过统一协议去接入大量外部工具也就是MCPModel Context Protocol模型上下文协议支持。这两个能力加上原本的代码执行能力才算是真正“能干活”的代理。1.2 为什么非要做成单文件从一开始我就给自己定了一个硬性约束整个代理必须是单文件运行。这个约束看起来有点自找麻烦但实际用下来它带来的好处远超想象。首先单文件意味着零安装心智负担。用户不需要理解什么是虚拟环境不需要折腾依赖安装顺序也不需要面对一堆配置文件。他们拿到一个脚本用Python跑起来就能开始对话。这对于一个免费分发的工具来说是极其友好的第一印象。我见过太多好东西死在“安装太麻烦”这一步。我不想让用户还没体验功能就先经历环境地狱。其次单文件在安全审计上也有天然优势。AI编码代理本质上是把操作权限交给了模型用户最关心的就是“你到底做了什么”。一个只有几千行的单文件脚本用户可以自己打开从头到尾读一遍搞清楚它有没有偷偷上传数据、会不会执行危险命令。打包成二进制或者一个巨型框架项目反而让人不放心。当然单文件的代价也很真实。所有代码挤在一个文件里模块划分只能靠清晰的注释和段落结构来维持依赖第三方库时不能无脑引入否则用户本机缺库跑不起来。我的解决方法是尽量用Python标准库涉及第三方库时做成“运行时按需自动安装”后面实操部分我会详细讲这个机制。1.3 整体架构是怎么搭起来的单文件不代表结构混乱。我在文件内部还是做了清晰的分层大致可以分成四个逻辑块第一块是对话与Agent调度核心。它负责与后端大模型API通信维护会话历史并且在一个循环里根据模型输出决定下一步动作——是回复用户、调用工具还是继续观察结果。这个循环是所有代理的心脏模型输出一条结构化指令我解析后执行再把执行结果当作新的上下文还给模型反复迭代直到任务收尾。第二块是通用工具集。包括执行Shell命令、读写文件、请求HTTP接口、网络搜索等基础操作。这些工具让代理在终端和文件系统层面具备基本的“动手能力”和普通编码代理的能力对齐。第三块是GUI操控模块。它负责截取屏幕、分析界面内容、移动鼠标、点击、输入文字。为了实现这一步我需要把屏幕上的视觉信息转换成模型能理解的文本描述再把模型选择的动作转换成真实的系统级输入事件。第四块是MCP客户端。它负责按MCP协议与外部服务建立连接拉取工具列表把外部工具动态注册成代理可调用的动作。这样用户不需要改我的代码只要给一个MCP服务器配置代理就能用上新的工具。四个块之间通过一个统一的“工具注册表”衔接每个能力都是一组“名字描述执行函数”模型看到的是统一结构化的工具列表实际执行时由派发器路由到具体的实现模块。这样GUI工具、MCP工具、Shell工具彼此独立又能被同一个调度循环无缝调用。2. GUI操控与MCP支持两大核心能力的技术拆解2.1 GUI操控是怎么让模型“看见”屏幕并动手的GUI操控的第一步是让模型能感知屏幕内容。这个环节我先后试过几种方案各自的取舍很值得说一说。最朴素的方案是把整个屏幕截下来交给支持视觉的大模型直接分析。模型看到截图后输出“我要点击左上角第某个位置的按钮”。这种方案效果直观但有几个现实问题一是视觉模型推理成本高每轮操作都传一张大图既慢又贵二是模型对像素坐标的估算并不稳定同一个按钮在不同分辨率下位置差很多很容易点偏。所以我把视觉方案当兜底而不是主路径。更实用的方案是“结构化屏幕描述”。在Windows系统上可以通过UI Automation拿到当前窗口的控件树类似浏览器里的DOM窗口里有哪些按钮、输入框、菜单项它们在屏幕上的具体坐标和尺寸是多少全部转成文本结构再交给模型。这样模型不需要“猜坐标”它看到的是类似“按钮[保存]位于(x1280,y830)”点击目标非常明确。这个方案精准、便宜、速度快是最适合GUI自动化的路径。但UI Automation在非Windows平台覆盖度不高而且很多第三方应用尤其是游戏、自绘界面的工具压根不暴露控件信息。所以我的GUI模块做了两层优先尝试控件树拿不到控件树时退回到截图方案让视觉模型描述看到的元素并给出估算坐标。两层都有容错机制比如点击完成后会重新截图对比界面状态用来判断操作是否真的生效。动作执行层相对简单核心就三类移动鼠标、点击左键/右键/双击、键盘输入。跨平台实现上我直接用系统API而不是第三方自动化库Windows下用ctypes调用user32.dll的SetCursorPos和mouse_eventmacOS下用Quartz的事件注入接口。自己调API的好处是减少额外依赖也更容易精确控制坐标和按键行为。这里有个很关键的小技巧发送完点击后不要马上认为任务就完成了。我习惯让代理在每次交互后截取一张新截图用文件哈希或像素差异判断界面是否发生了预期变化。比如点击“保存”按钮后如果弹出了“保存失败”对话框截图内容就会暴露这个问题模型就能及时进入异常处理流程。这套“动作-观察-校验”的循环是GUI自动化稳定性的基石。2.2 高DPI缩放和多显示器场景一个都不能忽略GUI操控最容易被新手低估的问题就是坐标系统和屏幕缩放不一致。现在的Windows系统默认开启DPI缩放一个逻辑分辨率1920x1080的屏幕实际物理像素可能是2560x1440甚至更高。如果你直接截一张物理像素图交给模型去估算坐标再用用户态的鼠标坐标去点击大概率会点偏。处理办法说出来也不难先统一坐标基准。我使用逻辑坐标也就是系统API层面鼠标移动所用的坐标空间作为唯一基准。截图时把屏幕实际像素图按缩放比例缩放到逻辑尺寸UI Automation返回的坐标本来就是逻辑坐标可以直接使用。关键代码里的缩放因子通过系统API查询Windows下有个System DPI Awareness的设置需要提前声明否则进程默认被系统强制按DPI缩放拿到的坐标还是不准确。多显示器的情况就更麻烦了负坐标是常态主显示器左边可能还挂着另一个显示器那台显示器最左侧的坐标就是负数。鼠标移动API本身支持负坐标但要确保截图模块能覆盖所有显示器的完整虚拟桌面区域并且正确处理不同显示器之间DPI不一致的问题。我第一次实现时就因为没处理负坐标导致模型点击任务栏图标时鼠标往右上方飞找了好久才发现是多显示器负坐标的锅。我给的解决方案是定义统一的虚拟桌面坐标系把所有显示器的边界信息传给截图和分析模块。分析界面时只截取目标窗口所在显示器的区域而不是盲目截全屏这样既减少模型要处理的信息量也避免跨屏坐标换算错乱。2.3 MCP协议到底是什么一次握手和一套工具列表MCP现在已经不算新概念了但很多人对它的理解还停留在“某种AI插件协议”。我在实现客户端时把协议文档完整啃了一遍发现整个设计其实非常清爽。它本质上是一个基于JSON-RPC 2.0的通信协议专门解决“AI应用如何与外部工具/数据源对话”的问题。整个交互过程可以简化成三个阶段连接握手、能力发现、工具调用。连接阶段MCP客户端会发起initialize请求告诉服务端自己支持的协议版本和客户端能力服务端同样返回自己的版本和能力。如果版本不匹配连接会直接失败这是新手最容易踩的第一个坑。握手成功后客户端发送一个notifications/initialized通知表示初始化完成双方进入正常工作状态。能力发现阶段客户端发送tools/list请求服务端返回一堆工具定义每一条包括工具名、描述、参数结构。这个参数结构用JSON Schema描述对代理来说非常重要——模型需要根据参数说明来决定传什么参数。这个设计非常像OpenAI Function Calling的工具定义所以学过Function Calling的人理解MCP会很快。工具调用阶段客户端发送tools/call请求带上工具名和参数对象。服务端执行对应操作后返回结果结果可以是纯文本也可以是结构化内容比如JSON还可能包含图片等资源。我实现的客户端还会把返回的MCP内容转成内部统一的工具结果格式再放进模型上下文里让模型基于结果进行下一步决策。MCP有两种传输方式分别是本地stdio和远程HTTP/SSE。stdio模式是客户端启动一个子进程跑MCP服务器通过标准输入输出流来通信适合本地工具比如文件系统服务、数据库连接器。HTTP模式则是连接到已经部署好的远程服务适合共享的团队工具或者云端服务。我的客户端两种都支持配置里声明一下transport类型就能自动切换。2.4 代理怎么把MCP工具动态接入调度循环真正把MCP工具接进代理时最大的设计问题不是通信而是“动态注册”。因为MCP服务器的工具列表在运行时才能拿到我没法在编码阶段就把所有工具写死到提示词里。我采用的方式是配置驱动加载。用户配置一个JSON片段里面声明MCP服务器的名字、启动命令或远程URL、传输方式。代理启动时读取配置逐个连接服务器拉取工具列表然后把这些工具的“名字描述参数Schema”动态加入到模型可用的工具列表中。整个过程中模型完全感知不到MCP的存在它只知道自己多了一批新工具可以用。举个例子用户接了一个文件管理MCP服务器代理的工具列表里就会多出read_file、write_file、rename_file之类的动作。再加上一个数据库MCP服务器代理就突然拥有了直接查询数据库的能力。每一次接入都是即插即用的完全不需要改Agent本体代码。这里有一个值得注意的细节MCP服务器返回的工具名很容易和代理内置工具名冲突。比如我内置有write_fileMCP服务器又提供一个同名的write_file模型调用时就会产生歧义。我的做法是给来自MCP的工具名加前缀格式是“mcp__服务器名__工具名”同时在工具描述里标注来源。模型看到工具名时能清楚知道哪些是外部工具调用起来相当稳定。3. 实操从零开始跑起并完成两个真实任务3.1 运行环境和最小配置先说明一下运行前提。整个项目是Python实现的单文件脚本目标运行环境是Python 3.10及以上版本。我不想让用户先安装一堆依赖所以脚本做了一个“自举”机制启动时检查必备第三方库是否安装缺什么就自动用pip装上。比如图像处理要用到Pillow它不在标准库里但脚本第一次运行时会自动安装用户全程是无感的。模型接口这块我兼容的是OpenAI风格的API。用户只需要提供API的base_url和api_key以及想用的模型名。这样无论是商用大模型还是本地部署的开源模型只要能提供OpenAI兼容接口就能接入。最小配置长这样export LLM_BASE_URLhttps://your-provider.example.com/v1 export LLM_API_KEYyour-api-key export LLM_MODELyour-model-name python single_agent.py启动后会进入一个交互式命令行界面直接输入任务描述代理就会开始干活。第一次运行时脚本会自动创建两个默认文件一个是代理配置文件用来声明MCP服务器另一个是任务日志文件记录每一轮模型调用和工具执行结果方便事后回溯。3.2 实操案例一让代理打开记事本并保存一段文本这个案例我演示过很多次虽然任务本身简单但能完整体现GUI操控的完整闭环。我输入的任务是“打开记事本输入一段Python代码保存到桌面上。”代理的处理过程大致是这样的第一步它调用内置Shell工具执行notepad命令启动记事本。这里没有走GUI去点击开始菜单因为Shell方式更快更可靠。第二步启动后并不会自动聚焦到输入区域所以代理调用GUI模块做“激活窗口”操作通过UI Automation找到标题为“无标题 - 记事本”的窗口调用SetForegroundWindow把它带到前台。这一步非常关键如果窗口没激活后面的键盘输入会直接丢失。第三步代理通过GUI输入工具模拟键盘把模型生成的代码逐行打进去。这里我做了个防抖处理键盘输入之间加极短的间隔防止输入过快导致系统丢键。代码输入完成后代理调用CtrlS触发保存对话框。第四步保存对话框出现后代理重新扫描屏幕上的窗口找到“另存为”对话框里的文件名输入框和“保存”按钮把目标路径填入点击保存。点击完成后代理会再次检查窗口标题是否变成了“xxx.py - 记事本”如果变了说明保存成功。整个过程看起来简单但每一环的校验都不可少。如果保存对话框没有按预期弹出代理必须能从上一步的截图中发现异常并重新尝试一次。这类“失败重试”逻辑是GUI自动化稳定性的护城河。3.3 实操案例二通过MCP文件服务器批量整理文件名第二个案例演示MCP的接入价值。我本地跑了一个文件整理的MCP服务器它的能力是读取目录内容、批量重命名文件、按规则移动文件。比内置Shell工具更强大的是这个MCP服务器专门封装了安全操作比如拒绝移动到系统目录、保留文件扩展名等相当于外部工具已经预设好了一堆安全边界。我的配置文件里增加了这样一段声明{ mcpServers: { file-helper: { command: python, args: [file_server.py], env: { ALLOWED_DIR: /tmp/workspace } } } }代理启动后发现这个MCP服务器自动注册了list_files、rename_with_rule、move_files等一组工具。我给出的任务是“把/tmp/workspace目录下所有文件名里的日期格式从20240101改成2024-01-01。”代理的调度过程是这样的先调用MCP的list_files工具拿到目录文件列表发现几个命名不规范的文件然后调用rename_with_rule工具传入正则表达式和目标格式服务器执行重命名后返回结果列表代理核对后报告完成。整个过程里代理完全不需要知道这些文件操作是如何实现的。它只需要理解工具描述和参数含义就能把任务拆解成一步步的MCP调用。这也是MCP最迷人的地方外部能力封装得越好代理就越省心。3.4 核心配置项速查整理一下最常用的配置项方便后面自己改配置项作用示例LLM_BASE_URL模型API地址http://localhost:8000/v1LLM_API_KEYAPI密钥sk-xxxLLM_MODEL模型名称qwen2.5-coder:32bGUI_SCALE_FACTOR手动覆盖屏幕缩放比例1.5MCP_CONFIG_FILEMCP服务器配置文件路径mcp_config.jsonENABLE_GUI_CONFIRMGUI操作前是否弹确认trueENABLE_GUI_CONFIRM这个开关我个人建议默认开着。尤其在无人值守模式下每次点击和输入前先征求用户确认能极大降低误操作风险。后面我会专门展开讲安全这个话题。4. 踩坑记录与排查技巧这些坑我替你们踩过了4.1 MCP连接与工具发现阶段的问题MCP这部分我初期踩的坑主要集中在握手阶段。最典型的是协议版本不一致MCP的协议迭代速度很快我的客户端实现基于某个版本而用户配置的MCP服务器是基于另一个版本开发的服务端会在initialize阶段直接拒绝连接。这类错误的排查思路很简单把MCP服务器的启动日志打出来看看握手响应里返回的error内容。如果日志提示版本不支持就需要升级客户端或服务器把两边协议版本对齐。另一个常见问题是stdio模式下子进程启动失败。MCP服务器本身依赖的Python环境可能和主进程不一致比如主进程用的是系统Python服务器需要的是conda环境。配置文件里如果直接写成command: python很容易启动了一个不包含所需依赖的环境。解决方式是command字段写绝对路径比如/path/to/venv/bin/python。这类问题在一开始容易忽略但排查起来往往就浪费半天时间。工具列表为空的情况也遇到过。连接明明正常但tools/list返回空数组。这类问题八成是服务器自己初始化失败但没有报错退出或者服务器认为当前会话没有可用工具。我会先做一次手工验证单独在终端里启动那个MCP服务器命令看看会不会报错顺便确认它支持的transport是不是stdio。很多号称MCP服务器的工具实际默认跑的是HTTP模式指望它通过stdio通信自然拿不到任何工具。4.2 点击偏移和截图失真的坑GUI操作的第一个坑就是DPI。我在前面提到过坐标缩放问题这里再补充一个实操细节不要相信截图像素和鼠标坐标是同一套单位。Windows上截图API返回的是物理像素而鼠标API用的逻辑单位两者之间隔着一个缩放因子。第一次做GUI代理的人十有八九会在高清屏上翻车模型说点某个按钮结果鼠标落在按钮下方十几像素的位置。多屏幕的坑比DPI还要隐蔽。Windows虚拟桌面坐标系里主屏之外的屏幕可能位于负坐标区域。我自己的主屏旁边挂了一个竖屏竖屏顶部坐标直接就是负数。有一次代理控制鼠标去点击任务栏系统告诉我鼠标位置在(-1920, 860)我愣了好一会儿才反应过来这是副屏坐标。后来我统一了坐标系换算工具函数所有模块都通过同一个函数把图形坐标转成鼠标坐标负坐标问题才算彻底解决。还有个容易忽略的问题是全屏截图和窗口截图的视角差别。模型如果看全屏截图它能注意到屏幕上的各种干扰信息反而对目标任务界面不够聚焦。我调整了策略优先截取目标窗口区域让模型只关注当前应用的界面视觉效果和准确率都提升明显。4.3 模型幻觉与操作安全护栏说实话GUI操控最大的风险不是技术实现而是模型幻觉导致的操作错误。模型可能“觉得”某个按钮应该存在就输出一次点击动作但屏幕上根本没有这个按钮或者按钮位置和模型想象的完全不一样。如果不加护栏代理就会对着空气乱点甚至误触发危险操作。我的经验是三层护栏缺一不可。第一层叫动作验证。模型每次输出GUI动作前先描述这个动作的预期效果执行动作后系统自动截图并比对界面状态如果预期效果没有出现就把异常反馈给模型禁止它继续下一个动作。这个循环让模型有机会从错误中恢复而不是将错就错。第二层叫范围限制。默认情况下代理只能在用户指定的应用窗口里操作不能随便切换窗口、不能点击任务栏系统区域、不能触发系统级快捷键。这个限制在Windows上通过窗口句柄实现把鼠标事件注入目标窗口而不是全局注入。这样即使模型点错了影响范围也只限于当前应用。第三层是人机确认。在“执行不可逆操作”删除、移动、保存覆盖、发送消息之前强制弹出一个确认提示用户允许后才继续。虽然这个过程打破全自动化体验但它的价值在关键时刻会体现得很明显。有一次模型差点把一份文件移动到回收站以外的分区是确认机制拦下来的。这些限制看起来会拖慢速度但没有它们GUI代理只能活在演示视频里上不了真实桌面。安全不是可选项是默认项。4.4 单文件运行模式的依赖问题单文件模式最大的挑战是依赖分发。我把第三方依赖控制到最少实际运行时只有Pillow和requests是需要安装的其他功能全部用标准库实现。但即便只有两个依赖用户环境也可能出问题有的用户自定义了pip镜像源导致安装失败有的用户跑在什么权限都没有的受限环境里还有的用户系统里存在多个Python版本脚本里的依赖装到了另一个解释器里。我给的解决思路是三级回退。第一级启动时运行系统命令检查依赖通过importlib.util.find_spec判断是否能导入第二级缺依赖时尝试用pip install --user安装优先满足当前用户环境第三级安装失败时打印明确的错误提示和手动安装命令不静默失败。还有一类问题是网络受限环境的离线运行。我最终做了一个“依赖预置”变体版本把所有需要用到的第三方库的核心代码直接合并进单文件脚本里。Pillow的代码量太大不好整包合并所以我替换成了纯标准库的PNG读取逻辑只支持BMP和PNG格式的桌面截图存储和裁剪。这样一来这个变体脚本在完全离线的Python环境里也能跑通全套功能代价是封面截图没有压缩、体积变大。不过对无人值守服务器来说这个取舍非常划算。4.5 常见问题速查表现象可能原因排查建议MCP握手失败协议版本不匹配或配置错误查看MCP服务器stderr日志核对版本和启动命令点击位置偏移高DPI缩放未处理或屏幕坐标系错乱检查缩放因子确认多屏负坐标换算键盘输入丢失窗口未激活或输入间隔太短先SetForegroundWindow再输入并加防抖模型反复执行无效操作界面状态反馈缺失执行后截图并做界面状态差异判断工具名冲突MCP工具与内置工具重名强制加前缀隔离命名空间自动安装依赖失败pip环境异常或网络受限使用--user参数或手动安装命令做回退除了这些已经列出来的问题我最后还想分享一个可能被长期忽略的细节GUI代理的任务日志非常值钱。我给每一次点击、输入、调用都打上了带时间戳的日志并且保留每一步的截图缩略图。出现事故时翻日志和截图基本就能还原现场不需要用户复述。这个习惯救了我很多次也让我能不断修正代理的失败行为。这个项目到目前为止还在持续小步迭代。最近我在考虑把GUI确认弹窗改成支持语音播报让代理在操作前用语音读一遍它要执行的步骤适合辅助不方便看屏幕的场景MCP那边也在考虑支持通过配置文件同时连接多个服务器让代理并行调度多个外部工具。单文件这个约束我会一直保持下去它逼着我不断简化依赖和接口让整个工具始终保持在“一个脚本能讲清楚”的复杂度以内。如果你也在做类似的AI代理或者GUI自动化工具希望上面这些踩坑经验和架构思路能帮你少走一段弯路。