@delta-infra/cli 1.0.89 → 1.0.91

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 到最新版本 |

package/checksums.txt

@@ -1,5 +1,5 @@
-7d508465cf9cd3e646b5c6b40f7455e87d19d50220549ba99fc2cba8446e4620  delta-cli-darwin-amd64.tar.gz
-c37f4cd4dff81a202a2f9902ba44385a4f5d8117270ea07d2fa929c9a42fbbfb  delta-cli-darwin-arm64.tar.gz
-e8d891e90578a487e225621d682435b003fbfb681544f152dddd69eb76fcc95d  delta-cli-linux-amd64.tar.gz
-debd0241feb4a02c2a46054767f826a35d7abcd22f804bc134ec2df0ab5b85cd  delta-cli-linux-arm64.tar.gz
-c5274e69364a89293062b886e7cfb41934259c442180531d76c66855de18d16f  delta-cli-windows-amd64.zip
+3522e93c6d34f7c5c0a622731a2b5ab716245c4ca5905c1f9b874a7f50d7ac82  delta-cli-darwin-amd64.tar.gz
+e6a82316dbbca11c7130780fbe129b8ac02e68fe9a116724394660eb34a10c47  delta-cli-darwin-arm64.tar.gz
+01136105d040dea3ef3166488a92123c2e0ea579bceefc39b9e48df87dbf913e  delta-cli-linux-amd64.tar.gz
+f1b6c060eb09c14ee829f063a941663c7b096764e5b1c925f0f8902e26fa62d4  delta-cli-linux-arm64.tar.gz
+e3034b5a1442f480a630af37548b03d34c7179ac227a5ee6e223988ca5f9307f  delta-cli-windows-amd64.zip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delta-infra/cli",
-  "version": "1.0.89",
+  "version": "1.0.91",
   "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

@@ -47,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` → 仍运行
@@ -152,7 +152,7 @@ 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]` |
@@ -182,6 +182,7 @@ required_outputs:
      - `delta-cli sandbox recommend --cpu N --memory XGi [--gpu N]` — 资源配置推荐
 2. **创建**：`delta-cli sandbox create --image <img> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`。**返回的 JSON 信封中是 `data.sandbox_id`，不是 `data.id`；后续所有命令必须使用这个真实的 `sandbox_id`。**（创建后 sandbox 立即可用，无需额外连接）。**响应会回显请求的 `image`/`provider`/`resource`（服务端未返回的字段由 CLI 用请求值补齐，服务端返回值优先），可直接核对一遍资源配置，无需额外调 status。**（`provider` 请求值为 `auto` 时不回显，避免冒充实际 provider）。**同一次任务若已有 `sandbox_id`，禁止再次 create，必须优先复用。**
     - --max-life 指定 sandbox 最大存活时间（分钟），默认 30。长任务请调高，确保 sandbox 在命令执行期间不被回收。
+    - **`--gpu-mem`（单位 MiB）要匹配实际运行的模型**：模型参数量/精度越大所需显存越大，大模型塞进过小显存会直接 OOM。示例中的 8000（8GiB）只适配小模型，跑 7B/9B/13B 前先评估显存需求并适当调大。
     - `--no-auto-cleanup`：加此 flag 后该 sandbox **不会被自动清理**（服务端超时回收 + 本地周期 cleanup_stale 均跳过），只能通过显式 `sandbox kill`/`finish` 销毁。仅当任务确实需要跨越周期清理长期存活时才使用，任务结束后必须主动销毁，避免资源泄漏。
     - **禁止在 create 成功后反复调用 `sandbox status` 轮询**。`sandbox create` 返回时 sandbox 已经就绪，直接用它返回的 `data.sandbox_id` 执行 `write`/`run` 即可。多余的轮询会增加工具调用次数且没有任何收益。
 3. **写入代码/数据**：
@@ -192,14 +193,14 @@ required_outputs:
      - 支持嵌套目录，空目录也会被创建。
      - **写后验证（可选）**：`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` 字段为准）。脚本经 `sandbox write` 落盘后位于 working-directory，运行命令需用完整路径 `<working-directory>/<文件名>`（先 `sandbox working-directory <id>` 查询）。根据镜像中的运行时构造命令，常见示例（`<wd>` 为 working-directory）：
+    - **短任务（预计 ≤ 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 反向扫描提取，避免让大模型“读整段日志再摘要”。

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 <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 后端。）
+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 后端。**`--gpu-mem`（单位 MiB）要匹配实际运行的模型**：模型参数量越大所需显存越大，大模型塞进过小显存会 OOM，宜先评估模型显存需求再设置。）
 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
@@ -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

@@ -116,6 +116,8 @@ SKILL 会把它提取为 `result.json` 的 `summary`，并生成 `result_summary
   ```
 - skill 会把它提取为 `result.json` 的 `summary`，最终输出 `RESULT: exit_code=0, status=ok, cuda_available=True, generated_text=110, ...`。
 
+> **GPU 显存与模型匹配**：创建 sandbox 时的 `--gpu-mem`（单位 MiB）必须匹配实际运行的模型。模型参数量/精度越大，所需显存越大；把大模型塞进过小的 `--gpu-mem` 会直接 OOM。上面的示例用的是 `Qwen2.5-0.5B`（0.5B 小模型），**不要把它当作更大模型（如 7B/9B/13B）的显存参考**。跑较大模型前先评估其显存需求、适当调大 `--gpu-mem`，并建议先用小模型验证流程是否跑通。
+
 ## 注意事项
 
 - 尽量用自然语言描述任务，完整代码由 skill 内部处理。