企业官网建设流程全解析

做个东西的冲动，通常来自一次卡住的时刻。去年我用一款挺主流的 AI 编码助手改项目配置，模型很快就分析出问题、给出了修改方案，但改完后死活没法继续——因为它需要操作的下一步是一个图形弹窗里的按钮，而模型只能改文件，碰不到界面。那一瞬间我意识到，编码代理的真正瓶颈往往不是模型推理，而是它有没有“手”。这也是我后来坚持做这个免费 AI 编码代理的直接原因：它不只写代码，还能直接操控 GUI，同时支持 MCP（Model Context Protocol）接入外部工具，整个项目收敛成一个单文件，拿到任何一台装了 Python 的机器上都能跑。

这个代理本质上是一个把“文件操作 + 桌面操作 + 外部工具调用”统一起来的自治循环：模型看屏幕、看文件、看终端输出，然后决定下一步动作，动完再观察结果。你可以让它“帮我把这个 Markdown 文档转成 PDF 并放到桌面”，也可以让它“打开某个 GUI 软件完成一项重复设置”。免费、单文件、能摸界面、能接 MCP，这四个特性凑在一起，市面上的现成方案里我还没找到一个完全对应的，所以只能自己写了。这篇文章就把我的设计思路、实现细节、踩过的坑以及一套真实演示完整摊开讲，希望能给也在琢磨 AI Agent 落地的人一点参考。

1. 从“只写代码”到“会摸软件”：需求的起点与产品边界

1.1 编码代理的痛点：模型的回答不能替代操作

如果用一句话说清我这个代理和普通 AI 编程助手的差别，那就是：普通助手负责“出主意”，我这个代理还负责“动手”。

典型 AI 编程助手的闭环是“问题 -> 代码 diff”，它产出的是一个补丁，最终改文件、跑测试、看效果的环节还得人来。这没毛病，但现实中软件开发流程有一大堆操作根本不属于“代码修改”范畴：装依赖可能要点安装包界面，调数据库可能要操作图形客户端，看 CI 产物可能要打开一个 GUI 工具验证。这些环节一旦出现，自动化的链条就会断，最终还是要人回到电脑前手动处理。

所以我把产品定位从“编码补全”挪到了“编码代理”。它拥有对代码库的读写能力，也能执行终端命令，但最大的变化是给它加上了视觉和手持能力：截屏、识别界面、移动鼠标、点击、键入。这意味着它可以把过去断掉的环节重新接上，例如下载一个安装包、通过 GUI 向导完成安装、打开编辑器写入配置、再跑一遍命令行验证结果。

1.2 为什么把“GUI 操控”和“MCP”做进同一个代理

更早的时候，GUI 自动化（如 RPA）和 MCP 是两条独立的技术脉络：RPA 强调模拟人的桌面操作，MCP 强调用标准协议把工具能力暴露给大模型。按理说，分开用也行，但实际做代理时你会发现二者根本是互补关系。

GUI 操作适合“没有代码接口、只能人肉点”的场景，但它每一步都慢、容易受界面变动影响；MCP 适合“有明确定义的接口”的场景，效率高、可靠，但前提是对方提供了 MCP server。同一个任务往往两头都要走：从官网下载一个开源编译器，官网可能没有 MCP 接口，得用浏览器 GUI 操作；下完以后要处理的压缩包、安装脚本、环境变量，这些又完全可以走 MCP 的文件系统和命令工具。一个成熟的编码代理，理应在两种模式之间自由切换，所以我在设计的第一天就把 MCP 客户端和支持鼠标键盘的 GUI 执行器并排放进了同一个循环里。

1.3 “免费 + 单文件”作为产品底线的现实原因

为什么不让用户装一个大型框架？因为代理类工具的使用场景太碎片化：你可能在公司电脑上用，也可能在家里的旧笔记本上跑；环境可能是 Windows，也可能是 macOS 或者 Linux；你可能只想临时跑一个小任务，不想为此引入一整套运行时和依赖树。

单文件方案能解决这类碎片化问题。单个.py文件意味着分发简单、审查简单、迁移简单，更重要的是它倒逼我把架构做得清爽——如果一万多行代码连自己都理不清模块边界，那用户更不可能信任它。至于免费，一方面是因为它借用了各家 LLM API 的能力，工具本身没有理由收费；另一方面，我觉得这种“代理骨架”类项目本来就应该是开放的，让大家能检查它在本地到底做了什么，这对一个能操作你桌面的程序来说非常关键。

2. “单文件”的工程取舍：入口、依赖与内部组织方式

2.1 单文件不是把一万行代码堆在一起

很多第一次看到这个项目的人会问：单文件，那代码是不是一大坨没法维护？其实不是。我在文件内部按“区段”组织，用显眼的注释块把不同子系统分隔开，结构大致如下：

# ========== 1. 基础工具：日志、配置、并发 ========== # ========== 2. 感知层：截屏、OCR、图像压缩 ========== # ========== 3. 执行层：键盘鼠标、进程、文件 ========== # ========== 4. 模型层：LLM 调用、提示词编排 ========== # ========== 5. MCP 客户端：JSON-RPC 通信 ========== # ========== 6. 核心循环：感知-决策-执行-观察 ========== # ========== 7. 交互入口：CLI / Web UI ==========

这就像一个人家里没有单独建储藏间，但墙面做了足够的收纳分区，找东西依然很快。实际开发中我还会通过类型注解和 docstring 保证任意一个区段都能独立读懂。单文件在 Python 里还有一个隐藏好处：不会有代码包导入路径的问题，也不会有多个版本同时存在于 site-packages 的混乱。

2.2 依赖策略：轻量引入 + 启动时自检

全部依赖如果都塞进一个文件肯定不现实，所以我选了“最小依赖集合 + 启动时自检”的策略。核心依赖只有四类：多模态模型 SDK（OpenAI/Anthropic 二选一）、截图库（mss）、桌面控制库（pyautogui）、图像处理库（Pillow）。这些加起来不过百来兆，但能力覆盖面已经够了。

启动时我会做一次依赖扫描，缺哪个就打印一条明确的安装指令，而不是抛一个晦涩的 ModuleNotFoundError。比如：

python agent.py --task "打开记事本，输入一段文字" # 自动检查依赖，缺失时提示： # 缺少 pyautogui，请执行：pip install pyautogui

这种方式虽然不如“真正的单文件打包”干净，但比动不动就要用户配一个虚拟环境、装一堆 SDK 再跑 demo 要友好得多。等哪天有空了，我打算用 PyInstaller 把它再收成一个原生可执行文件，那就是彻彻底底的单文件了。

2.3 三种运行模式：对话、任务、服务

单文件并不意味着只有一种入口。我根据实际使用场景把它分成三种运行模式：

第一种是对话模式。直接python agent.py进入 REPL，你可以跟它连续对话，它会反复调用工具、汇报中间结果。适合调试代理行为、逐步尝试新任务。

第二种是任务模式。python agent.py --task "xxx"一条命令结束走人，适合脚本化调用和批处理。任务结束后它会输出一份简短的执行报告，包括“我做了什么、每步调用了什么工具、最终状态如何”。

第三种是服务模式。python agent.py --serve会起一个本地 HTTP 服务，前端是个小页面，可以在浏览器里观察代理的实时截屏和动作串。这个模式对我自己调试 GUI 自动化特别有用，因为我能直接看到它“看见”了什么、下一步打算点哪里。

3. 看着屏幕干活：GUI 操控链路的实现与可靠性设计

3.1 感知层：截图、压缩、视觉模型出结构化动作

GUI 操控的第一步是让模型“看见”屏幕。这里最直接的做法是截全屏，把截图直接送给多模态模型，让它基于图像推理出目标坐标和动作。全屏截图虽然信息完整，但 token 消耗巨大、推理速度很慢。所以我做了三层简化：

第一层，按窗口区域截图。模型需要操作某个应用时，我先通过窗口管理 API 拿到目标窗口的边界框，只截那一块，把无关区域全部剔除。第二层，JPEG 压缩与缩略化。默认把截图缩放到宽度 1280，JPEG 质量压到 60，单张图体积能控制在 200KB 左右，一次推理的视觉 token 成本大约只有原始 PNG 的三分之一到二分之一。第三层，必要时叠加 OCR 文本信息。模型对不规则中文界面元素偶尔会认不准确，我接入了一个本地 OCR 步骤，把界面里的关键文本提取出来，和截图一起送进上下文，让模型“看字 + 看图”双重校验。

模型输出不是自由文本，而是严格 JSON：

{ "reasoning": "窗口标题栏有“下载”按钮，位于屏幕右下角区域", "action": "click", "target": {"x": 1543, "y": 862}, "parameters": {"double_click": false} }

我在提示词里规定：不是所有坐标都需要精确到像素，模型可以先给一个粗略目标，执行层会做“按钮级校正”（比如 OCR 识别出按钮中心点，模型只需说“点这个按钮”）。这样既保留了模型的泛化能力，又减轻了它对坐标的精确记忆负担。

3.2 执行层：从坐标到鼠标键盘的落地方式

执行层相对粗暴，我用 pyautogui 作为主后端，因为它跨平台、API 简单、能覆盖鼠标移动、点击、拖拽、滚轮和键盘输入。但“简单”是有代价的，比如 GUI 缩放（DPI）问题就折腾了我一整天：Windows 下如果系统缩放是 150%，截图里的坐标是物理像素，而 pyautogui 操作的是逻辑坐标，两者存在 1.5 倍的比例偏差。解决办法是启动时读取系统缩放参数，对所有坐标做一次统一映射：

import tkinter as tk root = tk.Tk() scale = root.winfo_fpixels('1i') / 96.0 # Windows DPI 缩放因子 logical_x = physical_x / scale

做完映射之后，点击精度明显提升，误点率降了一大截。不过这同时也说明了一个问题：GUI 自动化上任何一个“想当然”的细节，都会在现场给你上一课。

3.3 可靠性设计：状态对比与二次确认机制

任何做过 GUI 自动化的人都知道，界面自动化的失败从来不是“偶尔失败”，而是“经常莫名失败”。最典型的场景是：模型想点“确定”按钮，但界面上有两个长得差不多的按钮，它认错位置了。单纯的“点一下”并没有自纠能力。

我采取的方案是动作前预判 + 动作后对比。执行完一个动作之后，系统会立刻重新截屏，与动作前画面做对比。如果发现画面完全没变化（说明点击没有命中任何交互元素）或者出现了未预期的弹窗，代理会自动把差异提取出来再交给模型分析：

• 如果画面没变化，它知道“刚才那一步可能没点上”，会微调坐标再试一次；
• 如果出现了意外弹窗，它会先分析弹窗内容，决定是关闭还是继续；
• 连续失败超过两次，它就停下，向你请求指令，而不是自作主张乱试。

另外，我还设计了一个“高代价操作确认”开关：当某个动作的代价较高（例如删除文件、提交代码、安装软件），代理默认不会直接执行，而是先把打算做的事用一句话告诉你，等你确认。这种谨慎对普通文本自动编辑可能多余，但一旦它开始摸你的鼠标和键盘，“确认”就不是可选项，而是必需品。

4. 接入 MCP：把外部工具变成代理的“外挂手脚”

4.1 边写边想：MCP 究竟解决了什么

MCP 全称 Model Context Protocol，最初由 Anthropic 提出并开源，本质上是一套让大模型应用动态发现和调用外部工具的协议。你可以把 MCP 想象成“USB-C 接口”之于外设：以前每个 AI 助手要接一个新工具，都得写一套私有集成；有了 MCP，只要工具提供方按同一个协议提供接口，AI 就能即插即用。

在实际使用中，MCP 给我带来了两个立竿见影的改变。一是打通了工作流：过去“让代理读一个 SQLite 数据库”“让代理搜索本地文件”这类能力都需要我为它单独开发，现在只要配置好对应的 MCP server，它就能自动列出可用工具并发起调用。二是和 GUI 操作形成互补：GUI 负责“打开安装包并勾选选项”，MCP 负责“读配置文件并修改参数”，二者叠加，自动化链条才完整。

4.2 我实现的 MCP 客户端核心逻辑（附代码）

MCP 协议描述起来很高大上，落地其实就是一个基于 JSON-RPC 2.0、通过标准输入输出（stdio）或者 HTTP 传输的通信过程。我没用官方 SDK，直接写了一个轻量客户端，核心只有几十行：

import json, asyncio class MCPClient: def __init__(self): self._id = 0 self.proc = None async def connect(self, command: list[str]): self.proc = await asyncio.create_subprocess_exec( *command, stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, ) await self._request("initialize", { "protocolVersion": "2025-03-26", "capabilities": {} }) async def list_tools(self): return await self._request("tools/list", {}) async def call_tool(self, name: str, arguments: dict): return await self._request("tools/call", { "name": name, "arguments": arguments }) async def _request(self, method: str, params: dict): self._id += 1 payload = { "jsonrpc": "2.0", "id": self._id, "method": method, "params": params } self.proc.stdin.write(json.dumps(payload).encode() + b"\n") await self.proc.stdin.drain() line = await asyncio.wait_for(self.proc.stdout.readline(), timeout=30) return json.loads(line)

核心方法是四个：connect负责拉起子进程并完成初始化握手，list_tools让模型知道这个 server 能做什么，call_tool真正调起工具，_request是公共的 JSON-RPC 收发层。整个过程只依赖 Python 标准库的asyncio，没有引入任何第三方依赖，这在单文件项目里非常关键——少一个依赖，用户部署时就会少一次出错机会。

4.3 接入后的真实效果与选型建议

我在项目里默认配置了三个实用的 MCP server：文件系统服务器（能对指定目录做读写，比 agent 自己拼路径安全）、命令执行服务器（负责跑命令行并回传输出）、以及一个浏览器自动化服务器（负责打开 URL、抓取页面内容）。

这套组合的实际效果是：代理拿到一个“把远端某个配置仓库拉下来并按说明修改”的任务时，可以先通过浏览器 MCP 读取说明页面，再通过命令 MCP 执行 git clone，然后通过文件系统 MCP 精确改动文件，最后还能跑 git diff 给我展示改动差异。全程 GUI 只需要在“确认执行命令”时露面，其余都在文本层面高速完成，效率和稳定性都比纯 GUI 操作高出一个量级。

对想接入 MCP 的开发者，我的建议是：先盘点自己的项目里“有哪些确定性接口”和“有哪些只能靠肉眼识别”的操作，尽量把前者交给 MCP、后者留给 GUI，而不是什么事情都想让模型用鼠标去试。混合调度才是生产力最大化的关键。

5. 实战演示：让代理自己完成一次 GUI 安装流程

5.1 任务的拆解与前置条件

为了展示真实效果，我在一台干净的 Windows 虚拟机上跑了一次完整流程：让代理“下载并安装一个开源 Markdown 编辑器，然后用它打开一个示例文档”。任务难点在于，下载页面、安装向导、界面菜单全都是 GUI，没有任何标准 API 可用，全部依赖视觉识别和鼠标键盘操作。

前置条件如下：

• 已准备好 Python 3.11 + agent.py + 必要的依赖；
• 配置了一个多模态视觉模型 API Key；
• 要求代理每一步操作后都汇报当前界面状态。

这个任务被代理自动拆成了五个子目标：打开浏览器、找到下载链接、触发下载、运行安装向导、启动应用并打开文档。每个子目标内部又会有若干次“截屏 -> 推理 -> 动作 -> 再截屏”的循环。

5.2 逐步推进：从下载到安装完成

第一阶段是打开浏览器并定位下载页。我给了它项目的官网地址，它直接通过“浏览器自动化 MCP”打开了页面。但页面上的下载按钮并不醒目，第一次截屏后模型误把“文档”按钮当作下载入口点了下去，随后通过“动作后画面对比”发现跳到了文档页。它立刻回退，重新截屏并 OCR 了页面上的按钮文字，这次识别到了“Download for Windows”，顺利进入下载页。

第二阶段是等待下载并定位安装包。下载完成之后，代理通过窗口标题变化判断“浏览器下载栏已出现”，然后用文件系统 MCP 扫描Downloads目录，找到新出现的.exe文件。到这里，它执行了一个 GUI 动作：双击该文件。

第三阶段是安装向导流程。安装程序弹出了安全提示窗口，显示“是否允许此应用更改设备”，代理的视觉模型识别到了“是”按钮并点击。随后安装向导出现，界面有“下一步”“选项”“安装”等多层页面。代理的策略是：每屏截一张图，找到最醒目的“下一步”按钮，点击；遇到“安装路径”页面，它没有修改默认路径，直接点“继续”；最后一屏出现“安装”按钮，点击后等待进度条走完。

第四阶段是验收。安装完成后，代理通过“开始菜单搜索”找到刚装的编辑器并启动，之后用“新建文件”选项创建了一个demo.md，写入一段测试文本并保存到桌面。到这里，整个无人值守流程顺利结束，耗时大约 20 分钟。

5.3 这次演示暴露的三个问题

一次完美 Demo 是不可能的，这次的教训很典型：

第一，安装向导的“界面语言”影响了识别准确率。中文安装界面里“为了在计算机上安装，请选择下一步”这类说明文字很长，模型有时会把中间某个链接误认为按钮。后来我在视觉提示词中增加了“只选择窗口最底部通常位于右下方的主操作按钮”的约束，误点率才有了明显下降。

第二，初始截图全屏时，模型会迷失重点。第一次它盯着整个桌面看，找下载按钮时把任务栏上的通知图标都分析了一遍，浪费了很多推理时间。后来我强制要求它“先根据 OCR 文本定位窗口区域，再局部截取”，感知效率提升了差不多两倍。

第三，安装过程不可回滚。安装程序一旦点错，可能会装错目录或者多装组件。虽然代理最后能完成，但过程里它确实有一次多点了“安装可选组件”，导致安装耗时变长。这提醒我，GUI 自动化的“验证”必须前置到动作之前，而不是等到出错了才补救。

6. 真实的边界：免费方案能做的事与踩过的坑

6.1 高频踩坑对照表

我连续迭代了三个月，把遇到的高频问题整理了一张表，希望对打算做类似项目的朋友有点帮助：

6.2 防误操作机制：GUI 代理最需要的一层保险

能做 GUI 自动化的代理，天然拥有比“改文件”高得多的操作权限，因此也必须有更严格的防误操作机制。我的设计里有一套三角色策略：

第一，默认只读。代理刚启动时处于只读模式，可以截屏、可以读文件、可以列目录，但不能修改任何东西。只有当用户显式下发“修改类任务”时，它才获得写权限。

第二，高危险操作二次确认。删除文件、执行系统级命令、安装软件、修改关键配置文件，这类操作默认要求用户确认，即使任务已经下发了，也必须弹出一个确认窗口。

第三，操作日志可审计。每一次 GUI 点击、每一次 MCP 调用、每一次文件写入，都会记录到本地日志。出了任何意外，用户可以立刻回溯到“它当时到底做了什么”。

这套机制一开始被我觉得“太啰嗦”，但实际用了才发现，自动化的价值在于替你干活，而不是替你惹祸，多一层确认反而让整个流程更容易被信任。

6.3 关于后续的一些个人打算

这个项目现在还在持续迭代。我下一步的计划是把 GUI 操作部分做成更原子化的“技能包”：例如“点击黄色高亮按钮”“在输入框键入文本”“滚动到底部”，让模型每次只调用一个原子技能而不是直接输出原始坐标，这样技能的内部实现可以不断优化，而模型不需要跟着学习细节。

最后再分享一个我实际使用中的体会：AI 代理这种工具，最让人上头的时刻不是它一次跑通的时候，而是它第一次犯错然后自己纠正过来的时候。那种感觉不像是在用一个自动化脚本，倒像是在带一个上手很快的新同事。前提是你要给它足够的边界和护栏，并且始终保留“你点头它才动手”的最终控制权。