@delta-infra/cli 1.1.14 → 1.1.15

package/README.md

@@ -1,493 +1,493 @@
-# delta-cli
-
-Delta Agent Cloud 的命令行工具，用于管理 Delta Sandbox GPU/CPU 计算任务和调用 Science 工具。
-
-## 安装
-
-### 方式一：npx 一键安装（推荐）
-
-```bash
-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. **初始化配置** `delta-cli config init`（交互式，非 TTY 跳过）
-5. **身份认证** `delta-cli auth login`（交互式，非 TTY 跳过）
-
-AI Agent 也可以直接使用以下指令完成安装：
-
-> 帮我安装 delta-cli：https://github.com/yzailab/delta-infra-cli
-
-### 卸载
-
-```bash
-npx @delta-infra/cli@latest uninstall
-```
-
-清理全局包、所有已知平台的 AI Skills 和配置文件。
-
-### 升级
-
-```bash
-# 升级 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](https://github.com/yzailab/delta-infra-cli/releases) 下载对应平台的压缩包（以下使用 `latest` 指向最新版）：
-
-```bash
-# 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**
-
-```bash
-# 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
-
-```bash
-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`，它会自动重新尝试下载。
-- 或者在安装前设置本地压缩包路径：
-
-```bash
-DELTA_CLI_ARCHIVE=/path/to/delta-cli-linux-amd64.tar.gz npm install -g @delta-infra/cli
-```
-
-常用环境变量：
-
-| 变量 | 说明 |
-|------|------|
-| `DELTA_CLI_MIRROR` | 下载镜像根地址，例如 `https://gh.ddlc.top`。脚本会自动补全为全前缀格式（`<mirror>/https://github.com/...`）。只接受 HTTPS 且需在白名单内。 |
-| `DELTA_CLI_MIRROR_ALLOWLIST` | 额外允许的主机列表，逗号分隔。 |
-| `DELTA_CLI_ARCHIVE` | 指向预先下载好的 `.tar.gz` / `.zip` 本地路径，跳过网络下载。 |
-| `DELTA_CLI_SKIP_POSTINSTALL` | 设置为 `1` 跳过安装时的二进制下载，之后由 `delta-cli` 运行时兜底。 |
-| `DELTA_CLI_FATAL_ON_ERROR` | 安装失败时退出码非 0（默认警告，用于调试）。 |
-| `DELTA_CLI_DOWNLOAD_TIMEOUT` | 单个下载源最大等待时间（毫秒，默认 120000）。 |
-
-### 方式五：Go Install
-
-```bash
-go install github.com/delta-infra/delta-infra-cli/cmd/delta-cli@latest
-```
-
-## 快速开始
-
-### 1. 初始化配置
-
-```bash
-delta-cli config init
-```
-
-执行时会交互式提示输入服务端地址（默认：`https://delta-infra-nacos.yangtzeailab.com`）以及 Bearer Token（可选，也可后续用 `auth login` 配置）。
-
-非交互式环境（如 CI）会直接使用默认值，也可以通过 flag 或环境变量一次性指定：
-
-```bash
-# 通过 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。
-
-```bash
-# 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 生命周期
-
-```bash
-# 创建带 GPU 的 sandbox（--max-life 默认 30 分钟，长任务请调高）
-# ⚠️ 资源语义：`--memory` 是容器 CPU 内存【总量】（每沙箱一份）；`--gpu-mem` 是【每张卡】的显存（MiB）——
-# `--gpu 2 --gpu-mem 8000` = 每卡 8000MiB、总显存 16000MiB（内部 OpenSandbox/HAMi 后端直接写入 HAMi 每卡注解；
-# 注意云端 runpod 后端将 --gpu-mem 视为总显存÷卡数）。单卡显存上限可查 `sandbox resources`（memory_mib）。
-delta-cli sandbox create \
-  --image image.yangtzeailab.com/opensandbox/pytorch-cuda13:latest \
-  --cpu 4 --memory 16Gi --gpu 1 \
-  --max-life 120
-
-# 需要长期存活、不被自动清理的 sandbox：加 --no-auto-cleanup（仅显式 kill/finish 可销毁）
-delta-cli sandbox create \
-  --image image.yangtzeailab.com/opensandbox/pytorch-cuda13:latest \
-  --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 在 complete 帧中
-# 需要 stdout 末尾 JSON 摘要时：读取 log_file 解析（sandbox read <id> --path <log_file>）
-delta-cli sandbox run <sandbox_id> --command "echo '{\"status\":\"ok\",\"result\":\"done\"}'" --timeout 60
-
-# 读取结果文件
-delta-cli sandbox read <sandbox_id> --path /workspace/result.json
-
-# 销毁 sandbox
-delta-cli sandbox kill <sandbox_id>
-```
-
-## 命令列表
-
-### 全局命令
-
-| 命令 | 说明 |
-|------|------|
-| `delta-cli config init` | 初始化配置文件 |
-| `delta-cli config show` | 查看当前配置（敏感字段已脱敏） |
-| `delta-cli config set <key> <value>` | 修改配置项 |
-| `delta-cli config remove <key>` | 移除配置项（支持 `token`、`apikey`） |
-| `delta-cli auth login` | 交互式登录（自动识别 API Key / Token） |
-| `delta-cli auth login --apikey <key>` | API Key 认证（推荐） |
-| `delta-cli auth login --token <token>` | Token 认证 |
-| `delta-cli auth status` | 查看认证状态 |
-| `delta-cli upgrade` | 升级 CLI 和 AI Skills 到最新版本 |
-| `delta-cli upgrade --check` | 检查是否有可用更新 |
-| `delta-cli upgrade --cli-only` | 只升级 CLI 二进制 |
-| `delta-cli upgrade --skills-only` | 只升级 AI Skills |
-| `delta-cli usage` | 查看当前用户用量和剩余额度 |
-| `delta-cli --version` | 显示版本 |
-
-### Sandbox 命令
-
-> **提示**：`sandbox list`（列沙箱实例）与 `sandbox ls <id>`（列目录）不同，注意区分。
-
-| 命令 | 说明 |
-|------|------|
-| `delta-cli sandbox list` | 列出当前用户的 sandbox 实例 |
-| `delta-cli sandbox providers` | 查看可用计算后端 |
-| `delta-cli sandbox resources [--provider opensandbox\|autodl]` | 查看各后端当前剩余可申请资源（GPU/显存/核心） |
-| `delta-cli sandbox images` | 查看可用镜像列表（每条含 `image_name`/`tags`/`description`/`supports_shared_workspace`；`supports_shared_workspace=true` 表示该算力可开共享工作区（opensandbox/autodl），可与 `--shared-workspace` 搭配；实际播种/写回由平台创建时探测镜像内 rclone 决定） |
-| `delta-cli sandbox recommend --cpu N --memory XGi` | 获取资源配置推荐 |
-| `delta-cli sandbox create --image <img> [--no-auto-cleanup] [--shared-workspace=true\|false]` | 创建 sandbox 容器（`--no-auto-cleanup` 不被自动清理；`--shared-workspace` 默认 true：启用共享工作区（播种/写回由平台创建时探测镜像内 rclone 决定，镜像无 rclone 时跳过、数据不跨沙箱持久）；false 跳过播种/写回，适合快速任务） |
-| `delta-cli sandbox extend <id> --max-life N` | **动态延长运行中** sandbox 的 max-life（可增可减，N 需大于已存活分钟且 ≤10080；提前回收用 `kill`/`finish`）；不带 `--max-life` 时查询当前生命周期（已存活/剩余/到期时间）；`status` 输出含 `data.lifecycle` 生命周期摘要（已存活/剩余/到期；生命周期接口不可用时省略） |
-| `delta-cli sandbox connect <id>` | 连接 sandbox |
-| `delta-cli sandbox status <id>` | 查看 sandbox 状态 |
-| `delta-cli sandbox finish <id>` | 保存结果并销毁 |
-| `delta-cli sandbox kill <id>` | 销毁 sandbox |
-| `delta-cli sandbox run <id> --command "..." [--timeout <秒>] [--summary/--no-summary] [--artifacts]` | 同步运行命令（SSE 原始 `data:` 帧透传到 stdout，无末尾信封，`exit_code`/`log_file` 在 `complete` 帧）；`--summary`/`--artifacts` 仅旧服务器回退路径生效 |
-| `delta-cli sandbox run-bg <id> --command "..." [--timeout <秒>] [--wait] [--summary/--no-summary] [--artifacts]` | 后台运行命令；不加 `--wait` 立即返回 `{execution_id, sandbox_id}`；加 `--wait` 通过 SSE 实时流跟随（原始 `data:` 帧透传到 stdout，无末尾信封） |
-| `delta-cli sandbox logs <id> --execution-id <eid> [--tail N --grep <pattern> --context N --max-bytes N]` | 查看后台日志；默认返回 `stderr_size + stderr_tail`（避免上下文爆炸）；可用 `--tail/--grep` 过滤 |
-| `delta-cli sandbox cancel <id> --execution-id <eid>` | 中断后台命令 |
-| `delta-cli sandbox read <id> --path <path> [--output <本地路径>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | 读取容器内文件；`--output <path>` 保存到本地；`--tail/--grep` 过滤；非 UTF-8 文件 CLI 自动走 base64 fallback |
-| `delta-cli sandbox pull <id> --source <沙箱路径> --target <本地路径> [--recursive] [--pattern <glob>]` | 从沙箱拉取文件/目录到本地（mirror of `upload`，flag 方向相反：source=远程，target=本地）；单文件或递归目录；CLI 端 + 服务端双向 sha1 完整性校验 |
-| `delta-cli sandbox write <id> --path <path> --source <本地路径>` | 写入文件 |
-| `delta-cli sandbox write-multiple <id> --entry <远程路径>=<本地路径>` | 批量写入 |
-| `delta-cli sandbox ls <id> --path <path>` | 列出目录 |
-| `delta-cli sandbox stat <id> --path <path>` | 文件元数据 |
-| `delta-cli sandbox mv <id> --entry <src=dest>` | 移动/重命名 |
-| `delta-cli sandbox replace <id> --path <path> --old <文本> --new <文本>` | 替换内容 |
-| `delta-cli sandbox chmod <id> --path <path> --mode <八进制>` | 修改权限 |
-| `delta-cli sandbox rm <id> --path <path>` | 删除文件 |
-| `delta-cli sandbox rmdir <id> --path <路径>` | 递归删除目录 |
-| `delta-cli sandbox mkdir <id> --path <路径>` | 创建目录 |
-| `delta-cli sandbox search <id> --path <根目录> --pattern <glob>` | 搜索文件 |
-| `delta-cli sandbox working-directory <id>` | 获取沙箱工作目录路径 |
-| `delta-cli sandbox upload <id> --source <本地目录> --target <沙箱路径>` | 上传目录（tar.gz + 自动解压） |
-| `delta-cli sandbox expose <id> [--port N]` | 将沙箱内服务端口暴露到公网（frp 隧道），默认端口 8700 |
-| `delta-cli sandbox exposes <id>` | 列出沙箱当前活跃的公网端口隧道 |
-| `delta-cli sandbox dispose <id> --port N` | 回收公网端口隧道（需指定端口号） |
-
-### Science 工具
-
-> Science Server 由 `base_url` 派生（`{base_url}/science_tool`），无需单独配置
-> `science_base_url`；Sandbox API 同样由 `base_url` 派生（`{base_url}/sandbox/api/v1`）。
-
-| 命令 | 说明 |
-|------|------|
-| `delta-cli science list` | 列出所有已启用的 science 工具 |
-| `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：
-
-```json
-// 成功
-{"ok":true,"data":{"id":"sb-xxx","status":"running"}}
-
-// 错误
-{"ok":false,"error":{"type":"auth","message":"not authenticated","hint":"run 'delta-cli auth login'"}}
-```
-
-错误类型及退出码：
-
-| Type | Exit Code | 场景 |
-|------|-----------|------|
-| validation | 2 | 参数错误 |
-| auth | 3 | 未认证 |
-| permission | 4 | 权限不足 |
-| not_found | 5 | 资源不存在 |
-| network | 6 | 网络错误 |
-| api | 7 | 服务端错误 |
-| internal | 10 | 客户端内部错误 |
-
-## AI Agent Skills
-
-delta-cli 内置 AI Agent 操作手册（Skills），帮助 Claude Code 等 AI 助手正确使用 CLI：
-
-```bash
-# 安装仓库中的全部 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、GSAS-II、LAMMPS、Delta-BO、LDM-BO、SynBO、AntBO
-  的按需 reference
-
-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 必须完全一致。
-
-## 开发
-
-```bash
-# 本地构建
-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 github.com/delta-infra/delta-infra-cli/cmd/delta-cli@latest
-
-# 方式 B：在仓库根目录运行 PowerShell 脚本，构建并添加到用户 PATH
-# .\install-from-source.ps1
-# .\install-from-source.ps1 -InstallDir "$env:USERPROFILE\bin"
-```
-
-### 日常开发流程
-
-修改 `skills/` 或编译 `delta-cli` 后，需要同步到 Memento-S 项目才能生效：
-
-```bash
-# 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` 配置。
-
-## 构建与发布
-
-### 本地构建
-
-```bash
-# 本地构建
-make build
-
-# 运行测试
-make test
-
-# 代码检查
-make lint
-
-# 跨平台编译（生成各平台二进制文件到 bin/）
-make release
-```
-
-> `make release` 仅生成各平台二进制文件（如 `bin/delta-cli-linux-amd64`），不会自动打包。打包与发布请使用下文的 `release.sh`。
-
-### 一键发布（维护者）
-
-项目根目录下的 `release.sh` 脚本负责完整发布流程：
-
-```bash
-export GH_TOKEN=<your-github-pat>
-export NPM_TOKEN=<your-npm-token>
-./release.sh v1.1.2
-```
-
-脚本执行步骤：
-1. 更新 `package.json` 版本号。
-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`。
-6. 执行 `npm publish --access public` 发布 `@delta-infra/cli`。
-
-需要提前安装 `gh` CLI、Node.js/npm，并配置 `GH_TOKEN` 与 `NPM_TOKEN`。CI 流程可参考 `.gitlab-ci.yml`。
-
-### npm 镜像
-
-如果 GitHub 下载较慢，安装 npm 包时可设置镜像：
-
-```bash
-DELTA_CLI_MIRROR="https://gh-proxy.com/https://github.com" npm install -g @delta-infra/cli
-```
-
-## 沙箱内镜像源自动配置
-
-创建沙箱时，服务端会**自动检测部署所在网络区域**（中国大陆 / 海外），并在区域为中国大陆时把镜像配置注入到容器里。用户无需任何手动配置，进去即可用。
-
-- **中国大陆（domestic）**：服务端自动注入镜像配置，`pip install` / `npm install` / `git clone` / HuggingFace 下载会走国内镜像。
-- **海外（overseas）**：不注入镜像，使用各包管理器官方源。
-- 服务端通过探测 `pypi.org` / `npmjs.org` 的连通性来判断区域（带缓存、探测失败时按海外兜底，即 fail-open）。
-
-覆盖的 4 类配置：
-
-| 类型 | 说明 | 示例 |
-|------|------|------|
-| pip index-url | Python 包索引 | `https://pypi.tuna.tsinghua.edu.cn/simple` |
-| npm registry | Node 包源 | `https://registry.npmmirror.com` |
-| HF_ENDPOINT | HuggingFace 下载域名 | `https://hf-mirror.com` |
-| git insteadOf | GitHub 克隆代理 | `https://gh-proxy.com/https://github.com` |
-
-AutoDL 计算后端默认关闭镜像注入（海外平台），仅当运维明确配置开启后才生效。
-
-> **注意区分两套镜像机制**：本沙箱镜像配置针对的是**沙箱里的包管理器**（pip / npm / git / HF）。它与 CLI 自身的下载镜像 `DELTA_CLI_MIRROR` 是两回事——`DELTA_CLI_MIRROR` 只用于**安装 delta-cli 二进制**，不作用于沙箱内。
-
-## 技术栈
-
-- **语言**: Go 1.23+
-- **CLI 框架**: [Cobra](https://github.com/spf13/cobra)
-- **配置**: JSON 文件（`~/.delta-infra/config.json`，权限 0600）
-- **输出**: JSON envelope（AI-agent 友好，可脚本化）
-- **发布**: GitHub Release（tar.gz/zip） + npm wrapper
-- **架构**: 扁平静态命令树，Factory 依赖注入，惰性初始化
-
-## License
-
-MIT
+# delta-cli
+
+Delta Agent Cloud 的命令行工具，用于管理 Delta Sandbox GPU/CPU 计算任务和调用 Science 工具。
+
+## 安装
+
+### 方式一：npx 一键安装（推荐）
+
+```bash
+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. **初始化配置** `delta-cli config init`（交互式，非 TTY 跳过）
+5. **身份认证** `delta-cli auth login`（交互式，非 TTY 跳过）
+
+AI Agent 也可以直接使用以下指令完成安装：
+
+> 帮我安装 delta-cli：https://github.com/yzailab/delta-infra-cli
+
+### 卸载
+
+```bash
+npx @delta-infra/cli@latest uninstall
+```
+
+清理全局包、所有已知平台的 AI Skills 和配置文件。
+
+### 升级
+
+```bash
+# 升级 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](https://github.com/yzailab/delta-infra-cli/releases) 下载对应平台的压缩包（以下使用 `latest` 指向最新版）：
+
+```bash
+# 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**
+
+```bash
+# 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
+
+```bash
+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`，它会自动重新尝试下载。
+- 或者在安装前设置本地压缩包路径：
+
+```bash
+DELTA_CLI_ARCHIVE=/path/to/delta-cli-linux-amd64.tar.gz npm install -g @delta-infra/cli
+```
+
+常用环境变量：
+
+| 变量 | 说明 |
+|------|------|
+| `DELTA_CLI_MIRROR` | 下载镜像根地址，例如 `https://gh.ddlc.top`。脚本会自动补全为全前缀格式（`<mirror>/https://github.com/...`）。只接受 HTTPS 且需在白名单内。 |
+| `DELTA_CLI_MIRROR_ALLOWLIST` | 额外允许的主机列表，逗号分隔。 |
+| `DELTA_CLI_ARCHIVE` | 指向预先下载好的 `.tar.gz` / `.zip` 本地路径，跳过网络下载。 |
+| `DELTA_CLI_SKIP_POSTINSTALL` | 设置为 `1` 跳过安装时的二进制下载，之后由 `delta-cli` 运行时兜底。 |
+| `DELTA_CLI_FATAL_ON_ERROR` | 安装失败时退出码非 0（默认警告，用于调试）。 |
+| `DELTA_CLI_DOWNLOAD_TIMEOUT` | 单个下载源最大等待时间（毫秒，默认 120000）。 |
+
+### 方式五：Go Install
+
+```bash
+go install github.com/delta-infra/delta-infra-cli/cmd/delta-cli@latest
+```
+
+## 快速开始
+
+### 1. 初始化配置
+
+```bash
+delta-cli config init
+```
+
+执行时会交互式提示输入服务端地址（默认：`https://delta-infra-nacos.yangtzeailab.com`）以及 Bearer Token（可选，也可后续用 `auth login` 配置）。
+
+非交互式环境（如 CI）会直接使用默认值，也可以通过 flag 或环境变量一次性指定：
+
+```bash
+# 通过 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。
+
+```bash
+# 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 生命周期
+
+```bash
+# 创建带 GPU 的 sandbox（--max-life 默认 30 分钟，长任务请调高）
+# ⚠️ 资源语义：`--memory` 是容器 CPU 内存【总量】（每沙箱一份）；`--gpu-mem` 是【每张卡】的显存（MiB）——
+# `--gpu 2 --gpu-mem 8000` = 每卡 8000MiB、总显存 16000MiB（内部 OpenSandbox/HAMi 后端直接写入 HAMi 每卡注解；
+# 注意云端 runpod 后端将 --gpu-mem 视为总显存÷卡数）。单卡显存上限可查 `sandbox resources`（memory_mib）。
+delta-cli sandbox create \
+  --image image.yangtzeailab.com/opensandbox/pytorch-cuda13:latest \
+  --cpu 4 --memory 16Gi --gpu 1 \
+  --max-life 120
+
+# 需要长期存活、不被自动清理的 sandbox：加 --no-auto-cleanup（仅显式 kill/finish 可销毁）
+delta-cli sandbox create \
+  --image image.yangtzeailab.com/opensandbox/pytorch-cuda13:latest \
+  --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 在 complete 帧中
+# 需要 stdout 末尾 JSON 摘要时：读取 log_file 解析（sandbox read <id> --path <log_file>）
+delta-cli sandbox run <sandbox_id> --command "echo '{\"status\":\"ok\",\"result\":\"done\"}'" --timeout 60
+
+# 读取结果文件
+delta-cli sandbox read <sandbox_id> --path /workspace/result.json
+
+# 销毁 sandbox
+delta-cli sandbox kill <sandbox_id>
+```
+
+## 命令列表
+
+### 全局命令
+
+| 命令 | 说明 |
+|------|------|
+| `delta-cli config init` | 初始化配置文件 |
+| `delta-cli config show` | 查看当前配置（敏感字段已脱敏） |
+| `delta-cli config set <key> <value>` | 修改配置项 |
+| `delta-cli config remove <key>` | 移除配置项（支持 `token`、`apikey`） |
+| `delta-cli auth login` | 交互式登录（自动识别 API Key / Token） |
+| `delta-cli auth login --apikey <key>` | API Key 认证（推荐） |
+| `delta-cli auth login --token <token>` | Token 认证 |
+| `delta-cli auth status` | 查看认证状态 |
+| `delta-cli upgrade` | 升级 CLI 和 AI Skills 到最新版本 |
+| `delta-cli upgrade --check` | 检查是否有可用更新 |
+| `delta-cli upgrade --cli-only` | 只升级 CLI 二进制 |
+| `delta-cli upgrade --skills-only` | 只升级 AI Skills |
+| `delta-cli usage` | 查看当前用户用量和剩余额度 |
+| `delta-cli --version` | 显示版本 |
+
+### Sandbox 命令
+
+> **提示**：`sandbox list`（列沙箱实例）与 `sandbox ls <id>`（列目录）不同，注意区分。
+
+| 命令 | 说明 |
+|------|------|
+| `delta-cli sandbox list` | 列出当前用户的 sandbox 实例 |
+| `delta-cli sandbox providers` | 查看可用计算后端 |
+| `delta-cli sandbox resources [--provider opensandbox\|autodl]` | 查看各后端当前剩余可申请资源（GPU/显存/核心） |
+| `delta-cli sandbox images` | 查看可用镜像列表（每条含 `image_name`/`tags`/`description`/`supports_shared_workspace`；`supports_shared_workspace=true` 表示该算力可开共享工作区（opensandbox/autodl），可与 `--shared-workspace` 搭配；实际播种/写回由平台创建时探测镜像内 rclone 决定） |
+| `delta-cli sandbox recommend --cpu N --memory XGi` | 获取资源配置推荐 |
+| `delta-cli sandbox create --image <img> [--no-auto-cleanup] [--shared-workspace=true\|false]` | 创建 sandbox 容器（`--no-auto-cleanup` 不被自动清理；`--shared-workspace` 默认 true：启用共享工作区（播种/写回由平台创建时探测镜像内 rclone 决定，镜像无 rclone 时跳过、数据不跨沙箱持久）；false 跳过播种/写回，适合快速任务） |
+| `delta-cli sandbox extend <id> --max-life N` | **动态延长运行中** sandbox 的 max-life（可增可减，N 需大于已存活分钟且 ≤10080；提前回收用 `kill`/`finish`）；不带 `--max-life` 时查询当前生命周期（已存活/剩余/到期时间）；`status` 输出含 `data.lifecycle` 生命周期摘要（已存活/剩余/到期；生命周期接口不可用时省略） |
+| `delta-cli sandbox connect <id>` | 连接 sandbox |
+| `delta-cli sandbox status <id>` | 查看 sandbox 状态 |
+| `delta-cli sandbox finish <id>` | 保存结果并销毁 |
+| `delta-cli sandbox kill <id>` | 销毁 sandbox |
+| `delta-cli sandbox run <id> --command "..." [--timeout <秒>] [--summary/--no-summary] [--artifacts]` | 同步运行命令（SSE 原始 `data:` 帧透传到 stdout，无末尾信封，`exit_code`/`log_file` 在 `complete` 帧）；`--summary`/`--artifacts` 仅旧服务器回退路径生效 |
+| `delta-cli sandbox run-bg <id> --command "..." [--timeout <秒>] [--wait] [--summary/--no-summary] [--artifacts]` | 后台运行命令；不加 `--wait` 立即返回 `{execution_id, sandbox_id}`；加 `--wait` 通过 SSE 实时流跟随（原始 `data:` 帧透传到 stdout，无末尾信封） |
+| `delta-cli sandbox logs <id> --execution-id <eid> [--tail N --grep <pattern> --context N --max-bytes N]` | 查看后台日志；默认返回 `stderr_size + stderr_tail`（避免上下文爆炸）；可用 `--tail/--grep` 过滤 |
+| `delta-cli sandbox cancel <id> --execution-id <eid>` | 中断后台命令 |
+| `delta-cli sandbox read <id> --path <path> [--output <本地路径>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | 读取容器内文件；`--output <path>` 保存到本地；`--tail/--grep` 过滤；非 UTF-8 文件 CLI 自动走 base64 fallback |
+| `delta-cli sandbox pull <id> --source <沙箱路径> --target <本地路径> [--recursive] [--pattern <glob>]` | 从沙箱拉取文件/目录到本地（mirror of `upload`，flag 方向相反：source=远程，target=本地）；单文件或递归目录；CLI 端 + 服务端双向 sha1 完整性校验 |
+| `delta-cli sandbox write <id> --path <path> --source <本地路径>` | 写入文件 |
+| `delta-cli sandbox write-multiple <id> --entry <远程路径>=<本地路径>` | 批量写入 |
+| `delta-cli sandbox ls <id> --path <path>` | 列出目录 |
+| `delta-cli sandbox stat <id> --path <path>` | 文件元数据 |
+| `delta-cli sandbox mv <id> --entry <src=dest>` | 移动/重命名 |
+| `delta-cli sandbox replace <id> --path <path> --old <文本> --new <文本>` | 替换内容 |
+| `delta-cli sandbox chmod <id> --path <path> --mode <八进制>` | 修改权限 |
+| `delta-cli sandbox rm <id> --path <path>` | 删除文件 |
+| `delta-cli sandbox rmdir <id> --path <路径>` | 递归删除目录 |
+| `delta-cli sandbox mkdir <id> --path <路径>` | 创建目录 |
+| `delta-cli sandbox search <id> --path <根目录> --pattern <glob>` | 搜索文件 |
+| `delta-cli sandbox working-directory <id>` | 获取沙箱工作目录路径 |
+| `delta-cli sandbox upload <id> --source <本地目录> --target <沙箱路径>` | 上传目录（tar.gz + 自动解压） |
+| `delta-cli sandbox expose <id> [--port N]` | 将沙箱内服务端口暴露到公网（frp 隧道），默认端口 8700 |
+| `delta-cli sandbox exposes <id>` | 列出沙箱当前活跃的公网端口隧道 |
+| `delta-cli sandbox dispose <id> --port N` | 回收公网端口隧道（需指定端口号） |
+
+### Science 工具
+
+> Science Server 由 `base_url` 派生（`{base_url}/science_tool`），无需单独配置
+> `science_base_url`；Sandbox API 同样由 `base_url` 派生（`{base_url}/sandbox/api/v1`）。
+
+| 命令 | 说明 |
+|------|------|
+| `delta-cli science list` | 列出所有已启用的 science 工具 |
+| `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：
+
+```json
+// 成功
+{"ok":true,"data":{"id":"sb-xxx","status":"running"}}
+
+// 错误
+{"ok":false,"error":{"type":"auth","message":"not authenticated","hint":"run 'delta-cli auth login'"}}
+```
+
+错误类型及退出码：
+
+| Type | Exit Code | 场景 |
+|------|-----------|------|
+| validation | 2 | 参数错误 |
+| auth | 3 | 未认证 |
+| permission | 4 | 权限不足 |
+| not_found | 5 | 资源不存在 |
+| network | 6 | 网络错误 |
+| api | 7 | 服务端错误 |
+| internal | 10 | 客户端内部错误 |
+
+## AI Agent Skills
+
+delta-cli 内置 AI Agent 操作手册（Skills），帮助 Claude Code 等 AI 助手正确使用 CLI：
+
+```bash
+# 安装仓库中的全部 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、GSAS-II、LAMMPS、Delta-BO、LDM-BO、SynBO、AntBO
+  的按需 reference
+
+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 必须完全一致。
+
+## 开发
+
+```bash
+# 本地构建
+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 github.com/delta-infra/delta-infra-cli/cmd/delta-cli@latest
+
+# 方式 B：在仓库根目录运行 PowerShell 脚本，构建并添加到用户 PATH
+# .\install-from-source.ps1
+# .\install-from-source.ps1 -InstallDir "$env:USERPROFILE\bin"
+```
+
+### 日常开发流程
+
+修改 `skills/` 或编译 `delta-cli` 后，需要同步到 Memento-S 项目才能生效：
+
+```bash
+# 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` 配置。
+
+## 构建与发布
+
+### 本地构建
+
+```bash
+# 本地构建
+make build
+
+# 运行测试
+make test
+
+# 代码检查
+make lint
+
+# 跨平台编译（生成各平台二进制文件到 bin/）
+make release
+```
+
+> `make release` 仅生成各平台二进制文件（如 `bin/delta-cli-linux-amd64`），不会自动打包。打包与发布请使用下文的 `release.sh`。
+
+### 一键发布（维护者）
+
+项目根目录下的 `release.sh` 脚本负责完整发布流程：
+
+```bash
+export GH_TOKEN=<your-github-pat>
+export NPM_TOKEN=<your-npm-token>
+./release.sh v1.1.15
+```
+
+脚本执行步骤：
+1. 更新 `package.json` 版本号。
+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`。
+6. 执行 `npm publish --access public` 发布 `@delta-infra/cli`。
+
+需要提前安装 `gh` CLI、Node.js/npm，并配置 `GH_TOKEN` 与 `NPM_TOKEN`。CI 流程可参考 `.gitlab-ci.yml`。
+
+### npm 镜像
+
+如果 GitHub 下载较慢，安装 npm 包时可设置镜像：
+
+```bash
+DELTA_CLI_MIRROR="https://gh-proxy.com/https://github.com" npm install -g @delta-infra/cli
+```
+
+## 沙箱内镜像源自动配置
+
+创建沙箱时，服务端会**自动检测部署所在网络区域**（中国大陆 / 海外），并在区域为中国大陆时把镜像配置注入到容器里。用户无需任何手动配置，进去即可用。
+
+- **中国大陆（domestic）**：服务端自动注入镜像配置，`pip install` / `npm install` / `git clone` / HuggingFace 下载会走国内镜像。
+- **海外（overseas）**：不注入镜像，使用各包管理器官方源。
+- 服务端通过探测 `pypi.org` / `npmjs.org` 的连通性来判断区域（带缓存、探测失败时按海外兜底，即 fail-open）。
+
+覆盖的 4 类配置：
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| pip index-url | Python 包索引 | `https://pypi.tuna.tsinghua.edu.cn/simple` |
+| npm registry | Node 包源 | `https://registry.npmmirror.com` |
+| HF_ENDPOINT | HuggingFace 下载域名 | `https://hf-mirror.com` |
+| git insteadOf | GitHub 克隆代理 | `https://gh-proxy.com/https://github.com` |
+
+AutoDL 计算后端默认关闭镜像注入（海外平台），仅当运维明确配置开启后才生效。
+
+> **注意区分两套镜像机制**：本沙箱镜像配置针对的是**沙箱里的包管理器**（pip / npm / git / HF）。它与 CLI 自身的下载镜像 `DELTA_CLI_MIRROR` 是两回事——`DELTA_CLI_MIRROR` 只用于**安装 delta-cli 二进制**，不作用于沙箱内。
+
+## 技术栈
+
+- **语言**: Go 1.23+
+- **CLI 框架**: [Cobra](https://github.com/spf13/cobra)
+- **配置**: JSON 文件（`~/.delta-infra/config.json`，权限 0600）
+- **输出**: JSON envelope（AI-agent 友好，可脚本化）
+- **发布**: GitHub Release（tar.gz/zip） + npm wrapper
+- **架构**: 扁平静态命令树，Factory 依赖注入，惰性初始化
+
+## License
+
+MIT