@delta-infra/cli 1.0.16 → 1.0.17

package/README.md

@@ -167,7 +167,7 @@ delta-cli sandbox kill <sandbox_id>
 | `delta-cli sandbox run-bg <id> --command "..."` | 后台运行命令 |
 | `delta-cli sandbox logs <id> --execution-id <eid>` | 查看后台日志 |
 | `delta-cli sandbox read <id> --path <path>` | 读取容器内文件 |
-| `delta-cli sandbox write <id> --path <path> --data "..."` | 写入文件 |
+| `delta-cli sandbox write <id> --path <path> --source <source_path>` | 写入文件 |
 | `delta-cli sandbox finish <id> --results '{...}'` | 标记完成并返回结果 |
 | `delta-cli sandbox kill <id>` | 销毁 sandbox |
 

package/package.json

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

package/skills/delta-sandbox/SKILL.md

@@ -35,7 +35,12 @@ metadata:
    - 后台模式（`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”的规则。
 
-7. **长任务必须后台执行**：预计执行时间超过 60 秒的任务（例如下载模型、训练、微调、长推理、大规模数据处理），**必须**使用 `delta-cli sandbox run-bg <id> --command "..." --timeout <秒>` 提交为后台任务，并通过 `delta-cli sandbox logs <id> --execution-id <exec_id>` 轮询结果。禁止对这类任务使用同步的 `sandbox run`。`run-bg` 会立即返回 `execution_id`；解析 `logs` 输出中的 `content`（并配合使用完成标记 `&& echo SANDBOX_BACKGROUND_DONE`）判断任务是否结束，建议每 15-30 秒轮询一次。后台任务成功后仍需按规则 2/3 销毁 sandbox。
+7. **长任务必须后台执行**：预计执行时间超过 60 秒的任务（例如下载模型、训练、微调、长推理、大规模数据处理），**必须**使用 `delta-cli sandbox run-bg <id> --command "..." --timeout <秒>` 提交为后台任务，禁止使用同步的 `sandbox run`。
+   - 命令末尾建议添加完成标记 `&& echo SANDBOX_BACKGROUND_DONE`，便于轮询时判断。
+   - 轮询用 `delta-cli sandbox logs <id> --execution-id <exec_id>`，每 15-30 秒一次。
+   - 完成判断：`content` 中出现 `SANDBOX_BACKGROUND_DONE` → 完成；`cursor` 在增长 → 仍在运行，继续等待。
+   - 故障诊断：连续 3 次查询 `content` 和 `cursor` 无变化且距离提交超过 60 秒 → 用 `sandbox status <id>` 检查 sandbox 是否存活。如果 sandbox 正常但 logs 无输出，用 `sandbox run <id> --command "ps aux" --timeout 15` 在容器内检查进程状态。
+   - 后台任务成功后仍需按规则 2/3 销毁 sandbox。
 
 ## 快速路由
 
@@ -50,7 +55,7 @@ metadata:
 | 后台运行命令 | `sandbox run-bg <id> --command "..."` |
 | 查看后台日志 | `sandbox logs <id> --execution-id <exec_id>`（仅用于 `run-bg`） |
 | 读取文件 | `sandbox read <id> --path <path>` |
-| 写入文件 | `sandbox write <id> --path <path> --data "..."` |
+| 写入文件 | `sandbox write <id> --path <path> --source <本地路径>`（推荐）|
 | 完成 sandbox | `sandbox finish <id> --results '{...}'` |
 | 销毁 sandbox | `sandbox kill <id>` |
 
@@ -60,7 +65,7 @@ metadata:
 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/<filename> --data "..."` 将源代码、脚本或数据文件写入 sandbox。文件路径和扩展名由镜像中的运行时决定。
+3. **写入代码/数据**：`delta-cli sandbox write <id> --path /workspace/<filename> --source <本地路径>` 或 `--data "..."`。`--source` 让 CLI 自行读取本地文件，推荐用于长文件；`--data` 适用于少量内容。文件路径和扩展名由镜像中的运行时决定。
 4. **运行命令**：
    - **短任务（预计 ≤ 60 秒）**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，结果（`stdout` / `stderr` / `exit_code`）直接返回，**不要**再调用 `sandbox logs`。根据镜像中的运行时构造命令，常见示例：
      - Python：`python /workspace/train.py`

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

@@ -7,7 +7,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；这些是 `create` 全部资源参数，不要 invented 其它 flag）
-4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/<filename> --data "..."` — 将源代码、脚本或数据文件写入 sandbox。文件路径和扩展名由镜像中的运行时决定。
+4. **写入代码/数据** `delta-cli sandbox write <id> --path /workspace/<filename> --source <本地路径>` — 将本地文件直接写入 sandbox（推荐方式，避免 Shell 转义问题）。也可用 `--data "..."` 直接写入内联内容。文件路径和扩展名由镜像中的运行时决定。
 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）
    - `sandbox run` 是同步执行，返回结果里直接包含 `stdout`、`stderr`、`exit_code`，**不要**再调 `sandbox logs`
 6. **读取结果** `delta-cli sandbox read <id> --path /workspace/result.json`
@@ -19,18 +19,29 @@
 
 ```bash
 # 1. 启动后台命令（立即返回，不阻塞）
-delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
+# 命令末尾加 echo SANDBOX_BACKGROUND_DONE 标记完成
+delta-cli sandbox run-bg <id> --command "<命令> && echo SANDBOX_BACKGROUND_DONE" --timeout 7200
 
 # ↑ 返回数据中包含 execution_id，请保存以便后续查询
 
-# 2. 轮询命令是否完成（可在后续 tool call 轮次执行）
+# 2. 轮询日志判断任务状态（可在后续 tool call 轮次执行）
 delta-cli sandbox logs <id> --execution-id <exec_id>
-# ↑ 如果返回 finished=false，说明命令仍在运行
 
 # 3. 全部完成后销毁 sandbox
 delta-cli sandbox kill <id>
 ```
 
+### 轮询判断逻辑
+
+`sandbox logs` 返回的数据结构为 `{"ok":true,"data":{"logs":"{\"data\":{\"content\":\"...\",\"cursor\":N}}"}}`。
+
+判断任务状态的规则（按优先顺序）：
+
+1. **`content` 中出现 `SANDBOX_BACKGROUND_DONE`** → 任务完成，可以读取结果并销毁 sandbox
+2. **`cursor` 在增长** → 任务正在输出，仍在运行，继续等待（建议每 15-30 秒查询一次）
+3. **连续 3 次 `content` 和 `cursor` 都没有变化，且距离提交已超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活
+4. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
+
 **注意**：
 - `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。
 - `sandbox run-bg` 的 `--timeout` 传给服务端作为命令超时，HTTP 请求本身会快速返回；命令若超时会以非零退出码结束。