delta-cli

Delta Agent Cloud 的命令行工具，用于管理 Delta Sandbox GPU/CPU 计算任务和调用 Science 工具。

安装

方式一：npx 一键安装（推荐）

npx @delta-infra/cli@latest install

该命令会依次完成：

1. 全局安装 @delta-infra/cli（含 Go 二进制）
2. 选择 AI 工具平台（可多选）：通用 Agent 目录 ~/.agents/skills/（Codex/Cursor/OpenCode）、Claude Code ~/.claude/skills/、OpenCode 原生 ~/.config/opencode/skills/、Cursor ~/.cursor/skills/、Memento-S 开发模式 ~/memento_s/skills/
3. 安装 AI Skills 到所选平台的 skills 目录
4. 初始化配置 自动写入默认服务端地址（无需人工填写 base_url）
5. 身份认证 delta-cli auth login（交互式，非 TTY 跳过）

AI Agent 也可以直接使用以下指令完成安装：

帮我安装 delta-cli：https://github.com/yzailab/delta-infra-cli

卸载

npx @delta-infra/cli@latest uninstall

清理全局包、所有已知平台的 AI Skills 和配置文件。

升级

# 升级 CLI + AI Skills
delta-cli upgrade

# 只检查是否有更新（不执行升级）
delta-cli upgrade --check

# 只升级 CLI 二进制
delta-cli upgrade --cli-only

# 只升级 AI Skills
delta-cli upgrade --skills-only

升级 CLI 时会通过 npm install -g @delta-infra/cli@latest 拉取最新版本；升级 Skills 时会通过 npx skills add 重新安装 AI Skills。

方式二：直接下载 Binary

从 GitHub Releases 下载对应平台的压缩包（以下使用 latest 指向最新版）：

# macOS (Apple Silicon)
curl -L -o delta-cli.tar.gz https://github.com/yzailab/delta-infra-cli/releases/latest/download/delta-cli-darwin-arm64.tar.gz
tar -xzf delta-cli.tar.gz
sudo mv delta-cli-darwin-arm64 /usr/local/bin/delta-cli
rm delta-cli.tar.gz

# Linux (AMD64)
curl -L -o delta-cli.tar.gz https://github.com/yzailab/delta-infra-cli/releases/latest/download/delta-cli-linux-amd64.tar.gz
tar -xzf delta-cli.tar.gz
chmod +x delta-cli-linux-amd64
sudo mv delta-cli-linux-amd64 /usr/local/bin/delta-cli
rm delta-cli.tar.gz

# Windows (AMD64，PowerShell)
Invoke-WebRequest -Uri https://github.com/yzailab/delta-infra-cli/releases/latest/download/delta-cli-windows-amd64.zip -OutFile delta-cli.zip
Expand-Archive -Path delta-cli.zip -DestinationPath . -Force
Move-Item -Path delta-cli-windows-amd64.exe -Destination delta-cli.exe
Remove-Item -Path delta-cli.zip
# 将 delta-cli.exe 放到 PATH 中的目录

方式三：一键安装脚本（国内用户推荐 / 无 npm 也可用）

安装脚本会自动检测环境：

• 已有 npm → 安装 @delta-infra/cli npm 包（自动尝试国内 npm 镜像 npmmirror，失败回退 npm 官方源）
• 没有 npm → 直接通过纯 shell 方式下载二进制（PowerShell + curl / bash + curl + tar，Windows 10+、macOS、Linux 均自带），无需安装 Node.js/npm

# Linux / macOS
curl -L https://raw.githubusercontent.com/yzailab/delta-infra-cli/main/install.sh | bash

# Windows (PowerShell)
Invoke-RestMethod -Uri https://raw.githubusercontent.com/yzailab/delta-infra-cli/main/install.ps1 | Invoke-Expression

脚本下载二进制时会按顺序尝试国内加速镜像（gh.ddlc.top、ghproxy.net、gh-proxy.com），全部失败再用 GitHub 源站，且会校验 SHA-256。可用 DELTA_CLI_VERSION 环境变量指定版本。

方式四：npm

npm install -g @delta-infra/cli

postinstall 会按以下顺序尝试下载当前平台的二进制：

1. DELTA_CLI_MIRROR 环境变量指定的镜像（如果设置，需为 HTTPS 且允许全前缀格式，如 https://gh.ddlc.top）
2. 探测国内加速镜像 gh.ddlc.top、ghproxy.net、gh-proxy.com（并行探测），可用的优先
3. GitHub 源站 https://github.com/yzailab/delta-infra-cli/releases/download/...（兜底）

如果安装时下载失败，可以：

• 直接运行一次 delta-cli，它会自动重新尝试下载。
• 或者在安装前设置本地压缩包路径：

DELTA_CLI_ARCHIVE=/path/to/delta-cli-linux-amd64.tar.gz npm install -g @delta-infra/cli

常用环境变量：

快速开始

1. 初始化配置

delta-cli config init

服务端地址无需人工填写：默认使用 https://delta-infra-nacos.yangtzeailab.com（已有配置则沿用其中的 base_url），仅交互式提示 Bearer Token（可选，也可后续用 auth login 配置）。

如需指向自建服务器，可通过 flag 或环境变量一次性指定：

# 通过 flag
delta-cli config init \
  --base-url http://your-server/api/v1 \
  --token your-token

# 通过环境变量（API Key 或 Token 二选一）
export DELTA_INFRA_BASE_URL=http://your-server/api/v1
export DELTA_INFRA_API_KEY=your-api-key        # 或 DELTA_INFRA_TOKEN
delta-cli config init

配置文件保存在 ~/.delta-infra/config.json（权限 0600）。

2. 认证

支持 API Key 与 Bearer Token 两种凭据（API Key 优先）。

获取 API Key：登录 Delta Agent Cloud Web 控制台，在 API Keys 页面生成一个 Key。

# API Key（推荐）
delta-cli auth login --apikey <your-api-key>

# Token
delta-cli auth login --token <your-token>

# 交互式登录（可直接粘贴 Key/Token，CLI 会自动识别格式）
delta-cli auth login

# 查看认证状态
delta-cli auth status

也可以通过环境变量指定：DELTA_INFRA_API_KEY=<key> / DELTA_INFRA_TOKEN=<token>。

3. Sandbox 生命周期

# 创建带 GPU 的 sandbox（--max-life 默认 30 分钟，长任务请调高）
# ⚠️ 生命周期计时（详见 skills/delta-sandbox/references/lifecycle.md）：
#   - 私有算力：平台从 create 请求被接受时开始计时，镜像拉取/就绪
#     时间也计入 max-life；到期由平台回收。
#   - 第三方算力：从沙箱就绪（本地记录 started_at）开始计时，
#     由服务端 cleanup 在 max-life + 最多 10 分钟宽限后回收。
#   - 自动回收（含平台提前回收）不会做 OSS 写回；需要保留产物请提前 pull 或
#     显式 `sandbox finish`。`sandbox status` 会返回 expires_at / reclaim_source /
#     termination_reason，沙箱结束后仍可查询。
# ⚠️ 资源语义：`--memory` 是容器 CPU 内存【总量】（每沙箱一份）；`--gpu-mem` 是【每张卡】的显存（MiB）——
# `--gpu 2 --gpu-mem 8000` = 每卡 8000MiB、总显存 16000MiB（私有算力直接按每卡注解调度；
# 注意第三方算力后端将 --gpu-mem 视为总显存÷卡数）。单卡显存上限可查 `sandbox resources`（私有算力分组的 `memory_mib`）。
# 注意：服务端已移除 shmSize / devices 资源字段，CLI 的 --shm-size / --devices 已被移除。
# `--ready-timeout` 是**创建阶段**等待沙箱就绪的上限（秒，默认 600，范围 10-1800）：冷节点首次拉取大镜像
# （如 2.9GB 层）常超过 60s，提高它可避免 error_code=SandboxReadyTimeout。对全部算力生效（私有算力 /
# 第三方算力）。注意它与 `--max-life`（创建成功后的存活时长）是两回事。
delta-cli sandbox create \
  --image-name "PyTorch CUDA13 (GPU)" \
  --cpu 4 --memory 16Gi --gpu 1 \
  --max-life 120


# 需要长期存活、不被自动清理的 sandbox：加 --no-auto-cleanup
# （同时关闭平台 TTL 与服务端 cleanup，仅显式 kill/finish 可销毁）
delta-cli sandbox create \
  --image-name "PyTorch CUDA13 (GPU)" \
  --cpu 4 --memory 16Gi --gpu 1 \
  --no-auto-cleanup

# 运行命令（短任务同步执行，长任务用 run-bg 替代 run）
delta-cli sandbox run <sandbox_id> \
  --command "<命令>" \
  --timeout 3600

# v1.0.85+ sandbox run 默认走 SSE 实时流：stdout 为原始 data: 帧（无末尾信封），
# exit_code / log_file / stdout_tail / duration_seconds 在 complete 帧中
delta-cli sandbox run <sandbox_id> --command "echo '{\"status\":\"ok\",\"result\":\"done\"}'" --timeout 60

# 自动化/编排推荐：--format json（等价 --json-result）只输出一个 JSON 信封，
# data 含 execution_id / finished / exit_code / stdout_tail / stderr_tail /
# stdout_size / stderr_size / log_file / duration_seconds / result_summary。
# 字段名与 complete 帧一致；失败时仍是单个对象：
# {"ok":false,"error":{...},"data":{...}}，进程退出码非零。
delta-cli sandbox run <sandbox_id> --command "python run.py" --timeout 600 --format json

# 后台任务 + 等待 + 统一结果
delta-cli sandbox run-bg <sandbox_id> --command "python train.py" --timeout 3600 --wait --format json

# 读取结果文件
delta-cli sandbox read <sandbox_id> --path /workspace/result.json

# 销毁 sandbox（销毁在服务端继续执行，响应带 request_id）
delta-cli sandbox kill <sandbox_id>

# 创建重试幂等 + 事后对账
delta-cli sandbox create --image-name <镜像名> --idempotency-key retry-001
delta-cli sandbox operation <request_id>

命令列表

全局命令

Sandbox 命令

提示：sandbox list（列沙箱实例）与 sandbox ls <id>（列目录）不同，注意区分。

沙箱内路径：指向沙箱内部的路径（--path、write-multiple --entry 的远端部分、upload --target、pull --source、run/run-bg --log-file）若为相对路径，会自动拼到沙箱工作目录（sandbox working-directory <id> 可查），绝对路径原样使用；指向本地机器的路径（write --source、upload --source、pull --target、read --output）不做任何改写。

Science 工具

Science Server 由 base_url 派生（{base_url}/science_tool），无需单独配置 science_base_url；Sandbox API 同样由 base_url 派生（{base_url}/sandbox/api/v1）。

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。 云端 XRD 的相识别、artifact、CIF 模拟和精修契约见 skills/delta-science/references/xrd.md。

输出格式

所有命令返回统一的 JSON envelope：

// 成功
{"ok":true,"data":{"id":"sb-xxx","status":"running"}}

// 错误
{"ok":false,"error":{"type":"auth","message":"not authenticated","hint":"run 'delta-cli auth login'","request_id":"create_a1b2c3"}}

error.hint 给出可执行的下一步（创建失败时会说明具体原因，例如「镜像未在目标节点缓存，重试或换一个已缓存该镜像的 GPU 型号」），error.request_id 用于在服务端日志中定位同一次失败。对于新服务端，创建失败时 error.details 还会携带结构化诊断（diagnostics_version/stage/retryable/suggested_actions，以及嵌套的 details，如 suggested_gpu_types、provider_label）；当客户端没有对应错误码的提示表时，会优先采用服务端下发的 hint。

错误类型及退出码：

AI Agent Skills

delta-cli 内置 AI Agent 操作手册（Skills），帮助 Claude Code 等 AI 助手正确使用 CLI：

# 安装仓库中的全部 Skills
npx skills add delta-infra/delta-infra-cli -y -g

# 只安装统一 Science Skill
npx skills add delta-infra/delta-infra-cli -s delta-science

Skill 文件位于 skills/ 目录：

• delta-shared/ — 全局通用规则（认证、配置、错误处理）
• delta-sandbox/ — Sandbox 操作指南（生命周期、命令路由）
• delta-science/ — 唯一 Science 入口，包含统一 Delta CLI wrapper、跨工具工作流和 PubChem、RDKit、pymatgen、XRD、GSAS-II、QE、LAMMPS、Delta-BO、LDM-BO、SynBO、 AntBO、materials-design、strbo 以及蛋白质/生物信息（huada_protein_tools）的按需 reference；蛋白质类 endpoint 契约位于 skills/delta-science/references/protein/

Memento 等宿主只需要选择 delta-science。Skill 根据自然语言科研目标选择 tool 和 operation，并且只加载当前工具对应的 reference，避免大量独立 Skill 给规划器增加 负担。升级时会自动移除旧版独立 Science Skill。

添加 Science tool 或 operation

工具目录由 Science Server 数据库维护。新增工具时配置 tools 记录及对应的 tool_endpoints 记录；停用时设置 status=false。CLI 无需同步任何静态表或重新增加 命令。若需要让 AI 根据自然语言自动选择新工具并安全组装请求，再更新 skills/delta-science/SKILL.md 的工具选择表和对应的 skills/delta-science/references/<tool>.md；references 目录只保存真实工具文档，不能放置 目录、路由、服务映射或跨工具工作流等元文档。数据库中的 canonical tool name 与工具表、 对应 reference 必须完全一致。

开发

# 本地构建
make build

# 运行测试
make test

# 代码检查
make lint

# 跨平台编译（生成各平台二进制文件到 bin/）
make release

# 源码安装到系统 PATH（默认 /usr/local/bin；macOS / Linux）
make install

# 自定义安装前缀
make PREFIX=$HOME/.local install

# Windows 源码安装（二选一）
# 方式 A：在仓库根目录用 go install 安装到 GOPATH/bin
go install ./cmd/delta-cli

# 方式 B：在仓库根目录运行 PowerShell 脚本，构建并添加到用户 PATH
# .\install-from-source.ps1
# .\install-from-source.ps1 -InstallDir "$env:USERPROFILE\bin"

日常开发流程

修改 skills/ 或编译 delta-cli 后，需要同步到 Memento-S 项目才能生效：

# 1. 通过安装向导同步完整 Skill 集合
node scripts/install-wizard.js

# 2. 用 Docker 编译 Windows 版本（本地无 Go toolchain 时）
docker run --rm -v "$(pwd):/src" -w /src \
  -e GOPROXY=https://goproxy.cn,direct \
  golang:1.23 \
  sh -c 'go build -buildvcs=false \
    -ldflags "-X github.com/delta-infra/delta-infra-cli/internal/build.Version=$(git describe --tags --always --dirty 2>/dev/null || echo dev)" \
    -o bin/delta-cli-windows-amd64.exe ./cmd/delta-cli'

# 3. 将 delta-cli 放到 Memento-S 的 node_modules/.bin（替换旧版本）
cp bin/delta-cli-windows-amd64.exe \
   <memento-s>/electron_rebuild/node_modules/.bin/delta-cli

# 4. 重启 Memento-S sidecar 使新 binary 生效
#   在 Electron 界面中重新加载，或手动重启 sidecar 进程

注意：delta-cli 替换后，如果 ~/.delta-infra/config.json 中已配置 token，则 Sandbox 和 Science Skills 可直接使用；否则需要先用 auth login 配置。

构建与发布

本地构建

# 本地构建
make build

# 运行测试
make test

# 代码检查
make lint

# 跨平台编译（生成各平台二进制文件到 bin/）
make release

make release 仅生成各平台二进制文件（如 bin/delta-cli-linux-amd64），不会自动打包。打包与发布请使用下文的 release.sh。

一键发布（维护者）

项目根目录下的 release.sh 脚本负责完整发布流程：

export GH_TOKEN=<your-github-pat>
export NPM_TOKEN=<your-npm-token>
./release.sh <version>

脚本执行步骤：

1. 更新 package.json 版本号并交叉编译 5 个平台二进制文件（优先 Docker + make release，Docker 不可用时回退本地 Go 工具链）。
2. 在 bin/ 目录生成 .tar.gz / .zip 归档及 SHA-256 checksums，并更新仓库根目录的 checksums.txt。
3. 运行公开同步计划器测试（.ci/sync-public-github.test.js）。
4. 提交 source commit 并打 tag（chore: release vX.Y.Z），推送 GitLab main 与 tag（PUSH_SOURCE 默认为 1，非 1 会直接中止；公开同步依赖这一步）。
5. 同步 allowlist 公开文件树与 tag 到公开仓库 yzailab/delta-infra-cli。
6. 通过 .ci/publish-github-release.js 创建 GitHub Release 并上传二进制归档及 checksums。
7. 执行 npm publish --access public 发布 @delta-infra/cli。

需要提前安装 gh CLI、Node.js/npm，并配置 GH_TOKEN 与 NPM_TOKEN。CI 流程可参考 .gitlab-ci.yml。

npm 镜像

如果 GitHub 下载较慢，安装 npm 包时可设置镜像：

DELTA_CLI_MIRROR="https://gh-proxy.com" npm install -g @delta-infra/cli

沙箱内镜像源自动配置

创建沙箱时，服务端会自动检测部署所在网络区域（中国大陆 / 海外），并在区域为中国大陆时把镜像配置注入到容器里。用户无需任何手动配置，进去即可用。

• 中国大陆（domestic）：服务端自动注入镜像配置，pip install / npm install / git clone / HuggingFace 下载会走国内镜像。
• 海外（overseas）：不注入镜像，使用各包管理器官方源。
• 服务端通过探测 pypi.org / npmjs.org 的连通性来判断区域（带缓存、探测失败时按海外兜底，即 fail-open）。

覆盖的 4 类配置：

第三方算力（海外平台）默认关闭镜像注入，仅当运维明确配置开启后才生效。

注意区分两套镜像机制：本沙箱镜像配置针对的是沙箱里的包管理器（pip / npm / git / HF）。它与 CLI 自身的下载镜像 DELTA_CLI_MIRROR 是两回事——DELTA_CLI_MIRROR 只用于安装 delta-cli 二进制，不作用于沙箱内。

技术栈

• 语言: Go 1.23+
• CLI 框架: Cobra
• 配置: JSON 文件（~/.delta-infra/config.json，权限 0600）
• 输出: JSON envelope（AI-agent 友好，可脚本化）
• 发布: GitHub Release（tar.gz/zip） + npm wrapper
• 架构: 扁平静态命令树，Factory 依赖注入，惰性初始化

License

MIT