使用内置与第三方插件
插件把 Scientific Agent 的研究循环连接到具体领域、求解器、评估器和报告工具。创建运行时，你选择的是插件公开的“能力”，例如 toy.evaluate，而不是让 Reasoner 任意调用本机程序。
插件状态
插件页会显示以下状态：
| 状态 | 含义 |
|---|---|
| Available | 目录中有能力声明，但尚未安装 |
| Installed | 已保存和验证，但尚未允许加载代码 |
| Enabled | 可用于新运行，并会加载插件代码 |
| Disabled | 已安装，但不向新运行提供能力 |
| Unavailable | 缺少依赖或当前环境不满足要求 |
已创建的研究合同会保留自己的插件和能力记录。启用、禁用或更新插件主要影响后续新运行。
随发行版提供的能力
实际列表取决于安装方式和可选依赖。可在 Settings → Plugins 或 /api/v1/capabilities 查看当前机器的权威列表。
| 插件 | 主要能力 | 适用场景 |
|---|---|---|
| Toy Dynamics | toy.evaluate |
无网络的入门与健康检查 |
| Local Executor | execution.local.run |
在受控工作区运行生成的本地作业 |
| Xsuite Beam Dynamics | beam.xsuite.track_particles、beam.xsuite.generate_stability_dataset |
参考加速器晶格的粒子跟踪与数据生成 |
| Model Evaluation | evaluation.classification.evaluate |
对分类预测做受信任评估 |
| Three-Body Trajectory Evaluation | evaluation.three_body_trajectory.evaluate |
对三体轨迹预测做受信任评估 |
| Scientific Analysis | scientific.analysis.analyze |
从数据、模型和评估结果生成分析 |
| Scientific Knowledge | scientific.evidence.extract 等 |
证据、主张、假设与验证记录 |
| Report Generator | scientific.report.generate |
Markdown 科学报告与 SVG 图表 |
仓库还带有两个可运行的教学领域插件：
physics.three_body：三体积分和代理模型数据集生成；tutorial.oscillator：本手册插件教程使用的零依赖振子示例。
目录中的 Geant4 Transport 和 Plasma Simulation 是带依赖要求的可用能力声明。只有环境依赖齐备且存在可加载适配器时才能启用；“看得到卡片”不代表求解器已经安装。
在桌面端使用插件
- 打开 Settings → Plugins。
- 按 Core 或 Domain 分类查找插件。
- 展开插件，检查能力、输入、产出指标、依赖和 Runtime 要求。
- 对 Available 插件选择 Install。
- 依赖满足后选择 Enable。
- 新建运行，在 Capabilities 部分只勾选本次研究需要的能力。
如果插件显示缺少依赖，应用不会替你自动执行 pip install。先阅读插件给出的依赖版本，在 Scientific Agent 所使用的 Python 环境中安装，再重新打开或刷新插件页。
在命令行中使用插件
配置文件的 plugins 可以写仓库相对目录、绝对目录或内置别名：
plugins:
- examples/plugins/three_body_solver
- executor.local
capabilities:
- physics.three_body.solve
- execution.local.run
然后照常运行：
scientific-agent run my-study.yaml
启动 Control API 时，可以重复使用 --plugin-dir 添加发现目录：
scientific-agent serve \
--plugin-dir ./my-plugins/one \
--plugin-dir ./my-plugins/two
查看已发现能力：
curl -sS http://127.0.0.1:8000/api/v1/capabilities | jq
安装自定义 ZIP
桌面端选择 Install custom plugin，然后选择 .zip 文件。一个合格包必须：
- 包含且只包含一个可判定的插件清单：
plugin.yaml、plugin.yml或plugin.json； - 清单中的
entrypoint能在包内导入； - 不含绝对路径、路径穿越、符号链接、加密项或重复项；
- 压缩后不超过 10 MiB，解压后不超过 50 MiB，文件数不超过 512。
安装阶段会先完成 ZIP 与清单验证，不导入 Python 代码。只有 Enable 时才真正导入。依赖不会自动安装。
如何选择能力
打开能力详情，重点看四项：
required_inputs：Reasoner 每次调用必须提供的普通输入；artifact_inputs：必须引用的既有产物及其类型；metric_outputs：可以支持哪些验收条件；example与cost_hints：合法输入形状和一次调用的大致资源成本。
若多个插件提供同一抽象能力，能力详情会列出各 provider。研究合同最终记录具体提供者，避免日后环境变化导致同一名称悄悄换实现。
Core 与 Domain
- Domain 插件表达物理领域或问题领域的操作，例如三体积分和束流跟踪。
- Core 插件提供跨领域基础工作，如执行、评估、分析、知识管理和报告。
分类只用于发现和理解，不表示权限高低。真正的特殊权限来自 trusted_evaluator 访问角色，而且应该只授予独立评估器。
安全边界
启用的插件与 Scientific Agent 进程拥有相同的本机权限，不是沙箱代码。只安装你信任来源的包，并在启用前查看清单、依赖和源代码。
Local Executor 会限制工作目录、声明的输入输出和作业协议，但它不是针对恶意代码的容器。处理陌生插件、陌生生成代码或高价值数据时，应额外使用操作系统账户、容器或虚拟机隔离。
插件出错时
按这个顺序检查：
- 插件是否为 Enabled，而不只是 Installed。
missing_dependencies是否为空。- 研究合同是否勾选了正确能力。
- 输入字段名和产物类型是否与能力详情一致。
- 控制室 Failure、Jobs 与日志中是否有
load_error或执行错误。
如果插件升级改变能力名或输入格式，请复制旧运行配置并显式迁移；不要修改已经开始运行的研究合同。