企业官网建设流程全解析

1. 项目缘起：为什么编码代理得"看得见屏幕"

1.1 终端型代理的盲区

先说结论：我最近搞了个免费开源的 AI 编码代理（coding agent），核心卖点是三件事——能直接操控图形界面（GUI）、原生支持 MCP（Model Context Protocol）协议、整个项目打包成单文件运行。

为什么要做这么个东西？因为传统编码代理有个很尴尬的盲区。市面上主流的 coding agent，工作方式基本都是在终端里跑命令、读写文件、执行测试。这套模式对后台任务确实够用，比如让我重构代码、修 linter 报错、补单元测试，都能干得有声有色。可一旦任务需要"看一眼界面"，它就彻底抓瞎了。举个我真实遇到的场景：我让某个开源的 agent 帮我在一个桌面软件里完成设置向导，结果对话框明明弹出来了，"下一步"按钮就在屏幕上，它却只能干瞪眼，因为它根本不知道屏幕上发生了什么，也没办法移动鼠标去点击。

这就很离谱。人类操作电脑的方式明明是"眼睛看屏幕、手点鼠标键盘"，为什么模型反而要绕开这条路，去走一条看不见的下水道？

1.2 回归人类操作电脑的本质

我花了很多时间想这个问题。本质上，人类操作电脑就是一个闭环：观察（看屏幕）→ 判断（理解当前状态）→ 操作（点击/输入）→ 再观察（确认结果有没有生效）。我决定让编码代理也走这条路，给它装上"眼睛"和"手"。

所谓眼睛，就是屏幕截图能力；所谓手，就是跨平台的鼠标键盘控制能力。模型的推理链路会变成：截一张图作为视觉输入，结合用户的任务描述决定下一步做什么，执行一次鼠标或键盘操作，然后再截一张图确认结果。如果结果不对就继续调整，直到任务完成。

听起来简单，但真做起来要解决一堆底层问题：截图和鼠标坐标怎么统一？窗口缩放和 DPI 变化怎么处理？OCR 识别定位怎么做？模型输出坐标后要不要安全校验？这些问题我在后面会逐个拆开讲。

1.3 为什么还要接 MCP

只解决"看得见屏幕、点得了鼠标"还不够。真正的编码工作流里，模型还得读代码仓库、查数据库、操作浏览器、跑测试框架。如果每个能力都自己造轮子，工程量巨大，而且每接一个新工具都要重新写适配，怕是写完天都亮了。

MCP（Model Context Protocol，模型上下文协议）就是来填这个坑的。它是一套开放标准协议，定义了模型如何以统一格式"发现"外部工具、"调用"外部工具、获取结果。简单说，MCP 相当于给模型装了一个"通用插座"，任何工具只要实现了 MCP 服务器端，模型就能直接插上使用，不用关心对方内部是怎么实现的。

所以这个项目的最终形态是"双引擎"架构：一个引擎负责 GUI 操控，另一个引擎负责 MCP 工具调用。两者既能独立作战，也能互相配合。比如先用 MCP 查数据库拿到用户信息，再打开 GUI 把数据填充到表单里并点击提交，整个链路非常自然。

2. 核心设计拆解：GUI 操控与 MCP 双引擎

2.1 GUI 操控模块的三个核心环节

GUI 自动化绕不开三件事：截图、定位、输入模拟。每个环节都有不少坑，我一个个说。

截图层面，我优先用系统级 API 而不是单一第三方库。原因很简单：很多第三方截图库在高分屏、多显示器、混合缩放的环境下会翻车，截出来的图跟真实屏幕尺寸对不上，后面坐标全错位。我的做法是跨平台分开处理——Windows 上走 Win32 的屏幕捕获接口，macOS 上走系统自带的截屏命令行，Linux 上走 X11 或 Wayland 对应的截屏工具。截完图统一转成标准格式喂给视觉模型。这样做的代价是代码里多了一层平台判断，但换来的是坐标系的稳定，这笔账非常划算。

定位层面，我做了三层递进策略。第一层是模板匹配，适合找图标、logo、固定形状的按钮，特征越明显越准。第二层是 OCR 文字定位，专治"确定""取消""下一步"这类文字按钮，先用 OCR 把文字位置提取出来，再映射到屏幕坐标。第三层是把整张截图直接交给多模态大模型，由模型理解图像内容后给出目标控件的坐标预测。三层策略按顺序尝试，绝大多数交互场景都能覆盖。如果三层都找不到目标，代理就会如实上报"无法定位"，而不是瞎猜一个坐标去点。

输入模拟层面，我封装了鼠标移动、点击、双击、拖拽、滚轮、键盘输入、快捷键这几种基础操作，并且统一遵循一个原则：先移动到目标坐标，再执行动作。所有操作在执行前都会过一道安全校验，坐标超出屏幕边界或者目标窗口未激活，直接拦截并报告。

这里必须强调安全设计。自动操作 GUI 的工具最怕失控，所以在默认配置下，代理每执行一次鼠标点击或按键，终端都会实时打印类似[ACTION] click(1200, 340)这样的日志，用户可以一键暂停、终止或者手动接管。我甚至把"高影响操作"单独拎出来做二次确认——比如执行系统命令、点击支付类按钮、删除文件之前，必须用户手动按确认键。宁可慢一点，不能失控。

2.2 MCP 集成的两种工作模式

MCP 协议本身不复杂，核心就是三部分：工具声明（描述这个工具是干什么的、需要什么参数）、调用请求（模型发出 JSON-RPC 格式的调用指令）、结果返回（工具把执行结果送回模型）。

我实现了两种模式。第一种是作为 MCP client，去连接现成的 MCP 服务器。这里有一些现成的选择：文件系统服务器、浏览器自动化服务器、数据库查询服务器、甚至 Figma 设计工具服务器。第二种是反过来，让我的代理自己作为一个 MCP server 暴露能力，这样其他支持 MCP 的开发工具也能反向调用这个代理的 GUI 操控能力。等于说，它既会用别人的工具，也能被别的模型用。

配置文件长这样：

{ "mcp_servers": { "filesystem": { "command": "mcp-server-fs", "args": ["--root", "./workspace"] }, "browser": { "command": "mcp-server-puppeteer" } }, "model": { "endpoint": "http://localhost:11434", "name": "qwen2.5-vl:7b" } }

注意看model这一段。我特意把模型端点设计成可配置的，不绑定任何一家服务商。本地部署的开源模型能用，云端商业模型的 API 也能用，只要模型具备工具调用能力（或者具备视觉理解能力），就能接入。这个设计非常实用，因为不同用户对"模型跑在哪、数据传去哪"的敏感度完全不同。

2.3 单文件运行背后的取舍

"单文件运行"这个需求，做起来远比听起来麻烦，但我依然坚持这么做。

技术实现上，Python 场景我用 zipapp 把所有模块和静态资源打包进一个自包含文件，外层加一个启动桩，运行时就地解包到临时目录。依赖处理是另一个关键点：GUI 控制和图像处理涉及的底层库不少，但全都打进包内，用户不用先手动装 Python 包。配置不硬编码，支持命令行参数覆盖模型端点、工作目录、权限开关等，这样单文件只是个"壳"，实际行为完全可控。

为什么这么执着于单文件？因为真实分发场景里，绝大多数人根本没耐心为了跑个工具先折腾半小时环境。一个文件拿过去，双击或一条命令就能用，出问题也能快速反馈。团队内部协作时，单文件方便传阅，版本号清晰，不会出现"我这边的依赖和你那边不一样"这种经典扯皮问题。代价也不是没有：打包体积会变大，首次启动稍慢，但这些跟"开箱即用"带来的便利相比，完全值得。

3. 上手实操：从拿到文件到跑通第一个任务

3.1 环境准备与启动细节

先讲最简运行条件：需要一台能跑 Python 3.10 以上的机器（Windows 10、macOS 12、Ubuntu 22.04 我都实测过），以及一个有 API 权限的大模型服务。GUI 操控功能在带桌面环境的系统上才有效，无头的纯服务器环境请直接用 MCP 模式。

下载那个单文件后，给它可执行权限，然后这样启动：

./ai-agent --config agent.json

启动日志会分成三段：初始化模型连接、加载 MCP 服务器、启用 GUI 控制模块。每一段都有明确的状态输出，任何一步失败都会给出清晰原因，不会让你在那瞎猜。

我个人强烈建议第一次跑的时候加一个--dry-run参数（模拟运行），让代理把"将要执行的操作序列"完整打印出来，但不真正落库、不真正点击。这相当于预演一遍，可以在真实操作之前先看看模型的计划是否合理，也方便排查配置错误。我实测下来，这一步能省掉至少一半的调试时间。

3.2 写一个最简单的验证任务

我习惯用一个"打文件并打开"的任务来测试环境：让代理在指定目录新建一个 Markdown 文件，写入一段摘要，然后用系统默认编辑器打开。这个任务能同时验证文件操作、GUI 启动能力、以及任务拆解能力，链路短、容易判断成败。

任务描述可以这样写：

在 /tmp/demo 目录下创建 welcome.md，内容是 50 字左右的自我介绍， 写完后用系统默认的文本编辑器打开它。

代理接到任务后，先通过文件系统 MCP 创建文件并写入内容，再用 GUI 模块模拟调起系统"打开方式"逻辑。整个过程大约二三十秒，日志里每步都很清楚。跑完如果文件真实存在、编辑器真的弹出来了，说明环境没问题，可以开始尝试更复杂的任务了。

3.3 验证任务结果的三层检查

任务跑完之后，别急着庆祝。我建议分三层验证：第一层看代理自己的总结日志——它认为自己干了什么；第二层看实际产出——文件系统里是不是真的有对应的内容；第三层看操作记录——GUI 操作日志里是不是真的有打开编辑器的那条动作记录。

三层都对得上，才算真正跑通。这个"多信道验证"的习惯在自动化场景里极度重要。不要只信模型嘴上说"我完成了"，要以客观状态为准。如果有某层对不上，大概率是代理的"自我认知"和"真实状态"出现了偏差，这种偏差在复杂任务里会被无限放大，尽早发现比事后补救强得多。

4. 实操案例：让代理走完一个完整的安装向导

4.1 选定一个现实中典型的测试场景

为了写这篇分享，我特意找了一个最适合测试 GUI 操控能力的场景：用代理去操作某个开源软件的安装向导。这个向导一共三步：选择语言、选择安装目录、确认安装，最后弹出"安装完成"的提示窗口。界面元素全部是图标加文字按钮，位置固定，没有复杂的拖拽操作，非常适合验证视觉识别和鼠标点击的配合。

更关键的细节是，安装向导这类窗口会屏蔽外部输入（模态对话框），而且"下一步"按钮会在条件不满足时置灰禁用。这些恰恰是 GUI 自动化最容易翻车的地方。

4.2 逐步拆解执行过程

第一步，向导首页加载后，我给代理发指令："读取当前界面，告诉我下一步应该点击哪个位置。"代理先截一张图，OCR 定位到"Next"按钮，返回坐标（大约在窗口右下角区域）。这里有个容易踩坑的地方：OCR 返回的是文字在图像像素坐标系里的位置，必须换算成屏幕绝对坐标才能驱动鼠标。换算公式是屏幕坐标 = 图像坐标 × (屏幕宽度 / 图像宽度)，同时要处理 DPI 缩放，否则点击位置会整体偏移。

第二步，进入安装目录选择界面，代理需要输入自定义路径。它先点击"Browse"按钮打开目录选择对话框，这一步靠模板匹配定位文件夹图标，然后通过键盘输入完整路径并回车。这里我遇到过一次大坑：某些系统的目录选择对话框不会自动聚焦输入框，代理直接输入路径就会输到莫名其妙的地方去。解决办法是先点击一下地址栏输入框，再输入路径，最后回车确认。这个"先聚焦再输入"的习惯，在 GUI 自动化里永远不过时。

第三步，点击"Install"进入安装过程。代理采用轮询策略：每 5 秒截一张图，检测屏幕上是否出现"安装完成"字样。轮询过程中它发现"Next"按钮一度处于置灰状态，没有硬点，而是继续等待进度条走完。这个判断力我觉得是区分"能用"和"好用"的分水岭——很多粗糙的自动化脚本碰到按钮禁用就会反复重试最后卡死，而视觉上下文感知让代理明白"现在不是点击时机"。

4.3 运行结果与效率优化的思考

整个流程执行完，安装目录里出现了预期文件，完成窗口也正常弹出。我统计了一下运行数据：代理一共执行了 10 次鼠标点击、5 次键盘输入、40 多次截图，每一步都有日志记录。如果手动操作，这个向导大概只要 1 分钟，代理花了 3 分钟——多出来的时间基本都耗在"截图→思考→执行"的循环上。

改进空间也很明确。比如等待进度条这个场景，固定间隔轮询截图太费资源，完全可以改成"视觉变化检测 + 定时轮询"双触发机制，平时休眠，检测到屏幕像素发生明显变化再醒过来识别，效率能提升一大截。这种优化思路在长时间运行的自动化任务里尤为重要。

5. 踩坑记录与排查手册

5.1 高频问题速查表

我把实操中踩过的问题、原因、解法整理成一张表，覆盖了最常见的几类情况：

5.2 三个花钱买来的经验

第一个经验是坐标系必须全局统一。截图、图像识别、鼠标控制这三层如果各玩各的坐标系，结果必然错位得离谱。我的方案是全局只用"屏幕绝对坐标"一种语言：截图时记录原始分辨率和缩放比例，识别时把所有图像坐标统一换算回绝对坐标，所有函数接受同一套坐标参数。任何偷偷摸摸的分歧，都会在未来某个深夜变成一场灾难。

第二个经验是窗口焦点问题。大量自动化脚本的点击失效，根本不是坐标算错了，而是目标窗口压根不在前台。操作系统只把键盘事件分发给当前激活窗口，鼠标点击虽然能落在任意坐标上，但弹出的菜单、对话框会优先响应焦点窗口。所以我的操作序列永远以"激活目标窗口"开头，这个前置步骤省掉的话，后面整个执行链都是空中楼阁。

第三个经验是安全边界必须前置设计。自动操作 GUI 的工具一旦被滥用，后果可能非常严重。我在代码里加了两道锁：一是应用白名单，模型只能操控预先授权的应用，启动时通过参数传入；二是实时确认机制，高影响操作（执行命令、点击敏感按钮、删除文件）必须经过用户手动确认。这套机制在开发和测试阶段确实增加了操作成本，但换来的是我可以放心地让它在真实环境里长期运行。

6. 一点个人经验总结

做完这个项目，我最大的感受是：把 GUI 操控和 MCP 装进同一个编码代理里，其实是在填一个长期被忽略的洞——"改代码"和"验证界面"之间的断层。以前模型改完代码，人还得手动去界面上验证效果，现在代理可以自己启动应用、点击菜单、观察界面反馈，整个开发闭环在原来自动化的基础上往前推了一大步。

作为最后的建议，我想说的是：如果你准备试用这类工具，先在低风险任务上跑熟。自动填表、自动打包、自动化 UI 回归测试，都是非常好的切入点。等你对代理的行为模式有了足够的把握，再逐步放开更高权限的操作。我见过不少人一上来就交给代理最高权限，然后被它的一次误操作搞得焦头烂额。工具越强大，你越需要在系统层面预留暂停键、日志开关和操作审计。这不只是工程素养，更是对"自动执行"这件事保持敬畏的基本觉悟。