安装并跑通第一次实验¶

这一页只做一件事：从空环境走到一条通过回放验证的 ChemWorld 轨迹。第一次运行建议使用 reaction-to-assay，整个过程通常只需要几分钟。

1. 安装项目¶

需要 Python 3.11 或更高版本。

git clone https://github.com/Knitua/ChemWorld-Public.git
cd ChemWorld-Public
python -m pip install -e ".[dev]"

确认命令行入口已经安装：

chemworld --help
chemworld tasks list

Windows文档与参考验证

如果 python 被解析成 Microsoft Store 别名，可以直接使用仓库虚拟环境：

.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

只有在构建站点或运行扩展物理参考检查时，才需要额外依赖：

python -m pip install -e ".[dev,docs,physchem-ref]"

2. 运行一个完整回合¶

先让内置 Agent 完成一次实验：

chemworld run --task reaction-to-assay --agent random --seed 0

命令会把 trajectory JSONL 和 manifest 写入 runs/，并在终端打印实际路径。这里的 random Agent 不是性能基线；它只是最短的端到端连通性检查。

3. 验证结果¶

把上一步输出的轨迹路径代入下面两条命令：

chemworld verify --constitution --submission runs/<trajectory>.jsonl
chemworld evaluate --submission runs/<trajectory>.jsonl

verify 检查文件结构、合同摘要、状态守恒和确定性回放。
evaluate 从轨迹重新计算结果，不采用提交文件自带的分数。

看到验证通过后，你已经跑通了 ChemWorld 最核心的链路：

任务 → Agent → Action → 环境 → 轨迹 → 回放 → 评分

4. 用 Python 查看环境¶

import gymnasium as gym
import chemworld  # 注册 ChemWorld 环境

env = gym.make("ChemWorld", task_id="reaction-to-assay", seed=0)
observation, info = env.reset(seed=0)

print(info["task_id"])
print(info["physics_maturity"])
print(env.unwrapped.available_actions())

available_actions() 返回当前状态下真正可执行的操作。它比维护一套固定动作模板更可靠，因为不同任务、阶段和物料状态会开放不同操作。

5. 手动执行一个 Action¶

先读取 schema，再在不改变环境状态的情况下校验动作：

schema = env.unwrapped.action_schema("add_reagent")
action = {"operation": "add_reagent", "amount_mol": 0.01}
check = env.unwrapped.validate_action(action)

if check["valid"]:
    observation, reward, terminated, truncated, info = env.step(action)
else:
    print(check["invalid_reasons"])

无效动作会带回 invalid_reasons 和前置条件提示，方便 Agent 修改后重试。任务允许哪些操作、仪器、预算与终止方式，以 reset 信息和任务卡为准。

正确处理未测量值

数组里的未测量值是 NaN，写入 JSONL 后是 null。不要把它当成零；读取数值时同时检查 observed_mask 或 observed_keys。

6. 打开可视化实验室¶

chemworld lab

启动后可以打开：

Agent Observatory：观看 Agent 的逐步决策、谱图与资源消耗。
Student Lab：手动选择操作，观察实验状态变化。

Agent Observatory 目前开放 scripted_chemistry、Random、LHS、Greedy、GP-BO、Safe GP-BO、 Tool-agent Stub 和 LLM Trace Replay。它们都在本机运行且不调用在线模型。页面中的策略对比固定相同任务和 seed，但单 seed 结果只用于理解行为，不能当作 leaderboard 或模型优越性证据。

自定义 Python Agent 和可选在线 Provider adapter 已由正式 runner 支持，接入方式见接入 Agent。Provider 凭据不会进入浏览器服务。

接下来做什么¶

如果你想……	继续阅读
换一个更复杂的任务	查看世界能力地图
编写自己的 Agent	从动作 schema 开始
理解每种操作的含义	认识操作语言
做可复现的方法比较	阅读公开协议