microsoft/AutoSaddler 来源: https://github.com/microsoft/AutoSaddler

🛠️ AutoSaddler：基于智能体执行轨迹的持久化更新实现运行环境自动优化

许可协议: MIT Python 3.12-3.14 (https://www.python.org/) arXiv: 2608.23041 (https://arxiv.org/abs/2608.23041)

AutoSaddler 通过分析执行轨迹、对提示词、工具和中间件应用结构化更新，并选择可泛化的改进方案，从而自动优化大语言模型智能体的运行环境。

📄 论文 (https://arxiv.org/abs/2608.23041) · 🌐 项目主页 (https://autosaddler-projectpage.github.io/) · 🎥 短视频 (https://autosaddler-projectpage.github.io/#video)

初步结果报告了在不同基准测试和智能体运行环境中取得的以下 Pass@1 得分：

请参阅论文 (https://arxiv.org/abs/2608.23041) 和交互式项目主页 (https://autosaddler-projectpage.github.io/) 以获取分模型结果、消融实验、计算效率图表和优化轨迹。

✨ 亮点

• 全面运行环境优化： 涵盖提示词、工具定义与实现、中间件钩子以及智能体循环逻辑的搜索优化。
• 深度诊断： 深入分析执行轨迹和运行环境代码库，定位根本原因，而非依赖浅层反思。
• 结构化干预： 通过明确的补丁分类法和分阶段的“能力-引导”调度，针对提示词、工具和中间件进行定向干预，而非无约束编辑。
• 泛化意识选择： 在超出初始轨迹的更多场景上验证更新效果，并利用带有进化有向无环图的反思机制，保留广泛适用的经验。
• 持久化执行： 记录仅追加的事件、不可变的出处、可恢复的状态以及基于内容寻址的候选方案。

📣 新闻

• 2026-08-25： 新增 V2 支持，用于在 GAIA2 上优化 Meta-ARE (https://github.com/pshlego/Meta-ARE) 运行环境。
• 2026-08-24： AutoSaddler 论文作为 arXiv v1 (https://arxiv.org/abs/2608.23041) 发布，同时上线了项目主页和短视频 (https://autosaddler-projectpage.github.io/)。

🛠️ 安装

AutoSaddler 需要 Python 3.12-3.14、uv (https://docs.astral.sh/uv/) 和 Git。

git clone https://github.com/microsoft/AutoSaddler.git
cd AutoSaddler
uv sync --extra dev

请通过 uv run 在本仓库中执行 Python 命令。

🚀 快速开始

运行确定性的、无需凭证的 V2 模板，以演练优化引擎、事件存储、候选方案进化和输出投射：

uv run python -m autosaddler.v2.cli \
  --config configs/v2/local_template.yaml \
  --run-id local-template

重复执行该命令将验证已解析的输入后恢复同一次运行。

🧭 版本

• V2（当前版本）： 本文档记录的、基于插件的持久化实现。新用户和集成应从此处开始。
• V1（旧版）： 用于 arXiv 论文实验的研究级实现，保留用于论文复现和参考。请参阅 V1 README。

🗂️ 仓库结构

text
AutoSaddler/
├── configs/         # V1/V2 配置和基准测试划分清单
├── docs/            # 架构和场景集成指南
├── figures/         # README 和论文图表
├── scripts/         # 数据准备和旧版启动脚本
├── src/autosaddler/v1/ # 旧版实现
├── src/autosaddler/v2/ # 当前引擎、插件、提供者和存储
└── tests/           # 特性化和针对性 V2 测试

请从 V2 架构指南 开始了解当前实现。

🧩 工作原理

AutoSaddler 将运行环境优化问题构建为离线小批量学习。它在优化生命周期中使用三种会话类型：

1. 诊断-补丁： 检查失败的轨迹和运行环境代码库，然后提出结构化的“能力”补丁（代码或基础设施）和“引导”补丁（文本行为变更）。
2. 反思： 比较补丁前后的轨迹，分类出已修复、已退化、仍然失败和仍然通过的情况，并记录可复用的经验。
3. 进化： 参考整个进化有向无环图，从不同世代的成功组件和经验中综合生成候选方案。

候选方案更新会在抽样的训练案例上进行验证，并通过开发集门控。当运行预算耗尽时，AutoSaddler 返回排名最高的开发集候选方案。有关事件生命周期和不变量，请参阅 V2 架构指南。

🎯 支持的运行环境和基准测试

当前仓库包含：

V2 支持不可变的、基于内容寻址的组件映射和 Git 候选空间。优化器会话可以使用内置的模拟提供者、Anthropic Claude Agent SDK 或 GitHub Copilot SDK 传输层。针对其他运行环境（例如 OpenClaw 和 Codex）和基准测试（例如 Terminal-Bench）的集成即将推出。敬请期待！

⚙️ 配置

每个 V2 配置都以 schema_version: autosaddler/v2 开头。场景插件是 AutoSaddler 通用优化引擎与特定运行环境/基准测试对之间的适配器。它提供运行环境空间、案例、评估器、证据、提示词、能力和可复现性元数据。配置选择该插件并声明四个明确的权责区域：

包含的配置：

配置是严格且默认拒绝的。运行 ID 只有在所有解析的输入在字节级相同时才能重用；任何更改的源代码修订版、清单、设置或出处都会被拒绝。

🔬 复现包含的 GAIA2 冒烟运行

已签入的 V2 冒烟配置在七个 GAIA2 场景上执行了真实的优化管道：六个训练案例和一个开发案例，进行两次优化迭代。这是一次有界的集成运行，而非完整论文实验，可能需要数小时并产生提供者费用。

1. 准备仓库

使用此同级目录布局：

text
/
├── AutoSaddler/
├── Meta-ARE/
├── meta_are_data/
└── working_dir/

克隆在配置中指定的修订版的已适配 Meta-ARE 仓库：

cd ..
git clone https://github.com/pshlego/Meta-ARE.git Meta-ARE
git -C Meta-ARE checkout --detach 2419824a94fb8211fc8227ada7bff1b29f86e563
mkdir -p working_dir
cd AutoSaddler
uv sync --extra meta-are-setup

2. 准备基准测试输入

从固定的 Hugging Face 修订版准备七个清单选定的 GAIA2 数据。HF_TOKEN 对于此公共数据集是可选的，但可以避免匿名速率限制：

uv run --extra meta-are-setup python scripts/meta_are/provision_gaia2_scenarios.py \
  --destination-root "$PWD/../Meta-ARE/datasets_local/gaia2" \
  --revision 78ea3bdbdeec2bdcd6afa5420915d8a22f23ed99

该命令必须报告 "file_count": 7。然后准备大约 260 MB 的演示文件系统：

uv run --extra meta-are-setup python scripts/meta_are/provision_demo_filesystem.py \
  --destination-root "$PWD/../meta_are_data/gaia2_filesystem" \
  --revision 132e26376f5e963bb59f64bcccdd02188cb08dee \
  --meta-are-project ../Meta-ARE

这两个命令都是幂等的，记录源代码修订版和内容摘要，并拒绝不匹配的本地文件。评估运行在强制离线模式下使用 Hugging Face 客户端。

3. 配置提供者并运行

冒烟配置使用 OpenAI gpt-4.1-mini 作为任务智能体和裁判，使用 Anthropic claude-opus-4-6 进行优化：

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."

从外部工作目录运行，这样生成的工作区不会通过 Git 祖先继承仓库级的智能体指令。每次独立运行使用新的运行 ID：

cd ../working_dir
RUN_ID="meta-are-smoke-$(date -u +%Y%m%dT%H%M%SZ)"
printf 'run_id=%s\n' "$RUN_ID"
uv run --project ../AutoSaddler \
  python -m autosaddler.v2.cli \
    --config ../AutoSaddler/configs/v2/meta_are_smoke.yaml \
    --run-id "$RUN_ID"

运行结果写入 working_dir/outputs/v2_meta_are/runs/<RUN_ID>/。成功时，result.json 包含 "iterations": 2 并打印选定的候选方案及开发集分数。

运行产物和恢复

一次运行是自包含的，可能包括：

text
<RUN_ID>/
├── events.jsonl
├── manifest.json
├── snapshot.json
├── evolution_dag.json
├── metrics.jsonl
├── metrics-summary.json
├── result.json
├── resolved/
├── candidates/
├── evaluations/
├── sessions/
├── mutation-deltas/  # 仅限 Git 运行环境
└── workspaces/

events.jsonl 是权威来源。要在中断后恢复，请确认没有进程正在使用该运行 ID，然后使用相同的输入重复相同的命令。切勿对一个运行 ID 运行两个进程。在分享运行之前，请检查 sessions/ 和 evaluations/，因为轨迹可能包含提示词、响应、工具参数、工作目录、仓库元数据或其他敏感数据。

要将一个已验证的非终态检查点分支为新运行：

uv run python -m autosaddler.v2.cli \
  --config CONFIG.yaml \
  --run-id NEW_RUN_ID \
  --fork-from-run-id SOURCE_RUN_ID \
  --fork-through-sequence LAST_EVENT_SEQUENCE

初始化分支时，只有 optimization.budget.max_iterations 可以不同。旧版检查点无法导入。

🔌 添加运行环境或基准测试

V2 场景插件拥有集成边界：运行环境空间、评估器、证据构建器、提示词包、不相交的训练和开发案例、提供者能力以及已解析的出处。内置集成位于 src/autosaddler/v2/plugins/。外部包可以通过 autosaddler.scenarios 入口点组注册插件，而无需向此仓库添加特定于场景的代码。AutoSaddler 会拒绝重复名称、API 版本不匹配、格式错误的描述符和插件加载失败。

请参阅 场景集成指南 了解所有权清单、包布局、注册契约、测试和冒烟配置要求。使用 src/autosaddler/v2/plugins/fake.py 作为最小的确定性示例，使用 src/autosaddler/v2/plugins/meta_are/ 作为生产级 Git 运行环境示例。

我们鼓励您使用编码智能体按照集成指南进行场景集成。

🧰 开发和项目政策

uv sync --extra dev
uv run ruff check src/autosaddler tests/
uv run python -m pytest tests/ -v --tb=short
uv build

欢迎贡献；请参阅 CONTRIBUTING.md。本项目遵循 Microsoft Open Source Code of Conduct，发布其 安全报告政策，并在 MIT License 下提供。

📝 引用

@misc{park2026autosaddlerautomaticharnessoptimization,
      title={AutoSaddler: Automatic Harness Optimization with Durable Updates from Agent Execution Traces},
      author={Sungho Park and Wonjoong Kim and Rongyuan Tan and Jue Zhang and Wook-Shin Han and Pengfei Gao and Chanyoung Park and Yongqiang Yao and Rao Fu and Elsie Nallipogu and Qingwei Lin and Saravan Rajmohan and Dongmei Zhang},
      year={2026},
      eprint={2608.23041},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2608.23041},
}