企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 大模型
• 工具调用
• RAG
• 提示工程
• 强化学习

本篇指南聚焦 openJiuwen agent-core 仓库中examples/mobile_gui提供的移动端 GUI Agent 示例：它以 uiautomator2 驱动 Android 模拟器或真机，并由**具备视觉能力的多模态 LLM（VLM）**根据截图进行坐标 grounding 来执行点击、滑动、输入等操作。读完本文你将掌握三条完整可运行的实战路径——单 Agent 直驱、带技能发现（skill discovery）的增强版、以及 Coordinator 协调多子 Agent 的编排版，并能从源码层面理解 VLM 感知、坐标归一化与多模态技能咨询的底层实现。

1. 示例总览：三条可运行的脚本路径

examples/mobile_gui目录下提供了三个脚本，覆盖从"单 Agent 直连设备"到"多子 Agent 协作"的三种玩法：

三个脚本共享同一个核心入口函数create_mobile_gui_agent（定义于 openjiuwen/harness/subagents/mobile_gui_agent.py）。从源码可以看到，该工厂方法会：

• 构建默认的 VLM grounding 系统提示词（build_vlm_grounding_system_prompt）；
• 通过build_mobile_gui_tool_instances注入坐标操作工具与导航工具；
• 通过build_mobile_gui_rails注入设备生命周期、截图感知、上下文摘要、目标锚定、技能咨询等一系列 rails；
• 若未显式传入ContextEngineConfig，则基于运行时设置自动生成上下文引擎配置（MOBILE_CONTEXT_MAX_MESSAGES/MOBILE_CONTEXT_WINDOW_ROUNDS分别对应max_context_message_num与default_window_round_num）。

以下所有命令均假设当前工作目录位于仓库根目录。

2. 从零搭建环境：Android Studio 与模拟器

2.1 安装 Android Studio 并准备 SDK

1. 下载并安装 Android Studio（支持 Windows、macOS、Linux）。

2. 打开Android Studio → More Actions → SDK Manager（或Settings → Languages & Frameworks → Android SDK），安装：

   • Android SDK Platform（建议较新的 API level，如 API 34 或 35）；
   • Android SDK Platform-Tools（其中包含adb）。

3. 将adb加入PATH，使终端可直接执行adb：

   • Windows（常见路径）："%LOCALAPPDATA%\Android\Sdk\platform-tools"（以 SDK Manager 中显示的Android SDK Location为准。）
   • macOS/Linux（常见路径）：$HOME/Android/Sdk/platform-tools

4. 创建虚拟设备：Device Manager（AVD Manager）→Create device→ 选择手机机型 → 选择系统镜像（如 Google APIs / x86_64 或 arm64）→ 完成创建。

5. 启动模拟器，等待其完全启动进入主屏幕。

6. 确认adb能识别设备：

   adb devices

   输出中应看到类似emulator-5554 device的行。示例脚本默认使用 serialemulator-5554；如果你的设备 serial 不同，请设置DEVICE_SERIAL（见共享环境变量一节）。

2.2 使用真机（可选）

在真机上运行需要：开启开发者选项与USB 调试，通过 USB（或无线调试）连接手机，接受 RSA 授权弹窗，然后用adb devices确认 serial 并通过DEVICE_SERIAL指定。

3. Python 环境与依赖安装

需要Python 3，以及本仓库的mobile-gui可选依赖（安装uiautomator2与Pillow）。依赖声明可见 pyproject.toml：

mobile-gui = [ "uiautomator2>=3.2.0", "pillow>=10.0.0", ]

使用uv（推荐，配合项目锁文件）：

uv sync --extra mobile-gui

使用pip（仓库根目录下）：

pip install -e ".[mobile-gui]"

如果连接新模拟器/真机时首次连接失败，出现 uiautomator2/atx-agent 相关报错，可先确保设备在线且adb devices可见，然后执行：

python -m uiautomator2 init

（每个环境执行一次即可；模拟器被重置后需重新执行。）

值得说明的是，示例脚本在启动时也会做依赖自检：example_utils.py中的ensure_mobile_gui_deps()会检查uiautomator2与PIL是否可导入，缺失时打印安装提示并退出（exit code 1）。此外load_example_env()会按"从最不具体到最具体"的顺序加载.env：仓库根.env→ 旧版examples/.env→examples/mobile_gui/.env（后者优先级最高），这保证了多级配置的兼容。

4. 配置多模态 LLM（examples/mobile_gui/.env）

环境变量由 example_utils.load_example_env 加载。创建examples/mobile_gui/.env（复制 .env.example），至少需要填写：

注：example_utils.build_chat_model()实际读取的是API_KEY/LLM_API_KEY、MODEL_NAME/LLM_MODEL_NAME、API_BASE/LLM_API_BASE、MODEL_PROVIDER/LLM_PROVIDER这类别名组合，并支持LLM_SSL_VERIFY控制 SSL 校验（取值1/true/yes表示开启）。进程在LLM_API_KEY未设置时会提前退出并给出提示。

完整的.env.example还提供了大量进阶调优项，本文后续章节会结合源码逐项讲解，例如：

# --- LLM --- LLM_PROVIDER=OpenAI LLM_API_KEY= LLM_API_BASE=https://api.openai.com/v1 LLM_MODEL_NAME=gpt-4.1-mini LLM_SSL_VERIFY=false # --- Device & task --- DEVICE_SERIAL=emulator-5554 # MOBILE_TASK=Open Chrome and search for weather in Singapore. # --- Agent loop --- MAX_ITERATIONS=30 AGENT_TEMPERATURE=0.7

5. 运行基础版：run_mobile_gui_agent.py

在仓库根目录执行：

uv run python examples/mobile_gui/run_mobile_gui_agent.py

若依赖已安装完成：

python examples/mobile_gui/run_mobile_gui_agent.py

该脚本的逻辑非常直接（对应源码 run_mobile_gui_agent.py）：

1. bootstrap_runtime()：注入导入路径、截断 stdout/stderr 中过长的 base64 截图（_TruncatingStream），加载环境变量并做依赖自检；
2. build_chat_model()构建多模态模型；
3. 创建临时工作区（tempfile.TemporaryDirectory(prefix="mobile-gui-ws-")）；
4. 调用create_mobile_gui_agent(...)创建 DeepAgent，其中max_iterations取自环境变量MAX_ITERATIONS（默认 30）；
5. 通过Runner.run_agent执行一轮对话并输出结果。

默认任务（default_task()，可用MOBILE_TASK覆盖）为：

Find the number of stars and forks for https://github.com/openJiuwen-ai/agent-core.

也就是说，开箱即用它会驱动模拟器里的浏览器打开该仓库页面并汇报 star/fork 数量——这正是对"移动 GUI Agent"能力的一个直观演示。

5.1 底层工具集：坐标操作 + 导航

create_mobile_gui_agent注入的工具由 runtime_tools.py 汇总，分为两组：

坐标操作工具（coordinate_action_tools.py）：

导航工具（navigation_tools.py）：

5.2 坐标归一化的关键设计

从 coordinate_utils.py 可以看出一个值得留意的工程细节：工具参数使用归一化坐标而非物理像素。

• 默认坐标系为[0, 1000] × [0, 1000]（由VLM_COORDINATE_SCALE控制，见 config.py），原点在左上角；
• 执行手势时通过normalized_to_pixel依据截图元数据（vlm_screen_width、vlm_screen_height、vlm_coordinate_scale_x/y）换算为真实像素，并做越界裁剪；
• 源码还内置了unwrap_xy_coords容错逻辑：当模型错误地把[x, y]打包进单个字段时自动拆包，避免手势失败。

这一设计让坐标与屏幕物理分辨率解耦，同一套模型输出可以适配不同分辨率的设备。

5.3 Rails：每次模型调用前的"感知管线"

VLM grounding 的核心不是工具本身，而是 rails_factory.py 注入的 6 条 rails：

1. DeviceLifecycleRail（device_lifecycle_rail.py，priority 95）：在 invoke 边界注入 uiautomator2 设备句柄，启动时做健康检查，结束后回到 Home 屏；
2. VlmGroundingPerceptionRail（priority 90）：在每次模型调用前抓取屏幕截图，做尺寸适配（限制最大宽度VLM_GROUNDING_MAX_WIDTH，默认 1280）、JPEG 压缩（VLM_GROUNDING_JPEG_QUALITY，默认 85）与 base64 编码，以image_url多模态消息注入对话，同时附带坐标轴范围说明与前台 App 名。它还根据模型名自适应调整发送给模型的图像尺寸与坐标系（例如 Claude 系列固定尺寸、Opus-4 自适应缩放、Kimi-K 使用单位坐标），并实现目标锚定（GoalAnchorInjectorRail补充[Task Goal]消息，防止长对话中遗忘原始任务）；
3. MultimodalContextSummarizerRail：控制保留最近 N 张截图（MCS_SCREENSHOTS_TO_KEEP，默认 3）；
4. GoalAnchorInjectorRail：注入/回收任务目标锚定消息；
5. MultimodalSkillBranchRail：技能咨询的 branch 模式实现（侧分支运行技能推理，不影响主对话）；
6. MultimodalSkillReadRail：将技能中的![]()图片转换为真实的多模态消息并添加"这是技能参考图，并非当前屏幕"的防误导提示。

6. 运行技能版：run_mobile_gui_agent_with_skills.py

该脚本与基础版唯一区别在于开启技能发现并把examples/mobile_gui/skills/下的内置技能播种到临时工作区的skills/目录。适用场景：任务需要遵循某个捆绑技能（如 GitHub 信息检索或日程/闹钟流程）。

uv run python examples/mobile_gui/run_mobile_gui_agent_with_skills.py

从源码（run_mobile_gui_agent_with_skills.py）可以看到，seed_workspace_skills()会把两个技能目录完整复制到<workspace>/skills/：

• scheduling（日历 + 时钟联动技能）；
• github-com（移动端 Chrome 浏览 github.com 的技能）。

创建 Agent 时传入enable_skill_discovery=True。这两个技能都是多模态技能，其SKILL.md中内嵌了大量真实操作截图，例如：

• scheduling/SKILL.md：定义"会议前 N 分钟设闹钟"（Workflow A）、"查询会议时间"（Workflow B）、"定点闹钟"（Workflow C）、"Timer vs Alarm 语义区分"（Workflow D）等完整 GUI 操作流程；
• github-com/SKILL.md：定义移动端仓库信息检索（文件列表、README、贡献者、语言、Release、star/fork 数）以及切换到Desktop site 模式获取更丰富元数据的方法。

技能中的截图由MultimodalSkillReadRail解析为带data:image/...;base64的多模态用户消息注入模型，同时给出REFERENCE_IMAGE_NOTE强调"示例截图仅作参考，不代表当前设备屏幕，切勿据此推断坐标"。这一防误判机制是移动 GUI 技能与普通文本技能的关键差异。

7. 运行子 Agent 版：run_mobile_gui_subagent.py

该脚本运行一个父级 DeepAgent（Coordinator），可向browser、code、mobile GUI三个子 Agent 委派任务。协调者自己处理简单请求（直接回答、澄清或制定计划），当某个子 Agent 更合适时调用task_tool委派。browser 委派需要像其他浏览器示例那样配置好 Playwright/MCP。

uv run python examples/mobile_gui/run_mobile_gui_subagent.py

可选的协调者提示词覆盖（配置于examples/mobile_gui/.env）：

子 Agent 迭代上限：OTHER_SUBAGENT_MAX_ITERATIONS（默认 25）、MOBILE_SUBAGENT_MAX_ITERATIONS（默认 30）；父 Agent 自身的MAX_ITERATIONS默认 20（见 run_mobile_gui_subagent.py）。

从源码可见其编排方式：三个子 Agent 分别通过build_browser_agent_config、build_code_agent_config、build_mobile_gui_agent_config构建SubAgentConfig，父 Agent 通过create_deep_agent(card=AgentCard(name="coordinator_with_mobile", ...))创建。默认的协调者提示词（_DEFAULT_COORDINATOR_HINT）明确要求："当任务明显匹配 task_tool 中某个子 Agent 类型时用task_tool委派并传清晰的task_description；不拆分反而更快时不要委派。"这为多模态多 Agent 场景提供了一套"优先本地直答、必要时精准委派"的路由策略。

8. 共享环境变量

三个脚本共用的环境变量：

截图与 grounding 的深度调优通过移动 GUI 工具内部读取的变量完成，完整定义见 openjiuwen/harness/tools/mobile_gui/config.py 中的MobileGuiRuntimeSettings（均由同名环境变量驱动，所有取值均有默认值）：

此外，.env.example 还包含了轨迹录制（SCREENSHOT_SIMILARITY_MAX_MEAN_DELTA、TRAJECTORY_CLASSIFICATION_QUEUE_SIZE、CLASSIFIER_MODEL_NAME、AGENT_ACTION_SUMMARIZE等）与对话压缩（DIALOGUE_COMPRESSOR_*、TIKTOKEN_IMAGE_PLACEHOLDER_TOKENS）相关的调优项，供需要录制移动 GUI 轨迹或做长对话压缩的读者参考（辅助模型构建逻辑见 trajectory_model_utils.py，支持CLASSIFIER_*、ACTION_SUMMARY_*前缀的独立模型配置并回退到主模型）。

9. 故障排查（Troubleshooting）

• adb devices显示unauthorized：解锁设备/模拟器，并在 USB 调试授权弹窗中点击允许。
• device not found/ 连接错误：确认DEVICE_SERIAL与adb devices输出完全一致（包括端口号）。
• 缺少依赖包：安装mobile-guiextra（uv sync --extra mobile-gui或pip install -e ".[mobile-gui]"）；脚本在uiautomator2或Pillow缺失时会打印安装提示。
• LLM 报错或行为异常：确认模型支持多模态输入，且API_BASE/MODEL_NAME与你的服务商配置一致。
• 首次连接 atx-agent 失败：设备在线时执行python -m uiautomator2 init（每次清空模拟器后需重跑）。

10. 小结：从示例到框架能力的延伸

这三个示例演示了 openJiuwen agent-core 移动 GUI 能力的完整闭环：

1. 感知层：VlmGroundingPerceptionRail在每次模型调用前抓屏并注入多模态消息，模型在同一轮内"看图选点"；
2. 执行层：tap/double_tap/long_press/drag/type_text/scroll/press_*等工具把归一化坐标转换为真实像素手势；
3. 智能层：技能发现 + 多模态技能 rails 让 Agent 能照"图文教程"完成任务；
4. 编排层：run_mobile_gui_subagent.py展示 Coordinator 如何把移动 GUI 与浏览器、代码能力组合成多 Agent 系统。

如果你需要在自己项目中复用这套能力，只需在构建 DeepAgent 时使用create_mobile_gui_agent（或build_mobile_gui_agent_config配置 SubAgent），并通过MobileGuiRuntimeSettings.from_env()读取的环境变量完成调优，即可获得与示例一致的行为。

• 人工智能
• AI Agent
• Agent 框架
• 大模型
• 工具调用
• RAG
• 提示工程
• 强化学习