1. 为什么我要自己造一个 AI 编码代理市面上能写代码的 AI 工具已经多到挑花眼从 IDE 插件到云端 Agent功能一个比一个花哨。但真正用起来总有几个地方让我如鲠在喉。最核心的痛点是绝大多数工具都要求你把代码传到别人的服务器上或者至少得装一堆依赖、配一堆环境变量折腾半天才能跑起来。我平时的工作流里既有本地项目也有需要快速验证的小脚本每次都要重新配置一遍时间全浪费在环境搭建上。另一个让我不爽的地方是这些工具大多只能“读代码、写代码”没法直接操作我电脑上的图形界面。比如我想让 AI 帮我自动填个表单、点个按钮、截个图分析界面状态现有的编码代理基本做不到。它们被困在纯文本的世界里对 GUI 视而不见。而 MCPModel Context Protocol的出现让我看到了转机——它本质上是一套让 AI 模型与外部工具、数据源交互的协议标准相当于给 AI 装上了“手”和“眼睛”。如果我能把 GUI 操控和 MCP 协议都集成到一个单文件运行的代理里那就能覆盖从纯代码任务到界面自动化的完整场景。于是我开始动手做一个完全免费、单文件运行、同时支持 GUI 操控和 MCP 的 AI 编码代理。目标很明确下载一个文件双击就能跑不需要装 Python 环境、不需要 npm install、不需要配置任何 API 密钥之外的东西。它要能理解我的自然语言指令自动调用合适的工具去完成任务无论是修改代码文件、执行终端命令还是操控鼠标键盘、截屏分析界面。这篇文章就是我把整个项目从零到一跑通后的完整记录包括架构设计、核心实现、踩过的坑以及我总结出来的一套实操方法。如果你也受够了臃肿的 AI 工具链想拥有一个真正轻量、可控、能干活儿的编码代理那这篇内容应该能帮你省下不少摸索时间。2. 整体架构设计与技术选型思路2.1 单文件运行的核心约束与取舍“单文件运行”这四个字听起来简单做起来全是坑。它意味着我不能依赖任何外部运行时环境不能要求用户提前安装 Python、Node.js 或者 Java。用户拿到的是一个可执行文件双击就能启动所有依赖都打包在里面。这个约束直接决定了我的技术选型范围。我考虑过几种方案。第一种是用 Go 或 Rust 写核心逻辑编译成静态二进制文件体积小、启动快但 GUI 操控和 MCP 协议相关的库生态相对薄弱很多功能需要自己从头造轮子。第二种是用 Python 写然后用 PyInstaller 打包成单文件。Python 的生态太丰富了GUI 自动化有 pyautogui、pynput截图有 mssMCP 相关的 SDK 也齐全开发效率极高。缺点是打包后的文件体积会比较大启动速度也比原生二进制慢一些但在我可接受的范围内。最终我选了 Python PyInstaller 的方案。原因很简单这个项目的核心价值在于功能集成和易用性而不是极致的性能。Python 能让我用最短的时间把 GUI 操控、MCP 协议、代码编辑、终端执行这些模块串起来而且后续维护和扩展也方便。打包后的单文件大概 40MB 左右对于一个功能完整的 AI 代理来说这个体积完全可以接受。提示PyInstaller 打包时一定要用--onefile模式并且把所有的资源文件比如配置文件模板、图标通过--add-data参数嵌进去。否则运行时会出现找不到文件的错误。2.2 GUI 操控模块的技术实现路径GUI 操控是这个代理区别于普通编码工具的关键能力。我把它拆成了三个子功能屏幕感知、鼠标键盘控制、窗口管理。屏幕感知负责“看”。我用 mss 库来截屏因为它比 PIL 的 ImageGrab 快很多而且支持多显示器。截屏后把图像传给多模态模型进行分析让 AI 理解当前界面上有什么元素、它们的位置在哪里。这里有个细节直接传全屏截图会消耗大量 token而且模型可能抓不住重点。我的做法是先让模型根据任务描述判断需要关注屏幕的哪个区域然后只截取那个区域或者对全屏截图做降采样后再传。实测下来把截图缩放到 1280 宽度以内token 消耗能降低 60% 以上而模型对界面元素的理解准确率几乎不受影响。鼠标键盘控制负责“动”。pyautogui 和 pynput 我都试过最后选了 pynput 做底层控制因为它对键盘事件的模拟更精细支持组合键和长按。pyautogui 的优势是 API 更简洁比如pyautogui.click(x, y)一行就能搞定点击。我把两者结合使用pynput 负责复杂的键盘操作pyautogui 负责鼠标移动和点击。这里有个坑pyautogui 默认的鼠标移动是瞬移有些应用比如游戏或者对鼠标轨迹敏感的设计软件会识别不出来。我加了一个duration参数让鼠标在 0.2 秒内平滑移动到目标位置兼容性就好了很多。窗口管理负责“定位”。我用 pygetwindow 来枚举当前打开的窗口获取它们的标题、位置和大小。这样 AI 就能知道某个应用是否已经打开、窗口在屏幕的哪个位置从而决定是激活已有窗口还是重新启动应用。2.3 MCP 协议集成的关键决策MCP 协议是这套代理的另一个核心。简单来说MCP 定义了一套标准接口让 AI 模型能够发现和调用外部工具。我的代理既是一个 MCP 客户端可以连接其他 MCP 服务器也是一个 MCP 服务器可以把自身的 GUI 操控、代码编辑等能力暴露给其他 AI 应用。作为客户端我需要实现 MCP 的传输层。MCP 支持 stdio 和 HTTPSSE 两种传输方式。stdio 适合本地进程间通信HTTPSSE 适合远程连接。我的代理主要面向本地使用场景所以优先实现了 stdio 传输。当用户配置了一个 MCP 服务器比如某个提供数据库查询能力的服务代理会启动一个子进程通过标准输入输出与它通信发送 JSON-RPC 格式的请求和响应。作为服务器我把代理的核心能力封装成 MCP 工具。比如gui_click、gui_type、gui_screenshot、file_edit、terminal_exec这些工具都按照 MCP 的规范定义了输入参数和输出格式。这样其他支持 MCP 的 AI 应用就能直接调用我的代理来操控 GUI 或编辑文件相当于把我的代理变成了一个能力扩展包。注意MCP 的 JSON-RPC 消息必须严格遵循协议格式尤其是id字段的匹配。我在调试时遇到过因为id类型不一致字符串 vs 数字导致响应被丢弃的问题排查了很久才发现。2.4 模型接入与工具调用的编排逻辑代理的大脑是 LLM。我设计了一个灵活的模型接入层支持 OpenAI 兼容的 API 接口。用户只需要在配置文件里填上 API Base URL、API Key 和模型名称就能接入各种模型服务。这样设计的好处是用户可以根据自己的需求和预算选择模型而不是被绑定在某一个服务商上。工具调用的编排逻辑是整个代理的“神经系统”。当用户输入一个任务描述后代理会把任务、可用的工具列表、以及当前上下文比如当前目录、打开的文件一起发给模型。模型返回的响应可能是直接回答也可能是工具调用请求。如果是工具调用代理会解析请求执行对应的工具函数把结果返回给模型然后模型继续推理直到任务完成或达到最大轮次限制。这里有个关键设计我把工具调用做成了流式处理。模型每返回一个工具调用请求代理就立即执行而不是等模型把所有内容都生成完再批量执行。这样用户能实时看到代理在做什么体验更接近“看着一个人干活”而不是“等一个黑盒出结果”。流式输出还有一个好处是能及时中断。如果代理执行了错误的操作用户可以随时按 CtrlC 终止避免造成更大的影响。3. 核心模块的详细实现与实操要点3.1 屏幕感知与 GUI 元素定位的实操细节屏幕感知模块的入口是一个screenshot函数它接受可选的区域参数返回截图的 base64 编码。我默认使用 mss 的grab方法因为它比ImageGrab.grab快 3 到 5 倍。截屏后我会根据配置的最大宽度对图像进行等比缩放。缩放用的是 PIL 的thumbnail方法它比resize更智能能保持宽高比。import mss import base64 from io import BytesIO from PIL import Image def capture_screen(regionNone, max_width1280): with mss.mss() as sct: if region: monitor {top: region[1], left: region[0], width: region[2], height: region[3]} else: monitor sct.monitors[1] # 主显示器 img sct.grab(monitor) pil_img Image.frombytes(RGB, img.size, img.bgra, raw, BGRX) if pil_img.width max_width: ratio max_width / pil_img.width new_size (max_width, int(pil_img.height * ratio)) pil_img pil_img.resize(new_size, Image.LANCZOS) buffer BytesIO() pil_img.save(buffer, formatPNG, optimizeTrue) return base64.b64encode(buffer.getvalue()).decode()这段代码里有个容易忽略的点Image.frombytes的最后一个参数是BGRX不是RGB。因为 mss 返回的原始数据是 BGRA 格式如果直接按 RGB 解析颜色会完全错乱。我第一次调试时截出来的图全是偏色的排查了半天才发现是这里的问题。元素定位方面我依赖多模态模型的能力。把截图和任务描述一起发给模型让它返回需要点击的元素的坐标。为了提高准确率我会在 prompt 里明确要求模型以 JSON 格式返回坐标并且坐标要基于缩放后的图像尺寸。代理收到坐标后再按缩放比例还原到原始屏幕坐标最后执行点击。实操心得如果模型返回的坐标总是有偏差可以在 prompt 里加入屏幕分辨率和缩放比例的信息让模型自己计算。另外对于小尺寸的 UI 元素比如图标按钮可以在截图时只截取目标区域并放大这样模型能看得更清楚。3.2 鼠标键盘控制的稳定性优化鼠标键盘控制看起来简单但要做得稳定可靠需要注意很多细节。首先是坐标系统。pyautogui 使用的是绝对屏幕坐标原点在左上角。多显示器环境下副显示器的坐标可能是负数或者超出主显示器范围。我的处理方式是先获取所有显示器的布局信息然后根据目标坐标判断它属于哪个显示器再做相应的偏移计算。import pyautogui from pynput.keyboard import Controller as KeyboardController from pynput.keyboard import Key keyboard KeyboardController() def move_and_click(x, y, duration0.2, buttonleft): pyautogui.moveTo(x, y, durationduration) pyautogui.click(buttonbutton) def type_text(text, interval0.02): for char in text: keyboard.type(char) time.sleep(interval) def press_hotkey(*keys): with keyboard.pressed(keys[0]): for key in keys[1:]: keyboard.press(key) keyboard.release(key)type_text函数里的interval参数很关键。如果打字速度太快有些应用尤其是基于 Electron 的应用会丢字符。我实测下来0.02 秒的间隔在大多数场景下都能稳定输入如果目标应用特别卡顿可以调到 0.05 秒。另外输入中文时不能用keyboard.type因为它只支持 ASCII 字符。我的解决方案是先把中文文本复制到剪贴板然后用CtrlV粘贴。剪贴板操作我用的是 pyperclip 库跨平台兼容性很好。热键操作也有坑。pynput 的keyboard.pressed上下文管理器能保证按键正确释放但如果中间抛出异常按键可能会卡住。我加了一层 try-finally 保护确保无论如何都会释放所有按键。这个细节在长时间运行的代理里特别重要否则一次异常就可能导致用户的键盘被“锁住”。3.3 MCP 服务器的搭建与工具注册流程MCP 服务器的实现我用了官方提供的 Python SDK。核心思路是定义一个工具注册表把每个工具的名称、描述、参数 schema 和处理函数注册进去。当客户端发起tools/list请求时服务器返回所有已注册工具的描述当客户端发起tools/call请求时服务器根据工具名称找到对应的处理函数并执行。from mcp.server import Server from mcp.types import Tool, TextContent app Server(ai-coding-agent) app.list_tools() async def list_tools(): return [ Tool( namegui_click, description点击屏幕上的指定坐标, inputSchema{ type: object, properties: { x: {type: integer, description: 横坐标}, y: {type: integer, description: 纵坐标} }, required: [x, y] } ), Tool( namegui_type, description在当前焦点位置输入文本, inputSchema{ type: object, properties: { text: {type: string, description: 要输入的文本} }, required: [text] } ) ] app.call_tool() async def call_tool(name, arguments): if name gui_click: move_and_click(arguments[x], arguments[y]) return [TextContent(typetext, text点击完成)] elif name gui_type: type_text(arguments[text]) return [TextContent(typetext, text输入完成)]工具注册的关键在于inputSchema的定义。这个 schema 遵循 JSON Schema 规范模型会根据它来生成正确的参数。我踩过的坑是schema 里的description一定要写清楚尤其是坐标是绝对坐标还是相对坐标、文本是否支持中文这些细节。模型对描述的理解能力很强描述写得越明确工具调用的准确率越高。MCP 服务器的启动方式我支持两种stdio 和 SSE。stdio 模式下服务器通过标准输入输出与客户端通信适合被其他进程作为子进程启动。SSE 模式下服务器监听一个 HTTP 端口客户端通过 Server-Sent Events 接收消息。我默认用 stdio因为它更简单、更安全不需要处理端口冲突和网络配置。3.4 代码编辑与终端执行的安全边界代码编辑功能我实现得比较克制。代理可以读取文件内容、在指定位置插入或替换文本、创建新文件但不会自动执行任何未经确认的破坏性操作。比如删除文件、覆盖整个文件内容这些操作都需要用户在配置里显式开启或者通过交互式确认。def edit_file(path, old_text, new_text): with open(path, r, encodingutf-8) as f: content f.read() if old_text not in content: return f错误未找到要替换的文本 new_content content.replace(old_text, new_text, 1) with open(path, w, encodingutf-8) as f: f.write(new_content) return f已修改 {path}这个edit_file函数用的是“查找并替换”策略而不是直接覆盖整个文件。这样做的好处是精确、可预测而且如果old_text不存在函数会返回错误而不是静默失败。我在实际使用中发现让模型生成完整的文件内容再覆盖写入很容易因为模型输出截断或格式错误导致文件损坏。查找替换的方式虽然需要模型提供更精确的指令但安全性高得多。终端执行我用的是 subprocess 模块设置了超时限制和输出捕获。默认超时是 30 秒可以通过配置调整。输出会截断到前 5000 个字符避免大量日志把上下文撑爆。这里有个安全考虑代理执行的命令会经过一层过滤禁止rm -rf /、format、shutdown这类高危命令。虽然用户可以在配置里关闭这个过滤但默认开启能防止很多意外。提示如果你打算把这个代理用在生产环境或共享机器上强烈建议保持命令过滤开启并且把终端执行功能限制在特定的工作目录内。4. 从零到一的完整实操流程4.1 环境准备与依赖安装虽然最终产物是单文件但开发阶段还是需要先搭好 Python 环境。我用的 Python 版本是 3.11因为它在性能和兼容性之间平衡得比较好。依赖库主要有这些库名用途版本要求mcpMCP 协议 SDK 1.0.0pyautogui鼠标控制 0.9.54pynput键盘控制 1.7.6mss屏幕截图 9.0.1Pillow图像处理 10.0.0pyperclip剪贴板操作 1.8.2pygetwindow窗口管理 0.0.9openai模型 API 调用 1.0.0pyinstaller打包工具 6.0.0安装命令很简单pip install mcp pyautogui pynput mss Pillow pyperclip pygetwindow openai pyinstaller这里有个细节pyautogui 在 Linux 上依赖 python3-xlib 和 scrot在 macOS 上需要授予辅助功能权限。Windows 上基本开箱即用。如果你在 macOS 上跑第一次运行时会弹出权限请求需要在“系统设置 - 隐私与安全性 - 辅助功能”里手动勾选你的终端或打包后的应用。4.2 配置文件的设计与参数说明代理的配置文件我用的是 JSON 格式放在用户主目录下的.ai-agent/config.json。首次运行时如果文件不存在代理会自动生成一份默认配置。配置项包括模型接入信息、工具开关、安全限制等。{ model: { base_url: https://api.example.com/v1, api_key: your-api-key-here, model_name: gpt-4o, max_tokens: 4096, temperature: 0.1 }, tools: { gui_control: true, file_edit: true, terminal_exec: true, mcp_servers: [] }, safety: { command_filter: true, max_terminal_timeout: 30, allowed_directories: [~/projects, ~/workspace] }, ui: { stream_output: true, screenshot_max_width: 1280 } }temperature我设成了 0.1因为编码任务需要确定性高的输出太高的温度会让模型生成不稳定的代码。max_tokens设成 4096 是为了平衡响应速度和输出长度如果你的任务经常需要生成大段代码可以调到 8192。allowed_directories限制了文件编辑和终端执行的工作目录范围防止代理意外修改系统文件。4.3 启动代理并执行第一个任务配置好之后启动代理只需要一行命令python agent.py或者如果你已经打包好了./ai-agent启动后代理会进入交互式命令行界面提示你输入任务描述。我第一次测试用的任务很简单“在当前目录创建一个 hello.py内容是一个打印 Hello World 的程序然后运行它”。代理的执行过程是这样的首先模型分析任务决定需要调用file_edit工具创建文件。代理执行文件创建返回结果给模型。模型确认文件创建成功后决定调用terminal_exec工具运行python hello.py。代理执行命令捕获输出Hello World返回给模型。模型确认任务完成输出最终结果。整个过程我用了大概 8 秒其中模型推理占了大部分时间。代理本身的工具执行几乎瞬间完成。这个响应速度在日常使用中完全可以接受。4.4 打包成单文件可执行程序开发调试完成后用 PyInstaller 打包pyinstaller --onefile --name ai-agent \ --add-data config_template.json:. \ --hidden-import pynput.keyboard._win32 \ --hidden-import pynput.mouse._win32 \ agent.py--hidden-import参数很关键。pynput 在运行时会动态导入平台相关的模块PyInstaller 的静态分析发现不了必须手动指定。Windows 上用_win32macOS 上用_darwinLinux 上用_xorg。如果不加这个参数打包后的程序在运行时会报ModuleNotFoundError。打包完成后dist/目录下会生成一个ai-agent.exeWindows或ai-agentmacOS/Linux。把这个文件复制到任何地方双击就能运行。配置文件会在首次运行时自动生成用户只需要填入 API Key 就能开始使用。实操心得打包后的文件体积如果超过 50MB可以用 UPX 压缩。PyInstaller 支持--upx-dir参数指定 UPX 路径压缩后体积通常能减少 30% 到 40%。不过 UPX 压缩有时会触发杀毒软件的误报如果分发给你不熟悉的人建议先不压缩或者提前说明。5. 常见问题与排查技巧实录5.1 模型不调用工具或调用错误工具怎么办这是最常见的问题。模型可能直接回答“我无法操作 GUI”而不是调用gui_click工具。原因通常是工具描述不够清晰或者系统提示词没有强调工具的存在。我的解决方法是优化系统提示词明确告诉模型“你拥有操控 GUI、编辑文件、执行终端命令的能力。当任务需要这些操作时必须调用对应的工具而不是仅给出文字建议。”同时在工具描述里加入使用示例比如gui_click的描述里写上“例如点击坐标 (100, 200) 的按钮”。如果模型调用了错误的工具比如该用file_edit却用了terminal_exec可以在工具描述里加入排除性说明“此工具仅用于编辑文件内容不用于执行命令。”实测下来描述越具体模型的工具选择准确率越高。5.2 GUI 操控失效的典型场景与修复GUI 操控失效通常有几种表现点击没反应、输入乱码、截图黑屏。点击没反应最常见的原因是坐标计算错误。如果你用的是多显示器或者系统缩放不是 100%坐标就需要额外转换。Windows 上可以在“显示设置”里查看缩放比例然后在代码里做相应的乘除运算。macOS 的 Retina 屏幕也有类似问题逻辑坐标和物理坐标是两套体系。输入乱码通常发生在中文输入场景。前面提到过keyboard.type不支持非 ASCII 字符。解决方案是用剪贴板粘贴代替直接输入。如果目标应用不支持粘贴可以尝试用pyperclip.copy配合CtrlShiftV某些终端支持。截图黑屏一般是因为权限问题。macOS 上需要在“屏幕录制”权限里勾选你的应用。Windows 上如果用了独占全屏的应用比如某些游戏mss 可能截不到内容可以尝试改用ImageGrab或者让应用窗口化运行。5.3 MCP 连接失败的排查清单MCP 连接失败时按以下顺序排查排查项检查方法常见问题服务器进程是否启动查看进程列表命令路径错误、依赖缺失传输方式是否匹配检查客户端和服务器配置一方用 stdio另一方用 SSEJSON-RPC 格式是否正确抓包或打印日志id 类型不一致、缺少必要字段工具名称是否一致对比 tools/list 返回结果大小写不匹配、拼写错误权限是否足够检查文件和网络权限沙箱限制、防火墙拦截我遇到最多的问题是 stdio 模式下服务器进程的输出被缓冲了导致客户端收不到响应。解决方法是在服务器代码里加上sys.stdout.flush()或者启动 Python 时加-u参数强制不缓冲。5.4 性能优化与资源占用的平衡代理运行时的资源占用主要来自三个方面截图、模型推理、工具执行。截图是最容易优化的降低截图频率、缩小截图尺寸、只在必要时截图都能显著减少 CPU 和内存占用。模型推理的耗时取决于你用的模型服务本地模型和云端 API 的延迟差异很大。工具执行本身很快但如果终端命令执行时间过长会阻塞整个流程。我的优化策略是截图默认只截取活动窗口而不是全屏模型调用设置 60 秒超时超时后自动重试一次终端命令设置 30 秒超时超时后强制终止并返回错误信息。这些参数都可以在配置文件里调整你可以根据自己的硬件和网络情况做取舍。注意如果你在笔记本电脑上运行代理长时间截图和模型调用会明显增加耗电。建议在插电状态下使用或者把截图频率调低。6. 我在这套代理上踩过的坑和总结的经验做这个代理的过程中我踩的坑比预想的多得多。最开始我以为最难的是 GUI 操控毕竟涉及图像识别和坐标计算。但实际做下来最耗时间的反而是 MCP 协议的调试和单文件打包的兼容性处理。MCP 的文档虽然齐全但示例代码大多是基于特定版本的 SDK版本更新后 API 有变化照着抄经常跑不起来。我的建议是直接看 SDK 的源码和类型定义比看文档更靠谱。单文件打包的坑主要集中在动态导入和资源路径上。PyInstaller 打包后的程序运行时工作目录和开发时不一样所有相对路径都会失效。我的做法是统一用sys._MEIPASS来定位打包后的资源目录这个属性在 PyInstaller 打包的程序里指向临时解压目录。另外pynput 和 pyautogui 都有平台相关的动态导入必须手动指定--hidden-import否则打包后的程序在运行时才会报错开发阶段完全发现不了。还有一个让我印象深刻的教训是不要过度依赖模型的单次输出。我最初的设计是让模型一次性生成完整的操作序列然后代理按顺序执行。但模型经常会漏掉步骤或者生成错误的参数导致执行到一半就卡住了。后来我改成了“推理-执行-观察”的循环模式模型每执行一步就观察结果再决定下一步做什么。虽然这样会增加模型调用次数但任务成功率从不到 50% 提升到了 85% 以上。这个改动让我意识到AI 代理的可靠性不取决于单次推理有多强而取决于它能否根据反馈及时调整。最后分享一个实用技巧给代理加一个“回放”功能。代理会把每一步的操作和结果记录到日志文件里如果任务失败了你可以查看日志找到出错的那一步然后手动修正后从中间继续执行而不需要从头再来。这个功能在我调试复杂任务时节省了大量时间也让我更容易理解模型为什么会做出某些决策。