检索与构建接入

记录怎样保存与检索

JSONL 是上传或导出的交换格式，每行表示一个反应。平台使用 PostgreSQL 保存完整 JSONB 记录，并建立物料、阶段、测量值和分子结构索引；原始文件另行保存。检索通过数据库筛选和结构匹配完成，不逐行读取下载文件。

新的反应只要完成解析并公开发布，就可使用已有的结构、温度、产率等条件检索。查询字段由规范和参数登记表定义，不由已有反应名称生成。新的条件类型需要登记；新增记录本身不需要修改检索程序。

自定义参数目前在对应阶段或物料的 JSONB 中筛选。登记并不自动建立每个数值的专用索引；常用参数可依据查询性能增设可重建的索引，无需更改原始数据。

按键变化检索

例如检索 C–N 断裂：网页在“结构与官能团”下添加键变化；MCP 或 API 使用下面的条件。可选择断键、成键或键级变化，并与分子结构、实验条件组合。

{
  "bond_changes": [
    {
      "change": "broken",
      "elements": [
        "C",
        "N"
      ]
    }
  ]
}

依据原始 SMILES 中两侧一致的原子映射编号比较连接关系，只比较两侧均出现的原子。缺少副产物、没有映射或映射有冲突时，不据此推断断键。结果提供 bond_change_coverage；这表示投料到最终产物的净变化，不表示机理或一锅反应的全部中间步骤。

自定义参数检索

补充条件保存在 parameters 中。已登记的参数可按数值、文字或是否填写筛选；用 get_parameter_catalog 查看名称、单位和支持的操作。同组条件匹配同一个阶段，避免混用不同步骤的条件。

上传自定义字段不会自动加入下拉列表。审核登记时明确英文标识、含义、数值／文字／布尔类型及单位。页面使用登记表的中文或英文名称显示，同一参数的标识不随语言变化。

quantity 类型可记录单值、区间或单侧界限，按原文选择写法；不需要为每种写法登记一个新字段。原始记录使用 lower／upper，查询边界使用 minimum／maximum。

数值参数：单值等于使用 value，例如 30 Hz；范围使用 minimum 和 maximum，可只填一侧。范围按相交匹配，20–40 Hz 会匹配 30 Hz 或 35–50 Hz。单值等于 30 Hz 不匹配 20–40 Hz、约 30 Hz 或小于 30 Hz。文字参数使用等于或包含；布尔参数使用 true 或 false。

{
  "parameter_filters": [
    {
      "parameter": "conditions.milling_frequency",
      "operator": "equals",
      "value": 30
    }
  ]
}

{
  "parameter_filters": [
    {
      "parameter": "conditions.milling_frequency",
      "operator": "range",
      "minimum": 20,
      "maximum": 40
    }
  ]
}

示例筛选 20–40 Hz 的球磨频率。未登记参数仍保留在完整记录中。新增检索参数由维护者审核登记，已有兼容记录无需重新上传。结果中的 parameter_coverage 说明事实数据是否齐备。

例如 parameters 中的 milling_ball_diameter: {value: 0.5, unit: "cm"} 可以按 4–6 mm 检索。新记录统一使用 parameters；登记后即可按其类型与单位检索。

null 表示停止沿用此前的已知值，不表示 0，也不推断反应停止。省略字段则表示本阶段没有报告变化。登记需提供稳定名称、科学含义、类型、位置、单位换算及示例，由维护者审核发布；当前没有开放自助登记接口。

python isynth_mcp_client.py parameters
python isynth_mcp_client.py validate parameter-upload.json
python isynth_mcp_client.py upload parameter-upload.json
# After parsing, review and publication:
python isynth_mcp_client.py search parameter-query.json

查询已有反应选择 reactions:read；需要规划、构建和下载构建结果时，再添加 construction:write。API 与 MCP 共用这些权限。