@delta-infra/cli 1.0.76 → 1.0.78

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

@@ -1,112 +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`。
-没有用户明确授权时不得启动或停止；未知结果不得重试。
+# 服务与参数参考
+
+只读取当前所选服务对应的部分。下文中的 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`。
+没有用户明确授权时不得启动或停止；未知结果不得重试。

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

@@ -1,44 +1,44 @@
-# 跨服务工作流
-
-每一步必须直接使用对应的具名 service Skill，并由该 Skill 的 `python_repl` 调用
-`delta-science/scripts/invoke.py`。禁止把步骤派发给 `task[general-purpose]`、通用
-subagent 或自由文本执行器；禁止 Bash、目录探测和直接 HTTP。wrapper 成功后每一步
-只消费 `result["native"]` 顶层。目标 operation 不在 CLI catalog 时，立即标记为
-不支持且未发送远端请求，不猜测相近 endpoint。
-
-## 单个已命名分子
-
-1. 用 PubChem `compound-summary` 解析名称并取得身份字段。
-2. 按文档规定的回退顺序提取 SMILES。
-3. 只有用户要求 RDKit 描述符或明确的结构校验时，才调用 RDKit `batch-parse-describe`。
-4. 只有用户明确要求图片时，才调用 RDKit `render`，并解码、验证图片字节。
-5. 比较分子式、分子量、InChIKey 和供体/受体数量时，要明确区分 LogP、TPSA 等依赖模型的数值。
-
-## 多分子比较
-
-1. 用 PubChem 批量解析全部名称，请求体只包含 `identifiers` 和 `namespace:"name"`。省略 `properties`。
-2. 从 `native.results[*]` 读取记录，并从每条记录的嵌套 `properties` 读取字段。
-3. 未解析成功的记录要排除，并明确说明原因。
-4. 使用 RDKit `similarity-matrix` 校验和排序两两相似度。它的 `sanitize` 已经校验输入，不要额外调用 parse。
-5. 用 PubChem 记录的原始 `input` 作为 molecule id，并按文档顺序从嵌套属性中提取 SMILES。
-6. 保持输入顺序，报告每个分数时明确对应的分子对。
-7. 除非用户明确要求，不要渲染、保存用户文件、检查健康状态或探测额外描述符。
-8. `ranked_pairs` 使用命名字段 `a`、`b`、`similarity`。找指定目标的最近邻时，
-   在包含该目标的记录中取最大 `similarity`，另一侧字段就是最近邻；不要使用
-   `i`、`j`、`score` 或猜测矩阵下标。
-
-## 材料工作流
-
-1. 使用 pymatgen 校验化学式/结构并转换 CIF；无机式量只能取当前 native `weight`。
-2. GSAS-II 只能接收真实 CIF 文本后再做衍射计算。
-3. LAMMPS 只能在已有明确的力场、data 和脚本设置后运行；部署检查可以使用内置有界示例。
-4. 从 LAMMPS 返回 pymatgen 或 GSAS-II 前，需要从弛豫结果重新构造 CIF/POSCAR。不要直接传递 LAMMPS data/dump 文件。
-
-## 优化工作流
-
-- 通用数值或分类实验变量：Delta-BO
-- 以分子结构为决策变量：LDM-BO
-- 带真实历史结果的分类反应条件：SynBO
-
-禁止为了让优化器运行而编造观测数据。用户没有提供测量结果时，只能使用初始化或随机建议模式，并明确说明它是待实验验证的建议，不是已经验证的最优条件。
-SynBO/Delta-BO 没有返回 recommendations 时，不得用本地回归、GP、UCB 或人工排序替代。
+# 跨服务工作流
+
+每一步必须直接使用对应的具名 service Skill，并由该 Skill 的 `python_repl` 调用
+`delta-science/scripts/invoke.py`。禁止把步骤派发给 `task[general-purpose]`、通用
+subagent 或自由文本执行器；禁止 Bash、目录探测和直接 HTTP。wrapper 成功后每一步
+只消费 `result["native"]` 顶层。目标 operation 不在 CLI catalog 时，立即标记为
+不支持且未发送远端请求，不猜测相近 endpoint。
+
+## 单个已命名分子
+
+1. 用 PubChem `compound-summary` 解析名称并取得身份字段。
+2. 按文档规定的回退顺序提取 SMILES。
+3. 只有用户要求 RDKit 描述符或明确的结构校验时，才调用 RDKit `batch-parse-describe`。
+4. 只有用户明确要求图片时，才调用 RDKit `render`，并解码、验证图片字节。
+5. 比较分子式、分子量、InChIKey 和供体/受体数量时，要明确区分 LogP、TPSA 等依赖模型的数值。
+
+## 多分子比较
+
+1. 用 PubChem 批量解析全部名称，请求体只包含 `identifiers` 和 `namespace:"name"`。省略 `properties`。
+2. 从 `native.results[*]` 读取记录，并从每条记录的嵌套 `properties` 读取字段。
+3. 未解析成功的记录要排除，并明确说明原因。
+4. 使用 RDKit `similarity-matrix` 校验和排序两两相似度。它的 `sanitize` 已经校验输入，不要额外调用 parse。
+5. 用 PubChem 记录的原始 `input` 作为 molecule id，并按文档顺序从嵌套属性中提取 SMILES。
+6. 保持输入顺序，报告每个分数时明确对应的分子对。
+7. 除非用户明确要求，不要渲染、保存用户文件、检查健康状态或探测额外描述符。
+8. `ranked_pairs` 使用命名字段 `a`、`b`、`similarity`。找指定目标的最近邻时，
+   在包含该目标的记录中取最大 `similarity`，另一侧字段就是最近邻；不要使用
+   `i`、`j`、`score` 或猜测矩阵下标。
+
+## 材料工作流
+
+1. 使用 pymatgen 校验化学式/结构并转换 CIF；无机式量只能取当前 native `weight`。
+2. GSAS-II 只能接收真实 CIF 文本后再做衍射计算。
+3. LAMMPS 只能在已有明确的力场、data 和脚本设置后运行；部署检查可以使用内置有界示例。
+4. 从 LAMMPS 返回 pymatgen 或 GSAS-II 前，需要从弛豫结果重新构造 CIF/POSCAR。不要直接传递 LAMMPS data/dump 文件。
+
+## 优化工作流
+
+- 通用数值或分类实验变量：Delta-BO
+- 以分子结构为决策变量：LDM-BO
+- 带真实历史结果的分类反应条件：SynBO
+
+禁止为了让优化器运行而编造观测数据。用户没有提供测量结果时，只能使用初始化或随机建议模式，并明确说明它是待实验验证的建议，不是已经验证的最优条件。
+SynBO/Delta-BO 没有返回 recommendations 时，不得用本地回归、GP、UCB 或人工排序替代。