@delta-infra/cli 1.1.0 → 1.1.2

package/README.md

@@ -271,11 +271,21 @@ delta-cli sandbox kill <sandbox_id>
 | `delta-cli science get <tool_name>` | 查看指定工具的详情 |
 | `delta-cli science invoke --tool <tool_name> --endpoint <endpoint_name> [--data '{"key":"value"}'] [--params '{"key":"value"}']` | 调用工具端点 |
 | `delta-cli science endpoints list <tool_name>` | 列出指定工具的所有端点 |
+| `delta-cli science task submit --tool <tool> --operation <operation> --input '<json>' [--wait]` | 提交持久化 Science 任务 |
+| `delta-cli science task get/list/cancel/invocations/artifacts` | 查询、取消任务及读取调用/artifact 元数据 |
+| `delta-cli science file invoke --tool <tool> --endpoint <operation> --file <path>` | 调用受控文件/multipart operation |
+| `delta-cli science file download --tool <tool> --endpoint <operation> --params '<json>' --output <path>` | 下载原始 artifact 并计算 SHA-256 |
 
 `tools.name` 和 `tool_endpoints.name` 是 Science 工具调用的唯一权威名称。
 `science list` 与 `science endpoints list` 原样展示服务端数据库中的启用项，
 `science invoke` 原样传递 `--tool` 和 `--endpoint`，不执行别名映射或旧名称兼容。
 
+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`。
+
 ## 输出格式
 
 所有命令返回统一的 JSON envelope：
@@ -417,12 +427,12 @@ make release
 ```bash
 export GH_TOKEN=<your-github-pat>
 export NPM_TOKEN=<your-npm-token>
-./release.sh v1.1.0
+./release.sh v1.1.2
 ```
 
 脚本执行步骤：
 1. 更新 `package.json` 版本号。
-2. 使用 Docker + `make release` 交叉编译 5 个平台二进制文件。
+2. 交叉编译 5 个平台二进制文件（优先 Docker + `make release`，Docker 不可用时回退本地 Go 工具链）。
 3. 在 `bin/` 目录生成 `.tar.gz` / `.zip` 归档。
 4. 通过 `.ci/publish-github-release.js` 创建 GitHub Release 并上传资产。
 5. 同步 npm 脚本、README 与全部 Skills 到公开仓库 `yzailab/delta-infra-cli`。

package/checksums.txt

@@ -1,5 +1,5 @@
-a10f6e14567f6abf3c5fea000812972a1f3cfe12fa3f4c32bc5a2f6c9625a481  delta-cli-darwin-amd64.tar.gz
-48491c7a1e74c195f58864967fd187cc42757e4b3fce93b9e8c48349585a3b8c  delta-cli-darwin-arm64.tar.gz
-619ba18441f4f7210876318f985174e5da6b4b93446f7dac128396563cc41f69  delta-cli-linux-amd64.tar.gz
-1a74f4193f9bf639fedbb572ffcc9bb353a1b38915ad6087a38cbc336e87edac  delta-cli-linux-arm64.tar.gz
-07b66fda183467d79de9ecc4431f4e7fe8a1fd243ae86572df4e13c693d94d88  delta-cli-windows-amd64.zip
+c956888bdd5e88ce3599d3f4c19d6ca39384248abe22af000194e2f942d232b8  delta-cli-darwin-amd64.tar.gz
+69a31eba4c684a128345d2db6f9f5e92bd53350297ef4df94054e9174899b930  delta-cli-darwin-arm64.tar.gz
+0bc0b62a1c3920ab72a806f45fa978dfaa22ed606a93827b463a471720c88211  delta-cli-linux-amd64.tar.gz
+595fcfddf391719c2aabfd851dde6d0316f6a41e827268e914b069fa685e0f43  delta-cli-linux-arm64.tar.gz
+9e6b97c65a854cdceb57eebbc2f3c0e4485d602918f16e4990ef7e5a479fb3d8  delta-cli-windows-amd64.zip

package/package.json

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

package/skills/delta-sandbox/SKILL.md

@@ -140,10 +140,10 @@ required_outputs:
 | **发现** | |
 | 查看可用镜像（镜像名） | `sandbox images` |
 | 查看剩余可申请资源 | `sandbox resources` — 按算力分组返回 GPU/显存/核心可用量：`compute_sources[].source` 为 `private`（私有算力）或 `third_party`（第三方算力）；`gpu_types` 结构随分组不同（private 含 `vgpu`/`core`/`memory_mib`，third_party 含 `gpu_name`/`total_gpu_num`/`idle_gpu_num`）。算力后端为内部概念，自动选择，无需指定 |
-| 获取资源推荐 | `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` |
+| 获取资源推荐 | `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]`（`--memory`/`--gpu-mem` 支持 g/m/G/M 格式，如 `1G`/`512M`，CLI 自动转换为 Gi/Mi） |
 | 列出当前用户的 sandbox | `sandbox list [--status <running/finished/killed/error>] [--start-time <ISO8601>] [--end-time <ISO8601>] [--sandbox-id <id>] [--days N]` |
 | **生命周期** | |
-| 创建 sandbox | `sandbox create --image-name <镜像名> [--cpu N --memory XGi --gpu N --gpu-mem N --gpu-type <型号> --max-life M]`；`--image-name` 用镜像名（`sandbox images` 返回的 `image_name` 字段，如 `"PyTorch CUDA13 (GPU)"`），底层镜像标识对用户隐藏；`--gpu-type` 指定 GPU 型号（如 `"RTX 4090"`、`H100`），服务端映射为 HAMi use-gputype 注解按型号调度，可选型号查 `sandbox resources`（`third_party` 分组 `gpu_types[].gpu_name`），不传则自动调度；不希望被自动清理时加 `--no-auto-cleanup`（仅显式 kill/finish 可销毁）；**单沙箱资源上限** cpu ≤ 512 / memory ≤ 1024Gi / gpu ≤ 64 / gpuMem ≤ 1024Gi，超出快速报错不挂起 |
+| 创建 sandbox | `sandbox create --image-name <镜像名> [--cpu N --memory XGi --gpu N --gpu-mem N --gpu-type <型号> --max-life M]`；`--memory`/`--gpu-mem` 支持 g/m/G/M 格式（如 `1G`/`512M`，小写亦可），CLI 自动转换为服务端接受的 `Gi`/`Mi` 单位；`--image-name` 用镜像名（`sandbox images` 返回的 `image_name` 字段，如 `"PyTorch CUDA13 (GPU)"`），底层镜像标识对用户隐藏；`--gpu-type` 指定 GPU 型号（如 `"RTX 4090"`、`H100`），服务端映射为 HAMi use-gputype 注解按型号调度，可选型号查 `sandbox resources`（`third_party` 分组 `gpu_types[].gpu_name`），不传则自动调度；不希望被自动清理时加 `--no-auto-cleanup`（仅显式 kill/finish 可销毁）；**单沙箱资源上限** cpu ≤ 512 / memory ≤ 1024Gi / gpu ≤ 64 / gpuMem ≤ 1024Gi，超出快速报错不挂起 |
 | 连接 sandbox | `sandbox connect <id>` |
 | 查看状态 | `sandbox status <id>` |
 | 完成 sandbox | `sandbox finish <id> [--results '{...}']` |

package/skills/delta-sandbox/references/commands.md

@@ -9,13 +9,13 @@
 | `sandbox list [--status <running/finished/killed/error>] [--start-time <ISO8601>] [--end-time <ISO8601>] [--sandbox-id <id>] [--days N]` | 列出当前用户的 sandbox（与 `ls` 不同：这是列 **沙箱实例**）；支持按状态/时间/sandbox_id 过滤；时间范围优先级 start_time/end_time > days > 默认 7 天。**不再支持按算力后端（provider）过滤**——provider 为内部概念，自动选择 |
 | `sandbox resources` | 查看各算力分组的当前**剩余可申请**资源（GPU/显存/核心）；响应 `compute_sources[].source` 为 `private`（私有算力）或 `third_party`（第三方算力）；`gpu_types` 结构随分组不同——private 含 `vgpu`/`core`/`memory_mib` 的 `total/used/available`，third_party 含 `gpu_name`/`total_gpu_num`/`idle_gpu_num` |
 | `sandbox images` | 查看可用镜像列表（返回**镜像名**，底层镜像标识对用户隐藏）；连"原逻辑"旧服务端时返回内部镜像名（URI），该值直接传给 `--image-name` 也能成功创建；连新逻辑服务端返回净化后的展示名 |
-| `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` | 获取资源配置推荐 |
+| `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` | 获取资源配置推荐（`--memory`/`--gpu-mem` 支持 g/m/G/M 格式，如 `1G`/`512M`，CLI 自动转换为 Gi/Mi） |
 
 ## 生命周期
 
 | 命令 | 说明 |
 |------|------|
-| `sandbox create --image-name <镜像名> [--cpu N --memory XGi --gpu N --gpu-mem N --gpu-type <型号> --max-life M --no-auto-cleanup]` | 创建 sandbox 容器（`--image-name` 用镜像名，如 `"PyTorch CUDA13 (GPU)"`，底层镜像标识对用户隐藏；`--gpu-type` 指定 GPU 型号，如 `"RTX 4090"`、`H100`，服务端映射为 HAMi use-gputype 注解按型号调度，可选型号查 `sandbox resources`（`third_party` 分组 `gpu_types[].gpu_name`），不传则自动调度；`--no-auto-cleanup` 不被自动清理，仅显式 kill/finish 可销毁）；**响应回显请求的镜像名/resource**（服务端未返回字段用请求值补齐，服务端值优先）；算力后端为内部概念，自动选择，不再支持 `--provider`。**单沙箱资源上限**：`--cpu` ≤ 512、`--memory` ≤ 1024Gi、`--gpu` ≤ 64、`--gpu-mem` ≤ 1024Gi，超出会在请求阶段**快速返回校验错误**（不会挂起），正常任务远低于这些上限 |
+| `sandbox create --image-name <镜像名> [--cpu N --memory XGi --gpu N --gpu-mem N --gpu-type <型号> --max-life M --no-auto-cleanup]` | 创建 sandbox 容器（`--image-name` 用镜像名，如 `"PyTorch CUDA13 (GPU)"`，底层镜像标识对用户隐藏；`--gpu-type` 指定 GPU 型号，如 `"RTX 4090"`、`H100`，服务端映射为 HAMi use-gputype 注解按型号调度，可选型号查 `sandbox resources`（`third_party` 分组 `gpu_types[].gpu_name`），不传则自动调度；`--no-auto-cleanup` 不被自动清理，仅显式 kill/finish 可销毁）；`--memory`/`--gpu-mem` 支持 g/m/G/M 格式（如 `1G`/`512M`，小写亦可），CLI 自动转换为服务端接受的 `Gi`/`Mi` 单位；**响应回显请求的镜像名/resource**（服务端未返回字段用请求值补齐，服务端值优先）；算力后端为内部概念，自动选择，不再支持 `--provider`。**单沙箱资源上限**：`--cpu` ≤ 512、`--memory` ≤ 1024Gi、`--gpu` ≤ 64、`--gpu-mem` ≤ 1024Gi，超出会在请求阶段**快速返回校验错误**（不会挂起），正常任务远低于这些上限 |
 | `sandbox connect <id>` | 连接已有 sandbox |
 | `sandbox status <id>` | 查看 sandbox 状态（running / done） |
 | `sandbox finish <id> [--results '{...}']` | 保存结果后自动销毁 |

package/skills/delta-sandbox/references/lifecycle.md

@@ -6,7 +6,7 @@
 
 1. **查看可用镜像** `delta-cli sandbox images` — 查询服务端支持的镜像列表。镜像决定了容器内的语言运行时（Python / Node.js / Go / Java / Rust 等），根据用户的技术栈和 GPU/CPU 需求匹配。
 2. **列出现有 sandbox（可选）** `delta-cli sandbox list` — 查看当前用户已创建的活跃 sandbox，避免重复创建
-3. **创建** `delta-cli sandbox create --image-name <镜像名> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120 [--gpu-type <型号>]`（创建后立即可用，无需连接；--max-life 指定 sandbox 最大存活时间（分钟），默认 30。`--no-auto-cleanup` 可让 sandbox 不被自动清理，仅显式 kill/finish 可销毁。`--image-name` 用镜像名，如 `"PyTorch CUDA13 (GPU)"`；算力后端为内部概念，自动选择，无需指定。`--gpu-type`（可选）指定 GPU 型号，如 `"RTX 4090"`、`H100`，服务端映射为 HAMi use-gputype 注解按型号调度，可选型号查 `sandbox resources`（`third_party` 分组 `gpu_types[].gpu_name`），不传则自动调度。**单沙箱资源上限**：cpu ≤ 512、memory ≤ 1024Gi、gpu ≤ 64、gpuMem ≤ 1024Gi，超出会在请求阶段快速返回校验错误而非挂起。）
+3. **创建** `delta-cli sandbox create --image-name <镜像名> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120 [--gpu-type <型号>]`（创建后立即可用，无需连接；--memory/--gpu-mem 支持 g/m/G/M 格式（如 1G/512M，小写亦可），CLI 自动转换为 Gi/Mi；--max-life 指定 sandbox 最大存活时间（分钟），默认 30。`--no-auto-cleanup` 可让 sandbox 不被自动清理，仅显式 kill/finish 可销毁。`--image-name` 用镜像名，如 `"PyTorch CUDA13 (GPU)"`；算力后端为内部概念，自动选择，无需指定。`--gpu-type`（可选）指定 GPU 型号，如 `"RTX 4090"`、`H100`，服务端映射为 HAMi use-gputype 注解按型号调度，可选型号查 `sandbox resources`（`third_party` 分组 `gpu_types[].gpu_name`），不传则自动调度。**单沙箱资源上限**：cpu ≤ 512、memory ≤ 1024Gi、gpu ≤ 64、gpuMem ≤ 1024Gi，超出会在请求阶段快速返回校验错误而非挂起。）
 4. **写入代码/数据** `delta-cli sandbox write <id> --source <文件名>` — 将本地文件直接写入 sandbox，**不传 `--path` 默认写到该 sandbox 的 working-directory**（`/workspace/{user_id}/{sandbox_id}/<文件名>`，在 OSS 同步范围内，kill 后文件不会丢）。写前可用 `delta-cli sandbox working-directory <id>` 确认路径。**必须**使用相对源路径（如 `--source infer.py`），禁止使用 `"$WORKSPACE_ROOT/<filename>"` 或 `$(pwd)/...`。相对 `--path` 也会拼到 working-directory 下；仅绝对 `--path` 原样使用（`/workspace/<filename>` 根路径不在 OSS 同步范围，不推荐）。也可用 `--data "..."` 写入少量内联内容（需显式 `--path`），`--mode 755` 可设置文件权限。写入后返回的 `size` 字段是 stat 验证后的实际磁盘字节数，可确认写入完整。批量写入用 `write-multiple`。文件路径和扩展名由镜像中的运行时决定。
 5. **运行命令** — 先 `delta-cli sandbox working-directory <id>` 查询 `<wd>`，再根据镜像中的运行时构造命令，常见示例：`python <wd>/train.py`（Python）、`node <wd>/app.js`（Node.js）、`go run <wd>/main.go`（Go）、`bash <wd>/run.sh`（Shell）
    - **短任务 ≤60s**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，SSE 原始 `data:` 帧透传到 stdout（无末尾信封），`exit_code`/`log_file` 从 `complete` 帧读取，完整 stdout 写入 log_file

package/skills/delta-science/AGENTS.md

@@ -5,7 +5,7 @@
 
 ## OVERVIEW
 
-Single public `delta-science` skill: the company online-Science unified entrypoint. It is host-neutral and routed exclusively through `delta-cli science invoke -> Science Server`. Per-tool operation contracts live in `references/` and are loaded on demand; there are no separate planner-visible per-tool skills.
+Single public `delta-science` skill: the company online-Science unified entrypoint. It is host-neutral and routed exclusively through Delta CLI (`science invoke`, durable `science task`, or controlled `science file`) to the Science Server. Per-tool operation contracts live in `references/` and are loaded on demand; there are no separate planner-visible per-tool skills.
 
 ## STRUCTURE
 
@@ -24,12 +24,12 @@ delta-science/
 
 | Path | Content |
 |------|---------|
-| `SKILL.md` | Service boundary, 安全红线 (no curl/requests/httpx/browser direct gateway), invocation template, cross-tool handoff |
+| `SKILL.md` | Service boundary, 安全红线 (no curl/requests/httpx/browser direct gateway), invoke/task/file templates, cross-tool handoff |
 | `references/<tool>.md` | One real tool's authoritative operation, request-field, response and failure schema |
 
 ## CONVENTIONS
 
-- All science operations go through `delta-cli science invoke --tool T --endpoint E --data JSON`; no alternate routes
+- JSON endpoint operations go through `delta-cli science invoke`; durable jobs go through `delta-cli science task`; raw/multipart operations go through `delta-cli science file`; no direct HTTP alternate routes
 - Tool/endpoint names are exact contracts from the server DB — read the matching reference first; never invent fields/enums from memory
 - Success is reported only when subprocess exit is 0 AND top-level JSON `ok` is `true`; `data` holds the service response
 - `references/` contains only one real tool per file; routing, service maps, catalogs and workflows belong in `SKILL.md` or live CLI discovery, not here

package/skills/delta-science/SKILL.md

@@ -14,8 +14,9 @@ Skill；工具选择、operation、参数、跨工具交接和结果校验都在
 
 ## 服务调用边界
 
-- 所有在线 Science 操作最终都经
-  `delta-cli science invoke -> Science Server`。
+- 所有在线 Science 操作最终都经 Delta CLI：只读/JSON 兼容端点使用
+  `delta-cli science invoke`，需要持久化生命周期的调用使用
+  `delta-cli science task`，原始文件或 multipart 使用 `delta-cli science file`。
 - 使用 CLI 的标准认证与 `base_url` 派生出的 Science 服务地址（`{base_url}/science_tool`）。
   不得通过环境变量、命令参数或业务 URL 改写服务路由。
 - 禁止使用 `curl`、`requests`、`httpx`、浏览器和 PowerShell Web 命令直接访问公司网关或
@@ -31,19 +32,41 @@ Skill；工具选择、operation、参数、跨工具交接和结果校验都在
   CLI 顶层 `data` 保存服务响应；仅按对应 reference 说明的信封和业务结构读取字段，
   不得递归搜索看似合理的值，也不得把 `valid:false` 等业务结果误报为传输失败。
 
-调用模板：
+JSON 兼容端点调用模板：
 
 ```text
 delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
 ```
 
+持久化任务模板：
+
+```text
+delta-cli science task submit --tool TOOL --operation OPERATION \
+  --input JSON --idempotency-key STABLE_KEY [--wait --timeout SECONDS]
+delta-cli science task get TASK_ID
+delta-cli science task cancel TASK_ID
+delta-cli science task invocations TASK_ID
+delta-cli science task artifacts TASK_ID
+```
+
+文件型操作模板：
+
+```text
+delta-cli science file invoke --tool qe --endpoint artifact-upload \
+  --file structure.cif --data '{"name":"structure.cif","role":"structure"}'
+delta-cli science file invoke --tool materials-design --endpoint job-submit \
+  --file train.xlsx --candidate-file candidates.xlsx --data CONFIG_JSON
+delta-cli science file download --tool qe --endpoint artifact-content \
+  --params '{"artifact_id":"sha256:<digest>"}' --output result.bin
+```
+
 仅当 reference 明确将字段定义为查询参数时使用 `--params JSON`。不要将 JSON 拼接为命令
 代码；使用调用环境的安全参数传递机制传入单个 JSON 参数。
 
-Materials Design 的训练表 multipart 上传、QE 的原始 artifact 上传和要求自定义
-`Idempotency-Key` 的请求，只有在 Science Server 已提供明确的 JSON/query adapter 时才能
-通过本 CLI 使用。不要把本地路径、base64 或请求头伪装成普通 `--data` 字段；若目录没有
-这样的 adapter，按“未暴露、未发送远端请求”处理，不要直连 preflight Gateway。
+Materials Design 的训练表 multipart 上传、QE 的原始 artifact/custom PP 上传和
+`Idempotency-Key` 都已有受控 CLI adapter：文件必须通过 `science file` 的文件 flag 传递，
+幂等键必须通过 `science task submit --idempotency-key` 或 file operation 的专用 flag 传递。
+不要把本地路径、base64 或请求头伪装成普通 `--data` 字段，也不要直连 preflight Gateway。
 
 只调用完成目标所需的 operation。跨工具任务在同一个 Skill 执行中按依赖顺序调用，
 下游只能使用上一步已验证的业务字段。已知工具默认不要额外调用 health、schema、

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

@@ -22,12 +22,23 @@ Materials Design 用于从实验或计算材料表格中建立 surrogate、验
 | `/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 |
 
-所有实时调用都必须走：
+所有 JSON/query 调用都必须走：
 
 ```text
 delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
 ```
 
+训练表提交使用受控文件 adapter：
+
+```text
+delta-cli science file invoke --tool materials-design --endpoint job-submit \
+  --file train.xlsx --candidate-file candidates.xlsx --data CONFIG_JSON
+delta-cli science task submit --tool materials-design --operation job-status \
+  --input '{"job_id":"mdjob_..."}' --wait
+delta-cli science file download --tool materials-design --endpoint artifact-download \
+  --params '{"job_id":"mdjob_...","artifact_path":"report.html"}' --output report.html
+```
+
 只读 query operation 才使用 `--params JSON`。如果新工具尚未出现在目录中，或目录没有
 返回足够的请求 schema，停止并报告未暴露；不要猜测 endpoint 名、body 或兼容别名。
 
@@ -41,12 +52,10 @@ 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。
+`science invoke` 只接受 JSON object body 和 JSON query 参数，不能表达 multipart；因此不能
+把本地路径或 base64 伪装成文件字段。artifact 下载同样是原始 bytes，必须通过
+`science file download` 保存并校验，不能当作普通 JSON 结果。不得调用
+`materials-design-service:8900` 或直连 preflight Gateway。
 
 ## 输入与配置
 

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

@@ -31,18 +31,20 @@ delta-cli science endpoints list <exact tool name>
 再用目录返回的精确名称调用；如果 catalog 没有 schema，不猜测 operation、路径参数、
 请求头或 body。
 
-## 当前 CLI 的文件和请求头边界
+## 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；
+稳定的 `Idempotency-Key`。`science invoke` 仍只用于 JSON/query；文件通过
+`science file`，持久化 job 通过 `science task`：
+
+- `delta-cli science file invoke --tool qe --endpoint artifact-upload --file <path>` 上传
+  结构 artifact；`custom-pp-upload` 同理并在 `--data` 中提供 `custom_pp_id`；
+- `delta-cli science task submit --tool qe --operation job-submit --input JSON
+  --idempotency-key KEY` 提交 durable QE job，worker 将幂等键传给 Gateway；
+- `delta-cli science file download --tool qe --endpoint artifact-content --params JSON
+  --output <path>` 下载原始 artifact；
 - 不要把结构文本、文件路径、base64、`Idempotency-Key` 或 QE service credential 当成
-  普通业务字段发送；
-- 若目录没有 adapter，报告“当前 CLI 未暴露该 operation；未发送远端请求”，不要调用
-  公开/私有 Gateway URL 或 `qe-cloud-compute:18020`。
+  普通业务字段发送，也不要调用公开/私有 Gateway URL 或 `qe-cloud-compute:18020`。
 
 ## 新作业的正确顺序