研究配置文件
配置文件把一次研究的目标、通过条件、预算和可用工具固定下来。桌面端会替你生成同样的“研究合同”；纯命令行用户可以直接写 YAML 或 JSON。
一个可直接运行的最小配置
title: "阻尼振子检查"
goal:
description: "确认参考阻尼振子的品质因数不小于 3"
acceptance:
metric: quality_factor
operator: ">="
value: 3.0
budget:
max_actions: 3
max_experiments: 1
max_failures: 1
plugins:
- examples/plugins/oscillator_quality
capabilities:
- tutorial.oscillator.evaluate
research_questions:
- "参考振子的品质因数是多少？"
仓库中已经提供了这份文件：examples/plugin_tutorial.yaml。运行它：
scientific-agent run examples/plugin_tutorial.yaml
必填内容
| 字段 | 用途 | 实用建议 |
|---|---|---|
goal |
用一句可验证的话描述要完成什么 | 避免只写“研究一下” |
acceptance |
首要通过条件 | 指标名必须由某个所选能力产出 |
budget |
本次运行的资源上限 | 至少保留 max_actions 和 max_failures |
plugins |
插件目录或内置插件名 | 每个配置至少声明一个 |
capabilities 建议显式填写。它是本次研究可以调用的能力白名单；省略时，为兼容旧配置，会开放所选插件提供的全部能力。
通过条件
单项条件由指标、比较符和值组成。比较符可以是 >=、>、<=、< 或 ==。
acceptance:
metric: balanced_accuracy
operator: ">="
value: 0.90
require_trusted: true
require_trusted: true 表示只有受信任评估器报告的指标才能满足条件，适合防止训练代码自己给自己打分。
需要同时满足多项条件时，acceptance 必须与 acceptance_criteria 的第一项相同；不同条件的指标名不能重复：
acceptance:
metric: balanced_accuracy
operator: ">="
value: 0.90
require_trusted: true
acceptance_criteria:
- metric: balanced_accuracy
operator: ">="
value: 0.90
require_trusted: true
- metric: inference_seconds
operator: "<="
value: 2.0
预算
不需要把每个预算项都写上。未填写的可选项不设该类上限；默认 max_actions: 10、max_failures: 3、max_repair_attempts: 1。
budget:
max_actions: 12
max_experiments: 8
max_failures: 3
max_wall_time: 3600
max_tokens: 200000
max_cpu_hours: 4
max_gpu_hours: 1
max_training_runs: 3
max_training_samples: 50000
max_solver_calls: 6
max_reasoner_calls: 12
max_reasoner_tokens: 240000
max_model_calls: 20
max_model_tokens: 300000
max_code_generation_calls: 4
max_code_repair_calls: 3
max_repair_attempts: 1
运行中的剩余预算可在控制室查看，也可以通过人工介入受控调整。若要从 BUDGET_EXHAUSTED 继续，必须提高已耗尽的上限，或把实验次数上限明确改为 unlimited。Runtime 不会静默超额。
推理器
插件可以提供确定性推理器，因此教学和回归示例不需要联网：
reasoner:
type: deterministic
让语言模型规划研究时，声明提供方和模型：
reasoner:
type: llm
provider: openai
model: YOUR_MODEL_ID
temperature: 0.2
max_output_tokens: 24000
timeout_seconds: 180
max_provider_retries: 1
max_schema_repairs: 1
prompt_version: scientific-reasoner-v1
命令行的 --reasoner、--provider、--model 和 --temperature 可以覆盖文件中的推理器设置，适合临时试验。
提供方与密钥
密钥只放环境变量，不要写入 YAML：
export OPENAI_API_KEY="你的密钥"
providers:
openai:
api_format: openai_responses
auth_env: OPENAI_API_KEY
structured_output_mode: json_schema
OpenAI 兼容端点可以这样声明：
providers:
lab_gateway:
api_format: openai_chat_completions
base_url_env: LAB_MODEL_BASE_URL
auth_env: LAB_MODEL_API_KEY
structured_output_mode: tool_call
可用格式为 openai_responses、openai_chat_completions 和 anthropic_messages。结构化输出模式为 json_schema、json_object 或 tool_call；Anthropic 格式只接受 json_schema 或 tool_call。base_url 必须是完整的 HTTP(S) 地址，也可通过 base_url_env 间接提供。
按角色选择模型
简单任务只用一个模型即可。需要分别控制科学推理、代码生成和代码修复时，使用模型档案：
models:
profiles:
reasoner:
provider: codex-cli
model: YOUR_REASONING_MODEL
structured_output: true
coder:
provider: lab_gateway
model: YOUR_CODING_MODEL
coding: true
repairer:
provider: lab_gateway
model: YOUR_REPAIR_MODEL
coding: true
fallback_profiles: [coder]
routing:
strategy: role_separated
scientific_reasoning: reasoner
code_generation: coder
code_repair: repairer
max_fallback_depth: 1
路由策略可选 strong_only、role_separated 和 repair_escalation。这些设置只影响新建运行；已经创建的运行会保留原合同。
能力约束
约束可以冻结评估数据、采样方法或求解器参数，防止推理器在运行中改变比较基准：
capability_constraints:
beam.xsuite.generate_stability_dataset:
- when:
dataset_role: evaluation
require:
num_turns: 128
dataset_role: evaluation
evaluation_id: beam_survival_eval_v1
当一次调用的 when 条件匹配时，Runtime 会要求其输入同时满足 require。约束字段属于对应插件；可先在桌面端能力详情或 GET /api/v1/capabilities/{id} 查看示例。
科学工作流与最终预测器
需要“指标合格并且关键科学产物齐全”时：
workflow:
scientific_verification:
enabled: true
scientific_completion_contract:
enabled: true
required_artifacts:
- scientific_report
- verification_result
需要交付一个冻结的文件式预测器时：
final_predictor:
required: true
interface: file-predictor-v1
input_filename: predictor_input.json
output_filename: predictor_output.json
输入、输出文件名必须不同，并且只能是普通文件名。对应插件需要真正产出符合该协议的模型包；仅打开开关不会自动生成模型。
检查配置
最稳妥的检查顺序是：
- 在桌面端预览研究合同，或通过 Control API 调用
POST /runs/preview。 - 确认每个验收指标都出现在某个能力的
metric_outputs中。 - 用小预算先跑一次，并用
scientific-agent status RUN_ID --events检查过程。
配置解析会拒绝未知比较符、无效预算、明文密钥、缺失插件和无效模型路由。YAML 与 JSON 表达的字段完全相同。