@delta-infra/cli 1.0.97 → 1.0.98

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/空间群、材料表格建模与候选推荐、Quantum ESPRESSO/QE DFT、模拟或精修 XRD、执行 LAMMPS、根据实验数据做贝叶斯优化、反应条件优化，以及任何 LDM/大发现模型、KRAS G12D 小分子生成优化、固定候选池/PDF2Dock 轨迹或抗体 CDRH3 优化任务，都必须使用本 Skill；不得调用旧 large-discovery-model Skill、旧 gateway 脚本、网页搜索或本地科学库绕过 Delta CLI。普通查询、比较或校验默认直接返回文本，不要主动增加 JSON/CSV、报告、图片或图表步骤；只有用户明确要求保存、导出、绘图或生成文件时才创建产物。"
 metadata:
   requires:
     bins: ["delta-cli"]
@@ -38,12 +38,12 @@ delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
 ```
 
 仅当 reference 明确将字段定义为查询参数时使用 `--params JSON`。不要将 JSON 拼接为命令
-代码；使用调用环境的安全参数传递机制传入单个 JSON 参数。
-
-Materials Design 的训练表 multipart 上传、QE 的原始 artifact 上传和要求自定义
-`Idempotency-Key` 的请求，只有在 Science Server 已提供明确的 JSON/query adapter 时才能
-通过本 CLI 使用。不要把本地路径、base64 或请求头伪装成普通 `--data` 字段；若目录没有
-这样的 adapter，按“未暴露、未发送远端请求”处理，不要直连 preflight Gateway。
+代码；使用调用环境的安全参数传递机制传入单个 JSON 参数。
+
+Materials Design 的训练表 multipart 上传、QE 的原始 artifact 上传和要求自定义
+`Idempotency-Key` 的请求，只有在 Science Server 已提供明确的 JSON/query adapter 时才能
+通过本 CLI 使用。不要把本地路径、base64 或请求头伪装成普通 `--data` 字段；若目录没有
+这样的 adapter，按“未暴露、未发送远端请求”处理，不要直连 preflight Gateway。
 
 只调用完成目标所需的 operation。跨工具任务在同一个 Skill 执行中按依赖顺序调用，
 下游只能使用上一步已验证的业务字段。已知工具默认不要额外调用 health、schema、
@@ -54,46 +54,45 @@ catalog、render、descriptors 或文件操作；用户请求、诊断需要或
 
 | 科研目标 | tool | 详细规则 |
 | --- | --- | --- |
-| 化合物身份、CID、同义词、公共属性、名称转 SMILES | `pubchem` | [pubchem.md](references/pubchem.md) |
-| SMILES/InChI、描述符、指纹、相似度、渲染、子结构 | `rdkit` | [rdkit.md](references/rdkit.md) |
-| 批量名称解析并联合 PubChem/RDKit 增强 | `chemistry` | [molecule-enrich.md](references/molecule-enrich.md) |
-| 无机化学式、CIF/POSCAR、晶体结构、空间群 | `pymatgen` | [pymatgen.md](references/pymatgen.md) |
+| 化合物身份、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) |
-| 分子动力学、最小化、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) |
-| Quantum ESPRESSO/QE 的 PP、异步 DFT 作业、日志与 artifact | `qe` | [qe-dft.md](references/qe-dft.md) |
-| 固定候选池 next-SMILES、PDF2Dock、分子 BO 轨迹 | `ldm-bo` | [ldm-bo.md](references/ldm-bo.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) |
+| Quantum ESPRESSO/QE 的 PP、异步 DFT 作业、日志与 artifact | `qe` | [qe.md](references/qe.md) |
+| 固定候选池 next-SMILES、PDF2Dock、分子 BO 轨迹 | `ldm-bo` | [ldm-bo.md](references/ldm-bo.md) |
 | KRAS G12D 小分子生成、vina/activity 多目标迭代 | `strbo` | [strbo.md](references/strbo.md) |
 | 反应条件初始化、基于真实得率推荐下一批实验 | `synbo` | [synbo.md](references/synbo.md) |
 | 抗体 CDRH3 生成/评估及 AntBO 作业管理 | `antbo` | [antbo.md](references/antbo.md) |
 
-用户使用 “LDM”“大发现模型”“小分子药 LDM” 或 “抗体 LDM” 表述完整科研流程时，
-先读取 [ldm.md](references/ldm.md)，再只读取其中选定后端对应的一个 reference。
-`ldm.md` 是编排规则，不是 tool，不得把 `ldm` 当作 `--tool` 参数。
-
-工具明确时直接读取所选 tool 的 reference，其中已经包含 operation、参数和最小场景；
-不要读取其他工具文档。只有任务在两个或多个工具之间存在歧义时，才先读
-[routing-index.md](references/routing-index.md)。跨工具任务再读
-[workflows.md](references/workflows.md)。
+用户使用 “LDM”“大发现模型”“小分子药 LDM” 或 “抗体 LDM” 表述完整科研流程时，
+先根据任务目标选择真实后端工具，再只读取所选后端对应的 reference；`ldm-bo` 是可调用的
+工具，`LDM` 本身不是 `--tool` 参数。若用户说“批量分子增强”或类似需求，应拆成真实
+工具调用：先用 `pubchem` 做名称/标识解析，再用 `rdkit` 做结构标准化或分子计算。
+
+工具明确时直接读取所选 tool 的 reference，其中已经包含 operation、参数和最小场景；
+不要读取其他工具文档。跨工具任务由本 Skill 的路由规则拆分，并只读取实际参与任务的
+工具 reference；不要依赖单独的路由、服务、工作流或目录文档。
 
-本表是经过验证的科研路由，不是服务端工具清单。若用户点名本表之外的新工具，或 reference
-缺失、过期或与 CLI 返回不一致，允许运行 `delta-cli science list`，再使用目录返回的精确 tool name 运行一次
+本表只列出已经维护真实工具 reference 的科研工具，不是静态服务端清单。若用户点名本表之外的新工具，或 reference
+缺失、过期或与 CLI 返回不一致，允许运行 `delta-cli science list`，再使用目录返回的精确 tool name 运行一次
 `delta-cli science endpoints list <tool>`；两次输出都必须满足退出码为 0 且顶层
 `ok:true`。不得用空 body、错误参数、源码或直接 HTTP 探测。实时 endpoint
 元数据若没有足够的请求字段契约，应说明“目录已发现，
 但服务端未提供可安全构造请求的 schema”，不得猜 body、模糊匹配或转换名称。新增工具
-因此无需修改 CLI；只有需要自然语言自动选路或自动组装参数时，才补充对应 reference。
+因此无需修改 CLI；只有确认它是独立真实工具并需要自然语言自动选路或自动组装参数时，才补充对应的单工具 reference。
 
 ## 路由边界
 
-- 普通分子名称先用 PubChem；只有需要结构计算时才把成功返回的 SMILES 交给 RDKit。
-- 无机化学式、组成和式量优先 pymatgen，不用 PubChem 或本地元素表补算。
-- 表格材料建模与候选排序使用 Materials Design；必须区分可控变量、目标、候选空间、
-  交叉验证和不确定性，推荐结果只是待验证假设。
-- 需要显式电子结构计算时使用 QE；先处理元素全集、PP policy/lock 和结构 artifact，
-  再提交异步 workflow，不把作业接收、scheduler 完成或 solver 收敛混为一谈。
-- 通用实验变量使用 Delta-BO；已有固定 SMILES 候选池或 PDF2Dock 轨迹使用 LDM-BO；
+- 普通分子名称先用 PubChem；只有需要结构计算时才把成功返回的 SMILES 交给 RDKit。
+- 无机化学式、组成和式量优先 pymatgen，不用 PubChem 或本地元素表补算。
+- 表格材料建模与候选排序使用 Materials Design；必须区分可控变量、目标、候选空间、
+  交叉验证和不确定性，推荐结果只是待验证假设。
+- 需要显式电子结构计算时使用 QE；先处理元素全集、PP policy/lock 和结构 artifact，
+  再提交异步 workflow，不把作业接收、scheduler 完成或 solver 收敛混为一谈。
+- 通用实验变量使用 Delta-BO；已有固定 SMILES 候选池或 PDF2Dock 轨迹使用 LDM-BO；
   围绕服务端固定 KRAS G12D 生成并迭代小分子使用 STRBO；偶联反应、反应条件和历史
   得率使用 SynBO；抗体/CDRH3 使用 AntBO，不得混用。
 - 在线 LDM、STRBO、AntBO 和 LDM-BO 任务不得转交旧 `large-discovery-model` Skill，

package/skills/delta-science/references/materials-design.md

@@ -1,109 +1,109 @@
-# Materials Design 详细规则
-
-Materials Design 用于从实验或计算材料表格中建立 surrogate、验证模型、定义可行候选空间，
-并生成带不确定性的候选排序。推荐是待验证假设，不是已确认材料、合成方案或实验结果。
-
-本 reference 的路由标签是 `materials-design`。`tools.name` 和
-`tool_endpoints.name` 仍以当前 `delta-cli science list` 和
-`delta-cli science endpoints list <tool>` 的返回为准；下列 Gateway 路径只是服务契约，
-不是可以直接拼接或访问的 URL。
-
-## 服务边界
-
-服务提供以下能力：
-
-| 服务路径 | 作用 | 结果边界 |
-| --- | --- | --- |
-| `/chem/materials-design/health` | Gateway 到服务的就绪检查 | `status`、依赖可用性、limits |
-| `/chem/materials-design/v1/capabilities` | 输入格式、模型、验证模式和限制 | 能力目录 |
-| `/chem/materials-design/v1/jobs` | 上传训练/候选表并创建异步作业 | `202`、`job_id`、状态和 links |
-| `/chem/materials-design/v1/jobs/{job_id}` | 查询作业 | `status`、`result_status`、result、warnings |
-| `/chem/materials-design/v1/jobs/{job_id}/cancel` | 请求取消 | 取消请求/终态 |
-| `/chem/materials-design/v1/jobs/{job_id}/artifacts` | 列出产物 | name、size、media_type、SHA-256 |
-| `/chem/materials-design/v1/jobs/{job_id}/artifacts/{path}` | 下载单个产物 | 原始 report/JSON/CSV/figure bytes |
-
-所有实时调用都必须走：
-
-```text
-delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
-```
-
-只读 query operation 才使用 `--params JSON`。如果新工具尚未出现在目录中，或目录没有
-返回足够的请求 schema，停止并报告未暴露；不要猜测 endpoint 名、body 或兼容别名。
-
-## CLI 能力边界
-
-`POST /v1/jobs` 的原始服务请求是 `multipart/form-data`，至少包含：
-
-```text
-file=<training table>
-candidate_file=<optional candidate table>
-config=<serialized JSON object>
-```
-
-当前通用 `delta-cli science invoke` 只接受 JSON object body 和 JSON query 参数，不能表达
-multipart 文件上传，也不能把本地路径或 base64 伪装成文件字段。artifact 下载同样是原始
-bytes，不应当当作普通 JSON 结果。只有 Science Server 目录明确提供等价的文件/adapter
-operation 时，才通过 CLI 调用；否则 Materials Design 的作业提交或文件下载属于当前 CLI
-未暴露能力，未发送远端请求。不得调用 `materials-design-service:8900` 或直连 preflight
-Gateway。
-
-## 输入与配置
-
-开始建模前必须确认：
-
-- `feature_columns`、`controllable_columns`、`target_column` 或 `objectives`；
-- identifier、metadata、leakage、post-measurement、group/time 列及单位；
-- 目标方向、可行性约束、候选表或候选生成规则；
-- 缺失值、重复样本、测量条件、数据来源和验证切分策略。
-
-单目标配置的核心字段：
-
-```json
-{
-  "feature_columns": ["Bi", "In", "Ti"],
-  "controllable_columns": ["Bi", "In", "Ti"],
-  "identifier_columns": ["sample_id"],
-  "target_column": "T",
-  "target_direction": "maximize",
-  "validation": {"strategy": "kfold", "n_splits": 5},
-  "model_names": ["ExtraTrees", "GPR", "Ridge"],
-  "random_state": 42,
-  "recommendation_count": 10
-}
-```
-
-多目标使用 `objectives: [{"target_column": "...", "direction": "maximize|minimize"}]`
-和显式的 Pareto/EHVI 配置。优先传入用户的 `candidate_file`；若服务按观测范围生成
-候选，必须显式保留 steps、hard constraints、composition closure、`max_candidates` 和
-`allow_extrapolation`。禁止优化 identifier、测量后变量、泄漏列或未获授权的域外点，禁止
-为填充候选数而任意外推。
-
-## 结果处理
-
-作业 `status` 与 `result_status` 必须分开判断：
-
-- `status`：`pending`、`running`、`completed`、`failed`、`cancelled`；
-- `result_status`：`complete`、`exploratory`、`readiness_only` 或 `failed`。
-
-`202` 只表示服务已接收/排队，不表示模型训练完成；`completed` 也不表示排序可靠。
-只有在 `result_status` 为 `complete` 时才能说数据和验证支持候选排序；`exploratory` 只能
-作为学习假设；`readiness_only` 要读取 readiness 信息并请求缺失输入；`failed` 原样报告。
-始终保留服务返回的 validation、ranking、warnings 和 error。
-
-预测结果必须和观测值、交叉验证预测区分。报告至少说明数据覆盖、切分、模型比较、
-不确定性校准、候选可行性、域内/域外状态、EI/PI/UCB 或 Pareto 设置，以及后续实验验证
-计划；不要用模型方差冒充实验误差或把候选预测写成实测值。
-
-## Artifact 与错误
-
-只有用户要求或工作流需要时才读取 artifacts。按 listing 返回的 `size`、`media_type` 和
-SHA-256 校验下载内容；不能凭文件名猜格式。服务可能产生 `report.html`、`result.json`、
-`data_dictionary.json`、`model_comparison.csv`、OOF/残差/校准文件、`search_space.json`、
-`candidate_predictions.csv`、`shortlist.csv`、`recommendation_views.csv`、
-`pareto_front.csv` 和 `figures/*`。
-
-常见终止条件包括配置/文件格式错误、缺目标或候选空间、超出上传/行数/候选数限制、
-后端未就绪、作业不存在和 artifact 不存在。提交超时或连接中断时不要盲目重试：multipart
-上传可能已经创建作业，先检查是否已经得到 `job_id`。失败或空推荐不得用本地回归、GP、
-随机数或人工排序替代。
+# Materials Design 详细规则
+
+Materials Design 用于从实验或计算材料表格中建立 surrogate、验证模型、定义可行候选空间，
+并生成带不确定性的候选排序。推荐是待验证假设，不是已确认材料、合成方案或实验结果。
+
+本 reference 的路由标签是 `materials-design`。`tools.name` 和
+`tool_endpoints.name` 仍以当前 `delta-cli science list` 和
+`delta-cli science endpoints list <tool>` 的返回为准；下列 Gateway 路径只是服务契约，
+不是可以直接拼接或访问的 URL。
+
+## 服务边界
+
+服务提供以下能力：
+
+| 服务路径 | 作用 | 结果边界 |
+| --- | --- | --- |
+| `/chem/materials-design/health` | Gateway 到服务的就绪检查 | `status`、依赖可用性、limits |
+| `/chem/materials-design/v1/capabilities` | 输入格式、模型、验证模式和限制 | 能力目录 |
+| `/chem/materials-design/v1/jobs` | 上传训练/候选表并创建异步作业 | `202`、`job_id`、状态和 links |
+| `/chem/materials-design/v1/jobs/{job_id}` | 查询作业 | `status`、`result_status`、result、warnings |
+| `/chem/materials-design/v1/jobs/{job_id}/cancel` | 请求取消 | 取消请求/终态 |
+| `/chem/materials-design/v1/jobs/{job_id}/artifacts` | 列出产物 | name、size、media_type、SHA-256 |
+| `/chem/materials-design/v1/jobs/{job_id}/artifacts/{path}` | 下载单个产物 | 原始 report/JSON/CSV/figure bytes |
+
+所有实时调用都必须走：
+
+```text
+delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
+```
+
+只读 query operation 才使用 `--params JSON`。如果新工具尚未出现在目录中，或目录没有
+返回足够的请求 schema，停止并报告未暴露；不要猜测 endpoint 名、body 或兼容别名。
+
+## CLI 能力边界
+
+`POST /v1/jobs` 的原始服务请求是 `multipart/form-data`，至少包含：
+
+```text
+file=<training table>
+candidate_file=<optional candidate table>
+config=<serialized JSON object>
+```
+
+当前通用 `delta-cli science invoke` 只接受 JSON object body 和 JSON query 参数，不能表达
+multipart 文件上传，也不能把本地路径或 base64 伪装成文件字段。artifact 下载同样是原始
+bytes，不应当当作普通 JSON 结果。只有 Science Server 目录明确提供等价的文件/adapter
+operation 时，才通过 CLI 调用；否则 Materials Design 的作业提交或文件下载属于当前 CLI
+未暴露能力，未发送远端请求。不得调用 `materials-design-service:8900` 或直连 preflight
+Gateway。
+
+## 输入与配置
+
+开始建模前必须确认：
+
+- `feature_columns`、`controllable_columns`、`target_column` 或 `objectives`；
+- identifier、metadata、leakage、post-measurement、group/time 列及单位；
+- 目标方向、可行性约束、候选表或候选生成规则；
+- 缺失值、重复样本、测量条件、数据来源和验证切分策略。
+
+单目标配置的核心字段：
+
+```json
+{
+  "feature_columns": ["Bi", "In", "Ti"],
+  "controllable_columns": ["Bi", "In", "Ti"],
+  "identifier_columns": ["sample_id"],
+  "target_column": "T",
+  "target_direction": "maximize",
+  "validation": {"strategy": "kfold", "n_splits": 5},
+  "model_names": ["ExtraTrees", "GPR", "Ridge"],
+  "random_state": 42,
+  "recommendation_count": 10
+}
+```
+
+多目标使用 `objectives: [{"target_column": "...", "direction": "maximize|minimize"}]`
+和显式的 Pareto/EHVI 配置。优先传入用户的 `candidate_file`；若服务按观测范围生成
+候选，必须显式保留 steps、hard constraints、composition closure、`max_candidates` 和
+`allow_extrapolation`。禁止优化 identifier、测量后变量、泄漏列或未获授权的域外点，禁止
+为填充候选数而任意外推。
+
+## 结果处理
+
+作业 `status` 与 `result_status` 必须分开判断：
+
+- `status`：`pending`、`running`、`completed`、`failed`、`cancelled`；
+- `result_status`：`complete`、`exploratory`、`readiness_only` 或 `failed`。
+
+`202` 只表示服务已接收/排队，不表示模型训练完成；`completed` 也不表示排序可靠。
+只有在 `result_status` 为 `complete` 时才能说数据和验证支持候选排序；`exploratory` 只能
+作为学习假设；`readiness_only` 要读取 readiness 信息并请求缺失输入；`failed` 原样报告。
+始终保留服务返回的 validation、ranking、warnings 和 error。
+
+预测结果必须和观测值、交叉验证预测区分。报告至少说明数据覆盖、切分、模型比较、
+不确定性校准、候选可行性、域内/域外状态、EI/PI/UCB 或 Pareto 设置，以及后续实验验证
+计划；不要用模型方差冒充实验误差或把候选预测写成实测值。
+
+## Artifact 与错误
+
+只有用户要求或工作流需要时才读取 artifacts。按 listing 返回的 `size`、`media_type` 和
+SHA-256 校验下载内容；不能凭文件名猜格式。服务可能产生 `report.html`、`result.json`、
+`data_dictionary.json`、`model_comparison.csv`、OOF/残差/校准文件、`search_space.json`、
+`candidate_predictions.csv`、`shortlist.csv`、`recommendation_views.csv`、
+`pareto_front.csv` 和 `figures/*`。
+
+常见终止条件包括配置/文件格式错误、缺目标或候选空间、超出上传/行数/候选数限制、
+后端未就绪、作业不存在和 artifact 不存在。提交超时或连接中断时不要盲目重试：multipart
+上传可能已经创建作业，先检查是否已经得到 `job_id`。失败或空推荐不得用本地回归、GP、
+随机数或人工排序替代。

package/skills/delta-science/references/{qe-dft.md → qe.md}

@@ -4,9 +4,9 @@ QE 用于通过 Chemistry Gateway 执行可追踪的异步 Quantum ESPRESSO 工
 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 别名。
+本 reference 对应 CLI 的真实工具为 `qe`。实际 `tools.name` 与 `tool_endpoints.name`
+必须逐字取自当前 CLI catalog。下列路径是 QE 服务契约，不是可直接访问的 URL，也不是
+可以自动改写的 endpoint 别名。
 
 ## 能力分组
 
@@ -21,7 +21,7 @@ Gateway/Science Server contract，不运行本地 `pw.x`，不调用内部 QE
 | `/chem/qe/v1/qe/jobs/{job_id}/events`、`steps`、`logs`、`artifacts` | 读取作业过程和结果 | 只读 |
 | `/chem/qe/v1/qe/jobs/{job_id}:cancel`、`:retry`、`:review` | 取消、重试和科学审核 | 远端变更 |
 
-选择新工具或新 operation 时，依次使用：
+选择新 operation 时，先使用：
 
 ```text
 delta-cli science list

package/skills/delta-science/scripts/invoke.py

@@ -9,11 +9,11 @@ import os
 from pathlib import Path
 import shutil
 import subprocess
-import sys
-import time
-from typing import Any
+import sys
+import time
+from typing import Any
 
-SKILL_DIR = Path(__file__).resolve().parents[1]
+SKILL_DIR = Path(__file__).resolve().parents[1]
 _CLI_ERROR_TYPES = {
     2: "validation",
     3: "auth",
@@ -170,7 +170,7 @@ def _resolve_cli(explicit: str | None, runtime: dict[str, Any]) -> str:
     )
 
 
-def _unwrap(stdout: str) -> tuple[Any, int]:
+def _unwrap(stdout: str) -> tuple[Any, int]:
     try:
         root = json.loads(stdout)
     except json.JSONDecodeError as exc:
@@ -223,7 +223,7 @@ def _validate_native(tool: str, endpoint: str, native: Any) -> None:
             raise RuntimeError("SynBO optimize returned no recommendations")
 
 
-def _parse_cli_error(completed: subprocess.CompletedProcess[str]) -> tuple[str, str]:
+def _parse_cli_error(completed: subprocess.CompletedProcess[str]) -> tuple[str, str]:
     detail = completed.stderr.strip() or completed.stdout.strip()
     error_type = _CLI_ERROR_TYPES.get(completed.returncode, "cli")
     try:
@@ -236,27 +236,27 @@ def _parse_cli_error(completed: subprocess.CompletedProcess[str]) -> tuple[str,
                 detail = str(message)
     except (AttributeError, json.JSONDecodeError):
         pass
-    return error_type, detail
-
-
-def _parser() -> argparse.ArgumentParser:
+    return error_type, detail
+
+
+def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--tool", required=True)
     parser.add_argument("--endpoint", required=True)
     body = parser.add_mutually_exclusive_group()
     body.add_argument("--data-json")
-    body.add_argument("--params-json")
-    parser.add_argument("--cli")
-    parser.add_argument("--science-base-url")
-    parser.add_argument("--timeout", type=float, default=120.0)
+    body.add_argument("--params-json")
+    parser.add_argument("--cli")
+    parser.add_argument("--science-base-url")
+    parser.add_argument("--timeout", type=float, default=120.0)
     return parser
 
 
 def main() -> int:
-    args = _parser().parse_args()
-    started = time.perf_counter()
-    stage = "arguments"
-    cli_exit_code: int | None = None
+    args = _parser().parse_args()
+    started = time.perf_counter()
+    stage = "arguments"
+    cli_exit_code: int | None = None
     error_type = "unknown"
     normalization: dict[str, Any] | None = None
     try:
@@ -270,22 +270,22 @@ def main() -> int:
         cli = _resolve_cli(args.cli, runtime)
 
         env = os.environ.copy()
-        base_url = args.science_base_url or runtime.get("science_base_url")
-        if base_url:
-            env["DELTA_INFRA_SCIENCE_BASE_URL"] = str(base_url)
-
-        command = [
-            cli, "science", "invoke",
-            "--tool", args.tool,
-            "--endpoint", args.endpoint,
-        ]
+        base_url = args.science_base_url or runtime.get("science_base_url")
+        if base_url:
+            env["DELTA_INFRA_SCIENCE_BASE_URL"] = str(base_url)
+
+        command = [
+            cli, "science", "invoke",
+            "--tool", args.tool,
+            "--endpoint", args.endpoint,
+        ]
         if data is not None:
             command.extend(["--data", json.dumps(data, ensure_ascii=False, separators=(",", ":"))])
         if params is not None:
             command.extend(["--params", json.dumps(params, ensure_ascii=False, separators=(",", ":"))])
 
         stage = "delta-cli"
-        completed = subprocess.run(
+        completed = subprocess.run(
             command,
             capture_output=True,
             text=True,
@@ -294,20 +294,20 @@ def main() -> int:
             env=env,
             timeout=args.timeout,
             check=False,
-        )
-        if completed.returncode != 0:
-            cli_exit_code = completed.returncode
-            error_type, detail = _parse_cli_error(completed)
-            raise RuntimeError(f"exit_code={completed.returncode}: {detail}")
-        stage = "response-validation"
-        native, depth = _unwrap(completed.stdout)
-        _validate_native(args.tool, args.endpoint, native)
+        )
+        if completed.returncode != 0:
+            cli_exit_code = completed.returncode
+            error_type, detail = _parse_cli_error(completed)
+            raise RuntimeError(f"exit_code={completed.returncode}: {detail}")
+        stage = "response-validation"
+        native, depth = _unwrap(completed.stdout)
+        _validate_native(args.tool, args.endpoint, native)
         result = {
             "ok": True,
-            "transport": "delta-cli",
-            "tool": args.tool,
-            "endpoint": args.endpoint,
-            "elapsed_seconds": round(time.perf_counter() - started, 3),
+            "transport": "delta-cli",
+            "tool": args.tool,
+            "endpoint": args.endpoint,
+            "elapsed_seconds": round(time.perf_counter() - started, 3),
             "envelope_depth": depth,
             "native": native,
         }
@@ -330,10 +330,10 @@ def main() -> int:
         error = str(exc)
     print(json.dumps({
         "ok": False,
-        "transport": "delta-cli",
-        "tool": args.tool,
-        "endpoint": args.endpoint,
-        "stage": stage,
+        "transport": "delta-cli",
+        "tool": args.tool,
+        "endpoint": args.endpoint,
+        "stage": stage,
         "error_type": error_type,
         "cli_exit_code": cli_exit_code,
         "elapsed_seconds": round(time.perf_counter() - started, 3),

package/skills/delta-shared/SKILL.md

@@ -60,7 +60,7 @@ CLI 使用 `token` 发送请求头 `Authorization: Bearer <token>`，并自动
 
 AI Agent 解析规则：
 - 始终检查 `ok`，不要只看 exit code。
-- `error.type` 是稳定分支字段：`auth`, `permission`, `not_found`, `validation`, `network`, `api`, `internal`。
+- `error.type` 是稳定分支字段：`auth`, `permission`, `not_found`, `validation`, `network`, `api`, `command_failed`, `internal`。
 - `error.hint` 可展示给用户。
 
 ## 退出码约定
@@ -73,6 +73,7 @@ AI Agent 解析规则：
 | not_found | 5 | sandbox/file 不存在 |
 | network | 6 | DNS、超时、连接失败 |
 | api | 7 | 服务端非 2xx |
+| command_failed | 8 | sandbox 内命令执行失败（非零 exit_code 或报错）；SSE 路径在 complete 帧后追加该 error 信封，**message 附 stderr 尾部**便于快速扫读 |
 | internal | 10 | 客户端内部错误 |
 
 ## 升级检查
@@ -92,4 +93,5 @@ delta-cli upgrade
 | `error.type: not_found` | 检查 `sandbox_id` / path |
 | `error.type: network` | 检查 `base_url` 和网络连通性 |
 | `error.type: validation` | 检查必填 flag 和参数格式 |
+| `error.type: command_failed` | sandbox 内命令失败：信封 `message` 已带 stderr 尾部，可快速定位；完整 `stderr`/`result_summary` 在 complete 帧里，重试或修正命令 |
 | 配置文件解析失败 | 检查 `~/.delta-infra/config.json` 是否为有效 JSON |

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

@@ -1,53 +0,0 @@
-# Delta CLI 执行约定
-
-## 使用 CLI
-
-所有实时 Science 调用最终都使用已安装的 Delta CLI；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 使用其标准认证和由 `base_url` 派生出的 Science 服务地址（`{base_url}/science_tool`）。
-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/generated-catalog.md

@@ -1,48 +0,0 @@
-# Science catalog（自动生成）
-
-本文件由 `skills/science-tools.json` 生成；不要手工修改。规范名称供 CLI/Skill 使用，legacy 名称仅用于兼容已部署的 `/science_tool` catalog。
-
-| 规范 tool | Skill | 类别 | operation | legacy endpoint |
-| --- | --- | --- | --- | --- |
-| pubchem | pubchem | molecule-information | health | chem_pubchem_health |
-| pubchem | pubchem | molecule-information | compound-resolve-cids | chem_pubchem_compound_resolve-cids |
-| pubchem | pubchem | molecule-information | compound-properties | chem_pubchem_compound_properties |
-| pubchem | pubchem | molecule-information | compound-synonyms | chem_pubchem_compound_synonyms |
-| pubchem | pubchem | molecule-information | compound-summary | chem_pubchem_compound_summary |
-| pubchem | pubchem | molecule-information | compound-batch-summary | chem_pubchem_compound_batch-summary |
-| rdkit | rdkit | cheminformatics | health | chem_rdkit_health |
-| rdkit | rdkit | cheminformatics | parse | chem_rdkit_parse |
-| rdkit | rdkit | cheminformatics | descriptors | chem_rdkit_descriptors |
-| rdkit | rdkit | cheminformatics | batch-descriptors | chem_rdkit_batch-descriptors |
-| rdkit | rdkit | cheminformatics | batch-parse-describe | chem_rdkit_batch-parse-describe |
-| rdkit | rdkit | cheminformatics | render | chem_rdkit_render |
-| rdkit | rdkit | cheminformatics | fingerprint | chem_rdkit_fingerprint |
-| rdkit | rdkit | cheminformatics | similarity | chem_rdkit_similarity |
-| rdkit | rdkit | cheminformatics | similarity-matrix | chem_rdkit_similarity-matrix |
-| rdkit | rdkit | cheminformatics | substructure | chem_rdkit_substructure |
-| pymatgen | pymatgen | materials-informatics | health | chem_pymatgen_health |
-| pymatgen | pymatgen | materials-informatics | composition-parse | chem_pymatgen_composition_parse |
-| pymatgen | pymatgen | materials-informatics | structure-parse | chem_pymatgen_structure_parse |
-| pymatgen | pymatgen | materials-informatics | structure-summary | chem_pymatgen_structure_summary |
-| pymatgen | pymatgen | materials-informatics | structure-convert | chem_pymatgen_structure_convert |
-| pymatgen | pymatgen | materials-informatics | structure-symmetry | chem_pymatgen_structure_symmetry |
-| gsasii | gsasii | diffraction | health | chem_gsasii_health |
-| gsasii | gsasii | diffraction | powder-simulate | chem_gsasii_powder_simulate |
-| gsasii | gsasii | diffraction | powder-refine | chem_gsasii_powder_refine |
-| lammps | lammps | molecular-dynamics | health | chem_lammps_health |
-| lammps | lammps | molecular-dynamics | lj-melt-example | chem_lammps_examples_lj-melt |
-| lammps | lammps | molecular-dynamics | run | chem_lammps_run |
-| delta-bo | delta-bo | optimization | commands | chem_delta-bo_commands |
-| delta-bo | delta-bo | optimization | generate | chem_delta-bo_generate |
-| ldm-bo | ldm-bo | molecule-optimization | health | chem_ldm-bo_health |
-| ldm-bo | ldm-bo | molecule-optimization | recommend | chem_ldm-bo_recommend |
-| ldm-bo | ldm-bo | molecule-optimization | trajectory | chem_ldm-bo_trajectory |
-| synbo | synbo-service | reaction-optimization | health | chem_synbo_health |
-| synbo | synbo-service | reaction-optimization | initialize | chem_synbo_initialize |
-| synbo | synbo-service | reaction-optimization | optimize | chem_synbo_optimize |
-| antbo | antbo-service | antibody-optimization | health | biology_antbo_health |
-| antbo | antbo-service | antibody-optimization | run-default-job | biology_antbo_run_default_job |
-| antbo | antbo-service | antibody-optimization | run | biology_antbo_run |
-| antbo | antbo-service | antibody-optimization | log | biology_antbo_log |
-| antbo | antbo-service | antibody-optimization | jobs | biology_antbo_jobs |
-| antbo | antbo-service | antibody-optimization | stop | biology_antbo_stop |