ReCode: 统一计划与行动的通用粒度控制

如果您在使用或复现代码时遇到任何困难，请通过 zhaoyangyu713@gmail.com 与我联系。

ReCode 引入了针对 LLM 代理的递归代码生成方法，将计划与行动统一为单一表示。通过将高层计划视为占位函数，并将其递归分解为可执行的原子操作，ReCode 实现了通用的粒度控制，能够动态地从战略思考过渡到具体行动。本仓库提供了论文中使用的参考实现，以及环境封装和实验工具。

核心思想

ReCode 采用分治策略，将复杂任务分解为可执行的代码片段：

1. 树状代码结构：以树形组织部分程序，每个节点代表一个子任务，并记录其执行轨迹。
2. 递归展开：占位函数由 LLM 根据特定于环境的提示和少量示例，扩展为更具体的调用或更小的子程序。
3. 动态执行循环：每个节点立即执行；根据新的观测结果决定是否继续展开、重试或结束。
4. 共享执行状态：受限的 Python 执行器维护环境变量、验证代码块，并暴露代理可用的工具集。

仓库布局

• run.py – CLI 入口，用于实例化代理和环境、管理并发并记录运行摘要。
• agents/recode/ – ReCode 代理实现、提示模板及辅助工具。
• envs/ – 针对 alfworld、webshop 和 sciworld 的环境封装及资源。
• configs/ – LLM 配置模板及异步客户端使用的定价元数据。
• utils/ – 共享组件：异步 OpenAI 封装、受限执行器、日志辅助工具和错误类型。
• figures/ – 本 README 中使用的论文图表。

实验

为评估 ReCode 的有效性，我们将实验分为推理部分和训练部分。

1. 推理结果：我们与几种主流范式（ReAct、CodeAct）以及一些专注于改进 LLM 代理规划的工作（AdaPlanner 和 ADaPT）进行了对比。ReCode 在所有三个环境中均取得了显著的性能提升，平均得分达到 60.8 分，比最佳基线方法高出 10.5 分（相对提升 20.9%）。在我们的测试中，ReCode 在 ALFWorld 环境下使用 claude-4-sonnet 模型时，甚至可以取得满分 100 分。

2. 训练结果：我们对 ReCode、ReAct 和 CodeAct 使用 Qwen2.5-7B-Instruct 进行了监督微调（SFT）。ReCode+SFT 在所有环境中表现出色，平均性能达到 70.4%，优于 ReAct+SFT（67.6%）和 CodeAct+SFT（55.8%），凸显了其卓越的数据效率。

快速入门

要运行 ReCode，我们需要一个 conda 环境。Python 版本应为 3.10 或更高。

随后，需要为三个环境配置依赖项（尚未确认这些环境之间是否会存在冲突），建议分别在三个独立的环境中进行配置。

conda create -n recode-envname python=3.10 # 将 "envname" 替换为您选择的环境名称。
conda activate recode-envname

---

ALFWorld

• 请按照 ALFWorld 官方说明 进行设置。

• 将 ALFWORLD_DATA 设置为数据集根目录，或编辑 envs/alfworld/base_config.yaml 以指向您的本地路径：

  export ALFWORLD_DATA=/path/to/alfworld
  

ScienceWorld

• 请参照 ScienceWorld 仓库 的说明进行设置。

WebShop

感谢 ETO 提供的便捷脚本来配置 WebShop 环境。

cd envs/webshop
pip install -e .
conda install -y -c conda-forge openjdk=11
pip install "en_core_web_lg @ https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.6.0/en_core_web_lg-3.6.0-py3-none-any.whl"

运行提供的辅助脚本以获取目标集合和预构建的索引：

# 当前路径为 "envs/webshop"
bash setup.sh

---

安装其他依赖项。

pip install -r requirements.txt # 此处可能并不完整，如遇问题请及时与我联系

确保 configs/profiles.yaml 指向有效的 API 凭证（如需模板，可复制 configs/profiles_example.yaml），然后在任意已启用的环境中运行一次简短的试运行：

python run.py -a recode -e alfworld -n 1 --split test --profile default

待 webshop 或 sciworld 的资源准备就绪后，可将 alfworld 替换为相应环境。日志会写入 logs/<run_id>/ 目录，控制台也会输出精简摘要以便快速诊断。

配置 LLM 访问权限

• configs/profiles.yaml 包含命名配置文件。run.py --profile 参数用于选择将哪个配置转发给 AsyncLLM。例如：

  models:
    default:
      api_key: "sk-your_api_key"
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o-mini"
      temperature: 0.0
      track_costs: true
    gpt-4o:
      api_key: "sk-your_other_key"
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o"
      temperature: 0.7
      max_tokens: 512
  

• 成本跟踪功能会加载 configs/prices.json 文件。如果您不想记录成本，可在配置中将 track_costs: false。

• 作为备用方案，您可以不使用该文件，而直接在环境变量中设置 OPENAI_API_KEY；默认配置将自动使用该密钥。

• 已准备好编辑的模板位于 configs/profiles_example.yaml；如果您是从头开始配置，可将其复制到 configs/profiles.yaml：

  cp configs/profiles_example.yaml configs/profiles.yaml
  

运行 ReCode

run.py 是标准入口点。它解析代理和环境的别名，管理并发，流式记录日志，并输出结构化的运行摘要。

# ALFWorld，单实例
python run.py -a recode -e alfworld -n 1 --split test --profile default

# WebShop，3个测试目标，允许更深的递归
python run.py -a recode -e webshop -n 3 --split test --profile default --max-depth 12

# ScienceWorld，运行5个实例，支持2路并发
python run.py -a recode -e sciworld -n 5 -c 2 --profile gpt-4o

关键命令行参数：

• -a / --agent – 代理类路径或别名（recode 解析为 agents.recode.agent.ReCodeAgent）。
• -e / --env – 环境类或别名（alfworld、webshop、sciworld）。
• -n / --instances – 评估剧集数量。
• -c / --concurrent – 最大并发剧集数（进度界面会自动调整）。
• --split、--seed、--max-depth、--profile – 会传递给代理和环境。
• -C / --config – YAML 配置文件，其键值可覆盖命令行参数；适用于复杂的参数扫描。

YAML 示例配置（configs/example.yaml）：

agent: recode
env: alfworld
instances: 10
concurrent: 2
profile: gpt-4o
split: test
task_types: ["put", "clean"] # 用于 ALFWorld
max_depth: 12
max_retry: 4

运行方式：

python run.py -C configs/example.yaml

日志与结果

• 每次运行都会创建 logs/<run_id>/ 目录，包含：
  • running_logs/run.log – 代理与环境日志的聚合流。
  • running_logs/instance_<id>.log – 每个实例的跟踪日志（当启动多个实例时）。
  • <results.json> – 由 write_summary 写入的结构化摘要文件，包含每个实例的指标及汇总统计信息（总体及按任务类型划分）。
• 运行结束后，控制台会打印精简的摘要信息（成功率、标准指标、按任务细分）。

扩展至新环境

1. 实现 Env 接口，位于 envs/<your_env>/env.py 中。以 base.environment.Env 作为接口规范：实现 reset、_run、is_done、is_success 和 report 方法。在 reset 方法中返回 {"observations": [...], "env_name": <name>, "env": self}。
2. 提供提示与指导材料，存放在 agents/recode/resources/ 目录下：
   • prompts/<env_name>/actions.txt – 对有效 run("...") 调用/工具的简要描述。
   • fewshots/<env_name>/ – 一个或多个 .txt 示例，展示思考→执行的模式。
   • 如果你的环境有任务类型，请更新 agents/recode/agent.py::_load_resources 和 agents/recode/utils.parse_raw_observation 方法，以便正确解析初始观测数据。
3. 注册别名，将你的类添加到 run.py 中的 ENV_ALIASES 列表中（可选但方便），并在必要时在代理工具中规划特定逻辑。
4. 可选地添加设置脚本（类似于 envs/webshop/setup.sh），用于记录数据集的获取过程。

编程式使用

你可以通过复用提供的工具，将代理直接嵌入到自己的循环中：

import asyncio

from agents.recode.agent import ReCodeAgent
from envs.alfworld.env import AlfworldEnv

async def solve_once():
    config = {"split": "test", "task_types": ["put"], "max_depth": 10}
    env = AlfworldEnv(logger=None)
    agent = ReCodeAgent()
    init_info = env.reset(config)
    agent.reset(config, init_info)

    observations = init_info["observations"]
    while not env.is_done():
        actions = await agent.act(observations)
        observations = await env.run(actions)

    print(env.report())
    await env.close()

asyncio.run(solve_once())

同样的模式适用于任何 Env 实现；如果需要文件记录的跟踪信息，请务必传递日志记录器。

引用

@misc{yu2025recodeunifyplanaction,
      title={ReCode: Unify Plan and Action for Universal Granularity Control}, 
      author={Zhaoyang Yu and Jiayi Zhang and Huixue Su and Yufan Zhao and Yifan Wu and Mingyi Deng and Jinyu Xiang and Yizhang Lin and Lingxiao Tang and Yingchao Li and Yuyu Luo and Bang Liu and Chenglin Wu},
      year={2025},
      eprint={2510.23564},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2510.23564}, 
}

ReCode 快速上手指南

ReCode 是一种通过递归代码生成统一“规划”与“行动”的 LLM Agent 框架，支持在 ALFWorld、WebShop 和 ScienceWorld 等环境中实现细粒度的任务控制。

环境准备

• 操作系统：Linux / macOS（Windows 需使用 WSL）
• Python 版本：3.10 或更高
• 包管理工具：Conda（推荐）或 pip
• API 密钥：需配置 OpenAI 或兼容 API 的密钥（如 gpt-4o, claude 等）

💡 建议为不同环境（ALFWorld、WebShop、ScienceWorld）分别创建独立的 Conda 环境，避免依赖冲突。

安装步骤

1. 创建并激活 Conda 环境

conda create -n recode-env python=3.10
conda activate recode-env

2. 安装核心依赖

pip install -r requirements.txt

3. 配置具体环境（任选其一）

ALFWorld

export ALFWORLD_DATA=/path/to/alfworld
# 或修改 envs/alfworld/base_config.yaml 指向本地数据路径

WebShop

cd envs/webshop
pip install -e .
conda install -y -c conda-forge openjdk=11
pip install "en_core_web_lg @ https://github.com/explosion/spacy-models/releases/download/en_core_web_lg-3.6.0/en_core_web_lg-3.6.0-py3-none-any.whl"
bash setup.sh
cd ../..

ScienceWorld

请参考 ScienceWorld 官方仓库 完成安装与数据准备。

4. 配置 LLM API

复制配置文件模板并填入你的 API 信息：

cp configs/profiles_example.yaml configs/profiles.yaml

编辑 configs/profiles.yaml，示例如下：

models:
  default:
    api_key: "sk-your_api_key"
    base_url: "https://api.openai.com/v1"
    model: "gpt-4o-mini"
    temperature: 0.0
    track_costs: true

若不使用成本追踪，可设 track_costs: false；也可直接设置环境变量 OPENAI_API_KEY 跳过配置文件。

基本使用

运行一个简单的测试任务（以 ALFWorld 为例）：

python run.py -a recode -e alfworld -n 1 --split test --profile default

参数说明：

• -a recode：使用 ReCode agent
• -e alfworld：指定环境（可替换为 webshop 或 sciworld）
• -n 1：运行 1 个测试实例
• --split test：使用测试集
• --profile default：使用默认 LLM 配置

运行完成后，日志和结果将保存在 logs/<run_id>/ 目录下，控制台会输出简要成功率统计。

其他常用命令示例

# WebShop，运行 3 个任务，允许最大递归深度为 12
python run.py -a recode -e webshop -n 3 --split test --profile default --max-depth 12

# ScienceWorld，并发运行 5 个实例（最多 2 个并发）
python run.py -a recode -e sciworld -n 5 -c 2 --profile gpt-4o

使用 YAML 配置文件批量运行

创建 configs/example.yaml：

agent: recode
env: alfworld
instances: 10
concurrent: 2
profile: gpt-4o
split: test
task_types: ["put", "clean"]
max_depth: 12
max_retry: 4

执行：

python run.py -C configs/example.yaml