CLI 命令参考

Runtime 与 Benchmark Suite 使用两个入口：

scientific-agent        普通研究运行与本地 Control API
scientific-agent-bench  外部冻结协议评测

全局存储选项

这些选项必须写在 Runtime 子命令之前：

scientific-agent \
  --data-dir PATH \
  --cache-dir PATH \
  --config-dir PATH \
  <command>
选项 用途 默认
--data-dir 持久 Run、Artifact、Model、Report、Export ~/Documents/ScientificAgent
--cache-dir 下载、build、临时文件、日志等可丢弃数据 平台 cache 目录
--config-dir plugin registry、storage/provider 等普通配置 平台 config 目录

scientific-agent new

创建契约和 RunCreated 事件，但不执行：

scientific-agent new CONFIG [REASONER_OPTIONS]

成功时会先打印运行日志，再单独打印 Run ID，退出码为 0。适合脚本分两步审批：先创建并保存 ID，审核后再 resume。

scientific-agent run

创建并立即执行：

scientific-agent run CONFIG [REASONER_OPTIONS]

CONFIG 可以是 .yaml、.yml 或 .json。最终 SUCCESS 返回 0，其他终态或可恢复状态返回 2，并输出：

DONE run_id=run_... status=<STATUS>

Reasoner override

new 与 run 共用：

选项 含义
--reasoner config 使用配置文件（默认）
--reasoner real 强制真实 LLM Reasoner
--reasoner deterministic 强制插件提供的确定性 Reasoner
--provider NAME 覆盖 provider；同时会使 Reasoner 走 LLM 路径
--model ID 覆盖 model；同时会使 Reasoner 走 LLM 路径
--temperature N 覆盖采样温度，范围 0–2

示例：

export OPENAI_API_KEY=...
scientific-agent run examples/beam_ml_llm.yaml \
  --reasoner real \
  --provider openai \
  --model <verified-model-id> \
  --temperature 0.2

尖括号表示占位符。务必使用 provider 当前对你的账户开放、且支持所需 structured output 的 model ID。

scientific-agent resume

scientific-agent resume RUN_ID

Runtime 重放事件流并继续同一契约。它可以：

  • 启动由 new 创建的 CREATED 任务；
  • 继续 PAUSED、BLOCKED、CAPABILITY_MISSING 或已调整预算的 BUDGET_EXHAUSTED 任务；
  • 识别崩溃后残留的 RUNNING 状态并走 interrupted recovery；
  • 复用中断前已经提交的 source、model call 和 checkpoint，避免重复生成。

不能继续 SUCCESS、FAILED 或 CANCELLED。resume 使用创建时持久化的 plugin、provider、model 和 capability contract，不接受临时模型覆盖。

scientific-agent status

scientific-agent status RUN_ID
scientific-agent status RUN_ID --events

JSON 包含 goal、status、metrics、预算使用量、Reasoner/provider/model 配置、失败、实验、jobs、最新小结果和所有 research-visible artifact references。--events 再输出序号、时间、event type 和 caused-by action，不会输出 artifact 大内容或 evaluator-private 数据。

用于脚本时可以配合 jq：

scientific-agent status "$RUN_ID" | jq -r '.status'
scientific-agent status "$RUN_ID" | jq '.metrics, .budget_usage'

scientific-agent serve

启动本地 Control API 和打包好的 React UI：

scientific-agent serve \
  --host 127.0.0.1 \
  --port 8000 \
  --plugin-dir ./plugins
  • --host 默认 127.0.0.1；开发模式没有登录认证，保持 loopback。
  • --port 默认 8000。
  • --plugin-dir 可重复，指定服务器批准的插件根目录。未指定且当前目录有 plugins/ 时会自动使用该目录。
  • UI：http://127.0.0.1:8000/
  • OpenAPI：http://127.0.0.1:8000/api/v1/docs

需要全无界面操作时见无界面 Control API。

Benchmark 命令

Benchmark 的全局 --data-dir 默认 .scientific-agent，同样必须放在子命令之前。

scientific-agent-bench run

scientific-agent-bench --data-dir .bench-data run CONFIG \
  --runs 3 \
  --output report.json \
  [REASONER_OPTIONS]

运行多个独立 Scientific Reasoner trial，并输出机器可读报告。未指定 output 时写入 <data-dir>/benchmarks/latest-report.json。

scientific-agent-bench generalization

scientific-agent-bench generalization SPEC \
  --output benchmark-report.json \
  --markdown benchmark-report.md \
  [REASONER_OPTIONS]

运行冻结的 v0.6 generalization 协议：研究成功后用未见 holdout 检查冻结 predictor，并与基线/不同预算比较。

scientific-agent-bench difficulty

scientific-agent-bench difficulty SPEC --prepare-only
scientific-agent-bench difficulty SPEC \
  --output benchmark-report.json \
  --markdown benchmark-report.md \
  [REASONER_OPTIONS]

--prepare-only 只固定私有数据和协议身份，不开始 LLM run。再次运行同一 spec 会继续未完成 slot，不重复已完成的研究或 holdout 工作。

历史 scientific-agent benchmark、benchmark-generalization、benchmark-difficulty 仍由控制台兼容包装器转发并打印 Deprecated；新脚本应始终使用 scientific-agent-bench。

退出码与错误

退出码 含义
0 命令级成功；对 run/resume 表示最终 SUCCESS
2 参数/配置/查找错误，或运行未到 SUCCESS；Benchmark 没有有效成功结果

错误写到 stderr，通常以 error: 开头。不要只依赖进程输出中的最后一行；自动化同时检查退出码和持久化 status。

找到 条结果：“”

    没有找到匹配结果：“”