我做了个免费的AI编码代理它能直接操控GUI应用也支持MCP工具调用最关键的是整个项目打包成了一个单文件不用装环境、不用配依赖拿到任何一台Windows机器上都能跑。这个想法起源于我自己的一堆重复劳动打开配置工具、切换页面、点按钮、等结果、复制数据、填到另一个窗口里……这些动作没有技术含量但非常消耗耐心。市面上的AI编码助手大多停留在编辑器里能补全代码、生成diff但没法替我去点击那些没有API的图形界面。于是我就想做一个“自己的AI操作员”用户只需要说一句“打开那个窗口把参数改成50然后跑一遍”它就能自己规划操作步骤并执行。这个东西适合谁如果你是开发、测试、运维或者经常需要操作多款GUI软件的人它能帮你把“看界面→点鼠标→读结果”的流程自动化。如果你在研究MCP协议想接入自己的工具它也能作为一个现成的参考实现。本文我会从设计思路、技术拆解、完整实现到打包出单文件把关键细节和踩过的坑都写出来你可以照着搭一套。1. 为什么需要这样一个AI编码代理1.1 问题从日常重复操作开始我工作里有一类很典型的任务每天早上要打开内部数据管理工具按指定条件筛选数据导出表格再打开另一个报表软件把导出的内容整理成固定格式。这个流程没有任何创造性而且工具都是老旧的GUI程序根本没有命令行接口更别说API。我也试过用按键精灵、AutoHotkey写固定脚本但一旦界面布局调整脚本就全废了。写一次性的Python自动化脚本也只能解决单一场景换个窗口就要重写。后来我开始在AI编码助手里描述这些操作希望它能生成一个pyautogui脚本。问题在于AI只会生成代码不会自己执行和调试它不知道屏幕上实际的坐标是多少看不到点击后弹出的对话框更不会根据执行结果修正下一步。于是我想能不能做一个“能自己看屏幕、自己执行、自己纠错”的AI编码代理它不再停留在生成代码的层面而是把生成的代码直接运行起来并观察运行结果是否符合预期。1.2 现有方案的三个空白我梳理了当时可用的工具发现存在三个明显空白第一大部分AI编码代理被设计在终端或IDE里运行它们能读写文件、执行shell命令但对系统图形界面天然“失明”无法主动寻找按钮、菜单和输入框第二MCP生态里虽然有不少工具服务器比如文件系统、数据库、浏览器但使用起来需要分别安装客户端、配置服务端和身份认证对一个只想快速完成任务的人来说太重了第三很多开源自动化项目要么体积大、依赖复杂要么需要特定的Python环境分发给别人用特别费劲。这三个问题指向同一个方向我可以把这些能力整合进一个统一的AI代理并把运行门槛压到最低——用户下载一个单文件双击就能跑不需要安装Python也不需要手动安装各种库。这样无论是自己用还是扔给团队里的人用成本都很低。1.3 我的设计目标我给自己定了几条硬性要求项目免费不藏付费点单文件分发用PyInstaller打包成独立的可执行程序原生支持GUI操控至少能在Windows上定位窗口、点击按钮、输入文本、读取控件内容同时实现一个MCP客户端让代理能通过标准协议调用外部工具和数据源整个执行逻辑对用户透明允许自定义系统提示词和工具清单。后面实现的每一步都是围绕这些目标展开的。2. 三个核心技术拆开看都不复杂2.1 AI编码代理到底是什么AI编码代理和普通AI编码助手的最大区别在于“自主执行”。普通助手是被动的你给它一段代码它回答你的问题补全你的思路。而代理是一个主动的执行体它接收到一个高层目标后会自己拆分步骤、调用工具、观察反馈、修正计划直到完成任务或明确需要用户介入。比如“把配置文件里所有timeout改成60”普通助手会生成一段sed命令然后你自己去跑。而我的代理会做这样的事先用文件工具找到配置文件读取内容分析哪些行包含timeout生成修改方案调用编辑器写入再重新读文件验证结果。如果中间发现路径不正确它会主动搜索文件名而不是直接报错。这背后的核心是一个“任务规划工具调用结果反馈”的循环而MCP和GUI控制是这个循环里最重要的两个工具出口。2.2 操控GUI的几种技术路线想要让AI操控图形界面首先得让程序“看见”界面元素。我对比过几条主流路线一是纯坐标模拟用pyautogui按固定坐标移动鼠标点击优点是简单缺点是屏幕分辨率一变就会失效二是图像识别用模板匹配或OCR定位目标元素优点是相对通用缺点是速度和准确率波动大三是操作系统辅助接口在Windows上走UIAUI Automation和MSAA可以直接读取控件树就像利用无障碍信息一样能拿到按钮的Name、ControlType、位置甚至控件里的文本。这种方法最稳定也不依赖屏幕分辨率但需要目标程序对辅助功能有基本支持。我的最终选择是混合方案优先用UIA去查找控件找不到控件时再用截图和屏幕坐标做兜底。这样既能拿到稳定的语义信息又能覆盖一些老旧的软件。这套思路本质上也是“先语义、后视觉”和人眼找按钮的逻辑很像。代码里我只暴露一个简单的find_element接口底层具体走UIA还是图像识别调用方完全不用关心。2.3 MCP协议到底是什么MCP的全称是Model Context Protocol翻译过来是“模型上下文协议”。它解决的问题很明确AI应用要接入外部工具、数据源和提示词不应该为每个工具单独写一套落后的SDK协议。MCP采用客户端-服务器架构一个MCP服务器对外暴露一系列“工具”比如操作文件、查询数据库、搜索网页而MCP客户端负责发现这些工具并统一调用。我看到的通俗类比是“AI领域的USB-C接口”——鼠标、键盘、显示器过去各有各的插头现在统一成一个标准口设备即插即用。MCP也是这样AI模型不需要关心某个工具是用Python写的还是Node写的只要它实现了MCP协议客户端就能用同样的方式调用。在我这个项目里MCP客户端是代理的一只“手”负责调用外部工具GUI控制器是另一只“手”负责直接操作界面。两者互不冲突组合起来能覆盖绝大多数任务。2.4 单文件运行的设计取舍单文件运行的直接好处是分发简单但代价是启动时会先释放临时文件体积会偏大而且资源文件需要额外指定。我用的是PyInstaller的--onefile模式它会生成一个独立的exe运行前在临时目录里解压Python解释器和依赖库。听起来很美好但实际有坑比如GUI控制库和MCP库依赖一些动态链接文件打包时漏了就启动直接报错再比如MCP服务器列表是外部配置文件如果忘记用--add-data打进去运行时就会找不到配置。解决思路有两步第一步所有外部资源配置都提供内置默认值第二步在程序启动时检查临时目录下的文件是否存在如果缺失就自动从可执行文件内提取。这样打包程序虽然体积大了一些但至少“双击能跑”这个体验是扎实的。3. 整体架构四个模块各司其职3.1 模块划分和运行流程整个代理我拆成四个模块LLM引擎、任务规划器、工具执行器、反馈观察器。用户输入自然语言后先交给LLM引擎把目标解析成结构化的任务描述任务规划器结合当前可用工具列表生成一个多步骤的执行计划工具执行器按计划依次调用MCP客户端或GUI控制器每执行完一步反馈观察器会把新状态比如屏幕截图、控件树、文件内容变化送回LLM引擎让它决定下一步动作。这个循环说得直白一点就是“AI出方案工具干活AI看结果”。没有规划器和观察器的AI只有一次性输出缺少“做完检查”这个关键动作。我实现时最深的体会是不要试图让AI一次性完成全部工作而是把大任务拆成很多次小决策每次决策只需要关注当前界面信息。这样就算某个步骤点错了AI也能根据反馈纠正不至于一条路走到黑。3.2 为什么用Python作为主力语言选择Python主要因为三点第一生态最合适pyautogui、pywinauto、uiautomation、mcp这些库都是Python优先第二开发效率高写一个原型只需要几百行代码第三PyInstaller的成熟度能很好地支持单文件打包。当然Python打包出来的exe启动速度偏慢内存占用也偏高但对于一个工具型应用来说多等两秒远比配置环境省心。在MCP客户端方面我优先实现了通用客户端对接的是任何标准MCP服务器。运行逻辑很简单启动时读取配置逐个连接到每个MCP服务器拉取工具列表放进提示词里告诉LLM有哪些工具可用。实际调用时LLM按约定格式返回一个工具调用请求客户端解析后通过JSON-RPC发送给服务器再拿回结果。整个过程对用户是隐藏的但用户能在日志里看到每一步调了什么工具、参数是多少。3.3 配置优先于硬编码我不想把工具清单写死在代码里所以做了一个YAML配置文件至少包含三部分MCP服务器列表、GUI应用快捷方式映射、执行策略参数。MCP服务器部分只需要填命令和参数比如本地启动一个文件系统服务器GUI部分可以把“打开报表工具”映射到具体exe路径执行策略部分设置超时时间和重试次数。这样换一台电脑时只改配置就行不用动代码。此外我还给每个工具声明了“影响范围”。比如读写文件的工具归为一类控制GUI的操作归为另一类。AI在规划时会优先选择风险最低的工具这也算一道简单的安全护栏。4. 从零到单文件完整实操过程4.1 环境准备与依赖安装我用的是Python 3.10安装了这样几个核心库mcp是官方客户端SDK负责与MCP服务器通信uiautomation用来读取Windows控件树pyautogui做鼠标键盘模拟和截图pyinstaller负责打包。如果你还打算做图像识别兜底那还需要opencv-python但不加也能跑通主体功能。pip install mcp uiautomation pyautogui pyinstaller安装之后我建议先跑一条最简单的UIA查询验证系统权限用uiautomation列出当前桌面上所有顶层窗口的名称。如果连这一步都失败大概率是权限不足因为UIA对被操作的程序也需要一定权限建议用管理员身份运行开发终端同时确保目标程序也是普通窗口程序。4.2 初始化MCP客户端MCP客户端初始化逻辑其实非常简单建立传输通道、发送initialize握手、拉取工具列表。官方SDK已经封装好了这些过程。我写了一个McpClient类专门负责管理服务器生命周期和工具调用。from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client class McpClient: def __init__(self, command: str, args: list[str]): self.server_params StdioServerParameters(commandcommand, argsargs) async def __aenter__(self): self.reader, self.writer await stdio_client(self.server_params) self.session await ClientSession(self.reader, self.writer) await self.session.initialize() tools await self.session.list_tools() self.tool_names [t.name for t in tools.tools] return self async def call_tool(self, name: str, arguments: dict): result await self.session.call_tool(name, arguments) return result.content这里有个容易忽略的细节MCP连接不是即时完成的需要几秒钟握手时间。我一开始把所有服务器串行启动结果慢得像蜗牛。后来改成并行连接同时最多连接三个服务器启动速度明显提升。另外MCP返回的工具参数结构比较复杂直接塞给LLM很容易让上下文爆炸我会先做一层精简只保留工具名和参数描述真正调用时再拼接完整参数。4.3 实现GUI控制核心GUI控制层的设计目标是“对AI友好”AI希望用自然语言描述元素而不是坐标。我封装了find_and_click、find_and_input、get_window_text这几个函数把底层UIA操作包起来。import uiautomation as auto import pyautogui import time def find_window(title_keyword: str): window auto.WindowControl(searchDepth1, Nametitle_keyword) if not window.Exists(3, 1): for win in auto.GetRootControl().GetChildren(): if title_keyword.lower() in win.Name.lower(): window win break window.SetActive() return window def click_button(window, button_text: str): btn window.ButtonControl(Namebutton_text) if btn.Exists(2): btn.Click() else: # 兜底在窗口客户区中心点击按钮 rect window.BoundingRectangle pyautogui.click(rect.left rect.width * 0.5, rect.top rect.height * 0.5) time.sleep(1)按钮命中的逻辑非常关键很多程序的按钮Text并不是肉眼看到的文字比如图标按钮只有Name属性是空的。我后来增加了一个“别名匹配”在配置里给每个按钮定义多个可能的文本值。如果UIA找不到再尝试图像匹配找到一张预先截好的按钮小图返回中心坐标。这套混合定位让成功率从六成提到了九成以上。4.4 把任务循环串起来核心执行循环我写成一个run_task函数接收用户指令返回最终结果。流程是先调用LLM生成计划然后顺序执行每个步骤每步执行完都收集新的观察信息再让LLM决定继续或修正。async def run_task(instruction: str, mcp_clients: list[McpClient]): plan await llm_plan(instruction, get_tools_summary(mcp_clients)) current_state await observe_desktop() for step in plan.steps: if step.tool gui: await execute_gui_action(step.params) elif step.tool mcp: client select_mcp_client(mcp_clients, step.server) await client.call_tool(step.name, step.params) current_state await observe_desktop() correction await llm_verify(step, current_state) if correction.needs_fix: plan.steps.insert(step.index, correction.new_step) return current_state这里observe_desktop负责收集屏幕信息包括当前活动窗口标题、可见控件列表以及按需截图。我特别控制观察的频率因为一次完整的控件树扫描可能要好几秒太频繁会让任务拖得很慢。经验做法是只在关键步骤之间观察同一步骤内的小动作不重复扫描。4.5 打包成单文件打包配置的关键是确保MCP服务器配置和GUI图标都被打进exe。我使用这样的PyInstaller命令pyinstaller --onefile --noconsole --name ai-agent ^ --add-data config.yaml;. ^ --add-data templates;templates ^ --hidden-import mcp.client.stdio ^ --hidden-import uiautomation ^ agent.py第一次打包时我漏了--hidden-import mcp.client.stdio结果exe一跑就提示找不到stdio_client。这是因为mcp客户端在导入时是动态加载子模块的PyInstaller静态分析发现不了。遇到这类“运行时才导入”的模块必须手动用hidden-import补上。另外--onefile参数会让程序启动时多一次解压过程所以我把启动欢迎语改成异步打印让用户第一时间看到界面实际后台逐步加载。4.6 配置示例与参数说明项目的配置我做成config.yaml供用户按需修改。下面是一个最小示例mcp_servers: - name: file_server command: python args: [-m, mcp_server_file] - name: db_server command: python args: [-m, mcp_server_sqlite, --db, test.db] gui_apps: data_tool: path: C:\\tools\\data_tool.exe window_title: 数据管理工具 execution: step_timeout: 15 max_retries: 2 observe_after_step: true我特别建议把step_timeout设得保守一些因为某些GUI操作会弹模态对话框程序会卡住等待用户确认。如果超时后还没反应可以让代理截图并询问用户。这种“人能介入”的接口很有必要总有一些任务必须人来兜底。5. 常见问题与排查实录5.1 UIA找不到目标控件这是最频繁的问题。原因通常是目标程序本身不支持UIA或者控件是自绘的。我的排查顺序是先用uiautomation自带工具Spy抓一下控件树看看目标按钮到底在不在如果在确认是Name还是AutomationId属性如果不在就切换到截图识别兜底。还有一个技巧是给窗口先发送一次点击或键盘按键有些控件只有获得焦点后才会渲染出子节点。5.2 MCP工具调用长时间没返回MCP服务器如果没起成功客户端会一直卡在连接上。我加了一个连接超时通过asyncio.wait_for把握手限制在10秒内。另外如果服务器返回内容特别大比如一个超大文件的内容会把上下文塞爆。我在客户端对返回内容做了截断默认只保留前2000字符并附带一个“内容过长已截断”的标记。这样AI不会因为信息过载而忽略关键步骤。5.3 单文件打包后体积大且被杀毒误报PyInstaller把Python解释器全量打进去体积很容易超过100MB。想瘦身有几个方向用--exclude-module排除用不到的库比如tkinter、test等如果只是给内部用也可以不加--noconsole保留控制台反而方便看日志。误报问题更麻烦因为PyInstaller生成的exe结构确实容易被安全软件怀疑。我的经验是优先做代码签名再提交给杀毒厂商申诉。如果只是个人使用临时加白名单也能接受。5.4 单文件运行时的临时目录导致路径失效--onefile运行时会把资源解压到一个临时目录如果代码里用了相对路径读配置文件可能读到临时目录下的文件但用户期望读exe旁边的文件。我的解决方案是优先读取exe所在目录的外部配置文件如果不存在再读取内置的默认配置。这样既保持了“单文件开箱即用”又保留了用户自定义覆盖的可能性。5.5 问题速查表症状可能原因处理办法启动后提示找不到模块PyInstaller漏掉hidden import用--hidden-import补模块名UIA扫描不到控件目标程序是自绘或老式控件切换截图识别或改用坐标兜底MCP连接卡住服务器启动失败或端口不通加超时查看MCP服务器日志点击按钮无效窗口未激活或控件被遮挡先SetActive()等待窗口置顶exe被杀毒误报PyInstaller特征区域代码签名提交厂商申诉任务一直重试步骤规划不合理调整提示词增加观察频率排查这些问题的过程中我最大的感触是“日志要够详细”。我在关键节点都打印了时间戳、调用工具名、参数、返回值摘要。哪怕只是简单的print也能在事后暴露很多问题。别小看这一步它能帮你快速定位到底是谁在拖后腿——是规划器、工具还是反馈环节。6. 实测效果和值得改进的方向我用这个代理跑通了一个实际场景每天自动打开一个老旧的配置管理程序通过UIA在窗口左侧点击“参数设置”在右侧输入框把某项阈值从30改成50然后点击“应用并重启”等程序重启后读取状态栏确认是否生效。整个过程如果人工操作大约要一分钟代理跑大概两分半看起来更慢但好处是一天跑十次也不会烦不需要人盯着。更重要的是代理能在执行过程中自主发现问题有一次重启后窗口标题变化了它通过观察发现新窗口名称不一致然后自动去匹配“配置管理”这个关键词重新绑定窗口继续操作这跟固定脚本比是质的不同。不过它也有明显短板面对完全不认识的新界面时探索效率很低。因为UIA只能拿到控件树AI缺少“视觉理解”能力遇到控件特别复杂的软件会像瞎子摸象。另外LLM推理延迟依然是主要瓶颈每走一步都要思考几十秒交互感比较卡。长远来看把视觉语言模型和UIA结合起来让AI同时看截图和控件树应该能大幅提升对陌生界面的适应能力。MCP侧的扩展空间更大我的这个客户端只要再接上新的MCP服务器代理就能使用新的能力几乎不用改代码。这也是我建议你重点研究的方向。最后分享一个我踩过几次坑之后总结的经验不要把配置和工具体系一开始就做得太大。先用最简单的方式跑通“一个GUI操作加一个MCP调用”的最小闭环再逐步加功能。因为代理系统的调试难点在于“AI行为的不确定性”如果同时接入五个工具出了错你很难判断是规划错了还是工具参数错了。先稳定一个场景把日志和观察机制调顺后面加新工具其实就是增加配置而已。