@delta-infra/cli 1.0.80 → 1.0.82

package/skills/delta-science/references/cli-contract.md

@@ -1,83 +1,53 @@
-# Delta CLI 执行约定
-
-## 只能通过内置 wrapper 调用
-
-实时 Science 调用只能由宿主可用的 shell 或 Python 执行内置 wrapper。先定位当前
-`SKILL.md` 所在目录，再执行该目录下 `scripts/invoke.py` 的绝对路径；不得直接执行
-`delta-cli`，也不得改用直接 HTTP。Claude Code 可使用 `CLAUDE_SKILL_DIR` 定位当前
-Skill；Codex 应以当前已加载 Skill 的目录为工作目录，或在已安装的 Skills 目录中查找
-精确的 `delta-science/scripts/invoke.py`。不得依赖宿主私有环境变量。
-
-使用 Python 执行 wrapper。下面的 `wrapper` 必须是上述方法定位到的绝对路径：
-
-```python
-import json, subprocess, sys
-
-wrapper = "/absolute/path/to/delta-science/scripts/invoke.py"
-payload = {"input": "CCO", "format": "smiles"}
-completed = subprocess.run(
-    [sys.executable, wrapper, "--tool", "rdkit", "--endpoint", "parse",
-     "--data-json", json.dumps(payload, ensure_ascii=False)],
-    capture_output=True, text=True, encoding="utf-8", errors="replace",
-    timeout=150,
-)
-result = json.loads(completed.stdout)
-```
-
-不要把调用拼成 shell 命令字符串。禁止使用 `curl`、`httpx`、`requests`、`Invoke-RestMethod` 或业务服务 URL。
-
-wrapper 内部构造以下 argv：
-
-```text
-delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
-```
-
-只有明确记录为查询参数的 operation 才使用 `--params-json`。同一次调用不得同时发送 `--data-json` 和 `--params-json`。
-
-## 可执行文件与配置解析顺序
-
-wrapper 按以下顺序解析 `delta-cli`：
-
-1. `--cli`
-2. `DELTA_CLI_PATH`
-3. `SKILL.md` 同级、未纳入版本控制的 `runtime.local.json`
-4. `PATH` 中的 `delta-cli` 或 `delta-cli.exe`
-5. npm 包相邻的 `bin/delta-cli[.exe]`
-
-CLI 从 `~/.delta-infra/config.json` 读取 `science_base_url`。显式 `--science-base-url` 只用于测试覆盖，并通过 `DELTA_INFRA_SCIENCE_BASE_URL` 传给子进程。
-
-## wrapper 返回结果
-
-成功输出格式：
-
-```json
-{
-  "ok": true,
-  "transport": "delta-cli",
-  "tool": "rdkit",
-  "endpoint": "parse",
-  "elapsed_seconds": 1.23,
-  "envelope_depth": 2,
-  "native": {}
-}
-```
-
-`tools.name` 和 `tool_endpoints.name` 是唯一权威名称。Skill 代码始终把 reference 中的
-tool/operation 原样传给 CLI，CLI 再原样提交给 Science Server；任何一层都不执行旧
-名称映射、前缀裁剪、profile 判断或失败后的改名重试。若 reference 与数据库名称不一致，
-本次调用按 `not_found` 失败结束，应修正数据库配置或 reference，而不是在客户端添加映射。
-
-wrapper 校验 CLI 的 `{ok,data}` 信封，只解包已知的 Infra 转发结果
-`{status_code,headers,data}` 和业务服务信封 `{code,message,data}`。它不会在任意嵌套
-字段中搜索看似合理的结果。`ok=false` 会包含稳定的 `stage`、`error_type`、
-`cli_exit_code` 和错误文本。宿主 shell/Python 的进程成功状态不能覆盖这些字段。
-
-解包成功后，业务结果直接位于 `result["native"]` 顶层。禁止读取
-`result["native"]["data"]`，也禁止递归搜索字段。
-
-即使存在部分数据，`ok=false` 仍必须视为失败。禁止静默切换到其他调用链，也不得在
-最终统计中写“无错误”。业务成功后立即结束，不得为比较模型而追加请求。
-
-## 二进制产物
-
-operation 返回 base64 数据时，只解码文档指定的 native 字段。PNG 文件必须以 `89 50 4e 47 0d 0a 1a 0a` 开头。以 `7b`（`{`）开头的是 JSON，不能描述成图片。
+# Delta CLI 执行约定
+
+## 直接调用 CLI
+
+所有实时 Science 调用都直接执行已安装的 Delta CLI：
+
+```text
+delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
+```
+
+`TOOL` 与 `ENDPOINT` 必须逐字使用当前 reference 或实时目录中的
+`tools.name`、`tool_endpoints.name`；不得增加别名映射、裁剪前缀或在 `not_found` 后改名重试。
+仅当 operation 文档明确要求查询参数时使用 `--params JSON`。不要同时传递 `--data` 和
+`--params`，也不要改用 `curl`、`httpx`、`requests`、`Invoke-RestMethod` 或业务服务 URL。
+
+CLI 使用其标准认证和 `science_base_url` 配置。Skill 不得通过环境变量、命令参数或临时配置
+改写服务路由，也不读取、修改或伪造凭据。
+
+## 成功与结果
+
+CLI 成功时输出单个 JSON 信封：
+
+```json
+{
+  "ok": true,
+  "data": {}
+}
+```
+
+只有 CLI 退出码为 0 且顶层 `ok` 为 `true` 时，才能报告调用成功。顶层 `data` 保存服务响应。
+按 operation reference 规定的响应结构读取字段：若文档明确说明网关或业务信封的 `data`，
+可读取该已知层级；不得递归搜索字段，也不得将业务返回的 `valid:false`、空结果或警告误报为
+CLI 传输失败。
+
+退出码非 0 或顶层 `ok:false` 时，本次调用失败；转发 CLI 的原始错误短摘要，不得切换到
+其他调用链、修改参数或重试可能已执行的远程变更。
+
+## 实时目录
+
+当用户点名 reference 以外的新工具，或 reference 缺失、过期或与 CLI 返回不一致时，依次执行：
+
+```text
+delta-cli science list
+delta-cli science endpoints list TOOL
+```
+
+两次调用都必须满足成功条件。目录只用于获取精确名称；若其未提供足以安全构造请求的 schema，
+说明该限制而不要猜测请求体。
+
+## 二进制产物
+
+operation 返回 base64 数据时，只解码 operation 文档指定的 `data` 字段。PNG 文件必须以
+`89 50 4e 47 0d 0a 1a 0a` 开头。以 `7b`（`{`）开头的是 JSON，不能描述成图片。

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

@@ -1,90 +1,89 @@
-# Delta-BO 详细规则
-
-所有在线调用只走统一 wrapper，tool 固定为 `delta-bo`。当前 CLI catalog 只暴露
-`commands` 和 `generate`；禁止根据旧 HTTP 文档猜测或直连 stateful command API。
-
-## commands
-
-情景：用户要求查看当前部署支持的 Delta-BO 命令。
-
-```python
-result = invoke("delta-bo", "commands")
-native = result["native"]
-```
-
-无 body。只报告当前 native 命令列表，不从历史文档补全。
-
-## generate
-
-情景：针对数值、整数或分类实验变量生成随机搜索或贝叶斯优化建议。
-
-无真实历史，或历史少于 5 条且用户没有明确要求 BO 时，使用有界随机搜索：
-
-```json
-{
-  "params": [
-    {"name": "x", "type": "numeric", "low": 0.0, "high": 1.0}
-  ],
-  "num_suggestions": 3,
-  "algorithm": "random-search",
-  "seed": 42
-}
-```
-
-有真实历史且用户明确要求 BO 时，可以使用：
-
-```json
-{
-  "params": [
-    {"name": "temperature", "type": "numeric", "low": 20.0, "high": 120.0},
-    {"name": "catalyst", "type": "categorical", "choices": ["A", "B", "C"]}
-  ],
-  "objectives": [{"name": "yield", "minimize": false}],
-  "num_suggestions": 2,
-  "algorithm": "bo",
-  "model": {"name": "gp", "min_samples": 2, "train_steps": 50},
-  "acq_target": {"name": "ucb", "beta": 2.0},
-  "solver": {"name": "ga", "pop_size": 40, "n_gen": 10},
-  "histories": {
-    "decisions": [
-      {"temperature": 40.0, "catalyst": "A"},
-      {"temperature": 80.0, "catalyst": "B"}
-    ],
-    "observations": [
-      {"yield": 0.42},
-      {"yield": 0.61}
-    ]
-  },
-  "seed": 7
-}
-```
-
-参数类型仅支持 `numeric`、`integer`、`categorical`。优先使用 object-form history，
-避免数组列顺序歧义。不得编造 observation、目标值或所谓最优点。
-
-可选去重与约束：
-
-```json
-{
-  "diversity": {
-    "deduplicate": true,
-    "min_numeric_distance": {"temperature": 5.0},
-    "prefer_unique_categories": true
-  },
-  "constraints": [
-    {"type": "unique_batch"},
-    {"type": "avoid_seen_decisions"}
-  ]
-}
-```
-
-只报告 native 的 `suggestions`、`suggestion_metadata`、`warnings`、
-`generated_candidate_count` 和 `diversity` 中实际存在的字段。空 suggestions 或失败
-不得用本地 GP、UCB 或随机数替代。
-
-## 已知但未暴露的旧能力
-
-旧服务曾包含 session、space、objective、policy、suggest、observe、loop、status、
-best 等有状态命令，但它们不是当前 Delta CLI operation。本 Skill 只保留这条能力
-边界，不保留 URL 或 curl 示例，也不执行这些操作。需要扩展时，先由 Science Server
-暴露 operation 和请求 schema，再更新本 reference。
+# Delta-BO 详细规则
+
+所有在线调用直接使用 `delta-cli science invoke`，tool 固定为 `delta-bo`。当前 CLI catalog 只暴露
+`commands` 和 `generate`；禁止根据旧 HTTP 文档猜测或直连 stateful command API。
+
+## commands
+
+情景：用户要求查看当前部署支持的 Delta-BO 命令。
+
+```text
+delta-cli science invoke --tool delta-bo --endpoint commands
+```
+
+无 body。只报告当前业务响应中的命令列表，不从历史文档补全。
+
+## generate
+
+情景：针对数值、整数或分类实验变量生成随机搜索或贝叶斯优化建议。
+
+无真实历史，或历史少于 5 条且用户没有明确要求 BO 时，使用有界随机搜索：
+
+```json
+{
+  "params": [
+    {"name": "x", "type": "numeric", "low": 0.0, "high": 1.0}
+  ],
+  "num_suggestions": 3,
+  "algorithm": "random-search",
+  "seed": 42
+}
+```
+
+有真实历史且用户明确要求 BO 时，可以使用：
+
+```json
+{
+  "params": [
+    {"name": "temperature", "type": "numeric", "low": 20.0, "high": 120.0},
+    {"name": "catalyst", "type": "categorical", "choices": ["A", "B", "C"]}
+  ],
+  "objectives": [{"name": "yield", "minimize": false}],
+  "num_suggestions": 2,
+  "algorithm": "bo",
+  "model": {"name": "gp", "min_samples": 2, "train_steps": 50},
+  "acq_target": {"name": "ucb", "beta": 2.0},
+  "solver": {"name": "ga", "pop_size": 40, "n_gen": 10},
+  "histories": {
+    "decisions": [
+      {"temperature": 40.0, "catalyst": "A"},
+      {"temperature": 80.0, "catalyst": "B"}
+    ],
+    "observations": [
+      {"yield": 0.42},
+      {"yield": 0.61}
+    ]
+  },
+  "seed": 7
+}
+```
+
+参数类型仅支持 `numeric`、`integer`、`categorical`。优先使用 object-form history，
+避免数组列顺序歧义。不得编造 observation、目标值或所谓最优点。
+
+可选去重与约束：
+
+```json
+{
+  "diversity": {
+    "deduplicate": true,
+    "min_numeric_distance": {"temperature": 5.0},
+    "prefer_unique_categories": true
+  },
+  "constraints": [
+    {"type": "unique_batch"},
+    {"type": "avoid_seen_decisions"}
+  ]
+}
+```
+
+只报告业务响应的 `suggestions`、`suggestion_metadata`、`warnings`、
+`generated_candidate_count` 和 `diversity` 中实际存在的字段。空 suggestions 或失败
+不得用本地 GP、UCB 或随机数替代。
+
+## 已知但未暴露的旧能力
+
+旧服务曾包含 session、space、objective、policy、suggest、observe、loop、status、
+best 等有状态命令，但它们不是当前 Delta CLI operation。本 Skill 只保留这条能力
+边界，不保留 URL 或 curl 示例，也不执行这些操作。需要扩展时，先由 Science Server
+暴露 operation 和请求 schema，再更新本 reference。

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

@@ -1,116 +1,116 @@
-# GSAS-II 详细规则
-
-所有调用只走统一 wrapper。模拟必须使用真实 CIF；精修必须使用真实 powder data、
-instrument parameters 和 phase CIF，任何失败不得用合成数据补齐。输入不是 CIF 时，
-先使用当前任务中成功的 pymatgen `structure-convert` 结果。
-
-## Health
-
-operation：`health`，无 body。
-
-Key response fields in `data`: `status`, `service`, `gsasii_available`,
-`metadata`, and `limits`.
-
-只有用户明确要求健康检查时才调用；不要在模拟或精修前自动增加 health。
-
-## Powder Simulation
-
-operation：`powder-simulate`。
-
-```json
-{
-  "cif": "<CIF text>",
-  "phase_name": "phase",
-  "instrument_parameters": "<GSAS-II instrument parameter text>",
-  "histogram_name": "simulation",
-  "t_min": 10.0,
-  "t_max": 80.0,
-  "t_step": 0.02,
-  "include_profile": true,
-  "max_profile_points": 1000,
-  "include_reflections": true,
-  "max_reflections": 1000,
-  "return_refined_cif": false,
-  "return_project": false
-}
-```
-
-Use either `t_step` or `n_points`, not both. Optional fields include
-`wavelength`, `radiation`, `scale`, `include_profile`, `max_profile_points`,
-`include_reflections`, `max_reflections`, `return_refined_cif`, and
-`return_project`.
-
-The response includes `profile` points with `x`, `y_calc`, optional background,
-bounded `reflections` with hkl/d-spacing/2theta where available, and metadata.
-If `return_project` is true, `project_base64` contains the GSAS-II `.gpx`
-project. If `return_refined_cif` is true, `refined_cif` contains exported CIF
-text for pymatgen handoff when GSAS-II supports export for the phase.
-
-Notes:
-
-- `cif` should be valid CIF text. If the input is POSCAR/JSON/CSSR/XSF, use
-  pymatgen `structure-convert` first with `output_format: "cif"`.
-- `instrument_parameters` should be GSAS-II instrument parameter text such as
-  `INST_XRY.PRM` when instrument-specific simulation is needed.
-- For quick simulation only, `instrument_parameters` may be omitted. The service
-  then generates a simple CW X-ray instrument model from `wavelength` or
-  `radiation` (`CuKa` by default; also supports aliases such as `MoKa`, `CoKa`,
-  `CrKa`, and explicit numeric wavelength).
-- Refinement still requires real `instrument_parameters`.
-- `max_profile_points` controls response sampling. Use small values for smoke
-  tests and larger values for profile comparison.
-- Older deployed gateway images may require `max_profile_points >= 10`.
-
-## Powder Refinement
-
-operation：`powder-refine`。
-
-```json
-{
-  "powder_data": "<two-column or three-column powder data text>",
-  "powder_format": "xy",
-  "instrument_parameters": "<GSAS-II instrument parameter text>",
-  "phases": [
-    {"name": "phase", "cif": "<CIF text>"}
-  ],
-  "refinement_mode": "rietveld",
-  "refinement_steps": [],
-  "max_cycles": 3,
-  "histogram_name": "powder",
-  "include_profile": true,
-  "max_profile_points": 1000,
-  "include_reflections": true,
-  "max_reflections": 1000,
-  "return_refined_cif": false,
-  "return_project": false
-}
-```
-
-Supported `powder_format` values: `xy`, `xye`, `fxye`, `gsas`, and `csv`.
-
-`refinement_mode: "rietveld"` is currently implemented. `pawley` and `lebail`
-return a clear not-implemented response until the service wires the
-mode-specific GSAS-II setup.
-
-The response includes fit `residuals` when available, phase summaries, sampled
-profile points, bounded `reflections`, warnings, optional `refined_cif`, and
-the optional `.gpx` project.
-
-Notes:
-
-- Use `xy` for simple whitespace-delimited `x y` rows, `xye` for `x y esd`,
-  `csv` for numeric comma-separated rows, or `gsas`/`fxye` for GSAS-like powder
-  formats.
-- `max_cycles: 0` is useful for project-construction smoke tests. Increase it
-  only when the powder data, phase model, instrument file, and refinement steps
-  are realistic.
-- `refinement_steps` is passed to `G2Project.do_refinements`. Keep recipes
-  incremental and inspect `warnings`, `residuals`, and `lst` output.
-- Refinement may return `valid: false` with partial phase/profile information
-  if GSAS-II constructed the project but a refinement step failed.
-
-## 跨工具交接
-
-结构转换、衍射模拟和精修必须在本 Skill 内通过 wrapper 逐步完成：
-`pymatgen structure-convert -> gsasii powder-simulate/powder-refine`。下游只使用上一步
-成功 native 中的结构文本或 profile；不得执行本地脚本或直连服务。
+# GSAS-II 详细规则
+
+所有调用直接使用 `delta-cli science invoke`。模拟必须使用真实 CIF；精修必须使用真实 powder data、
+instrument parameters 和 phase CIF，任何失败不得用合成数据补齐。输入不是 CIF 时，
+先使用当前任务中成功的 pymatgen `structure-convert` 结果。
+
+## Health
+
+operation：`health`，无 body。
+
+Key response fields in `data`: `status`, `service`, `gsasii_available`,
+`metadata`, and `limits`.
+
+只有用户明确要求健康检查时才调用；不要在模拟或精修前自动增加 health。
+
+## Powder Simulation
+
+operation：`powder-simulate`。
+
+```json
+{
+  "cif": "<CIF text>",
+  "phase_name": "phase",
+  "instrument_parameters": "<GSAS-II instrument parameter text>",
+  "histogram_name": "simulation",
+  "t_min": 10.0,
+  "t_max": 80.0,
+  "t_step": 0.02,
+  "include_profile": true,
+  "max_profile_points": 1000,
+  "include_reflections": true,
+  "max_reflections": 1000,
+  "return_refined_cif": false,
+  "return_project": false
+}
+```
+
+Use either `t_step` or `n_points`, not both. Optional fields include
+`wavelength`, `radiation`, `scale`, `include_profile`, `max_profile_points`,
+`include_reflections`, `max_reflections`, `return_refined_cif`, and
+`return_project`.
+
+The response includes `profile` points with `x`, `y_calc`, optional background,
+bounded `reflections` with hkl/d-spacing/2theta where available, and metadata.
+If `return_project` is true, `project_base64` contains the GSAS-II `.gpx`
+project. If `return_refined_cif` is true, `refined_cif` contains exported CIF
+text for pymatgen handoff when GSAS-II supports export for the phase.
+
+Notes:
+
+- `cif` should be valid CIF text. If the input is POSCAR/JSON/CSSR/XSF, use
+  pymatgen `structure-convert` first with `output_format: "cif"`.
+- `instrument_parameters` should be GSAS-II instrument parameter text such as
+  `INST_XRY.PRM` when instrument-specific simulation is needed.
+- For quick simulation only, `instrument_parameters` may be omitted. The service
+  then generates a simple CW X-ray instrument model from `wavelength` or
+  `radiation` (`CuKa` by default; also supports aliases such as `MoKa`, `CoKa`,
+  `CrKa`, and explicit numeric wavelength).
+- Refinement still requires real `instrument_parameters`.
+- `max_profile_points` controls response sampling. Use small values for smoke
+  tests and larger values for profile comparison.
+- Older deployed gateway images may require `max_profile_points >= 10`.
+
+## Powder Refinement
+
+operation：`powder-refine`。
+
+```json
+{
+  "powder_data": "<two-column or three-column powder data text>",
+  "powder_format": "xy",
+  "instrument_parameters": "<GSAS-II instrument parameter text>",
+  "phases": [
+    {"name": "phase", "cif": "<CIF text>"}
+  ],
+  "refinement_mode": "rietveld",
+  "refinement_steps": [],
+  "max_cycles": 3,
+  "histogram_name": "powder",
+  "include_profile": true,
+  "max_profile_points": 1000,
+  "include_reflections": true,
+  "max_reflections": 1000,
+  "return_refined_cif": false,
+  "return_project": false
+}
+```
+
+Supported `powder_format` values: `xy`, `xye`, `fxye`, `gsas`, and `csv`.
+
+`refinement_mode: "rietveld"` is currently implemented. `pawley` and `lebail`
+return a clear not-implemented response until the service wires the
+mode-specific GSAS-II setup.
+
+The response includes fit `residuals` when available, phase summaries, sampled
+profile points, bounded `reflections`, warnings, optional `refined_cif`, and
+the optional `.gpx` project.
+
+Notes:
+
+- Use `xy` for simple whitespace-delimited `x y` rows, `xye` for `x y esd`,
+  `csv` for numeric comma-separated rows, or `gsas`/`fxye` for GSAS-like powder
+  formats.
+- `max_cycles: 0` is useful for project-construction smoke tests. Increase it
+  only when the powder data, phase model, instrument file, and refinement steps
+  are realistic.
+- `refinement_steps` is passed to `G2Project.do_refinements`. Keep recipes
+  incremental and inspect `warnings`, `residuals`, and `lst` output.
+- Refinement may return `valid: false` with partial phase/profile information
+  if GSAS-II constructed the project but a refinement step failed.
+
+## 跨工具交接
+
+结构转换、衍射模拟和精修必须在本 Skill 内通过 CLI 逐步完成：
+`pymatgen structure-convert -> gsasii powder-simulate/powder-refine`。下游只使用上一步
+成功业务响应中的结构文本或 profile；不得执行本地脚本或直连服务。