使用内置与第三方插件
插件把 Scientific Agent 的研究循环连接到具体领域、求解器、评估器和报告工具。创建运行时，你选择的是插件公开的“能力”，例如 toy.evaluate，而不是让 Reasoner 任意调用本机程序。
插件状态
插件页会显示以下状态：
| 状态 | 含义 |
|---|---|
| Available | 目录中有能力声明，但尚未安装 |
| Installed | 已保存和验证，但尚未允许加载代码 |
| Enabled | 可用于新运行，并会加载插件代码 |
| Disabled | 已安装，但不向新运行提供能力 |
| Unavailable | 依赖准备、worker 探测或环境要求失败 |
已创建的研究合同会保留自己的插件和能力记录。启用、禁用或更新插件主要影响后续新运行。
预装与按需安装
桌面发行版预装 7 个经过审查的项目插件包。通用包和零依赖符号回归基线可与 Runtime Core 同进程运行；Beam 属于应用所有，但 Xsuite 使用隔离插件环境：
| 插件 | 主要能力 | 适用场景 |
|---|---|---|
beam.xsuite |
粒子跟踪、稳定性数据集 | Xsuite lattice 研究与私有 oracle 标签 |
evaluation.classification |
evaluation.classification.evaluate |
受信任分类评估 |
evaluation.regression |
evaluation.regression.evaluate |
受信任数值回归评估 |
ml.symbolic_regression.builtin |
ml.symbolic_regression.fit |
确定性候选公式基线 |
scientific.analysis |
scientific.analysis.analyze |
从数据、模型和评估结果生成分析 |
scientific.knowledge |
scientific.evidence.extract 等 |
证据、主张、假设与验证记录 |
scientific.report |
scientific.report.generate |
Markdown 科学报告与 SVG 图表 |
toy 和 executor.local 仍是 Runtime 内的参考别名，不属于受管理插件包。Settings → Plugins 或
/api/v1/capabilities 是当前机器实际可用能力的权威来源。
通用 ml.symbolic_regression PySR provider 会作为本地 Available Catalog 包随应用交付，并在符号搜索任务租用它时安装到隔离环境；已启用的 builtin 只是有界多项式基线，不会静默替代 PySR。三体等其他专用插件不打包进应用。源码 checkout 可以通过明确允许的本地目录提供它们，用户也可安装单独获取的自定义 ZIP。当前版本没有远程插件市场。仓库还带有可运行的教学领域插件：
physics.three_body：三体积分和代理模型数据集生成；tutorial.oscillator：本手册插件教程使用的零依赖振子示例。
在桌面端使用插件
- 打开 Settings → Plugins。
- 按 Core 或 Domain 分类查找插件。
- 展开插件，检查能力、输入、产出指标、依赖和 Runtime 要求。
- 对 Available 插件选择 Install。
- 等待 Desktop 自动准备该插件的私有依赖环境。
- 审查 manifest 后选择 Enable；只有这一步会在 worker 中探测/导入插件代码。
- 本地 Catalog 出现更高版本时，列表和详情会显示“当前版本 → 可用版本”；选择 Update 后，原来的 Enabled 或 Disabled 状态会保留。
- 默认新建页会根据任务与附件自动租用所需能力；若使用 Advanced setup，则只勾选本次研究需要的能力。
详情区域允许在更新前检查候选包的依赖、能力、运行要求和完整 manifest。更新会先复制到临时目录，验证 manifest、依赖和 worker，再替换已安装目录；替换或状态保存失败时会恢复旧版本。正在被未结束运行使用的插件不能更新。内置插件没有单独的 Update 按钮，它们随 Runtime 一起升级。
Desktop 使用自带的 uv 把声明的 Python 依赖安装到该插件独有的不可变环境，不会修改 Runtime Core、其他插件或系统 Python。自定义 ZIP 的依赖只允许二进制 wheel；应用单独列入白名单、经过审核的目录插件在没有 wheel 时，可以在托管安装环境中自动构建源码包。如果准备失败，请根据错误检查不支持的 requirement、不可用的发行包、网络或平台兼容性；不需要手工修改应用自己的 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 or update from ZIP，然后选择 .zip 文件。一个合格包必须：
- 包含且只包含一个可判定的插件清单：
plugin.yaml、plugin.yml或plugin.json； - 清单中的
entrypoint能在包内导入； - 不含绝对路径、路径穿越、符号链接、加密项或重复项；
- 压缩后不超过 10 MiB，解压后不超过 50 MiB，文件数不超过 512。
仓库开发者可以生成确定、带版本号的 ZIP 和校验文件：
python scripts/release_domain_plugin.py path/to/domain_plugin
安装阶段会完成 ZIP 与 manifest 验证、复制包并自动准备依赖，但不导入 Python 代码。只有 Enable 时才会在隔离 worker 中探测/导入。
若 ZIP 的插件 ID 与已安装的自定义插件相同，并且 manifest 版本是严格更高的三段式版本号（例如 1.4.0 → 1.5.0），同一入口会执行更新。相同版本、降级、预发布标签或非三段式版本会被拒绝；Catalog 和内置插件也不能被自定义 ZIP 覆盖。更新保留原来的 Enabled、Disabled 或 Installed 状态，并使用与 Catalog 更新相同的临时目录与回滚机制。
任务生成的项目插件
当“一句话开干”的任务明确要求一个后续可调用的工具，并且运行已产出通过检查的 file-predictor-v1 模型、推理源码、精确评价产物、已接受预测输出与 model card 时，Runtime 可以用固定模板生成插件候选。它不会接受任意插件源码或让 Reasoner 直接修改注册表；固定 publisher 只封装这些已记录产物，以及可选的求解器辅助文件与报告，并为包内文件和来源产物记录 SHA-256。若 attestation 与 Runtime 冻结的成功 predictor 或任一非 Runtime 验收指标不完全一致，Control 会拒绝安装与导出。
任务成功后，候选包还要经过普通受管理插件的包结构、保留 ID、依赖、安装与 worker 检查。发布成功的条目标记为 origin=generated，其 model card 记录输入/输出 schema、适用域、仅供说明的评价指标和任务标签，供后续任务保守匹配；多个兼容工具不会被静默任选。结果导出只会包含发布事件绑定的插件 ZIP、冻结模型、最小调用示例和使用说明。摘要校验不是代码签名，也不是独立科学证据。
从求解器文件夹生成适配插件
新建页也可以选择一个包含 README/usage 文档和原生可执行文件的文件夹。Web 与 Desktop 会把它确定性打成一个 ZIP 附件，限制为最多 512 个普通文件、压缩前 50 MiB、压缩后 10 MiB；危险路径、重复项和超限会在打包或后端校验时拒绝，Desktop 还会拒绝 symlink 与特殊条目。后端只读取最多 64 KiB README 文本并静态检查 ELF、PE 或 Mach-O 文件头，不执行二进制，也不整体解压。满足条件的附件画像为 solver_bundle；README 摘要是不可信用户文档，不是执行授权。
若操作者在新建页勾选现有 允许发布可复用插件 权限，Agent 可以编写 file-solver-adapter-v1 Python 兼容层。该层固定接收 --solver-root、--solver-executable、--input 和 --output；合同要求 Local Executor 以普通子进程用有界 help/version 或文档示例做冒烟验证。固定 runtime.solver_adapter.publish publisher 只接受三个不可变 Artifact 输入：原始 solver_bundle、生成的 adapter_source 和 validation；它校验 validation 声明的通过状态、接口、bundle/source 精确 SHA-256 与 Artifact 谱系，内嵌与外置 attestation 再绑定三者的 Artifact ID、SHA-256 和每个包内文件。Control 会重新核对这三源谱系和包摘要，再通过受管理安装/启用流程发布 origin=generated 的项目插件。validation 记录与 attestation 都不是冒烟测试实际执行的独立证明；这条路径也不会把二进制包装任务假装成模型训练或最终 predictor。
ExternalBinarySecurityReviewer 是这个 publisher 的可替换策略接口。当前默认实现明确返回 permissive_deferred：它允许发布并记录 independent_binary_review_performed=false，但没有执行恶意软件扫描、签名验证、来源认证或独立的二进制安全审查。摘要 attestation 只证明身份和谱系，不能称为“已通过安全审查”。适配器冒烟验证以及发布后调用都以当前用户权限作为普通子进程执行。
如何选择能力
打开能力详情，重点看四项：
required_inputs：Reasoner 每次调用必须提供的普通输入；artifact_inputs：必须引用的既有产物及其类型；metric_outputs：可以支持哪些验收条件；example与cost_hints：合法输入形状和一次调用的大致资源成本。
若多个插件提供同一抽象能力，能力详情会列出各 provider。研究合同最终记录具体提供者，避免日后环境变化导致同一名称悄悄换实现。
Core 与 Domain
- Domain 插件表达物理领域或问题领域的操作，例如三体积分和束流跟踪。
- Core 插件提供跨领域基础工作，如执行、评估、分析、知识管理和报告。
分类只用于发现和理解，不表示权限高低。真正的特殊权限来自 trusted_evaluator 访问角色，而且应该只授予独立评估器。
安全边界
受管理插件使用独立 worker 进程和独立 Python 依赖目录，且其进程环境不传入 provider 密钥。这能避免依赖冲突，但不是操作系统安全沙箱。启用后的插件仍有当前用户的本机权限。只安装你信任来源的包，并在启用前查看 manifest、依赖和源代码。
Local Executor、生成 predictor 推理和生成的外部求解器适配器会在 Linux、macOS 和 Windows 上作为普通子进程执行。Runtime 会校验工作区、过滤凭据、检查摘要、限制超时与输出，但这不是操作系统沙箱；进程仍有当前用户的文件系统和网络权限。外部求解器包即使记录了 permissive_deferred reviewer 状态，也不代表已经安全审查。
插件出错时
按这个顺序检查：
- 插件是否为 Enabled，而不只是 Installed。
- 依赖准备是否产生
environment_id，worker 探测是否成功。 - 研究合同是否勾选了正确能力。
- 输入字段名和产物类型是否与能力详情一致。
- 控制室 Failure、Jobs 与日志中是否有
load_error或执行错误。
如果插件升级改变能力名或输入格式，请复制旧运行配置并显式迁移；不要修改已经开始运行的研究合同。
受管理 worker 协议 v1 支持普通 ScientificPlugin。当前不支持自定义隔离 executor，插件本地 reasoner 也不会传送到 Desktop；Desktop 使用已配置的 Runtime reasoner。CLI 直接加载目录仍是使用当前 Python 环境的开发者进程内路径。