单文件AI编码代理：融合GUI自动化与MCP协议的开源实践

写这个项目的时候我其实没指望它能火。当时手头堆了好几个重复性工作：改前端样式、调接口、整理 GUI 自动化测试脚本，每个都得开着 IDE 一遍遍手动点。后来我把常用的编码辅助能力封装成一个只有单个文件的 AI 编码代理，它能直接操控图形界面，也原生支持 MCP（Model Context Protocol），跑起来不需要安装一堆运行时依赖，复制到哪台机器都能用。这篇文章就把我的设计思路、实现细节、踩坑记录和完整实操过程一次性讲清楚，希望能给想自己做 AI 代理工具的朋友省点弯路。

1. 这个 AI 编码代理是什么，为什么我只用了一个文件

1.1 项目的起源与使用者画像

先说背景。2024 年底我开始大量使用大模型辅助写代码，但很快就发现一个痛点：模型只能在终端里生成文本，真正要让我去执行命令、改配置文件、点开设计稿看一眼效果，还得我自己手动来。对我这种习惯“能自动化就绝不手工”的人，这种割裂感非常难受。

这个项目定位是轻量级的本地 AI 编码代理，它把三件事揉进一个文件里：调用大模型接口的能力、操作 GUI 界面的能力、通过 MCP 连接外部工具的能力。它不追求像 Cursor 那样做一个完整 IDE，而是专注解决“AI 能看懂并操作我的电脑”这件事。

适合什么人来用呢？我梳理下来大概三类：

• 独立开发者：想给自己的编码工作流加一个可定制的 AI 协作者，但不想引入重型的 Agent 框架。
• 自动化测试工程师：需要让 AI 自动操作 Web 页面或桌面软件来完成回归测试，同时希望保留 MCP 生态里现成的工具。
• 对 Agent 原理好奇的技术爱好者：想看明白大模型究竟如何被转化成键盘鼠标动作和工具调用，单文件版本更容易通读源码，没有框架的层层封装。

1.2 单文件架构的好处与代价

把整个代理做成单文件的初衷非常实际：部署成本最低，分发最快。我的使用场景常在多台开发机和测试机之间切换，如果每次都要装 Python 包、拉依赖、配虚拟环境，那还不如直接手动操作。

单文件本质上是一个自包含的 Python 脚本，里面用到的第三方库我尽量控制在标准库加上pyautogui、Pillow、openai和mcp这几个核心依赖。这样做的代价也很明显：代码可维护性变差。2000 多行的单文件后期改起来确实会头疼，我的解法是用清晰的注释块和函数分区来弥补——把 GUI 操作、MCP 客户端、LLM 调用、工具注册表分别放在独立的分区里，本质上是“逻辑模块化，物理集中化”。

另一个实际好处是便于审计。AI 代理要操控你的桌面，安全性很重要。单文件意味着你可以全文搜一遍，看看它到底调了哪些系统 API、访问了哪些网络地址，不会藏在某个深层依赖包里做一些你毫不知情的动作。

1.3 免费方案的技术路线选型

“免费”是这个项目的重要标签，但不是指完全没有成本。我理解免费有三个层面：

第一，代理本身开源免费，源码随便改，不会像商业 Agent 产品那样有节点数量限制。第二，尽量兼容免费或低价的模型端点。主程序使用 OpenAI 兼容的接口格式，可以直接接入各种开放模型服务，也支持本地部署的模型，用 Ollama 或 vLLM 拉起来后填个地址就能用。第三，优先使用系统级 API而不是购买商业的 GUI 自动化服务。

我也试过用 Playwright 来驱动浏览器，后来发现它并不适合所有桌面应用。真正做通用 GUI 代理，还是得靠操作系统层面的辅助功能接口和图像识别结合，这部分后面展开。

如果你要快速判断这个方案是否适合自己，可以看一份简单的对比：

2. GUI 自动化：让 AI 看见界面，而不只是命令行

2.1 三条技术路线：辅助功能 API、图像识别、坐标模拟

AI 编码代理要操控 GUI，光是能“说话”远远不够，它得长出手和眼睛。我在实现中把 GUI 控制拆成三条技术路线，对应不同场景。

第一条是辅助功能 API。在 Windows 上对应 UI Automation，在 macOS 上是 Accessibility API，在 Linux 桌面则是 AT-SPI。这类接口能拿到界面元素的树状结构、控件类型、名称、位置、是否可点击等属性，相当于让 AI 拥有了“读屏”的能力。好处是定位精准，不会被背景图干扰，缺点是并非所有应用都实现了完整的辅助功能支持，Electron 应用有时候暴露的节点就残缺不全。

第二条是图像识别。我使用模板匹配加截图分割的方式，先截取全屏图像，再让视觉模型和本地模板库识别按钮、输入框的大致位置。这种方式最通用，凡是渲染到屏幕上的东西都能识别，但精度受分辨率、缩放比例和遮挡影响，而且需要调用者的视觉理解能力足够强。

第三条是坐标模拟。最简单粗暴，直接用pyautogui在计算出的屏幕坐标上执行鼠标点击、拖拽和键盘输入。它没有任何智能，但作为兜底手段很可靠——当前面两种方式定位失败时，我可以通过多轮截图让模型自己“看着屏幕摸索”。

我在项目里没有赌某一条路线，而是设计了一个GUI 操作分层调度器：优先尝试辅助功能 API，拿不到可靠元素就退回视觉识别，最后才使用纯坐标模拟，并且每一步都留有人工确认的开关。

2.2 我采用的分层策略：先走系统级接口，再退回视觉

这个“先系统后视觉”的顺序是有讲究的。我一开始反过来了，以为让视觉模型直接看截图最省事，结果挨了一顿现实毒打。

第一次测试让代理点击一个对话框里的“确定”按钮，它看到的截图分辨率是 2560x1600，按钮实际只占 30x20 像素，屏幕还开着通知弹窗。视觉模型给出的坐标偏了 120 多个像素，那一票直接点到了旁边的“取消”。后来我改成先查 UI Automation 树，通过控件的 AutomationId 拿到精确 BoundingRectangle，准确率立刻接近百分之百。

所以分层逻辑就很清楚了：

def locate_element(driver, target_desc: str): # 第一优先：辅助功能接口 node = driver.find_by_accessibility(target_desc) if node: return node.bounding_rect # 第二优先：视觉模型识别 screen = grab_screen() bbox = visual_model.locate(screen, target_desc) if bbox and confidence > 0.75: return bbox # 兜底：让模型基于完整截图推理坐标，并强制人工确认 return manual_confirmation_coordinate(screen, target_desc)

这套设计解决了实际工程里最核心的问题：感知可靠性。辅助功能 API 返回的是逻辑坐标系，即使用户把窗口拖到屏幕角落、缩放比例调成 125% 甚至 150%，它都能给出正确的点击位置。而截图识别受物理像素影响，在高 DPI 屏幕上经常需要额外的坐标变换。

提示：在高 DPI 屏幕上使用pyautogui时，Windows 默认的坐标系统可能和你截图的像素坐标不一致。务必调用SetProcessDPIAware()或使用ctypes.windll.shcore.SetProcessDpiAwareness(1)，否则点击位置会整体偏移。

2.3 如何防止 AI 把界面折腾坏：沙箱与步骤回滚

AI 操作 GUI 最大的风险不是不够聪明，而是乱点。我在项目里加了三层保护机制，缺一不可。

第一层是动作前确认。从“只读查询”和“写入操作”之间划了硬界限，查询元素坐标、读取窗口标题、获取控件文本这些动作全自动执行。点击、输入、拖拽、回车这类会产生影响的操作，默认进入确认模式，用户可以把确认级别调成完全自动、关键动作确认、全部确认三档。

第二层是步骤回滚快照。在执行一系列操作之前，我记录了窗口列表、剪贴板内容、当前活动窗口和各关键应用的状态。如果模型判断后续步骤遇到矛盾，或者用户主动喊停，代理能把焦点还原到操作前的状态。严格说这不是完整的系统级快照，但应付误操作已经足够。

第三层是危险操作黑名单。删除文件、修改注册表、格式化磁盘、向生产环境推送代码等操作直接拦截，需要单独的--danger-ok参数才能放行。这个灵感来自数据库领域的“安全模式”，其实任何 Agent 工具都应该有类似的闸门。

回滚逻辑的核心代码如下：

class GUIController: def __init__(self): self.undo_stack = [] def safe_execute(self, action: dict): if action["type"] in DANGEROUS_ACTIONS and not self.danger_ok: raise PermissionError(f"危险操作被拦截: {action['type']}") if action.get("need_confirm") and not self.auto_confirm: confirm = input(f"确认执行 {action} ? [y/N] ") if confirm.lower() != "y": return False self._capture_snapshot() self._perform(action) self.undo_stack.append(action)

这套机制让我敢在无人值守模式下跑一些简单的 GUI 自动化任务，就算模型犯了傻，最多也就多了一堆无意义的窗口操作，不会造成不可逆的破坏。

3. MCP 集成：把外部工具变成 AI 的手和眼

3.1 MCP 协议的核心概念回顾

在展开我的实现之前，有必要把 MCP 的几个核心概念简单交代清楚，因为网上很多讨论把 MCP 和普通函数调用混为一谈。

MCP 是一个开放协议，它的设计目标是让大模型应用以标准化的方式连接外部数据源和工具。传统方式下，你想让模型调用某个 API，得为每个 API 单独写适配代码。有了 MCP，工具提供方实现一个 MCP Server，把能力暴露成标准化的工具、资源和提示词，模型应用端实现一个 MCP Client，通过 JSON-RPC 消息发现和调用这些能力。

我重点用到了三类原语：

• Tools：可被模型调用的函数，有明确的输入 schema。
• Resources：可被读取的数据，类似文件系统的只读文件。
• Prompts：可复用的提示词模板，方便模型理解特定场景的处理方式。

我的编码代理核心就是一个 MCP Client。它启动时连接一系列 MCP Server，获取它们的工具列表，然后把这些工具声明动态注入到模型的对话上下文中。模型只要在回复里输出工具调用指令，代理就会路由给对应的 MCP Server 执行，执行结果再回传给模型，形成一个完整的“感知-决策-行动-反馈”闭环。

3.2 在单文件代理里实现 MCP 客户端

实现 MCP 客户端比我想象中轻量，现代 SDK 已经把底层 JSON-RPC 通信封装得很干净。我的代理启动时会扫描一个配置文件，里面定义了要连接的 MCP Server 列表，包括本地进程启动型和远程 SSE 型两类。

本地进程型的 MCP Server 用起来最方便：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"] }, "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } }

启动时代理会逐一拉起这些子进程，通过标准输入输出和它们通信。这样做的好处是每个 Server 独立隔离，挂了不会拖垮主进程。通信的核心代码简化后是这样的：

async def call_mcp_tool(self, server_name: str, tool_name: str, arguments: dict): server = self.servers[server_name] if not server.session: await server.initialize() result = await server.session.call_tool(tool_name, arguments) return result.content

说实话，真正常踩的坑不在 MCP 客户端本身，而在于工具描述的编写质量。模型是一个“睁眼瞎”，它只能通过工具名和描述来理解某个工具该不该调用。如果你的 MCP Server 返回的工具描述写得太含糊，比如一个工具名叫run，描述只写“执行命令”，模型大概率不敢调用，或者调用了但传参不对。我的解决方案是在本地代理内置了一个工具描述增强层，把从 MCP Server 拿到的原始 schema 和一段补充说明合并，这段补充说明由我自己根据实际使用经验撰写，比原始描述更贴近业务场景。

3.3 从写代码到操纵 GUI：MCP 在此场景下的真正价值

有人会问：既然代理已经能直接操作 GUI，为什么还要劳心费力接 MCP？我的理解是，GUI 操作解决的是“模拟人手的动作”，MCP 解决的是“获取只有工具才知道的结构化信息”。

举一个最典型的场景：让 AI 帮助调试一个前端页面。纯 GUI 操作时，代理截图看页面效果，点击按钮触发事件，但看不到控制台报错、网络请求状态和 React 组件树。这些信息藏在 DevTools 里，一个像素一个像素去读既不现实也不可靠。接上 Playwright 的 MCP Server 后，代理可以直接调工具取回页面 console 日志、network 记录和 DOM 元素状态，信息密度提升了几个数量级。

所以我在项目里始终把 MCP 放在和 GUI 操作平等的地位。GUI 是执行层，MCP 是感知层和扩展层。两者结合，AI 编码代理才不只是“会点鼠标的机器人”，而是“看得懂系统的协作者”。

我接过的几个典型 MCP Server 包括：

• Playwright MCP：浏览器控制和网页状态读取，前端调试神器。
• Filesystem MCP：让代理读写工作区文件，比命令行拼接更安全。
• Git MCP：仓库状态查询和常用 Git 操作封装。
• SQLite MCP：让代理直接查询本地数据库。

每一个都对应一种能力扩展。后续如果你想给代理增加新能力，不需要改主程序代码，只需添加一个 MCP Server 配置就可以了，这是这个架构我比较满意的地方。

4. 实操：从零构建一个可运行的免费 AI 编码代理

4.1 环境依赖与快速启动

下面进入可以照着做的部分。先说环境要求：Python 3.10+，Windows 10/11、macOS 或带桌面环境的 Linux 都可以。核心依赖只有五个：openai、pyautogui、pillow、mcp、pyyaml。

我自己比较推荐用虚拟环境来装依赖，虽然项目是单文件，但依赖隔离还是必要的：

python -m venv .venv source .venv/bin/activate # Windows 下为 .venv\\Scripts\\activate pip install openai pyautogui pillow mcp pyyaml

启动代理只需要一个命令，它会读取当前目录下的agent_config.yaml：

python coding_agent.py

如果你还没有配置文件，代理会生成一份默认配置，然后提示你填写模型 API 地址和密钥。

4.2 配置 LLM 接口：兼容 OpenAI 格式的端点

项目之所以能保持“免费”属性，很大程度在于它没有绑定特定的模型供应商。openai这个 Python 包支持自定义base_url，这意味着任何实现了 OpenAI 兼容 API 的服务都能接进来。

我的配置文件里有这么一段：

llm: provider: openai-compatible base_url: "http://localhost:8000/v1" api_key: "sk-local" model: "qwen2.5-coder-7b-instruct" temperature: 0.2

使用本地模型的好处很明显：延迟低、隐私好、可以无限调用。我最早用 Ollama 跑qwen2.5-coder-7b，一个 7B 模型在消费级显卡上跑编码任务勉强够用。后来换成 vLLM 部署的 32B 模型，正确率提升了但显存要求也上去了。

如果你只是试验，也可以填远程服务的地址，注意别把密钥提交到公开仓库。无论是本地还是远程，代理只在意你的 API 是否符合 OpenAI 的chat/completions格式。

4.3 GUI 控制核心代码实现

GUI 控制模块是整个代理里我最花心思的部分。完整代码太长，我把最关键的两个函数拆出来讲。

第一个是获取窗口信息和元素树。在 Windows 上我使用uiautomation这个库，遍历窗口的控件树：

import uiautomation as auto def dump_window_tree(window_name: str): win = auto.WindowControl(searchDepth=1, Name=window_name) if not win.Exists(3): return [] results = [] def walk(control, depth=0): for child in control.GetChildren(): result = { "type": child.ControlTypeName, "name": child.Name, "rect": child.BoundingRectangle, "automation_id": child.AutomationId, "enabled": child.IsEnabled, } results.append(result) if depth < 5: walk(child, depth + 1) walk(win) return results

这个函数跑一次大概需要 100 到 300 毫秒，返回的结果会转成文本描述塞给模型，让它知道界面上有哪些可交互元素。

第二个是执行安全的点击和输入：

import pyautogui def perform_click(x: int, y: int, click_type: str = "left"): pyautogui.click(x, y, button=click_type) return {"status": "ok", "position": [x, y]} def perform_type(text: str, interval: float = 0.02): pyautogui.write(text, interval=interval) return {"status": "ok", "length": len(text)}

你可能觉得这不就是pyautogui的封装吗？其实关键的并不是点击本身，而是模型如何决定点击哪里。我的流程是把 GUI 元素树和截图一起交给模型，模型输出结构化指令，比如：

{ "action": "click", "target": "确定", "source": "ui_tree", "bbox": [1234, 567, 1280, 600] }

代理验证目标坐标在屏幕范围内、属于安全区域后，才交给perform_click执行。

4.4 MCP 工具注册与调用链路

MCP 模块的实现在我项目里已经迭代了三个版本。第一版只支持本地 stdio 类型的 Server，第二版加了 SSE 远程连接，第三版完善了断线重连和工具缓存。

工具注册的核心逻辑是这样的：启动时遍历配置里的mcpServers，逐个建立会话，拿到工具列表后写入一个内存中的注册表。注册表项不是简单存工具名，而是把工具描述、参数 schema、所属 Server 名称全部缓存起来，这样后续模型做工具选择时不需要反复调用服务器。

调用链路完整走一遍是这样的：

1. 用户提出需求：“帮我把这个项目的测试覆盖率跑一下，然后截图结果”。
2. 代理把需求发到大模型，模型看到可用的 MCP 工具里有git和playwright，决定先调用git_status确认仓库状态。
3. 代理把工具调用指令解析出来，路由到对应的 MCP Server，通过call_tool执行。
4. 执行结果返回，代理再附上截图和覆盖率报告文本，发给模型做下一步决策。
5. 如果模型判断需要点击某个界面元素，它会调用 GUI 模块的工具，而不是 MCP 工具。

整个链路混合了 MCP 工具和本地 GUI 工具，我统一把它们都注册在同一个路由层里。模型感知到的就是一个普通工具集合，不需要区分工具是来自 MCP 还是本地实现。

注意：不要让 MCP Server 的输出无限增长。单个工具多次调用后，累积结果很容易把上下文窗口塞满。我在代理里给 MCP 调用结果加了长度截断，默认每个工具最多返回 4000 字符，超过部分用省略标记代替。这能显著减少 token 消耗，也能避免模型在超长上下文中迷失重点。

5. 运行效果与真实用例复盘

5.1 用例一：自动录制 GUI 操作生成回放脚本

我在测试这个代理的实际能力时，设计了一个比较有意思的任务：让它观察我给某个桌面软件做的一组配置操作，然后自动生成一个 PyAutoGUI 回放脚本。

代理的处理流程令人惊讶地顺利。它先通过辅助功能接口读取窗口结构，识别出我正在操作的标签页和输入框，然后通过截图确认每一步的视觉上下文。整个过程中模型把操作拆成步骤清单，每条步骤都记录下元素定位依据和执行参数。最终生成的脚本虽然不是逐像素一样的完美复制，但核心操作逻辑完全正确。

这个过程让我意识到，所谓“AI 智能”一部分其实来自于结构化的观察。和人类操作时“凭肌肉记忆”不同，代理从第一步就开始记录每一步操作的系统状态、元素属性和触发条件，这些结构化日志极大地降低了回写脚本时的推理难度。

5.2 用例二：通过 MCP 读取 IDE 状态并辅助编码

第二个场景我实际用了很久：让代理帮忙排查前端构建报错。

传统做法是我手动复制报错信息、查文档、改配置，一套流程下来十分钟起步。现在流程压缩成：代理先使用 Playwright MCP 打开构建页面，截取报错信息；再通过 Filesystem MCP 读取vite.config.ts和相关组件源码；最后把这些上下文一并交给模型，模型直接给出修改建议。

最关键是代理不只是给建议，它还能通过 GUI 操作实际打开编辑器、定位到报错行、插入修改内容，然后重新执行构建。整条链路跑下来，我把“排查构建报错”这件事从十分钟压缩到了两分钟，而且多数情况下不需要我手动干预。

5.3 资源占用与延迟数据

为了让你对单文件方案的性能有直观感受，我贴一份实测数据。测试机器是 MacBook Pro M1 Pro 16GB，本地模型由 Ollama 提供：

体感是比人类操作慢，但胜在可以 24 小时不间断跑。如果你用云端模型，单步延迟主要取决于网络和模型响应速度，通常在 3 到 8 秒之间。资源占用方面，代理主进程常驻内存约 120MB，加上视觉模型的内存开销，整体对开发机来说不算负担。

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

6.1 GUI 元素定位失败怎么办

这是我被问得最多的问题，也是我实际调试遇到最多的场景。元素定位失败的典型表现是模型说“找不到确定按钮”或者“点击了但没反应”。

我按出现频率排一下原因：

1. 高 DPI 坐标偏移。前面提过，Windows 的 DPI 缩放会导致物理坐标和逻辑坐标不一致。排查方法是用辅助功能接口读到的坐标，和有道截图工具显示的坐标做对比，如果差了一个固定比例，基本就是 DPI 问题。
2. 窗口没有前置。很多 GUI 操作要求目标窗口处于激活状态，否则点击会落在其他窗口上。我的做法是在执行点击前，调用SetForegroundWindow窗口置顶，必要时先把最小化的窗口恢复。
3. 应用使用了自绘控件。一些游戏、设计软件不暴露标准控件，辅助功能树里就是空白。这个时候只能退回视觉模式，让模型直接看图操作。
4. 动态加载内容延迟。页面或界面还没渲染完，代理就急着找元素。解法是加入等待逻辑：在点击前检测目标元素是否出现，如果超时则重新截屏。

这里放一份问题速查表：

6.2 MCP 连接超时或工具调用失败

MCP 连接的坑比 GUI 少，但一旦踩到也够头疼一阵。

最典型的坑是stdio Server 启动目录错误。我早期用npx启动 Server 时，默认的工作目录不是用户期望的工程目录，导致 Filesystem MCP 打开的是错误路径。后来我在配置里强制追加cwd参数，问题立刻消失。

第二个坑是工具 schema 过大。某些 MCP Server 的工具描述很长，几个工具一拼下来可能几万字，直接塞进上下文既费 token 又让模型抓不住重点。我的方案是在发给模型前做一次工具裁剪，只保留名字里或描述里命中当前用户意图关键词的工具，其余暂时隐藏。

第三个坑是进程崩溃后没有自动重启。MCP Server 是独立进程，可能因为你操作了它依赖的文件而崩溃。我在 MCP 会话管理里实现了心跳检测，连续两次 ping 无响应就自动重启进程并重新初始化会话。

6.3 单文件部署在跨平台环境下的兼容性问题

单文件的便利性在跨平台上付出了一点代价。不同操作系统的 GUI API 完全不一样，我的处理方式是抽象出一个平台适配层，把 Windows 的 UIA、macOS 的 Accessibility、Linux 的 AT-SPI 分别封装成相同的接口。

实际开发中最影响体验的是截图和坐标基准的差异。macOS 上截屏权限需要在系统设置里授予终端，Linux 上需要选对显示服务器协议。我建议你在部署清单上写清楚每个平台需要额外授权的项目，省得第一次运行时白白浪费时间。

还有键盘输入的一个冷知识：在 Linux 的 Wayland 会话里，传统的 X11 键鼠模拟 API 大多失效，pyautogui会莫名静默失败。要么切换到 Xorg 会话，要么使用 Wayland 原生的虚拟输入设备方案。这一点如果不是我亲自踩过，真的很难排查。

7. 这个项目后续可以怎么扩展

写到最后，我想说点这个项目的延伸可能性。

我目前已经在做的扩展，是把 GUI 操作记录和 MCP 调用日志统一转成可复用的工作流描述文件。简单说，当代理完成一个多步骤任务后，它能把整个决策链条和数据流存储下来，下次遇到类似需求时，不再需要模型从零推理，而是直接以历史工作流为模板，只做参数替换和边界修正。实测下来，这种“经验复用”机制能把任务成功率提升四成左右，尤其适合那些固定业务流程的重活。

另一个想法是把代理包装成一个后台服务，通过 WebSocket 暴露接口，让其他系统也能调用这个 GUI 能力。设想一下 CI 流水线里跑完测试后，调用代理打开测试报告页面，自动截图、提取关键指标、发到团队群，整条链路就全自动化了。

最后分享一个个人感受：做这类 AI 代理工具，最容易低估的不是模型能力，而是工程可靠性的打磨。模型负责天马行空地想，工程层负责把想法稳稳落地。一个危险的 AI 操作犯一次错，可能就抵得上它一百次正确操作带来的收益。所以我始终建议，不管你用不用我这个项目，只要你在做类似的事，一定要在安全机制、异常恢复、人机确认这些“不酷”的模块上多花时间。它们不会出现在演示视频里，但会让你的工具真正值得被信任。