1. 为什么我要自己造一个编码代理
市面上能用的 AI 编码工具其实已经不少了，从 IDE 插件到命令行助手，选择很多。但我用了大半年之后，始终有几个地方觉得别扭，最后干脆自己动手做了一个。这个项目最核心的三个特点就是：免费、支持操控 GUI、支持 MCP 协议，而且整个程序是单文件运行的。
先说免费这件事。很多编码代理工具按 token 计费或者按月订阅，个人开发者偶尔用用还行，但如果想把它当成日常主力工具，成本会迅速累积。我这个项目本身不绑定任何付费服务，你只需要自己准备一个模型接口就行，程序本身不产生额外费用。
再说 GUI 操控。这是我觉得现有工具最欠缺的一块。大部分编码代理只能在终端里跑命令、读写文件，但真实的开发工作里，有大量操作是发生在图形界面里的——比如配置某个 IDE 的插件、在数据库客户端里执行查询、在浏览器里调试前端页面。这些操作纯靠命令行很难完成，或者需要写一堆自动化脚本。我这个代理可以直接操控 GUI，模拟鼠标点击、键盘输入、窗口切换，把图形界面操作也纳入到自动化流程里。
MCP 协议的支持是第三个关键点。MCP 是这两年逐渐流行起来的一个协议标准，简单说就是让 AI 模型能够以统一的方式调用外部工具和数据源。支持 MCP 意味着我的代理可以接入各种已有的 MCP 服务，比如文件系统访问、数据库查询、API 调用等等，不用每接一个新工具就重新写一遍适配代码。
单文件运行这个设计，是我在踩了无数次环境配置的坑之后做出的决定。你肯定遇到过这种情况：clone 一个项目下来，装依赖装了半天，结果某个包的版本冲突，或者 Python 版本不对，折腾两小时还没跑起来。单文件意味着你下载下来就能用，不需要 pip install 一堆东西，不需要配虚拟环境，不需要担心依赖冲突。对于我这种经常换机器、经常在别人电脑上临时干活的人来说，这个特性太重要了。
这个项目适合谁呢？如果你是个独立开发者，想有个趁手的自动化编码助手；如果你经常需要做重复性的 GUI 操作，想把它自动化掉；如果你对 MCP 协议感兴趣，想找个实际项目来理解和实践——那这个项目应该对你有用。下面我会从设计思路、核心实现、GUI 操控的具体做法、MCP 集成、以及实际使用中的各种坑，一步步拆开来讲。
2. 单文件架构的设计取舍与实现细节
2.1 为什么单文件比模块化更合适这个场景
一般做项目，我们都会强调模块化、分层架构、职责分离。但这些原则的前提是项目会长期维护、多人协作、功能不断扩展。对于一个个人用的编码代理工具，情况不太一样。
我一开始也是按标准项目结构来搭的：agents/目录放代理逻辑，tools/放工具实现，mcp/放协议适配，gui/放界面操控，utils/放辅助函数。结果用了两周就发现几个问题。第一是部署麻烦，每次换机器都要把整个目录拷过去，还得确保目录结构不变。第二是调试链路长，改一个函数要跳好几个文件才能理清调用关系。第三是分享困难，想发给朋友试用，得打包整个项目，对方还得配环境。
后来我决定把所有代码合并到一个文件里。这个决定听起来有点反直觉，但实际用下来收益很明显。整个程序就是一个.py文件，大概几千行，下载下来python agent.py就能跑。想改哪里直接搜索函数名，不用在目录树里找。想分享直接发文件，对方不需要任何额外配置。
当然单文件也有代价。最大的问题是代码组织会变得依赖注释和分区，而不是目录结构。我的做法是在文件里用明显的注释块划分区域，比如# ========== MCP 协议适配 ==========这样的分隔线，让视觉上仍然有清晰的模块边界。另外单文件不适合多人协作，但个人项目本来就不涉及这个问题。
2.2 依赖最小化的具体策略
单文件要真正能做到"下载即用"，光合并代码还不够，依赖也得控制住。我的原则是：能用标准库解决的，绝不引入第三方包。
Python 标准库其实比很多人想象的强大。subprocess可以调外部命令，json处理数据交换，urllib做 HTTP 请求，threading做并发，tkinter甚至能搭简单界面。我统计了一下，最终整个项目只依赖了三个第三方包：一个用于 GUI 操控的库、一个用于和模型 API 通信的 HTTP 客户端、一个用于处理 MCP 协议消息的解析库。其他全部用标准库实现。
这里有个细节值得说：GUI 操控库的选择。市面上做 GUI 自动化的方案有好几种，有基于图像识别的，有基于系统 API 的，有基于无障碍接口的。我最终选了一个跨平台支持比较好、API 相对简洁的库。它的原理是通过系统底层的输入事件模拟来实现点击和输入，不依赖图像匹配，所以不受分辨率和主题变化的影响。缺点是不同操作系统的权限配置不一样，这个后面会专门讲。
依赖最小化还有一个好处是启动速度快。我实测过，从执行命令到代理准备好接收输入，冷启动大概 1.5 秒左右。如果用了一堆重型框架，光 import 就要好几秒。对于需要频繁调用的工具来说，这个差异很明显。
2.3 配置管理：单文件怎么存设置
单文件运行有个现实问题：配置放哪？总不能每次都改代码里的常量。我的方案是约定优于配置，同时支持外部覆盖。
程序启动时会按顺序查找配置：先看当前目录有没有agent.config.json，没有就看用户主目录下的~/.ai-agent/config.json，都没有就用内置的默认值。配置项包括模型接口地址、API 密钥、默认工作目录、GUI 操控的灵敏度参数等等。这样设计的好处是，临时用可以直接跑，长期用可以把配置放到主目录，换项目也不用改。
API 密钥这种敏感信息，我建议不要写在配置文件里明文存储。我的做法是优先读环境变量，环境变量没有才读配置文件。这样在共享机器或者容器环境里，可以通过环境变量注入密钥，不落盘。
提示：如果你打算把这个工具放到服务器上跑，记得把 GUI 操控相关的功能关掉。服务器通常没有图形界面，相关调用会直接报错。配置文件里有个
enable_gui开关，设成 false 就行。
3. GUI 操控是怎么实现的
3.1 从"只能跑命令"到"能点鼠标"的跨越
传统的编码代理，能力边界基本就是文件系统和命令行。你让它改代码、跑测试、装依赖，都没问题。但一旦涉及图形界面，它就抓瞎了。比如你想让它帮你配置某个软件的设置，那个设置只存在于 GUI 里，没有对应的命令行接口，传统代理就无能为力。
GUI 操控的核心思路，是把"看屏幕"和"操作屏幕"这两件事拆开。看屏幕，就是截屏加图像分析，或者通过系统接口读取窗口和控件信息。操作屏幕，就是模拟鼠标移动点击、键盘按键输入。把这两件事组合起来，代理就能像人一样操作图形界面了。
我的实现里，GUI 操控被封装成一组工具函数，代理可以像调用普通函数一样调用它们。比如gui_click(x, y)在指定坐标点击，gui_type("text")输入文字，gui_hotkey("ctrl", "s")按快捷键，gui_screenshot()截取当前屏幕。代理在规划任务时，如果判断需要 GUI 操作，就会调用这些函数。
这里有个关键设计：坐标系统一用相对坐标还是绝对坐标。绝对坐标的问题是换分辨率就失效，相对坐标的问题是计算复杂。我最终用的是绝对坐标，但在配置里记录了一个基准分辨率，如果实际分辨率不同，会自动按比例缩放。这样既简单又能在常见分辨率变化下工作。
3.2 窗口定位：怎么找到要操作的那个窗口
光有坐标点击还不够，因为屏幕上的窗口位置会变。今天你的编辑器在左边，明天可能拖到右边了。所以代理需要能定位窗口。
我的做法是通过系统接口枚举当前所有窗口，拿到每个窗口的标题、位置、大小。代理可以按标题关键词查找窗口，比如找标题里包含 "Visual Studio Code" 的窗口，拿到它的位置后，再计算窗口内某个控件的相对坐标，转换成屏幕绝对坐标去点击。
这个流程听起来简单，实际有不少坑。不同操作系统的窗口接口差异很大，Windows 用 Win32 API，macOS 用 Accessibility API，Linux 用 X11 或 Wayland 的接口。我在代码里做了抽象层，上层调用统一的find_window(title_keyword)，底层根据操作系统走不同实现。目前 Windows 和 macOS 支持比较完善，Linux 在 X11 下能用，Wayland 下受限比较多。
还有一个坑是窗口层级。有时候你要找的窗口被其他窗口挡住了，直接点击会点到上面的窗口。我的处理是先调用系统的窗口激活接口，把目标窗口提到最前，等一小段时间让动画结束，再执行点击。这个等待时间很关键，太短了窗口还没到位，太长了整体效率低。我实测下来 300 毫秒是个比较稳的值。
3.3 输入模拟的可靠性问题
模拟键盘输入看起来简单，实际做起来问题不少。最典型的是输入法干扰。如果你的系统开着中文输入法，代理模拟按键输入英文时，可能会被输入法拦截，变成拼音候选。我的解决方案是在输入前先通过系统接口切换到英文输入法，输入完再切回来。这个操作在不同系统上实现方式不同，但思路是一样的。
另一个问题是输入速度。如果模拟输入太快，有些应用会丢字符。我一开始设的间隔是 10 毫秒，结果在某个 Electron 应用里经常丢字。后来调到 50 毫秒就稳定了。这个值可以在配置里调，不同应用可能需要不同的设置。
鼠标点击也有类似问题。单击通常没问题，但双击如果两次点击间隔太长，会被识别成两次单击。系统对双击的时间阈值一般是 500 毫秒，我设的是 200 毫秒，确保能被识别为双击。
注意：GUI 操控在有些系统上需要额外授权。macOS 需要在"辅助功能"里给终端或 Python 解释器授权，否则模拟的点击和按键会被系统忽略。Windows 一般不需要额外授权，但如果程序以管理员权限运行，而目标窗口是普通权限，可能会因为权限隔离导致操作失败。
3.4 截图与视觉反馈
代理要操作 GUI，光能点还不够，还得能"看到"操作的结果。截图功能就是代理的眼睛。我的实现里，gui_screenshot()会截取当前屏幕，返回图像数据。代理可以把这张图发给多模态模型分析，判断当前界面状态，决定下一步操作。
这里有个性能考量。全屏截图在高分辨率下数据量很大，传给模型既慢又贵。我的优化是支持区域截图，代理可以只截取关心的那块区域。比如它知道要操作的按钮大概在屏幕右下角，就只截右下角那一块，数据量能减少百分之八九十。
截图频率也需要控制。如果每一步操作都截图分析，整个流程会非常慢。我的策略是只在关键节点截图：操作前截一张确认初始状态，操作后截一张确认结果，中间过程不截。这样既保证了准确性，又控制了开销。
4. MCP 协议集成：让代理接入外部能力
4.1 MCP 到底解决了什么问题
MCP 这个词这两年出现频率很高，但很多人对它的理解还停留在"又一个协议"的层面。我用一句话解释：MCP 是让 AI 模型和外部工具之间用统一方式对话的标准。
在没有 MCP 之前，每接一个新工具，你都得写一套适配代码。接文件系统写一套，接数据库写一套，接某个 API 又写一套。这些适配代码逻辑类似但实现各异，维护起来很累。MCP 把这些统一了：工具方按照 MCP 规范暴露自己的能力，模型方按照 MCP 规范调用，中间不需要为每个工具单独写适配。
我的代理支持 MCP 之后，能力扩展变得非常简单。想让它能查数据库，找一个现成的数据库 MCP 服务接上就行。想让它能操作浏览器，找一个浏览器 MCP 服务接上。不用改代理本身的代码，只需要在配置里加上 MCP 服务的地址。
4.2 MCP 服务的接入流程
接入一个 MCP 服务，大致分几步。首先要知道这个服务是怎么通信的，MCP 支持几种传输方式，常见的是标准输入输出和 HTTP。标准输入输出的服务，通常是本地启动一个进程，通过管道通信。HTTP 的服务，就是一个网络地址。
我的代理在启动时会读取配置里的 MCP 服务列表，逐个建立连接。连接建立后，会调用服务的能力发现接口，拿到这个服务支持哪些工具、每个工具需要什么参数。这些信息会被注册到代理的工具列表里，代理在规划任务时就能看到这些工具并调用。
调用的时候，代理把工具名和参数打包成 MCP 格式的消息发过去，服务执行完把结果返回。整个过程对代理来说是透明的，它不需要知道底层是本地进程还是远程 HTTP。
这里有个实际经验：MCP 服务的启动顺序很重要。如果代理启动时某个 MCP 服务还没准备好，连接会失败。我的处理是加了重试机制，启动时连不上就等几秒再试，最多试三次。另外配置文件里可以标记某个服务是"可选"的，连不上就跳过，不影响代理主体功能。
4.3 工具注册与调用的内部机制
代理内部维护着一个工具注册表。每个工具有一条记录，包含工具名、描述、参数 schema、实际执行函数。MCP 服务提供的工具，在注册时会包装一层，把 MCP 的调用协议转换成内部统一的调用接口。
这样做的好处是，代理的核心逻辑不需要区分"这是内置工具"还是"这是 MCP 工具"。它看到的都是统一的工具接口，调用方式完全一样。这大大简化了代理的决策逻辑。
工具描述的质量直接影响代理的使用效果。如果描述写得太模糊，代理不知道该什么时候用这个工具。我在接入 MCP 服务时，会检查工具描述是否清晰，不清晰的会手动补充。比如一个数据库查询工具，描述里应该说明它支持什么数据库、参数格式是什么、返回什么结构。这些信息代理需要知道才能正确调用。
参数 schema 也很关键。MCP 用 JSON Schema 描述参数，代理会根据 schema 生成调用参数。如果 schema 写得不严谨，代理可能生成错误的参数格式，导致调用失败。我遇到过某个 MCP 服务的 schema 把数字类型写成了字符串，结果代理传数字过去被拒绝。这种问题只能在使用中发现并反馈给服务方。
4.4 流式输出与结果处理
有些 MCP 工具的执行时间比较长，比如跑一个大型查询或者处理一批文件。如果等全部完成才返回结果，代理会卡住很久。MCP 支持流式输出，工具可以分多次返回中间结果。
我的代理对流式输出的处理是：收到中间结果就先展示给用户，同时继续等待后续结果。这样用户能看到进度，不会觉得程序卡死了。对于编码代理来说，这个特性在跑测试或者构建项目时特别有用，能实时看到输出。
结果处理还有一个细节是错误处理。MCP 工具执行失败时，会返回错误信息。代理需要能识别这是错误，并决定是重试、换工具、还是报告给用户。我的做法是把错误信息也作为一种结果传给模型，让模型判断怎么处理。模型看到错误信息后，通常会尝试其他方案或者向用户说明情况。
5. 代理的决策循环与任务规划
5.1 从用户输入到任务分解
代理接收到用户的一句话需求，比如"帮我把这个项目的测试跑一遍，失败的修一下"，它需要把这句话拆解成可执行的步骤。这个拆解过程依赖模型的理解能力。
我的实现里，代理会把当前环境信息（工作目录、项目类型、可用工具列表）和用户需求一起发给模型，让模型输出一个执行计划。计划是一系列步骤，每一步指定用哪个工具、传什么参数。代理按顺序执行这些步骤，每步执行完把结果反馈给模型，模型根据结果决定下一步。
这个循环是代理的核心。它不是一次性规划好所有步骤然后机械执行，而是走一步看一步。因为实际执行中经常出现意外，比如某个命令报错了，某个文件不存在了，这些都需要模型根据实际情况调整计划。
循环的终止条件是模型判断任务完成，或者达到最大步数限制。最大步数限制很重要，防止模型陷入死循环。我设的默认值是 50 步，一般任务够用，复杂任务可以在配置里调大。
5.2 工具选择时的优先级逻辑
代理面对一个任务时，往往有多种工具可以完成。比如要读取一个文件，可以用内置的文件读取工具，也可以用 MCP 提供的文件系统工具。这时候需要有优先级逻辑。
我的优先级原则是：内置工具优先于 MCP 工具，专用工具优先于通用工具。内置工具经过充分测试，稳定性和性能都有保障。MCP 工具虽然扩展性强，但质量参差不齐。专用工具比如"读取 Python 文件并解析 AST"，比通用的"读取文件"更适合特定场景。
这个优先级不是硬编码的，而是通过工具描述里的优先级字段来控制的。代理在规划时会参考这个字段。用户也可以在配置里覆盖优先级，比如某个 MCP 工具特别好用，可以把它提到内置工具前面。
5.3 上下文管理与长任务处理
代理跑长任务时，上下文会越来越长。每一步的工具调用和结果都累积在对话历史里，很快就会超出模型的上下文窗口。这是个必须解决的问题。
我的方案是分层上下文管理。最近的几步完整保留，包括工具调用的详细参数和结果。稍早的步骤只保留摘要，比如"执行了测试，3 个失败"。更早的步骤只保留结论，比如"测试阶段完成，有失败需要修复"。这样既保留了关键信息，又控制了上下文长度。
摘要的生成也是让模型做的。当上下文超过阈值时，代理会把较早的对话历史发给模型，让它生成摘要。摘要会替换掉原始历史，释放上下文空间。这个过程对用户是透明的，用户看到的是代理持续工作，不会感知到上下文被压缩了。
提示：上下文管理策略对代理的长期表现影响很大。如果摘要太激进，代理会丢失重要细节，导致重复劳动或者做出错误决策。如果太保守，上下文很快爆掉。我的经验是保留最近 10 步的完整信息，10 到 30 步用摘要，30 步以上只留结论。这个比例可以根据任务复杂度调整。
6. 实际使用中的坑与应对
6.1 GUI 操控在不同系统上的权限问题
前面提过权限问题，这里展开说。macOS 的权限控制最严格。第一次运行 GUI 操控功能时，系统会弹窗要求授权。如果用户点了拒绝，后续所有模拟操作都会被静默忽略，程序不会报错，但什么都不会发生。这个坑我踩过，排查了半天才发现是权限没给。
解决办法是引导用户去"系统设置 - 隐私与安全性 - 辅助功能"里手动添加授权。程序启动时可以检测是否有权限，没有就提示用户去设置。检测的方法是尝试执行一个无害的模拟操作，看是否成功。
Windows 的权限问题主要出现在权限隔离上。如果代理以普通权限运行，要操作一个以管理员权限运行的窗口，操作会失败。反过来也一样。解决办法是让代理和目标窗口保持相同权限级别。如果目标程序需要管理员权限，代理也得用管理员权限启动。
Linux 下 X11 一般不需要特殊授权，但 Wayland 对模拟输入的限制比较多，很多操作无法实现。如果必须在 Wayland 下用，可以考虑切换到 X11 会话，或者用支持 Wayland 的输入模拟方案。
6.2 MCP 服务连接失败的排查思路
MCP 服务连不上是常见问题，原因可能有很多。我的排查顺序是这样的：
先看服务本身是否在运行。如果是本地进程方式，检查进程是否启动。如果是 HTTP 方式，用 curl 或浏览器访问一下地址，看是否有响应。
再看配置是否正确。地址、端口、认证信息，任何一项错了都连不上。我遇到过配置文件里地址写成了localhost但服务只监听127.0.0.1的情况，虽然通常这两个等价，但某些环境下会有差异。
然后看协议版本是否匹配。MCP 协议还在演进，不同版本之间可能有兼容性问题。如果服务用的协议版本和代理支持的不一致，连接会失败。这种情况需要升级其中一方。
最后看日志。MCP 服务通常会输出日志，代理这边也有连接日志。对照两边的日志，通常能定位到问题所在。我建议在配置里打开详细日志开关，排查问题时很有用。
6.3 模型接口不稳定时的降级策略
代理依赖模型接口，如果接口不稳定，整个代理就没法工作。我遇到过接口偶尔超时、偶尔返回格式错误的情况。如果每次失败都直接报错退出，体验很差。
我的降级策略是：接口调用失败时自动重试，重试间隔递增。连续失败超过阈值后，切换到备用接口（如果配置了的话）。如果所有接口都不可用，代理会暂停当前任务，保存状态，等接口恢复后可以继续。
状态保存是个关键设计。代理会把当前的任务计划、已执行的步骤、上下文摘要保存到本地文件。接口恢复后，从保存点继续，不用从头再来。这个功能在跑长任务时特别有用，避免了因为网络波动导致前功尽弃。
6.4 单文件带来的调试挑战与应对
单文件虽然部署方便，但调试确实不如多文件项目方便。没有模块化的 import 关系，函数之间的调用全靠搜索。代码量大了之后，找一个函数的定义要翻很久。
我的应对方法是在文件开头维护一个目录注释，列出所有主要函数和它们所在的行号范围。改代码时同步更新这个目录。虽然手动维护有点麻烦，但查找效率提升明显。
另一个方法是充分利用编辑器的跳转功能。现代编辑器都支持跳转到定义、查找引用，即使单文件也能快速导航。我用的是 VS Code，配合 Python 插件，跳转体验和多文件项目差不多。
还有一个技巧是把调试代码和正式代码分开。我在文件末尾放了一个if __name__ == "__main__"块，里面是各种调试入口。想测试某个功能，直接在这个块里调用对应函数，不用走完整的代理流程。这样调试单个功能时很快。
7. 这套方案还能怎么扩展
7.1 接入更多 MCP 服务扩展能力边界
目前我接入了文件系统、数据库、浏览器三个 MCP 服务，基本覆盖了日常开发的大部分场景。但 MCP 生态在快速发展，新的服务不断出现。比如有人做了设计工具的 MCP 服务，可以让代理直接操作设计稿；有人做了项目管理工具的 MCP 服务，可以让代理更新任务状态。
接入新服务的过程很简单，在配置里加一条记录，重启代理就行。我建议按需接入，不要一次接太多。每个服务都会占用上下文空间，工具太多反而会让模型选择困难。我一般同时启用不超过五个 MCP 服务。
7.2 自定义工具的编写方法
内置工具不够用时，可以自己写。工具的本质就是一个函数，接收参数返回结果。我的代理在启动时会扫描指定目录下的 Python 文件，把里面符合规范的函数注册成工具。
写自定义工具需要注意几点。函数要有清晰的文档字符串，代理会根据这个生成工具描述。参数要有类型标注，代理会根据这个生成参数 schema。返回值要是可序列化的，通常是字符串或字典。异常要妥善处理，抛出的异常会被代理捕获并作为错误结果处理。
我写过一个自定义工具，用来查询公司内部的 API 文档。实现很简单，就是发 HTTP 请求然后解析返回。但有了这个工具，代理在写代码时就能自动查阅内部 API 的用法，大大提高了准确性。
7.3 多代理协作的可能性
单个代理的能力有上限，复杂任务可以考虑多代理协作。比如一个代理负责规划，一个负责写代码，一个负责测试。它们之间通过消息传递协调。
这个方向我还在探索。初步的想法是让主代理把子任务分发给子代理，子代理完成后把结果返回。子代理可以是同一个程序的不同实例，配置不同的系统提示词来扮演不同角色。这样架构上不需要大改，只是启动多个进程的事。
多代理的挑战在于协调开销。代理之间通信需要时间，如果任务拆分得太细，协调开销可能超过收益。我的经验是只在任务确实复杂、单个代理搞不定时才用多代理，简单任务单代理更高效。
7.4 性能优化的几个方向
目前代理的性能瓶颈主要在模型调用上。每次决策都要调模型，网络延迟加上模型推理时间，一步操作可能要好几秒。优化方向有几个。
一是减少模型调用次数。有些决策其实不需要模型参与，比如连续执行几个已知的命令，可以合并成一次模型调用。我在代码里加了一些启发式规则，能合并的步骤自动合并。
二是缓存模型响应。相同的输入往往得到相同的输出，可以把响应缓存起来。下次遇到相同情况直接读缓存，省去模型调用。这个优化在重复性任务上效果明显。
三是用更小的模型做简单决策。不是所有决策都需要大模型，简单的工具选择用小模型就够了。我在配置里支持为不同类型的决策指定不同的模型，简单决策走小模型，复杂规划走大模型。这样整体速度和成本都能优化。
GUI 操控这块的性能主要受截图和图像分析影响。我的优化是尽量用区域截图代替全屏截图，用控件信息代替图像分析。如果能通过系统接口直接拿到控件的位置和状态，就不需要截图分析，速度快很多。只有在拿不到控件信息时，才退回到截图方案。
这套东西我陆陆续续写了几个月，中间推翻重来过两次。最大的体会是，做工具不要追求功能大而全，要把一两个核心场景做到极致。我这个代理的核心场景就是"自动化处理那些需要 GUI 操作的重复任务"，围绕这个场景把 GUI 操控和 MCP 集成做扎实，比堆一堆用不上的功能有价值得多。
