命令行快速开始

纯命令行模式适合服务器、SSH、脚本和 CI。它直接运行 Runtime，不需要桌面应用或浏览器。

1. 安装

需要 Python 3.11 或更高版本。在仓库根目录执行：

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'

Windows PowerShell 激活命令是：

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

确认命令可用：

scientific-agent --help
scientific-agent-bench --help

如果不安装，也可以从源码运行：

PYTHONPATH=src python -m scientific_agent run examples/toy.yaml

2. 运行确定性示例

scientific-agent run examples/toy.yaml

结尾应类似：

[Metric] score = 0.93
[CriteriaEngine] Acceptance criteria satisfied
DONE run_id=run_... status=SUCCESS

保存 run_...，随后检查状态：

scientific-agent status run_...
scientific-agent status run_... --events

status 输出 JSON 汇总；--events 追加可读的事件类型和 action 关联。退出码 0 表示命令成功，run/resume 在非 SUCCESS 状态下返回 2。

3. 只创建、不执行

scientific-agent new examples/toy.yaml

命令会写入不可变 RunCreated 事件并打印 Run ID。稍后执行：

scientific-agent resume run_...

resume 也用于恢复进程崩溃后处于 RUNNING 的任务，以及继续 PAUSED、BLOCKED、CAPABILITY_MISSING 或 BUDGET_EXHAUSTED 任务。需要调整预算时，应先通过桌面端或 Control API 写入新的限额，再 resume。

4. 选择数据位置

全局选项必须写在子命令之前：

scientific-agent \
  --data-dir /srv/scientific-agent/data \
  --cache-dir /srv/scientific-agent/cache \
  --config-dir /srv/scientific-agent/config \
  run examples/toy.yaml

未指定时，研究数据默认保存在 ~/Documents/ScientificAgent。缓存和普通配置使用平台自己的 cache/config 目录，不与科学数据混放。

5. 运行本教程插件

仓库包含一个零依赖、可完整运行的插件示例：

scientific-agent run examples/plugin_tutorial.yaml

它计算阻尼振子的 quality_factor=4，创建 oscillator-assessment.json，并由 quality_factor >= 3 结束任务。完整开发过程见从零开发可用插件。

6. 可选科学栈

只有对应任务才需要额外依赖：

python -m pip install -e '.[dev,beam-xsuite]'
scientific-agent run examples/beam_xsuite.yaml

python -m pip install -e '.[dev,beam-ml]'
scientific-agent run examples/beam_ml.yaml

真实模型调用可安装 llm 或组合 extra，并把密钥放在环境变量中。不要把 API key 写进 YAML。

下一步：完整 CLI 命令和研究配置文件。