AnyExperimentLoop

Any Experiment Loop (AEL)

AutoResearch Harness — 让 AI Agent 自动化做算法研究。 Any Experiment Loop (AEL) is a local-first autoresearch harness: an autonomous AI research agent loop that turns natural-language goals into reproducible experiments — automated algorithm research for Kaggle competitions, quantitative trading strategies, RAG pipelines, prompt engineering, and performance tuning.

Keywords: autoresearch · auto research · automated algorithm research · AI research agent · autonomous experimentation · experiment loop · AI scientist · Kaggle automation · quantitative strategy research · RAG evaluation · prompt optimization · reproducible experiments · local-first AI agent

什么是 AutoResearch（自动研究循环）

AutoResearch 是 AEL 的核心概念：把“做研究”变成一个可审计、可暂停、可复现的自动化循环。用户不再手动跑实验、记结论，而是描述目标，由 AI Agent 自主完成 提出假设 → 构建候选 → 运行实验 → 独立评价 → 沉淀经验 的闭环：

• 自然语言即研究计划：一句“提高 ROC AUC、不用外部数据”会被编译成冻结的目标契约（GoalPolicy）和评价协议（ExperimentProtocol）；
• 假设驱动的实验循环：固定 Research → Experiment → Synthesis Cycle，先建 baseline，再串行测试有界候选方案，目标达成或预算耗尽自动停止；
• 证据说话，而非 Agent 自夸：独立 Evaluator 只看冻结的物化证据，Developer 不能宣告自己的候选成功；
• 研究经验跨 Run 沉淀：只有被证据支持的 finding 才写入 Memory，供后续 Run 复用——这正是 autoresearch 相对“一次性脚本”的价值。

Any Experiment Loop（AEL）是一款面向个人用户、本地优先的通用 autoresearch 实验循环软件。用户只需要用自然语言描述“想完成什么项目、怎样算更好、有哪些限制”，AEL 负责把需求编译成可执行契约，并调用 AI 自动完成研究、开发、实验、独立评价、总结和经验沉淀。

AEL 不限定任务必须是机器学习或单一数值优化，它不但能帮你自动化打 Kaggle 比赛，也可以帮你自动化研究炒股量化策略、优化 RAG 检索质量、迭代 prompt 和做性能调优——任何“有可度量指标、可反复实验”的算法研究任务都适用。

产品需求见 design_docs/PRD.md，技术架构见 design_docs/any_experiment_loop_architecture.md。

AutoResearch 工作流：AEL 如何工作

一次完整使用分成 Preparation 和 Run 两部分：

用户自然语言需求
  → Preparation Agent 只读检查 workspace
  → 编译 ProjectSpec、GoalPolicy、ExperimentProtocol
  → 独立 Policy Verifier 检查目标、证据和执行边界
  → 创建并冻结 Run
  → Research 提出有界候选方案
  → Baseline Builder + 离线执行 + 证据冻结
  → Developer Builder + 离线候选实验
  → Independent Evaluator 根据证据比较 baseline/candidate
  → Synthesis 生成报告并写入可追溯 Memory

核心分工：

• AI Agent 负责理解问题、提出假设、编写候选代码和解释开放语义；
• Python 控制状态、预算、权限、命令执行、快照、证据和停止条件；
• Builder Agent 不能直接使用 Bash，只返回结构化 argv；
• AEL 使用 shell=False 执行本地命令，并在 macOS 上通过系统 sandbox 阻断实验子进程网络和越界写入；
• 独立 Evaluator 不读取 Research/Developer Skill 或历史经验，只依据冻结 GoalPolicy 和当前物化证据判断；
• Agent session 是推理缓存，本地 checkpoint 才是 Run 的事实来源。

固定 Cycle 为 Research → Experiment → Synthesis。Experiment 阶段先建立不占候选预算的 000-baseline，随后串行测试候选。目标达到、idea 耗尽或预算耗尽时停止。

如何使用

推荐：通过 AEL Operator Skill 使用自然语言

面向 Agent 的入口是 AEL Operator Skill。用户不需要区分 problem、goal 或记忆 CLI 参数，可以直接在 agent (例如 claude code 或 codex) 里描述：

使用这个目录中的 Kaggle 题目和数据建立可复现 baseline，在固定交叉验证下提高 ROC AUC。不使用外部数据，不改变训练集和测试集范围，最终生成 submission.csv。先运行 1 个 Cycle，最多 2 次实验。

Operator 会调用 AEL Preparation；信息不足时，只把最多三个真正阻塞的问题反馈给用户。权限、评价方向、成功阈值或研究对象范围不会被静默猜测。

直接使用 CLI

python3 -m pip install -e .
ael init

ael --json prepare ./workspace \
  --request "建立可复现 baseline，并在固定验证方案下提高 ROC AUC" \
  --allow-workspace-read \
  --allow-workspace-write \
  --allow-command

ael plan
ael run
ael status
ael pause
ael resume
ael report

若 Preparation 返回 needs_input：

ael --json prepare ./workspace \
  --instruction "使用五折交叉验证 ROC AUC，越高越好；训练集范围保持不变。"

主要命令：

• prepare：从自然语言生成、验证并保存公开 ProjectSpec；
• plan：显示目标、比较规则、证据、可编辑范围、权限和预算；
• run：启动一个新的冻结 Run；
• pause / resume：协作式暂停并恢复同一个 Run；
• rewind：将暂停 Run 的当前 Cycle 从 Research 可恢复地重试，旧工件进入审计归档；
• status：读取耐久状态；
• report：读取完成后的 REPORT.md。
• paths：显示 preparation、ProjectSpec、当前 Idea Portfolio、状态、日志和报告的绝对路径；
• runs：列出项目的全部 Run；
• inspect：聚合查看某个 Run、Cycle 或 Experiment 的耐久事实；
• timeline：读取结构化事件时间线；
• rebuild-views：从 JSON/JSONL 事实重建 INDEX.md、TIMELINE.md 和 FACTS.md；
• status --verbose/--watch：显示 active idea/role、预算和下一动作，或持续观察状态变化。

--runtime-binary 保持向后兼容，但它指 Agent Provider CLI；新命令建议使用更明确的 --agent-runtime-binary。实验 Python 由冻结的 ExperimentProtocol 与命令 argv 决定。

开发源码时可指定本地数据目录：

PYTHONPATH=src python3 -m ael --home .ael-dev --json status <project-id>

正式安装不默认使用仓库中的 .ael-dev；它会使用操作系统标准的用户数据目录。

Quickstart：公开合成示例

仓库提供了一个 Playground Series S6E8 风格 input-only 示例。它只提交人提供的任务信息、合成同 schema 小数据和预期行为，不提交 Agent 生成的 solution 或任何真实 Kaggle 数据。

python3 -m pip install -e .
cp -R examples/playground-series-s6e8 projects/demo-s6e8

ael --json prepare projects/demo-s6e8 \
  --name demo-s6e8 \
  --request "$(cat projects/demo-s6e8/request.txt)" \
  --allow-workspace-read \
  --allow-workspace-write \
  --allow-command

ael plan demo-s6e8
ael run demo-s6e8
ael report demo-s6e8

prepare 若需要澄清，按返回的 blocking_questions 使用 --instruction 补充即可。完整环境要求、输出边界和真实比赛数据使用方式见示例说明。

权限和执行边界

运行期执行策略只由 ael run/resume --security-level 控制，并由 Research、Developer、 依赖安装器和命令沙箱共享：

• standard（默认）：允许 /usr/bin/python3 -m pip install ...；
• offline：禁止包安装并阻断网络；
• network：允许 pip 和 uv。

安装不再额外检查 network.read、data.download 或 subject_universe.installable_packages。prepare --allow-network/--allow-download 仅为旧 ProjectSpec capability 元数据的兼容入口，不控制 pip。

其他能力未经明确授权：

• workspace 读、写和本地命令保持 require_confirmation；
• 外部数据源、远程任务和部署默认 deny；
• Skill 不能自行扩大权限；
• Run 启动后 GoalPolicy、ExperimentProtocol、Subject Universe、Skill 版本和经验上下文均被冻结。

command.execute=allow 不等于把 Bash 交给模型。Developer Builder 只负责写入冻结的 editable_roots 并返回 argv；AEL Runner 仍拒绝 shell、网络客户端、inline Python 和 不在可执行边界中的程序，包管理器则仅按全局 security-level 放行。实验产物会复制进 Run 并计算 SHA-256，避免后续实验覆盖历史证据。

当前 OS 级离线隔离适配器只实现并实测了 macOS；其他平台在没有对应隔离适配器时 fail closed，不会降级成不受控执行。

Skill 和持续积累的经验

用户可以显式声明本地 SKILL.md：

ael prepare ./workspace --request "..." --skill ./skills/tabular-ml
ael prepare ./workspace --request "..." --research-skill ./skills/modeling-ideas
ael prepare ./workspace --request "..." --developer-skill ./skills/tuning-rules

• --skill 同时用于 Research 和 Developer；
• 阶段参数可限制 Skill 只影响研究或开发；
• AEL 在 Run 启动时冻结 Skill 正文、来源和 SHA-256；
• pause/resume 不会重新读取变化后的 Skill；
• Synthesis 只把 supported_findings 和 confirmed_deadends 写入 Memory；
• 每条 Memory 包含 Project、Run、来源工件和 Evaluation 证据引用；
• unknown 和未验证假设不会进入长期 finding；
• 新写入的经验只影响后续 Run，不改变当前 Run。

外部知识库调用需要额外的 Tool/Adapter 和对应网络权限；加载 Skill 本身不等于授权外部访问。

本地数据目录

使用 --home .ael-dev 时，非临时的正式目录如下：

.ael-dev/
├── preparations/                  # 自然语言准备、澄清历史和 Preparer session
├── projects/
│   └── <project-id>/
│       ├── project.json           # 项目索引信息
│       ├── project.spec.yaml      # 用户可见 ProjectSpec
│       ├── prepared/
│       │   ├── goal_policy.json
│       │   ├── experiment_protocol.json
│       │   ├── policy_verification.json
│       │   └── manifest.json
│       └── runs/<run-id>/
│           ├── frozen_run_spec.json
│           ├── state.json
│           ├── events.jsonl
│           ├── cycles/001/
│           │   ├── research/
│           │   ├── experiments/
│           │   │   ├── 000-baseline/
│           │   │   └── 001/
│           │   └── synthesis/
│           ├── snapshots/
│           ├── sessions/
│           ├── logs/
│           ├── rewinds/           # 被 rewind 的旧工件和原因
│           └── REPORT.md
└── memory/                        # 跨 Run、带 provenance 的经验条目

各目录角色：

• preparations/：Project 尚未 ready 时也能保存用户原文、workspace 摘要和澄清进度；
• projects/：正式项目、冻结 Run、状态机、实验、证据、快照、报告和审计记录；
• memory/：供未来 Run 检索的已验证经验，不保存未证实推测。

runner-validation、runner-network-validation 等名称是开发期间的临时探针目录，不属于正式产品目录结构。

用户业务 workspace 只保存被授权修改的候选文件，例如 solution/；AEL 的状态、session 和证据副本保存在数据目录，不把管理文件散落到业务项目中。

JSON、JSONL 和 YAML 始终是唯一运行事实。为方便人阅读，ael rebuild-views 会生成可删除、 可重建的 Markdown 派生视图；这些 Markdown 不参与 resume 或状态判断。运行期 Agent 输出会经过 Provider JSON Schema、本地 schema 验证和有界格式修复，格式修复不会重复已 checkpoint 的训练命令。

真实案例：Kaggle Playground Series S6E8

测试任务：根据 691,369 行训练数据预测 smartphone addiction，指标为 ROC AUC；对 296,302 行测试数据输出 id,addicted_label 概率。最新韧性回归案例冻结为固定五折交叉验证、不使用外部数据、不改变 train/test 样本范围、无目标泄漏、最多 2 个 Cycle、每个 Cycle 最多 2 个候选实验。下述较早的公开 Run 采用 1 Cycle、最多 2 个候选实验。

完整 Run：20260810T055040037436Z-6aba9821，最终状态 completed / goal_reached。

AutoResearch 实战：2 次迭代实验结果

方案	固定 5 折 CV ROC AUC	标准差
LogisticRegression baseline	0.911449	0.000811
HistGradientBoosting candidate	0.962676	0.000514

候选相对 baseline 提升 +0.051227 AUC。候选五折分别为 0.961955 / 0.962483 / 0.963112 / 0.963394 / 0.962436。独立 Evaluator 根据三份冻结证据判定 better / reached，因此未继续消耗第二个候选实验预算。

最终 submission 全量 QA：

• 296,302 行，列为 id,addicted_label；
• ID 与 test.csv、sample_submission.csv 完全一致；
• 重复 ID 0，NaN 0；
• 概率范围 [0.00024548, 0.99999889]，范围外记录 0。

真实数据、生成的 solution 和完整 Run 证据均为本地隐私产物，我没有提交到 Git。仓库中的公开合成示例复用了相同任务 schema 和用户输入方式，供开源用户低成本复现实验流程；其数值不能与上述真实案例成绩比较。用户如果想复现实现效果，请自行下载 Kaggle 真实比赛数据、训练和测试集，不同的后端 LLM 能力不同，可能会产生不同的实验结果，当前实验结果采用 Kimi K3 模型获得。

当前实现与开发

当前 MVP 包含：

• provider-neutral domain contracts 和 AgentRuntime 接口；
• Claude Code Runtime 与离线测试用 FakeRuntime；
• 原子本地 Project/Run Store；
• 独立 Research、Developer、Evaluator、Synthesis Agent；
• sequential search、baseline bootstrap、文件 snapshot 和实验 checkpoint；
• run/pause/resume/rewind/status/report 与 --json 机器接口；
• 用户 Skill、冻结 ExperienceContext 和 provenance-first LocalFolderKnowledgeStore。

运行时要求 Python 3.9+；这与本仓库真实 Kaggle 案例使用的 /usr/bin/python3 3.9.6 一致。

运行测试：

PYTHONPATH=src python3 -m unittest discover -s tests -v

设计原则

• 自然语言是用户接口，结构化契约是系统接口；
• Python 管状态、预算、权限、执行协议和证据边界；
• Agent 会话是推理缓存，本地 checkpoint 是事实；
• 默认本地、私密、串行、可恢复；
• 不建设企业平台或通用 DAG；
• 新 Provider、任务、Skill、Tool 和搜索策略通过小接口扩展。

License

本项目基于 MIT License 开源，可自由用于个人与商业场景。