@delta-infra/cli 1.0.14 → 1.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delta-infra/cli",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "Delta Sandbox CLI",
   "bin": {
     "delta-cli": "scripts/run.js"

package/skills/delta-sandbox/SKILL.md

@@ -30,7 +30,9 @@ metadata:
 2. **必须销毁**：每次 `sandbox create` 成功后，在当前任务的最终 `step_finish` 之前 **必须** 执行 `sandbox kill <id>` 或 `sandbox finish <id>` 销毁 sandbox。未销毁等价于任务失败。
 3. **异常时也必须销毁**：即使 sandbox 内命令失败、超时或报错，仍然 **必须** 执行 `sandbox kill <id>`。异常不是跳过销毁的理由。
 4. **不得依赖外部清理**：server 端 **没有** sandbox 的自动过期或 TTL 机制。不 kill → sandbox 永久占用 GPU 资源。
-5. **一条命令内完成**：从 `create` 到 `kill` 的完整生命周期必须在同一次执行中完成。不允许跨任务保留 sandbox。
+5. **同步任务一条命令内完成，后台任务可跨轮次**：
+   - 同步模式（`sandbox run`）：从 `create` 到 `kill` 的完整生命周期必须在同一次执行中完成。不允许跨任务保留。
+   - 后台模式（`sandbox run-bg`）：允许在当前执行中将 `sandbox_id` 和 `execution_id` 报告给用户，后续轮次通过 `sandbox status` + `sandbox logs` 获取结果。任务完成后仍需 `sandbox kill`。
 6. **禁止重复创建**：同一次任务中只允许存在一个活跃 sandbox。若命令失败需要重试，优先复用已创建的 `sandbox_id`；若确实需要重新创建，必须先 `sandbox kill <旧_sandbox_id>`，确认旧实例销毁后再执行新的 `sandbox create`。可用 `delta-cli sandbox list` 查询当前用户的活跃 sandbox，但 **禁止** 用 list 来绕过“同一次任务只保留一个 sandbox”的规则。
 
 ## 快速路由
@@ -53,7 +55,8 @@ metadata:
 ## 完整生命周期
 
 1. **查看可用镜像**：`delta-cli sandbox images` — 查询服务端支持的镜像列表（含标签、最低资源要求、支持 provider），根据用户需求匹配镜像
-2. **创建**：`delta-cli sandbox create --image <img> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000`（创建后 sandbox 立即可用，无需额外连接）。**同一次任务若已有 `sandbox_id`，禁止再次 create，必须优先复用。**
+2. **创建**：`delta-cli sandbox create --image <img> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`（创建后 sandbox 立即可用，无需额外连接）。**同一次任务若已有 `sandbox_id`，禁止再次 create，必须优先复用。**
+   - --max-life 指定 sandbox 最大存活时间（分钟），默认 30。长任务请调高，确保 sandbox 在命令执行期间不被回收。
    - 这是 `sandbox create` 支持的完整资源参数集合，不存在其它“更正确”的资源 flag，不要 invented 不存在的参数。
 3. **写入代码**：`delta-cli sandbox write <id> --path /workspace/train.py --data "..."`
 4. **运行**：`delta-cli sandbox run <id> --command "python /workspace/train.py" --timeout 3600`

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

@@ -6,7 +6,7 @@
 
 1. **查看可用镜像** `delta-cli sandbox images` — 查询服务端支持的镜像列表，根据用户的 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`（创建后立即可用，无需连接；这些是 `create` 全部资源参数，不要 invented 其它 flag）
+3. **创建** `delta-cli sandbox create --image <image> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`（创建后立即可用，无需连接；--max-life 指定 sandbox 最大存活时间（分钟），默认 30；这些是 `create` 全部资源参数，不要 invented 其它 flag）
 4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/train.py --data "..."`
 5. **运行命令** `delta-cli sandbox run <id> --command "python /workspace/train.py"`
    - `sandbox run` 是同步执行，返回结果里直接包含 `stdout`、`stderr`、`exit_code`，**不要**再调 `sandbox logs`
@@ -15,11 +15,23 @@
 
 ## 后台任务
 
-对于长时间运行的训练，才使用 `run-bg` + `logs`：
+对于长时间运行的训练（>5 分钟），使用 `run-bg` 在后台异步执行：
 
 ```bash
-delta-cli sandbox run-bg <id> --command "python train.py" --timeout 3600
+# 1. 启动后台命令（立即返回，不阻塞）
+delta-cli sandbox run-bg <id> --command "python train.py" --timeout 7200
+
+# ↑ 返回数据中包含 execution_id，请保存以便后续查询
+
+# 2. 轮询命令是否完成（可在后续 tool call 轮次执行）
 delta-cli sandbox logs <id> --execution-id <exec_id>
+# ↑ 如果返回 finished=false，说明命令仍在运行
+
+# 3. 全部完成后销毁 sandbox
+delta-cli sandbox kill <id>
 ```
 
-**注意**：`sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。
+**注意**：
+- `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。
+- `sandbox run-bg` 的 `--timeout` 传给服务端作为命令超时，HTTP 请求本身会快速返回；命令若超时会以非零退出码结束。
+- 后台命令可跨 tool call 轮次查询：保存 `sandbox_id` 和 `execution_id`，后续轮次通过 `sandbox status` / `sandbox logs` 获取结果。