开源AI编码代理实战：GUI自动化、MCP接入与单文件打包

做这个 AI 编码代理，起因是我在几个编程助手之间折腾了好一阵，发现它们有一个共同的死穴：只能处理代码文件和终端命令，一旦任务里出现“打开系统设置、点几下界面、拖一个滑块”这种操作，就直接罢工。我当时想，与其等那些商业工具慢慢补上 GUI 自动化能力，不如自己动手写一个免费开源的小工具，让大模型拥有真正的“眼睛”和“手”，能够操作图形界面，同时通过 MCP 把外部工具链也串起来，最后用单文件方式发布，拿到哪台机器都能直接跑。

项目本身不大，但涉及的点不少：GUI 操控怎么做得稳、MCP 怎么当个 host 接入现成生态、打包成单文件又怎么处理依赖地狱。这篇文章把设计思路、核心实现、实操过程和我踩过的坑全部整理出来，希望能给想入坑 AI 代理开发的朋友一些参考。

1. 这个项目到底解决了什么问题

1.1 现有 AI 编码工具的痛点在哪里

如果你用过市面上的 AI 编程助手，你会发现它们的能力边界其实非常清楚：改代码、查文档、跑命令行、生成 diff，这些是强项；但只要任务牵涉到图形界面操作，基本就是空白。举个例子，你想让 AI“打开项目的编译设置，把优化等级从 O0 改成 O2，然后点保存”，普通编码助手顶多帮你改改配置文件里的参数，至于打开设置面板、在 GUI 里找到那个下拉框、点击确认按钮，这些它全都做不了。

更深层的问题是：现在很多开发工具本身就重度依赖图形界面，比如 Xcode 的签名配置、Visual Studio 的 NuGet 包管理器、各种数据库客户端里的可视化查询界面。如果你希望一个编码代理能端到端地完成“打开项目 → 调整界面配置 → 跑构建 → 查看结果”这条完整链路，它就是绕不开 GUI 这个环节的。我之所以决定自己写，正是因为意识到这个缺口在一段时间内不会有现成方案补上——商业产品更愿意在纯代码领域堆能力，GUI 自动化的坑太多、收益又不够立竿见影。

这个项目的目标很简单：做一个免费、开源、可在本地跑的 AI 编码代理，它既能跟其他助手一样写代码、跑命令，也能像人一样盯住屏幕、操作界面，再通过 MCP 挂上数据库、文件系统这些外部能力，把“想法”变成“真实操作”。它能覆盖的场景，恰好是传统编码助手够不到的那一块。

1.2 项目定位：AI 编码代理到底是个什么角色

很多人会把“AI 编码助手”和“AI 编码代理”混为一谈。我的理解是：助手只能在你给它划好的轨道里回答问题或改文件；代理不一样，它有一个自主循环——先理解任务，然后自己规划步骤，调用工具去执行，观察执行结果，再决定下一步做什么，直到任务完成为止。换句话说，代理是一个“主动干活”的角色，而不是一个被动的问答框。

在这个项目里，代理的工作模式大致是这样的：你给它一个任务描述，比如“把项目里所有的 TODO 注释整理成一份 Markdown 报告，并用 GUI 打开给我看”，它就拆解成几个子目标——扫描代码、收集 TODO、生成报告、用文本编辑器打开报告。前面几步靠命令和代码操作完成，最后一步就需要 GUI 能力了。这个过程完全在本地运行，模型 API 由你自己配置，费用透明，没有黑盒，也不会把你整个项目的代码悄悄传到某个不透明的服务器上。

目标用户其实很清晰：一是做 AI 自动化和 RPA 方向研究的开发者，二是希望给现有开发工作流增加“最后一公里”能力的工程师，三是对大模型应用感兴趣、想学习 Agent 架构的爱好者。这个项目不追求商业级产品的打磨程度，但胜在足够轻、足够开放，你可以随便改、随便扩展。

2. 整体架构与技术选型分析

2.1 GUI 操控的三条技术路线与选择

真正动手做 GUI 自动化时，你会发现可选的技术路线其实就那么几条，各自优劣势非常明显。我整理了一个对比表，也是我最初调研时给自己列的：

这个项目采用的是“UI 自动化树优先，OCR 兜底”的混合方案。原因很实际：我们面对的主要场景是 IDE、系统设置、文件对话框这些桌面程序，它们大多数都暴露了无障碍接口，可以从控件树里拿到按钮、输入框、菜单这些语义化元素。相比截图后让大模型去猜坐标，UI 树的信息更干净，也不占多少 token。只有在某些控件拿不到、或者目标窗口完全没有无障碍支持时，我才会回退到截屏加 OCR，让模型根据截图内容确认目标。

还有一个很容易踩的坑是 DPI 缩放。如果显示器的缩放比例不是 100%，截图坐标和系统逻辑坐标会不一致，点击位置就会偏。解决方法是调进程的 DPI Awareness，然后按缩放系数换算坐标。这个细节看起来小，但如果不处理，整个代理在大多数 Windows 电脑上都会点不准。

2.2 为什么要把 MCP 做成第一公民

MCP（Model Context Protocol，模型上下文协议）现在已经成为模型工具生态的一种事实标准，简单理解，它就是一个给大模型挂外部工具的“统一接口”，工具箱里的工具都遵循同一套 JSON-RPC 2.0 通信规范。你在代码里不需要为每个外部服务单独写适配器，只要有一份 MCP 客户端去连接各个 MCP server，工具描述和调用结果就会自动变成标准格式给到模型。

我在这个项目里选择把 MCP 做成第一公民，原因有两个。第一，生态价值大。GitHub、数据库、Figma、浏览器、文件系统等等，已经有大量的现成 MCP server，我挂上它们就等于立刻让代理有了连接外部世界的能力，省去了把时间花在重复封装 API 上。第二，反向价值也很大。这个代理本身也可以作为一个 MCP server 暴露给其他客户端，比如 Claude Desktop、自己写的其他 Agent，这样别人也能通过标准协议调用我的 GUI 操作能力。

MCP 本身是一个非常轻的协议，核心就几个调用：initialize 握手、tools/list 拿工具列表、tools/call 调用工具。代理在启动时读取一个 JSON 格式的 server 配置，用 stdio 方式把本地命令跑起来，然后通过这个子进程和 MCP server 通信。整个过程不需要网络，不依赖某个云服务商，隐私和可控性都在自己手里。

2.3 单文件运行的技术取舍

为什么一定要做成单文件？我的出发点很朴素：一个工具如果部署起来要先装 Python 环境、再拉一堆依赖、还要处理版本冲突，绝大多数人就不会用了。打包成单个可执行文件之后，用户体验就是“下载一个文件，双击运行”，这对一个开源小项目来说非常重要。我自己在分发东西时最烦的就是依赖地狱，所以这个项目从一开始就把单文件当成硬性指标。

技术选型上，我最终用的是 Python 加 PyInstaller 的 --onefile 模式。为什么不用 Go 或 Rust？因为 GUI 自动化这个领域，最成熟的开源库几乎都在 Python 这边，比如 pyautogui、mss、uiautomation，而 MCP 官方的 Python SDK 也很完善，生态可以直接吃。Go/Rust 虽然也能调系统 API，但很多封装要自己重写，做小项目时间成本太高。

代价也很明确：Python 打包出来的单文件体积偏大，尤其把大模型 SDK 和一堆依赖打进去，很容易到一两百 MB；启动时还要解压到临时目录，所以第一次启动明显慢一点；个别杀毒软件还会对 PyInstaller 特征误报。这些我在后面“单文件打包的配置与体积优化”一节里会讲清楚怎么处理。

3. 核心实现细节与实操要点

3.1 让大模型“看见”屏幕：截图、OCR 与 UI 树三合一

整个 GUI 操控模块的入口是“观察屏幕”。它有三个数据来源：全屏截图、OCR 文本、无障碍控件树。我封装了一个统一接口，让上层不用关心具体数据格式。

先说说最常用的无障碍控件树。在 Windows 上我用的是 uiautomation 这个库，它背后是系统自带的 UI Automation 框架，能拿到绝大多数原生程序的控件结构。比如你打开记事本，控件树里会有一个 Document 控件，里面是 Edit 区域，窗口标题栏上还有 System Menu Bar 按钮等等。这些控件都带属性：ControlType、Name、AutomationId、BoundingRectangle，足够的上下文让模型判断该操作什么。

但是控件树有一个烦人的问题：数据量大。一个复杂的窗口可能有好几百个节点，全量塞给模型不仅浪费 token，还可能把模型“带偏”。所以我在送模型之前会做一轮过滤，只保留可交互的控件，比如按钮、菜单项、编辑框、复选框，忽略掉静态文本和装饰性元素。这步过滤能砍掉大概 70% 的冗余信息，模型的理解准确率反而更高。

再看截图和 OCR 的兜底路径。在代码里，我用 mss 做高效截图，然后根据任务复杂度决定走哪条路：如果 UI 树已经给了足够信息，就直接用控件定位；如果控件树拿不到或目标元素属于自绘控件（比如某些游戏引擎界面、Electron 的特殊区域），就把截图传给 OCR，或者直接把压缩后的图片交给多模态模型识别。这里有个小经验：传图给多模态模型时，别传原始分辨率，按宽度 1024 以内缩一下，既能保住关键信息，又能省大量 token。

OCR 我一般用 Windows 自带的 OCR 引擎或 PaddleOCR，具体看目标机器的环境。对于“窗口中某个按钮上的文字被识别出来，然后点击对应坐标”这种任务，稳定度比想象中高，只要界面不是动画特别频繁的状态，基本都能点中。

3.2 MCP 工具注册与调用的具体流程

MCP 模块在项目里承担“给代理接上外部世界”的职责。我设计了三层结构：配置层、客户端层、桥接层。

配置层是一份 JSON 文件，里面列出要启动的 MCP server。配置格式大致是这样：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"], "env": {} }, "github": { "command": "docker", "args": ["run", "--rm", "-i", "mcp/github"], "env": { "GITHUB_TOKEN": "xxx" } } } }

代理启动时，会逐个读取这份配置，用 subprocess 拉起子进程，然后通过 stdio 和 MCP server 建立连接。这里值得注意的一点是，MCP server 本身不要求必须是同一个语言写的，它们只是通过标准输入输出来收发 JSON-RPC 消息，所以你可以混用 Python、Node、Docker 里跑的 server，只要协议正确就行。

客户端层我用的是 MCP 官方 Python SDK，处理了 initialize 握手、工具列表拉取、错误码这些底层细节。真正需要自己写的是桥接层：把 MCP 的工具描述转换成大模型 API 认识的 function calling 格式。比如 filesystem server 里有一个read_file工具，它的输入参数是一个文件路径，我就把它包装成一个 name 为filesystem_read_file、parameters 里含path字段的 OpenAI 风格函数定义，这样模型在规划阶段就能“看到”这些工具。

调用过程也不复杂：模型在回包里声明要调用某个 tool，代理收到后把参数转交给 MCP 客户端，客户端通过子进程发 tools/call，拿到结果再回传给模型。整套流程里最容易出问题的是超时和异常处理，因为 MCP server 可能是网络服务、可能是本地脚本，任何一步都可能卡住。我在桥接层统一加了 timeout 和重试机制，单个工具调用超时默认 60 秒，超时后把错误信息塞回给模型，让它决定要不要换一条路径。

3.3 单文件打包的配置与体积优化

PyInstaller 打包单文件本身不复杂，真正的坑都在细节里。我的 .spec 配置大致如下：

# build.spec a = Analysis( ['main.py'], pathex=['.'], binaries=[], datas=[('config.example.json', '.')], hiddenimports=[ 'mcp', 'mcp.server', 'mcp.client.stdio', 'uiautomation', 'mss', 'PIL', ], hookspath=[], runtime_hooks=[], excludes=['tkinter'], ) pyz = PYZ(a.pure) exe = EXE( pyz, a.scripts, a.binaries, a.datas, [], name='code_agent', debug=False, strip=False, upx=True, console=False, icon='icon.ico', )

几个关键点我单独说一下。

第一，hiddenimports 必须手动写全。MCP SDK 里有大量动态导入，PyInstaller 的静态分析经常漏掉，不写全的话打包出来的程序一运行就报ModuleNotFoundError，而且只在客户机器上报，你自己本机可能完全正常。

第二，upx=True可以显著减小体积。UPX 是一个可执行文件压缩工具，PyInstaller 可以直接调用它。但要注意，个别杀毒软件对 UPX 压缩过的文件比较敏感，如果遇到误报，可以把 UPX 关掉重新打包，体积大一点但更“干净”。

第三，console=False会隐藏命令行窗口，但代价是程序里如果有什么错误信息也看不到了。我的做法是加了一个--debug参数，调试模式下重新编译成带 console 的版本，方便看日志。发布版保持隐藏窗口，避免弹出一堆黑框影响体验。

体积优化方面，我做了两步。第一步是排除无用库，比如这个项目根本没用到 tkinter，就干脆在 excludes 里删掉，能省几 MB 而且少一些问题。第二步是精简依赖，MCP 官方 SDK 的体积其实不小，如果只用到 stdio transport，就没必要把 SSE、WebSocket 相关的依赖模块全部带进来。这两步做完，整个单文件从接近 200MB 降到了 120MB 左右，对于一个塞了大模型 SDK 的工具来说还算能接受。

4. 完整实操：从空白目录到跑通一个场景

4.1 项目初始化与依赖清单

这个项目我用的是 Python 3.10，理论上 3.8 以上都能跑，但 3.10 对类型注解的支持更舒服。先创建一个虚拟环境，然后把依赖装齐。

python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate pip install mcp mss pyautogui uiautomation openai anthropic pillow pyinstaller

依赖清单里，mcp是 MCP 官方 SDK，负责和 MCP server 通信；mss用来高效截屏；pyautogui负责模拟鼠标键盘操作；uiautomation读取 Windows 无障碍控件树；openai和anthropic分别是两家大模型 API 的 SDK，这个项目里你选一家配 API Key 就能用；pillow用来做截图压缩和简单图像处理。

整个项目的文件结构我保持得很简单，核心就是三个 Python 文件加一个配置模板：

code_agent/ ├── main.py # 入口，读取配置，运行主循环 ├── screen.py # 截图、OCR、UI 树采集与过滤 ├── mcp_bridge.py # MCP 客户端封装和工具桥接 ├── executor.py # 把模型决策翻译成 GUI 动作和系统命令 ├── config.example.json # 配置模板 └── build.spec # PyInstaller 打包配置

4.2 核心代码骨架讲解

主循环是全项目最关键的部分，它做的事情是：拿到用户任务，和模型多轮对话，在每一轮里检查模型是否要求调用工具，如果要求了就去执行，然后把结果返回给模型，循环往复，直到模型给出完成信号。

def run_agent(task: str): messages = [{"role": "user", "content": task}] tools = load_global_tools() # 拼接 GUI 工具 + MCP 工具 for step in range(MAX_STEPS): response = llm.chat(messages, tools=tools) messages.append(response) if response.finish_reason == "tool_calls": for call in response.tool_calls: result = execute_tool(call.function.name, call.function.arguments) messages.append({ "role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False) }) else: return response.content

这里有一个我在调优中发现的点：要给模型一个明确的工具使用规范。比如“点击某个按钮”之前，必须先调用screen_get_uia_tree获取当前窗口的控件列表，模型自己要判断目标按钮的坐标，再调用gui_click。如果省掉这一步直接让模型猜坐标，成功率会大幅下降。所以在系统提示词里，我把步骤写成了固定的套路：观察 → 决策 → 执行 → 再观察。

GUI 工具的响应格式也很讲究。get_uia_tree返回的不是原始 XML，而是一个经过过滤和精简的 JSON 数组，每个元素就是{index, type, name, position}这种结构，索引是快捷方式，模型可以直接说“点击 index 5 的元素”，省去理解一堆控件属性的开销。

4.3 端到端实操案例：让代理用 GUI 打开图片并另存

光讲代码骨架有点抽象，我拿一个实际跑通过的案例走一遍流程。任务很简单：让代理找到本地一张图片，用系统自带的画图程序打开，再把尺寸调整一下并另存为 PNG。

这个案例的特别之处在于，它同时用到了 MCP 和 GUI 两条能力线。第一步，代理先调用一个文件系统的 MCP 工具，列出某个目录下的文件，确认目标图片路径。这里的好处是，文件扫描这种操作用代码实现更靠谱，没必要通过 GUI 去翻文件夹。紧接着，代理调用gui_launch_app启动画图程序，等窗口出现后，再调用uiautomation拿到菜单栏的控件树，认出“文件”菜单的位置。

等画图程序打开后，代理开始操作：用键盘热键 Ctrl+O 唤起“打开”对话框，接着在对话框里用 UI 树找到文件名输入框，填入图片路径，按下回车。到这一步，GUI 自动化的“打开文件”这段就走完了。接下来它用同样的思路从菜单栏里找到“调整大小”按钮，点开之后在对话框里改成 50%，确认。最后通过菜单把文件另存为 PNG 格式。

执行过程中有一环让我印象深刻：另存为对话框里的“保存类型”下拉框，UI 树里拿到的是一个 ComboBox，里面有一堆文件格式选项。模型一开始选错了格式，但代理的执行器在点击之后会用 UI 树再拉一次当前对话框的状态，发现类型还没变，于是把错误信息反馈给模型，模型重新读控件树，找到正确选项再点一次。这种“观察-执行-验证”的闭环，是代理能真正稳定工作的关键。纯命令行的代理做不到这一点，因为它无法感知 GUI 里的状态变化。

我把这个案例的每一段执行记录都打印到了日志里，用户能看到代理每一步在做什么、为什么这么做，透明度比黑盒调用来得高得多。这也是我认为代理类工具必须具备的素质：它的每一步操作都可能出错，如果用户不能介入修正，这个工具就不可用。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

开发这个项目的过程中，我踩过不少坑，也收到过一些使用反馈。整理成速查表，遇到类似问题可以直接对照解决。

5.2 踩过最深的几个坑

第一个坑是 UI 树数据过载。最开始我直接把整个窗口的控件树传给模型，结果上下文一下子就爆了，而且模型经常找错按钮。后来加了过滤和排序，只保留可交互控件，并且把窗口标题、位置这类元信息单独摘出来，模型确实变“聪明”了。这个经验的核心是：给模型的信息不是越多越好，而是越有决策价值越好。有些开发者喜欢把所有状态都塞给模型，这其实是浪费 token 还增加噪声的做法。

第二个坑是窗口遮挡。代理在截屏时如果窗口被其他窗口盖住一多半，UI 树仍然能拿到完整元素，但像素级截屏就会得到残缺画面。如果这时候走 OCR 兜底，就很容易识别错。我的解决办法是：执行点击动作之前，先用SetForegroundWindow或 macOS 的activate接口把目标窗口带到前台，等它激活了再截屏。这个“激活窗口再观察”的顺序，基本上能解决 90% 的遮挡问题。

第三个坑是高 DPI 环境下的坐标换算。这个问题我在前面提过，但值得再强调一遍。Windows 系统里，如果你的代码拿到的控件坐标是“物理像素”，而 pyautogui 默认用的是“逻辑像素”，两者之间就有差值。你需要先调用ctypes.windll.shcore.SetProcessDpiAwareness(1)之类的接口，再统一坐标体系。我最初的版本没有处理这个，导致 4K 屏加 150% 缩放的机器上，代理点击的准确率惨不忍睹。这个问题排查了很久才发现，归根结底是因为我自己一直用 100% 缩放的显示器调试，根本没有暴露出来。

第四个坑是 MCP 子进程的编码。在 Windows 上，有些 MCP server 启动后输出的不是 UTF-8 编码，或者带 BOM 头，Python 的 subprocess 在解析 stdio 时就会报错。处理方式是在启动参数里强制设置环境变量PYTHONUTF8=1，并且用errors='replace'做解码兜底。这种问题非常隐蔽，但一旦遇到，整个代理的 MCP 能力就瘫痪了。

6. 后续扩展建议与个人体会

6.1 这个架构还能往哪里延伸

项目做到现在这个程度，其实已经是一个很顺手的骨架了。以我目前的规划，接下来有几个明确的方向。

第一个方向是接入视觉语言模型做屏幕理解。现在的方案以 UI 树为主，但面对没有无障碍接口的程序还是有点吃力。如果能本地跑一个 Qwen2.5-VL 这类小参数视觉模型，只用来做“截图里的按钮在哪”这种识别任务，不参与主对话，就能在不消耗主模型太多 token 的情况下补齐最后一环。

第二个方向是把代理反过来暴露成 MCP server。这个项目目前是 MCP host，去连接别人家的 server；但它也可以被别人当作 server 来用。比如你在 Claude Desktop 里给它接上，告诉它“帮我打开本地的某某工程，跑一下里面的脚本”，Claude 就能通过 MCP 调用这个代理，进而操作你电脑上的 GUI 程序。这个玩法很有意思，等于给自己常用的编程助手也接上了一双“手”。

第三个方向是任务记忆和长期规划。现在的代理还是“一拳一个目标”式的，执行完一张图片处理任务就结束，不会记住你上次的设置偏好。如果把用户历史操作、界面偏好、常用工具配置持久化到本地，再让模型在规划时参考这些记忆，它就会越用越顺手。这其实也是 Agent 类产品从“能用”走向“好用”的关键一步。

6.2 做这个项目的一些真实感受

写代码本身不难，难的是把异常路径处理得足够稳。我在调试过程中发现，AI 代理的最大问题通常不是模型不够聪明，而是工具链不够可靠。一次点击失败、一次 MCP 超时、一次坐标换算错误，就足以让整个任务在中途崩掉。模型虽然有纠错能力，但它能纠正的次数是有限的，前提是错误信息能准确返回到它手里。所以在这个项目里，我对“执行反馈”的重视程度远高于对“规划能力”的重视程度——规划错了模型自己会改，执行错了反馈不全面，模型就只能在原地打转。

这个工具本身是免费开源的，我也没打算靠它盈利。当时做的时候的一个朴素想法是：如果有一天，有人想给自己的开发流程加一双“看得见摸得着的手”，能有一个开箱即用的起点，那这个项目的价值就实现了。现在它已经能稳定跑通不少场景，如果你也感兴趣，拉一份代码下来，装好依赖，按着这篇文章里的思路把它跑起来，再顺手加几个自己需要的工具，说不定它很快就会变成你日常开发里离不开的那个小助手。