@delta-infra/cli 1.0.87 → 1.0.90

package/README.md

@@ -141,9 +141,9 @@ 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_TOKEN=your-token
+export DELTA_INFRA_API_KEY=your-api-key        # 或 DELTA_INFRA_TOKEN
 delta-cli config init
 ```
 
@@ -151,16 +151,26 @@ delta-cli config init
 
 ### 2. 认证
 
-使用 Bearer Token：
+支持 **API Key** 与 **Bearer Token** 两种凭据（API Key 优先）。
+
+**获取 API Key**：登录 Delta Infra **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
@@ -201,7 +211,8 @@ delta-cli sandbox kill <sandbox_id>
 | `delta-cli config init` | 初始化配置文件 |
 | `delta-cli config show` | 查看当前配置（敏感字段已脱敏） |
 | `delta-cli config set <key> <value>` | 修改配置项 |
-| `delta-cli auth login` | 交互式登录 |
+| `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 到最新版本 |
@@ -218,6 +229,7 @@ delta-cli sandbox kill <sandbox_id>
 |------|------|
 | `delta-cli sandbox list` | 列出当前用户的 sandbox 实例 |
 | `delta-cli sandbox providers` | 查看可用计算后端 |
+| `delta-cli sandbox resources [--provider opensandbox\|autodl]` | 查看各后端当前剩余可申请资源（GPU/显存/核心） |
 | `delta-cli sandbox images` | 查看可用镜像列表 |
 | `delta-cli sandbox recommend --cpu N --memory XGi` | 获取资源配置推荐 |
 | `delta-cli sandbox create --image <img> [--no-auto-cleanup]` | 创建 sandbox 容器（`--no-auto-cleanup` 不被自动清理） |
@@ -421,6 +433,27 @@ export NPM_TOKEN=<your-npm-token>
 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+

package/checksums.txt

@@ -1,5 +1,5 @@
-4f90fb1c489ac827e1be5aa0fbe9086518e0ae8b74e1c52254625f97b88cb699  delta-cli-darwin-amd64.tar.gz
-e672888b452508b0721acb4c49a72202e7cd7010986bee8f5d806a0067fbdb2f  delta-cli-darwin-arm64.tar.gz
-3d8174a44a868992815dfade0d5b8509fbf83099506b16cf240f9ff519e00849  delta-cli-linux-amd64.tar.gz
-da0da161c54d1876b6b0d8a8dd2002d9ca0a8438e5f6b117f0da59135ddaa67d  delta-cli-linux-arm64.tar.gz
-9773fabda94a779c6dec18f0486fe25e7ec7177a8ef490683e00b9dc2cf7ac04  delta-cli-windows-amd64.zip
+79a7cf6a8f997f1aa1fa66c4d3a2f8a342d5e709684dab4be487dfa4f0bf8e97  delta-cli-darwin-amd64.tar.gz
+9883f3b2441349160389e32d32ef6a4c7b627f6277962da2cede032126530520  delta-cli-darwin-arm64.tar.gz
+cb0945d795f00e4ddb33bcb7cd0ea55ca847b1a7dd9698f7d45d6e38ff9ee20c  delta-cli-linux-amd64.tar.gz
+1bcc9be8107bd1785296cdb3060292576d6b5529de812445363b15347ef04aee  delta-cli-linux-arm64.tar.gz
+b0b68d07995291b55a781c2ef30c333e67d838ad9b4fd7fe49c2fbab8ddac6cd  delta-cli-windows-amd64.zip

package/package.json

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

package/scripts/install-wizard.js

@@ -15,6 +15,7 @@ const CONFIG_DIR = path.join(osHomedir(), ".delta-infra");
 const CONFIG_VERSION = 1;
 const DEFAULT_BASE_URL = "https://delta-infra-nacos-test.yangtzeailab.com/sandbox/api/v1";
 const DEFAULT_SCIENCE_BASE_URL = "http://8.141.101.94:8080/science_tool";
+const DASHBOARD_API_KEYS_URL = "https://delta-infra-dashboard-test.yangtzeailab.com/dashboard/api-keys";
 const isWindows = process.platform === "win32";
 
 const PLATFORM_PATHS = {
@@ -137,12 +138,14 @@ const messages = {
     step3Fail:      "配置初始化失败。运行以下命令重试: delta-cli config init",
     step4:          "身份认证",
     step4Confirm:   "是否进行身份认证？",
+    step4GuideTitle:"还未配置 API Key",
+    step4Guide:     "请先在网页端生成一个 API Key：\n  %s\n打开后复制生成的 Key，粘贴到下方提示处。",
     step4Skip:      "跳过身份认证。后续运行 delta-cli auth login 完成",
     step4Done:      "认证完成",
     step4Fail:      "认证失败。运行以下命令重试: delta-cli auth login",
     done:           "安装完成！\n现在可以让你的 AI 工具使用 delta-cli 管理 Delta Sandbox 资源或调用 Science 工具。",
     cancelled:      "安装已取消",
-    nonTtyHint:     "要完成配置，请在终端中运行：\n  delta-cli config init\n  delta-cli auth login",
+    nonTtyHint:     "要完成配置，请在终端中运行：\n  delta-cli config init\n  delta-cli auth login\n若还没有 API Key，请先在网页端生成：\n  " + "https://delta-infra-dashboard-test.yangtzeailab.com/dashboard/api-keys",
     uninstallConfirm: "将移除全局包、AI Skills 和配置文件。是否继续？",
     uninstallCancelled: "卸载已取消",
     uninstallDone:  "卸载完成",
@@ -171,12 +174,14 @@ const messages = {
     step3Fail:      "Failed to init config. Run manually: delta-cli config init",
     step4:          "Authorization",
     step4Confirm:   "Would you like to authenticate now?",
+    step4GuideTitle:"No API key configured yet",
+    step4Guide:     "Please generate an API key on the web dashboard first:\n  %s\nCopy the key and paste it when prompted.",
     step4Skip:      "Skipped. Run delta-cli auth login to authorize later",
     step4Done:      "Authorization complete",
     step4Fail:      "Failed to authorize. Run delta-cli auth login to retry",
     done:           "You are all set!\nYour AI tool can now use delta-cli to manage Delta Sandbox resources or invoke Science tools.",
     cancelled:      "Installation cancelled",
-    nonTtyHint:     "To complete setup, run interactively:\n  delta-cli config init\n  delta-cli auth login",
+    nonTtyHint:     "To complete setup, run interactively:\n  delta-cli config init\n  delta-cli auth login\nIf you don't have an API key yet, generate one first:\n  " + "https://delta-infra-dashboard-test.yangtzeailab.com/dashboard/api-keys",
     uninstallConfirm: "This will remove the global package, AI Skills and config. Continue?",
     uninstallCancelled: "Uninstall cancelled",
     uninstallDone:  "Uninstall complete",
@@ -561,6 +566,11 @@ async function stepAuthLogin(msg) {
   }
 
   p.log.step(msg.step4);
+  const existingConfig = getExistingConfig();
+  if (!existingConfig || (!existingConfig.token && !existingConfig.apikey)) {
+    p.log.warn(msg.step4GuideTitle);
+    p.log.info(fmt(msg.step4Guide, DASHBOARD_API_KEYS_URL));
+  }
   try {
     run(deltaCli, ["auth", "login"]);
     p.log.success(msg.step4Done);

package/skills/delta-sandbox/SKILL.md

@@ -23,6 +23,13 @@ metadata:
 - delta-cli 不内嵌默认凭证，运行前必须按 `delta-shared` 完成认证配置。
 - sandbox_id 必须来自真实返回，不要凭用户口述猜测。
 
+## 沙箱环境（镜像源）
+
+- **国内部署（domestic）**：沙箱创建时服务端已自动注入国内镜像配置。`pip install` / `npm install` / `git clone` / HuggingFace 下载**无需额外配置**，直接可用。覆盖：pip index-url（pypi.tuna.tsinghua.edu.cn）、npm registry（npmmirror）、HF_ENDPOINT（hf-mirror.com）、git insteadOf（github 代理）。
+- **海外部署（overseas）**：不注入镜像，使用官方源。
+- **AutoDL 沙箱**：默认不注入镜像（默认关闭），按官方源使用。
+- 若镜像源异常，优先检查沙箱所在区域的网络，而不是假设沙箱未配置。
+
 ## 强制规则（违规则任务视为失败）
 
 1. **必须使用 delta-cli**：所有 sandbox 操作必须通过 `delta-cli sandbox <subcommand>` 执行。**禁止**用 Python（urllib/httpx/requests）或任何 SDK 直接调用 HTTP API。delta-cli 提供类型化错误输出（`error.type`），是 AI agent 正确解析错误的唯一途径。
@@ -40,10 +47,10 @@ metadata:
    ```bash
    delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> --wait
    ```
-   CLI 通过 SSE 实时流（`/logs/stream`）跟随输出，把原始 SSE 帧（`data: {...}`）**逐帧透传到 stdout**（curl -N 风格），帧类型见 JSON 的 `type` 字段：`init`（含 `execution_id`）/ `stdout` / `stderr` / `error` / `complete`。收到 `complete` 即命令结束。**CLI 会在 complete 帧里补全字段**：服务端给 `exit_code`/`execution_id`/`error`，CLI 注入流内累计的 `stdout`/`stderr`、兜底恢复的 `log_file`、以及检测到的末尾 JSON `result_summary`（stdout 末尾 50 行内有合法 JSON 对象时）。命令成败看 `complete` 帧里的 `exit_code`；**命令非零退出或报错时，CLI 追加一个 `error.type: command_failed` 信封并以非零码退出（进程退出码 8）**，信封 `message` 已附 stderr 尾部，便于 `&&` 链与按 `error.type` 分支、快速扫读失败原因；`type:"error"` 帧的 `message` 也会 best-effort 附上已流出的 stderr 尾部；成功则不追加信封。若在 `--timeout`（默认 300s，同时充当服务端命令超时和客户端等待 deadline）内未收到 `complete`，CLI 会在已透传的帧后**追加一个 `finished=false` 的快照信封**（`CommandLogsResult`），表示命令仍运行。完整 stdout 在 `finished` 后被写入沙箱内的 `log_file`（默认 `/workspace/{user_id}/{sandbox_id}/{execution_id}/delta-result-{execution_id}.json`，以服务端返回的 `log_file` 字段为准），需要读全文时用 `sandbox read <id> --path <log_file>`（末尾 JSON 摘要已在 complete 帧里，通常无需再读）。**`--summary`/`--artifacts` 富化（含 hints）仅在旧服务器回退路径生效**（服务端无 `/logs/stream` 端点时 CLI 自动回退到 5s 轮询并输出 `CommandResult` 信封）。`execution_id` 可用于后续 `sandbox logs` / `cancel`。
+   CLI 通过 SSE 实时流（`/logs/stream`）跟随输出，把原始 SSE 帧（`data: {...}`）**逐帧透传到 stdout**（curl -N 风格），帧类型见 JSON 的 `type` 字段：`init`（含 `execution_id`）/ `stdout` / `stderr` / `error` / `complete`。收到 `complete` 即命令结束。**CLI 会在 complete 帧里补全字段**：服务端给 `exit_code`/`execution_id`/`error`，CLI 注入流内累计的 `stdout`/`stderr`、兜底恢复的 `log_file`、以及检测到的末尾 JSON `result_summary`（stdout 末尾 50 行内有合法 JSON 对象时）。命令成败看 `complete` 帧里的 `exit_code`；**命令非零退出或报错时，CLI 追加一个 `error.type: command_failed` 信封并以非零码退出（进程退出码 8）**，信封 `message` 已附 stderr 尾部，便于 `&&` 链与按 `error.type` 分支、快速扫读失败原因；`type:"error"` 帧的 `message` 也会 best-effort 附上已流出的 stderr 尾部；成功则不追加信封。若在 `--timeout`（默认 300s，同时充当服务端命令超时和客户端等待 deadline）内未收到 `complete`，CLI 会在已透传的帧后**追加一个 `finished=false` 的快照信封**（`CommandLogsResult`），表示命令仍运行。完整 stdout 在 `finished` 后被写入沙箱内的 `log_file`（默认 `/workspace/{user_id}/sandbox_logs/delta-result-{sandbox_id}-{execution_id}.json`，以服务端返回的 `log_file` 字段为准），需要读全文时用 `sandbox read <id> --path <log_file>`（末尾 JSON 摘要已在 complete 帧里，通常无需再读）。**`--summary`/`--artifacts` 富化（含 hints）仅在旧服务器回退路径生效**（服务端无 `/logs/stream` 端点时 CLI 自动回退到 5s 轮询并输出 `CommandResult` 信封）。`execution_id` 可用于后续 `sandbox logs` / `cancel`。
 
    **实时跟随 / 手动轮询（需要查看中间进度时）**：
-   `sandbox logs <id> --execution-id <exec_id> --stream` 实时跟随（SSE）：原始 `data:` 帧逐帧透传到 stdout，直到 `complete` 事件，无末尾信封。`sandbox logs <id> --execution-id <exec_id>`（不加 `--stream`）返回快照信封：
+   `sandbox logs <id> --execution-id <exec_id> --stream` 实时跟随（SSE）：原始 `data:` 帧逐帧透传到 stdout，直到 `complete` 事件，无末尾信封（`--stream` 必须传 `--execution-id`）。`sandbox logs <id> --execution-id <exec_id>`（不加 `--stream`）返回快照信封；`--execution-id` 可省略——省略时仅按 sandbox 查询，服务端因 sandbox_id / execution_id 未同时传递而自动走 ES（Elasticsearch）查询：
    - `finished=true` + `exit_code=0` → 完成
    - `finished=true` + `exit_code!=0` → 失败  
    - `running=true` → 仍运行
@@ -52,11 +59,14 @@ metadata:
 
    - 后台任务成功后仍需按规则 2/3 销毁 sandbox。
 
-8. **写入文件禁止使用路径或 Shell 变量，仅允许文件名**：
+8. **写入文件默认落到 sandbox 的 working-directory，禁止使用 Shell 变量路径**：
+   - ✅ **推荐**：`delta-cli sandbox write <id> --source train.py`（不传 `--path`，默认写到 `<working-directory>/train.py`）
+   - ✅ **显式指定**：`delta-cli sandbox write <id> --path <working-directory>/train.py --source train.py`（`--path` 传相对路径也会自动以 working-directory 为前缀）
    - ❌ **禁止**：`--source "$WORKSPACE_ROOT/train.py"`、`--source "$(pwd)/train.py"`（Shell 展开路径 → 空文件或失败）
    - ❌ **禁止**：`--data "大量代码..."`（Shell 转义问题）
-   - ✅ **正确**：`delta-cli sandbox write <id> --path /workspace/train.py --source train.py`（仅文件名）
-   - 少量配置（< 20 行）可用 `--data "..."`。`--mode 755` 可设置文件权限。
+   - ❌ **不建议**：`--path /workspace/train.py` 这类直接写工作目录根、落在 `{user_id}` 之外的路径——kill 后 `rclone sync` 不会写回 OSS，文件不持久化。
+   - 查询 sandbox 的 working-directory：`delta-cli sandbox working-directory <id>`（返回 `data.path`）。`run`/`run-bg` 引用脚本时用 `python <working-directory>/train.py` 的完整路径。
+   - 少量配置（< 20 行）可用 `--data "..."`，此时必须带 `--path`（无法从文件名推断）。`--mode 755` 可设置文件权限。
 
 9. **每个 `run-bg` 生成独立 `execution_id`**：每次调用 `sandbox run-bg` 都会返回一个唯一的 `execution_id`，多个后台任务之间通过它区分。务必保存每次返回的 `execution_id` 并与任务对应，后续通过 `sandbox logs <id> --execution-id <exec_id>` 分别查询各任务的结果。同步 `sandbox run` 无需 `execution_id`，结果直接返回。
 
@@ -67,7 +77,7 @@ metadata:
     - 只有在**解析 JSON**（例如从 `sandbox read` 的信封中提取 `summary` 并写入 `result.json`）时，才使用 `python3`/`python_repl`。
 
 11. **代码/数据必须经由 `delta-cli sandbox write` 进入 sandbox**
-    - 所有要送进 sandbox 执行的脚本、配置、数据文件，**必须**通过 `delta-cli sandbox write <id> --path /workspace/<文件名> --source <本地文件名>` 写入。
+    - 所有要送进 sandbox 执行的脚本、配置、数据文件，**必须**通过 `delta-cli sandbox write <id> --source <本地文件名>` 写入，默认落到该 sandbox 的 working-directory（`/workspace/{user_id}/{sandbox_id}/`，可用 `delta-cli sandbox working-directory <id>` 查询），位于 OSS 同步范围内、kill 后可持久化。
     - 不要把脚本先写到宿主 workspace 再依赖同步；宿主 workspace 的文件对 sandbox 内部不可见。
     - 本规则关注的是“入口统一为 `sandbox write`”，不针对任何特定宿主工具。无论宿主提供何种文件操作接口，最终都要把内容送到 sandbox 内部。
 
@@ -130,6 +140,7 @@ required_outputs:
 | **发现** | |
 | 查看可用镜像 | `sandbox images` |
 | 查看可用 provider | `sandbox providers` |
+| 查看剩余可申请资源 | `sandbox resources [--provider <opensandbox/autodl>]` — 各后端 GPU/显存/核心可用量，`gpu_types` 结构随 provider 不同（opensandbox 有 `vgpu`/`core`/`memory_mib`，autodl 有 `idle_gpu_num`） |
 | 获取资源推荐 | `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` |
 | 列出当前用户的 sandbox | `sandbox list [--status <running/finished/killed/error>] [--start-time <ISO8601>] [--end-time <ISO8601>] [--provider <opensandbox/autodl>] [--sandbox-id <id>] [--days N]` |
 | **生命周期** | |
@@ -141,12 +152,13 @@ required_outputs:
 | **命令执行** | |
 | 同步运行命令（≤60s） | `sandbox run <id> --command "..." [--timeout <秒>] [--summary/--no-summary] [--artifacts]` |
 | 后台运行命令（>60s） | `sandbox run-bg <id> --command "..." [--timeout <秒>] [--wait] [--summary/--no-summary] [--artifacts]` |
-| 查看后台日志 | `sandbox logs <id> --execution-id <exec_id> [--tail N --grep <pattern> --context N] [--stream]` |
+| 查看后台日志 | `sandbox logs <id> [--execution-id <exec_id>] [--tail N --grep <pattern> --context N] [--stream]`（`--execution-id` 可选；省略时按 sandbox 从 ES 查询，仅 `--stream` 必须传）|
 | 中断后台命令 | `sandbox cancel <id> --execution-id <exec_id>` |
 | **文件操作** | |
 | 读取文件 | `sandbox read <id> --path <path> [--output <本地路径> --tail N --grep <pattern> --offset N --limit N --context N --max-bytes N --parse-json]` |
 | 拉取文件/目录 | `sandbox pull <id> --source <沙箱路径> --target <本地路径> [--recursive] [--pattern <glob>]` — 单文件或目录递归，含 sha1 校验（mirror of upload，flag 方向与 upload 相反：source=远程，target=本地） |
-| 写入文件 | `sandbox write <id> --path <path> --source <文件名>`（推荐）|
+| 查询工作目录 | `sandbox working-directory <id>`（返回 `data.path`，形如 `/workspace/{user_id}/{sandbox_id}`）|
+| 写入文件 | `sandbox write <id> --source <文件名>`（不传 `--path` 默认写到 working-directory）；`--path <路径>` 传相对路径自动加 working-directory 前缀，绝对路径原样使用 |
 | 批量写入 | `sandbox write-multiple <id> --entry <远程路径>=<本地路径> [--entry ...]` |
 | 上传目录 | `sandbox upload <id> --source <本地目录> --target <沙箱路径>` |
 | 列出目录 | `sandbox ls <id> --path <路径>`（默认 `.`）|
@@ -173,21 +185,21 @@ required_outputs:
     - `--no-auto-cleanup`：加此 flag 后该 sandbox **不会被自动清理**（服务端超时回收 + 本地周期 cleanup_stale 均跳过），只能通过显式 `sandbox kill`/`finish` 销毁。仅当任务确实需要跨越周期清理长期存活时才使用，任务结束后必须主动销毁，避免资源泄漏。
     - **禁止在 create 成功后反复调用 `sandbox status` 轮询**。`sandbox create` 返回时 sandbox 已经就绪，直接用它返回的 `data.sandbox_id` 执行 `write`/`run` 即可。多余的轮询会增加工具调用次数且没有任何收益。
 3. **写入代码/数据**：
-   - **单个文件**：`delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — **必须**使用相对路径（如 `--source train.py`），**禁止**使用 `"$WORKSPACE_ROOT/train.py"` 或 `$(pwd)/train.py` 等 Shell 变量路径。`--source` 让 CLI 自行读取本地文件，不会经过 Shell 展开，是最安全的方式。写入后返回的 `size` 字段是实际磁盘字节数（来自 stat 验证），可对比确认写入完整性。少量配置（<20 行）可用 `--data "..."`。文件路径和扩展名由镜像中的运行时决定。
+   - **单个文件**：`delta-cli sandbox write <id> --source <文件名>` — 不传 `--path`，默认写到该 sandbox 的 working-directory（`/workspace/{user_id}/{sandbox_id}/`，可用 `delta-cli sandbox working-directory <id>` 查询）。`--source` 只传本地文件名（如 `--source train.py`），**禁止**使用 `"$WORKSPACE_ROOT/train.py"` 或 `$(pwd)/train.py` 等 Shell 变量路径。`--source` 让 CLI 自行读取本地文件，不会经过 Shell 展开，是最安全的方式。若需指定路径，`--path <相对路径>` 会自动加 working-directory 前缀，绝对路径原样使用（**不建议**写 `/workspace/<filename>` 这种落在 `{user_id}` 之外的位置，kill 后不持久化）。写入后返回的 `size` 字段是实际磁盘字节数（来自 stat 验证），可对比确认写入完整性。少量配置（<20 行）可用 `--data "..."`，但此时必须带 `--path`。文件路径和扩展名由镜像中的运行时决定。
    - **批量写入**：`sandbox write-multiple <id> --entry <远程路径>=<本地路径> [--entry ...]`（远程路径在 `=` 左边，本地路径在右边，`--data` 批量写入不可用）
    - **上传目录**：`sandbox upload <id> --source <本地目录> --target <沙箱路径>` — CLI 将本地目录打包为 tar.gz，通过 multipart/form-data 上传，服务端自动解压到 target 目录。返回每个文件的路径、大小、模式。上传后 CLI 自动对比本地和远程文件清单做完整性校验（大小不匹配、多余文件等会告警）。
      - **注意**：`--source` 是**本地目录路径**，`--target` 是**沙箱内的目标目录**，target 目录不存在会自动创建。
      - 支持嵌套目录，空目录也会被创建。
      - **写后验证（可选）**：`sandbox stat <id> --path <path>` 确认文件存在且 size 符合预期即可。**不要**用 `sandbox ls` + `sandbox read` 把刚写入的文件读回宿主再逐字对比；无异常时不需要读回。
 4. **运行命令**：
-    - **短任务（预计 ≤ 60 秒）**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，命令的 stdout/stderr 通过 SSE **以原始 `data:` 帧逐帧透传到 stdout**（无末尾信封），`exit_code` / `log_file` / `execution_id` 从 `complete` 帧读取。完整 `stdout` 在完成后写入 run envelope 日志文件（`log_file` 字段），需要读全文或提取末尾 JSON 时用 `sandbox read`，**不要**再调用 `sandbox logs`。可通过 `--log-file <路径>` 自定义 run envelope 日志文件路径；默认值为 `/workspace/{user_id}/{sandbox_id}/{execution_id}/delta-result-{execution_id}.json`（以服务端返回的 `log_file` 字段为准）。根据镜像中的运行时构造命令，常见示例：
-     - Python：`python /workspace/train.py`
-     - Node.js：`node /workspace/app.js`
-     - Go：`go run /workspace/main.go`
-     - Shell：`bash /workspace/run.sh`
+    - **短任务（预计 ≤ 60 秒）**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，命令的 stdout/stderr 通过 SSE **以原始 `data:` 帧逐帧透传到 stdout**（无末尾信封），`exit_code` / `log_file` / `execution_id` 从 `complete` 帧读取。完整 `stdout` 在完成后写入 run envelope 日志文件（`log_file` 字段），需要读全文或提取末尾 JSON 时用 `sandbox read`，**不要**再调用 `sandbox logs`。可通过 `--log-file <路径>` 自定义 run envelope 日志文件路径；默认值为 `/workspace/{user_id}/sandbox_logs/delta-result-{sandbox_id}-{execution_id}.json`（以服务端返回的 `log_file` 字段为准）。脚本经 `sandbox write` 落盘后位于 working-directory，运行命令需用完整路径 `<working-directory>/<文件名>`（先 `sandbox working-directory <id>` 查询）。根据镜像中的运行时构造命令，常见示例（`<wd>` 为 working-directory）：
+     - Python：`python <wd>/train.py`
+     - Node.js：`node <wd>/app.js`
+     - Go：`go run <wd>/main.go`
+     - Shell：`bash <wd>/run.sh`
    - **长任务（预计 > 60 秒，如下载模型、训练、编译、大规模数据处理）**：`delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> [--log-file <路径>]` 提交后台任务，获得 `execution_id` 后通过以下命令查询：
-       - `delta-cli sandbox logs <id> --execution-id <execution_id> --stream` — SSE 实时跟随，原始 `data:` 帧逐帧透传到 stdout，直到 `complete` 事件（含 `exit_code`/`log_file`），无末尾信封。
-       - `delta-cli sandbox logs <id> --execution-id <execution_id>` — 快照信封，返回 `stdout_tail`（末尾 800 字节）、`stderr_tail`（末尾 200 字节）、`stdout_size`、`stderr_size`、`cursor`、`running`、`finished`、`exit_code`、`log_file`（完成后）。当 `finished=true` 时认为完成，完整输出需读取 `log_file`。
+       - `delta-cli sandbox logs <id> --execution-id <execution_id> --stream` — SSE 实时跟随，原始 `data:` 帧逐帧透传到 stdout，直到 `complete` 事件（含 `exit_code`/`log_file`），无末尾信封（`--stream` 必须传 `--execution-id`）。
+       - `delta-cli sandbox logs <id> --execution-id <execution_id>` — 快照信封，返回 `stdout_tail`（末尾 800 字节）、`stderr_tail`（末尾 200 字节）、`stdout_size`、`stderr_size`、`cursor`、`running`、`finished`、`exit_code`、`log_file`（完成后）。当 `finished=true` 时认为完成，完整输出需读取 `log_file`。`--execution-id` 可省略：省略时仅按 sandbox 查询，服务端因 sandbox_id / execution_id 未同时传递而自动走 ES 查询。
            禁止对长任务使用同步 `sandbox run`
 
    **推荐实践**：让 sandbox 脚本在 `stdout` 末尾打印一个独立的结构化 JSON 对象（例如 `{"status":"ok", ...}`）。SSE 路径下 CLI 会检测该末尾 JSON 并直接在 `complete` 帧里带出 `result_summary`，**任务结束后直接复用 complete 帧的 `result_summary` 写入 result.json**，无需再 `sandbox read` log_file 反向扫描。仅当 complete 帧缺失 `result_summary`（末尾无合法 JSON）时，才用 `sandbox read <id> --path <log_file>` 读取并按步骤 5 反向扫描提取，避免让大模型“读整段日志再摘要”。
@@ -256,8 +268,8 @@ required_outputs:
 命令执行完毕后，推荐在 `stdout` 末尾打印一行**独立的结构化 JSON**。例如：
 
 - CUDA 检查：`{"status":"ok","torch_version":"2.5.1+cu121","cuda_available":true,"device_name":"NVIDIA H100 80GB HBM3"}`
-- 训练任务：`{"status":"ok","epochs":10,"final_loss":0.12,"final_accuracy":0.94,"model_file":"/workspace/model.pt"}`
-- 数据处理：`{"status":"ok","input_rows":10000,"output_rows":9876,"output_file":"/workspace/output.csv"}`
+- 训练任务：`{"status":"ok","epochs":10,"final_loss":0.12,"final_accuracy":0.94,"model_file":"<wd>/model.pt"}`
+- 数据处理：`{"status":"ok","input_rows":10000,"output_rows":9876,"output_file":"<wd>/output.csv"}`
 
 这样 SKILL 可以用同一套代码把它提取到 `result.json` 的 `summary` 字段，再生成 `RESULT:` 行。
 

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

@@ -8,6 +8,7 @@
 |------|------|
 | `sandbox list [--status <running/finished/killed/error>] [--start-time <ISO8601>] [--end-time <ISO8601>] [--provider <opensandbox/autodl>] [--sandbox-id <id>] [--days N]` | 列出当前用户的 sandbox（与 `ls` 不同：这是列 **沙箱实例**）；支持按状态/时间/Provider/sandbox_id 过滤；时间范围优先级 start_time/end_time > days > 默认 7 天 |
 | `sandbox providers` | 查看可用的计算后端（opensandbox / autodl） |
+| `sandbox resources [--provider <opensandbox/autodl>]` | 查看各后端当前**剩余可申请**资源（GPU/显存/核心）；`gpu_types` 按后端原样透传，结构随 provider 不同——opensandbox 含 `vgpu`/`core`/`memory_mib` 的 `total/used/available`，autodl 含 `total_gpu_num`/`idle_gpu_num` |
 | `sandbox images` | 查看可用镜像列表 |
 | `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` | 获取资源配置推荐 |
 
@@ -35,9 +36,10 @@
 | 命令 | 说明 |
 |------|------|
 | `sandbox read <id> --path <path> [--output <本地路径>] [--tail N] [--grep <pattern>] [--offset N] [--limit N] [--context N] [--max-bytes N] [--parse-json]` | 读取文件；返回 `content` + `size` + `content_length`；`--output <path>` 保存到本地；`--tail/--grep` 用于过滤；非 UTF-8 文件 CLI 自动走 base64 fallback |
-| `sandbox write <id> --path <path> --source <文件名>` | 写入文件（推荐，相对路径） |
-| `sandbox write <id> --path <path> --data "..."` | 写入少量内联内容 |
-| `sandbox write-multiple <id> --entry <src=path> [--entry ...]` | 批量写入多个文件 |
+| `sandbox working-directory <id>` | 查询 sandbox 当前工作目录（绝对路径 `/workspace/{user_id}/{sandbox_id}`） |
+| `sandbox write <id> [--path <路径>] --source <文件名>` | 写入文件（推荐）。不传 `--path` 默认写到 working-directory（`<working-directory>/<文件名>`）；相对 `--path` 也会拼到 working-directory 下；仅绝对 `--path` 原样使用（但 `/workspace/<文件名>` 根路径不在 OSS 同步范围内，不推荐） |
+| `sandbox write <id> --path <绝对路径> --data "..."` | 写入少量内联内容（`--data` 无源文件名，必须显式传 `--path`） |
+| `sandbox write-multiple <id> --entry <src=path> [--entry ...]` | 批量写入多个文件（目标 `path` 相对则同样拼到 working-directory） |
 | `sandbox pull <id> --source <沙箱路径> --target <本地路径> [--recursive] [--pattern <glob>]` | 拉取文件/目录到本地（mirror of `upload`，flag 方向相反：`--source`=远程沙箱路径，`--target`=本地路径）；单文件自动识别；目录默认递归；CLI 端 + 服务端双向 sha1 完整性校验 |
 | `sandbox ls <id> --path <path>` | 列出目录内容（默认 `.`） |
 | `sandbox stat <id> --path <path>` | 获取文件元数据（size / mode / owner / group） |

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

@@ -7,11 +7,11 @@
 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 <image> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`（创建后立即可用，无需连接；--max-life 指定 sandbox 最大存活时间（分钟），默认 30。`--no-auto-cleanup` 可让 sandbox 不被自动清理，仅显式 kill/finish 可销毁。`--provider autodl` 可指定使用 AutoDL 后端。）
-4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — 将本地文件直接写入 sandbox。**必须**使用相对路径（如 `--source infer.py`），禁止使用 `"$WORKSPACE_ROOT/<filename>"`。也可用 `--data "..."` 写入少量内联内容，`--mode 755` 可设置文件权限。写入后返回的 `size` 字段是 stat 验证后的实际磁盘字节数，可确认写入完整。批量写入用 `write-multiple`。文件路径和扩展名由镜像中的运行时决定。
-5. **运行命令** — 根据镜像中的运行时构造命令，常见示例：`python /workspace/train.py`（Python）、`node /workspace/app.js`（Node.js）、`go run /workspace/main.go`（Go）、`bash /workspace/run.sh`（Shell）
+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
    - **长任务 >60s**：`delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒> --wait` 后台执行（推荐），或 `run-bg` + `logs` 手动轮询 (run-bg --wait 默认带 --summary；不加 --wait 立即返回 {execution_id, sandbox_id})
-6. **读取结果** `delta-cli sandbox read <id> --path /workspace/result.json` — 返回 `content`（内容）、`size`（磁盘字节，来自 stat）、`content_length`（字符数）。读不存在的文件返回 error 而非空内容。
+6. **读取结果** `delta-cli sandbox read <id> --path <wd>/result.json`（`<wd>` 为 working-directory，可用 `delta-cli sandbox working-directory <id>` 查询） — 返回 `content`（内容）、`size`（磁盘字节，来自 stat）、`content_length`（字符数）。读不存在的文件返回 error 而非空内容。
 7. **销毁** `delta-cli sandbox kill <id>`（如需保存结果用 finish，finish 会自动销毁）
 
 > **注意**：server 端没有 sandbox 的自动过期或 TTL 机制，不 kill 会永久占用 GPU 资源。请务必在任务结束后销毁。
@@ -40,11 +40,12 @@ delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
 
 # 2a. 实时跟随（SSE，推荐）：
 delta-cli sandbox logs <id> --execution-id <exec_id> --stream
-# ↑ 原始 data: 帧逐帧透传到 stdout，直到 complete 事件，无末尾信封
+# ↑ 原始 data: 帧逐帧透传到 stdout，直到 complete 事件，无末尾信封（--stream 必须传 --execution-id）
 
 # 2b. 手动轮询快照（可用 --tail N / --grep <pattern> 过滤大输出）
 delta-cli sandbox logs <id> --execution-id <exec_id>
 # ↑ 返回 {sandbox_id, execution_id, stderr_tail, stderr_size, cursor, running, finished, exit_code, log_file?}
+#   --execution-id 可省略：省略时仅按 sandbox 查询，服务端因 sandbox_id/execution_id 未同时传递而自动走 ES
 
 # 3. 完成后销毁
 delta-cli sandbox kill <id>
@@ -55,11 +56,11 @@ delta-cli sandbox kill <id>
 `sandbox logs` 返回的数据结构为：
 
 ```json
-{"ok":true,"data":{"sandbox_id":"...","execution_id":"...","stdout_tail":"...","stderr_tail":"...","stdout_size":1234,"stderr_size":1234,"cursor":5,"running":false,"finished":true,"exit_code":0,"log_file":"/workspace/{user_id}/{sandbox_id}/{execution_id}/delta-result-{execution_id}.json"}}
+{"ok":true,"data":{"sandbox_id":"...","execution_id":"...","stdout_tail":"...","stderr_tail":"...","stdout_size":1234,"stderr_size":1234,"cursor":5,"running":false,"finished":true,"exit_code":0,"log_file":"/workspace/{user_id}/sandbox_logs/delta-result-{sandbox_id}-{execution_id}.json"}}
 ```
 
 字段说明：
-- `sandbox_id` / `execution_id` — 与请求一致
+- `sandbox_id` / `execution_id` — 与请求一致；省略 `--execution-id` 时走 ES 按 sandbox 查询，该字段为空
 - `stdout_tail` — CLI 默认保留的 **最后 800 字节** stdout 片段，避免上下文爆炸
 - `stderr_tail` — CLI 默认保留的 **最后 200 字节** stderr 片段（CLI 硬编码 `tailString(s, n)` 按字节截取；ASCII 等同 n 字符，多字节 UTF-8 可能被截断），避免上下文爆炸。不传任何 range flag 时，CLI 会把原始 `stdout`/`stderr` 字段清空，只暴露 `stdout_tail`/`stderr_tail` 和 `stdout_size`/`stderr_size`
 - `stdout_size` — 原始 stdout 字节数（CLI 端计算）

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

@@ -60,15 +60,17 @@ SKILL 会把它提取为 `result.json` 的 `summary`，并生成 `result_summary
 ## 2. 运行用户已有的脚本
 
 ```text
-在 sandbox <sandbox_id> 中运行 /workspace/train.py，参数为 --epochs 10 --batch-size 32。
+在 sandbox <sandbox_id> 中运行 <wd>/train.py，参数为 --epochs 10 --batch-size 32。
 ```
 
+> `<wd>` 为该 sandbox 的 working-directory（`/workspace/{user_id}/{sandbox_id}`，先 `delta-cli sandbox working-directory <id>` 查询）。
+
 说明：文件已存在，用中性动词 `运行`，不使用 `创建` 等承诺动词。
 
 ## 3. 安装依赖并执行命令
 
 ```text
-在 sandbox 中运行 pip install -r /workspace/requirements.txt，然后运行 python /workspace/app.py。
+在 sandbox 中运行 pip install -r <wd>/requirements.txt，然后运行 python <wd>/app.py。
 ```
 
 说明：依赖安装和命令执行都没有落盘新文件，使用中性动词描述。
@@ -82,20 +84,20 @@ SKILL 会把它提取为 `result.json` 的 `summary`，并生成 `result_summary
 说明：
 
 - 训练日志可能很长，不要让 skill 去读整段日志再摘要；让脚本自己输出关键指标。
-- 推荐脚本最终打印：`{"status":"ok","epochs":10,"final_loss":0.023,"final_accuracy":0.992,"model_file":"/workspace/model.pt"}`
+- 推荐脚本最终打印：`{"status":"ok","epochs":10,"final_loss":0.023,"final_accuracy":0.992,"model_file":"<wd>/model.pt"}`
 - skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, epochs=10, ...`。
 - 如需保存完整模型文件，可再用 `sandbox read` 或 `sandbox upload` 处理，不属于 `result.json` 的摘要范围。
 
 ## 5. 通用数据处理
 
 ```text
-在 sandbox 中运行数据处理命令，读取 /workspace/input.csv，输出 /workspace/output.csv，并在 stdout 末尾打印包含 input_rows、output_rows、output_file 的结构化 JSON。
+在 sandbox 中运行数据处理命令，读取 <wd>/input.csv，输出 <wd>/output.csv，并在 stdout 末尾打印包含 input_rows、output_rows、output_file 的结构化 JSON。
 ```
 
 说明：
 
-- 推荐脚本最终打印：`{"status":"ok","input_rows":10000,"output_rows":9876,"output_file":"/workspace/output.csv"}`
-- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, input_rows=10000, output_rows=9876, output_file=/workspace/output.csv`。
+- 推荐脚本最终打印：`{"status":"ok","input_rows":10000,"output_rows":9876,"output_file":"<wd>/output.csv"}`
+- skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, input_rows=10000, output_rows=9876, output_file=<wd>/output.csv`。
 
 ## 6. 模型推理（Qwen / LLM / 视觉等）
 
@@ -120,7 +122,7 @@ SKILL 会把它提取为 `result.json` 的 `summary`，并生成 `result_summary
 - 只有在 skill 会真实创建文件时，才在请求中显式写出 `*.py` / `*.json` / `*.csv` 等扩展名。
 - 不要使用 `脚本需输出...` 这类把代码片段直接跟在承诺动词后的句式。
 - **任务完成的标准是执行结果，不是脚本文件存在**。Planner 和 skill 都要以本地 `result.json` 的生成作为完成标志；`required_outputs` 必须声明 `.json`，不要只声明 `{"kind": "file"}`。
-- **`skill_request` 里不要出现完整代码块或宿主文件路径概念**（如 `@ROOT/...`、`/Users/...`）。脚本应通过 `delta-cli sandbox write` 进入 sandbox 内部路径 `/workspace/...`。
+- **`skill_request` 里不要出现完整代码块或宿主文件路径概念**（如 `@ROOT/...`、`/Users/...`）。脚本应通过 `delta-cli sandbox write <id> --source <文件名>` 写入 sandbox 的 working-directory（`/workspace/{user_id}/{sandbox_id}/...`）。
 
 ## 本地 `result.json` 的内容约定