@delta-infra/cli 1.1.15 → 1.1.16

package/README.md

@@ -293,8 +293,10 @@ delta-cli sandbox kill <sandbox_id>
 v1.1.1 起线上 catalog 已包含 `qe`（Quantum ESPRESSO DFT，20 个端点：任务提交/查询/
 日志/artifact/PP 库等）与 `materials-design`（持久化材料代理建模，7 个端点：
 health/capabilities/job-submit(multipart)/job-status/job-cancel 等）。用法见
-Skill 文档 `skills/delta-science/references/qe.md` 与
-`skills/delta-science/references/materials-design.md`。
+Skill 文档 `skills/delta-science/references/qe.md` 与
+`skills/delta-science/references/materials-design.md`。
+云端 XRD 的相识别、artifact、CIF 模拟和精修契约见
+`skills/delta-science/references/xrd.md`。
 
 ## 输出格式
 
@@ -336,7 +338,7 @@ Skill 文件位于 `skills/` 目录：
 - `delta-shared/` — 全局通用规则（认证、配置、错误处理）
 - `delta-sandbox/` — Sandbox 操作指南（生命周期、命令路由）
 - `delta-science/` — 唯一 Science 入口，包含统一 Delta CLI wrapper、跨工具工作流和
-  PubChem、RDKit、pymatgen、GSAS-II、LAMMPS、Delta-BO、LDM-BO、SynBO、AntBO
+  PubChem、RDKit、pymatgen、XRD、GSAS-II、LAMMPS、Delta-BO、LDM-BO、SynBO、AntBO
   的按需 reference
 
 Memento 等宿主只需要选择 `delta-science`。Skill 根据自然语言科研目标选择 tool 和
@@ -437,7 +439,7 @@ make release
 ```bash
 export GH_TOKEN=<your-github-pat>
 export NPM_TOKEN=<your-npm-token>
-./release.sh v1.1.15
+./release.sh v1.1.16
 ```
 
 脚本执行步骤：

package/checksums.txt

@@ -1,5 +1,5 @@
-79b30a0169261a0db4e862ee0f3d2b74946d1bff58b80ed96fca67deba0ae847 *delta-cli-darwin-amd64.tar.gz
-f40d24e602c5208974a8d4cd4869d76aad5a72af1a1dd98a660ad43ee42189f7 *delta-cli-darwin-arm64.tar.gz
-1e5c118d9bfafb852b766a69d9f972aca956a2d92492cc8e0561ed4dbac90a8e *delta-cli-linux-amd64.tar.gz
-ef4fb5116c5d6972450b55b5fadba42757cbfc4fc578f504236ebd0af655f003 *delta-cli-linux-arm64.tar.gz
-ebb01fd6d036f787305858981e86250699f8807f362b0463881c229983e52e62 *delta-cli-windows-amd64.zip
+14ab0d943d50009a3caa7d5ee2db13e557de36dc39a347e67ae90f88cae582d6 *delta-cli-darwin-amd64.tar.gz
+998c5188c25ec474818cf8aca047e349303d26208e900379b8e7e053babc7d82 *delta-cli-darwin-arm64.tar.gz
+c019843ac23cdf3f09f902686c6cdb0bfaa31136aa7d89cb32989992b1f2c255 *delta-cli-linux-amd64.tar.gz
+6ca4f2b73f99d1f78f339e2f171a7223d16b0a7a9e2e4667c1f8e418e9c9bedd *delta-cli-linux-arm64.tar.gz
+954bbd88f9ba7f706ec2e5106e0bba850553d809816a23cac30e2882a9753792 *delta-cli-windows-amd64.zip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delta-infra/cli",
-  "version": "1.1.15",
+  "version": "1.1.16",
   "description": "Delta Agent Cloud CLI for sandbox compute and science tools.",
   "bin": {
     "delta-cli": "scripts/run.js"

package/skills/delta-science/AGENTS.md

@@ -17,7 +17,7 @@ delta-science/
 └── references/
     └── <tool>.md            # one real tool's operation contract (pubchem, rdkit, pymatgen,
                              #  gsasii, lammps, delta-bo, ldm-bo, materials-design, qe,
-                             #  strbo, synbo, antbo)
+                             #  strbo, synbo, antbo, xrd)
 ```
 
 ## WHERE TO LOOK

package/skills/delta-science/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: delta-science
-description: "公司在线 Science 能力的统一入口，所有调用都经 Delta CLI。凡是查询具体化合物/CID/SMILES/分子性质、批量 PubChem 与 RDKit 分子增强、计算分子描述符或相似度、解析晶体/CIF/空间群、材料表格建模与候选推荐、Quantum ESPRESSO/QE DFT、模拟或精修 XRD、执行 LAMMPS、根据实验数据做贝叶斯优化、反应条件优化，以及任何 LDM/大发现模型、KRAS G12D 小分子生成优化、固定候选池/PDF2Dock 轨迹或抗体 CDRH3 优化任务，都必须使用本 Skill；不得调用旧 large-discovery-model Skill、旧 gateway 脚本、网页搜索或本地科学库绕过 Delta CLI。普通查询、比较或校验默认直接返回文本，不要主动增加 JSON/CSV、报告、图片或图表步骤；只有用户明确要求保存、导出、绘图或生成文件时才创建产物。"
+description: "公司在线 Science 能力的统一入口，所有调用都经 Delta CLI。凡是查询具体化合物/CID/SMILES/分子性质、批量 PubChem 与 RDKit 分子增强、计算分子描述符或相似度、解析晶体/CIF/空间群、云端 XRD 相识别与精修、材料表格建模与候选推荐、Quantum ESPRESSO/QE DFT、执行 LAMMPS、根据实验数据做贝叶斯优化、反应条件优化，以及任何 LDM/大发现模型、KRAS G12D 小分子生成优化、固定候选池/PDF2Dock 轨迹或抗体 CDRH3 优化任务，都必须使用本 Skill；不得调用旧 large-discovery-model Skill、旧 gateway 脚本、网页搜索或本地科学库绕过 Delta CLI。普通查询、比较或校验默认直接返回文本，不要主动增加 JSON/CSV、报告、图片或图表步骤；只有用户明确要求保存、导出、绘图或生成文件时才创建产物。"
 metadata:
   requires:
     bins: ["delta-cli"]
@@ -88,7 +88,8 @@ catalog、render、descriptors 或文件操作；用户请求、诊断需要或
 | 化合物身份、CID、同义词、公共属性、名称转 SMILES | `pubchem` | [pubchem.md](references/pubchem.md) |
 | SMILES/InChI、描述符、指纹、相似度、渲染、子结构 | `rdkit` | [rdkit.md](references/rdkit.md) |
 | 无机化学式、CIF/POSCAR、晶体结构、空间群 | `pymatgen` | [pymatgen.md](references/pymatgen.md) |
-| 粉末衍射模拟、Rietveld 精修 | `gsasii` | [gsasii.md](references/gsasii.md) |
+| 云端 XRD 相识别、XQueryer/XMatcher/XDecomposer、CIF 模拟、MP500、artifact 与精修作业 | `xrd` | [xrd.md](references/xrd.md) |
+| 直接 GSAS-II 模拟或精修 | `gsasii` | [gsasii.md](references/gsasii.md) |
 | 分子动力学、最小化、thermo 与输出文件 | `lammps` | [lammps.md](references/lammps.md) |
 | 通用数值/整数/分类实验变量优化 | `delta-bo` | [delta-bo.md](references/delta-bo.md) |
 | 表格材料 surrogate、候选空间、EI/PI/UCB 与异步推荐作业 | `materials-design` | [materials-design.md](references/materials-design.md) |
@@ -118,8 +119,10 @@ catalog、render、descriptors 或文件操作；用户请求、诊断需要或
 ## 路由边界
 
 - 普通分子名称先用 PubChem；只有需要结构计算时才把成功返回的 SMILES 交给 RDKit。
-- 无机化学式、组成和式量优先 pymatgen，不用 PubChem 或本地元素表补算。
-- 表格材料建模与候选排序使用 Materials Design；必须区分可控变量、目标、候选空间、
+- 无机化学式、组成和式量优先 pymatgen，不用 PubChem 或本地元素表补算。
+- 云端粉末 XRD 相识别、峰匹配、相分解、CIF/MP500 操作和精修生命周期使用 `xrd`；
+  直接请求 GSAS-II 工具时才使用 `gsasii`。两者的 score、作业状态和后端语义不能混用。
+- 表格材料建模与候选排序使用 Materials Design；必须区分可控变量、目标、候选空间、
   交叉验证和不确定性，推荐结果只是待验证假设。
 - 需要显式电子结构计算时使用 QE；先处理元素全集、PP policy/lock 和结构 artifact，
   再提交异步 workflow，不把作业接收、scheduler 完成或 solver 收敛混为一谈。

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

@@ -0,0 +1,186 @@
+# XRD Cloud Compute 详细规则
+
+`xrd` 是通过 Science 工具代理访问 XRD cloud compute 的真实工具。所有调用必须经由
+`delta-cli`，禁止使用 broker URL、`curl`、`requests`、`httpx`、浏览器或本地 XRD
+科学库绕过 CLI。本文是 `delta-science` 的工具 reference，不是第二套 HTTP 客户端。
+
+## 工具与 endpoint
+
+执行前使用实时目录确认当前环境中的 canonical 名称和启用状态：
+
+```text
+delta-cli science list
+delta-cli science endpoints list xrd
+```
+
+`xrd` endpoint 名称必须逐字取自第二条命令的结果。当前 reference 覆盖以下稳定契约：
+
+| endpoint | 方法/用途 | 请求类型 |
+| --- | --- | --- |
+| `healthz`、`readyz`、`capabilities`、`xmatcher-status` | 就绪、能力和数据库状态 | 只读 JSON |
+| `xmatcher-artifacts` | 上传观测曲线、模型输入、CIF 或仪器参数 | `invoke --file` |
+| `xmatcher-artifact`、`xmatcher-artifact-content` | 查询/读取 artifact | `invoke --path-params` |
+| `xqueryer-predictions` | XQueryer 单相候选预测 | JSON |
+| `xmatcher-detect-peaks`、`xmatcher-match` | 峰检测和单相匹配 | JSON |
+| `xmatcher-multiphase-match`、`xdecomposer-predictions` | 多相匹配和相分解 | JSON |
+| `xmatcher-cif-xrd`、`xmatcher-pdf-peaks-xlsx` | CIF 模拟及 PDF 峰表导出 | JSON/二进制 |
+| `xmatcher-refinement-patterns` | 生成精修输入和 provenance manifest | JSON |
+| `refinement-fullprof`、`refinement-gsasii`、`refinement-wpem` | 提交对应后端精修作业 | JSON + header |
+| `refinement-job`、`refinement-job-events`、`refinement-job-artifacts` | 查询精修作业 | `invoke --path-params` |
+| `refinement-job-cancel` | 请求取消精修作业 | `invoke --path-params` |
+| `mp500-cif-exports` | MP500 结构导出为 CIF | JSON |
+
+目录是最终权威。若 endpoint 不在实时目录中，停止并报告配置问题，不改名重试。
+
+## CLI 参数映射
+
+```text
+--data          上游 JSON body
+--params        上游 URL query 参数
+--path-params   替换 endpoint path 中的 {artifact_id}/{job_id}
+--headers       额外上游请求头，例如 Idempotency-Key
+--file          将本地文件通过 file_base64 传给工具代理
+--content-type  file 的原始 MIME 类型
+```
+
+`--params` 不能替代 `--path-params`。不要把本地路径、base64、路径参数或幂等键塞进
+普通业务 `--data`。`science file` 是 QE/Materials Design 等独立文件接口；XRD 的
+`xmatcher-artifacts` 属于工具代理 endpoint，应使用 `science invoke --file`。
+
+## 调用顺序
+
+1. 用户明确要求诊断或执行时，先读取 `healthz`；需要选择后端时再读取
+   `capabilities`。
+2. 通过 `xmatcher-artifacts` 上传真实文件，保存返回的 `artifact_id` 和 `sha256`。
+3. 观测数据使用 `xmatcher-match`、`xmatcher-multiphase-match` 或
+   `xdecomposer-predictions`；XQueryer 使用 `model_input_pattern`。
+4. CIF 模拟使用 `xmatcher-cif-xrd`；精修先调用 `xmatcher-refinement-patterns`，再选择
+   与 `data.backends` 一致的 refinement endpoint。
+5. 精修提交后用 `refinement-job`、`refinement-job-events` 和
+   `refinement-job-artifacts` 读取状态和产物。
+
+不要把服务返回的 queued、scheduler completed 或 backend success 直接描述成科学结论。
+精修至少分开报告传输/作业终态、后端执行状态和科学接受状态。
+
+## 就绪检查
+
+```text
+delta-cli science invoke --tool xrd --endpoint healthz
+delta-cli science invoke --tool xrd --endpoint capabilities
+```
+
+只有需要诊断或用户明确要求时才额外调用 readiness/status。能力结果中的每个所需组件
+都必须满足 `available`；生产任务还应检查 `asset_release_approved`、checksum 字段和
+warnings。`auto` 不代表实际使用 GPU，只有结果明确返回 GPU backend 才能这样报告。
+
+## Artifact 上传与身份
+
+上传观测曲线：
+
+```text
+delta-cli science invoke --tool xrd --endpoint xmatcher-artifacts `
+  --file observed.csv `
+  --params '{"filename":"observed.csv","kind":"observed_pattern","media_type":"text/csv"}' `
+  --content-type application/octet-stream
+```
+
+允许的 `kind` 为：`observed_pattern`、`model_input_pattern`、`cif`、
+`instrument_parameters`。成功响应中的 `artifact_id` 和 `sha256` 必须成对保存并原样
+传给下游。模式文件会在服务端标准化，返回的 digest 是标准化 artifact 的 digest，
+不是一定等于本地上传字节的 digest。
+
+查询 artifact 时使用路径参数：
+
+```text
+delta-cli science invoke --tool xrd --endpoint xmatcher-artifact `
+  --path-params '{"artifact_id":"art_<returned-id>"}'
+```
+
+二进制内容响应可能返回 `data._binary=true`、`content_base64`、`media_type` 和
+`content_length`。只有用户要求保存或工作流需要时才解码，并按服务返回的 SHA-256
+校验；不要凭文件名猜测格式。
+
+## 相识别与匹配
+
+XQueryer 的 `model_input_pattern` 必须正好包含 3500 个样本，覆盖 10 到 90 度 2theta，
+强度不超过服务能力限制：
+
+```text
+delta-cli science invoke --tool xrd --endpoint xqueryer-predictions `
+  --data '{"schema_version":1,"pattern":{"artifact_id":"art_<model>","sha256":"<sha>"},"top_k":10,"radiation_profile":"CuKa"}'
+```
+
+XMatcher 观测曲线：
+
+```text
+delta-cli science invoke --tool xrd --endpoint xmatcher-match `
+  --data '{"schema_version":1,"pattern":{"artifact_id":"art_<observed>","sha256":"<sha>"},"top_n":10,"element_filter_mode":"contains"}'
+```
+
+多相匹配：
+
+```text
+delta-cli science invoke --tool xrd --endpoint xmatcher-multiphase-match `
+  --data '{"schema_version":1,"pattern":{"artifact_id":"art_<observed>","sha256":"<sha>"},"max_phases":3,"candidate_pool":8}'
+```
+
+`xqueryer-predictions` 的 `score` 是 softmax probability；XMatcher 的 `score` 是
+`raw_score / 100`。两者不可直接平均或当作同一校准概率。
+
+## CIF 模拟与峰表
+
+`cifs` 中的每个 artifact 都必须同时提供 `artifact_id` 和 `sha256`：
+
+```text
+delta-cli science invoke --tool xrd --endpoint xmatcher-cif-xrd `
+  --data '{"schema_version":1,"cifs":[{"artifact":{"artifact_id":"art_<cif>","sha256":"<sha>"},"name":"phase"}],"two_theta_range":[5.0,90.0],"wavelength":"CuKa"}'
+```
+
+`xmatcher-pdf-peaks-xlsx` 返回二进制 XLSX；只有用户要求导出时才读取和保存它。
+
+## 精修作业
+
+先生成校正曲线和 provenance manifest：
+
+```text
+delta-cli science invoke --tool xrd --endpoint xmatcher-refinement-patterns `
+  --data '{"schema_version":1,"source_pattern":{"artifact_id":"art_<observed>","sha256":"<sha>"}}'
+```
+
+然后使用与 `data.backends` 匹配的 endpoint。示例结构如下，所有 artifact 身份必须来自
+当前调用链：
+
+```text
+delta-cli science invoke --tool xrd --endpoint refinement-gsasii `
+  --data '{"schema_version":1,"radiation_profile":"CuKa","refinement_pattern":{"observed_pattern":{"artifact_id":"art_<obs>","sha256":"<sha>"},"corrected_pattern":{"artifact_id":"art_<corrected>","sha256":"<sha>"},"provenance_manifest":{"artifact_id":"art_<manifest>","sha256":"<sha>"}},"phases":[{"phase_index":0,"name":"phase","cif":{"artifact_id":"art_<cif>","sha256":"<sha>"}}],"wavelengths_angstrom":[1.540593,1.544414],"backends":["gsasii"]}' `
+  --headers '{"Idempotency-Key":"<stable-unique-key>"}'
+```
+
+`refinement-fullprof`、`refinement-gsasii`、`refinement-wpem` 选择计费/后端入口；不要
+因为它们映射到同一路径就互换 endpoint 名或 `backends`。提交、取消、重试和审核是
+远端变更，必须得到用户明确授权；超时或连接中断时不要盲目重试，先查询是否已经创建
+作业。
+
+查询作业时：
+
+```text
+delta-cli science invoke --tool xrd --endpoint refinement-job `
+  --path-params '{"job_id":"refjob_<returned-id>"}'
+
+delta-cli science invoke --tool xrd --endpoint refinement-job-events `
+  --path-params '{"job_id":"refjob_<returned-id>"}'
+```
+
+## 结果与错误
+
+- 只有 CLI 退出码为 0 且顶层 JSON `ok` 为 `true` 才算调用成功。
+- 原样保留服务返回的 `data`、warnings、错误 detail 和稳定错误码。
+- `202`、`queued` 或 `running` 只代表作业接收/执行状态，不代表 solver 收敛或科学接受。
+- `TIER_CONCURRENCY_EXCEEDED`、`Endpoint is disabled`、`ARTIFACT_MISSING`、
+  `MP500_IDENTITY_MISMATCH` 等错误应停止当前调用链并报告原始 detail；不要换 endpoint、
+  改名、猜参数或用本地算法替代。
+- 付费 endpoint 的价格和可用状态以实时目录为准；执行前确认用户确实要求该业务调用。
+
+证据边界：仅限当前 Delta CLI `data` 中的业务结果。
+调用链：`delta-cli`。
+禁止补充未返回内容：是。