Cradle: 赋能基础智能体 (Foundation Agents) 迈向通用计算机控制

Cradle 框架赋能新兴的基础模型 (Foundation Models)，通过人类使用的统一接口执行复杂的计算机任务，即以截图作为输入，键盘和鼠标操作作为输出。

📢 更新

• 2024-06-27: 一次重大更新！Cradle 已扩展至四款游戏：RDR2、Stardew Valley、Cities: Skylines 和 Dealer's Life 2 以及各种软件，包括但不限于 Chrome、Outlook、Capcut、Meitu 和 Feishu。我们还发布了最新的 论文。快去查看吧！

最新视频

点击上方任意一个视频缩略图即可在 YouTube 上观看。

💾 安装

准备环境文件

我们目前提供 OpenAI 和 Claude 的 API 访问权限。请在仓库根目录下创建一个 .env 文件来存储密钥（只需其中一个即可）。

包含私有信息的示例 .env 文件：

OA_OPENAI_KEY = "abc123abc123abc123abc123abc123ab"
RF_CLAUDE_AK = "abc123abc123abc123abc123abc123ab" # Access Key for Claude
RF_CLAUDE_SK = "123abc123abc123abc123abc123abc12" # Secret Access Key for Claude
AZ_OPENAI_KEY = "123abc123abc123abc123abc123abc12"
AZ_BASE_URL = "https://abc123.openai.azure.com/"
RF_CLAUDE_AK = "abc123abc123abc123abc123abc123ab"
RF_CLAUDE_SK = "123abc123abc123abc123abc123abc12"
IDE_NAME = "Code"

OA_OPENAI_KEY 是 OpenAI API 密钥。您可以从 OpenAI 获取它。

AZ_OPENAI_KEY 是 Azure OpenAI API 密钥。您可以从 Azure Portal 获取它。

OA_CLAUDE_KEY 是 Anthropic Claude API 密钥。您可以从 Anthropic 获取它。

RF_CLAUDE_AK 和 RF_CLAUDE_SK 是用于 Claude API 的 AWS RESTful API 密钥和秘密密钥。

IDE_NAME 指的是代码运行的 IDE (集成开发环境) 环境，例如 PyCharm 或 Code (VSCode)。它主要用于启用 IDE 和目标环境之间的自动切换。

设置

Python 环境

请设置您的 Python 环境并安装所需的依赖项，如下所示：

# Clone the repository
git clone https://github.com/BAAI-Agents/Cradle.git
cd Cradle

# Create a new conda environment
conda create --name cradle-dev python=3.10
conda activate cradle-dev
pip install -r requirements.txt

安装 OCR 工具

1. Option 1
# Download best-matching version of specific model for your spaCy installation
python -m spacy download en_core_web_lg

or

# pip install .tar.gz archive or .whl from path or URL
pip install https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.7.1/en_core_web_lg-3.7.1.tar.gz

2. Option 2
# Copy this url https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.7.1/en_core_web_lg-3.7.1.tar.gz
# Paste it in the browser and download the file to res/spacy/data
cd res/spacy/data
pip install en_core_web_lg-3.7.1.tar.gz

🚀 开始使用

由于每款游戏和软件之间存在巨大差异，我们在下方提供了它们各自的特定设置。

1. Red Dead Redemption 2
2. Stardew Valley
3. Cities: Skylines
4. Dealer's Life 2
5. Software

🌲 文件结构

由于部分用户可能希望将我们的框架应用于新游戏，本节主要展示 Cradle 的核心目录和组织结构。我们将用 "⭐⭐⭐" 高亮显示与新游戏迁移相关的模块，并在后文提供详细解释。

Cradle
├── cache # Cache the GroundingDino model and the bert-base-uncased model
├── conf # ⭐⭐⭐ The configuration files for the environment and the llm model
│   ├── env_config_dealers.json
│   ├── env_config_rdr2_main_storyline.json
│   ├── env_config_rdr2_open_ended_mission.json
│   ├── env_config_skylines.json
│   ├── env_config_stardew_cultivation.json
│   ├── env_config_stardew_farm_clearup.json
│   ├── env_config_stardew_shopping.json
│   ├── openai_config.json
│   ├── claude_config.json
│   ├── restful_claude_config.json
│   └── ...
├── deps # The dependencies for the Cradle framework, ignore this folder
├── docs # The documentation for the Cradle framework, ignore this folder
├── res # The resources for the Cradle framework
│   ├── models # Ignore this folder
│   ├── tool # Subfinder for RDR2
│   ├── [game or software] # ⭐⭐⭐ The resources for game, exmpale: rdr2, dealers, skylines, stardew, outlook, chrome, capcut, meitu, feishu
│   │   ├── prompts # The prompts for the game
│   │   │   └── templates
│   │   │       ├── action_planning.prompt
│   │   │       ├── information_gathering.prompt
│   │   │       ├── self_reflection.prompt
│   │   │       └── task_inference.prompt
│   │   ├── skills # The skills json for the game, it will be generated automatically
│   │   ├── icons # The icons difficult for GPT-4 to recognize in the game can be replaced with text for better recognition using an icon replacer
│   │   └── saves # Save files in the game
│   └── ...
├── requirements.txt # The requirements for the Cradle framework
├── runner.py # The main entry for the Cradle framework
├── cradle # Cradle's core modules
│   ├── config # The configuration for the Cradle framework
│   ├── environment # The environment for the Cradle framework
│   │   ├── [game or software] # ⭐⭐⭐ The environment for the game, exmpale: rdr2, dealers, skylines, stardew, outlook, chrome, capcut, meitu, feishu
│   │   │   ├── __init__.py # The initialization file for the environment
│   │   │   ├── atomic_skills # Atomic skills in the game. Users should customise them to suit the needs of the game or software, e.g. character movement
│   │   │   ├── composite_skills # Combination skills for atomic skills in games or software
│   │   │   ├── skill_registry.py # The skill registry for the game. Will register all atomic skills and composite skills into the registry.
│   │   │   └── ui_control.py # The UI control for the game. Define functions to pause the game and switch to the game window
│   │   └── ...
│   ├── gameio # Interfaces that directly wrap the skill registry and ui control in the environment
│   ├── log # The log for the Cradle framework
│   ├── memory # The memory for the Cradle framework
│   ├── module # Currently there is only the skill execution module. Later will migrate action planning, self-reflection and other modules from planner and provider
│   ├── planner # The planner for the Cradle framework. Unified interface for action planning, self-reflection and other modules. This module will be deleted later and will be moved to the module module.
│   ├── runner # ⭐⭐⭐ The logical flow of execution for each game and software. All game and software processes will then be unified into a single runner
│   ├── utils # Defines some helper functions such as save json and load json
│   └── provider # The provider for the Cradle framework. We have semantically decomposed most of the execution flow in the runner into providers
│       ├── augment # Methods for image augmentation
│       ├── llm # Call for the LLM model, e.g. OpenAI's GPT-4o, Claude, etc.
│       ├── module # ⭐⭐⭐ The module for the Cradle framework. e.g., action planning, self-reflection and other modules. It will be migrated to the cradle/module later.
│       ├── object_detect # Methods for object detection
│       ├── process # ⭐⭐⭐ Methods for pre-processing and post-processing for action planning, self-reflection and other modules
│       ├── video # Methods for video processing
│       ├── others # Methods for other operations, e.g., save and load coordinates for skylines
│       ├── circle_detector.py # The circle detector for the rdr2
│       ├── icon_replacer.py # Methods for replacing icons with text
│       ├── sam_provider.py # Segment anything for software
│       └── ...
└── ...

📚 迁移到新游戏

由于每个游戏的设置及其兼容的操作系统不同，Cradle 不能简单地通过替换游戏名称来迁移到新游戏。我们建议针对每个游戏进行具体考虑。例如，RDR2（荒野大镖客 2）是一款独立的 AAA 级游戏，需要实时战斗，因此我们需要暂停游戏以等待 GPT-4o 的响应，然后取消暂停以执行操作。Stardew（星露谷物语）也存在同样的问题。其他游戏如《Dealer's Life 2》和《Cities: Skylines》没有实时性要求，因此不需要暂停。如果新游戏与后者类似，我们建议复制《Cities: Skylines》的实现，并遵循其实现路径来创建相应的模块。尽管每个游戏可能存在显著差异，但我们的 Cradle 框架仍然可以实现对游戏的统一适配。假设新游戏的名称为 newgame，具体的迁移流程可在 迁移到新游戏指南 中找到。

引用

如果您觉得我们的工作有用，请考虑引用我们！

@article{tan2024cradle,
  title={Cradle: Empowering Foundation Agents towards General Computer Control},
  author={Weihao Tan and Wentao Zhang and Xinrun Xu and Haochong Xia and Ziluo Ding and Boyu Li and Bohan Zhou and Junpeng Yue and Jiechuan Jiang and Yewen Li and Ruyi An and Molei Qin and Chuqiao Zong and Longtao Zheng and Yujie Wu and Xiaoqiang Chai and Yifei Bi and Tianbao Xie and Pengjie Gu and Xiyun Li and Ceyao Zhang and Long Tian and Chaojie Wang and Xinrun Wang and Börje F. Karlsson and Bo An and Shuicheng Yan and Zongqing Lu},
  journal={arXiv preprint arXiv:2403.03186},
  year={2024}
}

Cradle 快速上手指南

Cradle 是一个赋能基础模型（Foundation Models）进行通用计算机控制的框架。它通过统一的接口（截图输入、键盘鼠标输出），使 AI 能够执行复杂的电脑任务，支持多款游戏（如 RDR2、星露谷物语）及软件（如 Chrome、Outlook）。

1. 环境准备

• 系统要求: 支持 Windows/Linux/macOS。
• Python 版本: 建议使用 Python 3.10。
• 依赖服务: 需要配置大模型 API Key（支持 OpenAI 或 Claude）。
• OCR 工具: 需安装 spacy 及相关语言模型。

2. 安装步骤

克隆仓库

git clone https://github.com/BAAI-Agents/Cradle.git
cd Cradle

创建并激活虚拟环境

推荐使用 Conda 管理环境：

conda create --name cradle-dev python=3.10
conda activate cradle-dev

安装依赖

pip install -r requirements.txt

安装 OCR 模型 (二选一)

方式 1 (推荐):

python -m spacy download en_core_web_lg

方式 2:

cd res/spacy/data
pip install en_core_web_lg-3.7.1.tar.gz

配置环境变量

在根目录下创建 .env 文件，填入你的 API Key（至少一个即可）：

OA_OPENAI_KEY = "your_openai_key_here"
# 或者使用 Azure / Claude 等
AZ_OPENAI_KEY = "your_azure_key_here"
RF_CLAUDE_AK = "your_claude_ak"
RF_CLAUDE_SK = "your_claude_sk"
IDE_NAME = "Code"  # 例如 Code (VSCode) 或 PyCharm

3. 基本使用

由于不同游戏和软件的配置差异较大，请根据目标环境参考对应的文档配置。

1. 选择环境: 访问项目文档中的具体环境配置页，例如：

   • Red Dead Redemption 2
   • Stardew Valley
   • Software (Chrome/Outlook 等)

2. 运行程序: 主入口为 runner.py。通常需要在特定环境下执行，具体命令请参考对应环境的文档说明。一般流程如下：

   python runner.py
   

   (注：实际运行时可能需要指定配置文件或任务参数，详见各环境文档)

3. 迁移新游戏: 如需适配新游戏，可参考 Migrate to New Game Guide，主要涉及修改 conf 下的配置文件及 cradle/environment 下的环境模块。