1. 为什么我要自己造一个 AI 编码代理市面上能用的 AI 编码工具我基本都试过一遍。云端方案响应快、模型强但代码得往外传公司内网的私有仓库根本连不上本地方案呢要么依赖一大堆 Python 环境装个依赖能折腾一下午要么只能读写文件、跑跑命令碰到需要点界面、拖窗口、填表单的活儿就彻底歇菜。我手上有一堆重复性的脏活批量改配置、在图形化工具里点来点去导数据、把设计稿里的参数同步到代码里这些事纯靠命令行根本搞不定。所以我就想做一个自己的AI 编码代理核心诉求就三条第一能真正操控GUI不只是敲命令而是能看见屏幕、移动鼠标、点击输入第二支持MCPModel Context Protocol模型上下文协议这样我能把各种外部工具、数据库、内部系统都挂上来让代理按需调用第三单文件运行一个可执行文件丢过去就能跑不装环境、不配依赖发给同事直接双击。这篇文章就把我整个设计和实现过程拆开讲包括架构选型、GUI 操控怎么做、MCP 怎么接、单文件怎么打包以及我踩过的那些坑。如果你也在做类似的东西或者想给自己的工具链加一个能动手的代理这篇应该能帮你省不少时间。适合有一定编程基础、对 AI 代理和自动化感兴趣的读者小白也能看懂大思路动手部分照着抄就行。2. 整体架构设计与技术选型思路2.1 核心需求拆解代理到底要会做什么先把需求翻译成技术语言。一个能操控 GUI 和 MCP 的编码代理本质上要具备四种能力感知看到屏幕内容、读到文件、决策大模型推理下一步做什么、执行操作鼠标键盘、调用工具、读写文件、记忆保存上下文和历史操作。这四块缺一不可而且必须形成一个闭环——感知到的东西喂给模型模型输出动作动作改变环境环境再被感知。我见过很多玩具项目只做了决策执行结果代理像个瞎子点错地方还不知道。也有的只做感知决策输出一堆建议但落不了地。真正能用的代理闭环必须完整而且每一环都要足够稳。2.2 为什么选单文件部署成本才是第一生产力技术选型上我第一个定死的就是单文件运行。原因很现实我试过用 Python 写依赖装完 2 个 G换台机器就报错同事根本不愿意用。后来换成 Go编译出来一个二进制文件Windows 上 20 多兆Linux 上十几兆拷过去就能跑这才叫工具。单文件带来的好处不只是方便。它逼着你把依赖收敛不能随便引库逼着你把资源内嵌图片、配置、提示词模板全打进二进制也逼着你处理好跨平台因为用户不会管你什么系统。这些约束反过来让代码更干净。代价是编译体积大一点、调试麻烦一点但跟部署的爽快比起来完全值得。2.3 语言与运行时选择Go 还是 RustGo 和 Rust 我都认真评估过。Rust 性能更好、内存更安全但 GUI 自动化和跨平台打包的生态相对分散写起来心智负担重。Go 的优势在于标准库自带 HTTP、JSON、文件操作跨平台编译一条命令搞定GUI 自动化有成熟的库可用而且编译速度快改一行几秒就能出结果。最后我选 Go核心理由是开发效率。这个项目迭代频繁提示词、工具定义、协议解析天天改Go 的编译速度和简洁语法让我能快速试错。性能方面代理的瓶颈在大模型推理和网络 IO不在本地代码Go 完全够用。2.4 模块划分感知、决策、执行、记忆四层架构上我分成四层每层职责清晰感知层截屏、OCR 识别界面文字、读取当前活动窗口信息、读取文件系统。这一层输出结构化的世界状态。决策层把世界状态、历史对话、可用工具列表打包成提示词发给大模型解析返回的动作指令。执行层根据动作指令操作鼠标键盘、调用 MCP 工具、读写文件、执行命令。记忆层维护对话历史、操作日志、任务状态支持中断恢复。四层之间用统一的消息结构通信每层都可以单独替换。比如决策层今天用这个模型明天想换另一个只要接口不变其他层不用动。这种解耦在后期调试时救了我很多次。3. GUI 操控的核心实现细节3.1 屏幕感知截屏与元素定位的取舍GUI 操控最难的是看见和找准。截屏好办各平台都有原生 APIGo 里也有封装好的库。难的是从一张图里找到那个按钮在哪。我试过三条路线。第一条是纯视觉把截图直接丢给多模态模型让它输出坐标。优点是通用什么界面都能认缺点是慢一次推理好几秒而且坐标经常偏几十像素点不中。第二条是辅助功能树Accessibility API直接读控件的层级和位置精准且快但很多自绘界面、游戏、远程桌面根本读不到。第三条是 OCR 加模板匹配对固定界面效果好换个皮肤就废。最后我用的是混合方案优先读辅助功能树读不到就 OCR 识别文字区域再不行才走纯视觉。这样大部分场景又快又准极端情况也有兜底。实测下来混合方案的成功率比单一路线高出一大截。3.2 鼠标键盘模拟跨平台的那些坑模拟输入看起来简单实际坑很多。Windows 上要用 SendInputmacOS 上要用 CGEventLinux 上 X11 和 Wayland 完全是两套东西。我封装了一层统一接口内部按平台分发。几个必须注意的点坐标缩放。高分屏上逻辑坐标和物理坐标不一致直接按截图像素点会偏。我的做法是统一转成物理坐标再操作。操作间隔。连续点击太快目标程序可能来不及响应我在每个动作之间加了 50 到 100 毫秒的随机延迟模拟真人节奏稳定性明显提升。焦点问题。点击前要确保目标窗口在前台否则点了个寂寞。我加了一步激活窗口并等待的逻辑。提示模拟输入时一定要加随机延迟固定间隔容易被某些程序的风控识别也不符合真实操作节奏。3.3 视觉反馈闭环点完怎么知道成功了点完按钮不代表任务完成得验证结果。我的做法是每次操作后重新截屏对比操作前后的界面差异。如果界面没变化说明操作可能没生效代理会重试或换策略。如果出现了预期的新元素比如弹窗、新页面就认为成功。这个反馈闭环是代理能不能自主干活的关键。没有它代理就是个只会盲操作的机器人有了它代理才能根据结果调整行为。我一开始偷懒没做结果代理在登录页面反复输密码因为第一次没输进去它不知道。加上验证后这类问题基本消失。3.4 实操心得GUI 自动化的三条铁律干了这么久我总结出三条铁律。第一永远不要假设界面不变。同一个软件不同版本、不同分辨率、不同语言布局都可能不一样所以定位逻辑要足够鲁棒多用相对位置和文字锚点少用绝对坐标。第二操作要可回滚。代理点错了要能撤销所以我给每个动作都记了日志支持回放和反向操作。第三给用户留后门。代理卡住时用户能随时接管手动点几下再交还控制权。这个人机接力的设计在实际使用中非常实用。4. MCP 协议接入与工具生态4.1 MCP 是什么一句话讲清楚MCPModel Context Protocol简单说就是一套让 AI 模型和外部工具对话的标准协议。你可以把它理解成AI 世界的 USB 接口——只要工具实现了 MCP任何支持 MCP 的代理都能直接调用它不用为每个工具单独写适配代码。它定义了工具怎么描述自己、怎么被调用、返回什么格式全都标准化了。这个协议的价值在于解耦。以前我想让代理查数据库得写死一段代码现在只要挂一个数据库的 MCP 服务代理自己就知道有这个工具、参数是什么、怎么调。工具生态可以独立演进代理只管调用。4.2 工具注册与发现让代理知道自己会什么代理启动时会连接配置好的 MCP 服务拉取每个服务提供的工具列表。每个工具包含名称、描述、参数 schema。这些信息会被动态拼进提示词告诉模型你现在有这些工具可用。这里有个细节很重要工具描述的质量直接决定调用准确率。描述写得太简略模型不知道什么时候该用写得太啰嗦占满上下文还干扰判断。我的经验是描述里要包含这个工具做什么、什么时候用、参数含义、返回什么控制在两三句话。参数 schema 要严格类型、必填项、取值范围都写清楚模型照着填基本不会错。4.3 调用链路从模型输出到工具执行完整链路是这样的模型输出一个工具调用请求包含工具名和参数代理解析后找到对应的 MCP 服务通过标准输入输出或网络把请求发过去服务执行完返回结果代理把结果塞回对话历史再喂给模型继续推理。这条链路里最容易出问题的是错误处理。工具可能超时、可能返回错误、可能参数不对。我的做法是给每次调用设超时失败后把错误信息原样返回给模型让它自己决定重试还是换工具。实测下来模型对错误信息的理解能力很强很多时候能自己纠正。4.4 常见 MCP 工具类型与适配经验我实际接过的 MCP 工具大概分几类文件系统类读写、搜索、批量处理、数据库类查询、写入、网络类HTTP 请求、抓取、系统类执行命令、管理进程、专业工具类图像处理、格式转换。每一类的适配重点不同。文件系统类要注意权限和路径安全不能让代理乱删东西。数据库类要防注入参数必须走预编译。网络类要处理超时和重定向。系统类最危险我默认禁用危险命令只开放白名单。专业工具类通常有状态要注意会话管理。注意接入系统命令类 MCP 工具时务必做命令白名单和参数校验否则代理可能执行破坏性操作。5. 单文件打包与跨平台运行5.1 资源内嵌把提示词和配置塞进二进制单文件的核心是资源内嵌。Go 从 1.16 开始有 embed 包可以把文件直接编进二进制。我把提示词模板、默认配置、图标、甚至一个小型的 OCR 模型都嵌了进去。运行时从内存读不依赖外部文件。这样做的好处是分发零负担坏处是改配置要重新编译。我的折中是内嵌一份默认配置同时支持外部配置文件覆盖。用户想改就放个配置文件在旁边不想改就用默认的。提示词模板同理支持外部覆盖方便调试。5.2 跨平台编译一条命令出三个系统Go 的交叉编译非常省心。设置 GOOS 和 GOARCH 两个环境变量一条命令就能出对应平台的可执行文件。我写了个脚本一次性编译 Windows、macOS、Linux 三个版本输出到 dist 目录。要注意的是如果用了 CGO比如某些 GUI 库交叉编译会麻烦很多需要对应的交叉编译工具链。我的建议是尽量选纯 Go 的库避免 CGO这样编译最干净。实在要用就分平台在对应系统上编译用 CI 自动化。5.3 启动流程与依赖检查单文件不等于零依赖。GUI 操控依赖系统的辅助功能权限macOS 上要用户手动授权Linux 上要装 X11 或 Wayland 的相关库。所以启动时要做依赖检查缺什么明确告诉用户怎么装而不是直接崩溃。我的启动流程是先检查系统版本和必要权限再加载配置然后初始化各层模块最后连接 MCP 服务。任何一步失败都给出清晰的错误提示和解决建议。这个体验细节很影响用户留存我早期版本直接抛异常用户一脸懵后来加了引导就好多了。5.4 体积优化从 80M 压到 20M 的实践第一版编译出来 80 多兆主要是嵌了个大模型和一堆没用的库。优化手段有几个编译时加 -ldflags -s -w去掉符号表和调试信息能省 30% 左右换更小的 OCR 模型从几十兆压到几兆裁剪依赖把用不到的功能模块去掉用 UPX 压缩还能再小一半但启动会慢一点看取舍。最后压到 20 兆左右启动一秒内我觉得这个平衡点比较合适。再小就要牺牲功能了没必要。6. 常见问题排查与避坑实录6.1 代理点不中按钮怎么办这是最高频的问题。排查顺序先看截图里按钮位置和实际点击位置是否一致不一致多半是坐标缩放问题再看点击时目标窗口是否在前台不在就加激活逻辑还不行就看按钮是不是被遮挡或者需要滚动才能看到。我遇到过一次按钮在屏幕外代理一直点屏幕边缘加了滚动逻辑就好了。6.2 MCP 工具调用超时或失败先确认 MCP 服务本身是否正常单独跑一下测试。再看参数是否符合 schema类型对不对。然后看超时设置有些工具执行慢默认超时太短。最后看网络如果是远程服务检查连通性。我建议给每个工具单独配超时别用全局默认值。6.3 模型输出格式不对导致解析失败模型偶尔会不按格式输出比如该返回 JSON 却返回了自然语言。解决办法提示词里把格式要求写死给几个示例解析时做容错能提取就提取提取不了就重试重试几次还不行就报错让用户介入。我还会在系统提示里强调只输出 JSON不要任何解释能减少很多问题。6.4 常见问题速查表问题现象可能原因排查方向解决建议点击位置偏移坐标缩放不一致对比截图与实际坐标统一转物理坐标操作无响应窗口未激活检查前台窗口加激活等待逻辑工具调用超时超时设置过短单独测试工具按工具配超时解析失败模型输出格式错检查原始输出强化提示词容错启动崩溃缺系统依赖看错误日志加依赖检查引导代理死循环无结果验证看操作日志加反馈闭环6.5 独家避坑技巧汇总几个文档里不会写但很实用的技巧。日志要详细每次操作、每次模型调用、每次工具返回都记下来出问题能快速定位。给代理设最大步数防止它陷入死循环烧钱。关键操作要二次确认比如删除文件、发送消息让用户点一下确认。定期保存状态代理跑长任务时崩溃了能恢复。提示词版本化每次改动都记下来方便回滚对比效果。7. 实际应用场景与效果7.1 批量配置修改从两小时到十分钟我有个日常任务要给几十个项目的配置文件改同一个参数。以前手动改两小时起步还容易漏。现在写个提示词代理自己遍历目录、读文件、改参数、写回去十分钟搞定而且不会漏。关键是它能理解把超时时间改成 30 秒这种自然语言指令不用我写正则。7.2 图形化工具自动化填表单、导数据有些内部工具只有 GUI没有 API。以前只能人工点现在代理能识别界面、填表单、点按钮、导数据。我配了一套流程代理每天早上自动登录、导出昨天的数据、整理成表格发给我。这套流程跑了一个月没出过错。7.3 设计稿到代码参数同步的自动化设计稿改了代码里的颜色、间距、字号要同步。以前靠人肉对现在代理读设计稿的 MCP 工具拿到参数再改代码里的变量。虽然还不能全自动但省了 80% 的核对工作。7.4 效果评估成功率、耗时与成本实测数据简单任务改配置、跑命令成功率 95% 以上耗时几秒到几十秒中等任务GUI 操作、多步流程成功率 80% 左右耗时一到几分钟复杂任务跨系统、多工具协作成功率 60% 左右需要人工兜底。成本主要是模型调用简单任务几分钱复杂任务几毛钱。这个投入产出比我觉得很划算。8. 后续扩展方向这套东西还能往几个方向扩。多代理协作一个负责规划、一个负责执行、一个负责检查互相配合。学习能力把成功的操作序列存下来下次遇到类似任务直接复用。更强的视觉理解接入更好的多模态模型减少对辅助功能树的依赖。工具市场让大家分享自己写的 MCP 工具形成生态。我现在最想加的是操作录制与回放。用户手动做一遍代理学会下次自动做。这个功能对非技术用户特别友好能大幅降低使用门槛。技术上不难主要是要把操作抽象成可复用的步骤处理好变量和条件分支。最后分享一个小技巧调试代理时把每一步的截图和模型输出都存下来做成一个可视化的回放界面。这样你能清楚看到代理想了什么、看到了什么、做了什么定位问题快很多。我靠这个界面修好了好几个诡异的 bug。
