@delta-infra/cli 1.0.95 → 1.0.97

package/skills/delta-science/references/qe-dft.md

@@ -0,0 +1,123 @@
+# Quantum ESPRESSO DFT 详细规则
+
+QE 用于通过 Chemistry Gateway 执行可追踪的异步 Quantum ESPRESSO 工作流。agent 只接触
+Gateway/Science Server contract，不运行本地 `pw.x`，不调用内部 QE 容器，也不提交 shell
+命令、scheduler 脚本、`pseudo_dir`、`outdir` 或主机路径。
+
+本 reference 的服务路由标签为 `qe`，preflight 中对应的领域 skill 名为 `qe-dft`。
+实际 `tools.name` 与 `tool_endpoints.name` 必须逐字取自当前 CLI catalog。下列路径是 QE
+服务契约，不是可直接访问的 URL，也不是可以自动改写的 endpoint 别名。
+
+## 能力分组
+
+| 服务路径 | 作用 | 类型 |
+| --- | --- | --- |
+| `/chem/qe/health`、`/healthz`、`/readyz` | 运行时、scheduler、存储和 PP 就绪 | 只读 |
+| `/chem/qe/v1/qe/workflow-types` | workflow catalog 和支持状态 | 只读 |
+| `/chem/qe/v1/pp-sets`、`/pp-locks/{digest}` | 已发布 PP profile/lock | 只读 |
+| `/chem/qe/v1/pp-sets:resolve` | 按 campaign 元素全集解析 PP 候选 | 只读/校验 |
+| `/chem/qe/v1/artifacts` | 上传、查询和下载结构/fixed-coordinate artifact | 文件/二进制 |
+| `/chem/qe/v1/qe/jobs` | 提交异步计算并查询 job | 远端变更 |
+| `/chem/qe/v1/qe/jobs/{job_id}/events`、`steps`、`logs`、`artifacts` | 读取作业过程和结果 | 只读 |
+| `/chem/qe/v1/qe/jobs/{job_id}:cancel`、`:retry`、`:review` | 取消、重试和科学审核 | 远端变更 |
+
+选择新工具或新 operation 时，依次使用：
+
+```text
+delta-cli science list
+delta-cli science endpoints list <exact tool name>
+```
+
+再用目录返回的精确名称调用；如果 catalog 没有 schema，不猜测 operation、路径参数、
+请求头或 body。
+
+## 当前 CLI 的文件和请求头边界
+
+结构 artifact 上传需要 `application/octet-stream` 和 query metadata，QE job 提交要求
+稳定的 `Idempotency-Key`。当前通用 `delta-cli science invoke` 只有 JSON body/query 参数，
+没有原始二进制上传、multipart 或自定义请求头 flag。因此：
+
+- 只有在 Science Server 已提供明确等价 adapter 时，才可以通过 CLI 解析 PP、提交 job
+  或上传 artifact；
+- 不要把结构文本、文件路径、base64、`Idempotency-Key` 或 QE service credential 当成
+  普通业务字段发送；
+- 若目录没有 adapter，报告“当前 CLI 未暴露该 operation；未发送远端请求”，不要调用
+  公开/私有 Gateway URL 或 `qe-cloud-compute:18020`。
+
+## 新作业的正确顺序
+
+1. 读取 health；需要部署诊断时再读取 readiness，并从 workflow catalog 选择当前
+   `supported` 的 task。
+2. 计算完整 `campaign_elements` 集合，使用 `pp-sets:resolve` 得到 profile；生产作业
+   必须使用服务返回的 `pp_set_id` 与不可变 `lock_id`，不能只凭 profile 名称推断 lock。
+3. 让服务校验结构 artifact，job 只引用返回的 `sha256:<digest>` artifact ID。
+4. 用稳定幂等语义提交 `qe/jobs`；接收 `202` 只代表 accepted/queued，不代表 QE 已收敛。
+5. 轮询 job、events、steps、logs 和 artifacts；独立读取 `execution`、`solver`、
+   `scientific` 三个状态。
+6. 下载结果时校验每个 artifact 的 SHA-256，并分别报告 selected backend、资源 telemetry、
+   solver 状态、scientific review 状态和 warnings。
+
+PP 解析的最小业务数据形状如下；其中值必须来自当前服务/目录，不能填入虚构的生产 lock：
+
+```json
+{
+  "campaign_id": "si-bulk-scf-v1",
+  "campaign_elements": ["Si", "O"],
+  "workflows": ["qe.pw.scf"],
+  "explicit_mode": null
+}
+```
+
+作业的核心结构如下，`workflow_inputs` 必须遵循当前 task schema：
+
+```json
+{
+  "task": "qe.pw.scf",
+  "schema_version": "1.1",
+  "campaign_id": "si-bulk-scf-v1",
+  "campaign_elements": ["Si"],
+  "structure": {"format": "artifact", "artifact_id": "sha256:<64-hex>"},
+  "physics": {
+    "parameter_set": "<approved-parameter-set>",
+    "pp_policy": {
+      "mode": "sssp_single",
+      "pp_set_id": "<approved-pp-set>",
+      "lock_id": "sha256:<64-hex>"
+    },
+    "kpoints": [4, 4, 4]
+  },
+  "resources": {
+    "profile": "standard",
+    "nodes": 1,
+    "mpi_ranks_per_node": 1,
+    "omp_threads_per_rank": 1,
+    "walltime_seconds": 3600,
+    "gpu_policy": "cpu"
+  },
+  "client_request_id": "si-scf-v1",
+  "workflow_inputs": {}
+}
+```
+
+## CPU/GPU 与状态解释
+
+CPU 是默认策略，尤其适用于小/中型交互任务、PP/结构/审计/归档任务和成本敏感场景。
+只有用户明确要求或项目已有 GPU 预算，并且 live catalog 返回
+`gpu_support_status: "verified"` 时，才使用 `gpu`；强制 GPU 不得静默回退 CPU。只有
+结果明确返回 `selected_backend: "gpu"` 才能声称实际使用 GPU；`auto` 不是 GPU 使用证明。
+
+三个状态通道不可合并：
+
+- `execution`：prepared/submitted/queued/running/scheduler completion/cancelled/failed；
+- `solver`：not started/running/converged/not converged/failed/unknown；
+- `scientific`：unreviewed、scientifically accepted、accepted with limitations、needs
+  recalculation、not assessable、failed 或 archived。
+
+scheduler 完成不等于 solver 收敛，solver 收敛也不等于 scientific acceptance。按稳定
+错误码而不是 message 分支，重点包括 `PP_SET_INCOMPLETE`、`PP_POLICY_INCOMPATIBLE`、
+`PP_CAPABILITY_UNKNOWN`、`ARTIFACT_MISSING`、`SOLVER_NOT_CONVERGED`、
+`SCIENTIFIC_GATE_FAILED`、`RESTART_INCOMPATIBLE`、`IDEMPOTENCY_CONFLICT`、
+`EXECUTION_BACKEND_NOT_READY`、`GPU_UNSUPPORTED` 和 `GPU_UNAVAILABLE`。
+
+提交、取消、重试或审核属于远端变更，必须有用户明确授权；结果未知时禁止重试。不要把
+GPU smoke test、scheduler 日志或可解析的 QE 输出描述成科学结论或客户级性能保证。

package/skills/delta-science/references/rdkit.md

@@ -1,138 +1,138 @@
-# RDKit 详细规则
-
-只能通过 `delta-cli science invoke` 调用。以下业务响应位于 CLI 顶层 `data`；只按本文件
-说明读取字段，不得递归搜索。这里只记录 operation schema，不授权直接 HTTP。
-
-一个请求只执行完成目标所需的最少调用。同时校验、规范化并计算基础描述符时使用一次
-`batch-parse-describe`，payload 使用 `molecules:[{id,smiles}]`，不得拆成 parse 和
-descriptors。多个分子的全对相似度使用一次 `similarity-matrix`；排名字段固定为
-`a`、`b`、`similarity`，不是 `i`、`j`、`score`。
-
-只报告业务响应实际存在的描述符。渲染 PNG 时只解码文档指定字段，并验证字节以
-`89 50 4e 47 0d 0a 1a 0a` 开头；不得把 JSON envelope 保存成图片。
-
-## Health
-
-operation：`health`，无 body。
-
-## Parse
-
-operation：`parse`。
-
-```json
-{"input": "CCO", "format": "smiles", "sanitize": true}
-```
-
-Formats: `smiles`, `inchi`, `molblock`.
-
-Key response fields in `data`: `valid`, `canonical_smiles`, `formula`,
-`molecular_weight`, `exact_molecular_weight`, `inchi_key`, `atom_count`,
-`heavy_atom_count`, `bond_count`, `warnings`, `error`.
-
-## Descriptors
-
-operation：`descriptors`。
-
-```json
-{"smiles": "CCO", "descriptor_set": "basic", "sanitize": true}
-```
-
-`descriptor_set` currently supports `basic`. Descriptor keys include `Formula`,
-`MolWt`, `ExactMolWt`, `HeavyAtomMolWt`, `TPSA`, `MolLogP`, `NumHDonors`,
-`NumHAcceptors`, `NumRotatableBonds`, `RingCount`, `FractionCSP3`,
-`HeavyAtomCount`, `AtomCount`, and `BondCount`.
-
-## Batch Descriptors
-
-operation：`batch-descriptors`。
-
-```json
-{"smiles": ["CCO", "c1ccccc1"], "descriptor_set": "basic", "sanitize": true}
-```
-
-Limits: 1-500 SMILES.
-
-## Batch Parse Describe
-
-operation：`batch-parse-describe`。
-
-```json
-{
-  "molecules": [
-    {"id": "aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O"},
-    {"id": "caffeine", "smiles": "Cn1cnc2c1c(=O)n(C)c(=O)n2C"}
-  ],
-  "descriptor_set": "basic",
-  "fingerprint": {"type": "morgan", "radius": 2, "n_bits": 2048},
-  "sanitize": true
-}
-```
-
-Limits: 1-500 molecules. Returns per-item `valid`, `canonical_smiles`, parse
-fields, `descriptors`, optional `fingerprint_metadata`, `on_bits`, `bit_count`,
-`warnings`, and `error`.
-
-## Render
-
-operation：`render`。
-
-```json
-{"smiles": "CCO", "image_format": "svg", "width": 450, "height": 320}
-```
-
-Image formats: `svg`, `png`. SVG returns text; PNG returns base64.
-Width/height range: 150-2000.
-
-## Fingerprint
-
-operation：`fingerprint`。
-
-```json
-{"smiles": "CCO", "radius": 2, "n_bits": 2048}
-```
-
-Morgan fingerprint parameters: `radius` 1-6, `n_bits` 128-8192.
-
-## Similarity
-
-operation：`similarity`。
-
-```json
-{"query_smiles": "CCO", "target_smiles": "CCCO", "radius": 2, "n_bits": 2048}
-```
-
-Returns Tanimoto similarity.
-
-## Similarity Matrix
-
-operation：`similarity-matrix`。
-
-```json
-{
-  "molecules": [
-    {"id": "aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O"},
-    {"id": "ibuprofen", "smiles": "CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O"}
-  ],
-  "fingerprint": {"type": "morgan", "radius": 2, "n_bits": 2048},
-  "sanitize": true
-}
-```
-
-Returns `matrix` in input order and `ranked_pairs` sorted by descending
-Tanimoto similarity. Each ranked record is named, not index-based:
-
-```json
-{"a":"aspirin","b":"ibuprofen","similarity":0.195122}
-```
-
-Do not expect `i`, `j`, or `score` fields.
-
-## Substructure
-
-operation：`substructure`。
-
-```json
-{"query_smarts": "c1ccccc1", "target_smiles": ["c1ccccc1", "CCO"]}
-```
-
-Limits: SMARTS max length 5000; target list size 1-500.
+# RDKit 详细规则
+
+只能通过 `delta-cli science invoke` 调用。以下业务响应位于 CLI 顶层 `data`；只按本文件
+说明读取字段，不得递归搜索。这里只记录 operation schema，不授权直接 HTTP。
+
+一个请求只执行完成目标所需的最少调用。同时校验、规范化并计算基础描述符时使用一次
+`batch-parse-describe`，payload 使用 `molecules:[{id,smiles}]`，不得拆成 parse 和
+descriptors。多个分子的全对相似度使用一次 `similarity-matrix`；排名字段固定为
+`a`、`b`、`similarity`，不是 `i`、`j`、`score`。
+
+只报告业务响应实际存在的描述符。渲染 PNG 时只解码文档指定字段，并验证字节以
+`89 50 4e 47 0d 0a 1a 0a` 开头；不得把 JSON envelope 保存成图片。
+
+## Health
+
+operation：`health`，无 body。
+
+## Parse
+
+operation：`parse`。
+
+```json
+{"input": "CCO", "format": "smiles", "sanitize": true}
+```
+
+Formats: `smiles`, `inchi`, `molblock`.
+
+Key response fields in `data`: `valid`, `canonical_smiles`, `formula`,
+`molecular_weight`, `exact_molecular_weight`, `inchi_key`, `atom_count`,
+`heavy_atom_count`, `bond_count`, `warnings`, `error`.
+
+## Descriptors
+
+operation：`descriptors`。
+
+```json
+{"smiles": "CCO", "descriptor_set": "basic", "sanitize": true}
+```
+
+`descriptor_set` currently supports `basic`. Descriptor keys include `Formula`,
+`MolWt`, `ExactMolWt`, `HeavyAtomMolWt`, `TPSA`, `MolLogP`, `NumHDonors`,
+`NumHAcceptors`, `NumRotatableBonds`, `RingCount`, `FractionCSP3`,
+`HeavyAtomCount`, `AtomCount`, and `BondCount`.
+
+## Batch Descriptors
+
+operation：`batch-descriptors`。
+
+```json
+{"smiles": ["CCO", "c1ccccc1"], "descriptor_set": "basic", "sanitize": true}
+```
+
+Limits: 1-500 SMILES.
+
+## Batch Parse Describe
+
+operation：`batch-parse-describe`。
+
+```json
+{
+  "molecules": [
+    {"id": "aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O"},
+    {"id": "caffeine", "smiles": "Cn1cnc2c1c(=O)n(C)c(=O)n2C"}
+  ],
+  "descriptor_set": "basic",
+  "fingerprint": {"type": "morgan", "radius": 2, "n_bits": 2048},
+  "sanitize": true
+}
+```
+
+Limits: 1-500 molecules. Returns per-item `valid`, `canonical_smiles`, parse
+fields, `descriptors`, optional `fingerprint_metadata`, `on_bits`, `bit_count`,
+`warnings`, and `error`.
+
+## Render
+
+operation：`render`。
+
+```json
+{"smiles": "CCO", "image_format": "svg", "width": 450, "height": 320}
+```
+
+Image formats: `svg`, `png`. SVG returns text; PNG returns base64.
+Width/height range: 150-2000.
+
+## Fingerprint
+
+operation：`fingerprint`。
+
+```json
+{"smiles": "CCO", "radius": 2, "n_bits": 2048}
+```
+
+Morgan fingerprint parameters: `radius` 1-6, `n_bits` 128-8192.
+
+## Similarity
+
+operation：`similarity`。
+
+```json
+{"query_smiles": "CCO", "target_smiles": "CCCO", "radius": 2, "n_bits": 2048}
+```
+
+Returns Tanimoto similarity.
+
+## Similarity Matrix
+
+operation：`similarity-matrix`。
+
+```json
+{
+  "molecules": [
+    {"id": "aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O"},
+    {"id": "ibuprofen", "smiles": "CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O"}
+  ],
+  "fingerprint": {"type": "morgan", "radius": 2, "n_bits": 2048},
+  "sanitize": true
+}
+```
+
+Returns `matrix` in input order and `ranked_pairs` sorted by descending
+Tanimoto similarity. Each ranked record is named, not index-based:
+
+```json
+{"a":"aspirin","b":"ibuprofen","similarity":0.195122}
+```
+
+Do not expect `i`, `j`, or `score` fields.
+
+## Substructure
+
+operation：`substructure`。
+
+```json
+{"query_smarts": "c1ccccc1", "target_smiles": ["c1ccccc1", "CCO"]}
+```
+
+Limits: SMARTS max length 5000; target list size 1-500.

package/skills/delta-science/references/routing-index.md

@@ -1,36 +1,45 @@
-# Delta Science 路由索引
-
-本文件只描述稳定的科研意图边界，不复制 Science Server 的工具和 endpoint 清单。
-实际可用工具以 `delta-cli science list` 和 `delta-cli science endpoints list` 返回的
-实时目录为准。
-
-## 路由优先级
-
+# Delta Science 路由索引
+
+本文件只描述稳定的科研意图边界，不复制 Science Server 的工具和 endpoint 清单。
+实际可用工具以 `delta-cli science list` 和 `delta-cli science endpoints list` 返回的
+实时目录为准。
+
+## 路由优先级
+
 - 普通化合物名称、CID 和公共属性使用 PubChem；已有 SMILES/InChI 且需要结构计算时
   使用 RDKit。
+- 用户明确要求一次得到名称解析、PubChem 字段和 RDKit 描述符/指纹时，使用
+  `chemistry` 的 molecule-enrich workflow；不要为同一需求重复调用中间服务。
 - 无机化学式、组成、CIF、POSCAR 和空间群使用 pymatgen；粉末衍射模拟或 Rietveld
   精修使用 GSAS-II。
+- 表格材料数据、可控变量/目标、候选空间、 surrogate 验证和候选排序使用
+  Materials Design；不要把候选预测说成实验结果。
+- 需要 Quantum ESPRESSO 电子结构计算时使用 QE；先解析 workflow 与整组元素的 PP
+  policy/lock，再按异步 job 生命周期处理 execution、solver 和 scientific 状态。
 - 明确的 LAMMPS input、data 和力场任务使用 LAMMPS；不得从化学式或 CIF 猜测势函数。
-- 通用数值、整数或分类实验变量优化使用 Delta-BO。
-- 固定 SMILES 候选池或 PDF2Dock 轨迹使用 LDM-BO；固定 KRAS G12D 生成式优化使用
-  STRBO；反应条件与真实历史得率使用 SynBO；抗体 CDRH3 使用 AntBO。
-- “LDM/大发现模型”是跨上述三类能力的工作流意图，先读取 `ldm.md` 决定唯一后端，
-  不是服务端 tool，也不得路由到旧 `large-discovery-model` Skill。
-
-## 已验证 reference
-
+- 通用数值、整数或分类实验变量优化使用 Delta-BO。
+- 固定 SMILES 候选池或 PDF2Dock 轨迹使用 LDM-BO；固定 KRAS G12D 生成式优化使用
+  STRBO；反应条件与真实历史得率使用 SynBO；抗体 CDRH3 使用 AntBO。
+- “LDM/大发现模型”是跨上述三类能力的工作流意图，先读取 `ldm.md` 决定唯一后端，
+  不是服务端 tool，也不得路由到旧 `large-discovery-model` Skill。
+
+## 已验证 reference
+
 - [pubchem.md](pubchem.md)
 - [rdkit.md](rdkit.md)
+- [molecule-enrich.md](molecule-enrich.md)
 - [pymatgen.md](pymatgen.md)
-- [gsasii.md](gsasii.md)
-- [lammps.md](lammps.md)
+- [gsasii.md](gsasii.md)
+- [lammps.md](lammps.md)
 - [delta-bo.md](delta-bo.md)
+- [materials-design.md](materials-design.md)
+- [qe-dft.md](qe-dft.md)
 - [ldm-bo.md](ldm-bo.md)
-- [ldm.md](ldm.md)
-- [strbo.md](strbo.md)
-- [synbo.md](synbo.md)
-- [antbo.md](antbo.md)
-
-以上 reference 是已验证参数契约，不是服务端完整目录。用户明确点名新工具时，按
-`SKILL.md` 的实时 catalog 流程发现工具和 endpoint；若目录未返回请求 schema，不猜测
-请求体。
+- [ldm.md](ldm.md)
+- [strbo.md](strbo.md)
+- [synbo.md](synbo.md)
+- [antbo.md](antbo.md)
+
+以上 reference 是已验证参数契约，不是服务端完整目录。用户明确点名新工具时，按
+`SKILL.md` 的实时 catalog 流程发现工具和 endpoint；若目录未返回请求 schema，不猜测
+请求体。

package/skills/delta-science/references/services.md

@@ -0,0 +1,112 @@
+# 服务与参数参考
+
+只读取当前所选服务对应的部分。下文中的 endpoint 是 Delta CLI catalog 名称，不是 URL 路径。
+
+## PubChem
+
+Tool：`pubchem`。
+
+- 普通名称查询：`compound-summary`，data 为 `{"identifier":"caffeine","namespace":"name"}`。
+- 批量查询：`compound-batch-summary`。模糊的多分子比较必须严格使用 `{"identifiers":["aspirin","caffeine"],"namespace":"name"}`。
+- 批量查询不要添加 `properties` 或 `synonym_limit`，尤其不能把 `CID` 放进 `properties`。
+- 其他 operation：`compound-resolve-cids`、`compound-properties`、`compound-synonyms`。
+
+单个 `compound-summary` 的业务字段直接位于 wrapper 的 `native` 顶层：读取
+`native.valid`、`native.cid`、`native.properties` 和 `native.synonyms`；不存在
+`native.data` 这一层。
+
+模糊问题优先使用 summary。按 `CanonicalSMILES`、`ConnectivitySMILES`、`SMILES`、`IsomericSMILES` 的顺序提取 SMILES。PubChem 返回的 `MolecularWeight`、`XLogP` 和 `TPSA` 必须保留为 PubChem 数据。
+
+批量 native 输出为 `{"results":[...]}`。每条记录用 `input` 保存原始标签，化合物字段位于嵌套的 `properties`；记录不是平铺结构，集合键也不是 `compounds`。
+
+## RDKit
+
+Tool：`rdkit`。
+
+- `parse`：`{"input":"CCO","format":"smiles"}`
+- `descriptors`：`{"smiles":"CCO","descriptor_set":"basic","sanitize":true}`
+- `batch-parse-describe`：`{"molecules":[{"id":"ethanol","smiles":"CCO"}],"descriptor_set":"basic","sanitize":true}`
+- `render`：`{"smiles":"CCO","image_format":"png","width":500,"height":400}`
+- `similarity`：使用 `query_smiles` 和 `target_smiles`
+- `similarity-matrix`：使用 `molecules:[{id,smiles}]`
+- `substructure`：使用 `query_smarts` 和 `target_smiles`
+
+`batch-parse-describe` 使用 `molecules`，不能用 `inputs`；分子字段使用 `smiles`，不能用 `input`。fingerprint 选项是对象，不是布尔值。PubChem `XLogP` 与 RDKit `MolLogP` 使用不同模型。
+
+`similarity-matrix` 的 `ranked_pairs` 每项是
+`{"a": <输入 id>, "b": <输入 id>, "similarity": <数值>}`。不要读取
+`i`、`j` 或 `score`。
+
+## pymatgen
+
+Tool：`pymatgen`。
+
+- 化学式：`composition-parse`，data 为 `{"formula":"LiFePO4","format":"formula"}`
+- 结构 operation：`structure-parse`、`structure-summary`、`structure-convert`、`structure-symmetry`
+
+结构调用必须发送完整结构文本，不能发送本地文件路径。支持 CIF、POSCAR、JSON、CSSR 和 XSF。不要把 LAMMPS data/dump 文件交给 pymatgen。
+
+对无机化学式/式量，只报告当前 native 的 `formula`、`reduced_formula`、
+`chemical_system`、`weight` 与元素组成。PubChem 未收录时保留 `not_found`，
+不要编造 CID 或用本地计算补值。
+
+## GSAS-II
+
+Tool：`gsasii`；operation 为 `powder-simulate` 和 `powder-refine`。
+
+模拟需要完整 `cif` 文本。字段必须使用 `phase_name`、`include_profile`、`include_reflections`、`t_min`、`t_max` 和 `t_step`。
+
+精修需要真实的 `powder_data`、`instrument_parameters` 和 `phases:[{name,cif}]`。依赖模拟结果时，只能从成功调用的 native `profile[*].x` 和 `profile[*].y_calc` 构造粉末数据。
+
+## LAMMPS
+
+Tool：`lammps`。
+
+- 只读有界示例：`lj-melt-example`，无参数
+- 执行：`run`，参数必须是示例返回的精确 native `request`，或用户明确授权的 `input_script`/files
+
+绝不能把 CLI 外层信封传给 `run`，只能传 `native["request"]`。LAMMPS 不会自动推断力场。交互式运行必须保持有界。
+
+最小示例最终数值从当前 native `last_thermo` 读取；逐字保留 `Step`、`Temp`
+和 `TotEng`，不要除以原子数、换算单位或推测收敛性。
+
+## Delta-BO
+
+Tool：`delta-bo`。
+
+- 命令目录：`commands`，无参数
+- 无状态建议：`generate`，例如 `{"params":[{"name":"x","type":"numeric","low":0,"high":1}],"num_suggestions":2,"algorithm":"random-search","seed":42}`
+
+观测少于五条时，除非用户明确要求 BO，否则优先使用 `random-search`。有状态 native session 命令属于变更操作，不能盲目重试。
+
+## LDM-BO
+
+Tool：`ldm-bo`；operation 为 `recommend` 和 `trajectory`。
+
+有界测试使用 `bo-tanimoto`。`recommend` 接受 `method`、`pool`、`history:[{smiles,scores}]` 和 `batch_size`。`trajectory` 必须保留 native 连字符字段：`seed-smiles`、`num-evaluations` 和 `batch-size`。
+
+## SynBO
+
+Tool：`synbo`；operation 为 `initialize` 和 `optimize`。
+
+二者都使用 `condition_dict`、`opt_metrics` 和 `batch_size`。`optimize` 还要求数值型 `previous_results`，且每条记录必须包含全部条件和指标。有界 CPU 测试使用 `accuracy:"tiny"` 和 `device:"cpu"`，并串行执行。
+
+有真实 `previous_results` 的优化请求使用一次 `optimize`；每行必须包含全部条件列和
+数值指标。失败、超时或空 recommendations 时如实报告，禁止本地替代优化。
+
+## AntBO
+
+Tool：`antbo`。
+
+当前 CLI catalog 暴露 `health`、`run-default-job`、`run`、`log`、`jobs` 和
+`stop`；准确参数见 `operation-contracts.md`。没有 `ldm/suggest`、
+`ldm/initialize`、`ldm/evaluate`。遇到 AntBO/CDRH3 的这些 LDM 请求时不要调用工具、
+不要改用小分子 LDM-BO、不要探测目录或直连 HTTP；明确回复“当前 Delta CLI catalog
+未暴露该 operation；未发送远端请求”。
+
+启动作业只能根据同一次 native 的 `started`、`pid` 和 `log_name`/`log_path`
+报告；任一字段缺失时标记为未验证，不要重复提交或编造作业信息。
+
+`health`、`log`、`jobs` 是只读调用。`run-default-job`、`run`、`stop` 会改变远端状态；
+`run-default-job` 的 `log_name`、`append`、`timeout_seconds` 使用 `--params-json`。
+没有用户明确授权时不得启动或停止；未知结果不得重试。