前阵子我一直在折腾 AI 编码代理，市面上的主流 Agent 基本试了个遍。用下来的感受很直白：代码能力确实强，但它要么只能窝在终端里改文件、跑命令，要么得靠一堆插件和复杂环境才能跑起来。一旦遇到那种“要打开某个配置界面点几个选项、在图形工具里填表、拖拽操作后等结果”的任务，常见的编码代理基本就抓瞎了。可这些事儿恰恰是日常开发里最耗时间的部分。
所以我花了几周自己做了一个免费的 AI 编码代理。它除了能写代码、执行终端命令之外，最特别的是能直接操控 GUI——像人一样看屏幕、点按钮、敲输入框。同时支持 MCP，可以挂载各种外部工具，比如数据库、文件系统、测试平台。更关键的是，整个项目最终打包出来就一个可执行文件，扔到任何一台机器上双击就能跑，不依赖 Python 环境，也不需要安装乱七八糟的依赖。
这篇文章就把这个项目的设计思路、GUI 操控和 MCP 落地的技术细节、单文件打包的折腾过程，以及我在实际使用中踩过的坑全部拆开聊，希望能给你做同类工具时提供点参考。
1. 整体设计思路：为什么要把“看屏幕”和“写代码”放进同一个 Agent
1.1 现有编码代理的痛点
先说个我在实际工作中的场景。我用 AI 编码代理写了一个数据迁移脚本，脚本本身写得很好，但运行前需要在某个企业级管理工具的图形界面里做三步配置：勾选一个启用开关、填入数据库连接串、把运行模式从“dry-run”切成“live”。这个操作如果让人来点，十秒钟搞定，但让编码代理来做就非常别扭。
因为大多数编码代理本质上还是个“终端生物”。它通过命令行、文件读写、代码搜索这些工具来感知世界，对屏幕上的像素完全无感。如果目标软件没有命令行接口，或者它的 CLI 不够完善，代理就只能干瞪眼。传统 RPA（机器人流程自动化）虽然能点鼠标，但它本质上是在“录脚本”，界面一改就崩，更别提让它根据截图内容去推理应该如何操作了。
另外还有一个现实问题：很多 Agent 工具的安装和配置太繁琐。要装 Python 环境、要配各种 API Key、要管理依赖版本、要装插件。分享给别人用时，光环境问题就能劝退一批人。这也是我后来坚持“单文件运行”的直接原因。
1.2 设计目标：补齐“看界面”的能力
我的核心想法很简单：给编码代理加上一双眼睛和一只手。眼睛负责截图、理解界面；手负责点击、输入、拖拽、按键。Agent 的决策部分仍然交给大模型来完成，但它不仅能看代码，还能看屏幕。
这个思路与传统 RPA 有本质区别。RPA 是基于固定规则的回放，而我的代理是“目标驱动”的。比如给它一个任务：“打开设置面板，把自动更新关掉，然后截图确认”。它会自己截屏、根据屏幕内容决定点击哪个按钮、点击后再次截屏验证结果，如果没成功还会换一种方式再试。这就像把一个人派到陌生软件面前，让他边看边摸索，而不是给他一条画好的路线图。
为了不让这套能力变成孤岛，我还接入了 MCP。MCP 的全称是 Model Context Protocol，你可以把它理解成 AI 工具的 USB-C 接口标准：不同的外部工具（文件系统、数据库、浏览器、测试平台、设计稿工具）都通过统一协议暴露成 MCP Server，AI Agent 通过 MCP Client 去动态发现和调用这些工具。有了 MCP，我的编码代理就不是一个“只会点鼠标的傻瓜”，而是一个既能在 GUI 里操作、又能随时调用外部业务系统能力的复合体。
1.3 技术选型：Python 生态 + 兼容 OpenAI 接口的大模型
技术栈我选了 Python。理由很实际：GUI 自动化的核心库 pyautogui 成熟稳定，截图可以用 Pillow，窗口管理可以用 pygetwindow，图像分析可以直接交给支持视觉的多模态大模型，MCP 有官方 Python SDK。这些都是久经考验的轮子，没必要自己造。
大模型接入我做了兼容设计：任何提供 OpenAI 风格/chat/completions接口的模型服务都能用，只需要在配置文件里填 base_url、api_key、模型名称。实际测试中，我同时兼容了纯文本模型和带视觉能力的多模态模型。带视觉的模型可以直接分析截图，体验最好；纯文本模型也能用，只是 GUI 操作部分退化成“通过 OCR 识别屏幕文字”的方式，准确率会低一些。
整个 Agent 的循环结构也不复杂：观察（观察截图/工具返回结果）→ 思考（大模型产出下一步计划）→ 行动（调用工具）→ 观察反馈 → 循环，直到任务完成或达到最大轮数。这就是经典 ReAct 模式，但它比纯文本场景多了一个重要的“观察源”：屏幕像素。
2. GUI 操控能力的实现：从截屏到精准点击
2.1 观察层：截图与视觉模型配合
GUI 操控最难的不是“点击”，而是“知道往哪儿点”。我最初的方案是用 OCR 提取屏幕上的所有文字，然后把文字及其坐标交给模型，让模型根据文字位置去决定点击哪里。这个方案在小窗口内还行，但屏幕一复杂就露馅：按钮文字和描述文字混在一起，模型经常搞错坐标。
后来我换成了更符合直觉的做法：直接把截图丢给多模态大模型，让模型看到真实的界面。模型不但能描述界面上有什么控件，还能给出“这个按钮大概在截图区域的什么位置”。我再结合截图尺寸和屏幕实际分辨率做坐标换算，完成点击。
这一步有很关键的经验要分享：
- 不能用截图的全图坐标直接控制鼠标。不同操作系统在 DPI 缩放上的处理不同，Windows 常见 125%、150% 缩放。截图拿到的是“逻辑像素”，而 pyautogui 控制鼠标用的是“物理像素”，两者不一致会导致点击偏移。解决办法是读取系统缩放比例，做一个坐标乘子。实测在 Windows 150% 缩放下，逻辑坐标必须乘以 1.5 才能点准。
- 截图不带鼠标光标，但你可以用 PILLOW 画一个模拟光标，方便视觉模型理解当前焦点位置。
- 截图要控制裁切区域。多显示器场景下，主副屏坐标系统不一样，我默认只截主屏，避免坐标错乱。
2.2 操作层：点击、输入与快捷键
GUI 操作我封装成几个原子工具：click、double_click、input_text、press_key、scroll、drag。任何复杂操作都由这些原子工具组合完成。
点击这里有个细节：模型给出的坐标是“比例坐标”而不是绝对像素。比如模型说“这个按钮位于截图的 45%， 62%”，我再根据实际截图尺寸换算成像素。这样做的好处是，不同分辨率下截图缩放后，模型仍然可以稳定给出相对位置。
输入文本是踩坑重灾区。pyautogui 的typewrite只支持 ASCII，遇到中文直接乱码。我的方案是：遇到非 ASCII 字符时，先调用系统的剪贴板写入文本，再用ctrl+v粘贴。这个方案在 Windows、macOS、Linux 下都稳。另外，如果输入框本身支持右键菜单粘贴，也可以优先使用这个路径。
安全机制也必须设计好。AI 操控鼠标最怕的是它“乱点”，比如点到了危险的操作按钮。我做了一个“确认模式”：在高风险操作（比如点击删除、提交配置更改）之前，通过视觉模型识别按钮文字，若包含“删除”“清空”“重置”“提交”等关键词，会要求用户按一下确认快捷键才继续。同时注册了全局热键Ctrl+Shift+Q，任何情况下按下就会中断 Agent 执行，把鼠标控制权交还给用户。这个热键在开发到第 5 天时救了我一次——当时 Agent 在自动化测试工具里差点点了“恢复出厂设置”。
2.3 状态回读：点击之后必须验证
GUI 自动化有一个铁律：操作之后必须回读状态。因为界面可能弹出对话框、加载转圈、报错提示，这些都必须被模型“看见”才能做出下一步正确决策。
我在每次工具调用后都会强制截一张新图，返回给模型作为“操作结果”。同时我会用 OCR 提取屏幕上的弹窗文字，拼接到返回内容里，防止纯视觉模型漏看小字。这个细节让我 Agent 的成功率提升了不少。
说起来容易做起来难，这里有个性能问题：每轮循环都要调一次视觉模型，如果任务有 15 步，那就是 15 次带截图的多模态请求，单次任务耗时可能两到三分钟。但这是值得的，因为 GUI 操作必须步步为营。效率优化的办法是“截图差异感知”：如果前后两张截图完全一致，就说明界面没变化，可以跳过这次视觉分析，直接复用上一轮结论。实测一个 20 步的任务能省掉 5~8 次多余请求。
3. MCP 支持：让 Agent 长出手脚
3.1 MCP 协议的价值
MCP 解决的是“工具碎片化”问题。如果没有统一标准，每个 Agent 都要为每个外部系统写一套集成。比如你要让 Agent 查数据库，写一个数据库插件；要让 Agent 读测试报告，又写一个报告插件。插件越来越多，维护成本和失控风险都指数级上升。
有了 MCP，事情就清晰了。外部能力方按照协议实现一个 MCP Server，暴露若干“工具”。Agent 启动时会通过 MCP 协议列出这些工具（每个工具包含名字、描述、输入参数 Schema），然后把信息交给大模型。模型根据任务需要，动态决定调用哪个工具、传什么参数。整个过程和“USB 设备即插即用”非常像：一个支持 MCP 的 Agent，理论上可以连接任何符合协议的服务端。
3.2 Agent 内置工具：把本地能力 MCP 化
我给这个 Agent 内置了两个 MCP Server：
第一个是filesystem-tools，暴露了读写代码文件、搜索目录、查看 git 状态等操作。这些能力其实是编码代理的老本行，通过 MCP 协议暴露出去之后，我可以在外部写一个独立的工具服务，Agent 通过 MCP 去访问，而不是把所有代码耦合在一个主进程里。
第二个是gui-tools，也就是前面说的截图、点击、输入、按键等 GUI 操作。把它们封装成 MCP Server 有几个好处：一是接口标准化，未来如果换一个 Agent 内核，GUI 能力可以无缝迁移；二是便于做权限控制——通过 MCP Server 的配置文件，可以决定向 Agent 暴露哪些 GUI 能力。
外部服务可以通过两种方式接入：stdiotransport（本地子进程通信）和HTTP/SSEtransport（远程服务）。本地场景我用 stdio，比如把 Agent 接到一个本地文件索引服务上；远程场景我用 HTTP，比如需要访问团队内部的测试平台时，只要对方提供一个 MCP Server 地址即可。
3.3 MCP 与 GUI 的组合：复杂任务实操样本
举一个我实际用它跑通的场景：任务要求是“打开项目里的配置文件，把数据库连接超时时间从 10 秒改成 30 秒，然后在数据库管理工具的图形界面里验证连接，最后在浏览器里打开报表页面刷新数据”。
这个任务包含了三种生态：命令行/文件（编码能力）、GUI（数据库管理工具）、HTTP/MCP（浏览器报表）。放在传统 RPA 里，你得写三段不同脚本拼起来；而我的 Agent 处理方式是：
- 第 1 轮：调用
filesystem-tools打开配置文件，用大模型直接改超时参数。 - 第 3 轮：调用
gui-tools截屏数据库管理工具界面，识别连接配置窗口，填入新超时时间，点击测试连接。这一轮 GUI 上操作了 4 步。 - 第 7 轮：图片提示“连接成功”，接着调用
browser-mcp-server（MCP 暴露的浏览器控制能力）打开报表 URL，截图确认页面数据刷新时间戳。
整个过程顶层仍旧是一个 Agent 在统一调度，但底层工具来自三个不同的来源：文件操作、GUI 操作、MCP 远程服务。这就是我设计这个代理时最想看到的“混合作战”效果。
4. 单文件运行：从一堆 Python 脚本到一个可执行文件
4.1 打包路线：PyInstaller 的 onefile 模式
项目开发前期是标准的 Python 工程，带requirements.txt、虚拟环境、一堆.py文件。但我很清楚，这样没法交付给非技术朋友用。我要的是“一个文件、一步到位”的体验。
打包我用的 PyInstaller，关键参数就三个组合：
pyinstaller --onefile --windowed --name ai-agent codex_agent.py说下参数意图：
--onefile：把所有模块和依赖打进一个可执行文件。--windowed：Windows 下不弹出黑色控制台窗口。但注意，这个参数会让print输出不可见，所以我在代码里把所有内部日志都转向了日志文件，方便排查。--name ai-agent：指定产物文件名，不放默认的main。
真正的麻烦在于依赖。pyautogui、Pillow、mcp 这些库体积不小，特别是如果带上了整套视觉模型的 SDK，打包产物轻松超 200MB。我做了两件事来瘦身：
一是排除不需要的依赖。PyInstaller 在分析时经常“贪心”，把一堆用不到的子模块也打进来。我在.spec文件里手工处理了排除清单，比如把tkinter、matplotlib、numpy的某些子模块去掉（我的代码不用它们）。这一点经验是：不要盲信 PyInstaller 的自动分析，要看最终产物里有哪些冗余模块，把没用的从excludes里显式排除。
二是用 UPX 压缩可执行文件。UPX 能显著降低 Windows 可执行文件体积，但小心它对某些 DLL 会误伤，导致启动时报“内存不能为 read”。我最后是选择性启用，只压缩 pyautogui 和 Pillow 相关的纯 Python DLL。
4.2 资源与配置外置：单文件不等于封闭文件
“单文件运行”容易让人误以为所有东西都塞在一个文件里，连配置也不能改。实际上我在产物旁边放了一个自动生成的config.ini，首次运行 Agent 时会检测到没有配置文件，自动创建一份默认配置并用文本编辑器打开，用户只需要填 API Key、模型地址、截图保存路径等几项信息。
这样设计是为了兼顾“免安装”和“可配置”。如果所有配置写死，用户换个模型就得重新打包，太不友好。而配置文件外置之后，即使用户完全没有命令行经验，也能通过编辑文本文件完成个性化设置。
资源文件（比如提示词模板、内置工具的定义文件）我也外置到可执行文件同目录的resources/文件夹里。这会导致多出几个文件，但对于“单文件主程序 + 外置资源”的组合，用户仍然没有任何安装步骤，拷贝过去就能跑。
4.3 跨平台打包的注意事项
单文件化最大的坑在跨平台。PyInstaller 不能跨平台打包，也就是说 Windows 上打不出 Linux 可执行文件，Linux 上也打不出 macOS 的。我为三个平台分别准备了 CI 打包脚本。这里要提醒的事很具体：
- Windows 下要提前安装 Visual C++ 运行库。如果你的目标机器没有装各种运行库，打包出的 exe 在对方机器上可能启动报错。
- macOS 上 pyautogui 控制鼠标键盘需要辅助功能权限。首次运行会弹权限请求，用户必须在“系统设置-隐私与安全性-辅助功能”里勾选终端或者你的应用。这个步骤不能省，否则点击会静默失败。我在首启引导界面里专门放了一页说明，不然新手会以为软件坏了。
- Linux 下打包如果是无显示环境（只有 SSH），GUI 部分会失败。因为 pyautogui 依赖 X11/XWayland。我的处理是启动时检测显示环境，如果没有图形会话就自动禁用 GUI 工具，只保留 MCP 和编码能力。
5. 实测记录与问题排查：从跑通到跑稳
5.1 一个完整任务的实测流程
以“在画图工具中打开示例图片，将图片缩放到 60%，另存为 PNG 格式”为例，我实际跑出来的执行序列如下：
- 模型收到任务文本，调用
gui-open打开画图工具。 - 截屏，视觉模型识别到顶部菜单栏，坐标定位到“文件-打开”。
- 打开文件对话框，输入图片路径，点击“打开”。
- 截屏确认图片已加载。
- 模型识别到“调整大小”按钮位于工具栏第二排中间位置，点击。
- 弹出的百分比输入框被模型定位，执行
ctrl+A全选后输入 60。 - 点击“确定”，再截屏验证图片尺寸变化是否生效。
- 通过“文件-另存为”菜单，在保存对话框里输入文件名，格式选择 PNG，完成。
这个流程总计 8 轮循环，耗时约 3 分钟。比例坐标换算非常关键，如果某个操作因为缩放问题点偏了，模型回读截图后会自我修正，重新定位再点一次。
5.2 常见问题速查表
我把开发中遇到的高频问题整理成了表格，方便有心做类似项目的朋友直接对照：
| 现象 | 根因 | 排查思路与解决 |
|---|---|---|
| 点击偏到按钮左边/上边 | 系统 DPI 缩放导致坐标偏移 | 读取缩放比例，对坐标做乘子换算；或改为比例坐标+屏幕实际尺寸换算 |
| 中文输入变成乱码或没反应 | pyautogui 对非 ASCII 输入支持差 | 改用剪贴板+ctrl+v方案，或调用系统级输入事件接口 |
| 截图颜色像“负片” | Pillow RGB 与截图库 BGR 通道顺序不一致 | 检查通道顺序，用img.convert("RGB")统一格式 |
| 多显示器下鼠标飞走 | 主副屏坐标系统未归一化 | 限定主屏截图与操作，或为每个显示器建立独立坐标映射表 |
| MCP Server 能连上但工具调用失败 | 工具返回 JSON 格式不规范或超长文本截断 | 校验工具的输入输出 Schema，并在 Agent 侧对长文本做分块摘要 |
| 打包后 exe 启动闪退 | 缺 DLL 或 PyInstaller 分析遗漏模块 | 用--debug模式启动查看报错，检查.spec文件里的 hiddenimports |
| macOS 上点击没反应 | 未授予辅助功能权限 | 在“系统设置-隐私与安全性-辅助功能”中勾选应用，重启进程 |
| Agent 陷入死循环反复操作同一界面 | 模型误判“操作未生效” | 设置最大轮数上限；截图相似度达到阈值时强制停止，改为请求用户介入 |
5.3 印象最深的三条经验
项目做到后期，我最大的感触是：AI 操控 GUI 的真正难点不是技术，而是“信任边界”。模型再聪明，也不能替代人对系统产生的“敬畏感”——你永远不会让一个刚学会点鼠标的程序去执行生产环境上的破坏性操作。所以我加了很多机制：高风险动作二次确认、危险关键词识别、最大轮数上限、以及随时可以中断全局热键。看起来是额外功能，实际上是让这个工具真正能放心落地的前提。
第二条经验是关于 MCP 与 GUI 的边界划分。我一开始试图把所有 GUI 能力也直接写死在主 Agent 里，后来发现这样改哪里都得动主循环，风险大得很。重构为 MCP Server 之后，主 Agent 只负责调度推理，GUI 工具变成一个可插拔服务，代码结构瞬间清爽。建议后来者做类似项目时，把任何“可复用的能力”都往 MCP 协议靠拢，别偷懒塞进主进程。
第三条，也是很多人容易忽略的：单文件工具更要在日志上做文章。可执行文件不像源码那样可以用 IDE 调试，出问题时两眼一抹黑。我特意做了一个滚动日志文件，记录每一轮模型返回的内容摘要、每次工具的入参和出参、以及截图路径。排查问题时，先看日志就能定位八成问题，不必靠猜。
最后分享一个实用小技巧：我在 Agent 的“行动”阶段做了一层“执行前自检”——让模型在调用 GUI 工具前，用一句话说明“我要点哪个按钮、目的是什么”，如果这句话命中危险词表，就自动暂停。这个技巧让误操作的次数大幅下降，也能让用户肉眼看到它的决策过程。虽然只是一个小改动，但使用体验提升非常明显。这个项目后续我还会继续加补丁，比如支持更多远程 MCP Server、增加对 Wayland 会话的支持等等。如果你也在做类似的 Agent，希望这些踩坑记录能帮你少走几段弯路。
