这两年，AI编码代理（Coding Agent）这个概念已经快被炒烂了，从GitHub Copilot的自动补全，到能自己改代码跑测试的Claude Code、Cursor Background Agent，每一步都在把"写代码"的门槛往下拉。但我始终有个很直接的痛点：绝大多数Agent都活在终端和IDE里，碰不到桌面上的GUI程序。你让它"把Windows计算器打开，算一下578乘以362，把结果贴进记事本"，它多半就愣住了。所以我干脆自己写了一个免费的AI编码代理，核心卖点就三样：能操控GUI、支持MCP（Model Context Protocol）、单文件运行。这个项目现在已经能在Windows和macOS上稳定跑起来，代码也开源了，这篇文章我把设计思路、原理拆解和实操过程全部分享出来，包括我踩过的那些坑。
我先把结论放前面：这个代理不是要跟Claude Code正面硬刚，而是补它们覆盖不到的角落——给那些不想装Node.js、不想配一堆环境变量、只想双击一个文件就能用的普通用户和测试人员，提供一个能"看见屏幕、点击界面、调用工具"的AI助手。整个过程确实不需要多复杂的部署：一个可执行文件，一个配置文件，你把API Key填进去，它就能干活。下面我从头到尾讲清楚。
1. 项目概述与设计思路
1.1 为什么在"什么都AI化"的今天，我还要自己造一个轮子
先聊聊背景。当你打开任何一个流行的AI编程工具，它们的能力边界通常是这样划分的：命令行里跑命令、读写项目文件、调用LSP，OK，很强。但一旦涉及桌面GUI，比如操作某个旧系统的配置面板、填写一个没有API的老软件表单、远程点一下某个工业软件里的按钮，这些工具就集体失语了。它们的架构里根本没有"看屏幕"这一层。
我周围有不少测试工程师和运维朋友，他们面对的根本不是漂亮的API服务，而是那些必须靠鼠标点来点去的桌面程序。他们也想让AI帮忙自动化操作，但现有方案要么是写一堆UFT脚本，要么是录宏，又慢又脆。**有人可能说，那就用Computer Use API呗。**问题在于，那玩意收费不低，而且它确实能看图操作，但不能跟你的本地工具链深度耦合，换句话说，它只会"看"和"点"，不会"调用Git命令"、"读写数据库"、"解析JSON配置"这套本地能力。
MCP恰好补上了这半边天。MCP相当于给AI装了一个标准化的"USB接口"，通过这个协议，AI可以自由调用你本地的各种工具服务器——文件读写、数据库查询、浏览器控制、CI构建，都可以通过MCP暴露给AI。把GUI操控和MCP这两件事做到同一个代理里，是我判断真正有价值的技术组合，既能看见屏幕，又能触达所有工程化工具链，这就是这个项目的出发点。
再说单文件运行。很多人低估了"一个文件"的价值。你去搜一下开源社区，一半以上的工具卡死在环境配置这一步。要装Python、要配C++运行时、要处理依赖冲突，普通人直接劝退。我认识的不少QA同学电脑上干干净浄，装个东西要找IT审批。一个绿色单文件，拷到U盘里就能跑，这在企业内网和跨部门协作场景里就是杀手锏。
1.2 核心设计：一个代理的大脑、眼睛和手
整个项目拆开来看，其实就三个模块：
- 大脑：一个LLM对话循环，负责理解用户指令、拆解步骤、做出决策。它其实是无状态的，不断接收任务上下文和工具返回值，然后决定下一步动作。
- 眼睛和手：GUI操控模块，负责截图、读取控件树、模拟鼠标键盘事件。我前后试了三套技术路线（后面详细展开），最终选择了一条兼顾跨平台和精度的混合方案。
- 神经网络：MCP客户端模块，负责感知本地已注册的工具服务器，通过JSON-RPC调用它们的能力。
这三个模块被一个主循环串起来：AI拿到指令 -> 规划 -> 调用工具或点击界面 -> 观察结果 -> 重新规划 -> 直到任务完成。这个过程听起来不复杂，但真正做好很难。难在什么时候该点按钮什么时候该写代码的决策，难在截图识别误差的纠正，难在MCP工具返回大段输出时的上下文裁剪。这些细节在后面的章节里逐一展开。
1.3 技术栈与工程形态
为了让"单文件运行"成立，我在编程语言选择和构建策略上做了不少权衡。第一版用Python写，开发效率确实高，GUI操控库选pyautogui + accessibility解析，MCP客户端用官方的Python SDK。但天然缺陷也暴露了：PyInstaller打包出来的"单文件"，首次启动要解压到临时目录，杀毒软件容易误报，而且文件体积直接往100MB以上飙。
所以我后来把核心调度层重写了一遍。现在的版本：调度和协议层用Rust重写，GUI操控保留一个系统级原生模块，MCP SDK通过FFI接入。Rust编译出来的单文件，体积在20MB左右，启动快，不需要解释器，依赖全部静态编译进去。代价是开发慢，但换来的是"拷贝即用"的干净体验。如果你想看具体实现，项目的构建脚本把两条生态的打包流程都做了，我这篇不展开Rust内部细节，重点讲行为逻辑和实际用法。
2. 核心原理解剖：GUI操控和MCP到底是怎么工作的
2.1 GUI操控的三种技术路线，我全部试了一遍
这个项目里最核心也最容易翻车的部分，就是让AI操控GUI。我在做之前，把市面上可行的路线摸了一遍，每种都有明显的取舍。
路线一：计算机视觉（截图+多模态识别）
这个思路最简单粗暴：定时截取屏幕，把截图发给多模态模型（比如GPT-4o、Claude的视觉能力），让模型判断下一步该点哪里，然后模拟点击。好处是跨平台，只要屏幕显示出来就能操作，不需要任何系统权限之外的接口。坏处也很明显：每个动作要多一次API调用，又贵又慢。而且模型对像素坐标的判断经常有偏差，尤其是高分屏、缩放比例不是100%的时候，屏幕上UI元素的实际定位会和模型猜测的坐标错位好几像素。我实测下来，让模型点一个宽高只有40像素的小按钮，成功率大概就六成。
路线二：辅助功能树（Accessibility Tree）
Windows上叫UI Automation（UIA），macOS上叫Accessibility API，Linux是AT-SPI。这套体系的思路是：系统为所有界面元素暴露一个"控件树"，上面写着这块是什么（按钮/输入框/列表项）、在什么位置、当前是什么状态。AI只要读取这棵树，就能精确知道界面上有什么，根本不需要"看图猜坐标"。
这条路线的准确率是最高的，而且不需要烧OCR的钱。问题是：不是所有程序都实现了完整的辅助功能接口。有些老旧软件、某些自绘界面的程序、游戏引擎渲染的窗口，辅助功能树要么残缺，要么干脆是空的，UI元素全都识别不出来。我在测试某工业控制软件时，整棵树拿下来只有两个节点，一个叫"Window"，一个叫"Panel"，等于白搭。
路线三：纯坐标宏回放
这就是多年前按键精灵的思路，预先录制一串鼠标坐标动作然后回放。简单到极致，也脆弱到极致，窗口位置一挪，分辨率一变，脚本立刻失效。这种方案连"感知"都谈不上，AI无法知道当前屏幕是什么状态。
最终我的方案是混合模式，优先辅助功能树，视觉作为兜底。默认走Accessibility解析界面元素，把结构化信息交给模型；遇到辅助功能树空白的情况，自动降级到截图+视觉推理。同时引入一个"坐标校正器"：视觉模型给出点击目标后，在周边像素做一次模板匹配或颜色锚点校验，把偏差拉回来。这套混合方案现在跑下来，对主流桌面应用的成功率已经能到八成五左右，比单一方案稳定得多。
2.2 MCP协议：AI世界的统一"USB接口"
MCP（Model Context Protocol）这个概念，简单说就是给AI模型提供一套标准化的工具调用协议。以前每个AI应用要连接一个数据源或工具，都得单独写集成代码，数据库一家、GitHub一家、Slack一家，生态隔裂得不行。MCP把这件事标准化了。
它的架构涉及三个角色：
- Host：宿主程序，也就是我这个代理。
- Client：负责跟Server建立连接、发送请求、接收结果。
- Server：一个独立的工具提供方，暴露三类核心能力——Tools（可执行函数）、Resources（可读数据）、Prompts（提示词模板）。
整个通信基于JSON-RPC 2.0，最常见的有两种传输方式：一个是stdio（Agent以子进程方式拉起Server，通过标准输入输出通信），另一个是HTTP/SSE（远程服务的方式）。stdio模式非常契合我这个单文件工具的场景：主程序启动时根据配置文件拉起若干个本地MCP Server进程，用管道保持双向通信，子进程退出或崩溃都会被主程序捕获并重启。
对使用者来说，MCP价值在于：它让AI从"只能聊天/只能改代码"升级为"能用你所有本地工具"。举个例子，我接入了一个文件系统MCP Server，AI就能直接读取任意路径下的目录结构、文本内容；接入Git Server，AI就能直接跑git status、git diff、git commit，不需要我在外面提供一遍shell能力。生态里还有数据库MCP、浏览器MCP、二维码生成MCP等等，前阵子我还看到有人给Cheat Engine、IDA这类逆向工具写了MCP插件——MCP这个生态发展速度，说实话超过了我当初的预期。
2.3 单文件运行的技术内幕
"单文件"这三个字，看起来简单，真正做到不掺水需要解决几个问题。首先，运行时依赖必须静态链接。我用Rust做调度层，所有工具库的依赖都在编译期定死，一个二进制文件里包含了全部代码。其次，外部工具尽量不在运行时解压。市面上一些单文件方案其实是自解压包，启动时把所有模块释放到Temp目录再运行，本质还是多文件。我这版的思路是：能编译进二进制的就编译进去，不能编进去的资源（比如图标、证书文件）用嵌入式资源表带上，运行时直接在内存里读取，不落盘。只有MCP Server这种必须独立进程的工具，才通过配置文件指示路径，由主程序拉起。
这么做的代价同样明显：编译产物对不同系统版本敏感，Windows上不能用老编译器硬扛新系统，Linux下即使单文件也要考虑系统库版本。GitHub Actions上我配了三套构建流程，分别对应Windows x64、macOS arm64、Linux x64，确保每个平台都有正式二进制。转发给别人用的时候，基本就是下载、赋予可执行权限、填写配置三步到位。
3. 实操：从下载配置到让它真正干活
3.1 五分钟快速跑起来
第一步永远是下载。项目Release页面会同时放出三个平台的压缩包，Windows用户拿zip版，macOS用户拿tar.gz，Linux同理。解压后你会看到两个文件：
agent-cli # 主程序（单文件） config.example.json # 配置文件模板没有一堆依赖，没有pip install，没有npm install，这就是我想要的形态。首次运行前，把config.example.json复制成config.json，在里面填入基础信息。
注意：Windows上如果直接双击运行会闪退，因为它是命令行程序。正确的打开方式是：在当前目录打开PowerShell或CMD，输入
.\agent-cli.exe --config config.json。macOS用户如果提示无法打开，去"系统设置-隐私与安全性-安全性"里点"仍要打开"，或者执行chmod +x agent-cli。
3.2 配置模型连接与代理参数
配置文件是整个工具的命门，我把常用参数列一下：
{ "model_provider": "openai", "model_name": "gpt-4o", "api_key_env": "AI_AGENT_API_KEY", "base_url": "https://api.openai.com/v1", "max_turns": 40, "screenshot_interval_ms": 1000, "gui_preference": "accessibility_first", "mcp_servers": [ { "name": "filesystem", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"] }, { "name": "git", "command": "npx", "args": ["-y", "mcp-server-git", "./repo"] } ] }把api_key_env指向你当前环境变量里已有的Key名称，这是个安全小习惯：API Key永远不要直接写进配置文件，避免文件被别人看到时的泄露风险。max_turns控制AI最多自主执行的步骤数，防止它无限循环烧Token。screenshot_interval_ms是视觉模式下相邻两次截图的间隔，太短会增加延迟和成本，太长又会显得反应迟钝，每秒一次是我试下来最均衡的数值。gui_preference前面说了，默认优先辅助功能树。
3.3 接入第一个MCP Server
MCP的接入方式在配置里就是声明一个server条目。最常见的入门server是文件系统的官方示例，它需要Node.js环境，因为底层是npx拉包运行。在配置文件里加好之后，启动代理时它会自动检测并拉起这些子进程。
验证MCP是否连接成功，有个好用的小技巧：在交互界面直接问一句"你现在能调用哪些工具"，代理会把所有可用工具列表拉出来展示。正常情况你会看到每个MCP Server暴露的工具名和描述，比如文件系统server会有read_file、write_file、list_directory、create_directory这些方法，Git server会有git_status、git_commit、git_branch等。如果列表是空的，基本就是连接失败，排查方法我在第4节详细讲。
3.4 实战一：让代理操作GUI完成文件整理
空谈原理没用，我们直接开一把真实的。假设任务要求是：打开Windows的文件资源管理器，在桌面新建一个叫"工作备份"的文件夹，然后把桌面上所有jpg图片移动进去，完成后打开该文件夹确认结果。
操作过程大致如下：
我向代理下达指令："打开文件资源管理器，新建文件夹工作备份，把桌面上所有jpg图片移动进去，然后打开文件夹确认。"
代理接收到指令后，调度模块先做一次规划，大致会产生这么几步：
- 用系统API打开资源管理器（这一步其实可以直接调系统命令
explorer.exe，不需要GUI操作）。 - 等待窗口渲染完成，调用辅助功能树接口读取窗口内的控件，找到桌面路径地址栏，或者通过快捷键
Win+D回到桌面。 - 通过键盘事件模拟
Ctrl+Shift+N新建文件夹，重命名为"工作备份"。 - 借助文件系统MCP，直接列出桌面上扩展名为jpg的所有文件路径，这一步其实已经不需要GUI操作，MCP就能完成。
- 把列出的文件路径传给系统
move命令，批量移动。 - 最后打开目标文件夹，截图让AI确认所有jpg已经就位。
你会发现很有意思的一点：这个代理天然知道哪些步骤应该用GUI点，哪些步骤应该用命令或MCP。文件移动这种确定性操作交给命令效率更高，而新建文件夹、窗口跳转这些GUI相关步骤则用模拟操作更顺。混合调度让整个流程又快又稳。整个任务跑完大约用了90秒，其中绝大部分时间花在窗口渲染同步和截图确认上，实际API调用次数只有8次。
3.5 实战二：通过MCP操作Git仓库
第二个场景完全绕开GUI，但它的实用性更狠：我把项目仓库路径暴露给git MCP server后，直接对代理说："把当前分支状态梳理一下，看看工作区有没有未提交的改动，有的话帮我提交，Commit message根据改动内容总结，然后推送到远程。"
代理在处理时，会调用git_status查看状态，git_diff查看具体改了哪些内容，然后基于diff内容生成一条Commit message，通过git_commit提交，git_push推送。全程我没有手动敲过一条Git命令。这就是MCP价值的直观体现：没有MCP之前，虽然很多Agent也能执行shell命令，但那是通过"跑命令"这种黑盒方式，现在改为结构化工具调用，安全性、可观察性和可追溯性都高了一个量级。而且MCP Server的封装让AI能理解每个参数的含义，比如git_commit需要message参数，它就知道该生成什么格式的消息。
4. 常见问题速查与避坑记录
4.1 MCP连接失败，八成卡在这三个位置
我接触过的用户反馈里，MCP相关的报错占了快一半。根据我的排查经验，按照顺序去检查这几个环节：
第一，MCP Server本身启动不了。官方文档没写清楚的前提是：某些server依赖Node.js、Python或者其他运行时，如果你电脑上根本没有对应环境，npx或python一条命令都执行不了，代理自然连不上。解决方法是服务端改用已编译好的二进制版本，或者提前装好运行时。
第二，stdio的通信超时。有些MCP Server第一次启动时要拉取依赖包，这个过程可能要几十秒。我的代理默认连接超时8秒，第一次连接很可能直接超时。你可以在配置里把mcp_timeout_ms调大到60000，让首连有足够时间。启动一次之后，后续的依赖缓存让连接速度就快多了。
第三，路径参数错误。配置里的args如果是文件路径，记得用绝对路径，避免子进程的工作目录跟主程序不一致。我见过太多人在这里把相对路径当成绝对路径填，server启动后根本找不到目标目录，连个有效响应都返回不了。
4.2 GUI识别不准：从三个方向去调
当你发现代理老点错按钮、识别不了界面元素，首先排查询的是屏幕缩放比例。Windows的DPI缩放如果设置成125%、150%，辅助功能树拿到的坐标和实际位图坐标会有一个缩放系数问题，旧版在缩放比例非100%的时候，经常精确点击失败。我后来在坐标转换时加入了缩放因子补偿，但如果你用的是外接显示器混合配置，仍然有概率出现偏移。手边的解决办法：临时把显示缩放调成100%，跑任务，基本稳了。
其次是窗口不是前台焦点。模拟点击事件发送到后台窗口，很多程序不愿意处理，导致点击无效。我的实现里有一个bring_to_front的逻辑，在每次GUI操作前会把目标窗口强制弹到前台并激活。如果你实现自己的代理，注意很多语言对窗口激活有权限限制，Windows下需要先附加线程输入，否则SetForegroundWindow失灵。
最后是多显示器负坐标。如果副屏在主屏左边，副屏上的控件会得到负的X坐标，不少图像库默认不支持负坐标。我自己在截图模块里补了offset偏移逻辑，保证全屏拼接图上的坐标与物理屏幕一致。这里强烈建议：做GUI自动化的朋友，多屏环境下统一用虚拟屏幕坐标系。
4.3 单文件程序在不同平台的启动差异
单文件程序看着清爽，实际分发时还是有些平台特有的怪问题。Windows上最常见的是SmartScreen拦截，毕竟是未签名的exe，系统会弹蓝窗警告。选择"仍要运行"就能用，但要让团队内其他人放心使用，建议去申请一个代码签名证书，或者至少发布时附带SHA256校验值，让他们比对后确认文件完整。
macOS上更麻烦一点，未签名程序不仅要被Gatekeeper拦，Apple Silicon机器上还必须处理quarantine属性。一条命令解决：
xattr -d com.apple.quarantine /path/to/agent-cliLinux上则主要看libc版本，用旧发行版编译的程序在新系统上通常没问题，反过来新系统编译的二进制在老旧CentOS上很可能缺GLIBC符号。规避办法是尽量在较老的基础镜像里交叉编译，或者直接用musl构建纯静态二进制。
4.4 别把代理的权限放得太大
这是我写这篇文章最想强调的一件事。一个能操控GUI、能调用MCP工具的AI代理，本质上等于给LLM发了一把"万能钥匙"。如果你在配置里外挂了文件系统MCP且路径指向根目录，又挂了数据库MCP，那AI理论上可以读走你机器上的所有文件、改成所有数据。权限上我默认做了两层限制：一是MCP Server的访问路径由用户在白名单里声明，比如文件系统server我通常会限定在工作区目录；二是代理自身的system_prompt里明确写了"未获用户明确授权，不得执行删除、覆盖、安装软件等高危操作"。但再强的约束也挡不住模型被prompt injection诱导，所以真正使用的时候，请像对待一个有管理员权限的新员工一样对待你的代理：不给多余权限，不在重要机器上做未经验证的实验。
5. 这个项目的扩展空间与后续打算
5.1 从"编码代理"到"数字员工"
说实话，把它定义为"编码代理"多少低估了这份能力组合。当代理既能看屏幕、点击GUI，又能通过MCP操作文件、走数据库、调外部API，它的使用场景就远不止写代码了。我身边已经有朋友拿它在做软件UI自动化测试：传统测试脚本碰到元素定位变更就崩，但视觉模式让AI能自适应地找到按钮；还有人用它在采集老旧垂直管理系统的数据，填表单、点击翻页、把数据通过数据库MCP写走。这些都是传统RPA工具动辄几十万授权费的场景，现在一个免费的单文件就能处理基础需求。
5.2 把MCP当成扩展插件系统来玩
我强烈建议所有使用者把MCP理解成"Agent的App Store"。你不需要等主程序更新功能，只要找到一个好用的MCP Server，在配置里加一行就能获得对应能力。比如加入一个浏览器控制MCP，代理就能打开网页、读取DOM元素、点击提交，这等于把Web自动化的能力也内置了。再比如引入二维码生成MCP，在输出设备上展示信息流的时候就很方便。社区里甚至有人做了将蓝湖设计稿导出的MCP、把Figma标注转成代码的MCP，这类工具对前端开发者的提效是即时可见的。
我自己后续在项目里计划加三块东西：一是图形化配置界面，让不熟悉JSON的用户可以点点鼠标完成MCP配置；二是任务回放与断点续跑，GUI操作失败时不是从头开始，而是从上一步重试；三是插件市场，直接从代理里浏览和安装经过验证的MCP Server，降低搜索成本。
5.3 一件让我意外的事
写到这里想分享一个上线之后的意外收获：有一个做运维的朋友拿它去处理一个老旧工业系统，那套系统没有API、只能人工点击，以前每次升级都要运维手动点几百次按钮。现在他用这个代理接上截图和辅助功能树，配了一段简单的操作提示，让AI循环执行"点确认按钮-等待进度条消失-点下一步"，一次升级流程从手工2小时缩短到20分钟。他跟我说，这才叫"数字员工"的时候，我突然觉得当初选择把GUI操控和MCP组合在一起，走对了。
这个项目目前仍然是我一个人在维护，功能迭代全凭社区反馈。我个人的体会是：AI代理的下一个战场，一定不是聊天窗口，而是真正接管桌面上的操作。我能做的只是抛一块砖——单文件、免费、可扩展，剩下能长出多高的墙，得看社区里有多少人愿意一起往里砌砖了。如果你也想试试，下载一个跑通第一个GUI任务，你会回来感谢我的。
