做 AI 编码代理这一年多，我一直有个执念：为什么这些"智能体"总是活在终端里？它们在命令行里写代码、跑测试、改配置头头是道，可一碰到图形界面就变成瞎子。我的日常开发里大量工作其实发生在 GUI 里——填表单、点按钮、拖文件、看图表数据。让 AI 只能操作文本终端，等于派一个高材生去上班，却只给他一部对讲机而不让他碰电脑屏幕。所以我把这个项目做出来了：一个完全免费的 AI 编码代理，能操控 GUI，支持 MCP 协议，而且整个程序打包成单个文件，拷到任何一台电脑上都能直接运行。这篇文章就是对这个项目的一次完整复盘，从为什么这么设计，到核心架构怎么拆，再到实测中踩过的坑，一次讲清楚。
项目整体用一句话概括：一个可以"看见"并操作图形界面的 AI 代理，通过解析屏幕内容、模拟鼠标键盘、调用系统辅助功能接口来干活，同时通过 MCP 协议把外部工具（浏览器、数据库、Git 仓库等）接进来做为外部能力。单文件打包让它天生便携，不需要 Python 环境，不需要 pip install，更不需要配环境变量。对正在做 AI Agent 开发的朋友、有 GUI 自动化需求但不想被商业工具绑定的团队，还有对 MCP 协议生态感兴趣的技术爱好者来说，这个项目既是参考范本，也是可以直接拿去改的底座。
1. 为什么我要做这个"能看见界面"的 AI 代理：现有 AI 编程工具的盲区
1.1 终端特权的边界：编码代理"看得见代码，看不见界面"
现在市面上的 AI 编程工具，从老牌的 Copilot 到新兴的 Claude Code、Codex CLI、OpenInterpreter，清一色以终端为中转站。它们在 Bash、PowerShell、Zsh 里面如鱼得水，ls、grep、vim、curl、cd一把梭，跑测试改代码干净利落。但终端天然有一个致命边界：它只能表达文本流，表达不了图形界面的空间关系。
比如我接到一个需求，要自动把 CRM 系统里某个客户的资料补全。这个操作在 GUI 里就是"点击编辑按钮 → 找到客户姓名输入框 → 填入数据 → 点保存"，每一步都依赖视觉定位和空间坐标。终端代理面对这种任务只能干瞪眼——它连"屏幕上有一个蓝色按钮在左上角"这种最基本的空间事实都获取不到。就算强行用xdotool这类工具去做纯坐标点击，那也只是盲人摸象，界面稍微一变，所有坐标全部失效。
这个痛点不是个例。开发团队里凡是跟旧系统打交道的，都会发现一个尴尬现实：很多企业系统没有 API，只有万年不变的 Windows 客户端和网页表单。RPA（机器人流程自动化）工具是解决这个问题的传统方案，但商业 RPALicense 贵得离谱，轻量的开源 RPA 又往往需要厚重的运行时。我更想要的是一个轻量级的、AI 驱动的、能理解界面语义而不是死记坐标的方案。
1.2 现有工具的"三座大山"：配置繁琐、依赖地狱、云端绑定
在动手写代码之前，我认认真真考察过现成的开源方案。任何一个对"AI + GUI 自动化"这个方向有基本了解的人，第一时间想到的都是 Anthropic 的 Computer Use。这个方案确实震撼——模型直接理解截图、输出点击坐标，端到端完成任务。但它的问题也很明显：依赖云端大模型 API，截图传云端处理，隐私风险高；而且它是闭源商业服务，没法满足我"免费自托管、单文件离线运行"的硬指标。
国内外的开源项目我也试了一圈。有基于 Playwright 做的浏览器自动化 Agent，比如早期版本的 browser-use，这个方向聚焦浏览器内操作，做得很出色，但对浏览器之外的桌面应用无能为力。还有些项目想统一解决桌面 GUI 自动化，从 pyautogui 级别到 Windows UI Automation 级别都有涉及，但几乎全都卡在依赖管理的泥潭里——OpenCV、PyTorch、PaddleOCR、onnxruntime 这些库随便一装就是几个 GB，用户光是配环境就得配半天，还没开始用就劝退了。
再叠加一个所有 AI Agent 项目都绕不开的问题：大模型 API Key 的配置和费用。大部分 Agent 项目把模型调用写死成某个云厂商，用户想换模型就得改源码。我觉得这种设计从一开始就走偏了——工具应该像螺丝刀一样即插即用，而不是出厂就焊死在某一家上。
1.3 我对"单文件"的执念：一个能装进 U 盘带走的代理
说白了，我对这个项目的核心诉求就三条。第一，免费且开源，任何人拿到源码都能自己审计、修改、分发，不藏着掖着。第二，单文件运行，把 Python 解释器、依赖库、模型权重、内置 MCP 工具全部打包进一个可执行文件，用户拷走就能跑。第三，模型无关，通过 OpenAI 兼容接口对接任何模型——本地跑的 Ollama、Qwen，云上的 GPT、Claude，只要能提供兼容 API 就能接进来。
很多人不理解"单文件"这个需求到底有多重要，觉得现在谁电脑上没有 Python 环境啊。但实际接触过企业内网和边缘设备的开发者应该深有感触：生产环境的 Windows 服务器经常是隔离网，别说 pip install，连外网都不通；现场工程师拿着的旧笔记本里，Python 版本五花八门，装个 tkinter 都能给你报错。单文件方案在这种场景下就是"拿过去就能用"的交付形态，不考验使用者的环境维护能力。
2. 单文件运行的实现路径：技术选型与架构分层
2.1 为什么选 Python：AI 生态最全，打包方案成熟
确定"单文件"这个硬指标之后，技术栈的选择其实没有太多悬念。Python 是我做这个项目的第一选择，原因很实在：AI Agent 生态里 Python 是事实上的标准语言，模型调用的 SDK、GUI 自动化的库、OCR 识别的工具链，用 Python 调起来最顺手。虽然 Go、Rust 在打包静态二进制方面有天然优势（编译出来就是单文件，还不依赖解释器），但它们的 AI 生态相对单薄，很多 GUI 自动化能力要靠 cgo 调用 C 库或者自己封装系统 API，开发效率就差了一大截。
Python 做单文件方案有个成熟路线：PyInstaller。这个工具能把 Python 解释器、你 import 的所有库、以及自定义资源文件全打包进一个可执行二进制。官方说法叫"one-file mode"，实际原理是先打出一个引导器（bootloader），运行时把内部压缩的依赖解压到临时目录再执行。这也是它最大的坑：启动慢——解压一段时间的等待是不可避免的，尤其依赖库体积大的时候。我的项目为了控制体积做了大量裁剪，尽量不引入重型库，但这部分细节后面会详细讲。
2.2 PyInstaller 单文件打包的真相：依赖裁剪和体积优化的平衡
单文件跑起来的背后，是与依赖体积的长期斗争。我最开始设想得很好：反正都打包了，OpenCV、PyTorch 全塞进去，视觉识别能力拉满。结果打开 PyInstaller 的产物一看，1.2 GB。这个体积任何一个正常人看了都会直接删除。
所以压体积成了打包阶段的头号任务。我的取舍原则是：能调系统 API 就不引三方库，能用轻量模型就不用重型框架。GUI 截图不引 PyQt 全家桶，直接用系统接口（Windows 用mss库截屏，这个库底层是 Win32 API，轻量到只有几千行）；图像识别的大部分场景不用深度学习模型，用 OpenCV 的模板匹配和特征点匹配先扛住；文字识别改用 PaddleOCR 的轻量版 PP-OCRv4 mobile 模型，这个模型全套只有十几 MB，远小于动不动几个 GB 的目标检测大模型。经过这一轮裁剪，最终产物从 1.2 GB 压到 180 MB，再配合 PyInstaller 的 UPX 压缩选项（UPX 是给可执行文件做壳压缩的工具），最后落在 90 MB 上下。
反复调整后我给 PyInstaller 的配置大概是这样的（示意）：
# build.spec 关键片段（PyInstaller 配置文件） a = Analysis( ['main.py'], datas=[('models/ocr_model/', 'models/ocr_model/')], # 内置 OCR 模型 hiddenimports=['mss', 'PIL', 'onnxruntime'], excludes=['tkinter', 'matplotlib', 'numpy.testing'], # 排除用不到的库 ) exe = EXE( a, name='ai-coding-agent', console=False, upx=True, icon='icon.ico' )排除列表很重要。PyInstaller 默认会把你环境里能扫描到的库全收集进去，不加excludes的话，光是把 numpy 和 opencv 连带的可选依赖一起打包就够你受的。这里面的门道得自己试过一遍才知道：依赖裁剪不只是节省磁盘，更直接决定启动速度和杀软误报率。
2.3 架构分层：Agent 核心、GUI 操作层、MCP 客户端层
整个项目我拆成了三个层次，彼此通过事件和消息解耦，这样既方便单测，也方便别人往里面加自定义能力。
最底层叫GUI 操作层，负责一切跟"看屏幕、动鼠标键盘"有关的事情。它封装了三类能力：截图（获取当前屏幕状态）、元素识别（从截图里定位按钮、输入框、文本区域）、动作执行（点击、输入、滚轮、拖拽、组合快捷键）。这个层次暴露给上层的是一个干净的接口，比如click_text('保存')、type_into_field('客户名称', '某某公司')，上层不需要关心坐标怎么算、用什么 OCR 识别出来的。
中间层是Agent 核心层，负责决策和任务编排。它维护当前任务的上下文（包括历史操作记录、屏幕观察结果、错误反馈），把大任务拆成小步骤，每一步确定"该调用哪个工具、传入什么参数"，拿到结果后判断"任务完成还是出错重试"。这一层设计了通用的工具调用框架，GUI 操作只算其中一个工具，MCP 外部工具同样挂在这个框架下。
最外层是MCP 客户端层，负责与外部 MCP Server 通信。MCP（Model Context Protocol）的全称是模型上下文协议，本质是一套定义"AI Agent 如何调用外部工具"的开放标准。我的项目内置了一个轻量 MCP 客户端，遵循 JSON-RPC 2.0 规范，支持 stdio 和 HTTP+SSE 两种传输模式。这意味着用户根据自己的需求写好 MCP Server 配置文件后，我的 Agent 就能调用那些 Server 提供的能力——比如连上浏览器控制 Server 实现网页操作、连上数据库 Server 执行 SQL 查询、连上 Git Server 管理仓库。
这三层之间的关系用一个不严谨但好懂的类比：Agent 核心层是"大脑"，负责思考和做决定；GUI 操作层是"手和眼睛"，负责看界面、点界面；MCP 客户端层是"数据接口",负责从外部系统拿数据或执行操作。大脑不直接动手，手和眼睛也不负责思考，各干各的，逻辑边界清晰，出了问题也好排查。
3. GUI 操控的核心实现：从"盲人摸象"到"看见界面"
3.1 四条技术路线的取舍：坐标脚本、模板匹配、无障碍树、视觉模型
GUI 自动化这个领域其实发展很多年了，技术路线大概有四条，每条都是不同时代的产物，各有各的适用场景。
纯坐标脚本是上古方案，就是 RPA 工具最原始的形态——先把"点击 (300, 450)"这样的动作录制成脚本，以后每次照做。优点是想都不用想，缺点是屏幕分辨率一变全废。我直接排除这条路，因为 AI Agent 的最大价值就是适应动态环境，不能活在"固定分辨率"的幻想里。
模板匹配是图像处理时代的方案，用 OpenCV 的matchTemplate在截图里找已知的小图片，比如按钮图标、Logo。这个方案在小范围内依然有效，尤其是对那些长年不换 UI 的工业软件界面，按钮长得几十年不变，模板匹配又快又准。但如果界面有按钮高亮、主题切换，或者模板图片和实际渲染有细微色差，匹配就会失败。我只用它来兜底，比如识别特定的图标按钮。
无障碍树是系统层面的方案——Windows 有 UI Automation（UIA），macOS 有 Accessibility API，Linux 有 AT-SPI。这套技术本来是给屏幕阅读器（盲人辅助工具）设计的，它能把界面控件组织成一棵有层级关系的树，每个按钮、输入框都有名字、类型、状态属性。用它来定位控件是"语义级"的，比模板匹配高一个维度——不是"找长得一样的图"，而是"找名为保存的按钮"。但它有两个短板：很多老旧的自绘控件根本不向无障碍树暴露信息；跨平台实现细节差异巨大，写兼容代码很头疼。
视觉模型就是 Computer Use 那套玩法，直接把截图丢给大模型或专门的 GUI 理解模型，让它输出目标控件坐标。这个上限最高、适应性最强，模型看到了就能理解，不需要额外配置模板或依赖系统 API。但代价是延迟和算力——截图传云端一来一回要好几秒，本地跑小型模型精度又不够。目前我只把它作为提升手段，不是主路径。
3.2 我的混合方案：系统 API 优先，OCR 文字识别做兜底
综合考虑四条路线，我最终采用了"系统 API 优先 + OCR 文字兜底 + 模板匹配补充"的混合策略。为什么这么排？核心逻辑是先打最省力的牌，能语义定位就不要靠猜。
正常执行链路是这样的：Agent 收到一个"点击登录按钮"的指令，GUI 操作层先去问系统无障碍树——Windows 上遍历 UIA 树，找 Name 属性为"登录"的按钮元素，拿到它的屏幕坐标后直接点击。整个过程几十毫秒完成，不需要截图分析，高效且精准。如果 UIA 树里找不到（可能因为目标程序是自绘界面），就降级到截图 OCR 识别：截屏 → PP-OCR 识别出"登录"文字的坐标 → 点击文字中心点。这一步通常会慢一些，但能解掉绝大多数 UIA 盲区。如果连 OCR 都识别不出来（比如按钮上没有文字只有图标），最后调用模板匹配，用预先截好的图标小样在整屏截图里搜位置。
值得强调的是，OCR 方案比很多人想象得可靠。PP-OCRv4 mobile 模型在普通办公软件界面上的识别准确率相当能打，尤其是中英文混合的按钮文字、表格文字，识别效果比前几年的开源 OCR 强了一个数量级。实测下来，90% 的 GUI 定位问题能通过 UIA 或 OCR 解决，真正需要模板匹配兜底的场景不多。
3.3 行为抽象层：把"点击保存按钮"翻译成跨平台操作序列
有了上面说的混合定位能力，还差最后一层封装——行为抽象。这一层解决的问题是：同一个语义操作，Windows 和 macOS 的实现路径完全不同，不能让上层 Agent 去关心这些差异。
比如"点击窗口右上角的关闭按钮"：Windows 上可以设置 UIA 拿关闭按钮的坐标，然后用pyautogui.click()；macOS 上 Accessibility API 的暴露方式不同，某些窗口还需要先激活再关闭。这些差异全部封装进window_ops模块里。上层只需要调用一个跨平台统一的close_window()，底层自己根据操作系统路由。
再比如"输入文字"：Windows 上模拟键盘输入中文容易翻车，剪贴板方案反而更稳——先写入系统剪贴板再模拟 Ctrl+V 粘贴，不管是中文英文都没有输入法干扰。这个坑我踩过好几次，早期直接模拟键盘敲中文，按键事件在各种输入法面前就是灾难，十次有三次内容全乱。后来统一改成剪贴板粘贴，稳定性和效率都直线上升。行为抽象层就是把这类经验固化成代码，让每个调用方都不会再踩第二遍。
4. MCP 协议接入：给编码代理装上"外接大脑"
4.1 为什么要接 MCP：模型上下文协议如何打通 Agent 与工具之间的大门
MCP（Model Context Protocol）是我这个项目里含金量最高的部分，也是我认为未来 AI Agent 基础设施的关键方向。它由 Anthropic 在 2024 年底提出，本质是一种开放标准：AI 应用（Host）可以通过该协议发现并调用外部工具（Server）提供的能力。你可以把它理解成 AI 世界的 USB-C 接口——任何设备只要遵守这个接口规范，插上就能用，不用关心对方是谁。
没有 MCP 之前，一个 AI 编码代理要接外部工具，基本上就是硬编码。代码里写死"调用某浏览器的 API 控制网页""调用某个库去查数据库"，换一个工具就得改源码、改依赖、重新打包。引入 MCP 之后，工具变成可插拔的：Agent 运行时通过配置文件发现有哪些 MCP Server 可用，询问每个 Server 提供了哪些工具，然后在需要的时候发起调用。工具的新增、替换、下线完全不碰主程序——这让单文件 Agent 同时获得了生态扩展性，看起来互斥的需求被 MCP 完美调和了。
MCP 协议本身走 JSON-RPC 2.0。核心交互分三个阶段：
- 初始化（initialize）：客户端和服务端交换协议版本、能力信息。
- 工具发现（tools/list）：客户端问服务端"你有哪些工具"，服务端返回工具列表和参数 schema。
- 工具调用（tools/call）：客户端发起调用，传参数，服务端返回结果或错误。
除工具外，MCP 还定义了资源（Resources）和提示词模板（Prompts），分别对应"暴露数据"和"复用 Prompt"的能力。我的项目目前重点实现了工具调用部分，另外两个能力在计划中。
4.2 客户端实现要点：JSON-RPC 状态机、同步与流式输出、错误重试
MCP 客户端的实现细节挺多，我挑几个最容易踩坑的讲讲。
第一个坑：JSON-RPC 状态机必须严格按规范走。initialize 请求必须在任何其他请求之前完成，否则服务端直接拒绝连接。很多新手写 MCP 客户端时图省事，跳过握手直接调工具，十有八九收到不友好的错误。还有一次，我在调某个第三方 Server 时发现它的响应格式里result和error字段同时为空，客户端代码里如果不判断这种情况，就会把空结果当成"调用成功但无返回"，反而可能误判任务状态。
第二个坑：传输方式选 stdio 还是 HTTP+SSE，体验差异巨大。stdio 模式是客户端启动一个子进程跑 MCP Server，通过标准输入输出通信。好处是本地可靠、不用管端口和鉴权，坏处是子进程生命周期由客户端管理，进程崩溃了要负责重启。HTTP+SSE 模式是服务端独立运行，客户端通过 HTTP 发起请求、通过 SSE 接收流式响应。我默认推荐 stdio——因为大多数场景下 MCP Server 和 Agent 跑在同一台机器上，少一个网络跳板就少一类故障。HTTP 模式一般留给远程服务端（比如连公司内网的统一工具网关）。
第三个坑：长时间运行的工具调用必须支持流式输出。某些 MCP Server 的工具（比如浏览器自动化或大数据查询）执行耗时很长，如果客户端只是傻等一个最终响应，用户体验就是"卡死式等待"。所以我在客户端实现上同时支持同步调用和流式订阅——流式模式下，客户端可以边收结果边向用户滚动显示进度，执行到一半还能取消。这个能力在交互式任务里特别重要，用户能通过进度判断 Agent 是在正常干活还是卡住了。
4.3 项目内置的常用 MCP Server：浏览器控制、数据库查询、Git 操作
为了让用户拿到项目就能用，我内置了几个常用 MCP Server 的配置样例。这些 Server 本身作为可选模块存在，默认不启动（保持单文件体积和启动速度），用户需要时在配置文件里打开对应开关。
我做的最多的三个类型是：浏览器控制 Server——底层用 Playwright 驱动一个浏览器实例，提供打开网页、点击元素、填表、提取内容、截图等工具。对比自研 GUI 操作层，浏览器里的元素定位更简单直接（有 DOM 结构，天然是棵语义树），所以把浏览器单独拎出来做 MCP Server 是合理的。Agent 接上它就能做网页自动化、数据采集、表单填报。
数据库查询 Server——提供执行 SQL、查看表结构、获取查询结果等工具。这个能力对"编码代理"尤其有用，写代码的人经常需要查一下数据表长什么样再写 SQL；有了这个 Server，Agent 可以直接连数据库调研，代码生成质量会高很多，而不是凭空捏造字段名。
Git 操作 Server——提供仓库状态查询、提交、分支创建、合并等工具。Agent 干完活自动提交代码、创建 PR，是我用的最频繁的场景之一。
这三个 MCP Server 的配置模式下，配置文件长这样（我用的是 JSON，因为单文件场景不想引入 YAML 解析依赖）：
{ "mcpServers": { "browser": { "command": "mcp-server-browser", "args": ["--headless"], "env": {} }, "mysql": { "command": "mcp-server-database", "args": ["--dialect", "mysql", "--dsn", "root:secret@tcp(127.0.0.1:3306)/app"] }, "git": { "command": "mcp-server-git", "args": ["--repo", "/workspace/my-project"] } } }只要用户机器上装好的 Node 或 Python 环境中存在对应 Server，Agent 启动时就会自动发现并注册这些工具。
5. 实测案例：让代理自己完成一次完整的 GUI 自动化任务
5.1 任务设定：读取 Excel 客户数据，逐条填充到旧版 CRM 系统
理论讲了一堆，还是上一个完整实测案例来验证这套架构到底行不行。我选了一个非常有代表性的任务：把 Excel 里的客户信息，逐条填进公司那套老掉牙的 Windows CRM 客户端。
为什么说这个任务有代表性？首先，这个 CRM 客户端是本世纪初的技术栈，自绘控件为主，UIA 树里基本啥也拿不到，只能靠 OCR 视觉定位。其次，它没有 API、没有数据库接口，唯一的自动化途径就是模拟人工操作 GUI。再者，数据本身在 Excel 里，需要先读出来再塞进表单，涉及跨系统数据流转。这个任务几乎同时考验了 GUI 操作层、OCR 识别、MCP 工具调用和 Agent 决策能力，是理想的压力测试。
测试环境是一台干净的 Windows 10 虚拟机，分辨率 1920×1080，无 DPI 缩放；CRM 客户端以固定窗口模式运行在桌面右下角区域。我准备了一份 20 行的 Excel 客户数据，字段包括公司名称、联系人、电话、邮箱、地址。任务是：打开 CRM 系统 → 点击"新增客户"按钮 → 依次填充五个字段 → 点击"保存" → 记录操作结果 → 自动跳到下一行重复操作。
5.2 执行链路拆解：每一步 Agent 在想什么、做什么
Agent 拿到任务描述后，先做了任务分析，拆成四个子任务：读 Excel 数据、操作 CRM 界面、填充数据并保存、循环处理剩余行。下面是其中关键几步的实际执行情况：
第一步，读 Excel。Agent 调用内置的"本地文件工具"（非 MCP，是内建能力），用 pandas 读取指定路径的工作簿，把数据转成 JSON 格式放到上下文里。这一步没有任何 GUI 操作，纯粹的数据读取，很快完成。
第二步，启动 CRM。Agent 调用 GUI 操作层的launch_app找到桌面图标并双击。这里有个小细节：现代 Windows 的"开始菜单"磁贴和应用列表经常挡住桌面图标，Agent 没有无脑双击桌面坐标，而是先调用 UIA 搜索"开始菜单"里的应用入口，找不到再回到桌面找图标。这一层智能体现在实际任务里很关键——因为桌面环境的布局每次都可能不同，死板的脚本早挂了。
第三步，点击"新增客户"。CRM 主窗口加载完成后，Agent 截屏、OCR 扫描全屏，找到"新增客户"按钮的文字坐标，然后调用点击动作。这个环节执行了两轮才成功——第一次 OCR 识别出的坐标偏到了按钮边缘的空白区，点击无效；Agent 从返回的截图对比中发现问题（屏幕没有任何变化），自动加大搜索范围，重新识别到按钮文字块的几何中心，第二次点击成功。如果是一次性的傻瓜脚本，第一次偏了就失败了，但 Agent 能从失败中自我纠错，这是它区别于传统 RPA 的核心价值。
第四步，填充表单。这是最关键的环节——定位到录入界面后，Agent 需要依次把五个字段填进去。我预先把五个字段的标签文字（"公司名称 *"、"联系人"等）作为定位依据，Agent 对表单区域截屏，OCR 搜索标签文字，根据标签的坐标推导出对应输入框的位置（通常在标签右侧或下方），然后再执行"点击输入框 → 写入数据 → 切换到下一个字段"。填充过程中第四次字段（邮箱）出了岔子：OCR 把"邮箱"识别成了"邮 箱"（中间多了一个空格），坐标推导偏差导致点到了隔壁输入框。Agent 在写入后执行了一次"读回校验"——把输入框内容重新 OCR 出来跟目标值比对，发现不匹配，重新定位输入框重填。这个自校验设计当初是为了防误点，没想到在真实测试中救了场。
5.3 实测结果和复盘：成功率、耗时、失败环节
整批 20 条数据跑完，我计时统计：总耗时约 14 分 30 秒，成功 18 条，失败 2 条。失败的 1 条是 CRM 系统弹出了一个我没预设的模态对话框（系统提示"该企业已存在"），Agent 没有为这种对话框定义处理策略，尝试了关闭按钮但没识别准确，最终卡住并主动放弃；另 1 条是 Excel 里有一行数据格式异常（电话号码混入了非法字符），Agent 校验时发现数据与表头不符，停止了该条的填充并记录到错误日志。
这个结果在我的预期范围内：20 条数据只失败 2 条，综合成功率 90%，对一个纯视觉定位的 GUI 自动化项目来说已经算不错了，而且完全免费、完全本地运行。耗时方面，单条平均 43 秒，主要瓶颈在 OCR（每条数据的表单定位要截 4~6 次屏、跑 4~6 次 OCR），以及 Agent 的自我校验机制（每填充一个字段都要截屏确认）。对比商业 RPA 动辄几十万的授权费，这个时间成本完全可接受。
复盘时最深的体会是：AI Agent 做 GUI 自动化，真正拉开差距的不是"识别得准不准"，而是"识别错了之后能不能自我纠错"。传统 RPA 脚本识别错一次就死了，Agent 可以识别错、执行错、然后靠校验机制发现问题、换个策略重新来。这个"试错-反馈-重试"的闭环，才是 AI 自动化相比传统自动化的本质优势。
6. 踩坑实录：坐标偏移、权限限制与进程通信
6.1 DPI 缩放和虚拟桌面坐标：这个坑让我的坐标点偏移了 25%
第一个让我浪费最多时间的坑，是DPI 缩放导致的坐标系统混乱。我最初的测试环境用的是 100% 缩放的默认显示设置，一切正常。后来把程序拿到一台高分屏笔记本上跑，发现 Agent 点击的位置整体偏移，按钮永远偏到右上角，当时看到那个画面真是脑壳疼。
原因其实不复杂：Windows 的屏幕坐标存在两套逻辑。物理分辨率是 1920×1080 的话，像素就是 1920×1080 个；但如果开了 125% 缩放，系统逻辑分辨率就变成了 1536×864（1920/1.25），鼠标 API 默认返回的坐标可能用的是逻辑坐标，而截屏 API 返回的像素坐标是物理坐标，两套坐标在缩放率不是 100% 时不相等，用逻辑坐标点物理像素位置自然就偏移了。
解决办法是统一坐标基准。我在 GUI 操作层里加了一个坐标转换函数，先通过系统 API 读取当前的缩放比例（Windows 上可以用ctypes调GetDpiForSystem），然后把 OCR 识别出的物理像素坐标除以缩放系数，转成逻辑坐标再送进点击动作。处理后 DPI 缩放带来的偏移问题基本绝迹。这个坑对于只做网页自动化的人是碰不到的，因为浏览器内部坐标已经统一过了；但做桌面 GUI 自动化，坐标基准一致性是地基，不打好后面全是歪楼。
6.2 macOS 辅助功能权限：一次授权引发的问题比想象中多
跨平台支持是我一开始就立下的目标，但实际推进到 macOS 时遇到的问题让我意识到：跨平台的复杂度主要不在代码逻辑，而在操作系统权限模型。
macOS 的辅助功能权限（Accessibility Permission）和屏幕录制权限（Screen Recording Permission）是两个独立的 TCC 权限。如果只授权了辅助功能没授权屏幕录制，UIA 树能读（能拿到控件列表），但截屏输出全黑——OCR 和视觉定位全部失灵。反过来只授权了屏幕录制，截图没问题但拿不到控件属性，等于有眼睛没手。
更麻烦的是，macOS 的 TCC 权限缓存十分顽固。我用 PyInstaller 打包出的可执行文件在~/Applications/目录里，授权时需要精确定位到那个二进制文件；如果后来改了路径（比如拷到别的文件夹），之前的授权自动失效，又要重新加。我踩过的坑是：在开发机上用python main.py跑的时候一切正常，一打包成独立文件就报权限不足——因为系统里授权的是python进程，不是打包后的二进制进程，权限不通用。
这类问题很难通过代码优雅解决，只能在文档里反复强调：macOS 用户安装后的第一件事，就是把程序加入"系统设置 → 隐私与安全性 → 辅助功能 / 屏幕录制"的白名单，并且在修改安装路径后重新授权。我甚至加了一个自检工具，启动时主动检测两个权限的状态，如果没有授权就弹窗提示并给出操作指引，省得用户面对莫名其妙的"黑屏"一头雾水。
6.3 Agent 上下文丢失与断点恢复：长任务跑一半全功尽弃怎么办
最后一个让我印象深刻的坑，是长任务执行过程中的上下文丢失问题。在测试一个 50+ 步骤的下载表单任务时，程序因为一次 OCR 异常导致 Agent 决策分支产生死循环，我在调试模式下强行终止了进程。重启程序后发现：Agent 已经完全不记得之前执行到哪一步、哪些数据填过了——整个任务从头开始执行，结果重复填充了之前已经写好的数据，造成表单混乱。
这个问题本质上是"Agent 无状态"的通病。大模型本身不保存对话历史，我的 Agent 把任务上下文放在内存里，进程一杀死就全丢了。为了解决这个问题，我做了一个轻量级的检查点机制：每完成一个关键步骤（比如"填充完第三个字段"、"点完保存按钮"），就把当前状态序列化成一个 JSON 快照，包括已完成步骤列表、当前表单数据、下一步待执行指令，写入本地磁盘。进程重启后，Agent 会先检测是否有未完成的检查点，有就提示用户"发现未完成任务，是否继续"；选择继续的话，就从断点恢复执行，跳过已经完成的步骤。
这个机制的难点是如何精确定义"已完成"的语义。只存步骤编号没用，因为同一行数据里"填充公司名称"和"填充联系人"是两个独立动作，但如果第 10 行的字段都填完了才开始第 11 行，断点就应该基于"行"和"字段"两个维度记录。我最后设计了双维度的检查点结构：外层是"当前处理到第几行"，内层是"当前行的哪几个字段已填充"。恢复时可以精确定位到"第 11 行的联系人字段"，而不是粗暴地从第 11 行开头的公司名重新填起。这个设计在实际恢复测试中效果很好，既节省了时间，也避免了重复写入带来的数据脏问题。
7. 后续规划：这个项目的真正价值在于成为 AI Agent 基础设施的参考
7.1 MCP Server 生态将迎来爆发：每个常用应用都会有自己的 MCP 接口
做这个项目让我更坚定一个判断：MCP 协议正在成为 AI Agent 时代的事实标准，而围绕它的 Server 生态会迎来一波大爆发。2025 年以来，主流 SaaS 和开发工具厂商（包括 Google、GitHub、JetBrains 等）都在陆续提供官方 MCP Server，开源社区的工具数量增长更快。MCP 之于 Agent，就像 SQL 之于数据库——它把"能力的发现和使用"标准化了，任何 Agent 只要实现一套客户端协议，就能访问所有已经接入 MCP 的工具，不需要为每个工具单独写 SDK。
我的项目在这一点上的定位很明确：做一个快速可用的 MCP 客户端参考实现，同时用 GUI 自动化能力补上桌面端 MCP 的盲区。市面上大多数 MCP 生态聚焦在数据获取和云端工具上，很少有人把"操作桌面 GUI"作为 MCP 能力暴露出来。我后续计划把 GUI 操作层也包装成一个 MCP Server——这样一来，任何支持 MCP 的 AI 编码工具（包括 Claude Desktop 这类商业产品）都能通过我的 Server 间接获得桌面 GUI 操控能力。这个反向思路我觉得挺有意思：别人把 MCP 当作 Agent 的外部工具来源，我把 MCP 当作让我的 Agent 能力被别人调用的出口。
7.2 本地优先与隐私：为什么所有处理都留在本机
从项目设计之初，"本地优先"就是一个不可妥协的原则。GUI 截图里往往包含大量敏感信息——客户名单、财务报表、内部系统界面，这些东西如果默认上传到云端大模型处理，对很多企业就是严重的合规风险。所以我的项目架构在设计上尽量把重计算放在本地：OCR 模型、模板匹配、无障碍树解析全部在本地完成，只有最后 Agent 的"决策思考"才调用大模型 API，而且模型调用支持用户自选端点。
如果用户接的是本地模型（比如 Ollama、LM Studio 部署的 Qwen、DeepSeek），整个链路就是完全离线闭环——截图不过本机，推理不过本机，数据不出局域网。对于很多连公网都不接的生产网环境，这是唯一现实可行的方案。虽然本地小模型在复杂决策和代码生成上的能力比云端顶级模型差一些，但在"读界面、点按钮、填表单"这类结构化任务里，本地小模型的准确率已经足够，加上我前面说的自校验纠错机制，最终效果不输云端方案多少。
7.3 给想做类似开源工具的朋友：三个经验，说完就收
项目做到这个阶段，回头看看最想分享的三条经验，送给打算做同类工具的人。
第一条，先立好"不做什么"，再定"做什么"。我一开始什么都想要——无限的模型支持、完美的跨平台、全功能浏览器自动化，结果被这些目标拖得分身乏术。后来砍掉了很多"锦上添花"的想法，只保留"GUI 操控 + MCP 接入 + 单文件"三个核心，才真正把项目推到了可用状态。做工具型开源项目，克制比激进更重要。
第二条，打包和性能优化要早点动手，不要等所有功能写完才考虑。我最初低估了 PyInstaller 打包的复杂度，等到基本功能写完才发现体积爆表、启动奇慢、杀软误报频发，返工成本极高。这些都是架构级问题，不是配置级问题，晚处理只会更痛。
第三条，GUI Agent 的灵魂是反馈闭环，不是单步执行。传统 RPA 是"按脚本走一步看一步"，Agent 必须做到"操作了 → 验证结果 → 不对就换方案"。这个闭环的价值在长期任务里会被无限放大——因为界面总会变、OCR 总会出错、按钮总会失灵，能不能从失败中自愈，才是 Agent 和脚本的分水岭。我的项目里所有看起来繁琐的"执行后截屏验证"逻辑，都是围绕这一条打磨的。
做开源工具的这一年，最大的收获反而不是代码本身，而是通过这个项目验证了一个想法：终端不是 AI 编码代理的终点，GUI 和 MCP 协议补上的是 Agent 的"眼睛"和"触手"。把所有能力打包进一个单文件，让那些没有 Python 环境、没有最新工具链、甚至没有外网的普通用户也能跑起一个能看懂屏幕、操作软件、连接外部数据的 AI 助手——这件事本身就值得做下去。如果你也在研究 AI Agent 的落地形态，希望这篇复盘能给你一些参考，哪怕是踩坑部分能帮你少浪费两周时间，这个项目就有它的价值了。
