SA_PCAgent - 智能PC操作代理

SA_PCAgent是一个基于多模态AI的智能PC操作代理，能够理解用户的自然语言指令并自动执行相应的PC操作。

特性

• 🤖 智能指令理解: 支持复杂的用户指令分解和执行
• 🖥️ 跨平台支持: 同时支持Windows和macOS系统
• 🔄 反思机制: 内置操作反思和错误纠正能力（可选）
• 📝 完整日志: 详细的操作日志和执行记录

项目结构

SA_PCAgent/
├── __init__.py
├── main.py                   # 主入口
├── requirements.txt          # 依赖
├── README.md                 # 项目说明
├── config/
│   ├── __init__.py
│   ├── settings.py           # 配置访问
│   ├── config_example.json
│   └── config.json           # 运行时配置
├── core/
│   ├── __init__.py
│   ├── agent_controller.py   # 流程编排/截图/反思/日志
│   ├── ai_interface.py       # 模型调用接口
│   ├── prompts_cn.py         # 中文提示词
│   └── prompts.py            # 英文提示词
├── actions/
│   ├── __init__.py
│   ├── base_actions.py       # 点击/输入/拖拽/快捷键
│   └── action_parser.py      # 动作解析与执行
├── perception/
│   ├── __init__.py
│   ├── coordinate_locator.py # 坐标定位（双阶段）
│   ├── icon_detection.py # 当前已经弃用的感知模块，下同
│   ├── ocr.py
│   ├── perception_manager.py
│   ├── vlm_perception.py
│   └── vlm_perception_old.py
├── utils/
│   ├── __init__.py
│   ├── logger.py
│   ├── image_utils.py
│   ├── merge_utils.py
│   └── string_utils.py
├── platform_backup/
│   ├── __init__.py
│   ├── mac_aci.py        # Mac无障碍接口
│   └── win_aci.py        # Windows无障碍接口
└── OpenOCR/              # OCR模块（已弃用）

安装

1. 克隆项目到本地
2. 安装依赖包：

   pip install -r SA_PCAgent/requirements.txt

3. 配置API密钥，在SA_PCAgent目录下创建config.json文件：

   cp SA_PCAgent/config_example.json SA_PCAgent/config.json

   然后编辑SA_PCAgent/config.json填入API信息：

   {
       "vl_model_name": "your_vision_model",
       "llm_model_name": "your_llm_model", 
       "token": "your_api_token",
       "url": "your_api_url"
   }

使用方法

基本使用

python main.py --instruction "在浏览器中搜索人工智能的最新发展"

高级参数

python main.py \
    --instruction "在浏览器中搜索人工智能的最新发展" \
    --use_som 1 \
    --num_step_limit 30 \
    --disable_reflection 0 \
    --simple 0

参数说明

• --instruction: 用户指令（必需）
• --use_som: 是否生成SOM标注（默认: 1）
• --disable_reflection: 是否禁用反思（默认: 1）
• --num_step_limit: 最大步数限制（整数）
• --simple: 简单指令模式（1-不做任务分解）
• --mac: 是否在Mac平台（1-MAC, 0-WIN）

配置说明

模型配置

• vl_model_name: 视觉语言模型名称
• llm_model_name: 大语言模型名称
• token: API访问令牌
• url: API服务地址

系统配置

• ratio: 显示比例（Windows: 1.0, Mac: 2.0）
• font_path: 字体文件路径

工作流

1. 决策：模型输出动作与目标元素描述。
2. 感知：根据描述在截图中定位坐标，生成SOM标注。
3. 执行：合成最终指令并执行；可选进行反思与规划。

日志系统

系统会自动记录详细的执行日志，包括：

• 操作步骤和结果
• 错误信息和异常处理

日志文件保存在任务目录的logs/下；如启用SOM，会在同一任务目录生成screenshot_*_som.png。

开发指南

添加新的操作类型

1. 在actions/base_actions.py中添加基础操作方法
2. 在actions/action_parser.py中添加解析逻辑
3. 更新提示词模板以包含新操作

扩展感知能力

1. 在perception/目录下创建新的感知模块
2. 在perception_manager.py中集成新模块
3. 更新配置文件以支持新的感知选项