1. 为什么我要自己造一个 AI 编码代理市面上能写代码的 AI 工具已经多到挑花眼从 IDE 插件到云端 Agent功能一个比一个花哨。但真到日常干活的时候我发现自己反复被三件事卡住第一绝大多数工具要么绑定特定编辑器要么必须登录某个平台想在一个干净的环境里跑起来特别费劲第二它们大多只能读写文本文件碰到需要点按钮、拖窗口、看界面状态的任务就彻底歇菜第三想接自己的工具链往往要写一堆胶水代码配置成本比任务本身还高。所以我给自己定了一个目标做一个免费、单文件、能操控 GUI、原生支持 MCP的 AI 编码代理。单文件意味着拷贝一个脚本就能在任何装了运行时的机器上跑起来不用装依赖、不用配环境操控 GUI 意味着它不只能改代码还能像人一样去点界面、填表单、验证结果支持 MCP 意味着它能直接挂载各种现成的工具服务把文件系统、浏览器、数据库这些能力接进来而不是每接一个能力就重写一遍逻辑。这篇文章我会把这套东西的完整设计思路、核心实现细节、实操步骤和踩过的坑全部摊开讲。适合两类人看一类是想理解 AI 编码代理到底怎么运转的开发者另一类是想自己动手做一个、但不知道从哪下手的折腾党。哪怕你之前没接触过 MCP我也会用生活化的例子把它讲清楚保证你看完能照着复现一个能用的版本。2. 整体架构设计与技术选型思路2.1 单文件运行到底意味着什么先把“单文件运行”这个卖点说透。很多人以为单文件就是把代码塞进一个.py里其实远不止如此。真正的单文件运行要满足三个条件零外部依赖安装、零配置文件、零后台服务。也就是说用户拿到这个文件python agent.py一敲就能跑不需要先pip install一堆包不需要先启动一个数据库或者消息队列更不需要去某个网站注册账号拿密钥。要做到这一点我在选型上做了几个关键取舍。运行时我选了 Python因为它的标准库足够厚http.server、subprocess、json、threading这些开箱即用能覆盖代理 80% 的基础能力。唯一必须外部引入的是大模型的调用但这一块我通过标准库的urllib直接发 HTTP 请求解决连requests都不需要。GUI 操控部分我优先用系统自带的辅助功能接口Windows 上用ctypes调user32.dllmacOS 上用osascript走 AppleScriptLinux 上走xdotool这些都是系统层面就有的东西不需要额外装包。提示单文件不等于功能阉割。关键在于把“必须常驻”的东西压到最少把“按需加载”的东西做成可选。比如 MCP 客户端只在用户真的配置了服务时才初始化没配置就完全不走那条路径。2.2 为什么是 MCP 而不是自己造协议MCP 全称 Model Context Protocol直白点说就是一套让 AI 模型和外部工具对话的标准接口。你可以把它理解成 USB 接口以前每个设备都有自己的插头现在统一成 USB谁都能插。MCP 的价值就在这它把“工具怎么描述自己”“模型怎么调用工具”“结果怎么回传”这三件事标准化了。我一开始也想过自己定义一套 JSON 格式来传工具调用但很快就放弃了。原因很简单自己造协议意味着所有工具都得我亲自适配而 MCP 已经有现成的生态文件系统、浏览器自动化、数据库查询这些常见能力都有别人写好的服务端我只要实现一个客户端去连就行。这就像你装修房子自己拉电线当然可以但既然有标准插座为什么不直接用。在代理里MCP 客户端的职责很清晰启动时读取配置知道有哪些服务可用运行时把服务提供的工具列表转成模型能理解的格式模型决定调用某个工具时客户端负责发请求、等结果、把结果塞回对话上下文。整个链路是异步的因为工具调用可能很慢不能阻塞主循环。2.3 GUI 操控的实现路径选择GUI 操控是这套代理和普通编码工具最大的区别。普通工具改完代码就结束了但真实开发里经常需要“改完代码打开应用点几下看看效果”。我实现 GUI 操控时面临一个选择是用图像识别去找按钮还是用系统辅助功能接口去定位控件。图像识别听起来很酷但实际用起来很脆。分辨率一变、主题一换、字体一调识别率就崩了。而且图像识别需要额外的模型和依赖违背了单文件的原则。所以我选了辅助功能接口这条路。它的原理是操作系统本身就维护了一棵控件树每个按钮、输入框、菜单都有自己的标识和位置信息。代理通过这棵树去查找目标控件然后模拟点击或输入。这种方式稳定得多因为它不依赖像素只依赖控件的逻辑结构。具体实现上我封装了一层抽象find_element负责按名称或类型找控件click负责点击type_text负责输入get_state负责读取控件当前状态。底层根据不同系统调不同的接口上层逻辑完全一致。这样代理在写操作步骤时不需要关心当前是什么系统。2.4 大模型调用与提示词设计模型这块我没有绑定任何一家而是做了一个可切换的适配层。配置里写清楚用哪个接口、哪个模型名、密钥是什么代理就按这个去调。这样做的好处是今天用这个模型明天想换另一个改一行配置就行不用动代码。提示词设计上我把系统提示分成三块角色定义、工具说明、行为约束。角色定义告诉模型它是一个编码代理能读写文件、能操控界面、能调用工具。工具说明把当前可用的 MCP 工具和内置工具列出来每个工具的名字、参数、用途都写清楚。行为约束是最关键的部分它规定模型必须先思考再行动、每次只做一件事、做完要验证结果、遇到错误要报告而不是瞎猜。这三块合起来才能让模型稳定地按预期工作而不是天马行空地乱来。3. 核心模块拆解与关键实现细节3.1 代理主循环是怎么转起来的代理的核心是一个循环接收任务、思考、行动、观察结果、再思考直到任务完成或达到最大步数。这个循环看起来简单但里面有几个细节决定了它好不好用。第一个细节是上下文管理。每轮对话都会往上下文里塞东西如果不控制很快就会超出模型的窗口限制。我的做法是保留完整的系统提示和最近若干轮对话更早的内容做摘要压缩。摘要不是随便压而是保留“做了什么操作、得到什么结果、当前处于什么状态”这三类信息丢掉冗余的中间输出。第二个细节是错误处理。模型调用工具失败是常态比如文件不存在、控件找不到、网络超时。我的策略是失败信息原样回传给模型让它自己决定是重试、换方法还是放弃。但我会加一个重试计数器同一个操作连续失败三次就强制中断避免死循环烧钱。第三个细节是步数限制。没有限制的代理可能会陷入无限循环所以我在配置里设了一个最大步数默认 50 步。超过就停下来把当前状态和未完成的任务报告给用户。# 代理主循环的简化骨架 def run_agent(task, max_steps50): context build_initial_context(task) for step in range(max_steps): response call_model(context) action parse_action(response) if action.type finish: return action.result result execute_action(action) context append_observation(context, result) if should_compress(context): context compress_context(context) return 达到最大步数任务未完成3.2 MCP 客户端的连接与工具发现MCP 客户端要做的第一件事是连接服务端。连接方式主要有两种一种是本地进程代理启动一个子进程通过标准输入输出通信另一种是远程服务通过 HTTP 或 WebSocket 通信。我两种都支持配置里写清楚用哪种就行。连接建立后客户端会发一个“列出工具”的请求服务端返回它提供的所有工具及其参数定义。这些定义会被转换成模型能理解的格式塞进系统提示里。这里有个坑不同服务端返回的工具描述详细程度差别很大有的写得很清楚有的就一句话。我的做法是在转换时做一层增强把参数类型、是否必填、示例值都补上让模型更容易正确调用。工具调用的结果回传也有讲究。MCP 的结果可能是纯文本也可能是结构化数据还可能是错误。我在客户端里统一做了一层包装把结果转成“成功/失败 内容”的格式再交给模型。这样模型不需要关心底层协议细节只看统一格式就行。注意MCP 服务端的启动命令要写绝对路径相对路径在不同工作目录下会找不到。这个坑我踩过排查了半天才发现是路径问题。3.3 GUI 操控的定位与操作封装GUI 操控最难的部分是定位控件。辅助功能接口虽然提供了控件树但树的结构在不同应用里差异很大。有的应用控件命名规范直接按名字就能找到有的应用所有控件都叫“Button”只能靠位置和层级去推断。我的定位策略是组合条件先按名称精确匹配找不到就按类型加位置模糊匹配再找不到就遍历子树打印结构让模型自己判断。这个“打印结构”的能力很关键相当于给模型一双眼睛让它能看到当前界面上有什么而不是盲猜。操作封装上点击我实现了三种模式单击、双击、右键。输入我实现了两种覆盖输入和追加输入。读取状态我实现了获取文本、获取选中项、获取是否可用。这些看起来基础但组合起来就能覆盖绝大多数界面操作场景。# GUI 操作的统一接口示例 class GUIAgent: def find_element(self, nameNone, roleNone, index0): # 先按名称找再按角色找最后按索引取 pass def click(self, element, buttonleft, clicks1): # 根据系统调用不同的底层接口 pass def type_text(self, element, text, clear_firstTrue): # 先清空再输入避免追加到旧内容后面 pass def dump_tree(self, max_depth3): # 打印控件树供模型分析 pass3.4 文件操作与代码编辑的安全边界编码代理必然要读写文件但这里有个安全边界问题代理不能想改哪就改哪。我的做法是划定一个工作目录所有文件操作都限制在这个目录内。路径里出现..或者绝对路径指向目录外直接拒绝。这个限制看起来简单但能避免很多误操作。代码编辑上我没有让模型直接输出整个文件内容再覆盖而是采用“查找替换”的方式。模型给出要替换的原文和替换后的内容代理在文件里定位原文确认唯一匹配后再替换。这样做的好处是模型不需要知道文件全部内容只需要知道要改的那一段既省 token 又降低出错概率。如果原文在文件里出现多次代理会拒绝替换并报告让模型给出更精确的上下文。这个机制逼着模型去理解代码结构而不是粗暴地全局替换。4. 从零到一完整实操流程4.1 环境准备与依赖检查虽然说是单文件但运行环境还是要有 Python 的。我实测下来Python 3.9 以上都能跑3.11 最稳。检查环境很简单终端里敲python --version看一眼就行。如果版本太低去官网下个新的装上记得勾选“添加到 PATH”。GUI 操控部分在不同系统上需要不同的系统组件。Windows 上什么都不用装user32.dll是系统自带的。macOS 上需要开启辅助功能权限在“系统设置 - 隐私与安全性 - 辅助功能”里把终端加进去。Linux 上需要装xdotool一条命令sudo apt install xdotool搞定。这些是系统层面的依赖不是 Python 包所以不影响单文件的定位。MCP 服务端如果是本地进程模式需要确保对应的命令能执行。比如文件系统服务端通常是个 Node 脚本那就需要机器上有 Node。这个按需准备就行不用 MCP 的话完全不需要。4.2 配置文件的最小化设计配置文件我用 JSON 格式因为标准库直接支持解析不需要额外依赖。配置里主要写三块模型接口信息、MCP 服务列表、代理行为参数。{ model: { endpoint: https://api.example.com/v1/chat, api_key: your-key-here, model_name: coding-model-v1, max_tokens: 4096 }, mcp_servers: [ { name: filesystem, command: node, args: [/abs/path/to/fs-server.js], transport: stdio } ], agent: { max_steps: 50, work_dir: /home/user/project, retry_limit: 3 } }配置文件的路径我设计成可选的不传就用默认值传了就用指定的。默认值里模型接口是空的所以第一次跑必须传配置否则代理会提示缺少模型信息。这个设计是为了避免把密钥硬编码在代码里也方便多环境切换。4.3 启动代理并跑通第一个任务启动命令就一行python agent.py --config config.json。跑起来后代理会先加载配置、连接 MCP 服务、拉取工具列表然后进入交互模式等你输入任务。第一个任务我建议选简单的比如“在当前目录创建一个 hello.txt内容写 Hello World”。这个任务能验证文件操作链路是否通畅。代理收到任务后会先思考需要调用哪个工具然后调用文件写入工具最后确认文件创建成功。整个过程你可以在终端看到每一步的日志。如果这一步成功了再试一个带 GUI 的任务比如“打开计算器计算 123 加 456把结果告诉我”。这个任务会触发 GUI 操控链路代理先找到计算器窗口然后依次点击数字按钮和运算符最后读取显示区域的结果。这一步能跑通说明整套系统都活了。4.4 接入 MCP 工具服务的实操步骤接入 MCP 服务分三步。第一步是找到或写一个 MCP 服务端。现成的服务端很多文件系统、浏览器、数据库这些常见能力都有开源实现。第二步是在配置文件的mcp_servers数组里加上这个服务的启动信息。第三步是重启代理让它重新拉取工具列表。这里有个细节要注意不同服务端的启动参数格式不一样有的用位置参数有的用命名参数。配置里的args数组会原样传给启动命令所以你得看清楚服务端的文档把参数写对。写错了代理会连不上日志里会报错按报错信息调整就行。接入成功后你可以在代理启动日志里看到新增的工具列表。比如接入了浏览器服务就会多出“打开网页”“点击元素”“截图”这些工具。模型在规划任务时会自动把这些工具纳入考虑范围。5. 常见问题与排查技巧实录5.1 模型不按预期调用工具怎么办这是最常见的问题。表现是模型在回复里描述了要做什么但没有真正发起工具调用或者调用了错误的工具。原因通常有三个工具描述不清楚、系统提示约束不够、模型本身能力不足。排查顺序是这样的先看工具描述参数名和说明是不是足够明确有没有歧义。再看系统提示有没有明确要求“必须通过工具调用而不是文字描述来执行操作”。如果这两块都没问题那就是模型能力问题换个更强的模型试试。我自己的经验是在系统提示里加一句“你只能通过调用工具来执行操作任何文字描述都不算执行”能显著减少模型“光说不做”的情况。另外给每个工具加一个简短的调用示例也能提升调用准确率。5.2 GUI 控件找不到的排查思路控件找不到的报错很常见原因也很多。我的排查流程是先让代理打印当前窗口的控件树看看目标控件到底在不在树里。如果不在可能是窗口没激活或者控件是动态加载的还没出现。如果在树里但名字对不上就调整查找条件用类型加位置去匹配。还有一种情况是控件在树里但代理点不到。这通常是坐标计算的问题比如控件有偏移或者被遮挡。解决办法是先滚动到可见区域再执行点击。如果还是不行就换用键盘操作比如用 Tab 键切换焦点用回车键触发。提示调试 GUI 操控时把每一步的截图和控件树都打出来对照着看比盲猜快得多。5.3 MCP 连接失败的典型原因MCP 连接失败一般报错很直接比如“命令未找到”“连接超时”“协议错误”。命令未找到就是启动命令的路径不对检查配置里的command和args。连接超时通常是服务端启动太慢可以加大超时时间。协议错误一般是版本不匹配服务端和客户端的 MCP 版本要对上。我遇到过一个比较隐蔽的问题服务端启动后往标准输出打了日志干扰了协议通信。MCP 的 stdio 模式要求标准输出只能走协议数据日志必须打到标准错误。如果你自己写服务端这点一定要记住。5.4 常见问题速查表问题现象可能原因排查方法解决方式模型只描述不执行系统提示约束不足检查提示词加“必须调用工具”约束工具调用参数错误工具描述不清晰查看工具定义补充参数说明和示例GUI 控件找不到窗口未激活或控件未加载打印控件树先激活窗口再查找点击无效坐标偏移或被遮挡截图对照滚动到可见区域再点MCP 连接超时服务端启动慢看启动日志加大超时时间MCP 协议错误版本不匹配查版本号对齐客户端服务端版本文件操作被拒绝路径超出工作目录检查路径限制在工作目录内代理陷入死循环无步数限制看步数计数设置最大步数5.5 性能与成本的平衡技巧代理跑起来后token 消耗是实打实的成本。我总结了几个省 token 的技巧。第一上下文压缩要激进一点中间过程的冗余输出该丢就丢。第二工具返回的结果如果太长只保留关键部分比如文件内容只返回改动附近的行。第三简单任务用便宜模型复杂任务再切强模型配置里可以按任务类型切换。还有一个技巧是缓存。同样的工具调用如果短时间内重复出现结果可以直接复用不用再跑一遍。比如连续读取同一个文件第二次直接返回缓存内容。这个在调试阶段特别有用能省不少时间和 token。6. 我踩过的坑和几条实在建议第一个坑是过度信任模型的空间理解能力。我一开始让模型直接输出控件的坐标结果它给的坐标经常偏。后来改成让模型描述要找什么控件由代理去定位准确率一下就上来了。模型擅长理解意图不擅长精确计算把这两件事分开各干各的效果最好。第二个坑是忽略了不同系统的差异。我最早在 Windows 上开发跑得好好的换到 macOS 上发现控件树结构完全不一样查找逻辑全废。后来我把系统相关的部分全部抽象成接口上层逻辑不碰具体实现才解决了这个问题。如果你也打算做跨平台的东西这一步越早做越好。第三个坑是 MCP 服务端的生命周期管理。代理启动时拉起服务端代理退出时如果没关掉服务端进程就会变成孤儿进程越积越多。我的做法是在代理退出时发一个关闭信号等服务端自己退出超时再强制杀。这个细节不起眼但不处理的话跑几天机器上全是僵尸进程。最后分享一个实用建议把代理的每一步操作都记日志包括输入、输出、工具调用、结果。出问题的时候日志就是唯一的线索。我现在的日志格式是每行一个 JSON包含时间戳、步骤号、操作类型、内容。这样既能人眼看也能用脚本分析。调试效率比瞎猜高太多了。这套东西我陆陆续续打磨了小半年从最开始只能改文件到现在能操控界面、挂载各种工具中间推翻重来了好几次。如果你也想动手做一个我的建议是从最小可用版本开始先跑通“读文件、改文件、写文件”这条链路再逐步加 GUI 和 MCP。一口吃不成胖子但每一步跑通的成就感会让你愿意继续折腾下去。