@delta-infra/cli 1.0.96 → 1.0.97

package/skills/delta-sandbox/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Delta Sandbox 工作站"
-  short_description: "通过 Delta CLI 安全创建、运行并销毁隔离计算工作站"
-  default_prompt: "使用 $delta-sandbox 在隔离工作站中完成这项计算并返回结果。"
+interface:
+  display_name: "Delta Sandbox 工作站"
+  short_description: "通过 Delta CLI 安全创建、运行并销毁隔离计算工作站"
+  default_prompt: "使用 $delta-sandbox 在隔离工作站中完成这项计算并返回结果。"

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

@@ -1,58 +1,56 @@
-> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
-
-# 命令速查表
-
-## 发现
-
-| 命令 | 说明 |
-|------|------|
-| `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]` | 获取资源配置推荐 |
-
-## 生命周期
-
-| 命令 | 说明 |
-|------|------|
-| `sandbox create --image <img> [--cpu N --memory XGi --gpu N --gpu-mem N --max-life M --no-auto-cleanup --provider P]` | 创建 sandbox 容器（`--no-auto-cleanup` 不被自动清理，仅显式 kill/finish 可销毁）；**响应回显请求的 `image`/`provider`/`resource`**（服务端未返回字段用请求值补齐，服务端值优先；`provider=auto` 不回显） |
-| `sandbox connect <id>` | 连接已有 sandbox |
-| `sandbox status <id>` | 查看 sandbox 状态（running / done） |
-| `sandbox finish <id> [--results '{...}']` | 保存结果后自动销毁 |
-| `sandbox kill <id>` | 直接销毁 sandbox（不保存结果） |
-
-## 命令执行
-
-| 命令 | 说明 |
-|------|------|
-| `sandbox run <id> --command "..." [--timeout N] [--summary/--no-summary] [--artifacts]` | 同步运行命令（SSE 实时流，原始 `data:` 帧逐帧透传到 stdout；**成功无末尾信封**；`complete` 帧由 CLI 补全 `exit_code`/`execution_id`/`log_file`/`stdout`/`stderr`/`result_summary`；**命令非零退出或报错时追加 `error.type: command_failed` 信封并以非零码退出**，信封 `message` 附 stderr 尾部，`type:"error"` 帧 message 亦附 best-effort stderr 尾部）；`--summary`/`--artifacts` 仅在旧服务器回退路径（无 SSE 端点时输出 `CommandResult` 信封）生效 |
-| `sandbox run-bg <id> --command "..." [--timeout N] [--wait] [--summary/--no-summary] [--artifacts]` | 后台运行命令；不加 `--wait` 立即返回 `{execution_id, sandbox_id}`；加 `--wait` 通过 SSE 实时流跟随到 `complete`（原始 `data:` 帧透传到 stdout；`complete` 帧由 CLI 补全 `log_file`/`stdout`/`stderr`/`result_summary`；**命令失败时追加 `command_failed` 信封并非零退出**，信封 `message` 附 stderr 尾部；超时则追加 `finished=false` 快照信封）；`--summary`/`--artifacts` 仅在旧服务器回退路径生效 |
-| `sandbox logs <id> --execution-id <eid> [--tail N --grep <pattern> --context N] [--stream]` | 获取后台命令日志；**默认返回 `stdout_tail`（末尾 800 字节）+ `stderr_tail`（末尾 200 字节）+ `stderr_size` + `cursor`**，总计约 1KB，避免上下文爆炸；`--stream` 走 `/logs/stream` SSE 实时跟随，原始 `data:` 帧透传到 stdout 直到 `complete`（complete 帧由 CLI 补全 `stdout`/`stderr`/`log_file`/`result_summary`，无末尾信封）；`--tail N` 同时作用于 stdout 和 stderr（各取尾 N 行）；`--grep <pattern>` 同时过滤 stdout 和 stderr（正则）；`--context N` 提供 grep 匹配行前后 N 行上下文（同时用于 stdout 和 stderr）；**`cursor` 字段无 `omitempty`，0 也常驻响应**；快照含 `last_updated`（SSE 路径由 CLI 填，服务端快照路径待服务端补齐）。 |
-| `sandbox cancel <id> --execution-id <eid>` | 中断正在运行的后台命令 |
-
-## 文件操作
-
-| 命令 | 说明 |
-|------|------|
-| `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 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） |
-| `sandbox mv <id> --entry <source=dest> [--entry ...]` | 移动或重命名文件 |
-| `sandbox replace <id> --path <path> --old <文本> --new <文本> [--regex] [--ignore-case]` | 替换文件内容 |
-| `sandbox chmod <id> --path <path> --mode <八进制>` | 修改文件权限 |
-| `sandbox rm <id> --path <path> [--path ...]` | 删除文件 |
-| `sandbox mkdir <id> --path <路径> [--path ...]` | 创建目录（mkdir -p） |
-| `sandbox search <id> --path <根目录> --pattern <glob>` | 搜索文件 |
-
-## 注意事项
-
-- `list` ≠ `ls`：`sandbox list` 列沙箱实例，`sandbox ls <id>` 列沙箱内目录
-- 写文件后返回的 `size` 是 stat 验证后的实际磁盘字节数
-- 读文件返回 `size`（磁盘字节，来自 stat）和 `content_length`（内存字符数），对比可判断编码偏差
-- 读不存在的文件会返回 error，不会静默返回空内容
+> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
+
+# 命令速查表
+
+## 发现
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox list` | 列出当前用户创建的活跃 sandbox（与 `ls` 不同：这是列 **沙箱实例**） |
+| `sandbox providers` | 查看可用的计算后端（opensandbox / autodl） |
+| `sandbox images` | 查看可用镜像列表 |
+| `sandbox recommend --cpu N --memory XGi [--gpu N] [--gpu-mem N]` | 获取资源配置推荐 |
+
+## 生命周期
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox create --image <img> [--cpu N --memory XGi --gpu N --gpu-mem N --max-life M --provider P]` | 创建 sandbox 容器 |
+| `sandbox connect <id>` | 连接已有 sandbox |
+| `sandbox status <id>` | 查看 sandbox 状态（running / done） |
+| `sandbox finish <id> [--results '{...}']` | 保存结果后自动销毁 |
+| `sandbox kill <id>` | 直接销毁 sandbox（不保存结果） |
+
+## 命令执行
+
+| 命令 | 说明 |
+|------|------|
+| `sandbox run <id> --command "..." [--timeout N] [--summary/--no-summary] [--artifacts]` | 同步运行命令；默认 `--summary` 开启，返回 JSON 中 `summary` 字段已含 stdout 末尾 JSON 提取结果；`--artifacts` 附带 workspace 产物清单 |
+| `sandbox run-bg <id> --command "..." [--timeout N] [--wait] [--summary/--no-summary] [--artifacts]` | 后台运行命令；不加 `--wait` 立即返回 `{execution_id, sandbox_id}`；加 `--wait` 等待完成返回含 `summary` 的完整结果 |
+| `sandbox logs <id> --execution-id <eid> [--tail N --grep <pattern> --context N]` | 获取后台命令日志；**默认返回 `stdout_tail`（末尾 800 字节）+ `stderr_tail`（末尾 200 字节）+ `stderr_size` + `cursor`**，总计约 1KB，避免上下文爆炸；`--tail N` 同时作用于 stdout 和 stderr（各取尾 N 行）；`--grep <pattern>` 同时过滤 stdout 和 stderr（正则）；`--context N` 提供 grep 匹配行前后 N 行上下文（同时用于 stdout 和 stderr）；**`cursor` 字段无 `omitempty`，0 也常驻响应**。 |
+| `sandbox cancel <id> --execution-id <eid>` | 中断正在运行的后台命令 |
+
+## 文件操作
+
+| 命令 | 说明 |
+|------|------|
+| `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 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） |
+| `sandbox mv <id> --entry <source=dest> [--entry ...]` | 移动或重命名文件 |
+| `sandbox replace <id> --path <path> --old <文本> --new <文本> [--regex] [--ignore-case]` | 替换文件内容 |
+| `sandbox chmod <id> --path <path> --mode <八进制>` | 修改文件权限 |
+| `sandbox rm <id> --path <path> [--path ...]` | 删除文件 |
+| `sandbox mkdir <id> --path <路径> [--path ...]` | 创建目录（mkdir -p） |
+| `sandbox search <id> --path <根目录> --pattern <glob>` | 搜索文件 |
+
+## 注意事项
+
+- `list` ≠ `ls`：`sandbox list` 列沙箱实例，`sandbox ls <id>` 列沙箱内目录
+- 写文件后返回的 `size` 是 stat 验证后的实际磁盘字节数
+- 读文件返回 `size`（磁盘字节，来自 stat）和 `content_length`（内存字符数），对比可判断编码偏差
+- 读不存在的文件会返回 error，不会静默返回空内容

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

@@ -1,98 +1,92 @@
-> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
-
-# Delta Sandbox 生命周期
-
-## 完整流程
-
-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 后端。**`--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
-   - **长任务 >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 <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 资源。请务必在任务结束后销毁。
-
-## 后台任务
-
-对于长时间运行的任务（>60 秒，如训练、编译、数据处理），使用 `run-bg` 在后台异步执行：
-
-### 方式一（推荐）：`--wait` 一次性等待完成
-
-```bash
-delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200 --wait
-```
-CLI 通过 SSE 实时流（`/logs/stream`）跟随输出，把原始 SSE 帧（`data: {...}`）**逐帧透传到 stdout**，收到 `complete` 帧即命令结束。**CLI 会在 complete 帧里补全字段**：除服务端给的 `exit_code`/`execution_id`/`error` 外，还注入流内累计的 `stdout`/`stderr`、兜底恢复的 `log_file`，以及检测到的末尾 JSON `result_summary`（stdout 末尾 50 行内若有合法 JSON 对象）。命令非零退出或报错时，CLI **追加一个 `error.type: command_failed` 信封并以非零码退出**（进程退出码 8），便于 `&&` 链和 agent 分支；成功则不追加信封。只消耗 **1 次 tool call**，适合不关心中间进度的场景。
-
-> `--wait` 的 SSE 路径 **complete 帧直接带 `result_summary`**（末尾 JSON 检测到即附上），无需再 `sandbox read <id> --path <log_file>` 反向扫描。仅当末尾没有合法 JSON 时才需手动读 log_file。`--summary`/`--artifacts` 富化（含 hints）仍仅旧服务器回退路径生效。
-
-> **输出契约（SSE 路径）**：`run-bg --wait` 命令成功时 stdout 只有原始 SSE 帧，**没有末尾信封**；命令失败时在 complete 帧后追加 `{"ok":false,"error":{"type":"command_failed",...}}` 信封；`--timeout` 内未结束则追加一个 `finished=false` 的 `CommandLogsResult` 快照信封；旧服务器（无 `/logs/stream` 端点）回退到 5s 轮询并输出 `CommandResult` 信封（`finished` 键始终存在，`finished=true` 时带 `result_summary`/`hints` 富化）。
-
-### 方式二：手动轮询（需要看实时输出时）
-
-```bash
-# 1. 启动后台命令
-delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
-# ↑ 返回 execution_id
-
-# 2a. 实时跟随（SSE，推荐）：
-delta-cli sandbox logs <id> --execution-id <exec_id> --stream
-# ↑ 原始 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>
-```
-
-### 轮询判断逻辑
-
-`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_logs/delta-result-{sandbox_id}-{execution_id}.json"}}
-```
-
-字段说明：
-- `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 端计算）
-- `stderr_size` — 原始 stderr 字节数（CLI 端计算）
-- `cursor` — 服务端 stderr 行计数器；**该字段无 `omitempty`，永远出现在响应中**（即使为 0）。`cursor=0` 通常意味着服务端从 provider 还没读到任何 stderr 行；**仅凭 cursor 判断停滞不可靠**（纯 stdout 或静默任务 cursor 恒为 0），停滞检测应以 `last_updated` 为主
-- `last_updated` — 最近活动时间（RFC3339）。SSE 流式路径由 CLI 填最后 data 帧到达时间；快照轮询路径由服务端填（当前服务端可能缺省），缺失时判断停滞退化用 `cursor`/`stdout_tail` 变化
-- `running` — 命令是否仍在运行
-- `finished` — 命令是否已完成（`finished = not running`）
-- `exit_code` — 退出码（完成后才有值，运行中字段省略）
-- `log_file` — 仅 `finished=true` 时出现，是 run envelope 日志文件路径（含完整 stdout + stderr + exit_code + finished + command + error），需读它用 `delta-cli sandbox read <id> --path <log_file>`；SSE 路径下 CLI 已在 complete 帧里兜底补全该字段
-
-**stdout 路径说明**：`sandbox logs` 默认返回 stdout 末尾 800 字节（`stdout_tail`）提供实时中间进度预览，完整 stdout 仍在命令结束时被写入沙箱内的 `log_file`，需全文时用 `sandbox read` 读。SSE 路径下 CLI 已在 complete 帧里带 `stdout`（全文）与 `result_summary`（末尾 JSON 检测到即附上），`--summary` 富化（含 hints）仅旧服务器回退路径生效。
-
-要用 `--tail/--grep/--context` 自定义切片：传任意一个 flag 时，CLI 会把过滤后的 stdout 和 stderr 分别写回 `stdout`/`stderr` 字段并更新 `stdout_size`/`stderr_size`；不传则保持 `stdout=""` + `stdout_tail` 末尾 800 字节预览 + `stderr=""` + `stderr_tail` 末尾 200 字节预览（总计约 1KB）。
-
-```bash
-# 看最后 50 行 stdout 和 stderr
-delta-cli sandbox logs <id> --execution-id <eid> --tail 50
-# 过滤 ERROR/warning 行（同时作用于 stdout 和 stderr）
-delta-cli sandbox logs <id> --execution-id <eid> --grep "ERROR|warning" --context 2
-```
-
-判断任务状态的规则（按优先顺序）：
-
-1. **`finished=true` + `exit_code=0`** → 正常完成，可以读取结果并销毁 sandbox
-2. **`finished=true` + `exit_code≠0`** → 命令执行失败，查看 stderr/error 信息
-3. **`running=true`** → 任务仍在运行，继续等待（建议每 15-30 秒查询一次）
-4. **连续 3 次 `running=true` 且输出无变化且距离提交超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活。判断「输出无变化」：快照里有 `last_updated` 时，直接比较它与当前时间是否持续滞后；缺 `last_updated` 时才退化为 `stderr_tail`/`cursor` 无变化（注意 `cursor` 只反映 stderr 行数，纯 stdout 任务会恒为 0，勿据此误判挂起）
-5. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
-
-**注意**：
-- `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。
-- `sandbox run-bg` 不加 `--wait` 时，HTTP 请求本身会快速返回 `{execution_id, sandbox_id}`；命令若超时会以非零退出码结束，需后续通过 `logs` 拿 `exit_code`。
-- `sandbox run-bg --wait` 模式下，`--timeout` **同时**充当服务端命令执行超时和客户端等待 deadline（默认 300s）；CLI 通过 SSE 实时流（`/logs/stream`）跟随，原始 `data:` 帧透传到 stdout，收到 `complete` 即结束（无末尾信封），超时则追加 `finished=false` 快照信封；初始 `/run-background` POST 有独立的 60s HTTP timeout。
-- 后台命令可跨 tool call 轮次查询：保存 `sandbox_id` 和 `execution_id`，后续轮次通过 `sandbox status` / `sandbox logs` 获取结果。
+> **前置条件：** 先阅读 [`../delta-shared/SKILL.md`](../delta-shared/SKILL.md) 了解认证、配置和通用错误处理。
+
+# Delta Sandbox 生命周期
+
+## 完整流程
+
+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` 全部资源参数，不要发明其它 flag。`--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）
+   - **短任务 ≤60s**：`delta-cli sandbox run <id> --command "<命令>" --timeout <秒>` 同步执行，返回 `stdout`/`stderr`/`exit_code` (默认带 --summary，返回 JSON data.result_summary 已含 stdout 末尾 JSON 提取结果)
+   - **长任务 >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 而非空内容。
+7. **销毁** `delta-cli sandbox kill <id>`（如需保存结果用 finish，finish 会自动销毁）
+
+> **注意**：server 端没有 sandbox 的自动过期或 TTL 机制，不 kill 会永久占用 GPU 资源。请务必在任务结束后销毁。
+
+## 后台任务
+
+对于长时间运行的任务（>60 秒，如训练、编译、数据处理），使用 `run-bg` 在后台异步执行：
+
+### 方式一（推荐）：`--wait` 一次性等待完成
+
+```bash
+delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200 --wait
+```
+CLI 内部每 5 秒轮询一次，`finished=true` 时返回，结果中包含 `execution_id`。只消耗 **1 次 tool call**，适合不关心中间进度的场景。
+
+> `--wait` 默认带 `--summary`，返回的 JSON `data.result_summary` 字段已包含 stdout 末尾结构化 JSON 的提取结果。常用场景无需再调 `sandbox read` 二次解析 log_file。
+
+> ⚠️ **返回类型不对称**：`finished=true` 时返回 `CommandResult` 信封（含 `execution_id, sandbox_id, finished, exit_code, stderr_tail, stderr_size, log_file, result_summary, hints, error`）；若轮询 deadline 到了仍未 `finished=true`（即 `--timeout` 超时），CLI 会返回 `CommandLogsResult` 信封（**字段集合不同**：含 `cursor, running, finished, exit_code, stderr_tail, stderr_size, log_file?` 但**没有 `result_summary` / `hints` / `sandbox_id`**）。调用方解析 `run-bg --wait` 返回时应兼容两种 schema。从 `execution_id` 是否存在可粗略区分，更准确的信号是 `result_summary` 字段是否存在。
+
+### 方式二：手动轮询（需要看实时输出时）
+
+```bash
+# 1. 启动后台命令
+delta-cli sandbox run-bg <id> --command "<命令>" --timeout 7200
+# ↑ 返回 execution_id
+
+# 2. 手动轮询进度（可用 --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?}
+
+# 3. 完成后销毁
+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":"/tmp/delta-result-...json"}}
+```
+
+字段说明：
+- `sandbox_id` / `execution_id` — 与请求一致
+- `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 端计算）
+- `stderr_size` — 原始 stderr 字节数（CLI 端计算）
+- `cursor` — 服务端 stderr 行计数器；**该字段无 `omitempty`，永远出现在响应中**（即使为 0）。`cursor=0` 通常意味着服务端从 provider 还没读到任何 stderr 行
+- `running` — 命令是否仍在运行
+- `finished` — 命令是否已完成（`finished = not running`）
+- `exit_code` — 退出码（完成后才有值，运行中字段省略）
+- `log_file` — 仅 `finished=true` 时出现，是 run envelope 日志文件路径（含完整 stdout + stderr + exit_code + finished + command + error），需读它用 `delta-cli sandbox read <id> --path <log_file>`
+
+**stdout 路径说明**：`sandbox logs` 默认返回 stdout 末尾 800 字节（`stdout_tail`）提供实时中间进度预览，完整 stdout 仍在命令结束时被写入沙箱内的 `log_file`，需全文时用 `sandbox read` 读。CLI `run-bg --wait` 完成后默认开启 `--summary`，会自动 reverse-scan stdout 末尾 JSON 填入 `data.result_summary`，常用场景无需手动读 `log_file`。
+
+要用 `--tail/--grep/--context` 自定义切片：传任意一个 flag 时，CLI 会把过滤后的 stdout 和 stderr 分别写回 `stdout`/`stderr` 字段并更新 `stdout_size`/`stderr_size`；不传则保持 `stdout=""` + `stdout_tail` 末尾 800 字节预览 + `stderr=""` + `stderr_tail` 末尾 200 字节预览（总计约 1KB）。
+
+```bash
+# 看最后 50 行 stdout 和 stderr
+delta-cli sandbox logs <id> --execution-id <eid> --tail 50
+# 过滤 ERROR/warning 行（同时作用于 stdout 和 stderr）
+delta-cli sandbox logs <id> --execution-id <eid> --grep "ERROR|warning" --context 2
+```
+
+判断任务状态的规则（按优先顺序）：
+
+1. **`finished=true` + `exit_code=0`** → 正常完成，可以读取结果并销毁 sandbox
+2. **`finished=true` + `exit_code≠0`** → 命令执行失败，查看 stderr/error 信息
+3. **`running=true`** → 任务仍在运行，继续等待（建议每 15-30 秒查询一次）
+4. **连续 3 次 `running=true` 且 `stderr_tail`/`cursor` 无变化且距离提交超过 60 秒** → 任务可能挂起或无输出，用 `sandbox status <id>` 检查 sandbox 是否存活
+5. **`sandbox status` 返回正常但 logs 仍然无变化** → 用 `sandbox run <id> --command "ps aux | grep <进程名>" --timeout 15` 在容器内检查命令是否还在运行
+
+**注意**：
+- `sandbox logs` 只应配合 `sandbox run-bg` 使用；同步 `sandbox run` 的结果直接返回，不能也不应该调用 `logs`。
+- `sandbox run-bg` 不加 `--wait` 时，HTTP 请求本身会快速返回 `{execution_id, sandbox_id}`；命令若超时会以非零退出码结束，需后续通过 `logs` 拿 `exit_code`。
+- `sandbox run-bg --wait` 模式下，`--timeout` **同时**充当服务端命令执行超时和客户端轮询 deadline（默认 300s）；轮询间隔固定 5 秒；初始 `/run-background` POST 有独立的 60s HTTP timeout。
+- 后台命令可跨 tool call 轮次查询：保存 `sandbox_id` 和 `execution_id`，后续轮次通过 `sandbox status` / `sandbox logs` 获取结果。