PC-Agent 实战指南：基于层次化多智能体协作框架的 PC 复杂任务自动控制

PC-Agent 实战指南基于层次化多智能体协作框架的 PC 复杂任务自动控制【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgentPC-Agent 是 MobileAgent GUI Agent 家族中专用于 PC 端Windows / Mac复杂任务自动化的层次化多智能体协作框架它基于视觉感知与系统无障碍信息能够依据自然语言指令自动控制 Chrome、Word、WeChat 等生产力应用。本文将以 PC-Agent 官方 README 为骨架结合仓库源码逐层剖析其任务分解—主动感知—行动决策—反思验证—规划进度的运行机制并给出完整的安装、配置与运行方案帮助读者在自己的电脑上复现与二次开发。一、PC-Agent 是什么根据 PC-Agent/README.mdPC-Agent 是一个多智能体协作系统能够基于用户指令实现对生产力场景如 Chrome、Word、WeChat的自动化控制其核心设计目标有三多智能体协作系统由多个角色各异的智能体子任务分解、行动决策、反思、规划、记忆协同完成长链路操作主动感知模块针对 PC 平台密集、多样的可交互元素专门设计比单纯依赖整屏截图更适应高分辨率、元素重叠的 PC 界面层次化多智能体协作结构通过先分解、后逐段执行、每步反思与规划的层次结构提升复杂任务序列的整体成功率。PC-Agent 是 MobileAgent 系列Mobile-Agent、Mobile-Agent-v2、Mobile-Agent-v3、PC-Agent、GUI-Critic-R1 等中面向桌面端的一环仓库根目录 README.md 将其整体定位为 Mobile-Agent: The Powerful GUI Agent Family。在仓库中 PC-Agent 存在两个代码版本版本目录说明更新版默认PC-Agent/PCAgent以qwen3-vl、gpt-4o等视觉语言模型为基座采用子任务分解 主动感知 决策 反思 规划的多智能体结构入口为 PC-Agent/run.py早期版PC-Agent/PCAgent_v1以 GPT-4o 为基座采用 Planning-Decision-Reflection规划-决策-反思框架入口为 PC-Agent/run_v1.py下文以更新版为主展开讲解。二、系统架构层次化多智能体如何协同工作从 PC-Agent/run.py 的主循环# communication hub之后的主体逻辑可以看到PC-Agent 将一次指令的执行组织为如下层次用户指令 └─ 子任务分解智能体Subtask把复杂指令拆成可独立执行的子任务序列 └─ 逐子任务循环 ├─ 主动感知Perception截图 OCR 图标检测 无障碍树 → 生成带编号的 SOM 图 ├─ 行动决策智能体Action依据指令与感知信息输出 {Thought,Action,Summary} ├─ 执行动作Execution调用 pyautogui / pynput 落盘到真实系统 ├─ 反思智能体Reflection对比操作前后截图判定 A/B/C/D 并纠正错误 └─ 规划智能体Planning更新 已完成内容维护任务进度2.1 子任务分解Subtask Decomposition任务分解是层次化结构的顶层。PC-Agent 要求分解出的每个子任务都能脱离其他子任务独立执行为此定义了四种子任务类型见 PC-Agent/PCAgent/prompt_qwen.py 中的get_subtask_prompt常规字符串如 Open dark mode in system settings包含字典内容的字符串子任务结果需以字典形式传递给后续任务例如在 Outlook 中查看 Paul 的邮件并输出{contact: Paul, mail_content: content of the email}格式化字符串利用前序子任务输出的 key 补全后独立执行例如 Send {mail_content} via SMS to Joey包含字典内容的格式化字符串既依赖前序 key 补全又要向后续任务输出字典。官方提示词给出了一个跨应用复合指令的分解示例Open dark mode in system settings, check the questions sent by John in WeChat, search for answers in Chrome, create a new Word document with the answers, save as assignment.docx, and send to John.可被分解为系统设置开深色模式 → 微信读取 John 的问题并以 dict 输出{John_question: ...}→ Chrome 搜索{John_question}并以 dict 输出答案 → Word 新建文档写入{John_question_answer}保存为assignment.docx→ 微信发送该文件。分解时还需注意每个格式化字符串中的 key 必须能在前序子任务中找到对应的 dict 输出每个子任务要明确指定应用程序docx 用 Word、xlsx 用 Excel打开文件要写清文件名。2.2 行动决策Action Decision每个子任务内部PC-Agent 进入感知 → 决策 → 执行 → 反思 → 规划的迭代循环。行动决策智能体接收get_action_prompt构造的提示见 prompt_qwen.py提示中包括Background当前截图宽高、用户子指令add_info用户附加的操作经验Screenshot information感知模块提取的可交互元素坐标 文本/图标描述History operations历史步骤的操作、动作与反思记录Progress此前规划智能体输出的已完成内容Memory记忆单元记录的页面关键信息Last operation错误时若上一步反思判定失败会附加上次操作未达预期请重新规划的纠错上下文。模型需要以 JSON 格式输出{Thought: ..., Action: ..., Summary: ...}三个字段其中 Action 只能从预定义动作集中选择一个。2.3 反思Reflection与规划Planning反思智能体get_reflect_prompt接收操作前后两张截图及其感知信息回答四个选项A操作结果符合预期且当前截图确认用户目标已达成B操作进入了错误页面需要纠正C操作没有产生任何变化D操作看似执行了但当前截图确认目标并未真正达成如点错位置、选中错误项。对应地run.py 中error_flag会被置位并把这些反思结果写回下一次决策的上下文驱动模型修正动作。这里体现了 PC-Agent 的关键设计必须以操作后截图验证目标是否真实达成而不是执行了动作就默认成功。规划智能体get_process_prompt则在每步操作后结合当前截图与历史操作序列输出### Completed contents ###形式的任务进度摘要作为下一轮决策的 Progress 上下文从而在长任务中维护对已完成/未完成的全局认知。2.4 记忆单元Memory框架还预留了记忆单元get_memory_prompt当memory_switch开启时模型会判断当前页面是否存在与任务关键信息相关的内容记录到memory中供后续步骤使用。默认关闭以换取速度见 run.py 中的# Memory Setting注释。三、主动感知模块让模型看见PC 界面针对 PC 平台界面元素密集、图标多样、文本与控件重叠的特点PC-Agent 设计了多路融合的主动感知管线核心实现在 run.py 的get_perception_infos函数中主要包括四条信息通路3.1 OCR 文本感知文本由 OCR 提取支持两种方式通过--ocr_api切换云端 OCR API默认--ocr_api 1调用阿里云 OCR API实现位于 PCAgent/text_localization.py需要配置OCR_ACCESS_KEY_ID与OCR_ACCESS_KEY_SECRET环境变量本地 OCR 模型--ocr_api 0通过 ModelScope 加载 OCR 检测与识别模型damo/cv_resnet18_ocr-detection-line-level_damo与damo/cv_convnextTiny_ocr-recognition-document_damo实现位于 PCAgent/text_localization_old.py。提取到的文本块会经过merge_boxes_and_texts_new等合并策略见 PCAgent/merge_strategy.py进行邻近框合并避免同一文本被切碎。3.2 图标/元素感知与无障碍树PC-Agent 通过--use_a11y开关选择图标信息的获取方式无障碍树默认--use_a11y 1Windows 下使用 pywinauto/win32gui 实现的无障碍接口pywin.py 中的WindowsACImacOS 下使用 AppKit/ApplicationServices 实现pymac.py 中的MacOSACI。系统会把 UI 元素线性化为带文本、角色、位置、尺寸的节点列表天然弥补了纯视觉方案对无可视文本图标如按钮、菜单项感知不足的问题。OCR 结果还会与无障碍元素做 IOU 重叠过滤filter_ocr_elements去除冗余文本GroundingDINO 图标检测--use_a11y 0通过 ModelScope 下载AI-ModelScope/GroundingDINO权重调用 Grounding-DINO 检测界面中的图标区域。3.3 SOM 标注图Set-of-Mark感知信息最终通过draw_coordinates_boxes_on_image在截图上绘制编号框生成 SOM 图*_som.png并把每个元素的文本/图标描述与中心坐标组织成{text: ..., coordinates: [x, y]}列表。决策智能体同时获得 SOM 图与结构化元素列表use_som1时或仅原始截图use_som0时从而做到看得见界面、读得懂元素、点得准坐标。注意run.py中坐标有屏幕缩放处理——Windows 下ratio1.0macOS 下ratio2.0Retina 屏动作执行前会把视觉坐标除以 ratio 转换为真实屏幕像素。四、安装与依赖PC-Agent 同时支持Windows与Mac安装步骤如下以官方 README 为准conda create --name pcagent python3.10 source activate pcagent # Windows 平台 pip install -r PC-Agent/requirements.txt # Mac 平台 pip install -r PC-Agent/requirements_mac.txt # 额外安装 OpenOCR用于 Select 动作的文本范围定位 git clone https://github.com/Topdu/OpenOCR.git pip install openocr-python两份依赖清单的差异主要体现在平台绑定库上PC-Agent/requirements.txtWindows包含pywin32、pywinauto、comtypes、pypiwin32等 Windows 自动化与无障碍树读取依赖以及PyAutoGUI、pynput、pyperclip等全局输入模拟库PC-Agent/requirements_mac.txtMac包含pyobjc-core、pyobjc-framework-Cocoa、pyobjc-framework-Quartz、pyobjc-framework-ApplicationServices等 macOS 无障碍与图形框架绑定以及tensorflow-macos等本地 OCR 推理依赖。两类平台均依赖openai调用视觉语言模型、dashscope阿里云 DashScope 多模态接口、modelscope本地模型下载与推理管线、pillow截图绘制、psutil进程管理等。另需注意本地 OCR 与 GroundingDINO 通路依赖torch/torchvision与transformers若只使用 API 通路--ocr_api 1、--use_a11y 1则相关计算负担较小。五、配置文件config.json运行前需编辑 PC-Agent/config.json填入 API 密钥与模型信息其字段与 README 完全一致{ vl_model_name: gpt-4o, llm_model_name: gpt-4o, token: sk-..., url: https://api.openai.com/v1 }字段含义vl_model_name视觉语言模型名用于行动决策、反思、规划等需要读图的任务README 示例为gpt-4o源码中同时对qwen3-vl等模型做了坐标归一化兼容见 run.py 中的坐标反归一化逻辑llm_model_name文本语言模型名用于子任务分解等纯文本任务示例同为gpt-4otokenAPI Key需替换为真实密钥urlOpenAI 兼容的 API Base URL实际调用由 PCAgent/api.py 中的inference_chat完成它基于openai库的OpenAI(api_keytoken, base_urlapi_url)构建客户端发送多模态messages文本 base64 图片并内置 5 次重试机制。若使用阿里云百炼等 OpenAI 兼容服务将url指向对应 endpoint 并填入相应 Key 即可。图片在发送前会经resize_encode_image按screen_scale_ratio0.5缩放以减小传输体积见 api.py。六、运行你的第一个任务配置完成后用 README 提供的命令即可启动# Windows python PC-Agent/run.py --instructionOpen Chrome and search the PC-Agent paper. --mac 0 # Mac python PC-Agent/run.py --instructionOpen Chrome and search the PC-Agent paper. --mac 1执行过程中PC-Agent 会在当前目录生成task_1/目录逐帧保存原始截图、SOM 标注图、perception_infos_step*.json感知元素列表与output_for_save.json每步决策/反思/规划记录、instruction.json子任务分解结果便于事后回放与调试。6.1 命令行参数全解析PC-Agent/run.py 通过argparse暴露了以下参数官方 README 仅列出其中三个核心参数其余参数均可从源码确认参数默认值说明--instruction用户自然语言指令必填--mac1平台开关1为 Mac使用 Command 键、ratio20为 Windows使用 Ctrl 键、搜索快捷键 WinS--add_infoClick the search bar in the middle of the page to search附加操作经验帮助 Agent 更准确地操作run.py 中还内置了一段基础经验浏览器顶部搜索框、微信输入框在发送按钮旁、下载文件优先用快捷键--disable_reflection1设为1跳过反思智能体以提升速度README 明确警告这可能降低操作成功率0则开启反思--simple1设为1跳过任务分解把整条指令当作单一子任务适合简单指令--use_som1决策时是否使用带编号标注的 SOM 图1或原始截图0--draw_text_box0是否在 SOM 图中额外绘制 OCR 文本框--font_pathC:\Windows\Fonts\arial.ttfSOM 标注数字的字体路径--use_a11y1图标信息来自无障碍树1还是 GroundingDINO 检测0--use_perception_info10时仅使用截图不注入 OCR/无障碍信息--ocr_api11用阿里云 OCR API0用本地 ModelScope OCR 模型--text_len_thre1000过滤文本长度超过该阈值的感知元素--num_step_limit20单个任务的全局最大执行步数--clear_history_each_subtask1每个子任务开始前是否清空历史记录--ratio1.0屏幕缩放比Windows 1.0 / Mac 2.0Mac 下自动覆盖为 2--screenshot_roottask_截图与日志输出目录前缀--mute0设为1关闭过程日志打印6.2 动作空间与执行映射决策模型输出的 Action 字符串由 run.py 中的if/elif动作分发链解析并映射到真实系统操作动作全集如下与get_action_prompt中定义的动作空间一致动作语义底层实现Tap (x, y)/Double Tap (x, y)/Triple Tap (x, y)单击/双击/三击双击可用于打开文件pyautogui.moveTopynput鼠标click(countn)Right Tap (x, y)右键如新建文件鼠标右键Shortcut (key1, key2)组合快捷键如commands保存、commanda全选、commandt新建标签页pyautogui.keyDown/keyUpcommand/ctrl自动按平台归一化Press (key)按键如enter、backspace、方向键pyautogui.pressOpen App (name)通过系统搜索启动应用Windows 用 WinSMac 用 CmdSpace搜索框输入 EnterType (x, y), (text)点击输入框并键入文本后回车中文走剪贴板粘贴英文走typewriteSelect (content)选中文档中指定范围如标题、某段落供后续编辑调用 OpenOCR 定位首末行文本坐标后拖拽Replace (x, y), (text)替换可编辑内容重命名、新搜索双击选中 command/ctrla全选 输入Append (x, y), (text)在指定位置后追加内容单击 全选 下移 输入Tell (answer)以 dict 形式返回子任务结果供后续子任务通过{key}引用解析{key: value}存入answer_dictStop仅在当前截图确认所有需求真正完成时结束任务结束循环其中Tell动作实现了子任务间的参数传递子任务分解时定义的 dict 输出会在后续格式化子任务中通过answer_dict与字符串格式化run.py中的analyze_string/check_subtask_dict完成回填这正是层次化协作在数据流层面的落地。七、事件循环与可观测性整个任务执行过程由 run.py 的while True循环驱动每个 step 的完整链路为截图并生成感知信息与 SOM 图构造行动决策 prompt → 调用inference_chat得到 JSON 决策解析并执行动作对qwen3-vl/doubao等返回归一化坐标的模型会按截图宽高反归一化到像素坐标等待 2 秒后重新截图获取新感知若开启反思对比前后截图判定 A/B/C/D 并更新error_flag规划智能体更新completed_requirements判断是否命中Tell/Stop/步数上限否则进入下一轮。每一步的决策、反思与规划输出都会持久化到output_for_save.json配合task_1/下的截图序列可以完整复盘 Agent 的每个操作与判断依据——这也是定位为什么某个任务执行失败的最直接手段。八、早期版本参考Planning-Decision-Reflection 框架早期版 PC-Agent/PCAgent_v1对应 PC-Agent/README_v1.md采用更简洁的三段式框架规划Planning—决策Decision—反思Reflection其中规划模块负责制定操作步骤决策模块输出具体动作反思模块校验操作结果。相比更新版v1 不包含无障碍树感知与子任务级参数传递其示例指令为python PC-Agent/run_v1.py --instructionCreate a new doc on Word, write a brief introduction of Alibaba, and save the document. --api_tokenYour GPT-4o API token.更新版在此基础上引入了子任务分解与跨应用参数传递、无障碍树增强感知、以及截图验证目标是否达成的规划机制整体结构更适用于跨应用的复合任务。读者可根据任务复杂度选择对应版本。九、源码结构与进一步阅读指引PC-Agent 目录的代码组织如下可作为继续深入研究的索引入口与主循环PC-Agent/run.py参数解析、子任务分解、感知管线、动作分发、反思/规划调度、PC-Agent/run_v1.py早期版入口提示词工程PCAgent/prompt_qwen.py子任务分解、行动决策、反思、规划、记忆、Select 全套提示词含中英双语分解模板模型调用PCAgent/api.pyOpenAI 兼容调用与图片缩放编码、PCAgent/chat.py多轮对话历史构造支持单图/多图感知模块PCAgent/text_localization.py阿里云 OCR API、PCAgent/text_localization_old.py本地 OCR、PCAgent/icon_localization.pyGroundingDINO 图标检测、PCAgent/merge_strategy.py文本框合并策略平台适配层PC-Agent/pywin.pyWindowsACIpywinauto/win32gui 无障碍树、PC-Agent/pymac.pyMacOSACIAppKit/ApplicationServices 无障碍树配置与依赖PC-Agent/config.json、PC-Agent/requirements.txt、PC-Agent/requirements_mac.txt早期版组件PCAgent_v1/v1 的 api/chat/crop/prompt/感知与合并实现十、适用前提与注意事项运行环境需在真实 Windows / macOS 桌面环境运行依赖屏幕截图、鼠标键盘注入与系统无障碍权限。macOS 下需为终端/运行环境授予辅助功能与屏幕录制权限Windows 下需确保相关自动化库可用模型依赖README 示例默认 GPT-4o 与 OpenAI 兼容 API但源码对qwen3-vl、doubao等模型做了坐标兼容处理且依赖中同时包含dashscope与modelscope说明可替换为其他多模态大模型具体需结合所选服务的输入输出格式调整性能取舍--disable_reflection 1、--simple 1、关闭记忆单元均以降低成功率为代价换取速度--num_step_limit用于防止任务无限循环本地推理开销若关闭 OCR API--ocr_api 0或无无障碍树可用--use_a11y 0会引入本地 OCR 与 GroundingDINO 的模型下载与推理开销需预先准备相应依赖与显存/内存资源。综上PC-Agent 提供了一个从任务分解到逐步验证的完整 PC 自动化智能体参考实现。无论是直接运行体验还是借鉴其多智能体层次协作 主动感知融合 截图验证的工程范式都可以从上述源码路径中找到对应的设计与实现细节。【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考