无界面 Control API

Control API 是桌面端使用的同一控制面，也可用于服务器、脚本和实验室自动化。日常只跑一个配置时，优先使用 scientific-agent run；需要创建、暂停、查询、上传产物或接收实时事件时再使用 API。

启动服务

在第一个终端运行：

scientific-agent \
  --data-dir ./research-data \
  serve --host 127.0.0.1 --port 8000

在第二个终端检查：

curl -sS http://127.0.0.1:8000/api/v1/health | jq

交互式接口说明位于 http://127.0.0.1:8000/api/v1/docs。serve 是无认证的本地开发模式，请保持监听地址为 127.0.0.1，不要直接暴露到局域网或互联网。桌面应用会使用临时令牌启动自己的受控服务，二者不要混用。

一次完整的 API 运行

先把请求保存为 run.json：

{
  "title": "API toy run",
  "goal": "Reach a score of at least 0.9",
  "acceptance": {
    "metric": "score",
    "operator": ">=",
    "value": 0.9
  },
  "budget": {
    "max_actions": 5,
    "max_experiments": 3,
    "max_failures": 2
  },
  "capabilities": ["toy.evaluate"],
  "research_questions": ["Can the deterministic candidate pass?"],
  "reasoner": {"type": "deterministic"}
}

预览合同，不写入运行：

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data @run.json \
  http://127.0.0.1:8000/api/v1/runs/preview | jq

创建并记下 run_id：

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data @run.json \
  http://127.0.0.1:8000/api/v1/runs | tee created.json | jq

RUN_ID=$(jq -r '.summary.run_id' created.json)
curl -sS -X POST "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/start" | jq

查询状态和事件：

curl -sS "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/state" | jq
curl -sS "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/events?cursor=0&limit=100" | jq

实时更新

Server-Sent Events 流适合进度面板或守护脚本：

curl -N "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/stream?after=0"

每条更新都有递增游标。断线重连时把上次游标放入 after，或发送 Last-Event-ID 请求头，就不会从头读取。

生命周期操作

curl -sS -X POST "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/pause" | jq
curl -sS -X POST "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/resume" | jq
curl -sS -X POST "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/recover" | jq
curl -sS -X POST "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/cancel" | jq

recover 只适用于中断后存在恢复点的运行。对取消和恢复请求，可加唯一的 X-Idempotency-Key，让脚本重试时不会重复执行命令。

Ask 与人工介入

Ask 根据已有研究记录回答问题，并返回可定位到事件、指标、作业或产物的引用：

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data '{"message":"Why is the run not complete?"}' \
  "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/ask" | jq

添加研究备注：

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data '{
    "directive_type":"ADD_RESEARCH_NOTE",
    "reason":"Record an operator observation",
    "note":"Repeat the evaluation if score variance exceeds 0.02"
  }' \
  "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/intervene" | jq

directive_type 还支持 PAUSE_RUN、RESUME_RUN 和 UPDATE_BUDGET。更新预算时，budget 对象只放要修改的字段；max_experiments: null 表示移除实验次数上限。从 BUDGET_EXHAUSTED 自动继续时，至少一项现有限额必须实际提高或移除。所有介入都会留下审计记录。

查询研究结果

常用只读端点如下：

把后缀接到 /api/v1/runs/$RUN_ID。有分页的列表接受 cursor 与 limit，单页最多 250 条。

下载产物时，先从 /artifacts 获取 artifact_id：

curl -sS \
  "http://127.0.0.1:8000/api/v1/runs/$RUN_ID/artifacts/$ARTIFACT_ID/content" \
  -o result.bin

上传输入产物使用 Base64：

{
  "name": "measurements.csv",
  "artifact_type": "OTHER",
  "content_base64": "YSxiCjEsMgo="
}

将它 POST 到 /api/v1/runs/$RUN_ID/artifacts。输入文件应在运行开始前上传。

科学命令

自动化系统可以明确请求分析、报告、假设或验证，而不必伪装成普通聊天：

下面的报告示例假设该运行仍可接受科学命令、合同已经授权 scientific.report.generate，并且已有可见的锚点产物。前面的最小 toy 合同没有授权报告能力，直接复用它会按设计返回能力缺失错误。

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: report-request-001' \
  --data '{
    "command_type":"RequestReport",
    "report_title":"Final assessment",
    "include_figures":true,
    "reason":"Prepare the review package"
  }' \
  "http://127.0.0.1:8000/api/v1/runs/$REPORT_RUN_ID/scientific-commands" | jq

命令类型包括 RequestAnalysis、RequestReport、SubmitHypothesis、CreateVerificationPlan、ApproveVerificationPlan、RequestVerification 和 UpdateHypothesisStatus。不同命令需要不同引用和字段；以 /api/v1/docs 中的 ScientificCommandRequest 为准。

能力、插件、存储和导出

curl -sS http://127.0.0.1:8000/api/v1/capabilities | jq
curl -sS http://127.0.0.1:8000/api/v1/plugins | jq
curl -sS http://127.0.0.1:8000/api/v1/storage/info | jq
curl -sS -X POST http://127.0.0.1:8000/api/v1/storage/backups | jq

插件可通过 POST /plugins/{plugin_id}/install、/enable 和 /disable 管理。自定义 ZIP 使用 POST /plugins/custom/install，请求体字段为 filename 和 content_base64。安装只验证并保存包；启用才会导入代码。

成功运行可创建便于移交的科学导出：

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data "{\"run_id\":\"$RUN_ID\",\"name\":\"review-package\"}" \
  http://127.0.0.1:8000/api/v1/exports | jq

自动化注意事项

• 先调用 /health，再创建运行。
• 先预览合同并检查 valid、warnings，再正式创建。
• 保存 run_id、命令幂等键和 SSE 游标。
• 解析 JSON 状态，不要根据终端文字猜测成功与否。
• 不要绕过 API 直接修改事件文件或产物目录。
• 多用户或远程部署需要另行配置反向代理、认证和 TLS；内置 serve 本身不是公网服务。