@delta-infra/cli 1.0.17 → 1.0.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/skills/delta-sandbox/SKILL.md +22 -6
  3. package/skills/delta-sandbox/references/lifecycle.md +23 -10
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@delta-infra/cli",
3
- "version": "1.0.17",
3
+ "version": "1.0.19",
4
4
  "description": "Delta Sandbox CLI",
5
5
  "bin": {
6
6
  "delta-cli": "scripts/run.js"
package/skills/delta-sandbox/SKILL.md CHANGED
@@ -36,12 +36,23 @@ metadata:
36
36
  6. **禁止重复创建**：同一次任务中只允许存在一个活跃 sandbox。若命令失败需要重试，优先复用已创建的 `sandbox_id`；若确实需要重新创建，必须先 `sandbox kill <旧_sandbox_id>`，确认旧实例销毁后再执行新的 `sandbox create`。可用 `delta-cli sandbox list` 查询当前用户的活跃 sandbox，但 **禁止** 用 list 来绕过“同一次任务只保留一个 sandbox”的规则。
37
37
 
38
38
  7. **长任务必须后台执行**：预计执行时间超过 60 秒的任务（例如下载模型、训练、微调、长推理、大规模数据处理），**必须**使用 `delta-cli sandbox run-bg <id> --command "..." --timeout <秒>` 提交为后台任务，禁止使用同步的 `sandbox run`。
39
- - 命令末尾建议添加完成标记 `&& echo SANDBOX_BACKGROUND_DONE`，便于轮询时判断。
40
39
  - 轮询用 `delta-cli sandbox logs <id> --execution-id <exec_id>`，每 15-30 秒一次。
41
- - 完成判断：`content` 中出现 `SANDBOX_BACKGROUND_DONE` → 完成；`cursor` 在增长 → 仍在运行，继续等待。
42
- - 故障诊断：连续 3 次查询 `content` 和 `cursor` 无变化且距离提交超过 60 秒 → 用 `sandbox status <id>` 检查 sandbox 是否存活。如果 sandbox 正常但 logs 无输出，用 `sandbox run <id> --command "ps aux" --timeout 15` 在容器内检查进程状态。
40
+ - 完成判断（按优先级）：
41
+ a) `finished=true` + `exit_code=0` → 正常完成
42
+ b) `finished=true` + `exit_code!=0` → 命令执行失败，查看 stderr
43
+ c) `running=true` → 仍在运行，继续等待
44
+ - 也可用 `delta-cli sandbox status bg <id> --execution-id <exec_id>` 直接查询后台命令的运行状态和退出码。
45
+ - 故障诊断：连续 3 次 `running=true` 且 `content`/`cursor` 无变化且距离提交超过 60 秒 → 用 `sandbox status <id>` 检查 sandbox 是否存活。如果 sandbox 正常但 logs 无输出，用 `sandbox run <id> --command "ps aux" --timeout 15` 在容器内检查进程状态。
43
46
  - 后台任务成功后仍需按规则 2/3 销毁 sandbox。
44
47
 
48
+ 8. **写入文件禁止使用路径或 Shell 变量，仅允许文件名**：
49
+ - ❌ **禁止**：`--source "$WORKSPACE_ROOT/train.py"`、`--source "$(pwd)/train.py"`（Shell 展开路径 → 空文件或失败）
50
+ - ❌ **禁止**：`--data "大量代码..."`（Shell 转义问题）
51
+ - ✅ **正确**：`delta-cli sandbox write <id> --path /workspace/train.py --source train.py`（仅文件名）
52
+ - 少量配置（< 20 行）可用 `--data "..."`。`--mode 755` 可设置文件权限。
53
+
54
+ 9. **每个 `run-bg` 生成独立 `execution_id`**：每次调用 `sandbox run-bg` 都会返回一个唯一的 `execution_id`，多个后台任务之间通过它区分。务必保存每次返回的 `execution_id` 并与任务对应，后续通过 `sandbox logs <id> --execution-id <exec_id>` 分别查询各任务的结果。同步 `sandbox run` 无需 `execution_id`，结果直接返回。
55
+
45
56
  ## 快速路由
46
57
 
47
58
  | 用户目标 | 命令 |
@@ -54,6 +65,7 @@ metadata:
54
65
  | 同步运行命令 | `sandbox run <id> --command "..."` |
55
66
  | 后台运行命令 | `sandbox run-bg <id> --command "..."` |
56
67
  | 查看后台日志 | `sandbox logs <id> --execution-id <exec_id>`（仅用于 `run-bg`） |
68
+ | 查询命令状态 | `sandbox status bg <id> --execution-id <exec_id>` |
57
69
  | 读取文件 | `sandbox read <id> --path <path>` |
58
70
  | 写入文件 | `sandbox write <id> --path <path> --source <本地路径>`（推荐）|
59
71
  | 完成 sandbox | `sandbox finish <id> --results '{...}'` |
@@ -64,15 +76,18 @@ metadata:
64
76
  1. **选择镜像并查看可用镜像**：`delta-cli sandbox images` — 查询服务端支持的镜像列表，根据用户需求的编程语言和工具链匹配镜像。例如 `deltarouter/python:latest`（Python）、`node:20`（Node.js）、`golang:1.23`（Go），镜像决定了容器内可用的语言/运行时环境。
65
77
  2. **创建**：`delta-cli sandbox create --image <img> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`（创建后 sandbox 立即可用，无需额外连接）。**同一次任务若已有 `sandbox_id`，禁止再次 create，必须优先复用。**
66
78
  - --max-life 指定 sandbox 最大存活时间（分钟），默认 30。长任务请调高，确保 sandbox 在命令执行期间不被回收。
67
- - 这是 `sandbox create` 支持的完整资源参数集合，不存在其它“更正确”的资源 flag，不要 invented 不存在的参数。
68
- 3. **写入代码/数据**：`delta-cli sandbox write <id> --path /workspace/<filename> --source <本地路径>` 或 `--data "..."`。`--source` 让 CLI 自行读取本地文件，推荐用于长文件；`--data` 适用于少量内容。文件路径和扩展名由镜像中的运行时决定。
79
+ - 这是 `sandbox create` 支持的完整资源参数集合，不存在其它“更正确”的资源 flag，不要发明不存在的参数。
80
+ 3. **写入代码/数据**：`delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — **必须**使用相对路径（如 `--source train.py`），**禁止**使用 `"$WORKSPACE_ROOT/train.py"` 或 `$(pwd)/train.py` 等 Shell 变量路径。`--source` 让 CLI 自行读取本地文件，不会经过 Shell 展开，是最安全的方式。少量配置（<20 行）可用 `--data "..."`。文件路径和扩展名由镜像中的运行时决定。
69
81
  4. **运行命令**：
70
82
  - **短任务（预计 ≤ 60 秒）**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，结果（`stdout` / `stderr` / `exit_code`）直接返回，**不要**再调用 `sandbox logs`。根据镜像中的运行时构造命令，常见示例：
71
83
  - Python：`python /workspace/train.py`
72
84
  - Node.js：`node /workspace/app.js`
73
85
  - Go：`go run /workspace/main.go`
74
86
  - Shell：`bash /workspace/run.sh`
75
- - **长任务（预计 > 60 秒，如下载模型、训练、编译、大规模数据处理）**：`delta-cli sandbox run-bg <id> --command "<命令> && echo SANDBOX_BACKGROUND_DONE" --timeout <秒>` 提交后台任务，获得 `execution_id` 后循环调用 `delta-cli sandbox logs <id> --execution-id <execution_id>` 轮询：当 `logs.data.content` 中出现 `SANDBOX_BACKGROUND_DONE` 时视为完成。禁止对长任务使用同步 `sandbox run`
87
+ - **长任务（预计 > 60 秒，如下载模型、训练、编译、大规模数据处理）**：`delta-cli sandbox run-bg <id> --command "<命令>" --timeout <秒>` 提交后台任务，获得 `execution_id` 后通过以下命令轮询：
88
+ - `delta-cli sandbox logs <id> --execution-id <execution_id>` — 返回 `content`、`cursor`、`running`、`finished`、`exit_code`。当 `finished=true` 时认为完成。
89
+ - `delta-cli sandbox status bg <id> --execution-id <execution_id>` — 返回 `running`、`finished`、`exit_code`。
90
+ 禁止对长任务使用同步 `sandbox run`
76
91
  5. **读取结果**：`delta-cli sandbox read <id> --path /workspace/result.json`
77
92
  6. **销毁**：`delta-cli sandbox kill <id>`（如需保存结果，用 `sandbox finish --results '{...}'` 替代 kill，finish 会自动销毁 sandbox）
78
93
 
@@ -89,3 +104,4 @@ metadata:
89
104
  | `error.type: api`（5xx） | 服务端错误，检查 API 服务状态 |
90
105
  | 命令执行失败（exit_code ≠ 0） | 查看 `run` 返回的 stdout/stderr |
91
106
  | 命令超时 | 增加 `--timeout` 或使用 `run-bg` |
107
+ | `error.type: internal` | 客户端内部错误，检查 delta-cli 版本或联系维护者 |
package/skills/delta-sandbox/references/lifecycle.md CHANGED
@@ -6,21 +6,22 @@
6
6
 
7
7
  1. **查看可用镜像** `delta-cli sandbox images` — 查询服务端支持的镜像列表。镜像决定了容器内的语言运行时（Python / Node.js / Go / Java / Rust 等），根据用户的技术栈和 GPU/CPU 需求匹配。
8
8
  2. **列出现有 sandbox（可选）** `delta-cli sandbox list` — 查看当前用户已创建的活跃 sandbox，避免重复创建
9
- 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）
10
- 4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/<filename> --source <本地路径>` — 将本地文件直接写入 sandbox（推荐方式，避免 Shell 转义问题）。也可用 `--data "..."` 直接写入内联内容。文件路径和扩展名由镜像中的运行时决定。
9
+ 3. **创建** `delta-cli sandbox create --image <image> --cpu 4 --memory 16Gi --gpu 1 --gpu-mem 8000 --max-life 120`（创建后立即可用，无需连接；--max-life 指定 sandbox 最大存活时间（分钟），默认 30；这些是 `create` 全部资源参数，不要发明其它 flag。`--provider autodl` 可指定使用 AutoDL 后端。）
10
+ 4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/<filename> --source <文件名>` — 将本地文件直接写入 sandbox。**必须**使用相对路径（如 `--source infer.py`），禁止使用 `"$WORKSPACE_ROOT/<filename>"`。也可用 `--data "..."` 写入少量内联内容，`--mode 755` 可设置文件权限。文件路径和扩展名由镜像中的运行时决定。
11
11
  5. **运行命令** `delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` — 根据镜像中的运行时构造命令，常见示例：`python /workspace/train.py`（Python）、`node /workspace/app.js`（Node.js）、`go run /workspace/main.go`（Go）、`bash /workspace/run.sh`（Shell）
12
12
  - `sandbox run` 是同步执行，返回结果里直接包含 `stdout`、`stderr`、`exit_code`，**不要**再调 `sandbox logs`
13
13
  6. **读取结果** `delta-cli sandbox read <id> --path /workspace/result.json`
14
14
  7. **销毁** `delta-cli sandbox kill <id>`（如需保存结果用 finish，finish 会自动销毁）
15
15
 
16
+ > **注意**：server 端没有 sandbox 的自动过期或 TTL 机制，不 kill 会永久占用 GPU 资源。请务必在任务结束后销毁。
17
+
16
18
  ## 后台任务
17
19
 
18
- 对于长时间运行的任务（>5 分钟，如训练、编译、数据处理），使用 `run-bg` 在后台异步执行：
20
+ 对于长时间运行的任务（>60 秒，如训练、编译、数据处理），使用 `run-bg` 在后台异步执行：
19
21
 
20
22
  ```bash
21
23
  # 1. 启动后台命令（立即返回，不阻塞）
22
- # 命令末尾加 echo SANDBOX_BACKGROUND_DONE 标记完成
23
- delta-cli sandbox run-bg <id> --command "<命令> && echo SANDBOX_BACKGROUND_DONE" --timeout 7200
24
+ # delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
24
25
 
25
26
  # ↑ 返回数据中包含 execution_id，请保存以便后续查询
26
27
 
@@ -33,14 +34,26 @@ delta-cli sandbox kill <id>
33
34
 
34
35
  ### 轮询判断逻辑
35
36
 
36
- `sandbox logs` 返回的数据结构为 `{"ok":true,"data":{"logs":"{\"data\":{\"content\":\"...\",\"cursor\":N}}"}}`。
37
+ `sandbox logs` 返回的数据结构为：
38
+
39
+ ```json
40
+ {"ok":true,"data":{"content":"...","cursor":5,"running":false,"finished":true,"exit_code":0}}
41
+ ```
42
+
43
+ 字段说明：
44
+ - `content` — 命令的标准输出
45
+ - `cursor` — 输出行数计数器
46
+ - `running` — 命令是否仍在运行
47
+ - `finished` — 命令是否已完成（`finished = not running`）
48
+ - `exit_code` — 退出码（完成后才有值，运行中为 null）
37
49
 
38
50
  判断任务状态的规则（按优先顺序）：
39
51
 
40
- 1. **`content` 中出现 `SANDBOX_BACKGROUND_DONE`** → 任务完成，可以读取结果并销毁 sandbox
41
- 2. **`cursor` 在增长** → 任务正在输出，仍在运行，继续等待（建议每 15-30 秒查询一次）
42
- 3. **连续 3 次 `content` 和 `cursor` 都没有变化，且距离提交已超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活
43
- 4. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
52
+ 1. **`finished=true` + `exit_code=0`** → 正常完成，可以读取结果并销毁 sandbox
53
+ 2. **`finished=true` + `exit_code≠0`** → 命令执行失败，查看 stderr/error 信息
54
+ 3. **`running=true`** → 任务仍在运行，继续等待（建议每 15-30 秒查询一次）
55
+ 5. **连续 3 次 `running=true` 且 `content`/`cursor` 无变化且距离提交超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活；也可用 `sandbox status bg <id> --execution-id <exec_id>` 查后台命令状态
56
+ 6. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
44
57
 
45
58
  **注意**：
46
59
  - `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。